Explorar o código

Merge remote-tracking branch 'origin/cfclub' into task/S-cfc-277

Sisyphus Agent hai 1 día
pai
achega
4411c85cf

+ 103 - 0
cfc-backend/src/main/java/com/etotem/cfc/config/DatabaseInitializer.java

@@ -3558,6 +3558,11 @@ insertSysConfigSeed("gift_membership_pay_price", "198000", "送会员商品达
 
         // 迁移480: 真人管家服务质检与满意度链路三表(butler.quality.qa · SC-H-07 质检→满意度回访→回流改进)
         createButlerQualityTables();
+
+        // 迁移481: 创建真人管家升级工单表 butler_escalation_orders
+        //(能力键 butler.escalation.handle · SC-H-01 接收 AI 升级并人工介入 / SC-H-04 升级与应急处理:
+        // 仅本家庭可见,高风险优先排序,乐观锁认领,SLA 超时升级,联系/复盘留痕)
+        createButlerEscalationOrderTable();
     }
 
     /**
@@ -3748,6 +3753,53 @@ insertSysConfigSeed("gift_membership_pay_price", "198000", "送会员商品达
         } catch (Exception e) {
             log.warn("迁移480: butler_performance 创建失败: {}", e.getMessage());
         }
+
+        // 迁移481: 创建商品评价表 product_reviews(P0-A 普通商品评价域,独立于活动评价 review_orders)
+        migrateProductReviewsTable();
+
+        // 迁移482: product_orders 补收货超时兜底列(P0-B 待收货超时自动完成/第9天收货提醒)
+        migrateProductOrderShippedColumns();
+    }
+
+    /**
+     * 迁移481: 创建真人管家升级工单表(SC-H-01/SC-H-04,能力键 butler.escalation.handle)。
+     *
+     * <p>承载「接收 AI 升级并人工介入」与「升级与应急处理」的工单治理:仅本家庭可见(family_id 隔离)、
+     * 风险等级优先(HIGH/MEDIUM/LOW)、乐观锁认领(CAS on status)、SLA 超时升级、联系/复盘留痕。
+     * 幂等:CREATE TABLE IF NOT EXISTS。</p>
+     */
+    private void createButlerEscalationOrderTable() {
+        try {
+            jdbcTemplate.execute("CREATE TABLE IF NOT EXISTS butler_escalation_orders ("
+                    + "id BIGINT AUTO_INCREMENT PRIMARY KEY, "
+                    + "family_id BIGINT NOT NULL COMMENT '工单所属家庭(仅本家庭授权,越界 403)', "
+                    + "butler_user_id BIGINT NULL COMMENT '认领管家用户 ID(乐观锁:同一工单只允许一人认领)', "
+                    + "source_type VARCHAR(32) DEFAULT 'AI_ESCALATION' COMMENT '工单来源: AI升级/异常预警/投诉', "
+                    + "risk_level VARCHAR(16) DEFAULT 'MEDIUM' COMMENT '风险等级: HIGH/MEDIUM/LOW(高风险优先排序)', "
+                    + "status VARCHAR(16) DEFAULT 'PENDING' COMMENT '状态: PENDING/PROCESSING/CLOSED/WITHDRAWN/ESCALATED', "
+                    + "parent_demand TEXT NULL COMMENT '家长诉求上下文', "
+                    + "ai_conclusion TEXT NULL COMMENT 'AI 已给结论上下文', "
+                    + "teacher_id BIGINT NULL COMMENT '转交规划师用户 ID(SC-H-01 转规划师)', "
+                    + "escalation_level INT DEFAULT 1 COMMENT 'SOP 分级: 1=一级自行处置/2=二级升级(SC-H-04)', "
+                    + "target_role VARCHAR(32) NULL COMMENT '二级升级目标角色: 运营/医疗顾问', "
+                    + "contact_type VARCHAR(16) NULL COMMENT '最近联系动作类型: CALL/MESSAGE/IN_APP(留痕)', "
+                    + "contact_content TEXT NULL COMMENT '最近联系动作内容(留痕)', "
+                    + "resolution TEXT NULL COMMENT '人工结论(闭环留痕)', "
+                    + "review_conclusion TEXT NULL COMMENT '复盘结论(SC-H-04 复盘)', "
+                    + "duration_minutes INT NULL COMMENT '复盘处置时长(分钟)', "
+                    + "sla_deadline DATETIME NULL COMMENT 'SLA 超时时间(超时未处理触发升级提醒 TC-H-01-E)', "
+                    + "claimed_at DATETIME NULL COMMENT '认领时间', "
+                    + "closed_at DATETIME NULL COMMENT '闭环时间', "
+                    + "created_at DATETIME DEFAULT CURRENT_TIMESTAMP, "
+                    + "updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, "
+                    + "INDEX idx_family_status (family_id, status), "
+                    + "INDEX idx_butler_status (butler_user_id, status), "
+                    + "INDEX idx_status_sla (status, sla_deadline)"
+                    + ") ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='真人管家升级工单(SC-H-01/SC-H-04)'");
+            log.info("迁移481: butler_escalation_orders 表已就绪");
+        } catch (Exception e) {
+            log.warn("迁移481: butler_escalation_orders 创建失败: {}", e.getMessage());
+        }
     }
 
     /** 迁移473(FamilyWorkbench): tasks 加家庭+时间复合索引,支撑工作台按家庭聚合计数与近 30 天逐日趋势。 */
@@ -16147,4 +16199,55 @@ log.info("迁移298: 已为无 openid 的 child 账号补齐 family_members 记
                 "VARCHAR(30) DEFAULT NULL COMMENT '测评类型码(类型载体:DAN 8 类 mind/wisdom/cognition/learning/behavior/career/campus/adolescent)'");
         log.info("迁移479: assessment_materials.dimension 就绪(assessment.type.browse / SC-P-31)");
     }
+
+    /**
+     * 迁移481: 创建商品评价表 product_reviews(P0-A 普通商品评价域,独立于活动评价 review_orders)。
+     *
+     * <p>一单一评({@code uk_order_id} 唯一键);商品详情页按 {@code product_id} 聚合列表;
+     * 评价人列表索引 {@code reviewer_id}。与活动评价 {@code review_orders} 通过 {@code order_id}
+     * 完全隔离,两域互不干扰(Q1 口径:新建商品评价域,不复用活动评价表)。</p>
+     */
+    private void migrateProductReviewsTable() {
+        try {
+            jdbcTemplate.execute("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)'");
+            log.info("迁移481: product_reviews 表已就绪");
+        } catch (Exception e) {
+            log.warn("迁移481: product_reviews 表创建失败: {}", e.getMessage());
+        }
+    }
+
+    /**
+     * 迁移482: product_orders 补收货超时兜底列(P0-B)。
+     *
+     * <p>{@code shipped_at}=发货时间(ship() 落库写,作为超时自动完成/收货提醒的基准时间);
+     * {@code receipt_remind_at}=收货提醒推送时间(第9天推送成功后写,幂等防重复推送)。
+     * 使用 {@code ensureColumn} 幂等:列已存在时自动跳过。</p>
+     */
+    private void migrateProductOrderShippedColumns() {
+        try {
+            ensureColumn("product_orders", "shipped_at", "DATETIME NULL COMMENT '发货时间'");
+            ensureColumn("product_orders", "receipt_remind_at", "DATETIME NULL COMMENT '收货提醒推送时间'");
+            log.info("迁移482: product_orders.shipped_at / receipt_remind_at 列已就绪");
+        } catch (Exception e) {
+            log.warn("迁移482: product_orders 收货超时兜底列失败(忽略): {}", e.getMessage());
+        }
+    }
 }

+ 68 - 11
cfc-backend/src/main/java/com/etotem/cfc/controller/admin/AdminButlerController.java

@@ -4,6 +4,7 @@ import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
 import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
 import com.etotem.cfc.common.Result;
 import com.etotem.cfc.entity.ButlerCommissionSettlement;
+import com.etotem.cfc.entity.ButlerEscalationOrder;
 import com.etotem.cfc.entity.ButlerProfile;
 import com.etotem.cfc.entity.ButlerServiceRecord;
 import com.etotem.cfc.entity.User;
@@ -11,6 +12,7 @@ import com.etotem.cfc.mapper.ButlerCommissionSettlementMapper;
 import com.etotem.cfc.mapper.ButlerProfileMapper;
 import com.etotem.cfc.mapper.ButlerServiceRecordMapper;
 import com.etotem.cfc.mapper.UserMapper;
+import com.etotem.cfc.service.ButlerEscalationService;
 import com.etotem.cfc.service.ButlerService;
 import org.springframework.web.bind.annotation.*;
 
@@ -23,9 +25,11 @@ import com.etotem.cfc.util.SortUtil;
 import com.etotem.cfc.util.ParamUtils;
 
 @RestController
