PartsInquiry/doc/product_enhancement_requirements.md

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

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

---

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