# 需求文档

## 简介

珠宝商城微信小程序，基于 uni-app (Vue) 开发，面向单门店珠宝经营场景。核心功能包括商品展示与购物车、珠宝规格精细化管理、钻戒计算器、版房展示、订单全流程管理及配套管理后台。不接入线上支付，不对接物流位置 API，交易与物流均通过线下/微信沟通完成。

## 术语表

- **小程序前端 (Frontend)**：用户在微信中使用的小程序界面，包含商品浏览、购物车、订单、版房、我的等页面
- **管理后台 (Admin_Panel)**：工作人员使用的后台管理系统，用于商品、库存、订单、版房的全流程管理
- **商品规格 (Product_Spec)**：珠宝商品的属性参数体系，分为基础属性（固定展示）和详细参数（可选择）
- **基础属性 (Base_Attribute)**：商品详情页直接展示的固定属性，包括商品名称、基础价格、款号、库存、损耗、工费
- **详细参数 (Detail_Parameter)**：点击「查看详细参数」弹出的可选参数，包括成色、主石、手寸，不同分类可配置不同选项
- **规格数据列表 (Spec_Data_List)**：根据用户所选详细参数生成的精准核算数据列表
- **钻戒计算器 (Ring_Calculator)**：独立功能模块，内置金工石费用计算公式，支持各维度单独计算
- **版房专区 (Mold_Gallery)**：展示型页面，展示版房信息（名称、多图），定制需联系客服
- **订单 (Order)**：用户提交的购买请求，状态流转为：待支付 → 已支付 → 已发货
- **购物车 (Shopping_Cart)**：用户暂存待购商品的功能模块
- **在线客服 (Customer_Service)**：小程序内多场景客服入口，支持二维码添加好友和小程序自带客服两种方式
- **库存警告 (Stock_Alert)**：当商品库存低于 10% 时在管理后台首页展示的预警信息
- **支付凭证 (Payment_Proof)**：工作人员在后台上传的用户线下支付截图
- **物流信息 (Shipping_Info)**：工作人员在后台手动录入的物流公司名和物流单号，仅前端展示

## 需求

### 需求 1：商品展示与浏览

**用户故事：** 作为用户，我希望浏览和查看珠宝商品，以便了解商品信息并做出购买决策。

#### 验收标准

1. WHEN 用户进入商城首页, THE Frontend SHALL 展示商品列表，支持按分类筛选商品
2. WHEN 用户点击某个商品, THE Frontend SHALL 跳转至商品详情页，展示商品 Base_Attribute（名称、基础价格、款号、库存、损耗、工费）
3. WHEN 商品详情页加载完成, THE Frontend SHALL 在顶部 banner 区域展示该商品配置的多图和视频内容
4. WHEN 商品详情页加载完成, THE Frontend SHALL 在基础信息下方固定展示商城统一发货公告（含交易方式、客服微信、公司地址）
5. WHEN 用户点击「查看详细参数」, THE Frontend SHALL 弹出 Detail_Parameter 选择面板，展示成色、主石、手寸等可选参数
6. WHEN 用户选择 Detail_Parameter 组合后, THE Frontend SHALL 生成并展示对应的 Spec_Data_List（含金料重量、金值、石料信息、工费、总价等核算数据）

### 需求 2：购物车功能

**用户故事：** 作为用户，我希望将感兴趣的商品加入购物车并管理，以便统一下单购买。

#### 验收标准

1. WHEN 用户在商品详情页点击「加入购物车」, THE Frontend SHALL 将该商品及所选规格添加到 Shopping_Cart
2. WHEN 用户进入购物车页面, THE Frontend SHALL 展示已添加的商品列表，包含商品信息和规格信息
3. WHEN 用户勾选或取消勾选购物车中的商品, THE Frontend SHALL 实时计算并展示已勾选商品的总金额
4. WHEN 用户点击购物车中的「下单」按钮, THE Frontend SHALL 将已勾选的商品信息传递至订单提交页


