Atlas HTTP API 设计

状态：第一批可评审契约。本文档描述预期的 NestJS HTTP API，不代表接口已经实现。接口统一以前缀 /api 提供，JSON 字段使用 snake_case，时间使用 ISO 8601 UTC 字符串，ID 使用 UUID。

1. 文档路线

文档	状态	范围
`conventions.md`	已设计	鉴权、全局上下文、响应、分页、错误、并发与异步任务。
`auth.md`	已设计	邮箱注册、登录、刷新会话、退出、当前用户。
`stores-and-platforms.md`	已设计	平台目录、页头上下文、店铺授权、凭据校验、仓库、默认店铺。
`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 契约。后续商品模块会迁入本目录并替换其中的路径和细节。

登录身份决定用户和当前工作空间；客户端不能传 workspace_id 作为数据归属或隔离条件。
首期注册原子创建一个个人工作空间与 owner 成员关系。API 响应仍会返回 workspace，为未来协作预留。
平台是页头全局工作上下文，而非租户边界。平台范围接口使用 X-Atlas-Platform-Id，或在文档明确标注时使用 platform_id 查询参数；服务端验证该平台存在且已启用。
“默认店铺”由服务端按 workspace + platform 读取。不能相信客户端宣称某个店铺是默认店铺；需要指定店铺的写操作使用路径中的 store_id 并验证它属于当前工作空间和平台。
采集箱不带平台/店铺上下文；在线商品永远是平台 + 门店独有资源。这两个模块将在后续文档中分别约束。

这些事项不会由首期客户端私自调用管理接口；运营数据由受控 seed、migration 或后台任务维护。