Просмотр исходного кода

feat(S-cfc-349): teacher.client.export 客户档案数据导出(合规) 实现使绿(SC-T-29 G-3 缺口落地)

- 新增 FamilyExportController#exportClientArchive(POST /api/family/export/client-archive):
  统一 Result 包装、导出范围显式入参(familyId 可选)、teacher 角色守卫(GuideFamilyAccessGuard 注入 + params+userId+role 上下文)、空范围返回错误
- GuideFamilyQueryService#exportClientArchive:按 guide_families status='binding' 绑定源聚合 family_members 客户档案,
  phone/idCard 经 DataMaskUtil 强制脱敏(对齐 SC-S-11 口径),不依赖 children 表全字段快照
- TeacherExportContractTest 6 例红→绿(结构契约全过)
Sisyphus 2 дней назад
Родитель
Сommit
22f3fdd5d0

+ 91 - 0
cfc-backend/src/main/java/com/etotem/cfc/controller/FamilyExportController.java

@@ -0,0 +1,91 @@
+package com.etotem.cfc.controller;
+
+import com.etotem.cfc.common.Result;
+import com.etotem.cfc.common.RolesUtil;
+import com.etotem.cfc.service.GuideFamilyAccessGuard;
+import com.etotem.cfc.service.GuideFamilyQueryService;
+import com.etotem.cfc.util.ParamUtils;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestAttribute;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import javax.annotation.Resource;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * 客户档案数据导出(合规,能力键 {@code teacher.client.export},SC-T-29)。
+ *
+ * <p><b>背景</b>:契约缺口 G-3——管理端组织成员 {@code AdminOrgMemberController} 仅
+ * list/add/remove/change-type,无 export;{@code UserController POST /api/user/data-export}
+ * 仅为登录用户本人的个保法数据可携带权导出({@code AccountCleanupService.exportUserData}),
+ * 不覆盖「规划师导出其名下客户档案」的机构视角批量导出。本控制器补全该缺口。</p>
+ *
+ * <p><b>入口</b>:{@code POST /api/family/export/client-archive}</p>
+ * <ul>
+ *   <li><b>导出范围显式入参</b>:body {@code {familyId?: Long}}——非空则仅导出该绑定家庭的客户
+ *       (越授权可拒,TC-T-29-E 边界流);为空则导出规划师全部绑定客户,无绑定客户时返回错误。</li>
+ *   <li><b>角色守卫</b>:teacher 角色(admin 兜底),授权源与 {@code isBound()} 同源
+ *       ({@code guide_families.status='binding'},SC-T-13 同源,TC-T-29-P 权限流)。</li>
+ *   <li><b>返回</b>:统一 {@link Result} 包装(失败 {@code Result.error},不裸抛异常)。</li>
+ *   <li><b>合规</b>:敏感字段(phone/idCard)强制脱敏({@code DataMaskUtil},
+ *       对齐 SC-S-11 {@code supplier.data.exportCompliance} 契约口径)。</li>
+ * </ul>
+ */
+@Slf4j
+@RestController
+@RequestMapping("/api/family/export")
+public class FamilyExportController {
+
+    /** 全项目唯一授权判定点:绑定关系(guide_families.status='binding')即导出授权源 */
+    @Resource
+    private GuideFamilyAccessGuard guideFamilyAccessGuard;
+
+    @Resource
+    private GuideFamilyQueryService guideFamilyQueryService;
+
+    /**
+     * 规划师导出客户档案(批量/按家庭)。
+     *
+     * @param params  导出范围入参:{@code familyId} 可选(非空则仅导出该绑定家庭客户)
+     * @param userId  当前登录用户(JWT)
+     * @param roleObj 主角色(JWT role claim)
+     * @param roles   完整角色列表(JWT roles claim)
+     */
+    @PostMapping("/client-archive")
+    public Result<Map<String, Object>> exportClientArchive(
+            @RequestBody(required = false) Map<String, Object> params,
+            @RequestAttribute(value = "userId", required = false) Long userId,
+            @RequestAttribute(value = "role", required = false) Object roleObj,
+            @RequestAttribute(value = "roles", required = false) List<String> roles) {
+        if (params == null) {
+            params = new HashMap<>();
+        }
+        String role = roleObj != null ? roleObj.toString() : null;
+
+        // 角色守卫:仅 teacher(规划师)或 admin(运营兜底)可导出(TC-T-29-P 权限流)
+        if (!RolesUtil.hasTeacherRole(role, roles) && !"admin".equals(role)) {
+            return Result.error(403, "无权导出客户档案");
+        }
+
+        // 越授权可拒:显式 familyId 须为本人绑定客户;admin 跳过归属校验(与 checkFamilyAccess 口径一致)
+        Long familyId = ParamUtils.getLong(params.get("familyId"));
+        if (familyId != null && !"admin".equals(role)) {
+            Result<Void> denied = guideFamilyAccessGuard.checkBinding(userId, familyId);
+            if (denied != null) {
+                return Result.error(403, "无权导出该客户档案");
+            }
+        }
+
+        Map<String, Object> data = guideFamilyQueryService.exportClientArchive(userId, familyId);
+        // 空范围返回错误(TC-T-29-E 边界流:无绑定客户可导出)
+        if (data.isEmpty()) {
+            return Result.error("暂无可导出的客户档案");
+        }
+        return Result.success(data);
+    }
+}

+ 109 - 0
cfc-backend/src/main/java/com/etotem/cfc/service/GuideFamilyQueryService.java

@@ -1,6 +1,7 @@
 package com.etotem.cfc.service;
 
 import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