### 需求 3：订单全流程管理

**用户故事：** 作为用户，我希望提交订单并跟踪订单状态，以便完成购买流程。

#### 验收标准

1. WHEN 用户进入订单提交页, THE Frontend SHALL 展示公司地址/物流信息、用户发货信息填写区、发货时间提醒、下单商品列表及贵重物品不退换提醒
2. WHILE 用户未勾选贵重物品不退换提醒, THE Frontend SHALL 将「提交订单」按钮置为灰色不可点击状态
3. WHEN 用户勾选贵重物品不退换提醒后点击「提交订单」, THE Frontend SHALL 创建 Order 并跳转至订单详情页，同时在 Admin_Panel 生成对应订单信息
4. WHEN 用户查看订单详情, THE Frontend SHALL 展示订单商品列表、订单号、总价及当前订单状态（待支付/已支付/已发货）
5. WHEN Order 状态为已支付, THE Frontend SHALL 额外展示支付时间信息
6. WHEN Order 状态为已发货, THE Frontend SHALL 额外展示物流公司名称和物流单号（纯展示，无物流追踪）
7. WHEN 用户在订单详情页点击「取消订单」, THE Frontend SHALL 取消该 Order 并更新订单状态
8. WHEN 用户在订单详情页点击「添加客服好友」, THE Frontend SHALL 弹出客服微信二维码
9. WHEN 用户在订单详情页点击「联系客服」, THE Frontend SHALL 拉起微信小程序自带客服功能
10. WHEN 用户进入「我的-订单」页面, THE Frontend SHALL 展示该用户所有订单列表，点击可进入对应订单详情页

### 需求 4：钻戒计算器

**用户故事：** 作为用户，我希望使用钻戒计算器精准核算珠宝费用，以便了解金工石各项成本明细。

#### 验收标准

1. THE Ring_Calculator SHALL 提供金重、主石重、副石重、损耗、倒模金价、主石单价、副石单价、副石粒数、微镶费、3D起板费、基本工费、其他费用等输入字段
2. WHEN 用户输入金重、主石重和副石重, THE Ring_Calculator SHALL 按公式计算净金重：净金重(g) = 金重(g) - 主石重(ct)×0.2 - 副石重(ct)×0.2
3. WHEN 用户输入净金重和损耗, THE Ring_Calculator SHALL 按公式计算含耗重：含耗重(g) = 净金重(g) × 损耗
4. WHEN 用户输入含耗重和倒模金价, THE Ring_Calculator SHALL 按公式计算金值：金值(元) = 含耗重(g) × 倒模金价(元)
5. WHEN 用户输入主石重和主石单价, THE Ring_Calculator SHALL 按公式计算主石总价：主石总价(元) = 主石重(ct) × 主石单价(元)
6. WHEN 用户输入副石重和副石单价, THE Ring_Calculator SHALL 按公式计算副石总价：副石总价(元) = 副石重(ct) × 副石单价(元)
7. WHEN 用户输入副石粒数和微镶费, THE Ring_Calculator SHALL 按公式计算微镶总价：微镶总价(元) = 副石粒数(p) × 微镶费(元)
8. WHEN 所有费用项计算完成, THE Ring_Calculator SHALL 按公式计算总价：总价 = 金值 + 主石总价 + 副石总价 + 主石镶费 + 微镶总价 + 3D起板费 + 基本工费 + 其他费用
9. WHEN 用户修改任意输入字段, THE Ring_Calculator SHALL 实时重新计算所有关联的费用项和总价

### 需求 5：版房专区

**用户故事：** 作为用户，我希望浏览版房展示信息，以便了解可定制的珠宝款式。

#### 验收标准

