Quellcode durchsuchen

S-cfc-353: implement butler.escalation.handle contract (TDD-GREEN) — ButlerEscalationService + entity/mapper/table + family & admin escalation endpoints

Sisyphus vor 1 Tag
Ursprung
Commit
34613f181

+ 46 - 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();
     }
 
     /**
@@ -3756,6 +3761,47 @@ insertSysConfigSeed("gift_membership_pay_price", "198000", "送会员商品达
         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 天逐日趋势。 */
     void addTasksFamilyCreatedIndex() {
         try {

+ 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;
+}

+ 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> {
+}

+ 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);
+    }
+}

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

@@ -3127,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,

+ 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) |