# 商品详情内页 — 前端技术方案（C 端 · shop-app）

> **依据：** 《商品详情内页功能需求.md》v1.0、《商品详情内页技术方案.md》v1.4  
> **关联：** 《商城首页前端技术方案》（热销跳转）、《商品分类前端技术方案》（列表跳转）  
> **范围：** 消费者 APP **`shop-app`** 商品详情页、全部评价页；**不** 改后端、**不** 实现购物车 POST / 确认订单 / 店铺主页 / 评价发表。  
> **实现状态：** 页面与 API 封装已落地，待与 `/api/goods/**` 联调。

---

## 1. 技术栈与约定

| 项 | 说明 |
|----|------|
| 框架 | uni-app **Vue 3** + **uview-plus** |
| 请求 | `@/utils/request`；详情/可购为 `data`；评价为 `rows`/`total` |
| 鉴权 | 读接口 **`isToken: false`**；加购/购买前 **`getToken()`** 校验登录 |
| 规格 | **v1 统一规格**：仅 **数量** 选择；`specDisplay` **只读展示** |
| 参考 | `pages/index/index.vue`（价格卡片）、`components/mall/GoodsGrid.vue` |

---

## 2. 页面与路由

| 页面 | 路径 | 入口 |
|------|------|------|
| 商品详情 | `subpackage/goods/detail` | 首页热销、分类列表等带 `goodsId` |
| 全部评价 | `subpackage/goods/reviews` | 详情页「查看全部」 |

**Query：**

| 页面 | 参数 |
|------|------|
| detail | `goodsId`（必填） |
| reviews | `goodsId`（必填） |

**统一跳转：** `goGoodsDetail(goodsId)` — `utils/goodsDetail.js`

---

## 3. 文件清单

| 类型 | 路径 | 说明 |
|------|------|------|
| 详情页 | `shop-app/subpackage/goods/detail.vue` | 主页面（§3.1 结构） |
| 评价页 | `shop-app/subpackage/goods/reviews.vue` | 评价分页列表 |
| 底栏 | `shop-app/components/goods/DetailBottomBar.vue` | 店铺 / 加购 / 购买 |
| 评价卡 | `shop-app/components/goods/ReviewCard.vue` | 单条评价展示 |
| API | `shop-app/api/goods.js` | detail / can-purchase / reviews |
| 映射 | `shop-app/utils/goodsDetail.js` | VO 映射、图片 URL、售后文案 |
| 交易校验 | `shop-app/utils/purchaseAction.js` | 登录 + `/can-purchase` |

---

## 4. 接口封装

**模块：** `shop-app/api/goods.js`

| 方法 | HTTP | 路径 | 响应 |
|------|------|------|------|
| `getGoodsDetail(goodsId)` | GET | `/api/goods/{goodsId}` | `data: GoodsDetailAppVO` |
| `getGoodsCanPurchase(goodsId)` | GET | `/api/goods/{goodsId}/can-purchase` | `data: { allowed, reason }` |
| `getGoodsReviews(goodsId, params)` | GET | `/api/goods/{goodsId}/reviews` | `rows`, `total` |

**详情核心字段（前端使用）：**

| 字段 | UI 区块 |
|------|---------|
| pics[] | 轮播（主图+副图，URL 经 `resolveFileUrl`） |
| salePrice / goodsName / goodsBrief | 价格区 |
| stock / salesCount / categoryPath | 元信息 |
| goodsStatus / purchase | 状态条、底栏是否可点 |
| attributes / specDisplay | 商品参数 / 规格信息（只读） |
| logistics | 物流说明（有值才展示） |
| services | 服务说明 |
| detailContent | 图文详情 `rich-text` |
| shop | 进店区 |
| afterSalePhone | 售后服务文案 |

---

## 5. 详情页结构（自上而下）

```text
商品详情 detail.vue
├── 图片轮播 swiper（点击 previewImage）
├── 状态提示条（下架 / 不可购 / 库存不足等）
├── 价格与名称、简述、分类路径、库存、销量
├── 数量（点击弹出 u-popup + u-number-box）
├── 商品参数 attributes
├── 规格信息 specDisplay（只读，v1）
├── 物流说明 logistics（有字段才显示）
├── 服务说明 services
├── 评价摘要（GET reviews pageSize=2）+ 查看全部
├── 售后服务（固定模板 + 客服电话）
├── 图文详情 rich-text
├── 店铺入口（进店）
└── 固定底栏 DetailBottomBar
```

---

## 6. 交互与业务规则（前端）

| 规则 | 实现 |
|------|------|
| GD4 轮播 | `pics` 数组 swiper |
| GD10 不可购 | `purchase.allowed`、`goodsStatus`、库存 → `canOperate` 控制底栏 |
| 底栏置灰 | `:disabled="!canOperate"` |
| 加购 / 购买 | 先登录 → 可选数量弹层 → `getCanPurchase` → Toast 待建设模块 |
| 立即购买 | 打开数量弹层后确认 → 同上 |
| 进店 | Toast「店铺主页开发中」 |
| 评价 2 条 | `pageSize=2`；无数据「暂无评价」 |
| 全部评价 | `navigateTo` reviews 页，`pageSize=10` 上拉加载 |
| v1 统一规格 | 无 SKU 矩阵；仅数量 1～stock |

**可购校验顺序（后端 Facade，前端点击前重调）：**

商品存在 → 出售中 → 库存>0 → 店铺开业 → 分类可见

---

## 7. 上游入口改造

| 来源 | 改动 |
|------|------|
| `pages/index/index.vue` | 热销卡片 `goGoodsDetail` |
| `subpackage/category/level1.vue` | 列表 `@goods-click` |
| `subpackage/category/goods-list.vue` | 同上 |
| `GoodsListBlock.vue` | 继续 `emit('goods-click', item)` |

---

## 8. 联调检查清单

| # | 项 |
|---|-----|
| 1 | `GET /api/goods/{id}` 返回 pics 至少 1 张 |
| 2 | 非出售中商品详情 200 但底栏不可点、有提示文案 |
| 3 | `purchase.allowed=false` 时展示 `reason` |
| 4 | 点击加购未登录提示「请先登录」 |
| 5 | 登录后加购调 `/can-purchase` 失败展示后端 `reason` |
| 6 | 评价接口空列表显示「暂无评价」 |
| 7 | 图文详情 HTML 在 H5/小程序渲染正常 |

---

## 9. 待建设（非本方案）

| 项 | 说明 |
|----|------|
| POST 加入购物车 | 购物车模块 |
| 立即购买 → 确认订单 | 订单模块 |
| 店铺主页 | 店铺模块 |
| 登录/注册页 | 会员模块 |
| 多规格 SKU 选择 | `biz_goods_sku` 落地后扩展 |
| 评价发表 | 订单完成链 |

---

## 10. 修订记录

| 版本 | 说明 |
|------|------|
| **v1.0** | 首版：详情页 + 全部评价页；三读接口封装；上游入口打通 |

---

*文档版本：v1.0 · 工程目录 `shop-app` · 关联《商品详情内页功能需求.md》v1.0、《商品详情内页技术方案.md》v1.4*
