joey5628/atlas-seller-kit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add mandatory AI collaboration contract

Browse Source
This commit is contained in:
R524809
2026-09-03 09:19:29 +08:00
parent 403f6cfa27
commit 195b6d25e9
3 changed files with 105 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/README.md
+20 -19
View File
@@ -6,7 +6,7 @@
| 类型 | 位置 | 内容 |
|---|---|---|
| 项目 | [`project/`](./project/) | 产品定位、交接与已确认的长期约束 |
| 项目 | [`project/`](./project/) | 产品定位、交接、协作约定与已确认的长期约束 |
| 产品需求 | [`requirements/`](./requirements/) | 页面、流程、字段和待确认事项 |
| 基础架构 | [`architecture/`](./architecture/) | 多租户、平台、门店、水印、物流和定价的数据设计及 DDL |
| 商品领域设计 | [`product/`](./product/) | 已有的多 SKU 商品编辑页、领域模型与 API 草案 |
@@ -18,21 +18,22 @@
## 当前阅读顺序
1. [`project/HANDOFF.md`](./project/HANDOFF.md)：项目边界和已经确认的商品规则。
2. [`requirements/collector-browser-extension.md`](./requirements/collector-browser-extension.md)：来源商品采集、采集箱、多 SKU、插件认证和 Ozon Seller 网页观察实验。
3. [`requirements/collection-box-and-online-products.md`](./requirements/collection-box-and-online-products.md)：采集箱、上架后编辑限制、按 SKU 展示的在线商品和 Ozon 异步同步需求。
4. [`requirements/account-store-watermark.md`](./requirements/account-store-watermark.md)：账户、门店和水印需求。
5. [`requirements/pricing-tool.md`](./requirements/pricing-tool.md)：独立试算、SKU 定价方案和物流规则需求。
6. [`requirements/cel-ozon-rfbs-rates-review.md`](./requirements/cel-ozon-rfbs-rates-review.md)：从 CEL Ozon-rFBS 资费表提取的待审核规则。
7. [`architecture/foundation-data-model.md`](./architecture/foundation-data-model.md)：基础模块数据模型和 PostgreSQL DDL。
8. [`architecture/exchange-rates.md`](./architecture/exchange-rates.md)：系统汇率、CBR、免费备用接口、更新任务和报价快照规则。
9. [`architecture/product-domain-data-model.md`](./architecture/product-domain-data-model.md)：采集箱、商品编辑、发布任务和在线商品镜像的数据库设计与 SQL。
10. [`architecture/technology-and-deployment.md`](./architecture/technology-and-deployment.md)：已确认的 NestJS、PostgreSQL、Redis/BullMQ、MinIO、七牛 Kodo 与部署策略。
11. [`architecture/database-security.md`](./architecture/database-security.md)：迁移/应用数据库角色、RLS 强制策略与部署职责。
12. [`architecture/transactional-outbox-and-idempotency.md`](./architecture/transactional-outbox-and-idempotency.md)：关键写请求去重、事务 Outbox、BullMQ 投递与验收规则。
13. [`guides/object-storage-object-key.md`](./guides/object-storage-object-key.md)：对象存储、`object_key`、来源 URL 与预签名 URL 的使用边界。
14. [`guides/minio-local-deployment.md`](./guides/minio-local-deployment.md)：MinIO 简介、本地 Docker 部署与应用侧使用方法。
15. [`guides/postgresql-local-development.md`](./guides/postgresql-local-development.md)：原生 PostgreSQL / Docker Compose 本地数据库、角色、迁移与建表。
16. [`api/README.md`](./api/README.md)：HTTP API 统一约定及第一批账户、门店、水印接口。
17. [`reviews/implementation-readiness-open-items.md`](./reviews/implementation-readiness-open-items.md)：实现前必须闭环的数据库/API 事项与已确认约束。
18. 后续按模块补全定价、采集、商品编辑、发布和在线商品接口。
1. [`project/development-collaboration-contract.md`](./project/development-collaboration-contract.md)：**所有人工与 AI 开发者必须遵守的协作、领域所有权、API 与数据约束。**
2. [`project/HANDOFF.md`](./project/HANDOFF.md)：项目边界和已经确认的商品规则。
3. [`requirements/collector-browser-extension.md`](./requirements/collector-browser-extension.md)：来源商品采集、采集箱、多 SKU、插件认证和 Ozon Seller 网页观察实验。
4. [`requirements/collection-box-and-online-products.md`](./requirements/collection-box-and-online-products.md)：采集箱、上架后编辑限制、按 SKU 展示的在线商品和 Ozon 异步同步需求。
5. [`requirements/account-store-watermark.md`](./requirements/account-store-watermark.md)：账户、门店和水印需求。
6. [`requirements/pricing-tool.md`](./requirements/pricing-tool.md)：独立试算、SKU 定价方案和物流规则需求。
7. [`requirements/cel-ozon-rfbs-rates-review.md`](./requirements/cel-ozon-rfbs-rates-review.md)：从 CEL Ozon-rFBS 资费表提取的待审核规则。
8. [`architecture/foundation-data-model.md`](./architecture/foundation-data-model.md)：基础模块数据模型和 PostgreSQL DDL。
9. [`architecture/exchange-rates.md`](./architecture/exchange-rates.md)：系统汇率、CBR、免费备用接口、更新任务和报价快照规则。
10. [`architecture/product-domain-data-model.md`](./architecture/product-domain-data-model.md)：采集箱、商品编辑、发布任务和在线商品镜像的数据库设计与 SQL。
11. [`architecture/technology-and-deployment.md`](./architecture/technology-and-deployment.md)：已确认的 NestJS、PostgreSQL、Redis/BullMQ、MinIO、七牛 Kodo 与部署策略。
12. [`architecture/database-security.md`](./architecture/database-security.md)：迁移/应用数据库角色、RLS 强制策略与部署职责。
13. [`architecture/transactional-outbox-and-idempotency.md`](./architecture/transactional-outbox-and-idempotency.md)：关键写请求去重、事务 Outbox、BullMQ 投递与验收规则。
14. [`guides/object-storage-object-key.md`](./guides/object-storage-object-key.md)：对象存储、`object_key`、来源 URL 与预签名 URL 的使用边界。
15. [`guides/minio-local-deployment.md`](./guides/minio-local-deployment.md)：MinIO 简介、本地 Docker 部署与应用侧使用方法。
16. [`guides/postgresql-local-development.md`](./guides/postgresql-local-development.md)：原生 PostgreSQL / Docker Compose 本地数据库、角色、迁移与建表。
17. [`api/README.md`](./api/README.md)：HTTP API 统一约定及第一批账户、门店、水印接口。
18. [`reviews/implementation-readiness-open-items.md`](./reviews/implementation-readiness-open-items.md)：实现前必须闭环的数据库/API 事项与已确认约束。
19. 后续按模块补全定价、采集、商品编辑、发布和在线商品接口。
docs/project/HANDOFF.md
+1 -1
View File
@@ -1,6 +1,6 @@
# Atlas Seller Kit 交接说明
> 更新：2026-09-02。此文是新 AI 对话、架构讨论与开发工作的首读入口。
> 更新：2026-09-03。此文是新 AI 对话、架构讨论与开发工作的首读入口。开始开发前，必须先阅读并遵守 [`development-collaboration-contract.md`](./development-collaboration-contract.md)。
## 1. 项目定位
docs/project/development-collaboration-contract.md
+84
View File
@@ -0,0 +1,84 @@
# 多 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 → 定价 → 首次发布与在线商品同步。不得为了前端页面便利跳过前置的认证、工作空间隔离或数据边界。