atlas-seller-kit/docs/api/README.md

# Atlas HTTP API 设计

> 状态：第一批契约已冻结。认证、平台目录/上下文、门店基础管理和操作查询已实现；其余模块仍是设计契约。接口统一以前缀 `/api` 提供，JSON 字段使用 `snake_case`，时间使用 ISO 8601 UTC 字符串，ID 使用 UUID。

API 启动后会在 `/api-docs` 提供 Swagger UI，并在其 OpenAPI 文档中标记已实现的接口。Swagger 是运行时参考，不替代本目录的冻结契约。

运行状态端点不使用 `/api` 前缀：`GET /health` 只表明进程存活，`GET /ready` 会校验应用数据库连接，失败时返回 `503`。生产环境由环境变量控制 API 端口、CORS 来源、日志级别、请求体上限、认证限流及可信反向代理列表；缺少或格式错误的必需安全配置会阻止 API 启动。

## 1. 文档路线

| 文档 | 状态 | 范围 |
|---|---|---|
| [`conventions.md`](./conventions.md) | 部分已实现 | 鉴权、全局上下文、响应、分页、错误、并发与异步任务。 |
| [`auth.md`](./auth.md) | 已实现 | 邮箱注册、登录、刷新会话、退出、当前用户。 |
| [`stores-and-platforms.md`](./stores-and-platforms.md) | 部分已实现 | 平台目录、页头上下文、店铺授权、门店 CRUD、默认店铺、操作查询与仓库读取；平台实际验证与同步 Worker 待实现。 |
| [`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) | M3.1 部分已实现 | 编辑上下文、只读快照和产品/平台文案/SKU 的原子草稿保存；类目/属性、媒体、定价、AI 与首次上架仍待实现。 |
| [`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)。