# 设计文档 ## 概述 珠宝商城微信小程序基于 uni-app (Vue 3) 开发，采用前后端分离架构。前端为微信小程序（用户端）和 Web 管理后台（管理员端），后端提供统一的 RESTful API 服务。系统核心围绕商品展示、购物车、订单管理、钻戒计算器和版房展示五大模块构建，不接入线上支付和物流追踪 API。 ## 架构 ### 整体架构 ```mermaid graph TB subgraph 用户端["用户端 (微信小程序)"] MP[uni-app Vue 3 小程序] end subgraph 管理端["管理端 (Web)"] ADMIN[管理后台 Web 应用] end subgraph 后端服务["后端 API 服务"] API[RESTful API] AUTH[鉴权模块] end subgraph 数据层["数据层"] DB[(MySQL 数据库)] OSS[文件存储/OSS] end MP -->|HTTP 请求| API ADMIN -->|HTTP 请求| API API --> AUTH API --> DB API --> OSS ``` ### 前端页面结构 ```mermaid graph LR subgraph TabBar["底部 TabBar"] HOME[首页/商品列表] CART[购物车] MOLD[版房专区] MINE[我的] end HOME --> PRODUCT_DETAIL[商品详情] HOME --> CATEGORY[分类筛选] PRODUCT_DETAIL --> SPEC_PANEL[详细参数面板] CART --> ORDER_SUBMIT[订单提交] ORDER_SUBMIT --> ORDER_DETAIL[订单详情] MINE --> ORDER_LIST[订单列表] ORDER_LIST --> ORDER_DETAIL MINE --> ADDRESS[收货地址管理] MINE --> ABOUT[关于我们] CALC[钻戒计算器] -.->|独立入口| TabBar ``` ### 技术选型 | 层级 | 技术方案 | |------|---------| | 前端框架 | uni-app + Vue 3 + Composition API | | 状态管理 | Pinia | | 网络请求 | uni.request 封装 | | UI 组件 | uni-ui + 自定义组件 | | 管理后台 | Vue 3 + Element Plus（Web 端） | | 后端 API | Node.js + Express / Koa | | 数据库 | MySQL | | 文件存储 | 本地存储 / 云存储 OSS | ## 组件与接口 ### 前端核心组件 #### 1. 页面组件 | 组件 | 路径 | 职责 | |------|------|------| | HomePage | `pages/home/index.vue` | 商品列表、分类筛选 | | ProductDetail | `pages/product/detail.vue` | 商品详情、banner、规格选择 | | CartPage | `pages/cart/index.vue` | 购物车管理 | | OrderSubmit | `pages/order/submit.vue` | 订单提交 | | OrderDetail | `pages/order/detail.vue` | 订单详情 | | OrderList | `pages/order/list.vue` | 订单列表 | | MoldGallery | `pages/mold/index.vue` | 版房专区 | | RingCalculator | `pages/calculator/index.vue` | 钻戒计算器 | | MinePage | `pages/mine/index.vue` | 我的页面 | | AddressManage | `pages/address/index.vue` | 收货地址管理 | #### 2. 公共组件 | 组件 | 职责 | |------|------| | ProductCard | 商品卡片（列表项） | | SpecPanel | 详细参数选择弹窗 | | BannerSwiper | 商品详情顶部轮播（图片+视频） | | CustomerServiceBtn | 客服按钮（二维码/小程序客服） | | ShippingNotice | 统一发货公告 | ### API 接口设计 #### 商品模块 ``` GET /api/products # 商品列表（支持分类筛选、分页） GET /api/products/:id # 商品详情（含 Base_Attribute） GET /api/products/:id/specs # 商品详细参数选项 POST /api/products/:id/spec-data # 根据参数组合获取 Spec_Data_List GET /api/categories # 商品分类列表 ``` #### 购物车模块 ``` GET /api/cart # 获取购物车列表 POST /api/cart # 添加商品到购物车 PUT /api/cart/:id # 更新购物车项（数量等） DELETE /api/cart/:id # 删除购物车项 ``` #### 订单模块 ``` POST /api/orders # 提交订单 GET /api/orders # 获取用户订单列表 GET /api/orders/:id # 获取订单详情 PUT /api/orders/:id/cancel # 取消订单 ``` #### 版房模块 ``` GET /api/molds # 版房列表（支持搜索） GET /api/molds/:id # 版房详情 ``` #### 用户模块 ``` POST /api/auth/wx-login # 微信登录 GET /api/user/profile # 用户信息 GET /api/user/addresses # 收货地址列表 POST /api/user/addresses # 新增收货地址 PUT /api/user/addresses/:id # 编辑收货地址 DELETE /api/user/addresses/:id # 删除收货地址 ``` #### 管理后台接口 ``` # 商品管理 POST /api/admin/products # 创建商品 PUT /api/admin/products/:id # 编辑商品 DELETE /api/admin/products/:id # 删除商品 POST /api/admin/products/import # 规格数据表格导入 GET /api/admin/products/export # 规格数据表格导出 GET /api/admin/stock-alerts # 库存预警列表 # 订单管理 POST /api/admin/orders # 手动创建订单 PUT /api/admin/orders/:id # 修改订单 PUT /api/admin/orders/:id/status # 更新订单状态（已支付/已发货） # 版房管理 POST /api/admin/molds # 创建版房信息 PUT /api/admin/molds/:id # 编辑版房信息 DELETE /api/admin/molds/:id # 删除版房信息 # 文件上传 POST /api/admin/upload # 上传图片/视频/支付凭证 ``` ## 数据模型 ### 商品 (Product) ```typescript interface Product { id: number name: string // 商品名称 basePrice: number // 基础价格 styleNo: string // 款号 stock: number // 库存数量 totalStock: number // 总库存（用于计算库存百分比） loss: number // 损耗 laborCost: number // 工费 categoryId: number // 分类 ID bannerImages: string[] // banner 图片 URL 列表 bannerVideo?: string // banner 视频 URL status: 'on' | 'off' // 上架/下架 createdAt: string updatedAt: string } ``` ### 商品分类 (Category) ```typescript interface Category { id: number name: string parentId?: number sort: number } ``` ### 详细参数配置 (DetailParameterConfig) ```typescript interface DetailParameterConfig { id: number productId: number fineness: string[] // 成色选项列表 mainStone: string[] // 主石选项列表 ringSize: string[] // 手寸选项列表 } ``` ### 规格数据 (SpecData) ```typescript interface SpecData { id: number productId: number modelName: string // 商品型号名称 fineness: string // 成色 mainStone: string // 主石 ringSize: string // 手寸 goldTotalWeight: number // 金料总重 goldNetWeight: number // 金料净重 loss: number // 损耗 goldLoss: number // 金耗 goldPrice: number // 金价 goldValue: number // 金值 mainStoneCount: number // 主石数量 mainStoneWeight: number // 主石石重 mainStoneUnitPrice: number // 主石单价 mainStoneAmount: number // 主石金额 sideStoneCount: number // 副石数量 sideStoneWeight: number // 副石石重 sideStoneUnitPrice: number // 副石单价 sideStoneAmount: number // 副石金额 accessoryAmount: number // 配件金额 processingFee: number // 加工工费 settingFee: number // 镶石工费 totalLaborCost: number // 总工费 totalPrice: number // 总价 } ``` ### 购物车项 (CartItem) ```typescript interface CartItem { id: number userId: number productId: number specDataId: number // 关联的规格数据 quantity: number product: Product // 关联商品信息 specData: SpecData // 关联规格数据 checked: boolean // 前端勾选状态（本地） } ``` ### 订单 (Order) ```typescript interface Order { id: number orderNo: string // 订单号 userId: number status: 'pending' | 'paid' | 'shipped' | 'cancelled' totalPrice: number // 收货信息 receiverName: string receiverPhone: string receiverAddress: string // 支付信息（已支付后填充） paymentTime?: string paymentProof?: string // 支付凭证图片 URL // 物流信息（已发货后填充） shippingCompany?: string // 物流公司名 shippingNo?: string // 物流单号 createdAt: string updatedAt: string } ``` ### 订单商品项 (OrderItem) ```typescript interface OrderItem { id: number orderId: number productId: number specDataId: number quantity: number unitPrice: number product: Product specData: SpecData } ``` ### 版房信息 (MoldInfo) ```typescript interface MoldInfo { id: number name: string // 名称 styleNo?: string // 款号 barcodeNo?: string // 条码号 style?: string // 款式 images: string[] // 展示图片 URL 列表 createdAt: string updatedAt: string } ``` ### 收货地址 (Address) ```typescript interface Address { id: number userId: number name: string phone: string province: string city: string district: string detail: string isDefault: boolean } ``` ### 用户 (User) ```typescript interface User { id: number openId: string // 微信 openId nickname: string avatar: string createdAt: string } ``` ### 钻戒计算器输入/输出 (RingCalculatorData) ```typescript interface RingCalculatorInput { goldWeight: number // 金重(g) mainStoneWeight: number // 主石重(ct) sideStoneWeight: number // 副石重(ct) lossRate: number // 损耗（倍率） moldGoldPrice: number // 倒模金价(元) mainStoneUnitPrice: number // 主石单价(元) sideStoneUnitPrice: number // 副石单价(元) sideStoneCount: number // 副石粒数(p) microSettingFee: number // 微镶费(元/粒) mainStoneSettingFee: number // 主石镶费(元) threeDFee: number // 3D起板费(元) basicLaborCost: number // 基本工费(元) otherCost: number // 其他费用(元) } interface RingCalculatorResult { netGoldWeight: number // 净金重(g) weightWithLoss: number // 含耗重(g) goldValue: number // 金值(元) mainStoneTotal: number // 主石总价(元) sideStoneTotal: number // 副石总价(元) microSettingTotal: number // 微镶总价(元) totalPrice: number // 总价(元) } ``` ### 钻戒计算器核心计算逻辑（纯函数） ```typescript function calculateRing(input: RingCalculatorInput): RingCalculatorResult { const netGoldWeight = input.goldWeight - input.mainStoneWeight * 0.2 - input.sideStoneWeight * 0.2 const weightWithLoss = netGoldWeight * input.lossRate const goldValue = weightWithLoss * input.moldGoldPrice const mainStoneTotal = input.mainStoneWeight * input.mainStoneUnitPrice const sideStoneTotal = input.sideStoneWeight * input.sideStoneUnitPrice const microSettingTotal = input.sideStoneCount * input.microSettingFee const totalPrice = goldValue + mainStoneTotal + sideStoneTotal + input.mainStoneSettingFee + microSettingTotal + input.threeDFee + input.basicLaborCost + input.otherCost return { netGoldWeight, weightWithLoss, goldValue, mainStoneTotal, sideStoneTotal, microSettingTotal, totalPrice, } } ``` ## 正确性属性 *属性（Property）是指在系统所有有效执行中都应成立的特征或行为——本质上是对系统应做什么的形式化陈述。属性是人类可读规格与机器可验证正确性保证之间的桥梁。* ### Property 1：购物车添加商品不变量 *对于任意* 商品和有效规格组合，将其添加到购物车后，购物车中应包含该商品和规格的条目，且购物车项数增加 1。 **Validates: Requirements 2.1** ### Property 2：购物车总金额计算正确性 *对于任意* 购物车商品集合和勾选状态组合，展示的总金额应等于所有已勾选商品的单价乘以数量之和。 **Validates: Requirements 2.3** ### Property 3：订单状态与展示字段匹配 *对于任意* 订单及其状态（待支付/已支付/已发货），订单详情展示的信息字段应与状态匹配：已支付状态应包含支付时间，已发货状态应包含物流公司名称和物流单号。 **Validates: Requirements 3.5, 3.6** ### Property 4：钻戒计算器公式正确性 *对于任意* 有效的 RingCalculatorInput（所有数值字段为非负数），calculateRing 函数的输出应满足： - netGoldWeight = goldWeight - mainStoneWeight × 0.2 - sideStoneWeight × 0.2 - weightWithLoss = netGoldWeight × lossRate - goldValue = weightWithLoss × moldGoldPrice - mainStoneTotal = mainStoneWeight × mainStoneUnitPrice - sideStoneTotal = sideStoneWeight × sideStoneUnitPrice - microSettingTotal = sideStoneCount × microSettingFee - totalPrice = goldValue + mainStoneTotal + sideStoneTotal + mainStoneSettingFee + microSettingTotal + threeDFee + basicLaborCost + otherCost **Validates: Requirements 4.2, 4.3, 4.4, 4.5, 4.6, 4.7, 4.8** ### Property 5：版房搜索结果匹配 *对于任意* 关键词和版房数据集，搜索返回的每一条结果的名称、款号、条码号或款式中至少有一个字段包含该关键词。 **Validates: Requirements 5.3** ### Property 6：规格数据导入导出 Round-Trip *对于任意* 有效的商品规格数据集合，导出为表格文件后再导入，应得到与原始数据等价的规格数据集合。 **Validates: Requirements 8.3** ### Property 7：库存预警阈值判断 *对于任意* 商品集合，库存预警列表应恰好包含所有 stock/totalStock < 0.1 的商品，且按库存数量从少到多排序。 **Validates: Requirements 8.4** ### Property 8：订单价格自动重算 *对于任意* 订单及其商品项变更（修改商品或型号），变更后的订单总价应等于所有订单项的单价乘以数量之和。 **Validates: Requirements 9.4** ## 错误处理 ### 前端错误处理 | 场景 | 处理方式 | |------|---------| | 网络请求失败 | 展示友好提示（如"网络异常，请稍后重试"），提供重试按钮 | | 商品已下架/售罄 | 在商品详情页和购物车中标记状态，禁止加入购物车或下单 | | 购物车为空时点击下单 | 提示"请先选择商品" | | 订单提交失败 | 提示错误原因，保留用户填写的信息，支持重新提交 | | 钻戒计算器输入非法值 | 输入框校验，提示"请输入有效数字"，不执行计算 | | 版房搜索无结果 | 展示"未找到匹配结果"提示 | | 微信登录失败 | 提示用户重新授权，引导至授权页面 | | 图片/视频加载失败 | 展示占位图，不影响页面其他内容 | ### 后端错误处理 | 场景 | 处理方式 | |------|---------| | 请求参数校验失败 | 返回 400 状态码，附带具体字段错误信息 | | 资源不存在 | 返回 404 状态码 | | 未授权访问 | 返回 401 状态码，前端引导重新登录 | | 管理员权限不足 | 返回 403 状态码 | | 库存不足 | 返回业务错误码，前端提示"库存不足" | | 订单状态流转非法 | 返回业务错误码（如已取消的订单不能改为已支付） | | 规格数据导入格式错误 | 返回具体行号和错误原因，支持部分导入 | | 文件上传失败 | 返回错误信息，前端提示重新上传 | | 数据库操作异常 | 记录错误日志，返回 500 状态码，前端展示通用错误提示 | ### 订单状态流转规则 ```mermaid stateDiagram-v2 [*] --> 待支付 : 提交订单 待支付 --> 已支付 : 后台确认支付 已支付 --> 已发货 : 后台确认发货 待支付 --> 已取消 : 用户取消 已取消 --> [*] 已发货 --> [*] ``` 合法状态流转： - 待支付 → 已支付（仅后台操作） - 已支付 → 已发货（仅后台操作） - 待支付 → 已取消（用户或后台操作） - 其他状态流转均为非法操作 ## 测试策略 ### 测试框架选型 | 类型 | 工具 | |------|------| | 单元测试 | Vitest | | 属性测试 | fast-check + Vitest | | 组件测试 | @vue/test-utils + Vitest | | API 测试 | Supertest + Vitest | ### 属性测试（Property-Based Testing） 使用 fast-check 库进行属性测试，每个属性测试至少运行 100 次迭代。 每个属性测试必须以注释标注对应的设计文档属性编号： ```typescript // Feature: jewelry-mall, Property 4: 钻戒计算器公式正确性 ``` 属性测试覆盖的正确性属性： - Property 1：购物车添加商品不变量 - Property 2：购物车总金额计算正确性 - Property 3：订单状态与展示字段匹配 - Property 4：钻戒计算器公式正确性 - Property 5：版房搜索结果匹配 - Property 6：规格数据导入导出 Round-Trip - Property 7：库存预警阈值判断 - Property 8：订单价格自动重算 每个正确性属性由一个独立的属性测试实现。 ### 单元测试 单元测试覆盖具体示例、边界情况和错误条件： - 钻戒计算器：输入为 0 的边界情况、负数输入校验 - 购物车：空购物车操作、重复添加同一商品 - 订单：非法状态流转、缺少必填字段 - 版房搜索：空关键词、特殊字符 - 库存预警：库存恰好为 10% 的边界值 - 规格数据导入：格式错误、缺少必填列 ### 组件测试 使用 @vue/test-utils 测试关键 Vue 组件的渲染和交互逻辑： - 商品详情页 banner 渲染 - 购物车勾选和金额计算 - 订单提交页贵重物品提醒勾选逻辑 - 钻戒计算器输入和结果展示 ### API 集成测试 使用 Supertest 测试后端 API 的请求/响应： - 商品 CRUD 操作 - 订单创建和状态流转 - 购物车操作 - 版房搜索 - 规格数据导入导出