feat(catalog): add product catalog APIs

docs/R1商品目录接口验证说明.md

@@ -0,0 +1,90 @@
+# R1 商品目录交付说明
+
+**提供方：成员 1（R1 商品目录）**
+
+**可使用成员：成员 2（设计清单）、成员 3（订单）、成员 4（设计与生产）**
+
+**分支：`feat/r1-catalog`**
+
+R1 商品目录已完成，可以对外提供商品数据。商品页面现在从后端接口读取商品信息，不再以写死在前端的商品数据作为主数据源。本说明中的验证结果用于证明商品目录已经真实可用；接口说明用于方便其他成员接入这份目录数据。
+
+## 已完成内容
+
+| 完成项 | 结果 |
+| --- | --- |
+| 后端商品数据 | 已建立商品分类及 5 个在售商品的本机数据。 |
+| 商品接口 | 已提供商品列表、单个商品详情和分类列表接口。 |
+| 前端商品页面 | 首页、商品列表、商品详情、立即定制页均已接入商品接口。 |
+| 本机联调环境 | Docker 中的后端、数据库、Redis 已启动；微信开发者工具可正常运行前端。 |
+
+## 已完成前后端数据通路验证
+
+这次验证不只是确认接口能访问，而是确认后端数据变化会传到前端页面，证明前端展示的确实是后端商品数据。
+
+| 验证步骤 | 验证结果 |
+| --- | --- |
+| 读取商品初始值 | `notebook-small` 的价格为 12 元，划线原价为 18 元。 |
+| 修改后端数据库 | 将该商品测试价格改为 19 元，测试划线原价改为 29 元。 |
+| 重新编译小程序 | 微信开发者工具重新编译后，商品卡片和详情页同步显示 19 元、29 元。 |
+| 验证结论 | 前端展示随数据库和接口返回同步改变，前后端商品数据通路正常。 |
+
+![image-20260912143719516](C:\Users\24595\AppData\Roaming\Typora\typora-user-images\image-20260912143719516.png)
+
+![image-20260912143750067](C:\Users\24595\AppData\Roaming\Typora\typora-user-images\image-20260912143750067.png)
+
+**结论：** 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` | 商品标签、规格参数和定制画布信息。 |
+
+### 可用商品 ID
+
+| productId | 商品名称 | 对应分类 ID |
+| --- | --- | --- |
+| `notebook-small` | 微雕笔记本（小） | `cat-notebook-small` |
+| `notebook-large` | 微雕笔记本（大） | `cat-notebook-large` |
+| `coaster` | 铜质杯垫 | `cat-coaster` |
+| `penbox` | 竹制笔盒 | `cat-penbox` |
+| `booklamp` | 书本型灯 | `cat-booklamp` |
+
+## 给其他成员的使用说明
+
+| 成员 | 可以使用的商品数据 |
+| --- | --- |
+| 成员 2：设计清单 | 保存 `productId`、`productName`、`price`、`count`；设计数据中原样保留 `mask` 和 `tone`。 |
+| 成员 3：订单 | 客户端只传 `productId` 与 `quantity`；订单服务端必须重新读取 `price` 计算金额。 |
+| 成员 4：设计与生产 | 使用 `mask` 确定画布尺寸，使用 `tone` 作为主题色；生产任务保存商品 ID 与设计快照。 |
+
+## 本机联调地址
+
+- 后端接口：`http://127.0.0.1:3090`
+- Swagger 接口页面：`http://127.0.0.1:3090/docs`
+- 小程序导入目录：`wechat_wc/dist`
+
+以上地址只适用于本机模拟器联调。真机和生产环境需要替换为已配置合法域名的 HTTPS 地址。