docs: 更新初始化交接文档

This commit is contained in:
R524809
2026-09-02 17:56:42 +08:00
parent 1a2caba2b3
commit 09e5207c83
3 changed files with 31 additions and 19 deletions
+10 -8
View File
@@ -6,7 +6,9 @@
这是一个全新的云端产品,不是 `ozon-seller-kit` 的本地版重构。目标用户可拥有多个门店,每个门店只能绑定一个平台;平台自身可支持多个市场、国家、语言和币种。因此语言、币种、类目和发布规则不能写死为 Ozon 或中文/俄文。
当前项目还没有业务代码、数据库、部署或依赖。不要从旧项目复制 SQLite 模型、无鉴权 API、旧 `/trial/:id` 或商品编辑页组件。可选择性复用已经验证过的纯计价公式、采集扩展思路和 AI 任务经验,但必须先适配多租户和云端边界。
当前已完成 pnpm monorepo 初始化:包含 Web、NestJS API、BullMQ Worker、WXT 浏览器扩展、共享 API 契约、数据库包、本地基础设施 Compose 与依赖锁文件。API 仅实现健康检查,Web/Worker/扩展仅有启动骨架;尚未实现业务模块、迁移执行器、数据库 schema、鉴权或实际部署。不要从旧项目复制 SQLite 模型、无鉴权 API、旧 `/trial/:id` 或商品编辑页组件。可选择性复用已经验证过的纯计价公式、采集扩展思路和 AI 任务经验,但必须先适配多租户和云端边界。
当前运行时基线:Node 24.20.0、pnpm 11.25.0、PostgreSQL 18.6、Redis 7.4.11、MinIO `RELEASE.2025-09-07T16-13-09Z`;Web 默认端口为 `8100`,API 默认端口为 `8200`,Worker 无 HTTP 端口。完整目录、依赖边界与版本表见 [`architecture/project-structure.md`](../architecture/project-structure.md) 和 [`architecture/technology-and-deployment.md`](../architecture/technology-and-deployment.md)。
## 2. 已确认产品决策
@@ -54,7 +56,7 @@ User → Workspace → Membership / Role
## 5. 已冻结的第一阶段 API 契约
第一阶段 HTTP API 的接口范围已讨论完成,当前状态为**设计冻结、尚未实现**。后续编码以 [`docs/api/`](../api/README.md) 为唯一 HTTP 契约来源;旧 [`product/api.md`](../product/api.md) 仅作历史背景,不能作为实现依据。
第一阶段 HTTP API 的接口范围已讨论完成,当前状态为**设计冻结、业务接口尚未实现**。仓库已有 NestJS API 启动骨架及 `GET /health`,它不构成任何已实现的业务契约。后续编码以 [`docs/api/`](../api/README.md) 为唯一 HTTP 契约来源;旧 [`product/api.md`](../product/api.md) 仅作历史背景,不能作为实现依据。
- 覆盖账户认证、平台/门店、水印与素材、定价、浏览器采集/采集箱、商品编辑/首次发布、在线商品读取与同步。
- 所有接口遵循统一鉴权、工作空间隔离、页头平台上下文、金额字符串、错误格式、`Idempotency-Key`、`If-Match` 和异步 `operation` 约定。
@@ -65,13 +67,13 @@ User → Workspace → Membership / Role
## 6. 下一步建议
下一步进入项目初始化与实现准备,而不是继续扩大 API 范围:
项目初始化已完成;下一步进入实现准备,而不是继续扩大 API 范围:
1. 创建 NestJS 后端、React 前端、迁移工具、Redis/BullMQ 和本地 Docker Compose 骨架。
2. 以 `001_foundation.sql`、`002_product-domain.sql` 建立可重复执行的迁移,并按数据库角色/RLS 约束验证本地环境。
3. 在开始商品编辑/在线同步模块前,先关闭评审文档中的 P1 事项:同商品归属约束、未映射属性持久化、乐观锁 Repository 规则、平台能力 Schema;并确认在线商品归档策略和 Client ID 编辑边界。
4. 优先实现账户、平台上下文、门店、素材上传、操作任务、幂等/Outbox Dispatcher 的纵向最小闭环,再接入采集箱和商品编辑。
5. 为浏览器采集准备真实多 SKU 解析测试集,并继续限定 Ozon Seller 网页观察实验的字段口径,见 [`requirements/collector-browser-extension.md`](../requirements/collector-browser-extension.md)。
1. 以 `001_foundation.sql`、`002_product-domain.sql` 建立可重复执行的迁移执行器,并按数据库角色/RLS 约束验证本地环境。
2. 在 API 建立配置校验、认证、工作空间上下文和事务包装器;任何工作空间查询前固定 `SET LOCAL app.workspace_id`。
3. 建立 `operations`、幂等请求和 Outbox Dispatcher 的第一个集成测试闭环。
4. 在开始商品编辑/在线同步模块前,关闭评审文档中的 P1 事项:同商品归属约束、未映射属性持久化、乐观锁 Repository 规则、平台能力 Schema;并确认在线商品归档策略和 Client ID 编辑边界。
5. 优先实现账户、平台上下文、门店、素材上传的纵向最小闭环,再接入采集箱和商品编辑;浏览器扩展仅在采集 API 稳定后实现实际解析器。
## 7. 文档导航