R1 商品目录交付说明

提供方：成员 1（R1 商品目录）

可使用成员：成员 2（设计清单）、成员 3（订单）、成员 4（设计与生产）

分支：feat/r1-catalog

R1 商品目录已完成，可以对外提供商品数据。商品页面现在从后端接口读取商品信息，不再以写死在前端的商品数据作为主数据源。本说明中的验证结果用于证明商品目录已经真实可用；接口说明用于方便其他成员接入这份目录数据。

已完成内容

完成项	结果
后端商品数据	已建立商品分类及 5 个在售商品的本机数据。
商品接口	已提供商品列表、单个商品详情和分类列表接口。
前端商品页面	首页、商品列表、商品详情、立即定制页均已接入商品接口。
本机联调环境	Docker 中的后端、数据库、Redis 已启动；微信开发者工具可正常运行前端。

这次验证不只是确认接口能访问，而是确认后端数据变化会传到前端页面，证明前端展示的确实是后端商品数据。

验证步骤	验证结果
读取商品初始值	`notebook-small` 的价格为 12 元，划线原价为 18 元。
修改后端数据库	将该商品测试价格改为 19 元，测试划线原价改为 29 元。
重新编译小程序	微信开发者工具重新编译后，商品卡片和详情页同步显示 19 元、29 元。
验证结论	前端展示随数据库和接口返回同步改变，前后端商品数据通路正常。

结论： R1 商品页面读取的是后端真实商品数据；后端数据变化能够传递到前端页面。因此以下接口已完成实际联调验证，可作为其他路线的商品数据来源。

约定	说明
稳定商品 ID	跨模块使用 `productId` 关联商品，例如 `notebook-small`、`coaster`、`penbox`。不要使用数组下标或商品名称作为关联键。
公开查询	商品与分类查询不依赖登录态；前端调用时使用 `auth: false`。
价格来源	`price` 是服务端权威价格。前端可展示价格，订单金额必须由 R3 服务端重新查询并计算。
在售限制	商品列表与详情只返回 `ON_SALE` 商品；不存在或下架商品的详情返回 `404`。

所有接口统一返回：{ code: 0, message: 'ok', data }。实际业务数据位于 data 中。

接口	用途	参数	验证状态
`GET /api/categories`	获取按 `sort` 排序的分类列表	无	已验证
`GET /api/products`	获取在售商品分页列表	`page`、`pageSize`、`categoryId`、`keyword` 均可选	已验证
`GET /api/products/:id`	获取一个在售商品的完整详情	`id` 为稳定商品 ID	已验证

字段	含义
`id`、`name`、`categoryId`、`status`、`sort`	商品标识、名称、分类、在售状态和稳定排序。
`price`、`originalPrice`、`leadTime`	商品价格、划线原价和制作周期。
`subtitle`、`description`、`story`、`scene`	商品卖点、介绍、设计理念和使用场景。
`images`、`iconImg`、`tone`	商品图片、图标与详情页视觉主题色。
`tags`、`specs`、`mask`	商品标签、规格参数和定制画布信息。

成员	可以使用的商品数据
成员 2：设计清单	保存 `productId`、`productName`、`price`、`count`；设计数据中原样保留 `mask` 和 `tone`。
成员 3：订单	客户端只传 `productId` 与 `quantity`；订单服务端必须重新读取 `price` 计算金额。
成员 4：设计与生产	使用 `mask` 确定画布尺寸，使用 `tone` 作为主题色；生产任务保存商品 ID 与设计快照。

以上地址只适用于本机模拟器联调。真机和生产环境需要替换为已配置合法域名的 HTTPS 地址。