# 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 地址。