|
|
@@ -0,0 +1,405 @@
|
|
|
+# CFC 商品订单域「补缺口」增量架构设计 + 任务拆分
|
|
|
+
|
|
|
+> 文档类型:增量架构设计(可执行实施方案)
|
|
|
+> 作者:高见远(架构师)· 日期:2026-11-14
|
|
|
+> 上游输入:`2026-11-14-product-order-gap-prd.md`(产品经理许清楚)+ 项目规约 `AGENTS.md`
|
|
|
+> 关联代码基线:`product_order_gap_fill`;不改动已完成主链路(pending→paid→pending_receipt→completed)
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 0. 主理人已拍板默认口径(本设计依此落地,用户可后续覆敲)
|
|
|
+
|
|
|
+| 编号 | 口径 | 本设计落法 |
|
|
|
+|---|---|---|
|
|
|
+| Q1 | 评价=**新建商品评价域**(不复用 `review_orders` 活动评价表);字段=综合星级(1-5)+文字(≤500字)+晒图(≤3张);完成后 90 天可评;支持商家回复;不支持追评(P2 再议) | 新建 `product_reviews` 表 + 独立 `ProductReview*` 服务/控制器;`ReviewOrderServiceImpl` 活动评价链路**零改动** |
|
|
|
+| Q2 | 咨询 MVP = 官方企微客服承接(PRD §4 方案 A) | 小程序原生客服会话 `<button open-type="contact">` + `session-from` 带订单/商品上下文,零后端 |
|
|
|
+| Q3 | 发货后 **10 天**未确认 → 自动 completed;发货后**第 9 天**推送微信订阅消息提醒;虚拟/实物统一阈值(实物主场景),可配置 | `shop.order.receipt-timeout-days=10`、`shop.order.receipt-remind-days=9`(可配 + 开关) |
|
|
|
+| Q4 | 完成 90 天内可评、不追评(P2 再议);商家回复由本迭代落地 | 见 Q1 |
|
|
|
+| Q5 | 用户端 `POST /api/product/order/ship` **废弃**(410 Gone + 注释);仅保留 `POST /api/admin/product/order/ship`(管理端身份校验),管理员可代发;存量幽灵 `shipped/pending_shipment` 无代码写入 → **不改历史数据**,前端判断统一 `pending_receipt` | service.ship() 增加操作者校验(订单商品 `vendorId` 或平台角色),写 `shipped_at` |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 1. 总览:P0/P1/P2 需求实现概要(表 / 接口 / 页面三视角)
|
|
|
+
|
|
|
+### 1.1 P0 · Must have
|
|
|
+
|
|
|
+| 需求 | 表 | 接口 | 页面 |
|
|
|
+|---|---|---|---|
|
|
|
+| **P0-A 普通商品评价打通**(G2) | 新表 `product_reviews`(迁移464) | `POST /api/product/review/create`、`/detail`、`/list`、`/reply`、`/my` | 订单详情「去评价」按钮 + 新页 `order-review`;订单列表「去评价」+ 新页 `my-reviews`;商品详情页评价列表/浮层 |
|
|
|
+| **P0-B 待收货超时自动完成**(G4) | `product_orders` 加 `shipped_at`、`receipt_remind_at`(迁移465) | 无新接口(定时任务内部) | 订单详情待收货态提示「超时将自动完成」;支付页订阅消息授权(提醒触达前提) |
|
|
|
+| **P0-C ship 越权修复**(G6) | — | `POST /api/product/order/ship` 标 410 废弃;`POST /api/admin/product/order/ship` 增加操作者身份校验(商家本人或平台角色,管理员可代发) | 无(前端目前无 ship 调用);商家端发货见 P1-B |
|
|
|
+| **P0-D 状态字典口径修复**(G5) | — | `POST /api/product/order/my/counts` 键 `shipped` → `pending_receipt`(兼容期双键) | `order-detail.vue`、`order-list.vue` 幽灵 `shipped` 判断统一改 `pending_receipt` |
|
|
|
+
|
|
|
+### 1.2 P1 · Should have
|
|
|
+
|
|
|
+| 需求 | 表 | 接口 | 页面 |
|
|
|
+|---|---|---|---|
|
|
|
+| **P1-A 售前/售中咨询渠道**(G1) | 无(微信客服会话) | 无后端新接口(沿用小程序原生客服) | 商品详情页、订单详情页「咨询客服」入口(`open-type=contact`,`session-from` 带上下文) |
|
|
|
+| **P1-B 商家端小程序发货入口**(G3) | — | 复用 `POST /api/admin/product/order/ship`(P0-C 改造后;商家登录态 + service 身份校验) | `pages/vendor/orders/orders.vue`:新增「待发货」集合 + 发货弹窗(物流单号/快递公司)+「待收货」Tab |
|
|
|
+
|
|
|
+### 1.3 P2 · Nice to have(本迭代仅留接口扩展位,不实现)
|
|
|
+
|
|
|
+| 需求 | 说明 | 预留 |
|
|
|
+|---|---|---|
|
|
|
+| P2-A 追评 | 不实现(Q1 口径);晒图已随 P0-A 落表 | `product_reviews` 预留 `status` 列伸缩空间 |
|
|
|
+| P2-B 评价治理 | 敏感词/隐藏/申诉/置顶 | 评价列表接口预留 `status` 过滤位;敏感词可复用 `ContentFilterService`(若存在) |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 2. 数据层
|
|
|
+
|
|
|
+### 2.1 新表:商品评价表 `product_reviews`(迁移 464)
|
|
|
+
|
|
|
+```sql
|
|
|
+CREATE TABLE IF NOT EXISTS product_reviews (
|
|
|
+ id BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT '主键ID',
|
|
|
+ order_id BIGINT NOT NULL COMMENT '关联 product_orders.id',
|
|
|
+ product_id BIGINT NOT NULL COMMENT '关联 products.id(冗余,便于商品详情页列表)',
|
|
|
+ reviewer_id BIGINT NOT NULL COMMENT '评价人ID(user.id)',
|
|
|
+ rating TINYINT NOT NULL COMMENT '综合星级 1-5',
|
|
|
+ review_text VARCHAR(500) NOT NULL DEFAULT '' COMMENT '评价文字 ≤500字',
|
|
|
+ images TEXT COMMENT '晒图URL数组 JSON(≤3张),如 ["/upload/a.jpg"]',
|
|
|
+ reply_text VARCHAR(500) DEFAULT NULL COMMENT '商家回复 ≤500字',
|
|
|
+ replied_at DATETIME DEFAULT NULL COMMENT '商家回复时间',
|
|
|
+ reply_by BIGINT DEFAULT NULL COMMENT '回复人ID(商家 user.id)',
|
|
|
+ status TINYINT NOT NULL DEFAULT 1 COMMENT '1=展示 0=隐藏(P2治理预留)',
|
|
|
+ review_at DATETIME NOT NULL COMMENT '评价时间',
|
|
|
+ created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
|
|
|
+ updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
|
|
|
+ UNIQUE KEY uk_order_id (order_id),
|
|
|
+ KEY idx_product_id (product_id),
|
|
|
+ KEY idx_reviewer_id (reviewer_id)
|
|
|
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='商品订单评价表(独立于活动评价 review_orders)';
|
|
|
+```
|
|
|
+
|
|
|
+> 说明:不复用 `review_orders`(该表承载活动多分项评价,由 `ReviewOrderServiceImpl` 独占,放开硬限制会污染活动口径)。新表与旧表通过 `order_id` 隔离,两域互不干扰。
|
|
|
+
|
|
|
+### 2.2 既有表变更:`product_orders`(迁移 465)
|
|
|
+
|
|
|
+```sql
|
|
|
+-- 发货时间:ship() 成功落库时写(超时任务/提醒的基准时间)
|
|
|
+ALTER TABLE product_orders ADD COLUMN shipped_at DATETIME NULL COMMENT '发货时间';
|
|
|
+-- 收货提醒推送标记:第9天推送成功后写,幂等防重复推送
|
|
|
+ALTER TABLE product_orders ADD COLUMN receipt_remind_at DATETIME NULL COMMENT '收货提醒推送时间';
|
|
|
+```
|
|
|
+
|
|
|
+### 2.3 DatabaseInitializer 迁移规约
|
|
|
+
|
|
|
+- **唯一入口**:`DatabaseInitializer.runMigrations()` 内追加两个方法(保持既有 `// 迁移N` 注释编号风格),最新编号 **463** → 本迭代 **464、465**:
|
|
|
+ - `private void migrateProductReviewsTable()`(迁移464:`CREATE TABLE IF NOT EXISTS product_reviews`)
|
|
|
+ - `private void migrateProductOrderShippedColumns()`(迁移465:`ensureColumn("product_orders","shipped_at",...)` + `ensureColumn("product_orders","receipt_remind_at",...)`,幂等忽略已存在)
|
|
|
+- **同步 schema.sql**:`CREATE TABLE product_orders`(1310 行处)补两列;新增 `CREATE TABLE IF NOT EXISTS product_reviews` 建表语句。
|
|
|
+- **存量数据**:不改历史数据(Q5 口径)。`shipped_at` 为 NULL 的存量 `pending_receipt` 订单,超时任务以 `COALESCE(shipped_at, updated_at)` 作为发货时间兜底,避免历史订单永久卡单;提醒推送仅对 `shipped_at` 非空的订单触发。
|
|
|
+- 验证:`mvn clean compile` + 启动日志确认「迁移464/465」幂等执行。
|
|
|
+
|
|
|
+### 2.4 配置新增(application.yml)
|
|
|
+
|
|
|
+```yaml
|
|
|
+shop:
|
|
|
+ order:
|
|
|
+ payment-timeout-minutes: 30 # 既有
|
|
|
+ receipt-timeout-days: 10 # 新增:发货后超时自动完成天数(P0-B)
|
|
|
+ receipt-remind-days: 9 # 新增:发货后第N天推送收货提醒(P0-B)
|
|
|
+ receipt-auto-complete-enabled: true # 新增:总开关(灰度/回滚用)
|
|
|
+ receipt-remind-template-id: '' # 新增:微信订阅消息模板ID(空=跳过推送,fail-open)
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 3. 接口层
|
|
|
+
|
|
|
+> 规约遵守:统一 `@PostMapping`;`Result<T>`;`@RequestAttribute("userId")/("roles")`;路由先查 `API_REFERENCE.md` 防重复;废弃接口 410 Gone + 注释。
|
|
|
+
|
|
|
+### 3.1 新接口(商品评价域,`ProductReviewController`,前缀 `/api/product/review`)
|
|
|
+
|
|
|
+| # | 接口 | 鉴权 | 入参 | 出参 | 对应需求 | 要点 |
|
|
|
+|---|---|---|---|---|---|---|
|
|
|
+| R1 | `POST /api/product/review/create` | 登录(买家本人) | `{orderId, rating(1-5), reviewText(≤500), images[]≤3}` | `Result<String>` | P0-A | 校验:订单存在、`productType != 'activity'`、`status=completed`、`buyerId==userId`、`confirmTime >= now-90d`、`findByOrderId` 幂等(一单一评);晒图 URL 由前端先走 `/api/media/upload` 获得 |
|
|
|
+| R2 | `POST /api/product/review/detail` | 登录(下单人/商家) | `{orderId}` | `Result<ProductReviewResponse>`(含 `review` / `canReview` / `reviewHint`) | P0-A | 订单详情页「去评价」按钮态 + 已评展示;`review==null` 且可评时 `canReview=true` |
|
|
|
+| R3 | `POST /api/product/review/list` | **公开**(加 PUBLIC_PATHS) | `{productId, page, size}` | `Result<Map>`:`{total, avgRating, records[]}` | P0-A | 商品详情页评价列表(含星级聚合);只读公开,匿名可看 |
|
|
|
+| R4 | `POST /api/product/review/reply` | 登录(商家本人:`product.vendorId==userId`) | `{reviewId, replyText(≤500)}` | `Result<String>` | P0-A/Q1 | 一评一回复覆盖式更新(P2 再议多次);校验该评价对应商品属于当前商家 |
|
|
|
+| R5 | `POST /api/product/review/my` | 登录(买家) | `{page,size}` | `Result<Map>`:`{reviews[], reviewableOrders[], reviewableCount}` | P0-A | 「我的评价」列表 + 「待评价」入口(completed 且 90 天内且未评的普通商品订单) |
|
|
|
+
|
|
|
+### 3.2 既有接口改造
|
|
|
+
|
|
|
+| # | 接口 | 改造 | 对应需求 |
|
|
|
+|---|---|---|---|
|
|
|
+| M1 | `POST /api/admin/product/order/ship` | Controller 增加 `@RequestAttribute("roles")`,透传 `operatorId+operatorRoles` 到 `service.ship()`;service 内校验「`product.vendorId == operatorId` **或** `AdminRoles.hasAnyPlatformRole(roles)`」,否则 `Result.error("无权发货")`;发货成功写 `shipped_at=now`;保留微信 `upload_shipping_info` fail-open 同步 | P0-C / P1-B / P0-B数据源 |
|
|
|
+| M2 | `POST /api/product/order/ship`(用户端) | 标 **410 Gone**(`Result.error` code 410 + 注释说明废弃原因与迁移路径),不删除方法;已核实前端 `api.js` 无任何调用 → 可直接废弃 | P0-C |
|
|
|
+| M3 | `POST /api/product/order/my/counts` | statuses 数组 `{"pending","paid","shipped","completed","refunding"}` → `{"pending","paid","pending_receipt","completed","refunding"}`,**兼容期同时返回 `shipped` 键**(值=pending_receipt 计数),避免旧小程序闪断 | P0-D |
|
|
|
+| M4 | `ProductOrderService.ship()` | 新增重载 `ship(orderNo, shipType, trackingNumber, expressCompany, shippingCost, receiverContact, operatorId, operatorRoles)`;原重载保留给内部/测试(不暴露) | P0-C |
|
|
|
+| M5 | `ProductOrderService.vendorConfirm()` | 不改逻辑;`"pending_shipment"` 容错保留为只读兼容(无写入,历史数据不动) | P0-D |
|
|
|
+
|
|
|
+### 3.3 新增定时任务(P0-B,G4)
|
|
|
+
|
|
|
+- 新文件 `task/OrderReceiptTimeoutTask.java`,仿 `OrderTimeoutCancelTask` 模式:`@Scheduled(fixedRate = 60000)` + `DatabaseInitializer.isMigrationsComplete()` 守卫 + `@Transactional`。
|
|
|
+- 逻辑(幂等,可重复执行):
|
|
|
+ 1. **自动完成**:`status=pending_receipt AND COALESCE(shipped_at, updated_at) < now - receipt-timeout-days` → `status=completed`、`confirmTime=now`、`updatedAt=now`、写 `user_operation_logs`(type=product_order_auto_complete,备注含 orderNo/原因)、SLF4J 日志。
|
|
|
+ 2. **第9天提醒**:`status=pending_receipt AND shipped_at IS NOT NULL AND shipped_at < now - receipt-remind-days AND receipt_remind_at IS NULL` → 经 `WechatService.sendTemplateMessage(buyerOpenid, templateId, {orderNo, productName, hint})` 推送,成功后写 `receipt_remind_at=now`(失败仅日志,不重试风暴,下一轮再试)。
|
|
|
+- 配置:见 2.4(天数/开关/模板ID 全部可配;`receipt-auto-complete-enabled=false` 时仅提醒不自动完成,作为灰度开关)。
|
|
|
+- 选型说明:复用 Spring `@Scheduled` 单机任务框架(与 `OrderTimeoutCancelTask` 一致),不引入 Quartz/xxl-job —— 增量场景订单量可控、表按 status 索引、每分钟扫描成本低;多实例部署风险(重复执行)由「状态幂等 + COALESCE 基准」天然免疫(completed 不再被扫中;提醒有 receipt_remind_at 标记)。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 4. 前端层
|
|
|
+
|
|
|
+### 4.1 api.js 常量位置(`utils/api.js`,约 1773 行 `productOrderReviewUpdate` 附近追加)
|
|
|
+
|
|
|
+```
|
|
|
+productReviewCreate → POST /api/product/review/create
|
|
|
+productReviewDetail → POST /api/product/review/detail
|
|
|
+productReviewList → POST /api/product/review/list
|
|
|
+productReviewReply → (P1 可选,商家端暂不作) POST /api/product/review/reply
|
|
|
+productReviewMy → POST /api/product/review/my
|
|
|
+productOrderShip → POST /api/admin/product/order/ship // 商家端发货(P1-B)
|
|
|
+```
|
|
|
+
|
|
|
+### 4.2 改动页面清单
|
|
|
+
|
|
|
+| 文件 | 改动 | 需求 |
|
|
|
+|---|---|---|
|
|
|
+| `pages/shop/order-detail/order-detail.vue` | ①L111 物流区块条件 `shipped`→`pending_receipt`;②L136 确认收货按钮 `shipped`→`pending_receipt`;③`getDisplayStatusText` 增加 `pending_receipt:'待收货'`(保留 `shipped` 只读兼容);④待收货态新增提示「请及时确认收货,超时将自动完成」;⑤底部操作栏新增「去评价」(`completed && !reviewed && productType!='activity'`,数据来自 R2);⑥新增「咨询客服」按钮(`open-type="contact"`,`session-from="order:{orderNo}"`) | P0-D / P0-A / P1-A / P0-B UX |
|
|
|
+| `pages/shop/order-list/order-list.vue` | ①待收货 Tab `value:'shipped'`→`'pending_receipt'`;②L92 确认收货按钮 `shipped`→`pending_receipt`;③状态文案 map 增加 `pending_receipt`;④新增 `.status-pending_receipt` 样式(对齐 detail 页已有样式);⑤completed 卡片加「去评价」快捷入口;⑥状态计数键对齐(读后端兼容双键) | P0-D / P0-A |
|
|
|
+| `pages/shop/order-review/order-review.vue`(新) | 评价提交页:星级(1-5 单选)、文字 ≤500 字计数、晒图最多 3 张(`uni.chooseImage` + `/api/media/upload`)、提交调 R1;参数 `orderId/orderNo` | P0-A |
|
|
|
+| `pages/shop/my-reviews/my-reviews.vue`(新) | 「我的评价」+「待评价」两个集合;调 R5;待评价项跳转 order-review | P0-A |
|
|
|
+| `pages/discover-detail/product-detail/product-detail.vue` | ①底部操作栏附近「咨询客服」入口(`open-type="contact"`,`session-from="product:{id}"`);②评价浮层/区块:调 R3 展示全局星级均值 + 评价列表(评分/文字/晒图/商家回复) | P1-A / P0-A |
|
|
|
+| `pages/vendor/orders/orders.vue` | ①「待发货」Tab(`value:'paid'` 标签语改「待发货」)+ 卡片上「发货」按钮 → 发货弹窗(物流单号、快递公司,虚拟/自提按 shipType 推导可不填)→ `productOrderShip`;②新增「待收货」Tab(`pending_receipt`);③`statusLabel` 增加 `pending_receipt:'待收货'`/`pending_receipt` 徽标样式 | P1-B |
|
|
|
+| `pages/shop/payment/payment.vue` | 支付成功回调内 `wx.requestSubscribeMessage` 请求「订单发货/收货提醒」订阅授权(模板ID来自后端配置或常量),保证第9天提醒有触达授权 | P0-B 联动 |
|
|
|
+| `pages.json` | 注册 `pages/shop/order-review/order-review`、`pages/shop/my-reviews/my-reviews` | P0-A |
|
|
|
+
|
|
|
+### 4.3 小程序约束(必须遵守)
|
|
|
+
|
|
|
+- 禁止可选链 `?.`(用 `&&`);禁止 CSS Grid(用 flexbox);禁止 `:key` 表达式(用 `getItemKey(item)` 方法);禁止直接 `new Date(string)`(用 `utils/format.js` 的 `parseDate()`);Vue 2 Options API;时间展示按 `parseDate` 格式化 `yyyy-MM-dd HH:mm:ss` / `yyyy-MM-dd`。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 5. 程序调用流(核心时序)
|
|
|
+
|
|
|
+### 5.1 买家评价(P0-A)
|
|
|
+
|
|
|
+```mermaid
|
|
|
+sequenceDiagram
|
|
|
+ participant U as 买家小程序
|
|
|
+ participant OD as order-detail.vue
|
|
|
+ participant RC as ProductReviewController
|
|
|
+ participant RS as ProductReviewServiceImpl
|
|
|
+ participant UM as ProductReviewMapper
|
|
|
+ participant OM as ProductOrderMapper
|
|
|
+
|
|
|
+ U->>OD: onLoad(orderNo)
|
|
|
+ OD->>RC: POST /api/product/review/detail {orderNo}
|
|
|
+ RC->>RS: detail(orderNo, userId)
|
|
|
+ RS->>OM: select order
|
|
|
+ RS->>UM: findByOrderId
|
|
|
+ RS-->>OD: {review, canReview}
|
|
|
+ OD-->>U: completed 且可评 → 显示「去评价」
|
|
|
+
|
|
|
+ U->>OD: 点「去评价」→ order-review 页
|
|
|
+ U->>RC: POST /api/product/review/create {orderId,rating,reviewText,images}
|
|
|
+ RC->>RS: createReview(req, userId)
|
|
|
+ RS->>OM: 校验 status=completed / productType!='activity' / 90天内 / buyer本人
|
|
|
+ RS->>UM: findByOrderId → null 才允许(一单一评)
|
|
|
+ RS->>UM: insert product_reviews
|
|
|
+ RS-->>U: Result.success
|
|
|
+
|
|
|
+ Note over U,RC: 商品详情页匿名读评价
|
|
|
+ U->>RC: POST /api/product/review/list {productId,page,size}
|
|
|
+ RC->>RS: listByProduct(productId) → {total,avgRating,records}
|
|
|
+ RS-->>U: 评价列表 + 商家回复
|
|
|
+```
|
|
|
+
|
|
|
+### 5.2 发货鉴权 + 超时兜底(P0-C / P0-B)
|
|
|
+
|
|
|
+```mermaid
|
|
|
+sequenceDiagram
|
|
|
+ participant V as 商家小程序 orders.vue
|
|
|
+ participant AC as AdminProductOrderController
|
|
|
+ participant PS as ProductOrderService
|
|
|
+ participant PM as ProductOrderMapper
|
|
|
+ participant IT as OrderReceiptTimeoutTask
|
|
|
+ participant WS as WechatService
|
|
|
+
|
|
|
+ V->>AC: POST /api/admin/product/order/ship {orderNo,shipType,trackingNumber,expressCompany}
|
|
|
+ AC->>PS: ship(..., operatorId=userId, operatorRoles=roles)
|
|
|
+ PS->>PM: select order + product
|
|
|
+ alt 非商家本人 且 非平台角色(admin/operator)
|
|
|
+ PS-->>AC: Result.error 无权发货
|
|
|
+ else 通过
|
|
|
+ PS->>PM: status=pending_receipt, logisticsNo/Company, shipped_at=now, updatedAt=now
|
|
|
+ PS->>WS: uploadShippingInfo (fail-open)
|
|
|
+ PS-->>V: Result.success 已发货
|
|
|
+ end
|
|
|
+
|
|
|
+ Note over IT: 每分钟扫描(迁移守卫 + 幂等)
|
|
|
+ IT->>PM: status=pending_receipt AND COALESCE(shipped_at,updated_at) < now-10d
|
|
|
+ IT->>PM: status=completed, confirmTime=now + user_operation_logs 留痕
|
|
|
+ IT->>PM: status=pending_receipt AND shipped_at<now-9d AND receipt_remind_at IS NULL
|
|
|
+ IT->>WS: sendTemplateMessage(buyerOpenid, 收货提醒模板)
|
|
|
+ IT->>PM: receipt_remind_at=now
|
|
|
+```
|
|
|
+
|
|
|
+### 5.3 类图(数据 + 服务)
|
|
|
+
|
|
|
+```mermaid
|
|
|
+classDiagram
|
|
|
+ class ProductOrder {
|
|
|
+ +Long id
|
|
|
+ +String orderNo
|
|
|
+ +Long productId
|
|
|
+ +String productType
|
|
|
+ +Long buyerId
|
|
|
+ +String status
|
|
|
+ +Date shippedAt
|
|
|
+ +Date receiptRemindAt
|
|
|
+ +Date confirmTime
|
|
|
+ }
|
|
|
+ class ProductReview {
|
|
|
+ +Long id
|
|
|
+ +Long orderId
|
|
|
+ +Long productId
|
|
|
+ +Long reviewerId
|
|
|
+ +Integer rating
|
|
|
+ +String reviewText
|
|
|
+ +String images
|
|
|
+ +String replyText
|
|
|
+ +Date repliedAt
|
|
|
+ +Long replyBy
|
|
|
+ +Integer status
|
|
|
+ +Date reviewAt
|
|
|
+ }
|
|
|
+ class ProductReviewMapper {
|
|
|
+ +ProductReview findByOrderId(orderId)
|
|
|
+ +List~ProductReview~ listByProduct(pid, offset, size)
|
|
|
+ +Map statsByProduct(pid)
|
|
|
+ }
|
|
|
+ class ProductReviewService <<interface>> {
|
|
|
+ +String createReview(ProductReviewRequest, Long reviewerId)
|
|
|
+ +ProductReviewResponse detail(Long orderId, Long userId)
|
|
|
+ +Map listByProduct(Long productId, int page, int size)
|
|
|
+ +String reply(Long reviewId, String replyText, Long operatorId)
|
|
|
+ +Map my(Long userId, int page, int size)
|
|
|
+ }
|
|
|
+ class ProductReviewServiceImpl {
|
|
|
+ -ProductReviewMapper reviewMapper
|
|
|
+ -ProductOrderMapper orderMapper
|
|
|
+ -UserMapper userMapper
|
|
|
+ }
|
|
|
+ class ProductReviewController {
|
|
|
+ +Result create(req, userId)
|
|
|
+ +Result detail(params, userId)
|
|
|
+ +Result list(params)
|
|
|
+ +Result reply(params, userId)
|
|
|
+ +Result my(params, userId)
|
|
|
+ }
|
|
|
+ class ProductOrderService {
|
|
|
+ +Result~String~ ship(orderNo, shipType, trackingNumber, expressCompany, shippingCost, receiverContact, operatorId, operatorRoles)
|
|
|
+ +Result confirmReceive(orderNo, userId)
|
|
|
+ +Result~Map~ myOrderCounts(userId)
|
|
|
+ }
|
|
|
+ class AdminProductOrderController {
|
|
|
+ +Result ship(params, userId, roles)
|
|
|
+ }
|
|
|
+ class OrderReceiptTimeoutTask {
|
|
|
+ +void processTimeoutOrders()
|
|
|
+ -void autoComplete()
|
|
|
+ -void sendRemind()
|
|
|
+ -String resolveShipTimeBase(ProductOrder)
|
|
|
+ }
|
|
|
+ class DatabaseInitializer {
|
|
|
+ +void runMigrations()
|
|
|
+ -void migrateProductReviewsTable()
|
|
|
+ -void migrateProductOrderShippedColumns()
|
|
|
+ }
|
|
|
+
|
|
|
+ ProductReview o-- ProductOrder : order_id 唯一
|
|
|
+ ProductReviewMapper --> ProductReview : CRUD
|
|
|
+ ProductReviewServiceImpl --> ProductReviewMapper
|
|
|
+ ProductReviewServiceImpl --> ProductReviewService : implements
|
|
|
+ ProductReviewController --> ProductReviewService
|
|
|
+ ProductOrderService --> ProductOrder : 读改写
|
|
|
+ AdminProductOrderController --> ProductOrderService : 透传 operatorId/roles
|
|
|
+ OrderReceiptTimeoutTask --> ProductOrder : 扫描/置状态
|
|
|
+ DatabaseInitializer --> ProductReview : 建表(迁移464)
|
|
|
+ DatabaseInitializer --> ProductOrder : 加列(迁移465)
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 6. 任务拆分(按模块分组,≤5 个,粒度 ≥3 文件)
|
|
|
+
|
|
|
+| ID | 名称 | 关联需求 | 目标文件(新建★) | 前置 | 改动量 | 验证方式 |
|
|
|
+|---|---|---|---|---|---|---|
|
|
|
+| T01 | 项目基础设施:数据层底座 | G2/G4 | `DatabaseInitializer.java`、`schema.sql`、`ProductOrder.java`、`entity/ProductReview.java★`、`mapper/ProductReviewMapper.java★`、`mapper/ProductReviewMapper.xml★`、`application.yml` | — | M | `mvn clean compile`;启动日志见迁移464/465 幂等;schema.sql 与实体列一致 |
|
|
|
+| T02 | 后端商品评价域(服务+接口) | P0-A(G2) | `service/ProductReviewService.java★`、`service/impl/ProductReviewServiceImpl.java★`(或 service 包内)、`dto/ProductReviewRequest.java★`、`dto/ProductReviewResponse.java★`、`controller/product/ProductReviewController.java★`、`config/JwtInterceptor.java`(R3 公开路径登记) | T01 | M | `mvn compile`;接口冒烟:create 幂等/90天/activity 拒绝、detail canReview、list 匿名、reply 商家校验 |
|
|
|
+| T03 | 后端订单履约修复+超时兜底 | P0-B/P0-C/P0-D/P1-B(后端) | `service/ProductOrderService.java`、`controller/product/ProductOrderController.java`(ship 410)、`controller/admin/AdminProductOrderController.java`(roles 透传)、`task/OrderReceiptTimeoutTask.java★` | T01 | M | `mvn compile`;越权用例:非商家调用 admin ship 被拒、商家/管理员通过;造数验证超时自动 completed + 提醒幂等;my/counts 双键 |
|
|
|
+| T04 | 前端买家侧(状态字典+评价+订阅) | P0-A/P0-D/P0-B(UX) | `utils/api.js`、`pages.json`、`pages/shop/order-detail/order-detail.vue`、`pages/shop/order-list/order-list.vue`、`pages/shop/order-review/order-review.vue★`、`pages/shop/my-reviews/my-reviews.vue★`、`pages/shop/payment/payment.vue` | T02 + T03 | L | 微信开发者工具走查:待收货 Tab/确认收货按钮(shipped 幽灵不再出现)、去评价/晒图/我的评价、支付订阅授权弹窗 |
|
|
|
+| T05 | 前端展示与商家端 | P0-A(展示)/P1-A/P1-B | `pages/discover-detail/product-detail/product-detail.vue`、`pages/vendor/orders/orders.vue`、`pages/shop/order-review/order-review.vue`(评价详情浮层复用能力一并在T05验收) | T03 + T04 | M | 联调:商品详情评价列表+客服入口;商家发货 → 买家待收货态同步可见;微信 upload_shipping_info 不阻塞 |
|
|
|
+
|
|
|
+> T04 依赖 T02(评价接口就绪)+ T03(counts/ship 语义);T05 依赖 T03(发货接口)+ T04(api.js 常量与页面基座)。T02/T03 互不依赖(仅共同依赖 T01),可并行开发。
|
|
|
+
|
|
|
+### 任务依赖图
|
|
|
+
|
|
|
+```mermaid
|
|
|
+graph LR
|
|
|
+ T01[T01 数据层底座] --> T02[T02 后端商品评价域]
|
|
|
+ T01 --> T03[T03 后端履约修复+超时]
|
|
|
+ T02 --> T04[T04 前端买家侧]
|
|
|
+ T03 --> T04
|
|
|
+ T03 --> T05[T05 展示+商家端]
|
|
|
+ T04 --> T05
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 7. 风险与回滚(每项 P0)
|
|
|
+
|
|
|
+| 需求 | 风险 | 灰度/回滚策略 |
|
|
|
+|---|---|---|
|
|
|
+| P0-A 评价 | 新表/新接口与活动评价混淆;晒图 URL 非法 | 完全隔离新表,不动 `ReviewOrderServiceImpl`;R3 仅只读公开;回滚=前端隐藏入口即可,数据表保留无害(可随时 DROP) |
|
|
|
+| P0-B 超时 | 误转历史 long-pending 订单;提醒打扰 | 总开关 `receipt-auto-complete-enabled`(默认 true 生产前可先 false);阈值可配置调大;存量 NULL shipped_at 用 updated_at 兜底仅覆盖超时、不触发提醒;提醒 fail-open + 模板ID 空则跳过;误完成后台可人工改状态(少量) |
|
|
|
+| P0-C ship 越权 | 旧用户端接口被滥用(当前已存在);商家端发货入口未就绪前废弃导致商家无法发货 | 后端 service 校验先行(M1/M2 同批次);商家端发货(T05)紧随其后上线;回滚=保留方法体仅去 410 分支(一行),管理员/商家发货不受影响 |
|
|
|
+| P0-D 状态字典 | 旧版小程序仍读 `shipped` 键/判断 | 后端 counts 兼容期双键(shipped+pending_receipt)双周观察后清除旧键;前端统一 pending_receipt 后回滚即改回两处判断,成本极低 |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 8. 工作量汇总
|
|
|
+
|
|
|
+| 任务 | 改动量 | 预估人日 |
|
|
|
+|---|---|---|
|
|
|
+| T01 数据层底座 | M | 1 |
|
|
|
+| T02 后端商品评价域 | M | 2 |
|
|
|
+| T03 后端履约修复+超时 | M | 2 |
|
|
|
+| T04 前端买家侧 | L | 3 |
|
|
|
+| T05 展示+商家端 | M | 2 |
|
|
|
+| **合计** | **4M + 1L** | **≈ 10 人日**(不含测试/联调缓冲,建议 +30% 缓冲 = 13 人日) |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 9. 共享知识(跨任务约定)
|
|
|
+
|
|
|
+- 响应统一 `Result<T>`(code/message/data);接口一律 `@PostMapping`;分页入参 `page/size`(默认 1/20)。
|
|
|
+- 鉴权:`@RequestAttribute("userId")` 登录上下文;管理端角色用 `@RequestAttribute("roles")` + `AdminRoles.hasAnyPlatformRole()` / `isSupplierOnly()`;商家身份判定统一为 `product.vendorId == userId`。
|
|
|
+- 评价幂等:`product_reviews.uk_order_id` + `findByOrderId` 双重保护;90 天窗口基准为 `confirmTime`(用户确认与超时完成均写该字段)。
|
|
|
+- 时间:后端 ISO 8601 UTC;前端禁用 `new Date(string)`,统一 `parseDate()`;展示 `yyyy-MM-dd HH:mm:ss` / `yyyy-MM-dd`。
|
|
|
+- 数据库迁移:`runMigrations()` 内追加(编号 464/465),`ensureColumn` 幂等,**同步 schema.sql**;迁移未完成时任务须 `isMigrationsComplete()` 守卫跳过。
|
|
|
+- 微信侧全部 fail-open:发货同步、订阅消息推送失败只记日志不阻塞主流程;`wechat.test-mode=true` 时跳过。
|
|
|
+- 废弃接口:标 `410 Gone` + 注释说明,不直接删除;本迭代仅 `POST /api/product/order/ship` 废弃(前端无调用已核实)。
|
|
|
+- 商品评价与活动评价完全隔离:活动评价走 `ReviewController /api/review/*` + `ReviewOrderServiceImpl`(不动);普通商品评价走 `ProductReviewController /api/product/review/*`(新域)。
|
|
|
+- 小程序页面 `pages.json` 注册新页时遵循分包/主包现有约定;路由跳转一律带 `orderNo/orderId/productId` 上下文。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 10. 待确认 / 假设(Anything UNCLEAR)
|
|
|
+
|
|
|
+| 项 | 假设 | 状态 |
|
|
|
+|---|---|---|
|
|
|
+| 客服渠道 | MVP 采用小程序原生客服会话 `<button open-type="contact">`(官方企微/微信客服需在小程序后台绑定);`session-from` 带订单/商品上下文。**主理人已拍板 Q6:原生客服会话满足「可感知上下文」验收**(2026-11-14),无需演进站内 IM(P2) | ✅ 已确认 |
|
|
|
+| 评价晒图上传 | 前端先走 `POST /api/media/upload`(`MediaController`,返回 `MediaRecord` 含 URL)拿图后提交评价;接口返回结构实现时以 `API_REFERENCE.md` 为准 | 实现时核实 |
|
|
|
+| 超时通知载体 | 超时自动完成的可追溯记录以 `user_operation_logs` + `confirmTime` 留痕;「系统通知用户」若已有站内通知表则复用,否则仅日志(验收以字段/日志为准) | P1 补通知体验 |
|
|
|
+| 订阅消息模板ID | `receipt-remind-template-id` 需运营在微信后台配置模板并审核;**主理人已拍板 Q7:模板 ID 走配置项(application.yml),不硬编码**(2026-11-14);未配时跳过推送(fail-open),运营填 ID 后即生效 | ✅ 已确认(入配置) |
|
|
|
+| 商家端发货身份 | 商家小程序登录态为普通 JWT(role=supplier/等),调用 `/api/admin/product/order/ship` 可被 `JwtInterceptor` 放行(token 有效即可,无 `/api/admin` 硬性角色闸),实际身份校验在 service(vendorId/平台角色)完成 | 实现时核实 |
|
|
|
+| 虚拟商品评价 | 虚拟商品(`productType` 非 activity、支付即自动 completed)也可评价(Q1「普通商品」口径含虚拟);如需排除,在 `create` 校验加 `productType != 'virtual'` | 默认含虚拟 |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+*文档结束。关联文件:`docs/superpowers/specs/2026-11-14-product-order-gap-sequence.mermaid`、`docs/superpowers/specs/2026-11-14-product-order-gap-class.mermaid`(时序/类图独立导出)。*
|