R524809
85 lines
7.2 KiB
Markdown
85 lines
7.2 KiB
Markdown
# 多 AI 开发协作约定（强制）
|
||
|
||
> 生效日期：2026-09-03。适用于本仓库所有人工与 AI 开发者。除非仓库维护者明确批准并同时更新本文档，任何实现不得违反本约定。
|
||
|
||
## 1. 目的与优先级
|
||
|
||
本约定使前端、服务端、Worker 和浏览器扩展能够独立推进，并以小范围、可验证的改动持续集成。
|
||
|
||
发生冲突时，按以下顺序处理：
|
||
|
||
1. 本文档的协作、所有权与变更流程约束。
|
||
2. `docs/project/HANDOFF.md` 的产品边界与云端架构底线。
|
||
3. `docs/api/` 的 HTTP API 契约，特别是 `docs/api/conventions.md`。
|
||
4. `docs/architecture/` 的数据模型、SQL、RLS、Outbox 与部署约束。
|
||
5. 模块需求文档。
|
||
6. 当前代码的既有行为。
|
||
|
||
较低优先级内容与较高优先级冲突时，不得通过代码“兼容”或自行猜测解决；必须先修订上游文档并取得维护者确认。
|
||
|
||
## 2. 领域所有权
|
||
|
||
| 领域 | 负责人 | 可修改范围 | 交付责任 |
|
||
|---|---|---|---|
|
||
| 服务端与数据 | 后端 AI | `apps/api/`、`apps/worker/`、`packages/database/`、`packages/contracts/`、服务端相关文档 | 迁移、RLS、认证、API、异步任务、平台适配和集成测试 |
|
||
| 前端体验 | 前端 AI | `apps/web/`、前端相关文档 | 页面、组件、路由、交互、可访问性、加载/空/错误状态与前端测试 |
|
||
| 浏览器扩展 | 后端 AI（采集 API 稳定前只维护骨架） | `apps/extension/` | 扩展认证、采集、净化上传与 API 集成 |
|
||
| 共享契约 | 后端 AI维护，前端 AI共同评审 | `packages/contracts/`、`docs/api/` | 对外类型、DTO、枚举、错误码与接口样例保持一致 |
|
||
| 最终集成 | 仓库维护者指定；默认后端 AI | 根配置、锁文件、跨应用变更 | 合并顺序、契约兼容性与端到端验收 |
|
||
|
||
任何人修改非自己负责的领域前，必须在任务说明中写明原因、影响文件和接口影响；未经明确授权不得改动该领域的业务实现。
|
||
|
||
## 3. API 与共享类型约束
|
||
|
||
1. `docs/api/` 是唯一的 HTTP API 行为来源；实现前必须先有对应契约，或在同一个经过评审的变更中先更新契约。
|
||
2. 接口路径、字段名、必填性、枚举、金额字符串格式、分页、错误格式、`Idempotency-Key`、`If-Match` 和异步 `operation` 规则不得由客户端自行推断或扩展。
|
||
3. 已冻结接口的破坏性变更必须先由维护者批准，并同时更新契约、`@atlas/contracts`、服务端测试和调用端。
|
||
4. 稳定的请求、响应、枚举和错误类型必须放入 `@atlas/contracts`；`apps/web` 不得长期维护其副本。允许在后端 API 尚未交付时使用明确标注为临时的 mock/adapter，接入接口时必须删除或替换。
|
||
5. 前端遇到契约缺口时，提交具体问题（页面/用户动作/所需字段/建议响应），不得私自新增后端字段或改变服务端语义。
|
||
|
||
## 4. 数据与安全硬约束
|
||
|
||
1. PostgreSQL 是业务事实来源。所有业务数据必须有 `workspace_id`，或能经强制外键安全追溯到工作空间；查询必须在事务中设置 `SET LOCAL app.workspace_id`。
|
||
2. 数据库约束、RLS 与迁移是安全边界；不得只依赖 API 服务层校验。迁移必须可重复执行、可在全新本地环境验证。
|
||
3. 关键可重试写入必须实现幂等；触发异步工作的事务必须同时写入 Transactional Outbox。Redis/BullMQ 不得成为业务事实的唯一来源，Worker 必须幂等。
|
||
4. access token 不得写入浏览器持久化存储；Cookie、API Key、预签名 URL 等秘密不得写进日志、Outbox 载荷、fixture 或提交进仓库。**维护者已于 2026-09-07 批准唯一例外：**为自托管采集插件的网页登录态同步，Atlas Web 可在本站 `localStorage["atlas.extension.web-access"]` 写入当前短期 access token，扩展仅可从 Atlas Web 标签读取并保存到 extension storage；不得读取/写入 refresh Cookie，生产 host permission 必须限制为 Atlas Web 域。完整取舍见 [`extension-login-alternatives.md`](./extension-login-alternatives.md)。
|
||
5. 不得从旧 `ozon-seller-kit` 复制 SQLite、多店铺无隔离、无鉴权 API 或旧商品编辑实现。复用逻辑前必须适配多租户与云端边界。
|
||
|
||
## 5. 工作方式与集成规则
|
||
|
||
1. 一个任务只完成一个可验收的垂直能力，明确列出：目标、负责人、允许改动范围、依赖的 API/数据表、验收标准和是否修改契约。
|
||
2. 每个开发者使用独立分支或 worktree；提交应小而单一。不要在无关任务中格式化全仓、升级依赖、修改根脚本或重新生成锁文件。
|
||
3. 在同一时间，只有最终集成负责人可以合并跨领域改动、根配置、`pnpm-lock.yaml` 和共享契约的冲突解决。
|
||
4. 合并前至少运行受影响工作区的 typecheck 与 build；新增或修改 API 时必须增加服务端测试，并在任务结果中提供请求/响应示例或测试覆盖说明。
|
||
5. 未完成的 P0/P1 设计事项以 `docs/reviews/implementation-readiness-open-items.md` 为准。任务触及其中事项时，必须先关闭该事项或获得维护者明确的范围豁免。
|
||
|
||
## 6. 首个建议任务：账户与工作空间基础闭环（M0）
|
||
|
||
**目标：** 交付第一个真实的、可由前端接入的认证闭环：注册、登录、刷新会话、登出、读取当前用户与个人工作空间。
|
||
|
||
### 后端 AI 负责
|
||
|
||
- 建立可重复执行的基础迁移执行器，并落地认证所需的基础表、数据库角色/RLS 约束与本地验证。
|
||
- 按 `docs/api/auth.md` 实现认证模块、密码处理、refresh cookie、access token、请求工作空间上下文及统一错误响应。
|
||
- 注册成功时，在同一事务创建用户、个人工作空间和唯一 `owner` 成员。
|
||
- 将稳定 DTO、枚举和错误类型加入 `@atlas/contracts`，并添加 API/数据库集成测试。
|
||
- 不实现门店、素材、采集、商品、发布或 Worker 业务；这些不属于 M0 范围。
|
||
|
||
### 前端 AI 负责
|
||
|
||
- 保持现有 `/login` 和 `/register` 的视觉及表单体验，按 `docs/api/auth.md` 接入真实接口。
|
||
- 使用共享契约替换本地认证类型；完成应用启动时的会话恢复、主布局路由守卫、401 后的受控跳转和加载/错误状态。
|
||
- 不修改认证接口的字段、错误语义、Cookie 策略或 token 存储边界；需要变化时按第 3 节提出契约问题。
|
||
|
||
### M0 验收标准
|
||
|
||
1. 新用户可注册、自动拥有个人工作空间，并能登录后读取当前身份。
|
||
2. access token 仅存于内存；刷新页面可通过 HttpOnly refresh cookie 恢复会话；登出后刷新 cookie 失效。
|
||
3. 未认证请求与已过期会话返回契约定义的统一错误，前端不会陷入重试循环。
|
||
4. 工作空间隔离通过数据库集成测试验证；跨工作空间读取或写入被拒绝。
|
||
5. API、Web、共享契约的 typecheck 和 production build 均通过。
|
||
|
||
## 7. M0 完成后的顺序
|
||
|
||
M0 合并后，按以下顺序建立纵向闭环：门店与平台上下文 → 素材上传与媒体处理 → 采集箱 → 商品编辑与 SKU → 定价 → 首次发布与在线商品同步。不得为了前端页面便利跳过前置的认证、工作空间隔离或数据边界。
|