feat: 方案设计、数据库和接口设计基本完成

2026-09-02 14:47:18 +08:00
parent a3fe066a5f
commit 04c94e75db
30 changed files with 3305 additions and 122 deletions
@@ -0,0 +1,37 @@
+# Atlas HTTP API 设计
+
+> 状态：第一批可评审契约。本文档描述预期的 NestJS HTTP API，不代表接口已经实现。接口统一以前缀 `/api` 提供，JSON 字段使用 `snake_case`，时间使用 ISO 8601 UTC 字符串，ID 使用 UUID。
+
+## 1. 文档路线
+
+| 文档 | 状态 | 范围 |
+|---|---|---|
+| [`conventions.md`](./conventions.md) | 已设计 | 鉴权、全局上下文、响应、分页、错误、并发与异步任务。 |
+| [`auth.md`](./auth.md) | 已设计 | 邮箱注册、登录、刷新会话、退出、当前用户。 |
+| [`stores-and-platforms.md`](./stores-and-platforms.md) | 已设计 | 平台目录、页头上下文、店铺授权、凭据校验、仓库、默认店铺。 |
+| [`watermarks-and-assets.md`](./watermarks-and-assets.md) | 已设计 | 素材直传、短时访问、水印模板、字体、店铺推荐水印。 |
+| [`pricing.md`](./pricing.md) | 已设计 | 汇率、物流价卡、即时试算、定价方案、报价快照衔接。 |
+| [`collection-and-extension.md`](./collection-and-extension.md) | 已设计 | 插件授权、采集写入、采集箱查询、素材转存与状态。 |
+| [`product-editor-and-publishing.md`](./product-editor-and-publishing.md) | 已设计 | 商品编辑、SKU、类目、属性、AI、媒体选择、定价确认与部分 SKU 首次上架。 |
+| [`online-listings.md`](./online-listings.md) | 初版已设计 | 店铺独有的在线商品镜像、读取与异步同步；编辑/认领仍待讨论。 |
+
+旧的 [`../product/api.md`](../product/api.md) 是商品域的早期草案：已确认的产品规则可作为背景，但不能当作最终 HTTP 契约。后续商品模块会迁入本目录并替换其中的路径和细节。
+
+## 2. 首期的身份与上下文边界
+
+- 登录身份决定用户和当前工作空间；客户端**不能**传 `workspace_id` 作为数据归属或隔离条件。
+- 首期注册原子创建一个个人工作空间与 `owner` 成员关系。API 响应仍会返回 `workspace`，为未来协作预留。
+- 平台是页头全局工作上下文，而非租户边界。平台范围接口使用 `X-Atlas-Platform-Id`，或在文档明确标注时使用 `platform_id` 查询参数；服务端验证该平台存在且已启用。
+- “默认店铺”由服务端按 `workspace + platform` 读取。不能相信客户端宣称某个店铺是默认店铺；需要指定店铺的写操作使用路径中的 `store_id` 并验证它属于当前工作空间和平台。
+- 采集箱不带平台/店铺上下文；在线商品永远是平台 + 门店独有资源。这两个模块将在后续文档中分别约束。
+
+## 3. 未纳入第一批的事项
+
+- 手机号、短信登录、邮箱验证、忘记密码、第三方登录、MFA 与设备管理；
+- 团队成员、工作空间切换和角色管理 UI；
+- Cookie 授权/保存；
+- 平台、货币、字体、物流商、类目、佣金和汇率的后台维护接口。
+
+这些事项不会由首期客户端私自调用管理接口；运营数据由受控 seed、migration 或后台任务维护。
+
+相关需求：[账户、门店与水印](../requirements/account-store-watermark.md)、[基础数据模型](../architecture/foundation-data-model.md)、[数据库安全](../architecture/database-security.md)。