Răsfoiți Sursa

docs(spec): 商品订单补缺口增量PRD+可执行架构设计(T01数据层底座已推feature/product-order-gap)

Agnes Agent 1 zi în urmă
părinte
comite
85a64e02b

+ 405 - 0
docs/superpowers/specs/2026-11-14-product-order-gap-arch-design.md

@@ -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`(时序/类图独立导出)。*

+ 171 - 0
docs/superpowers/specs/2026-11-14-product-order-gap-prd.md

@@ -0,0 +1,171 @@
+# CFC 商品订单域「补缺口」增量需求 PRD
+
+> 文档类型:简单增量 PRD(不含竞品分析)
+> 作者:许清楚(产品经理) · 日期:2026-11-14
+> 关联口径:产品主理人确认——「下单后商家发货、用户确认收货完成订单,整个过程可咨询、可评价」
+
+---
+
+## 0. 项目信息
+
+| 项 | 内容 |
+|---|---|
+| Language | 中文 |
+| 现状技术栈 | 后端 `cfc-backend`(Java / Spring Boot,ProductOrder 域);前端 `cfc-frontend`(uni-app 小程序:`pages/shop` 买家侧、`pages/vendor` 商家侧) |
+| Project Name | `product_order_gap_fill` |
+| 文档范围 | 增量补缺口,不改动已完成的主链路(pending→paid→pending_receipt→completed) |
+
+**原始需求复述**:商品订单核心链路已在后端闭环,但按「下单后商家发货、用户确认收货完成订单,整个过程可咨询、可评价」的口径,存在 **3 个主缺口(途咨询/前咨询缺失、完成后普通商品不可评价、商家端小程序无法发货)+ 3 个健壮性问题(pending_receipt 无超时兜底、状态字典幽灵 shipped、ship 越权)**,需需求化并分级排期。
+
+---
+
+## 1. 产品目标
+
+**一句话目标**:把商品订单链路从"能付款、能跑通"补齐为"**可咨询、可评价、可确认、可兜底**"的完整交易闭环,即用户从购买前→发货→收货确认→完成收货评价**全流程可感知、可操作、有兜底**。
+
+**闭环判定口径(DoD 定义)**:
+1. 购买前/订单进行中 → 用户能联系商家或客服(咨询有落点)。
+2. 商家发货后 → 订单状态进入待收货,用户侧展示物流与「确认收货」按钮。
+3. 用户确认收货 or 超时兜底 → 订单进入 completed。
+4. completed 后 → 用户可对普通商品订单评价,评价展示在商品详情页。
+5. 安全边界 → 发货等关键操作具备调用者身份校验,且有超时兜底不卡单。
+
+---
+
+## 2. 角色与用户故事
+
+### 买家(Buyer)
+
+- **B1 售前/售中咨询**:作为买家,我想在下单前或订单进行中联系商家/客服进行咨询,以便下单更放心、订单疑问能及时得到解答。
+  - 验收:商品详情页、订单详情页均有可达「咨询」入口;发送后可收到回复/受理反馈(同一渠道可查看历史)。
+- **B2 收货确认**:作为买家,我想在待收货状态下清楚看到「确认收货」按钮并点击完成订单,以便订单顺利进入完成态。
+  - 验收:后端 ship() 写入 `pending_receipt` 后,订单详情页/订单列表「待收货」态均正确呈现,并展示「确认收货」按钮;点击后订单转 `completed`。
+- **B3 完成后评价**:作为买家,我想在普通商品订单完成后进行评价(星级+文字),并在商品详情页看到自己和他人的评价,以便表达体验、佐证他人购买决策。
+  - 验收:completed 的普通商品订单可提交评价且全站唯一(一单一评);商品详情页可查看评价;评价数据落独立表 `product_reviews`(Q1 已拍板),买家有「我的评价/待评价」入口。
+
+### 商家(Vendor)
+
+- **V1 小程序发货**:作为商家,我想在商家端小程序对待发货订单执行发货并填写物流单号/快递公司,以便无需运营后台替位即可完成「发货→待收货」闭环。
+  - 验收:商家端订单管理可见「待发货」状态集合;选中已支付订单可填物流单号、快递公司并发货;发货成功后订单状态转 `pending_receipt`,买家侧同步可见。
+
+### 运营 / 管理员(Operator / Admin)
+
+- **O1 兜底治理**:作为运营,我想让「用户长期不确认收货」的订单有超时自动完成机制,且发货等敏感操作有权限校验,以便订单不永久卡单、系统不被越权滥用。
+  - 验收:发货后超过 N 天未确认收货的订单由定时任务自动 `completed` 并留痕;`ship` 接口校验调用者身份(越权调用被拒)。
+
+---
+
+## 3. 需求池(P0 / P1 / P2)
+
+> 依赖编号:G1=咨询缺失、G2=普通商品评价缺失、G3=商家端发货缺失、G4=pending_receipt 无超时兜底、G5=状态字典不一致、G6=ship 越权。
+
+### P0 — Must have(补闭环 + 线上缺陷/安全修复)
+
+**P0-A 普通商品订单评价打通**(依赖 G2)
+- 目的:让普通商品订单在完成后可被评价,且评价与活动评价体系完全隔离、互不污染。
+- 功能描述:**主理人 Q1 已拍板=新建独立表**(2026-11-14)——不复用 `review_orders` 活动评价表,新建 `product_reviews` 独立表 + 独立 `ProductReview*` 服务/控制器(`ReviewOrderServiceImpl.createReview` 的 `productType=="activity"` 硬限制**零改动**,活动评价路径照常独占);普通商品订单在 `completed` 后可评价:综合星级(1-5)+文字(≤500字)+晒图(≤3张)、90 天窗口(Q4 默认口径)、支持商家回复;小程序商城线补「去评价」按钮、买家评价列表「我的评价」、以及商品详情页评价展示;`api.js` 补买家评价读/写接口。
+- 验收标准:
+  1. `completed` 的普通商品订单可提交评价且全站唯一(一单一评,`product_reviews.uk_order_id` + `findByOrderId` 幂等);
+  2. 活动订单评价路径不变(`review_orders` + `ReviewController`),普通商品评价落 `product_reviews` 新表,两域不串;
+  3. 商品详情页可展示该商品评价列表(匿名可读 + 星级聚合);买家可在「我的评价/待评价」看到入口。
+- 依赖缺口:G2
+
+**P0-B 待收货超时自动确认/完成**(依赖 G4)
+- 目的:避免因用户不点确认收货导致订单永久停在 `pending_receipt`。
+- 功能描述:新增定时任务(仿 `OrderTimeoutCancelTask` 模式,`cfc-backend/.../task/` 下)扫描 `pending_receipt` 且距发货时间超过设定阈值(见 Q3)的订单,自动转 `completed`,写入操作日志/系统通知用户;阈值走可配置而非硬编码。
+- 验收标准:
+  1. 发货后超过阈值未确认的订单被自动置 `completed`,并产生可追溯记录;
+  2. 阈值可在管理端/配置表调整;任务重复执行不重复完成(幂等)。
+- 依赖缺口:G4
+
+**P0-C ship 接口越权修复**(依赖 G6)
+- 目的:堵住 `POST /api/product/order/ship` 无调用者身份校验的越权洞,任何已登录用户可给任意已支付订单发货。
+- 功能描述:`ProductOrderController.ship()` 补齐调用者上下文(其他方法已有 `@RequestAttribute("userId")`,此处缺失,且第 6 参 `null` 位即为被跳过的身份/操作者参数);service 层校验"调用者必须是该订单所属商家或管理员"(管理员代发策略见 Q5);发货成功后 emit 待收货变更通知,触发订阅消息。
+- 验收标准:
+  1. 非该订单所属商家、非管理员的登录用户调用 `ship` 被拒(403/业务异常);
+  2. 商家本人、管理员代发(按 Q5 策略)可正常发货。
+- 依赖缺口:G6
+
+**P0-D 状态字典口径修复**(依赖 G5)
+- 目的:修复后端写 `pending_receipt`、前端判幽灵 `shipped` 的状态不一致,避免实物订单「确认收货」按钮永不出现(线上缺陷,成本低、直接影响闭环)。
+- 功能描述:清理/统一状态字典,确认 `pending_receipt` 为唯一"待收货"写入值;前端 `order-detail.vue:136`、`order-list.vue:92/133` 的"待收货/已发货"判断改为以 `pending_receipt` 为准(保留对旧数据的兼容读法,见 Q5);同步 `pending_shipment` 处理或废弃决定。
+- 验收标准:
+  1. ship 成功后前端 `completed` 前的待收货态正确显示「确认收货」;
+  2. 状态映射表在前后端一致,无未定义幽灵态被渲染。
+- 依赖缺口:G5(与 B/O1 直接联动)
+
+### P1 — Should have
+
+**P1-A 售前/售中咨询渠道**(依赖 G1)
+- 目的:解决「购买前/订单进行中无法联系商家或客服」的缺口。
+- 功能描述:落地咨询渠道方案(候选对比见 §4);MVP 选择官方企微客服或在 `pages/service-center`、订单详情页接入「咨询」入口,建咨询回路(工单化与否见 Q2),解决现有"请联系客服"无落点问题;保留与订单绑定的咨询上下文(可选)。
+- 验收标准:
+  1. 商品详情/订单详情可达「咨询」入口,咨询有受理/回复回路;
+  2. 入口可感知当前商品/订单上下文(至少订单号)。
+- 依赖缺口:G1
+
+**P1-B 商家端小程序发货入口**(依赖 G3)
+- 目的:让商家可不依赖运营后台,在商家端小程序完成发货。
+- 功能描述:`pages/vendor/orders` 新增「待发货」状态集合 + 发货弹窗(物流单号、快递公司,调 `/api/product/order/ship` 或 `/api/admin/product/order/ship`);api.js 补商家订单发货接口;与 P0-C 的身份校验配套(商家登录态)。
+- 验收标准:
+  1. 商家端待发货 Tab 正确展示 `paid`/实物订单集合;
+  2. 填写物流信息后可发货,成功后订单进入待收货态,买家侧同步可见。
+- 依赖缺口:G3
+
+### P2 — Nice to have
+
+**P2-A 评价晒图与追评**(依赖 G2)
+- 目的:丰富评价表达(待 Q1 决策后立项)。
+- 功能描述:评价晒图已随 P0-A 落表(`product_reviews.images`,≤3 张);本需求聚焦**追评**与评价列表图集展示/筛选。
+- 验收标准:可选功能,评审后补完 DoD。
+- 依赖缺口:G2
+
+**P2-B 订单评价治理**(依赖 G2)
+- 目的:防刷单/差评处理。
+- 功能描述:评价敏感词过滤(可对接现有审核能力 scope)、商家申诉/后台置顶、屏蔽、权重。
+- 验收标准:可选功能。
+- 依赖缺口:G2
+
+---
+
+## 4. 咨询渠道候选方案对比
+
+| 方案 | 一句话利弊 | 适配度 |
+|---|---|---|
+| A. 官方企微客服 | 接入最省(拉起即用、IM 能力现成,无需自建消息系统);弱点是链路断裂在企微,与订单/商品上下文绑定需额外带参,历史记录难枚举在小程序内。 | **推荐 MVP 首选** |
+| B. 站内 IM | 体验最完整、可与订单绑定留痕;弱点是需从零建消息/客服体系(TeacherMessageController 仅规划师域),成本最高、工期最长。 | 后续演进方向 |
+| C. 表单留言 | 实现最轻(一张表 + 列表);弱点是异步、实时性差、易烂尾,仅适合作为 A 的降级兜底。 | 兜底补充 |
+
+**推荐**:MVP 以 **方案 A(官方企微客服)**承接实时咨询,最小成本补上"有落点"红线;若产品坚持与订单强绑定/数据沉淀,再演进到 B。C 可作为 A 不可达时的异步兜底,**不建议单独作为主咨询链路**。是否工单化见 Q2。
+
+---
+
+## 5. UI 设计草案
+
+- **商品详情页**(`pages/discover-detail/product-detail/product-detail.vue`):底部操作栏附近增加「客服/咨询」入口,建评价浮层展示(含星级与文案);无障碍加载评价列表(P0-A)。
+- **订单详情页**(`pages/shop/order-detail/order-detail.vue`):把"已发货"区块与"确认收货"按钮的 `shipped` 判断修正为 `pending_receipt`;增加「咨询」入口;补「去评价」按钮(completed 且未评价时)。
+- **订单列表页**(`pages/shop/order-list/order-list.vue`):待收货 Tab `value` 及继续收货按钮状态判断修正。
+- **商家端订单页**(`pages/vendor/orders/orders.vue`):新增「待发货」Tab 与发货信息弹窗(P1-B)。
+
+---
+
+## 6. 待确认问题(需主理人决策)
+
+> **拍板记录(2026-11-14 主理人)**:Q1 独立表 ✅;Q6(客服 MVP 原生客服会话满足「可感知上下文」验收)✅;Q7(订阅消息模板 ID 入配置项 `shop.order.receipt-remind-template-id`,不硬编码)✅。Q2/Q3/Q4/Q5 按架构设计默认口径执行(Q2 不工单化、Q3 10天+第9天提醒、Q4 90天窗口不追评、Q5 ship 仅商家本人/平台角色 + 存量幽灵态不动数据)。
+> 历史问题仍列于下表供追溯。
+
+1. **评价字段口径(Q1)**:~~普通商品评价是"综合星级 + 文字"即可,还是沿用活动订单的多分项?是否支持晒图?~~ **已拍板:独立表 + 综合星级(1-5) + 文字(≤500) + 晒图(≤3张)**。
+2. **咨询是否需工单化(Q2)**:咨询是否需要与订单绑定、进入工单/待办留痕,还是仅拉起客服会话即可?(影响选 A vs B)→ **默认:不工单化,仅原生客服会话(方案 A)**。
+3. **超时阈值与提醒(Q3)**:`pending_receipt` 自动完成阈值取多少天?自动完成前是否需要给用户发订阅消息提醒?虚拟/实物是否区别对待?→ **默认:10 天自动完成 + 第 9 天订阅消息提醒,统一阈值**。
+4. **评价窗口(Q4)**:完成后多久内可评、是否可追评、商家申诉与后台治理要求?→ **默认:90 天窗口、不追评、商家可回复**。
+5. **ship 身份策略(Q5)**:越权修复后,ship 调用者限定"订单所属商家本人",还是允许管理员/运营代发?前端"幽灵 shipped / pending_shipment"存量数据如何兼容?→ **默认:商家本人或平台角色(管理员可代发),存量幽灵态不动数据**。
+
+---
+
+## 附录:已抽查佐证证据快照
+
+- `ReviewOrderServiceImpl.java:36`:`if (!"activity".equals(order.getProductType())) throw "Only activity orders are reviewable"` → 普通商品订单不可评价(G2)。
+- `ProductOrderController.java:110-117`:`@PostMapping("/ship")` 方法签名仅从 params 取 orderNo/shipType/trackingNumber/expressCompany/receiverContact,无 `@RequestAttribute("userId")`,第 6 参为 `null` → 越权洞(G6);对比 `reviewUpdate`:106 行有 `@RequestAttribute("userId")`。
+- 订单列表/详情页幽灵 `shipped`:`order-list.vue:92/133`、`order-detail.vue:136/137/263`(G5)。
+- 任务目录仅有 `OrderTimeoutCancelTask.java`(无自动确认收货任务)(G4)。
+- `POST /api/admin/product/order/ship` 已存在,缺商家小程序前端入口(G3);后端无商品域 consult/客服接口(G1)。