方案与实施计划 · 第一阶段文档

商品功能模块方案与计划

商户上传商品 → 平台审核 → 上架到平台公域(会员端可见可购)的完整链路设计与落地计划

现状:商户可自放上架、无平台审核闸口 目标:审核前置 + 公域仅展示已审核在售 估时:约 9.5 人日

一、目标与范围

业务目标:打通「商户在商家后台上传商品 → 提交平台审核 → 平台通过 → 上架到平台公域(会员端可见可购)」全链路;平台具备前置审核与治理权;全链路可审计。

范围边界:重新规划商品模块的数据模型、生命周期状态机、权限、接口、前端页面与平台公域目录。商户侧类型/分类/运费仍只读复用平台。uni-app 会员端接入为第二阶段,本阶段先交付接口规范 + 商家/平台后台。

二、现状与缺口分析

2.1 现有数据模型(已具备)

goods / goods_sku / goods_spec+goods_spec_value / goods_gallery+goods_detail_image+goods_video / goods_category+goods_category_rel / goods_type / goods_import_task。

2.2 现有能力

2.3 关键缺口

① 缺平台审核状态机

goods.status 仅 0/1;saveGoods 直接 status=1,新建即默认上架,商户可自放上架,平台无法前置管控。

② 公域无可见性过滤

会员端只能拿"任意商品详情",无"仅已审核+在售"的商品目录与搜索。

③ 审核痕迹缺失

无驳回原因留档、无提交/审核/上下架操作审计轨迹。

④ 模块边界模糊

商户(merchant_id>0)与平台自营(=0)混在同一表,缺"平台公域池 = 已审核&在售"统一定义。

三、整体方案

3.1 商品生命周期状态机(核心设计)

引入两个正交维度:review_status(0 草稿 / 1 待审核 / 2 已通过 / 3 已驳回)与 status(0 下架 / 1 上架,仅 review_status=2 有效)。

草稿draft
──提交──▶
待审核pending
──通过──▶
已通过可上架
──上架──▶
在售公域可见
已驳回rejected
◀──驳回──
待审核pending
──修改重提──▶
草稿draft

可视化规则:平台公域仅展示 review_status = 2 且 status = 1。平台治理可强制下架。草稿/待审核/已驳回禁止直接上架。

3.2 数据模型变更

goods 表新增:review_status(tinyint,默认0)、review_remark(varchar255)、submitted_at/reviewed_at(datetime)、reviewer_id(bigint)。新建表 goods_audit_log(goods_id / merchant_id / action / operator_id / operator_role / remark / created_at)。迁移脚本 migrate_goods_review.sql 幂等 ALTER + 建表 + 存量在售商品批量置 review_status=2。

3.3 模块功能划分

A. 商品库

商家后台:草稿增删改查、SKU、媒体、分类、运费、预售。

B. 上架与审核

商家后台:提交/撤回/重提、查看状态与驳回原因、通过后的上/下架。

C. 商品审核

平台后台:待审列表/预览/通过/驳回(填原因)。

D. 商品治理

平台后台:全量列表、强制下架、违规/类目管控。

E. 平台公域目录

公域接口:仅返已审核在售,支持分类/搜索/排序/分页/门店。

F. 统计看板

商户在售/待审数;平台待审/违规数。

3.4 接口设计

商家侧 merchant/Goods.php

方法路由说明
POSTgoods/submit提交审核(draft→pending),校验必填:名称/类型/分类/价格/封面/SKU库存
POSTgoods/withdraw撤回(pending→draft)
POSTgoods/resubmit重新提交(rejected→pending,保留草稿)
GETgoods/review/status我的商品各审核状态数量分布
调整goods/create|update仅存草稿:status 强制 0
调整goods/status仅 review_status=2 允许上下架

平台侧 admin/Goods.php 新增 goods:review 新增 goods:governance

方法路由说明
GETgoods/review/list审核列表(filter review_status)
GETgoods/review/detail审核预览(含商家信息)
POSTgoods/review/approvepending→approved(写 audit_log,高危)
POSTgoods/review/rejectpending→rejected(必填 remark)
POSTgoods/governance/off强制下架(高危)
GETgoods/platform/list平台治理全量列表

公域 app/Goods.php(新增控制器,公开组)

方法路由说明
GETgoods/list公域目录:仅 review_status=2 & status=1,支持分类/关键词/排序/门店/分页
GETgoods/detail已有接口增加校验:非 approved&on 返回"不存在/已下架"

3.5 前端页面

复用原则:类型/分类/运费只读复用平台;SKU/媒体/多分类复用现有保存逻辑,仅加审核状态约束;数据权限严格 merchant_id 隔离 + 门店 storeScope;下单仅在售商品,新增 review_status=2 约束。

四、实施计划

阶段 0 · 数据层
0.5 d
迁移脚本(加字段 + 建 goods_audit_log + 存量平滑);重跑数据字典。
阶段 1 · 商家侧生命周期
2 d
submit/withdraw/resubmit;create/update/status 状态约束;列表状态 Tab;编辑页状态联动。
阶段 2 · 平台审核
1.5 d
review/list/detail/approve/reject;权限 goods:review;审核页前端。
阶段 3 · 平台治理
1 d
governance/off;商品治理页;强制下架。
阶段 4 · 公域目录
1.5 d
app/Goods list + detail 校验;会员端目录/详情(uni-app 第二阶段);搜索/排序。
阶段 5 · 审计与统计
1 d
goods_audit_log 写入;看板(商户在售数 / 平台待审数)。
阶段 6 · 联调与文档
1 d
e2e(草稿→提交→通过→上架→公域可见→驳回→重提);更新数据字典/进度文档。

合计:约 9.5 人日

五、风险与待确认

六、验收口径(联调基线)

文档基于 xshop 真实代码调研产出(merchant/Goods.php · admin/Goods.php · goods 系列表)· 本文为方案与计划,不含实现代码。