1. WHEN 用户进入版房专区页面, THE Frontend SHALL 展示由 Admin_Panel 配置的版房信息列表（名称、展示图片）
2. WHEN 版房信息包含多张图片, THE Frontend SHALL 支持展示该条信息的所有配置图片
3. WHEN 用户在版房专区搜索框输入关键词, THE Frontend SHALL 按产品名称、款号、条码号或款式进行搜索并展示匹配结果
4. IF 用户需要定制服务, THEN THE Frontend SHALL 引导用户通过客服入口联系客服沟通


### 需求 6：在线客服

**用户故事：** 作为用户，我希望在多个场景方便地联系客服，以便咨询商品、交易和售后问题。

#### 验收标准

1. THE Frontend SHALL 在商品详情页、购物车页、订单详情页、我的页面等多场景配置客服入口
2. WHEN 用户点击「添加客服好友」入口, THE Frontend SHALL 弹出客服微信二维码供用户扫码添加
3. WHEN 用户点击「联系客服」入口, THE Frontend SHALL 拉起微信小程序自带客服会话功能

### 需求 7：「我的」页面

**用户故事：** 作为用户，我希望在「我的」页面管理个人信息和常用功能入口，以便快速访问核心功能。

#### 验收标准

1. WHEN 用户进入「我的」页面, THE Frontend SHALL 展示微信用户信息（头像、昵称）
2. THE Frontend SHALL 在「我的」页面提供以下功能入口：我的订单、收货地址、联系客服、关于我们、用户协议、隐私政策
3. WHEN 用户点击「我的订单」, THE Frontend SHALL 跳转至订单列表页
4. WHEN 用户点击「收货地址」, THE Frontend SHALL 跳转至收货地址管理页面，支持新增、编辑和删除收货地址

### 需求 8：管理后台 - 商品管理

**用户故事：** 作为管理员，我希望在后台管理商品信息和库存，以便维护商城商品数据。

#### 验收标准

1. THE Admin_Panel SHALL 提供商品配置功能，支持填写 Base_Attribute（名称、基础价格、款号、库存、损耗、工费）和配置 banner（多图+视频）
2. THE Admin_Panel SHALL 提供 Detail_Parameter 配置功能，支持按商品分类配置不同的成色、主石、手寸选项
3. THE Admin_Panel SHALL 支持商品规格数据的表格导入和导出功能
4. WHEN 商品库存低于该商品总库存的 10%, THE Admin_Panel SHALL 在首页展示 Stock_Alert，按库存数量从少到多排序
5. WHEN 管理员点击 Stock_Alert 中的商品, THE Admin_Panel SHALL 跳转至该商品的配置页面

### 需求 9：管理后台 - 订单管理

**用户故事：** 作为管理员，我希望在后台管理订单全流程，以便处理用户的购买请求。

#### 验收标准

1. THE Admin_Panel SHALL 支持手动创建 Order，需关联用户 ID 并选择商品/型号信息
2. WHEN 管理员手动创建 Order, THE Frontend SHALL 在对应用户的订单列表中自动展示该订单
3. THE Admin_Panel SHALL 支持修改 Order 中的商品和型号信息
4. WHEN 管理员修改 Order 的商品或型号, THE Admin_Panel SHALL 自动重新计算订单价格，且 Frontend 同步更新展示
5. WHEN 用户完成线下支付后, THE Admin_Panel SHALL 支持管理员将 Order 状态更新为「已支付」，并上传 Payment_Proof（图片）和填写支付时间
6. WHEN 商品线下发货后, THE Admin_Panel SHALL 支持管理员将 Order 状态更新为「已发货」，并填写物流公司名和物流单号
7. WHEN 管理员更新 Order 状态或信息, THE Frontend SHALL 自动同步展示最新的订单状态和信息

### 需求 10：管理后台 - 版房管理

**用户故事：** 作为管理员，我希望在后台管理版房展示信息，以便维护版房专区内容。

#### 验收标准

1. THE Admin_Panel SHALL 提供版房信息配置功能，支持填写名称和上传多张展示图片
2. WHEN 管理员新增或修改版房信息, THE Frontend SHALL 在版房专区页面同步展示最新内容