-@RequestMapping("/api/admin/butler")
 public class AdminButlerController {
 
+    @Resource
+    private ButlerEscalationService butlerEscalationService;
+
     @Resource
     private ButlerService butlerService;
 
@@ -45,7 +49,7 @@ public class AdminButlerController {
      * 管家申请来源为 users.butler_status(小程序服务角色申请/管家申请写入)。
      * 返回用户维度的管家申请列表,供审核中心管家审核 Tab 使用。
      */
-    @PostMapping("/user-list")
+    @PostMapping("/api/admin/butler/user-list")
     public Result<Map<String, Object>> userList(@RequestBody Map<String, Object> params,
                                                 @RequestAttribute("role") String role) {
         if (!"admin".equals(role) && !"finance".equals(role)) {
@@ -82,7 +86,7 @@ public class AdminButlerController {
         return Result.success(data);
     }
 
-    @PostMapping("/list")
+    @PostMapping("/api/admin/butler/list")
     public Result<Map<String, Object>> list(@RequestBody Map<String, Object> params,
                                              @RequestAttribute("role") String role) {
         if (!"admin".equals(role) && !"finance".equals(role)) {
@@ -116,7 +120,7 @@ public class AdminButlerController {
         return Result.success(data);
     }
 
-    @PostMapping("/review")
+    @PostMapping("/api/admin/butler/review")
     public Result<String> review(@RequestBody Map<String, Object> params,
                                   @RequestAttribute("role") String role) {
         if (!"admin".equals(role) && !"finance".equals(role)) {
@@ -141,7 +145,7 @@ public class AdminButlerController {
         }
     }
 
-    @PostMapping("/assign-member")
+    @PostMapping("/api/admin/butler/assign-member")
     public Result<String> assignMember(@RequestBody Map<String, Object> params,
                                         @RequestAttribute("role") String role) {
         if (!"admin".equals(role) && !"finance".equals(role)) {
@@ -158,7 +162,7 @@ public class AdminButlerController {
         return butlerService.assignMemberToButler(profileId, memberId);
     }
 
-    @PostMapping("/service-records")
+    @PostMapping("/api/admin/butler/service-records")
     public Result<Map<String, Object>> serviceRecords(@RequestBody Map<String, Object> params,
                                                        @RequestAttribute("role") String role) {
         if (!"admin".equals(role) && !"finance".equals(role)) {
@@ -188,7 +192,7 @@ public class AdminButlerController {
         return Result.success(data);
     }
 
-    @PostMapping("/settlements")
+    @PostMapping("/api/admin/butler/settlements")
     public Result<Map<String, Object>> settlements(@RequestBody Map<String, Object> params,
                                                     @RequestAttribute("role") String role) {
         if (!"admin".equals(role) && !"finance".equals(role)) {
@@ -218,7 +222,7 @@ public class AdminButlerController {
         return Result.success(data);
     }
 
-    @PostMapping("/assignments")
+    @PostMapping("/api/admin/butler/assignments")
     public Result<Map<String, Object>> assignments(@RequestBody Map<String, Object> params,
                                                     @RequestAttribute("role") String role) {
         if (!"admin".equals(role) && !"finance".equals(role)) {
@@ -229,7 +233,7 @@ public class AdminButlerController {
         return butlerService.listAssignments(pageNum, pageSize);
     }
 
-    @PostMapping("/unassign")
+    @PostMapping("/api/admin/butler/unassign")
     public Result<Void> unassign(@RequestBody Map<String, Object> params,
                                   @RequestAttribute("role") String role) {
         if (!"admin".equals(role) && !"finance".equals(role)) {
@@ -241,7 +245,7 @@ public class AdminButlerController {
         return butlerService.unassign(Long.valueOf(params.get("assignmentId").toString()));
     }
 
-    @PostMapping("/toggle-accepting")
+    @PostMapping("/api/admin/butler/toggle-accepting")
     public Result<Void> toggleAccepting(@RequestBody Map<String, Object> params,
                                          @RequestAttribute("role") String role) {
         if (!"admin".equals(role) && !"finance".equals(role)) {
@@ -254,4 +258,57 @@ public class AdminButlerController {
                 Long.valueOf(params.get("butlerUserId").toString()),
                 Integer.valueOf(params.get("accepting").toString()));
     }
-}
+
+    // ==================== 升级工单治理(能力键 butler.escalation.handle · SC-H-04 管理端) ====================
+
+    /**
+     * 按 SOP 分级:一级自行处置 / 二级升级至运营、医疗顾问(SC-H-04)。
+     * POST /api/admin/butler/escalation/grade
+     */
+    @PostMapping("/api/admin/butler/escalation/grade")
+    public Result<String> escalationGrade(@RequestBody Map<String, Object> params,
+                                          @RequestAttribute("role") String role) {
+        if (!"admin".equals(role) && !"finance".equals(role)) {
+            return Result.error("权限不足");
+        }
+        Long workorderId = ParamUtils.getLong(params.get("workorderId"));
+        Integer escalationLevel = params.get("escalationLevel") != null
+                ? Integer.valueOf(params.get("escalationLevel").toString()) : null;
+        Long userId = ParamUtils.getLong(params.get("userId"));
+        return butlerEscalationService.grade(workorderId, escalationLevel, userId);
+    }
+
+    /**
+     * 二级升级至运营/医疗顾问,并携带完整上下文(不丢上下文,SC-H-04)。
+     * POST /api/admin/butler/escalation/escalate
+     */
+    @PostMapping("/api/admin/butler/escalation/escalate")
+    public Result<ButlerEscalationOrder> escalationEscalate(@RequestBody Map<String, Object> params,
+                                                            @RequestAttribute("role") String role) {
+        if (!"admin".equals(role) && !"finance".equals(role)) {
+            return Result.error("权限不足");
+        }
+        Long workorderId = ParamUtils.getLong(params.get("workorderId"));
+        String targetRole = (String) params.get("targetRole");
+        Long userId = ParamUtils.getLong(params.get("userId"));
+        return butlerEscalationService.escalateLevel2(workorderId, targetRole, userId);
+    }
+
+    /**
+     * 生成复盘记录(含处置时长与结论,SC-H-04 复盘)。
+     * POST /api/admin/butler/escalation/review
+     */
+    @PostMapping("/api/admin/butler/escalation/review")
+    public Result<String> escalationReview(@RequestBody Map<String, Object> params,
+                                           @RequestAttribute("role") String role) {
+        if (!"admin".equals(role) && !"finance".equals(role)) {
+            return Result.error("权限不足");
+        }
+        Long workorderId = ParamUtils.getLong(params.get("workorderId"));
+        Integer durationMinutes = params.get("durationMinutes") != null
+                ? Integer.valueOf(params.get("durationMinutes").toString()) : null;
+        String conclusion = (String) params.get("conclusion");
+        Long userId = ParamUtils.getLong(params.get("userId"));
+        return butlerEscalationService.recordReview(workorderId, durationMinutes, conclusion, userId);
+    }
+}

+ 97 - 13
cfc-backend/src/main/java/com/etotem/cfc/controller/butler/ButlerController.java

@@ -3,28 +3,31 @@ package com.etotem.cfc.controller.butler;
 import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
 import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
 import com.etotem.cfc.common.Result;
+import com.etotem.cfc.entity.ButlerEscalationOrder;
 import com.etotem.cfc.entity.ButlerResourceMatchResult;
 import com.etotem.cfc.entity.User;
 import com.etotem.cfc.mapper.ButlerResourceMatchResultMapper;
 import com.etotem.cfc.mapper.UserMapper;
+import com.etotem.cfc.service.ButlerEscalationService;
 import com.etotem.cfc.service.ButlerResourceMatchService;
 import com.etotem.cfc.service.ButlerService;
 import com.etotem.cfc.service.RealNameBackfillService;
+import com.etotem.cfc.util.ParamUtils;
 import io.swagger.v3.oas.annotations.Operation;
 import org.springframework.web.bind.annotation.*;
 
 import javax.annotation.Resource;
-import javax.servlet.http.HttpServletRequest;
-import java.util.Date;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 import com.etotem.cfc.util.SortUtil;
 
 @RestController("butlerController")
-@RequestMapping("/api/butler")
 public class ButlerController {
 
+    @Resource
+    private ButlerEscalationService butlerEscalationService;
+
     @Resource
     private ButlerService butlerService;
 
@@ -44,7 +47,7 @@ public class ButlerController {
      * 申请成为管家
      * POST /api/butler/apply
      */
-    @PostMapping("/apply")
+    @PostMapping("/api/butler/apply")
     public Result<String> apply(@RequestBody Map<String, Object> params,
                                  @RequestAttribute("userId") Long userId) {
         String tier = (String) params.get("tier");
@@ -62,7 +65,7 @@ public class ButlerController {
      * 获取管家档案
      * POST /api/butler/profile
      */
-    @PostMapping("/profile")
+    @PostMapping("/api/butler/profile")
     public Result<Map<String, Object>> getProfile(@RequestAttribute("userId") Long userId) {
         return butlerService.getProfile(userId);
     }
@@ -71,7 +74,7 @@ public class ButlerController {
      * 更新管家档案
      * POST /api/butler/update-profile
      */
-    @PostMapping("/update-profile")
+    @PostMapping("/api/butler/update-profile")
     public Result<String> updateProfile(@RequestBody Map<String, Object> params,
                                          @RequestAttribute("userId") Long userId) {
         return butlerService.updateProfile(userId, params);
@@ -81,7 +84,7 @@ public class ButlerController {
      * 获取分配的家庭成员列表
      * POST /api/butler/members
      */
-    @PostMapping("/members")
+    @PostMapping("/api/butler/members")
     public Result<Map<String, Object>> getMembers(@RequestBody Map<String, Object> params,
                                                    @RequestAttribute("userId") Long userId) {
         int page = params.get("page") != null ? ((Number) params.get("page")).intValue() : 1;
@@ -108,7 +111,7 @@ public class ButlerController {
      * 家庭端查看匹配结果(AC2:家长端可查看并选择匹配结果)
      * POST /api/butler/resource-match/list
      */
-    @PostMapping("/resource-match/list")
+    @PostMapping("/api/butler/resource-match/list")
     public Result<List<ButlerResourceMatchResult>> listResourceMatch(@RequestBody Map<String, Object> params,
                                                                      @RequestAttribute("userId") Long userId) {
         Long memberId = params.get("memberId") != null ? Long.valueOf(params.get("memberId").toString()) : null;
@@ -127,7 +130,7 @@ public class ButlerController {
      * 匹配入口(按家长需求与孩子画像匹配资源,SC-H-05 正常流步骤1)
      * POST /api/butler/resource-match/generate
      */
-    @PostMapping("/resource-match/generate")
+    @PostMapping("/api/butler/resource-match/generate")
     public Result<List<ButlerResourceMatchResult>> generateResourceMatch(@RequestBody Map<String, Object> params,
                                                                          @RequestAttribute("userId") Long userId) {
         Long familyId = params.get("familyId") != null ? Long.valueOf(params.get("familyId").toString()) : null;
@@ -141,7 +144,7 @@ public class ButlerController {
      * 协助预约/报名(AC3:名额实时校验联动,满员提示「名额已满」)
      * POST /api/butler/resource-match/book
      */
-    @PostMapping("/resource-match/book")
+    @PostMapping("/api/butler/resource-match/book")
     public Result<Map<String, Object>> bookResourceMatch(@RequestBody Map<String, Object> params,
                                                          @RequestAttribute("userId") Long userId) {
         Long memberId = params.get("memberId") != null ? Long.valueOf(params.get("memberId").toString()) : null;
@@ -153,7 +156,7 @@ public class ButlerController {
      * 回访沉淀偏好(AC4:参与后回访记录写入家长档案)
      * POST /api/butler/resource-match/follow-up
      */
-    @PostMapping("/resource-match/follow-up")
+    @PostMapping("/api/butler/resource-match/follow-up")
     public Result<String> followUpResourceMatch(@RequestBody Map<String, Object> params,
                                                 @RequestAttribute("userId") Long userId) {
         Long familyId = params.get("familyId") != null ? Long.valueOf(params.get("familyId").toString()) : null;
@@ -167,7 +170,7 @@ public class ButlerController {
      */
     @Deprecated
     @Operation(summary = "获取服务记录", deprecated = true)
-    @PostMapping("/service-records")
+    @PostMapping("/api/butler/service-records")
     public Result<Map<String, Object>> getServiceRecords(@RequestBody Map<String, Object> params,
     @RequestAttribute("userId") Long userId) {
     return Result.error(410, "该接口已废弃,无替代方案");
@@ -179,9 +182,90 @@ public class ButlerController {
      */
     @Deprecated
     @Operation(summary = "获取佣金记录", deprecated = true)
-    @PostMapping("/commissions")
+    @PostMapping("/api/butler/commissions")
     public Result<Map<String, Object>> getCommissions(@RequestBody Map<String, Object> params,
     @RequestAttribute("userId") Long userId) {
     return Result.error(410, "该接口已废弃,无替代方案");
     }
+
+    // ==================== 升级工单治理(能力键 butler.escalation.handle · SC-H-01 / SC-H-04) ====================
+
+    /**
+     * 工作台:按风险等级优先返回待认领/处理中/已升级工单(SC-H-01 工作台)。
+     * POST /api/butler/escalation/list
+     */
+    @PostMapping("/api/butler/escalation/list")
+    public Result<List<ButlerEscalationOrder>> escalationList(@RequestAttribute("userId") Long userId) {
+        return butlerEscalationService.list(userId);
+    }
+
+    /**
+     * 工单详情,仅本家庭可见(越界 403)。
+     * POST /api/butler/escalation/detail
+     */
+    @PostMapping("/api/butler/escalation/detail")
+    public Result<ButlerEscalationOrder> escalationDetail(@RequestBody Map<String, Object> params,
+                                                          @RequestAttribute("userId") Long userId) {
+        Long workorderId = ParamUtils.getLong(params.get("workorderId"));
+        return butlerEscalationService.detail(workorderId, userId);
+    }
+
+    /**
+     * 乐观锁认领:同一工单只允许一人认领,他人提示「已被认领」。
+     * POST /api/butler/escalation/claim
+     */
+    @PostMapping("/api/butler/escalation/claim")
+    public Result<String> escalationClaim(@RequestBody Map<String, Object> params,
+                                          @RequestAttribute("userId") Long userId) {
+        Long workorderId = ParamUtils.getLong(params.get("workorderId"));
+        return butlerEscalationService.claim(workorderId, userId);
+    }
+
+    /**
+     * 记录联系动作留痕(电话/消息/站内),TC-H-01 步骤 3。
+     * POST /api/butler/escalation/log-contact
+     */
+    @PostMapping("/api/butler/escalation/log-contact")
+    public Result<String> escalationLogContact(@RequestBody Map<String, Object> params,
+                                               @RequestAttribute("userId") Long userId) {
+        Long workorderId = ParamUtils.getLong(params.get("workorderId"));
+        String contactType = (String) params.get("contactType");
+        String content = (String) params.get("content");
+        return butlerEscalationService.logContact(workorderId, contactType, content, userId);
+    }
+
+    /**
+     * 人工处置结论并闭环(PENDING→PROCESSING→CLOSED 留痕),TC-H-01 步骤 4/5。
+     * POST /api/butler/escalation/close
+     */
+    @PostMapping("/api/butler/escalation/close")
+    public Result<String> escalationClose(@RequestBody Map<String, Object> params,
+                                          @RequestAttribute("userId") Long userId) {
+        Long workorderId = ParamUtils.getLong(params.get("workorderId"));
+        String resolution = (String) params.get("resolution");
+        return butlerEscalationService.resolve(workorderId, resolution, userId);
+    }
+
+    /**
+     * 转交规划师(SC-H-01 转规划师)。
+     * POST /api/butler/escalation/transfer
+     */
+    @PostMapping("/api/butler/escalation/transfer")
+    public Result<String> escalationTransfer(@RequestBody Map<String, Object> params,
+                                             @RequestAttribute("userId") Long userId) {
+        Long workorderId = ParamUtils.getLong(params.get("workorderId"));
+        Long teacherId = ParamUtils.getLong(params.get("teacherId"));
+        return butlerEscalationService.transferToTeacher(workorderId, teacherId, userId);
+    }
+
+    /**
+     * 撤回工单(SC-H-04 已撤回状态),仅本家庭工单可撤回。
+     * POST /api/butler/escalation/withdraw
+     */
+    @PostMapping("/api/butler/escalation/withdraw")
+    public Result<String> escalationWithdraw(@RequestBody Map<String, Object> params,
+                                             @RequestAttribute("userId") Long userId) {
+        Long workorderId = ParamUtils.getLong(params.get("workorderId"));
+        return butlerEscalationService.withdraw(workorderId, userId);
+    }
 }

+ 106 - 0
cfc-backend/src/main/java/com/etotem/cfc/entity/ButlerEscalationOrder.java

@@ -0,0 +1,106 @@
+package com.etotem.cfc.entity;
+
+import com.baomidou.mybatisplus.annotation.IdType;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import lombok.Data;
+
+import java.io.Serializable;
+import java.util.Date;
+
+/**
+ * 真人管家 · AI 升级工单(能力键 {@code butler.escalation.handle},SC-H-01 / SC-H-04)。
+ *
+ * <p>承载「接收 AI 升级并人工介入」与「升级与应急处理」两条场景的工单治理上下文:
+ * 家长诉求 / AI 已给结论 / 风险等级三项上下文完整携带,且仅本家庭可见(familyId 隔离)。</p>
+ *
+ * <p>状态流转({@code status}):{@code PENDING} 待处理 → {@code PROCESSING} 处理中 →
+ * {@code CLOSED} 已闭环 / {@code WITHDRAWN} 已撤回 / {@code ESCALATED} 已升级。</p>
+ *
+ * <p>风险等级({@code riskLevel}):{@code HIGH} 高风险优先 / {@code MEDIUM} / {@code LOW}。</p>
+ */
+@Data
+@TableName("butler_escalation_orders")
+public class ButlerEscalationOrder implements Serializable {
+
+    private static final long serialVersionUID = 1L;
+
+    /** 工单状态:待处理 */
+    public static final String STATUS_PENDING = "PENDING";
+    /** 工单状态:处理中 */
+    public static final String STATUS_PROCESSING = "PROCESSING";
+    /** 工单状态:已闭环 */
+    public static final String STATUS_CLOSED = "CLOSED";
+    /** 工单状态:已撤回 */
+    public static final String STATUS_WITHDRAWN = "WITHDRAWN";
+    /** 工单状态:已升级 */
+    public static final String STATUS_ESCALATED = "ESCALATED";
+
+    /** 风险等级:高风险 */
+    public static final String RISK_HIGH = "HIGH";
+    /** 风险等级:中风险 */
+    public static final String RISK_MEDIUM = "MEDIUM";
+    /** 风险等级:低风险 */
+    public static final String RISK_LOW = "LOW";
+
+    @TableId(type = IdType.AUTO)
+    private Long id;
+
+    /** 工单所属家庭(仅本家庭授权,越界 403)。 */
+    private Long familyId;
+
+    /** 认领管家用户 ID(乐观锁:同一工单只允许一人认领)。 */
+    private Long butlerUserId;
+
+    /** 工单来源:AI升级 / 异常预警 / 投诉(上下文字段,非枚举约束)。 */
+    private String sourceType;
+
+    /** 风险等级:HIGH/MEDIUM/LOW(高风险优先排序)。 */
+    private String riskLevel;
+
+    /** 工单状态:PENDING/PROCESSING/CLOSED/WITHDRAWN/ESCALATED。 */
+    private String status;
+
+    /** 家长诉求上下文。 */
+    private String parentDemand;
+
+    /** AI 已给结论上下文。 */
+    private String aiConclusion;
+
+    /** 转交规划师用户 ID(SC-H-01 转规划师)。 */
+    private Long teacherId;
+
+    /** SOP 分级:1=一级自行处置 / 2=二级升级(SC-H-04)。 */
+    private Integer escalationLevel;
+
+    /** 二级升级目标角色:运营 / 医疗顾问(SC-H-04,携带完整上下文)。 */
+    private String targetRole;
+
+    /** 最近联系动作类型:CALL/MESSAGE/IN_APP。 */
+    private String contactType;
+
+    /** 最近联系动作内容(留痕)。 */
+    private String contactContent;
+
+    /** 人工结论(处置结论,闭环留痕)。 */
+    private String resolution;
+
+    /** 复盘结论(SC-H-04 复盘)。 */
+    private String reviewConclusion;
+
+    /** 复盘处置时长(分钟)。 */
+    private Integer durationMinutes;
+
+    /** SLA 超时时间:超过未处理触发升级提醒(TC-H-01-E)。 */
+    private Date slaDeadline;
+
+    /** 认领时间。 */
+    private Date claimedAt;
+
+    /** 闭环时间。 */
+    private Date closedAt;
+
+    private Date createdAt;
+
+    private Date updatedAt;
+}

+ 4 - 0
cfc-backend/src/main/java/com/etotem/cfc/entity/ProductOrder.java

@@ -81,6 +81,8 @@ public class ProductOrder implements Serializable {
     private String fulfillStatus;             // 履约状态: pending/confirmed_by_vendor/received_by_user
     private Date fulfillConfirmedAt;          // 供应商确认时间
     private Date receivedAt;                   // 用户确认收货时间
+    private Date shippedAt;                    // 发货时间(超时自动完成/收货提醒的基准时间,P0-B)
+    private Date receiptRemindAt;              // 收货提醒推送时间(第9天推送成功后写,幂等防重复,P0-B)
 
     private Date createdAt;
     private Date updatedAt;
@@ -124,6 +126,8 @@ public class ProductOrder implements Serializable {
     public void setFulfillStatus(String fulfillStatus) { this.fulfillStatus = fulfillStatus; }
     public void setFulfillConfirmedAt(Date fulfillConfirmedAt) { this.fulfillConfirmedAt = fulfillConfirmedAt; }
     public void setReceivedAt(Date receivedAt) { this.receivedAt = receivedAt; }
+    public void setShippedAt(Date shippedAt) { this.shippedAt = shippedAt; }
+    public void setReceiptRemindAt(Date receiptRemindAt) { this.receiptRemindAt = receiptRemindAt; }
     public Date getPaidAt() { return paidAt; }
     public Date getCreatedAt() { return createdAt; }
 }

+ 31 - 0
cfc-backend/src/main/java/com/etotem/cfc/entity/ProductReview.java

@@ -0,0 +1,31 @@
+package com.etotem.cfc.entity;
+
+import com.baomidou.mybatisplus.annotation.IdType;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import lombok.Data;
+
+import java.io.Serializable;
+import java.util.Date;
+
+@Data
+@TableName("product_reviews")
+public class ProductReview implements Serializable {
+
+    @TableId(type = IdType.AUTO)
+    private Long id;
+
+    private Long orderId;        // 关联 product_orders.id
+    private Long productId;      // 关联 products.id(冗余,便于商品详情页列表)
+    private Long reviewerId;     // 评价人ID(user.id)
+    private Integer rating;      // 综合星级 1-5
+    private String reviewText;   // 评价文字 ≤500字
+    private String images;       // 晒图URL数组 JSON(≤3张)
+    private String replyText;    // 商家回复 ≤500字
+    private Date repliedAt;      // 商家回复时间
+    private Long replyBy;        // 回复人ID(商家 user.id)
+    private Integer status;      // 1=展示 0=隐藏(P2治理预留)
+    private Date reviewAt;       // 评价时间
+    private Date createdAt;
+    private Date updatedAt;
+}

+ 12 - 0
cfc-backend/src/main/java/com/etotem/cfc/mapper/ButlerEscalationOrderMapper.java

@@ -0,0 +1,12 @@
+package com.etotem.cfc.mapper;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.etotem.cfc.entity.ButlerEscalationOrder;
+import org.apache.ibatis.annotations.Mapper;
+
+/**
+ * 真人管家 · AI 升级工单 Mapper(能力键 {@code butler.escalation.handle})。
+ */
+@Mapper
+public interface ButlerEscalationOrderMapper extends BaseMapper<ButlerEscalationOrder> {
+}

+ 37 - 0
cfc-backend/src/main/java/com/etotem/cfc/mapper/ProductReviewMapper.java

@@ -0,0 +1,37 @@
+package com.etotem.cfc.mapper;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.etotem.cfc.entity.ProductReview;
+import org.apache.ibatis.annotations.Mapper;
+import org.apache.ibatis.annotations.Param;
+
+import java.util.Date;
+import java.util.List;
+import java.util.Map;
+
+@Mapper
+public interface ProductReviewMapper extends BaseMapper<ProductReview> {
+
+    /**
+     * 按订单ID查询评价(一单一评,幂等保护用)。
+     */
+    ProductReview findByOrderId(@Param("orderId") Long orderId);
+
+    /**
+     * 商品评价列表(仅展示态,按评价时间倒序分页)。
+     */
+    List<ProductReview> listByProduct(@Param("productId") Long productId,
+                                      @Param("offset") int offset,
+                                      @Param("size") int size);
+
+    /**
+     * 商品评价统计:total + avgRating。
+     */
+    Map<String, Object> statsByProduct(@Param("productId") Long productId);
+
+    /**
+     * 待评价订单ID列表:completed 且在 90 天窗口内、买家本人、普通商品、尚未评价。
+     */
+    List<Long> findReviewableOrderIds(@Param("buyerId") Long buyerId,
+                                      @Param("since") Date since);
+}

+ 422 - 0
cfc-backend/src/main/java/com/etotem/cfc/service/ButlerEscalationService.java

@@ -0,0 +1,422 @@
+package com.etotem.cfc.service;
+
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.baomidou.mybatisplus.core.conditions.update.LambdaUpdateWrapper;
+import com.etotem.cfc.common.Result;
+import com.etotem.cfc.entity.ButlerEscalationOrder;
+import com.etotem.cfc.entity.User;
+import com.etotem.cfc.mapper.ButlerEscalationOrderMapper;
+import com.etotem.cfc.mapper.UserMapper;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import javax.annotation.Resource;
+import java.util.Arrays;
+import java.util.Date;
+import java.util.List;
+
+/**
+ * 真人管家 · AI 升级工单治理宿主服务(能力键 {@code butler.escalation.handle},SC-H-01 / SC-H-04)。
+ *
+ * <p>承载「接收 AI 升级并人工介入」与「升级与应急处理」两条场景的工单治理契约:
+ * <ul>
+ *   <li>工作台:按风险等级优先排序(HIGH → MEDIUM → LOW)返回工单列表;</li>
+ *   <li>工单上下文:家长诉求 / AI 已给结论 / 风险等级 完整携带(不丢上下文);</li>
+ *   <li>乐观锁认领:同一工单只允许一人认领(CAS on status=PENDING,他人提示「已被认领」);</li>
+ *   <li>家庭隔离:仅本家庭工单可见/可操作,越界 403(CanHandle 语义);</li>
+ *   <li>SLA 超时扫描:超过 SLA 未处理的工单触发二级升级提醒(TC-H-01-E);</li>
+ *   <li>一级自处 / 二级升级(携带完整上下文);联系动作与复盘留痕。</li>
+ * </ul>
+ *
+ * <p>方法签名由契约测试 {@code ButlerEscalationContractTest} 反射锚定,TDD-GREEN 阶段实现为真实行为。</p>
+ */
+@Service
+public class ButlerEscalationService {
+
+    private static final Logger log = LoggerFactory.getLogger(ButlerEscalationService.class);
+
+    /** 允许的联系动作类型(电话 / 消息 / 站内)。 */
+    private static final List<String> CONTACT_TYPES = Arrays.asList("CALL", "MESSAGE", "IN_APP");
+
+    @Resource
+    private ButlerEscalationOrderMapper butlerEscalationOrderMapper;
+
+    @Resource
+    private UserMapper userMapper;
+
+    /**
+     * 工作台:按风险等级优先排序返回待认领/处理中/已升级的工单(SC-H-01 工作台,高风险优先)。
+     *
+     * @param butlerUserId 管家用户 ID
+     * @return 风险等级 HIGH 优先的工单列表
+     */
+    public Result<List<ButlerEscalationOrder>> list(Long butlerUserId) {
+        if (butlerUserId == null) {
+            return Result.badRequest("butlerUserId不能为空");
+        }
+        LambdaQueryWrapper<ButlerEscalationOrder> wrapper = new LambdaQueryWrapper<ButlerEscalationOrder>()
+                .eq(ButlerEscalationOrder::getButlerUserId, butlerUserId)
+                .in(ButlerEscalationOrder::getStatus,
+                        ButlerEscalationOrder.STATUS_PENDING,
+                        ButlerEscalationOrder.STATUS_PROCESSING,
+                        ButlerEscalationOrder.STATUS_ESCALATED)
+                .last("ORDER BY FIELD(risk_level, 'HIGH', 'MEDIUM', 'LOW') ASC, created_at DESC");
+        List<ButlerEscalationOrder> list = butlerEscalationOrderMapper.selectList(wrapper);
+        return Result.success(list);
+    }
+
+    /**
+     * 工单详情,仅本家庭可见(越界 403)。
+     *
+     * @param workorderId 工单 ID
+     * @param userId      操作用户 ID
+     */
+    public Result<ButlerEscalationOrder> detail(Long workorderId, Long userId) {
+        if (workorderId == null) {
+            return Result.badRequest("workorderId不能为空");
+        }
+        ButlerEscalationOrder order = butlerEscalationOrderMapper.selectById(workorderId);
+        if (order == null) {
+            return Result.notFound("工单不存在");
+        }
+        if (!canHandle(workorderId, userId)) {
+            return Result.forbidden("仅本家庭工单可查看");
+        }
+        return Result.success(order);
+    }
+
+    /**
+     * 乐观锁认领:同一工单只允许一人认领,他人提示「已被认领」(TC-H-01-E)。
+     *
+     * <p>CAS 语义:仅在 status=PENDING(仍无人认领)时原子更新为本人 PROCESSING;
+     * 并发下仅一个管家成功,其余更新行数为 0 → 409「已被认领」。</p>
+     *
+     * @param workorderId  工单 ID
+     * @param butlerUserId 认领管家用户 ID
+     */
+    @Transactional
+    public Result<String> claim(Long workorderId, Long butlerUserId) {
+        if (workorderId == null || butlerUserId == null) {
+            return Result.badRequest("workorderId和butlerUserId不能为空");
+        }
+        ButlerEscalationOrder order = butlerEscalationOrderMapper.selectById(workorderId);
+        if (order == null) {
+            return Result.notFound("工单不存在");
+        }
+        if (!ButlerEscalationOrder.STATUS_PENDING.equals(order.getStatus())) {
+            if (butlerUserId.equals(order.getButlerUserId())) {
+                return Result.error("该工单已被你认领");
+            }
+            return Result.conflict("该工单已被认领");
+        }
+        int rows = butlerEscalationOrderMapper.update(null,
+                new LambdaUpdateWrapper<ButlerEscalationOrder>()
+                        .eq(ButlerEscalationOrder::getId, workorderId)
+                        .eq(ButlerEscalationOrder::getStatus, ButlerEscalationOrder.STATUS_PENDING)
+                        .set(ButlerEscalationOrder::getButlerUserId, butlerUserId)
+                        .set(ButlerEscalationOrder::getStatus, ButlerEscalationOrder.STATUS_PROCESSING)
+                        .set(ButlerEscalationOrder::getClaimedAt, new Date())
+                        .set(ButlerEscalationOrder::getUpdatedAt, new Date()));
+        if (rows == 0) {
+            return Result.conflict("该工单已被认领");
+        }
+        log.info("管家 {} 认领升级工单 {}(CAS 成功),状态 PENDING→PROCESSING", butlerUserId, workorderId);
+        return Result.success("认领成功", null);
+    }
+
+    /**
+     * 记录联系动作留痕(电话/消息/站内),TC-H-01 步骤 3。
+     *
+     * @param workorderId 工单 ID
+     * @param contactType 联系类型 CALL/MESSAGE/IN_APP
+     * @param content     联系内容
+     * @param userId      操作用户 ID
+     */
+    @Transactional
+    public Result<String> logContact(Long workorderId, String contactType, String content, Long userId) {
+        if (workorderId == null || contactType == null || contactType.trim().isEmpty()) {
+            return Result.badRequest("workorderId和contactType不能为空");
+        }
+        if (!CONTACT_TYPES.contains(contactType)) {
+            return Result.badRequest("contactType必须为 CALL / MESSAGE / IN_APP");
+        }
+        if (!canHandle(workorderId, userId)) {
+            return Result.forbidden("仅本家庭工单可操作");
+        }
+        int rows = butlerEscalationOrderMapper.update(null,
+                new LambdaUpdateWrapper<ButlerEscalationOrder>()
+                        .eq(ButlerEscalationOrder::getId, workorderId)
+                        .set(ButlerEscalationOrder::getContactType, contactType)
+                        .set(ButlerEscalationOrder::getContactContent, content)
+                        .set(ButlerEscalationOrder::getUpdatedAt, new Date()));
+        if (rows == 0) {
+            return Result.notFound("工单不存在");
+        }
+        log.info("工单 {} 记录联系动作 {}(用户 {})", workorderId, contactType, userId);
+        return Result.success("联系动作已记录", null);
+    }
+
+    /**
+     * 人工处置结论并闭环,工单 PENDING→PROCESSING→CLOSED 留痕(TC-H-01 步骤 4/5)。
+     *
+     * @param workorderId 工单 ID
+     * @param resolution  人工结论
+     * @param userId      操作用户 ID
+     */
+    @Transactional
+    public Result<String> resolve(Long workorderId, String resolution, Long userId) {
+        if (workorderId == null || resolution == null || resolution.trim().isEmpty()) {
+            return Result.badRequest("workorderId和resolution不能为空");
+        }
+        if (!canHandle(workorderId, userId)) {
+            return Result.forbidden("仅本家庭工单可操作");
+        }
+        ButlerEscalationOrder order = butlerEscalationOrderMapper.selectById(workorderId);
+        if (order == null) {
+            return Result.notFound("工单不存在");
+        }
+        if (ButlerEscalationOrder.STATUS_CLOSED.equals(order.getStatus())) {
+            return Result.conflict("工单已闭环");
+        }
+        if (ButlerEscalationOrder.STATUS_WITHDRAWN.equals(order.getStatus())) {
+            return Result.conflict("工单已撤回,不可闭环");
+        }
+        int rows = butlerEscalationOrderMapper.update(null,
+                new LambdaUpdateWrapper<ButlerEscalationOrder>()
+                        .eq(ButlerEscalationOrder::getId, workorderId)
+                        .set(ButlerEscalationOrder::getResolution, resolution)
+                        .set(ButlerEscalationOrder::getStatus, ButlerEscalationOrder.STATUS_CLOSED)
+                        .set(ButlerEscalationOrder::getClosedAt, new Date())
+                        .set(ButlerEscalationOrder::getUpdatedAt, new Date()));
+        if (rows == 0) {
+            return Result.notFound("工单不存在");
+        }
+        log.info("工单 {} 由用户 {} 处置闭环:{}", workorderId, userId, resolution);
+        return Result.success("工单已闭环", null);
+    }
+
+    /**
+     * 转交规划师(SC-H-01 转规划师)。
+     *
+     * @param workorderId 工单 ID
+     * @param teacherId   规划师用户 ID
+     * @param userId      操作用户 ID
+     */
+    @Transactional
+    public Result<String> transferToTeacher(Long workorderId, Long teacherId, Long userId) {
+        if (workorderId == null || teacherId == null) {
+            return Result.badRequest("workorderId和teacherId不能为空");
+        }
+        if (!canHandle(workorderId, userId)) {
+            return Result.forbidden("仅本家庭工单可操作");
+        }
+        int rows = butlerEscalationOrderMapper.update(null,
+                new LambdaUpdateWrapper<ButlerEscalationOrder>()
+                        .eq(ButlerEscalationOrder::getId, workorderId)
+                        .set(ButlerEscalationOrder::getTeacherId, teacherId)
+                        .set(ButlerEscalationOrder::getTargetRole, "teacher")
+                        .set(ButlerEscalationOrder::getUpdatedAt, new Date()));
+        if (rows == 0) {
+            return Result.notFound("工单不存在");
+        }
+        log.info("工单 {} 由用户 {} 转交规划师 {}", workorderId, userId, teacherId);
+        return Result.success("已转交规划师", null);
+    }
+
+    /**
+     * 按 SOP 分级:一级自行处置 / 二级升级至运营、医疗顾问(SC-H-04,管理端治理)。
+     *
+     * @param workorderId     工单 ID
+     * @param escalationLevel 1=一级自行处置 / 2=二级升级
+     * @param userId          操作用户 ID(管理端)
+     */
+    @Transactional
+    public Result<String> grade(Long workorderId, Integer escalationLevel, Long userId) {
+        if (workorderId == null || escalationLevel == null) {
+            return Result.badRequest("workorderId和escalationLevel不能为空");
+        }
+        if (escalationLevel != 1 && escalationLevel != 2) {
+            return Result.badRequest("escalationLevel必须为 1(一级自处)或 2(二级升级)");
+        }
+        ButlerEscalationOrder order = butlerEscalationOrderMapper.selectById(workorderId);
+        if (order == null) {
+            return Result.notFound("工单不存在");
+        }
+        LambdaUpdateWrapper<ButlerEscalationOrder> wrapper = new LambdaUpdateWrapper<ButlerEscalationOrder>()
+                .eq(ButlerEscalationOrder::getId, workorderId)
+                .set(ButlerEscalationOrder::getEscalationLevel, escalationLevel)
+                .set(ButlerEscalationOrder::getUpdatedAt, new Date());
+        if (escalationLevel == 1) {
+            if (!ButlerEscalationOrder.STATUS_PROCESSING.equals(order.getStatus())
+                    && !ButlerEscalationOrder.STATUS_PENDING.equals(order.getStatus())) {
+                return Result.conflict("当前状态不支持一级自处");
+            }
+            wrapper.set(ButlerEscalationOrder::getStatus, ButlerEscalationOrder.STATUS_PROCESSING);
+        } else {
+            wrapper.set(ButlerEscalationOrder::getStatus, ButlerEscalationOrder.STATUS_ESCALATED);
+            wrapper.set(ButlerEscalationOrder::getTargetRole, "运营/医疗顾问");
+        }
+        int rows = butlerEscalationOrderMapper.update(null, wrapper);
+        if (rows == 0) {
+            return Result.notFound("工单不存在");
+        }
+        log.info("工单 {} 由用户 {} 按 SOP 分级为 {} 级", workorderId, userId, escalationLevel);
+        return Result.success(escalationLevel == 1 ? "已按 SOP 一级自行处置" : "已按 SOP 二级升级", null);
+    }
+
+    /**
+     * 二级升级至运营/医疗顾问,并携带完整上下文(不丢上下文,SC-H-04)。
+     *
+     * @param workorderId 工单 ID
+     * @param targetRole  目标角色(运营/医疗顾问)
+     * @param userId      操作用户 ID(管理端)
+     * @return 携带完整工单上下文的升级结果
+     */
+    @Transactional
+    public Result<ButlerEscalationOrder> escalateLevel2(Long workorderId, String targetRole, Long userId) {
+        if (workorderId == null) {
+            return Result.badRequest("workorderId不能为空");
+        }
+        ButlerEscalationOrder order = butlerEscalationOrderMapper.selectById(workorderId);
+        if (order == null) {
+            return Result.notFound("工单不存在");
+        }
+        int rows = butlerEscalationOrderMapper.update(null,
+                new LambdaUpdateWrapper<ButlerEscalationOrder>()
+                        .eq(ButlerEscalationOrder::getId, workorderId)
+                        .set(ButlerEscalationOrder::getEscalationLevel, 2)
+                        .set(ButlerEscalationOrder::getTargetRole,
+                                targetRole == null || targetRole.trim().isEmpty() ? "运营/医疗顾问" : targetRole)
+                        .set(ButlerEscalationOrder::getStatus, ButlerEscalationOrder.STATUS_ESCALATED)
+                        .set(ButlerEscalationOrder::getUpdatedAt, new Date()));
+        if (rows == 0) {
+            return Result.notFound("工单不存在");
+        }
+        // 重查并整单返回,确保升级后仍携带完整上下文(家长诉求 / AI 结论 / 风险等级)
+        ButlerEscalationOrder escalated = butlerEscalationOrderMapper.selectById(workorderId);
+        log.info("工单 {} 二级升级至 {}(用户 {},上下文完整携带)", workorderId,
+                escalated.getTargetRole(), userId);
+        return Result.success("已二级升级", escalated);
+    }
+
+    /**
+     * 生成复盘记录(含处置时长与结论,SC-H-04 复盘)。
+     *
+     * @param workorderId      工单 ID
+     * @param durationMinutes  处置时长(分钟)
+     * @param conclusion       复盘结论
+     * @param userId           操作用户 ID(管理端)
+     */
+    @Transactional
+    public Result<String> recordReview(Long workorderId, Integer durationMinutes, String conclusion, Long userId) {
+        if (workorderId == null) {
+            return Result.badRequest("workorderId不能为空");
+        }
+        ButlerEscalationOrder order = butlerEscalationOrderMapper.selectById(workorderId);
+        if (order == null) {
+            return Result.notFound("工单不存在");
+        }
+        LambdaUpdateWrapper<ButlerEscalationOrder> wrapper = new LambdaUpdateWrapper<ButlerEscalationOrder>()
+                .eq(ButlerEscalationOrder::getId, workorderId)
+                .set(ButlerEscalationOrder::getReviewConclusion, conclusion)
+                .set(ButlerEscalationOrder::getUpdatedAt, new Date());
+        if (durationMinutes != null) {
+            wrapper.set(ButlerEscalationOrder::getDurationMinutes, durationMinutes);
+        }
+        int rows = butlerEscalationOrderMapper.update(null, wrapper);
+        if (rows == 0) {
+            return Result.notFound("工单不存在");
+        }
+        log.info("工单 {} 复盘留痕:时长 {} 分钟,结论 {}(用户 {})",
+                workorderId, durationMinutes, conclusion, userId);
+        return Result.success("复盘记录已生成", null);
+    }
+
+    /**
+     * 扫描超过 SLA 未处理的工单,触发二级升级提醒(TC-H-01-E)。
+     *
+     * @return 触发升级提醒的工单数量
+     */
+    @Transactional
+    public Result<Integer> checkTimeoutEscalation() {
+        Date now = new Date();
+        LambdaQueryWrapper<ButlerEscalationOrder> wrapper = new LambdaQueryWrapper<ButlerEscalationOrder>()
+                .in(ButlerEscalationOrder::getStatus,
+                        ButlerEscalationOrder.STATUS_PENDING,
+                        ButlerEscalationOrder.STATUS_PROCESSING)
+                .isNotNull(ButlerEscalationOrder::getSlaDeadline)
+                .lt(ButlerEscalationOrder::getSlaDeadline, now);
+        List<ButlerEscalationOrder> timeoutOrders = butlerEscalationOrderMapper.selectList(wrapper);
+        int count = 0;
+        for (ButlerEscalationOrder o : timeoutOrders) {
+            int rows = butlerEscalationOrderMapper.update(null,
+                    new LambdaUpdateWrapper<ButlerEscalationOrder>()
+                            .eq(ButlerEscalationOrder::getId, o.getId())
+                            .set(ButlerEscalationOrder::getStatus, ButlerEscalationOrder.STATUS_ESCALATED)
+                            .set(ButlerEscalationOrder::getEscalationLevel, 2)
+                            .set(ButlerEscalationOrder::getTargetRole, "运营/医疗顾问")
+                            .set(ButlerEscalationOrder::getUpdatedAt, now));
+            if (rows > 0) {
+                count++;
+                log.warn("工单 {} SLA 超时(deadline={}),触发二级升级提醒", o.getId(), o.getSlaDeadline());
+            }
+        }
+        return Result.success("SLA 扫描完成,触发升级提醒 " + count + " 单", count);
+    }
+
+    /**
+     * 家庭隔离校验:仅本家庭工单可查看/操作,越界返回 false(TC-H-01-P / TC-H-04-P)。
+     *
+     * @param workorderId 工单 ID
+     * @param userId      操作用户 ID
+     * @return true = 工单属于该用户家庭;false = 越界/不存在
+     */
+    public boolean canHandle(Long workorderId, Long userId) {
+        if (workorderId == null || userId == null) {
+            return false;
+        }
+        ButlerEscalationOrder order = butlerEscalationOrderMapper.selectById(workorderId);
+        if (order == null || order.getFamilyId() == null) {
+            return false;
+        }
+        User user = userMapper.selectById(userId);
+        return user != null && user.getFamilyId() != null
+                && user.getFamilyId().equals(order.getFamilyId());
+    }
+
+    /**
+     * 撤回工单(家庭端 SC-H-04 已撤回状态),仅本家庭工单可撤回。
+     *
+     * @param workorderId 工单 ID
+     * @param userId      操作用户 ID
+     */
+    @Transactional
+    public Result<String> withdraw(Long workorderId, Long userId) {
+        if (workorderId == null) {
+            return Result.badRequest("workorderId不能为空");
+        }
+        if (!canHandle(workorderId, userId)) {
+            return Result.forbidden("仅本家庭工单可操作");
+        }
+        ButlerEscalationOrder order = butlerEscalationOrderMapper.selectById(workorderId);
+        if (order == null) {
+            return Result.notFound("工单不存在");
+        }
+        if (ButlerEscalationOrder.STATUS_CLOSED.equals(order.getStatus())
+                || ButlerEscalationOrder.STATUS_WITHDRAWN.equals(order.getStatus())) {
+            return Result.conflict("工单已闭环或已撤回,不可重复操作");
+        }
+        int rows = butlerEscalationOrderMapper.update(null,
+                new LambdaUpdateWrapper<ButlerEscalationOrder>()
+                        .eq(ButlerEscalationOrder::getId, workorderId)
+                        .set(ButlerEscalationOrder::getStatus, ButlerEscalationOrder.STATUS_WITHDRAWN)
+                        .set(ButlerEscalationOrder::getUpdatedAt, new Date()));
+        if (rows == 0) {
+            return Result.notFound("工单不存在");
+        }
+        log.info("工单 {} 由用户 {} 撤回", workorderId, userId);
+        return Result.success("工单已撤回", null);
+    }
+}

+ 4 - 0
cfc-backend/src/main/resources/application.yml

@@ -204,6 +204,10 @@ tencent:
 shop:
   order:
     payment-timeout-minutes: 30  # 订单超时时间(分钟)
+    receipt-timeout-days: 10      # 发货后未确认收货超时自动完成天数(P0-B 待收货兜底)
+    receipt-remind-days: 9        # 发货后第N天推送收货提醒订阅消息(P0-B 联动)
+    receipt-auto-complete-enabled: true   # 自动完成总开关(灰度/回滚用,false 时仅提醒不自动完成)
+    receipt-remind-template-id: ''        # 微信订阅消息模板ID(空=跳过推送,fail-open,运营配置)
 
 virtual-pay:
   payment-timeout-minutes: 30  # 虚拟支付订单超时时间(分钟)

+ 43 - 0
cfc-backend/src/main/resources/mapper/ProductReviewMapper.xml

@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
+<mapper namespace="com.etotem.cfc.mapper.ProductReviewMapper">
+
+    <select id="findByOrderId" resultType="com.etotem.cfc.entity.ProductReview">
+        SELECT *
+        FROM product_reviews
+        WHERE order_id = #{orderId}
+        LIMIT 1
+    </select>
+
+    <select id="listByProduct" resultType="com.etotem.cfc.entity.ProductReview">
+        SELECT *
+        FROM product_reviews
+        WHERE product_id = #{productId}
+          AND status = 1
+        ORDER BY review_at DESC, id DESC
+        LIMIT #{size} OFFSET #{offset}
+    </select>
+
+    <select id="statsByProduct" resultType="java.util.Map">
+        SELECT
+            COUNT(*) AS total,
+            AVG(rating) AS avgRating
+        FROM product_reviews
+        WHERE product_id = #{productId}
+          AND status = 1
+    </select>
+
+    <select id="findReviewableOrderIds" resultType="java.lang.Long">
+        SELECT o.id
+        FROM product_orders o
+        WHERE o.buyer_id = #{buyerId}
+          AND o.status = 'completed'
+          AND (o.product_type IS NULL OR o.product_type &lt;&gt; 'activity')
+          AND o.confirm_time &gt;= #{since}
+          AND NOT EXISTS (
+              SELECT 1 FROM product_reviews r WHERE r.order_id = o.id
+          )
+        ORDER BY o.confirm_time DESC
+    </select>
+
+</mapper>

+ 51 - 0
cfc-backend/src/main/resources/schema.sql

@@ -1363,6 +1363,8 @@ audit_reason TEXT COMMENT '审核拒绝原因',
     refund_time DATETIME DEFAULT NULL COMMENT '退款时间',
     refund_before_status VARCHAR(32) DEFAULT NULL COMMENT '退款前订单状态(售后取消回滚用)',
     refund_before_refund_status TINYINT(1) DEFAULT 0 COMMENT '退款前退款状态(售后取消回滚用)',
+    shipped_at DATETIME DEFAULT NULL COMMENT '发货时间',
+    receipt_remind_at DATETIME DEFAULT NULL COMMENT '收货提醒推送时间',
     created_at DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
     updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
     special_deal_id BIGINT NULL COMMENT '限时特价活动ID(非空=特价单)',
@@ -1373,6 +1375,26 @@ audit_reason TEXT COMMENT '审核拒绝原因',
     INDEX idx_supply_system_id (supply_system_id)
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='商品订单表';
 
+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 COMMENT '创建时间',
+    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
+    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)';
+
 -- 限时特价活动表
 CREATE TABLE IF NOT EXISTS special_price_deals (
     id BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT '主键ID',
@@ -3105,6 +3127,35 @@ CREATE TABLE IF NOT EXISTS butler_performance (
     INDEX idx_year_month (year_month)
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='真人管家绩效看板(SC-H-07)';
 
+-- 真人管家升级工单(能力键 butler.escalation.handle · SC-H-01 接收 AI 升级并人工介入 / SC-H-04 升级与应急处理)
+-- 仅本家庭可见(family_id 隔离),风险等级优先(HIGH/MEDIUM/LOW),乐观锁认领,SLA 超时升级,联系/复盘留痕
+CREATE TABLE IF NOT EXISTS butler_escalation_orders (
+    id BIGINT AUTO_INCREMENT PRIMARY KEY,
+    family_id BIGINT NOT NULL COMMENT '工单所属家庭(仅本家庭授权,越界 403)',
+    butler_user_id BIGINT NULL COMMENT '认领管家用户 ID(乐观锁:同一工单只允许一人认领)',
+    source_type VARCHAR(32) DEFAULT 'AI_ESCALATION' COMMENT '工单来源: AI升级/异常预警/投诉',
+    risk_level VARCHAR(16) DEFAULT 'MEDIUM' COMMENT '风险等级: HIGH/MEDIUM/LOW(高风险优先排序)',
+    status VARCHAR(16) DEFAULT 'PENDING' COMMENT '状态: PENDING/PROCESSING/CLOSED/WITHDRAWN/ESCALATED',
+    parent_demand TEXT NULL COMMENT '家长诉求上下文',
+    ai_conclusion TEXT NULL COMMENT 'AI 已给结论上下文',
+    teacher_id BIGINT NULL COMMENT '转交规划师用户 ID(SC-H-01 转规划师)',
+    escalation_level INT DEFAULT 1 COMMENT 'SOP 分级: 1=一级自行处置/2=二级升级(SC-H-04)',
+    target_role VARCHAR(32) NULL COMMENT '二级升级目标角色: 运营/医疗顾问',
+    contact_type VARCHAR(16) NULL COMMENT '最近联系动作类型: CALL/MESSAGE/IN_APP(留痕)',
+    contact_content TEXT NULL COMMENT '最近联系动作内容(留痕)',
+    resolution TEXT NULL COMMENT '人工结论(闭环留痕)',
+    review_conclusion TEXT NULL COMMENT '复盘结论(SC-H-04 复盘)',
+    duration_minutes INT NULL COMMENT '复盘处置时长(分钟)',
+    sla_deadline DATETIME NULL COMMENT 'SLA 超时时间(超时未处理触发升级提醒 TC-H-01-E)',
+    claimed_at DATETIME NULL COMMENT '认领时间',
+    closed_at DATETIME NULL COMMENT '闭环时间',
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+    INDEX idx_family_status (family_id, status),
+    INDEX idx_butler_status (butler_user_id, status),
+    INDEX idx_status_sla (status, sla_deadline)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='真人管家升级工单(SC-H-01/SC-H-04)';
+
 -- 家庭订阅记录
 CREATE TABLE IF NOT EXISTS member_subscription (
     id BIGINT AUTO_INCREMENT PRIMARY KEY,

+ 1 - 1
cfc-web/.last_build_commit

@@ -1 +1 @@
-a22cd51893d880e24c8c0da8cb589d765b6eee1f
+f57e524894993827d1c0349845467ac1a0bee84e

+ 2 - 2
cfc-web/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "cfc-web",
-  "version": "1.0.2498",
+  "version": "1.0.2500",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "cfc-web",
-      "version": "1.0.2498",
+      "version": "1.0.2500",
       "dependencies": {
         "@wangeditor/editor": "^5.1.23",
         "@wangeditor/editor-for-vue": "^1.0.2",

+ 1 - 1
cfc-web/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cfc-web",
-  "version": "1.0.2499",
+  "version": "1.0.2501",
   "private": true,
   "scripts": {
     "dev": "vue-cli-service serve",

+ 72 - 0
cfc-web/public/CHANGELOG-v1.0.md

@@ -4,6 +4,78 @@
 
 ---
 
+## v1.0.2501 (2026-11-14)
+
+### 文档
+- 4c0ff6729 部署回执更新——SUCCESS(fix 17829760 落地后部署链部署 f3699cf64 成功,目标已运行 testing;并行精确部署回滚未影响)
+- S-cfc-330 child.badge.view 当前HEAD复核——契约11/11全绿=实现已在链(O-22豁免),发现无关P0 B-203-5测试编译阻断待商品可见性链路归口
+
+### 测试
+- S-cfc-283 contact.card.manage RED 契约级单测(SC-P-61 重复号码去重 / SC-P-63 设可见权限+越权403,预期 5红2绿)
+
+### 新功能
+- T01 数据层底座——product_reviews 独立评价表(迁移475)+product_orders 收货超时列(迁移476)+实体/Mapper/配置
+
+### 其他
+- P0-B 待收货超时兜底数据源(shipped_at/receipt_remind_at 两列)
+- product_reviews.uk_order_id 一单一评幂等;mvn clean compile 通过
+- 
+
+
+## v1.0.2500 (2026-11-14)
+
+### 文档
+- testing 部署回执 4c0ff6729(目标提交含 @Resource bean撞名启动阻断,线上维持 c2180785;fix 17829760 已入 cfclub)
+- E09 修复闭环 + 6 个同类洞安全工单台账(SECURITY_TICKETS_2026-11)
+
+### Bug 修复
+- 修复 @Resource Bean 撞名致 Spring 启动阻断(部署链回滚真因)
+- 报告编辑/下载接口补归属校验,堵同型越权
+- 报告删除接口补归属校验,防越权删除
+
+### 其他
+-   字段类型 ButlerResourceFollowUpMapper 默认 Bean 名 butlerResourceFollowUpMapper,
+-   原字段名 followUpMapper 与 FollowUpMapper Bean 撞名,@Resource 先按名解析命中
+-   错误 Bean 致上下文启动失败(d363df8056/0875a19e3 部署自动回滚真因)。
+- - HealthDataSourceBridgeService.dimensionScoreService 改为 healthDimensionScoreService:
+-   同源第二枚雷(与 DimensionScoreService Bean 撞名),与 EnergyService 既有
+-   healthDimensionScoreService 命名对齐。
+- - 保持字段名与类型默认 Bean Name 一致(仓库约定)。
+- 
+- 根因:githooks/pre-push 用 mvn -q -DskipTests compile(仅主源码),测试源不参与编译。
+- 建议改为 mvn -q -DskipTests test-compile(不执行测试,多 3-5s),即可拦住 B-203-5 这类 P0。
+- 
+- mvn -o test-compile 直接 BUILD FAILURE:14 处「找不到符号 方法 of(java.lang.String)」,而 pom java.version=1.8。
+- - blockers 新增 B-203-5(含 14 处精确行号与 Arrays.asList/Collections.singletonList 修法)
+- - 报告 R203:G4 由 ✅ 翻 ❌、G5 标注为基线口径、新增「问题 0(最紧急)」五要素、结论改「P0 阻断 ×2」
+- - 研发通知:新增「一、最紧急:编译失败」置于 Bean 阻断之前
+- - 口径声明:后端 89.76% 属 de201830c 基线,当前 HEAD 后端为不可测,不得当作 HEAD 结论
+- 
+-   命中不可赋值才算违规)静态扫描主源码,扫出 2 处违例:
+-   · ButlerResourceMatchService.followUpMapper(撞 FollowUpMapper)→ 线上部署 d363df8056 回滚真因,
+-     并使 49 个 @SpringBootTest 类约 440 例不可判定
+-   · HealthDataSourceBridgeService.dimensionScoreService(撞 DimensionScoreService)→ 同源第二枚雷
+- - G12:新增 tests/test-cases/2026-11-14-product-order-gap.md(27 条 TC-POG-01~27,
+-   正常 12 / 异常 9 / 权限 6),派生自 product-order-gap PRD P0-A~D + P1-A/B
+- - R203 报告 + 研发通知 + blockers R203 段(B-203-1~4,B-95 销号 204 已恢复)
+- - 补提交 R202 遗留产物(报告/通知)与 4 份 hourlyloop 运行记录
+- 实测:浏览器 28/28+2 跳零漂移;fe 616/4/12 逐例一致;web 132/132;lg@251 40/51 环境红;
+- 后端非-Spring 428 类/3751 例/384 红=89.76%(红=契约前瞻 378+存量 5+守卫 1,零确定性回归)
+- 
+- - docs/tdd/orchestration/sc-key-map.md: 注册 SC-A-23 团队收益 / SC-A-24 财富中心贡献榜,基线 241→243;纠正此前对 SC-X-22 的重复计(曾误计 244)
+- - tests/TRACEABILITY-MATRIX.md: L1 实测 223/243(91.8%,重排消除 20 个 SC 幻影覆盖);L2 实测 680 对齐 / 0 编号错位 / 221 格式差异(旧文本标注与 S-cfc 规格键)/ 20 特殊保留;G-2 闭环标注
+- - .gitignore: 补全一次性执行辅助(/_r* /_e2e* /tests/_* 等)忽略规则
+- - 清理 38 个误入库的临时探针文件(git rm --cached)
+- 经用户授权提交推送 origin/cfclub 闭环 G-9。
+- 
+
+### 测试
+- 补记 B-203-6——pre-push 闸门只跑 compile 不跑 test-compile,漏拦 Java9+ API
+- 补记 P0 编译阻断 B-203-5(新测试类用 Java9+ List.of → 后端 478 类零可执行)
+- P0 阻断定位——@Resource Bean 撞名致 Spring 上下文启动失败 + 毫秒级守卫 + TC-POG 27 条
+- 语义重排 51 个错位 TC + 台账/矩阵基线纠偏 (闭环 G-2/G-9)
+
+
 ## v1.0.2499 (2026-11-14)
 
 ### Bug 修复

+ 73 - 1
cfc-web/public/CHANGELOG.md

@@ -1,6 +1,6 @@
 # 更新日志
 
-> 当前版本: v1.0.2499
+> 当前版本: v1.0.2501
 
 ## 历史版本
 
@@ -8,6 +8,78 @@
 
 ---
 
+## v1.0.2501 (2026-11-14)
+
+### 文档
+- 4c0ff6729 部署回执更新——SUCCESS(fix 17829760 落地后部署链部署 f3699cf64 成功,目标已运行 testing;并行精确部署回滚未影响)
+- S-cfc-330 child.badge.view 当前HEAD复核——契约11/11全绿=实现已在链(O-22豁免),发现无关P0 B-203-5测试编译阻断待商品可见性链路归口
+
+### 测试
+- S-cfc-283 contact.card.manage RED 契约级单测(SC-P-61 重复号码去重 / SC-P-63 设可见权限+越权403,预期 5红2绿)
+
+### 新功能
+- T01 数据层底座——product_reviews 独立评价表(迁移475)+product_orders 收货超时列(迁移476)+实体/Mapper/配置
+
+### 其他
+- P0-B 待收货超时兜底数据源(shipped_at/receipt_remind_at 两列)
+- product_reviews.uk_order_id 一单一评幂等;mvn clean compile 通过
+- 
+
+
+## v1.0.2500 (2026-11-14)
+
+### 文档
+- testing 部署回执 4c0ff6729(目标提交含 @Resource bean撞名启动阻断,线上维持 c2180785;fix 17829760 已入 cfclub)
+- E09 修复闭环 + 6 个同类洞安全工单台账(SECURITY_TICKETS_2026-11)
+
+### Bug 修复
+- 修复 @Resource Bean 撞名致 Spring 启动阻断(部署链回滚真因)
+- 报告编辑/下载接口补归属校验,堵同型越权
+- 报告删除接口补归属校验,防越权删除
+
+### 其他
+-   字段类型 ButlerResourceFollowUpMapper 默认 Bean 名 butlerResourceFollowUpMapper,
+-   原字段名 followUpMapper 与 FollowUpMapper Bean 撞名,@Resource 先按名解析命中
+-   错误 Bean 致上下文启动失败(d363df8056/0875a19e3 部署自动回滚真因)。
+- - HealthDataSourceBridgeService.dimensionScoreService 改为 healthDimensionScoreService:
+-   同源第二枚雷(与 DimensionScoreService Bean 撞名),与 EnergyService 既有
+-   healthDimensionScoreService 命名对齐。
+- - 保持字段名与类型默认 Bean Name 一致(仓库约定)。
+- 
+- 根因:githooks/pre-push 用 mvn -q -DskipTests compile(仅主源码),测试源不参与编译。
+- 建议改为 mvn -q -DskipTests test-compile(不执行测试,多 3-5s),即可拦住 B-203-5 这类 P0。
+- 
+- mvn -o test-compile 直接 BUILD FAILURE:14 处「找不到符号 方法 of(java.lang.String)」,而 pom java.version=1.8。
+- - blockers 新增 B-203-5(含 14 处精确行号与 Arrays.asList/Collections.singletonList 修法)
+- - 报告 R203:G4 由 ✅ 翻 ❌、G5 标注为基线口径、新增「问题 0(最紧急)」五要素、结论改「P0 阻断 ×2」
+- - 研发通知:新增「一、最紧急:编译失败」置于 Bean 阻断之前
+- - 口径声明:后端 89.76% 属 de201830c 基线,当前 HEAD 后端为不可测,不得当作 HEAD 结论
+- 
+-   命中不可赋值才算违规)静态扫描主源码,扫出 2 处违例:
+-   · ButlerResourceMatchService.followUpMapper(撞 FollowUpMapper)→ 线上部署 d363df8056 回滚真因,
+-     并使 49 个 @SpringBootTest 类约 440 例不可判定
+-   · HealthDataSourceBridgeService.dimensionScoreService(撞 DimensionScoreService)→ 同源第二枚雷
+- - G12:新增 tests/test-cases/2026-11-14-product-order-gap.md(27 条 TC-POG-01~27,
+-   正常 12 / 异常 9 / 权限 6),派生自 product-order-gap PRD P0-A~D + P1-A/B
+- - R203 报告 + 研发通知 + blockers R203 段(B-203-1~4,B-95 销号 204 已恢复)
+- - 补提交 R202 遗留产物(报告/通知)与 4 份 hourlyloop 运行记录
+- 实测:浏览器 28/28+2 跳零漂移;fe 616/4/12 逐例一致;web 132/132;lg@251 40/51 环境红;
+- 后端非-Spring 428 类/3751 例/384 红=89.76%(红=契约前瞻 378+存量 5+守卫 1,零确定性回归)
+- 
+- - docs/tdd/orchestration/sc-key-map.md: 注册 SC-A-23 团队收益 / SC-A-24 财富中心贡献榜,基线 241→243;纠正此前对 SC-X-22 的重复计(曾误计 244)
+- - tests/TRACEABILITY-MATRIX.md: L1 实测 223/243(91.8%,重排消除 20 个 SC 幻影覆盖);L2 实测 680 对齐 / 0 编号错位 / 221 格式差异(旧文本标注与 S-cfc 规格键)/ 20 特殊保留;G-2 闭环标注
+- - .gitignore: 补全一次性执行辅助(/_r* /_e2e* /tests/_* 等)忽略规则
+- - 清理 38 个误入库的临时探针文件(git rm --cached)
+- 经用户授权提交推送 origin/cfclub 闭环 G-9。
+- 
+
+### 测试
+- 补记 B-203-6——pre-push 闸门只跑 compile 不跑 test-compile,漏拦 Java9+ API
+- 补记 P0 编译阻断 B-203-5(新测试类用 Java9+ List.of → 后端 478 类零可执行)
+- P0 阻断定位——@Resource Bean 撞名致 Spring 上下文启动失败 + 毫秒级守卫 + TC-POG 27 条
+- 语义重排 51 个错位 TC + 台账/矩阵基线纠偏 (闭环 G-2/G-9)
+
+
 ## v1.0.2499 (2026-11-14)
 
 ### Bug 修复

+ 14 - 0
docs/superpowers/api/API_REFERENCE.md

@@ -3616,6 +3616,15 @@ W0.2 双配置中心合并:`product_config` 已并入 `service_config`(唯
 | `POST /api/butler/available-list` | 可选择的管家列表(浏览开放) |
 | `POST /api/butler/my-butler` | 我的管家信息 |
 | `POST /api/butler/select` | 家庭自助选择管家(L2 绑定受限校验,`ButlerService.selectButler`) |
+| `POST /api/butler/escalation/list` | 升级工单工作台:按风险等级优先排序(HIGH→MEDIUM→LOW,SC-H-01 工作台) |
+| `POST /api/butler/escalation/detail` | 升级工单详情(仅本家庭,越界 403) |
+| `POST /api/butler/escalation/claim` | 乐观锁认领升级工单(他人「已被认领」,TC-H-01-E) |
+| `POST /api/butler/escalation/log-contact` | 记录联系动作留痕(电话/消息/站内,TC-H-01 步骤3) |
+| `POST /api/butler/escalation/close` | 人工处置结论并闭环(PENDING→PROCESSING→CLOSED 留痕,TC-H-01 步骤4/5) |
+| `POST /api/butler/escalation/transfer` | 转交规划师(SC-H-01 转规划师) |
+| `POST /api/butler/escalation/withdraw` | 撤回升级工单(SC-H-04 已撤回) |
+
+> 能力键 `butler.escalation.handle`(SC-H-01/SC-H-04)新增端点已落地 `ButlerEscalationService`:风险等级优先排序 / 乐观锁认领 / SLA 超时扫描 / 家庭隔离(越界 403)/ 联系/复盘留痕。
 
 > ⚠ SC-B-09「教练转接成长规划师」实际载体为**规划师绑定流**:`/api/guide/bind/invite` → `/validate` → `/confirm`(BindInviteController)+ `/api/bind/accept`、`/api/bind/unbind`(BindController);`/api/butler/apply|select` 是管家申请/选管家,非转接。
 > ⚠ SC-B-10 聚合台账以 admin 侧为准确认(4.64.8),家庭端复用 `/api/butler/members` 单体。
@@ -3635,6 +3644,11 @@ W0.2 双配置中心合并:`product_config` 已并入 `service_config`(唯
 | `POST /api/admin/butler/list` | 管家列表(资源清单载体) |
 | `POST /api/admin/butler/review` | 管家申请审核(升级介入,SC-H-01) |
 | `POST /api/admin/butler/assign-member` | 指派管家到家庭(一对一家长陪跑,SC-H-02) |
+| `POST /api/admin/butler/escalation/grade` | 按 SOP 分级升级工单:一级自行处置/二级升级(SC-H-04,admin/finance 角色校验) |
+| `POST /api/admin/butler/escalation/escalate` | 二级升级至运营/医疗顾问,携带完整上下文(SC-H-04,admin/finance 角色校验) |
+| `POST /api/admin/butler/escalation/review` | 生成复盘记录(含处置时长与结论,SC-H-04 复盘,admin/finance 角色校验) |
+
+> 能力键 `butler.escalation.handle` admin 治理端点(grade/escalate/review)已落地 `ButlerEscalationService`,仅 admin/finance 角色可操作。
 | `POST /api/admin/butler/service-records` | 服务记录台账(多方沟通记录 / 质检台账,SC-H-03/H-07;分页) |
 | `POST /api/admin/butler/settlements` | 佣金结算列表(月结 `calculateButlerSettlement`,SC-H-07) |
 | `POST /api/admin/butler/assignments` | 管家-家庭分配关系列表(SC-H-01/H-03) |

+ 26 - 46
docs/tdd/orchestration/report-deploy-2026-11-14-4c0ff6729.md

@@ -1,63 +1,42 @@
-# 部署回执:4c0ff6729 → testing(2026-11-14 22:30)
+# 部署回执:4c0ff6729 → testing(2026-11-14 22:43)
 
 ## 结论
 
-**目标提交 `4c0ff672994a3f7f5081604dc7968b01a4afe13c`(S-cfc-369 测评预约创建前校验所选规划师 ∈ 家庭已绑定 T 列表)部署 FAILED —— 目标提交自身含启动阻断缺陷(与 d363df8056 同源:`butlerResourceMatchService` bean 名冲突),部署链自动回滚,目标改动**未**真实运行在 testing 环境。**
+**目标提交 `4c0ff672994a3f7f5081604dc7968b01a4afe13c`(S-cfc-369 测评预约创建前校验所选规划师 ∈ 家庭已绑定 T 列表)已真实部署并运行在 testing 环境,部署成功。**
 
-testing 当前线上版本为 **`c2180785a3e186bbff59798a594beb8e5a0cef7e`**(构建于 2026-11-14 14:31,md5 `2e116d30e16cc6d4b215f99999c3892f`,最后一次成功启动版)。目标提交 `4c0ff6729` **不是** `c2180785` 的祖先:
-`git merge-base --is-ancestor 4c0ff6729 c2180785` → **不成立**,目标改动未打进线上 JAR。
+testing 当前线上版本为 **`39b8d7fed81a58864b2f9d5d63c6e919030de168`**(部署链 22:34:13 写入 state,其后 22:41 并行精确部署回滚后 state 复写为同一值),其纯净构建源为 **`f3699cf64a9315f8d003dc114a3296594d9d2193`**(= `17829760` 启动阻断修复 + 目标提交 + 本回执 docs 提交)。`git merge-base --is-ancestor 4c0ff6729 39b8d7fe` → 成立,且目标 2 个后端文件在 `4c0ff6729..39b8d7fe` 间 **0 行差异(字节一致)**,目标改动完整打进线上 JAR 并通过健康检查。
 
-## 根因(目标提交自身代码缺陷,非部署链问题)
+## 部署方式与过程(含一次启动阻断阻塞 + 修复落地)
 
-目标提交 `4c0ff6729` 含 `d363df8056`(`feat(butler): 实现资源匹配服务 SC-H-05`)引入的启动阻断缺陷:
+1. **初始阻塞**:目标提交 `4c0ff6729` 自身含 `d363df8056` 引入的启动阻断缺陷(`ButlerResourceMatchService` 字段 `@Resource private ButlerResourceFollowUpMapper followUpMapper;` 与既有 `FollowUpMapper` bean 名 `followUpMapper` 冲突 → `BeanNotOfRequiredTypeException` → Spring 上下文取消 → `APPLICATION FAILED TO START`)。部署链自 14:31 起每轮(14:45/…/22:14)构建 → 安装 → 启动失败 → 回滚,线上维持 `c2180785` 构建(md5 `2e116d30...`),目标改动**未**在线上(`javap` 运行 JAR 无 `requireBoundPlanner`/`guideFamilyService`/`请先绑定规划师`;无 `ButlerResourceMatch*` 类)。
+2. **修复落地**:研发侧提交 `17829760`(`fix(butler): 修复 @Resource Bean 撞名致 Spring 启动阻断`,字段重命名 `followUpMapper` → `butlerResourceFollowUpMapper`,含同类 `HealthDataSourceBridgeService` 修复)入 `origin/cfclub`,且为目标的祖先。
+3. **部署链执行**:`/home/iwt/cfc-deploy-251.sh`(部署链:origin/cfclub 更新检测 → 纯净 worktree 构建 → JAR 校验 → 停旧进程 → 装新 JAR → 启动健康检查 → 前端/H5 产物部署 → 最终验证 → auto-bump 回写 + 写 state)检测更新至 `f3699cf64`,22:29:13 后端构建成功 → 22:31:21 前端构建成功 (v1.0.2500) → 22:33:33 部署 commit `f3699cf64` → 22:33:39 装新 JAR → 22:34:05 **`Started CfcApplication in 25.607s`(PID 2460172)** → 22:34:07 后端健康通过(401) → 22:34:13 写 state(`39b8d7fe`,auto-bump commit)。
+4. **并行精确部署回滚(已自愈,非本部署责任)**:22:35 起另一会话 `cfc-deploy-precise.sh`(目标 `677e6153d1`)在 22:40:29 备份当前 JAR → 22:40:32 安装其 JAR(PID 2533180)→ 22:40:59 **启动失败**(`677e6153d1` 自身亦含启动阻断)→ 22:41:00 回滚**恢复本部署 JAR**(md5 `722be485`,PID 2546904)→ 22:41:31 健康通过(401) → 22:41:31 state 复写 `39b8d7fe`。**回滚恢复的即本部署的 `f3699cf64` 构建 JAR,目标改动仍在线上。**
 
-```java
-// cfc-backend/.../service/ButlerResourceMatchService.java:46(目标提交内,与 origin/cfclub HEAD 3afa2ef28 字节一致)
-@Resource
-private ButlerResourceFollowUpMapper followUpMapper;
-```
-
-Spring `@Resource` **按 bean 名优先解析**。MyBatis-Plus 已将**既有** `FollowUpMapper` 接口注册为 bean 名
-`followUpMapper`(接口简单名首字母小写),故 Spring 将类型为 `FollowUpMapper` 的 JDK 代理
-(`$Proxy388/$Proxy389`)注入到类型为 `ButlerResourceFollowUpMapper` 的字段 → 类型不匹配
-`BeanNotOfRequiredTypeException` → Spring 上下文初始化取消 → `APPLICATION FAILED TO START`。
-
-`git merge-base --is-ancestor d363df8056 4c0ff6729` → 成立,即目标提交**确含**该缺陷;
-`git diff 4c0ff6729 origin/cfclub -- ButlerResourceMatchService.java` → 0 行(缺陷在 origin HEAD `3afa2ef28` 仍存在,未在提交线内修复)。
-
-## 部署证据
+## 证据
 
 | 项 | 值 |
 |----|----|
-| 目标提交 | `4c0ff672994a3f7f5081604dc7968b01a4afe13c`(S-cfc-369:AssessmentAppointmentController +21/-1、AssessmentAppointmentService +18,合计 2 文件 +38/-1;authored 2026-11-14 15:55:22 +0800) |
-| 实际线上 commit | `c2180785a3e186bbff59798a594beb8e5a0cef7e`(Merge 2026-11-14 14:27:09,构建 14:31,14:36 安装、14:37 健康通过的最后一次成功启动版) |
-| 线上 JAR(state md5 与磁盘一致) | md5 `2e116d30e16cc6d4b215f99999c3892f`,类时间戳 2026-11-14 14:31 |
-| 祖先关系 | `git merge-base --is-ancestor 4c0ff6729 c2180785` → **不成立**(目标改动不在运行版中) |
-| 目标是否在运行 JAR | **否**:`javap -p` 运行 JAR 的 `AssessmentAppointmentService.class` 无 `requireBoundPlanner` 方法(0 处);常量池无 `guideFamilyService`/`请先绑定规划师`/`isBound` 字符串;JAR 内 `ButlerResourceMatch*` 类 0 个(运行版早于缺陷与目标) |
-| 缺陷祖先关系 | `git merge-base --is-ancestor d363df8056 4c0ff6729` → 成立(目标提交含缺陷) |
-| 缺陷字节一致性 | `git diff 4c0ff6729 origin/cfclub -- ButlerResourceMatchService.java` → 0 行(缺陷未在提交线内修复,origin HEAD `3afa2ef28` 仍带病) |
-| 部署链失败证据 | `/home/iwt/cfc-deploy.log`:自 14:31 起每轮(14:45/14:55/15:05/.../20:06/21:45/22:06/22:14)安装新 JAR → 启动失败(`butlerResourceMatchService` bean 注入异常 `BeanNotOfRequiredTypeException: Bean named 'followUpMapper' ... $Proxy388`)→ 回滚至上一版健康 JAR |
-| 最近一轮(22:08-22:14) | 部署链检测 origin/cfclub 推进至 `0875a19e3`(含目标提交),22:13:37 装新 JAR → 22:14:03 进程 2247521 启动后退出(同上 bean 异常)→ 22:14:10 回滚启动 PID=2251841 → 22:14:37 健康通过(401) → 22:14:40 state 记录 |
-| 运行进程 | PID=2251841(22:14:10 启动,健康通过),`java -Xms512m -Xmx1024m -jar /sc-data/springboot/cfc/cfc-backend-1.0.0.jar` |
-
-## 健康回执(回执出具时直连探测,2026-11-14 22:25 前后)
+| 目标提交 | `4c0ff672994a3f7f5081604dc7968b01a4afe13c`(S-cfc-369:AssessmentAppointmentController +21/-1、AssessmentAppointmentService +18,2 文件 +38/-1) |
+| 实际线上 commit(state) | `39b8d7fed81a58864b2f9d5d63c6e919030de168`(22:34:13 写入 state,22:41 精确回滚后复写一致) |
+| 构建源 commit | `f3699cf64a9315f8d003dc114a3296594d9d2193`(22:29 纯净 worktree 构建,含目标 + 修复 `17829760`) |
+| 祖先关系 | `git merge-base --is-ancestor 4c0ff6729 39b8d7fe` → 成立(目标改动已进构建源) |
+| 源码一致性 | `git diff 4c0ff6729..39b8d7fe -- <2 个目标后端文件>` → **0 行**(字节一致,目标版本完整进 JAR,其后无回退/改写) |
+| JAR 内容校验 | 线上 JAR(md5 `722be4853718d3f1e7e413d6696f104e` = state `backend_jar_md5` 一致)内含:`AssessmentAppointmentService.class` 的 `public boolean requireBoundPlanner(java.lang.Long, java.lang.Long)` 方法(javap 证实)、常量池 `guideFamilyService`/`isBound`/`requireBoundPlanner`;`AssessmentAppointmentController.class` 常量池 `guideFamilyService`/`requireBoundPlanner`/`请先绑定规划师`;`ButlerResourceMatchService.class` 含修复字段 `butlerResourceFollowUpMapper` |
+| 部署时间轴 | 22:29:13 后端构建成功 → 22:31:21 前端构建成功 → 22:33:33 部署 commit → 22:33:39 装新 JAR + 启动 PID 2460172 → 22:34:05 `Started CfcApplication` → 22:34:07 健康通过(401) → 22:34:13 写 state;22:41 并行精确回滚后 PID 2546904 健康通过(401) |
+| 部署 state | `/home/iwt/.cfc-deploy-state`: `last_commit=39b8d7fe...` `backend_jar_md5=722be4853718d3f1e7e413d6696f104e` |
+| 运行进程 | PID 2546904,`java -Xms512m -Xmx1024m -jar /sc-data/springboot/cfc/cfc-backend-1.0.0.jar`,22:41:00 启动,健康 |
+| 回滚 | 本部署启动健康检查一次通过(22:34:07),未触发回滚;后续并行精确部署(677e6153d1)失败回滚至本部署 JAR |
+
+## 健康回执(回执出具时直连探测,2026-11-14 22:43,连续 3 次稳定)
 
 | 目标 | 探测 | 结果 |
 |------|------|------|
 | 后端(部署基线) | `POST http://localhost:9082/api/admin/foods/list` | 401(无 token 预期)✓ |
+| 目标控制器端点 | `POST http://localhost:9082/api/assessment/appointment/create` | 200(路由已注册,非 404;对照 `/list` → 404)✓ |
 | 管理端 | `http://localhost/admin/`(Host: cfc.iwintrue.com) | 200 ✓ |
 | 小程序 H5 | `http://localhost/frontend/`(Host: cfc.iwintrue.com) | 200 ✓ |
-| 后端 JAR 状态 | md5 `2e116d30...` = state `backend_jar_md5` | 一致 ✓ |
-
-## 状态文件失真说明(部署脚本既有缺陷,需知悉)
-
-`/home/iwt/.cfc-deploy-state` 当前 `last_commit=cdf81991bf904a557f5e2150fbdf3036e3b8e909`(`chore: auto bump version and changelog`,2026-11-14 21:46:30),**非真实运行版本**。部署脚本回滚路径将 `ACTUAL_COMMIT` 置为 `$LAST_COMMIT`,随后 auto-bump 步骤又覆盖 `ACTUAL_COMMIT=$(git rev-parse HEAD)`,故 state 的 `last_commit` 为 auto-bump 提交,而线上实际 JAR 为 `c2180785` 构建(md5 `2e116d30...`)。判定线上版本必须以**线上 JAR md5 + JAR 内类字节码**为准,勿以 state `last_commit` 为准。
-
-## 后续处置(属研发侧,非本次部署职责)
-
-- 修复方向(已按 d363df8056 报告预案实施于共享工作区,但**尚未提交/推送**):`ButlerResourceMatchService.followUpMapper` 字段重命名为 `butlerResourceFollowUpMapper`(工作区已见,另 `HealthDataSourceBridgeService.dimensionScoreService` → `healthDimensionScoreService` 同类修复)。
-- 修复提交并推送 `origin/cfclub` 后,部署链 cron 才会自动构建部署;本轮部署链对带病提交的每轮尝试均正确回滚,未产生数据/服务损坏。
-- ⚠️ 目标 `4c0ff6729` 的 S-cfc-369 改动本身(`requireBoundPlanner`/`guideFamilyService`)不在线上;修复提交落地后需重新部署并复验。
+| 后端 JAR 状态 | md5 `722be485...` = state `backend_jar_md5` | 一致 ✓ |
 
 ## 说明
 
@@ -65,5 +44,6 @@ Spring `@Resource` **按 bean 名优先解析**。MyBatis-Plus 已将**既有**
   `--deploy-done testing --commit <sha>` 由编排侧/负责人在**主分支目录**统一落盘,本会话不处理。
 - 部署链路:`/home/iwt/cfc-deploy-251.sh`(origin/cfclub 更新检测 → 纯净 worktree 构建 → JAR 校验 →
   停旧进程 → 装新 JAR → 启动健康检查 → 前端/H5 产物部署 → 最终验证 → auto-bump 回写 + 写 state)。
-- **实际部署成功的 commit hash(供编排侧 `--deploy-done` 落盘):无**(目标未部署成功,部署链自动回滚;
-  线上维持 `c2180785a3e186bbff59798a594beb8e5a0cef7e` 构建)。
+- **实际部署成功的 commit hash(供编排侧 `--deploy-done testing --commit` 落盘):`39b8d7fed81a58864b2f9d5d63c6e919030de168`**
+  (state `last_commit`,= 构建源 `f3699cf64` + 前端元数据 auto-bump;目标 `4c0ff6729` 为其祖先、2 个目标文件字节一致,已真实运行在 testing)。
+  注:若编排侧以构建源为准,亦可使用 `f3699cf64a9315f8d003dc114a3296594d9d2193`(后端代码树一致)。