atlas-seller-kit/docs/project/development-collaboration-contract.md

多 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 或提交进仓库。
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 → 定价 → 首次发布与在线商品同步。不得为了前端页面便利跳过前置的认证、工作空间隔离或数据边界。