Add isolated advertiser authentication, account hierarchy and project APIs

docs/advertiser-console.md

@@ -0,0 +1,28 @@
+# 广告主控制台 API
+
+访客 `identity` 代表产生广告流量的产品终端用户。广告主使用独立 `advertiser_*` 表、密码与会话，不执行 stitch，不依赖 IDENTITY_SECRET。
+
+- `POST /v1/advertiser/register`：email、password（10–128 字符）、name、company；原子创建用户、主账户、默认子账户。
+- `POST /v1/advertiser/login`、`POST /logout`、`GET /me`。
+- `GET/POST /v1/advertiser/accounts`：创建时 parent_id 为空表示主账户，否则必须是本人主账户。
+- `PUT /v1/advertiser/accounts/{id}`：修改 name、company、industry，不允许换归属。
+- `GET/POST /v1/advertiser/accounts/{id}/projects`：只允许子账户创建项目。
+- `PUT /v1/advertiser/accounts/{id}/projects/{project_id}`：校验账户所有权和项目归属。
+
+主账户 → 子账户 → 项目。没有第三层账户。当前每个主子账户只有注册用户本人有权限；成员与角色授权后续实现。
+
+密码使用独立随机盐 + scrypt，会话为随机 256-bit token，数据库仅保存 SHA-256 摘要，24 小时失效，退出立即撤销。浏览器 HttpOnly / SameSite=Lax Cookie；Secure 由 COOKIE_SECURE 控制。写操作复用显式 Origin 校验，生产应仅允许实际控制台来源。登录 / 注册按客户端 IP + 邮箱在数据库中限频（十分钟十次）；生产还应配合入口级全局限频，防止轮换邮箱/IP 绕过。
+
+广告主接口共用 DATABASE_URL 数据库和事务锁，但身份完全独立。即使没有配置访客身份密钥，启动也会初始化数据库；访客接口仍返回 503。新增表采用现有 additive create_all 初始化，不修改已存在的 identity 表结构。
+
+当前不提供邮箱验证、密码找回、成员协作、资质审批、预算扣款或广告投放。项目状态只有草稿 / 已暂停。所有金额表示配置值，不是资金账本。上线前必须补齐业务审核和资金域。
+
+验证：`uv run pytest tests/test_advertiser.py` 覆盖会话、身份隔离、主子层级、跨用户访问、项目修改、日期预算校验、Origin 和限频。
+
+## URL 导航与服务器 CI
+
+新增 `GET /v1/advertiser/accounts/{account_id}/projects/{project_id}`，支持项目详情直达和刷新；校验登录用户、投放子账户和项目归属。项目配置包含推广产品、转化目标和可选监测链接，六个页面步骤共用一个持久化项目。
+
+广告主 API 测试分别在 SQLite 和真实 PostgreSQL 上执行；PostgreSQL 使用每个测试独立的随机 schema，结束后只清理该 schema。CI integration 容器设置 `ADCLOUD_REQUIRE_INTEGRATION=true`，任何跳过的测试都会令集成阶段失败，避免数据库缺失时仍显示成功。
+
+测试环境默认 CORS 增加 `http://47.76.92.159:18081`，用于同 runner 部署的广告主前端。保持既有开发者端来源；生产地址通过 `DEPLOY_CORS_ORIGINS` 覆盖。