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	部分已实现	鉴权、全局上下文、响应、分页、错误、并发与异步任务。
auth.md	已实现	邮箱注册、登录、刷新会话、退出、当前用户。
stores-and-platforms.md	部分已实现	平台目录、页头上下文、店铺授权、门店 CRUD、默认店铺、操作查询与仓库读取；平台实际验证与同步 Worker 待实现。
watermarks-and-assets.md	部分已实现	水印模板、字体、店铺推荐水印；素材直传与短时访问待实现。
pricing.md	已设计	汇率、物流价卡、即时试算、定价方案、报价快照衔接。
collection-and-extension.md	已设计	插件授权、采集写入、采集箱查询、素材转存与状态。
product-editor-and-publishing.md	已设计	商品编辑、SKU、类目、属性、AI、媒体选择、定价确认与部分 SKU 首次上架。
online-listings.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 或后台任务维护。

相关需求：账户、门店与水印、基础数据模型、数据库安全。