+import com.etotem.cfc.common.DataMaskUtil;
 import com.etotem.cfc.entity.Family;
 import com.etotem.cfc.entity.FamilyMember;
 import com.etotem.cfc.entity.GuideFamily;
@@ -92,4 +93,112 @@ public class GuideFamilyQueryService {
         return familyMemberMapper.selectList(
                 new QueryWrapper<FamilyMember>().eq("family_id", familyId));
     }
+
+    /**
+     * 客户档案导出(合规,sc-key-map SC-T-29 → 能力键 {@code teacher.client.export}):
+     * 导出规划师名下绑定家庭({@code guide_families.status='binding'},与 {@code isBound()} 同源授权)的客户档案。
+     *
+     * <p><b>导出范围显式入参</b>:{@code familyId} 非空 → 仅导出该绑定家庭的客户(越授权拦截由调用方守卫
+     * {@code GuideFamilyAccessGuard#checkBinding} 负责);为 null → 导出全部绑定客户。</p>
+     *
+     * <p><b>合规口径</b>:敏感字段 {@code phone/idCard} 强制脱敏({@link DataMaskUtil},对齐 SC-S-11
+     * {@code supplier.data.exportCompliance} 契约口径,个保法最小化)。</p>
+     *
+     * <p><b>历史约束</b>:不依赖 {@code children} 表全字段快照(生产缺 {@code phone/id_card} 两列,
+     * 见根 AGENTS.md「children 表标注冲突」),统一经 {@code family_members} 聚合导出。</p>
+     *
+     * @param guideId  规划师(teacher)userId
+     * @param familyId 可选导出范围(家庭ID);null 导出全部绑定客户
+     * @return 导出包:{@code {families:[{familyId, familyName, serviceType, boundAt, clients:[{memberId, nickname,
+     *         phone(脱敏), idCard(脱敏), gender, age, birthday, memberType}]}]}};无绑定客户时返回空 Map
+     */
+    public Map<String, Object> exportClientArchive(Long guideId, Long familyId) {
+        Map<String, Object> out = new HashMap<>();
+        List<GuideFamily> bindings;
+        if (familyId != null) {
+            bindings = guideFamilyMapper.selectList(
+                    new QueryWrapper<GuideFamily>()
+                            .eq("guide_id", guideId)
+                            .eq("family_id", familyId)
+                            .eq("status", "binding"));
+        } else {
+            bindings = guideFamilyMapper.selectList(
+                    new QueryWrapper<GuideFamily>()
+                            .eq("guide_id", guideId)
+                            .eq("status", "binding")
+                            .orderByDesc("bound_at"));
+        }
+        if (bindings == null || bindings.isEmpty()) {
+            return out;
+        }
+
+        List<Long> familyIds = bindings.stream()
+                .map(GuideFamily::getFamilyId)
+                .filter(Objects::nonNull)
+                .distinct()
+                .collect(Collectors.toList());
+
+        Map<Long, String> nameByFamily = new HashMap<>();
+        if (!familyIds.isEmpty()) {
+            List<Family> families = familyMapper.selectBatchIds(familyIds);
+            if (families != null) {
+                for (Family f : families) {
+                    if (f != null && f.getId() != null) {
+                        nameByFamily.put(f.getId(), f.getName());
+                    }
+                }
+            }
+        }
+
+        Map<Long, List<FamilyMember>> membersByFamily = new HashMap<>();
+        if (!familyIds.isEmpty()) {
+            List<FamilyMember> members = familyMemberMapper.selectList(
+                    new QueryWrapper<FamilyMember>().in("family_id", familyIds));
+            if (members != null) {
+                for (FamilyMember m : members) {
+                    if (m == null || m.getFamilyId() == null) {
+                        continue;
+                    }
+                    membersByFamily.computeIfAbsent(m.getFamilyId(), k -> new ArrayList<>()).add(m);
+                }
+            }
+        }
+
+        List<Map<String, Object>> families = new ArrayList<>();
+        for (GuideFamily gf : bindings) {
+            Long fid = gf.getFamilyId();
+            if (fid == null) {
+                continue;
+            }
+            Map<String, Object> familyRow = new HashMap<>();
+            familyRow.put("familyId", fid);
+            familyRow.put("familyName", nameByFamily.get(fid));
+            familyRow.put("serviceType", gf.getServiceType());
+            familyRow.put("boundAt", gf.getBoundAt());
+            List<Map<String, Object>> clients = new ArrayList<>();
+            List<FamilyMember> mbrs = membersByFamily.getOrDefault(fid, Collections.emptyList());
+            for (FamilyMember m : mbrs) {
+                clients.add(toMaskedClient(m));
+            }
+            familyRow.put("clients", clients);
+            families.add(familyRow);
+        }
+        out.put("families", families);
+        return out;
+    }
+
+    /** 客户档案单行导出载体:敏感字段(phone/idCard)强制脱敏。 */
+    private Map<String, Object> toMaskedClient(FamilyMember m) {
+        Map<String, Object> client = new HashMap<>();
+        client.put("memberId", m.getId());
+        client.put("nickname", m.getNickname());
+        client.put("gender", m.getGender());
+        client.put("age", m.getAge());
+        client.put("birthday", m.getBirthday());
+        client.put("memberType", m.getMemberType());
+        // 合规:个保法最小化,对齐 SC-S-11 supplier.data.exportCompliance 契约口径
+        client.put("phone", DataMaskUtil.maskPhone(m.getPhone()));
+        client.put("idCard", DataMaskUtil.maskIdCard(m.getIdCard()));
+        return client;
+    }
 }