# 货品功能扩展需求文档（草案）

## 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` 的关系，明确平台配件库与用户私有货品的边界，以免数据混乱。

---
> 本文档结合现状与新增需求整理。请确认方案后，可进一步拆解任务并排期执行。