2

doc/product_enhancement_requirements.md

@@ -0,0 +1,187 @@
+# 货品功能扩展需求文档（草案）
+
+## 1. 当前实现概览
+
+### 1.1 用户端（uni-app）
+- `pages/product/list.vue`：支持关键字与按类别筛选、下拉分页、查看详情并跳转编辑；展示“平台推荐/我的提交”标签。
+- `pages/product/form.vue`：可创建/编辑货品，字段涵盖名称、条码、品牌、型号、规格、产地、单位、类别、安全库存、四列售价、初始库存、图片与备注；提供图片识码能力；图片上传走 `/api/attachments`。
+- **`pages/product/submit.vue`**：新增配件提交入口，支持型号唯一校验、多图上传、参数 JSON、备注、安全库存等字段，提交成功跳转“我的提交”。
+- **`pages/product/submissions.vue`、`pages/product/submission-detail.vue`**：新增提交列表与详情页，支持状态筛选、滚动分页、驳回重新提交、图片/参数展示。
+- 字典：调用 `/api/product-units`、`/api/product-categories` 读取全局单位/类别，并缓存到本地。
+
+### 1.2 管理端（Vue3 + Element Plus）
+- **`admin/src/views/parts/Submissions.vue`**：已上线配件审核模块，提供筛选、详情、编辑、通过/驳回、Excel 导出能力。
+- 其它模块：VIP 系统、公告管理、咨询回复、用户管理、配件管理、供应商管理、主数据字典。
+- 待迭代：登录页、角色权限细分、操作日志可视化。
+
+### 1.3 后端（Spring Boot）
+- `ProductSubmissionController` + `ProductSubmissionService`：完成用户提交、用户查看、管理员审核/驳回、导出全链路；审批通过时同步 `products`、`product_images`、`source_submission_id` 等字段。
+- OpenAPI 已新增 `/api/products/submissions*` 与 `/api/admin/parts/submissions*` 路径，并标记为 ✅ Fully Implemented。
+- 数据模型：`products`、`product_prices`、`inventories`、`product_images` 已投产；`part_submissions` 已扩展 JSON、状态、审核信息等字段。
+- 图片存储：统一走 `attachments`，提交与商品共享资源。
+
+## 2. 差距分析
+
+| 需求点 | 现状 | 差距 |
+| --- | --- | --- |
+| 用户提交配件待审核 | 用户端新增提交/列表/详情页面，与后台接口打通 | 持续跟踪型号唯一范围（店铺或全局）；补充并发校验测试 |
+| 审核管理 | 管理端已上线审核列表、详情编辑、通过/驳回、导出 | 后续可扩展批量操作、导出更大数据量的异步方案 |
+| 数据查询增强 | 后端支持多条件、返回 total；前端列表分页同步 | 可继续优化查询性能（索引/缓存）与前端展示字段 |
+| 图片管理 | 提交端与审核端均支持多图显示、预览、排序 | 可根据需求补充图片备注、AI 识别等增强能力 |
+| 上架逻辑 | 审核通过自动写入 `products` 并关联 `source_submission_id`、`global_sku_id` | 待确认产品图片、参数同步策略是否满足后续拓展（如平台库） |
+| 导出 | 管理端支持按筛选条件导出 Excel（2000 条以内同步导出） | 后续可评估异步导出/下载中心、导出模板自定义 |
+
+## 3. 设计方案
+
+> 项目采用方案 A（基于 `part_submissions` + `products` 双轨流程），方案 B 已放弃，不再纳入考虑。
+
+### 方案 A：基于现有 `part_submissions` + `products` 双轨流程（已确认）
+1. **用户提交**
+   - 新增用户端页面 `pages/product/submit.vue`，字段：型号（model，唯一必填）、配件名称（name）、配件参数（parameters：自由文本/JSON 字段）、图片（多图，最多 9 张）、备注。
+   - 调用 `POST /api/products/submissions`，写入 `part_submissions`：`shop_id`、`user_id`、`model_unique`、`status=pending`、`images JSON`、`extra_attrs`、`created_at`。
+   - 验证规则：
+     - `model_unique` 同一店铺 + 全局唯一（需确认范围）。
+     - 图片通过 `attachments` 保存，限制尺寸/数量。
+     - 上传成功后展示提交状态（待审核）。
+2. **管理员审核**
+   - 新增管理端视图 `admin/src/views/parts/Submissions.vue`：
+     - 列表字段：型号、名称、提交人、提交时间、当前状态、备注、图片缩略图。
+     - 过滤项：状态（待审/已审/驳回）、关键字（支持型号/名称/提交人）、提交时间区间、店铺。
+     - 操作：
+       - 查看详情（弹窗）：可编辑名称、型号、参数、图片（增删排序）、备注。
+       - 审核按钮：批准/驳回，必须填写备注（驳回）。
+       - 批量导出：选中或按筛选条件导出 Excel。
+   - 审核通过逻辑：
+     - 检测是否存在相同型号产品：
+       - 若没有：创建 `products`（source_submission_id 引用）、初始化库存 0、价格默认 0，关联图片。
+       - 若已有：补充图片、参数（可覆盖或合并），并记录 submission→product 对应关系。
+     - 更新 `part_submissions.status=approved`、`reviewer_id`、`reviewed_at`、`product_id`。
+     - 将产品显示给提交用户（若产品属于平台库，可关联 `global_sku_id`）。
+   - 审核驳回：状态=reject，记录 `remark`、`reviewer_id`、`reviewed_at`。
+3. **数据查询**
+   - `GET /api/products` 增强：支持 `brand`、`model`、`status`（是否审核通过）、`createdStart/End` 等参数；返回 `{ list, total }`。
+   - `GET /api/admin/parts/submissions` 支持分页+多条件，默认按创建时间倒序。
+   - Excel 导出：`GET /api/admin/parts/submissions/export`，返回文件下载，支持当前过滤条件。
+4. **图片管理**
+   - 提交阶段：图片存储 `attachments`，ownerType=submission，路径按 hash 去重。
+   - 审核详情弹窗内使用 `el-image` + preview 功能查看大图；允许删除/新增（调用 `/api/attachments` 上传）。
+   - 审核通过时同步图片至 `product_images`（可重用 attachment URL，无需复制物理文件），根据排序保存 `sort_order`。
+5. **上架逻辑**
+   - 平台维护 `global_skus`（可选）：
+     - 审核通过界面提供“关联平台配件”下拉，或创建新平台配件，同时写入 `global_skus`。
+     - `products.global_sku_id` 记录来源，供其他店铺引用。
+   - 用户提交的产品通过审核后自动加入其店铺的 `products`，并可在商品列表中展示“平台推荐/自有”区分。
+
+### 4.1 数据模型变更细节
+
+#### part_submissions（新增/调整）
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `name` | VARCHAR(120) | 配件名称（用户填写，可用于审核） |
+| `parameters` | JSON | 结构化参数，如规格、尺寸、材质等 |
+| `images` | JSON | 图片 URL 列表，提交阶段存储 |
+| `status` | ENUM('pending','approved','rejected') | 当前审核状态 |
+| `remark` | VARCHAR(255) | 审核备注（驳回原因等） |
+| `reviewer_id` | BIGINT | 审核人 ID |
+| `reviewed_at` | DATETIME | 审核时间 |
+| `product_id` | BIGINT | 审核通过后关联的产品 ID |
+| `global_sku_id` | BIGINT | 可选，关联平台配件 ID |
+| `source_shop_id` | BIGINT | 原提交店铺（若与 shop_id 区分需求明确可保留） |
+
+> 若原表已有旧字段（如 `compatible`、`size` 等），可迁移到 `parameters` JSON 中或保留以兼容老数据。
+
+#### products（新增字段）
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `source_submission_id` | BIGINT | 来源提交记录 ID |
+| `global_sku_id` | BIGINT | 平台配件 ID（可选） |
+| `platform_status` | ENUM('platform','custom') | 产品来源标识（可选） |
+
+需要为 `model_unique`、`shop_id` 添加唯一索引，保障型号不可重复提交（规则确定后实施）。
+
+### 4.2 接口契约摘要
+
+| 接口 | 方法 | 说明 | 核心入参 | 返回 |
+| --- | --- | --- | --- | --- |
+| `/api/products/submissions` | POST | 用户提交配件 | `{ name, model, parameters?, images[], remark? }` | `{ id, status }` |
+| `/api/products/submissions` | GET | 用户查看提交记录 | `status?, page, size` | `{ list, total }` |
+| `/api/admin/parts/submissions` | GET | 管理端列表 | `status?, kw?, shopId?, reviewerId?, startAt?, endAt?, page, size` | `{ list, total }` |
+| `/api/admin/parts/submissions/{id}` | GET | 查看详情 | - | 详细信息（含图片） |
+| `/api/admin/parts/submissions/{id}` | PUT | 编辑字段（名称/参数/图片） | `{ name?, parameters?, images?, remark? }` | `{ ok: true }` |
+| `/api/admin/parts/submissions/{id}/approve` | POST | 审核通过 | `{ remark?, assignGlobalSkuId?, createGlobalSku? }` | `{ ok: true, productId }` |
+| `/api/admin/parts/submissions/{id}/reject` | POST | 审核驳回 | `{ remark }` | `{ ok: true }` |
+| `/api/admin/parts/submissions/export` | GET | Excel 导出 | 同列表查询参数 | 二进制文件 |
+| `/api/products` | GET | 增强查询 | `kw, brand, model, status, categoryId, startAt, endAt, page, size` | `{ list, total }` |
+
+OpenAPI 需同步更新：新增路径、请求体/响应体、状态标注。
+
+### 4.3 前端/后端任务拆分
+
+**后端**
+1. 数据库迁移脚本（新增字段、索引、默认值）。
+2. 提交接口实现：存储提交记录、处理图片、型号唯一校验。
+3. 审核接口实现：
+   - 获取详情、编辑提交记录。
+   - 批准流程（创建/更新产品、同步图片、记录审计）。
+   - 驳回流程。
+4. 列表查询与导出（注意权限：仅管理员）。
+5. 产品查询增强（支持多条件和 total）。
+6. 单元测试/集成测试：审核通过/驳回、重复型号、导出大数据量。
+
+**管理端前端**
+1. 新建 `Submissions.vue` 页面：
+   - 列表 + 搜索表单 + 分页。
+   - Excel 导出按钮。
+2. 审核详情弹窗组件：
+   - 多图预览/排序（Element Plus `el-image` + `el-upload` 或复用现有 `ImageUploader` 组件）。
+   - 字段编辑与保存。
+   - 审核通过/驳回按钮及确认弹窗。
+3. 上架结果联动：审批通过后刷新列表，提示成功。
+
+**用户端前端**
+1. 新增 `pages/product/submit.vue`：
+   - 表单输入 + 多图上传 + 校验（型号唯一、本地格式校验）。
+   - 提交成功提示与跳转。
+2. 新增“我的提交”页面或在现有列表中添加状态指示。
+3. 货品列表/详情展示新字段（如“平台配件”标签、审核状态）。
+
+## 5. 开发计划建议
+1. **第一阶段：后端改造**
+   - 数据库变更（通过 MysqlMCP）：更新 `part_submissions`、`products`、`global_skus` 相关字段与索引。
+   - 新增接口实现（提交、审核、导出、多条件查询）。
+   - 扩展 `ProductService` 支持 total、更多筛选。
+   - 调整 OpenAPI，标注实现状态。
+2. **第二阶段：管理端前端**
+   - 新建审核模块页面，集成组合查询 + 分页 + 导出。
+   - 审核详情对话框支持多图预览/编辑、字段修改、审核按钮。
+3. **第三阶段：用户端前端**
+   - 新增“提交配件”入口（从货品列表或我的模块进入）。
+   - 提交表单 + 多图上传（复用 ImageUploader）。
+   - 提交记录列表（待审/已通过/驳回）与状态提示。
+   - 审核通过后自动同步到货品列表（带标签）。
+4. **第四阶段：测试与文档**
+   - 定义审批流程测试用例：提交->审批->列表刷新->导出。
+   - 验证图片上传、重复型号、并发审批场景。
+   - 更新需求文档、开发文档、用户操作指引。
+
+## 6. 验收标准
+- 用户端可提交配件：型号唯一校验、上传多图成功、提交后状态为“待审核”。
+- 管理端待审核列表能根据筛选条件展示结果，并支持详情查看（含大图预览、编辑字段）。
+- 管理端可对单条记录审核通过/驳回：
+  - 通过：在 `products` 中生成或更新商品；提交用户在商品列表中可见；状态变更为“已通过”。
+  - 驳回：状态变更为“已驳回”，记录审核备注。
+- 导出功能可按筛选条件导出 Excel，至少包含 2000 条数据测试无超时；生成文件名避免冲突（时间戳+操作人）。
+- 数据查询支持组合条件，返回总数；前后端分页一致。
+- 图片管理：审核详情中可预览大图、删除、重新上传；重复文件自动识别 hash，避免冲突。
+- 上线后数据库结构、OpenAPI、开发文档同步更新，无遗漏。
+
+## 7. 风险与注意事项
+- 型号唯一性需统一标准化（去空格、大小写）并考虑跨店铺冲突策略。
+- 审核通过时同步到 `products`，需明确库存与价格的初始值（建议默认 0，提醒用户自行编辑）。
+- Excel 导出需加限流或异步处理，防止长时间请求阻塞。
+- 图片引用避免重复占用存储；可直接引用同一 URL，而非复制文件。
+- 若需消息通知（如审核结束提醒），需要后续补充通知机制。
+- 需要回顾 `global_skus` 与 `products` 的关系，明确平台配件库与用户私有货品的边界，以免数据混乱。
+
+---
+> 本文档结合现状与新增需求整理。请确认方案后，可进一步拆解任务并排期执行。