# AdCloud · 广告主控制台

React + TypeScript + Vite，独立 AdCloud 品牌的广告主网站。前后端发布与测试全部通过 Gitea Actions 执行。

## 页面和 URL

| 页面                    | URL                                                                           |
| ----------------------- | ----------------------------------------------------------------------------- |
| Landing / 登录 / 注册   | `/`、`/login`、`/register`                                                    |
| 工作台                  | `/workbench`                                                                  |
| 全部主账户 / 指定主账户 | `/account-manage`、`/account-manage/:accountId`                               |
| 新建 / 编辑主账户       | `/account-manage/new`、`/account-manage/:accountId/edit`                      |
| 投放子账户              | `/account-manage/:accountId/promotion-manage/:promotionId`                    |
| 新建 / 编辑子账户       | 主账户路径下的 `/promotion-manage/new`、`/promotion-manage/:promotionId/edit` |
| 新建项目                | 子账户路径下的 `/create-project/:step`                                        |
| 编辑项目                | 子账户路径下的 `/projects/:projectId/edit/:step`                              |

`step` 依次为 `goal`、`product`、`audience`、`budget`、`tracking`、`name`，对应营销目标、推广产品、受众、排期预算、监测链接和项目名称。步骤切换产生浏览器历史记录。已保存项目可复制链接、在新标签页打开、刷新恢复和前进后退；未保存的表单编辑仍是临时状态。

`accountId` 是主账户，`promotionId` 是进入投放工作区的子账户 ID，`projectId` 是项目 ID。`promotion-manage` 是功能名，不是额外的数据实体。URL 层级会与后端归属校验相互验证；非法或无权限的 ID 不会回退到其他账户。未登录访问受保护页面会跳转登录，登录后回到原链接。

注册创建独立广告主用户、主账户及默认子账户；所有账户和已保存项目进入后端关系数据库。终端流量用户的 `identity` 表和广告主身份完全分离。

## Gitea CI/CD

- `.gitea/workflows/deploy.yml`：main 推送或手动触发，复用 `ubuntu-latest` runner（现有 Docker 宿主机）。
- Docker 多阶段构建：Node 22 执行 `npm ci`、TypeScript 检查和 Vite 打包；Nginx 提供页面与同源广告主 API 代理。
- Playwright 测试镜像运行在 runner，访问真实部署的 `BASE_URL`。覆盖注册登录、主子账户 URL、六步项目创建、修改、深链接刷新、前进后退、重新登录返回、错误账户和移动端工作台。
- 独立容器 `adcloud-advertiser-console`、并发组与默认端口 `18081`，后端继续使用 `18080`。
- 先在候选容器网络内完成浏览器验收（仅回环监听 5173，未发布宿主机端口），再替换前端；公开端口或浏览器验证失败恢复上一个前端容器。
- 同仓库 PR 只构建；外部 fork PR 不在拥有 Docker socket 的 runner 执行。

仓库变量：`ADCLOUD_ADVERTISER_PORT`（18081）、`ADCLOUD_ADVERTISER_API_UPSTREAM`（`http://host.docker.internal:18080`）、`ADCLOUD_ADVERTISER_PUBLIC_URL`（`http://47.76.92.159:18081`）。拉取源码优先使用现有 `GITEA_TOKEN` secret，否则使用 Actions 自动提供的短期仓库 token。无需把密码写入仓库。

先部署后端的 `/v1/advertiser` 接口，并在其 CORS 中允许前端公网 origin。测试 HTTP 环境使用 `COOKIE_SECURE=false`；生产需要 HTTPS 和 `COOKIE_SECURE=true`。Nginx 支持所有前端深链接 fallback，API 路径单独代理，API 404 不会伪装成 HTML。

CI 浏览器验证使用带 `CI` 标记的测试广告主和项目，保留在测试环境，不能视为真实客户数据。依赖数据库的后端集成阶段不允许跳过测试。

## 开发配置

Node.js 22.12+。默认 `VITE_API_BASE_URL` 留空，Vite 开发代理指向 `127.0.0.1:8000`；部署使用 Nginx 同源代理。不要在 `VITE_` 配置放密钥。依据当前工作约定，测试与发布验证在 Gitea runner 和部署服务器完成，而非本机。

## 首版边界

项目只有“草稿”和“已暂停”，没有实际投放、资金消耗或结算；报表展示空态。尚无成员邀请与细分角色、邮箱验证、密码找回、资质审核、素材和投放引擎。监测链接当前只保存配置，不主动请求外部地址。