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

feat(admin.familyRelation.manage): S-cfc-387 关系类型字典 CRUD 实现使绿

SC-A-04 平台运营·关系类型 CRUD 管理(能力键 admin.familyRelation.manage):
- 新增 AdminFamilyRelationController(/api/admin/family-relation/types/list|save|update|disable)
  承载关系类型字典列表/新增/编辑/停用,类级挂 /api/admin 前缀 + admin/operator 角色门禁
- 新增 AdminFamilyRelationService:type_key/type_name 唯一(新增重名拒绝 TC-A-10-E)、
  名称注入 400 拒绝、停用前按 family_relationships 引用检查提示先解绑(SC-A-04 边界)
- 新增 FamilyRelationType 实体 + FamilyRelationTypeMapper(字典表 family_relation_types,迁移494)
- DatabaseInitializer 迁移494 建表 + 空表播种默认 6 类(spouse/parent/child/sibling/grandparent/grandchild)
- schema.sql 同步 family_relation_types 定义与种子;API_REFERENCE.md 新增 §4.66 并关闭 §4.60.18 SC-A-04 缺口行

契约测试 AdminFamilyRelationManageContractTest:8 失败 → 0 失败(8 通过)
Sisyphus 12 часов назад
Родитель
Сommit
3bd4de7dc7

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

@@ -3636,6 +3636,56 @@ insertSysConfigSeed("gift_membership_pay_price", "198000", "送会员商品达
         // 新建 4 表(cf_team_share_config/cf_team_pool_order/cf_team_pool_share/cf_platform_revenue_log)
         // + ensureServiceConfig 播种 6 键 + F03c 种子(seedCfEarnRules / seedCfServiceConfig 内已含)
         migrateCfRewardV2TeamPool();
+
+        // 迁移494: 家庭关系类型字典表 family_relation_types(SC-A-04 关系类型 CRUD 管理,
+        // admin.familyRelation.manage)。v2 辈分重构后 relationship_types 已废弃 DROP(迁移169),
+        // 此处重建字典作为管理端关系类型列表/新增/编辑/停用的数据载体;表名避开历史
+        // relationship_types(迁移169 历史 DROP 会在每次启动清表,勿复用该名)。
+        migrateFamilyRelationTypes();
+    }
+
+
+    /**
+     * 迁移494: 创建家庭关系类型字典表 family_relation_types + 默认字典种子
+     * (SC-A-04 关系类型 CRUD,能力键 admin.familyRelation.manage)。
+     *
+     * <p>幂等:CREATE TABLE IF NOT EXISTS + 空表才播种默认 6 类(spouse/parent/child/
+     * sibling/grandparent/grandchild,对应 v2 generation 辈分模型)。运营停用后不再回填。</p>
+     */
+    private void migrateFamilyRelationTypes() {
+        try {
+            jdbcTemplate.execute("CREATE TABLE IF NOT EXISTS family_relation_types ("
+                    + "id BIGINT AUTO_INCREMENT PRIMARY KEY, "
+                    + "type_key VARCHAR(50) NOT NULL UNIQUE COMMENT '类型标识: spouse/parent/child/sibling/grandparent/grandchild', "
+                    + "type_name VARCHAR(100) NOT NULL COMMENT '类型显示名: 配偶/父母/子女/兄弟姐妹/祖父母/孙辈', "
+                    + "generation_value INT DEFAULT 0 COMMENT '辈分值: 0=同辈, 1=父母, -1=子女, 2=祖辈, -2=孙辈', "
+                    + "sort_order INT DEFAULT 0 COMMENT '排序序号', "
+                    + "enabled INT DEFAULT 1 COMMENT '是否启用: 1=启用, 0=停用', "
+                    + "remark VARCHAR(255) DEFAULT NULL COMMENT '备注', "
+                    + "created_at DATETIME DEFAULT CURRENT_TIMESTAMP, "
+                    + "updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP"
+                    + ") ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='家庭关系类型字典表(关系类型 CRUD 管理)'");
+            log.info("迁移494: family_relation_types 表已就绪");
+        } catch (Exception e) {
+            log.warn("迁移494: family_relation_types 表创建失败(忽略): {}", e.getMessage());
+        }
+        try {
+            Integer cnt = jdbcTemplate.queryForObject("SELECT COUNT(*) FROM family_relation_types", Integer.class);
+            if (cnt != null && cnt > 0) {
+                return;
+            }
+            jdbcTemplate.update("INSERT INTO family_relation_types "
+                    + "(type_key, type_name, generation_value, sort_order, enabled) VALUES "
+                    + "('spouse', '配偶', 0, 1, 1), "
+                    + "('parent', '父母', 1, 2, 1), "
+                    + "('child', '子女', -1, 3, 1), "
+                    + "('sibling', '兄弟姐妹', 0, 4, 1), "
+                    + "('grandparent', '祖父母', 2, 5, 1), "
+                    + "('grandchild', '孙辈', -2, 6, 1)");
+            log.info("迁移494: family_relation_types 默认字典种子已写入 6 行");
+        } catch (Exception e) {
+            log.warn("迁移494: family_relation_types 种子写入失败(忽略): {}", e.getMessage());
+        }
     }
 
 

+ 75 - 0
cfc-backend/src/main/java/com/etotem/cfc/controller/admin/AdminFamilyRelationController.java

@@ -0,0 +1,75 @@
+package com.etotem.cfc.controller.admin;
+
+import com.etotem.cfc.common.Result;
+import com.etotem.cfc.entity.FamilyRelationType;
+import com.etotem.cfc.service.AdminFamilyRelationService;
+import com.etotem.cfc.util.ParamUtils;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+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.List;
+import java.util.Map;
+
+/**
+ * 管理端-家庭关系类型字典 CRUD(SC-A-04 / TC-A-10,能力键 admin.familyRelation.manage)。
+ *
+ * <p>契约:{@code /api/admin/family-relation/types} 承载关系类型字典增删改查
+ * (列表/新增/编辑/停用)。项目接口统一 {@code @PostMapping},故按语义子路径落地
+ * ({@code /types/list|save|update|disable},等价于契约的 GET/POST/PUT/DELETE 动词语义,
+ * 由契约测试按语义操作探测)。类级映射挂 {@code /api/admin} 前缀 → JwtInterceptor 整族
+ * 强制登录 + 控制器内 admin/operator 角色门禁(TC-A-10-P 非 admin 统一 401/403)。</p>
+ */
+@Tag(name = "管理端-家庭关系类型", description = "关系类型字典 CRUD 管理(admin.familyRelation.manage)")
+@RestController
+@RequestMapping("/api/admin/family-relation")
+public class AdminFamilyRelationController {
+
+    @Resource
+    private AdminFamilyRelationService adminFamilyRelationService;
+
+    @Operation(summary = "关系类型字典列表(含停用)")
+    @PostMapping("/types/list")
+    public Result<List<FamilyRelationType>> typesList(@RequestAttribute("role") String role) {
+        if (!"admin".equals(role) && !"operator".equals(role)) {
+            return Result.forbidden("无权限:仅平台管理员可管理关系类型");
+        }
+        return adminFamilyRelationService.list();
+    }
+
+    @Operation(summary = "新增关系类型(重名拒绝,TC-A-10-E)")
+    @PostMapping("/types/save")
+    public Result<FamilyRelationType> typesSave(@RequestBody FamilyRelationType type,
+                                                @RequestAttribute("role") String role) {
+        if (!"admin".equals(role) && !"operator".equals(role)) {
+            return Result.forbidden("无权限:仅平台管理员可管理关系类型");
+        }
+        return adminFamilyRelationService.create(type);
+    }
+
+    @Operation(summary = "编辑关系类型")
+    @PostMapping("/types/update")
+    public Result<FamilyRelationType> typesUpdate(@RequestBody FamilyRelationType type,
+                                                  @RequestAttribute("role") String role) {
+        if (!"admin".equals(role) && !"operator".equals(role)) {
+            return Result.forbidden("无权限:仅平台管理员可管理关系类型");
+        }
+        return adminFamilyRelationService.update(type);
+    }
+
+    @Operation(summary = "停用关系类型(被引用时提示先解绑,SC-A-04 边界)")
+    @PostMapping("/types/disable")
+    public Result<Void> typesDisable(@RequestBody(required = false) Map<String, Object> params,
+                                     @RequestAttribute("role") String role) {
+        if (!"admin".equals(role) && !"operator".equals(role)) {
+            return Result.forbidden("无权限:仅平台管理员可管理关系类型");
+        }
+        Long id = params != null ? ParamUtils.getLong(params.get("id")) : null;
+        return adminFamilyRelationService.disable(id);
+    }
+}

+ 47 - 0
cfc-backend/src/main/java/com/etotem/cfc/entity/FamilyRelationType.java

@@ -0,0 +1,47 @@
+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;
+
+/**
+ * 家庭关系类型字典(SC-A-04 / TC-A-10,能力键 admin.familyRelation.manage)。
+ *
+ * <p>v2 辈分重构后 {@code relationship_types} 表已废弃 DROP,关系由
+ * {@code family_relationships}(generation 辈分模型)承载;本表重建「关系类型字典」
+ * 作为管理端关系类型 CRUD(列表/新增/编辑/停用)的唯一数据载体,供关系选择器取可用类型
+ * (迁移494)。表名避开历史 {@code relationship_types} 以不与迁移169 的历史 DROP 冲突。</p>
+ */
+@Data
+@TableName("family_relation_types")
+public class FamilyRelationType implements Serializable {
+
+    @TableId(type = IdType.AUTO)
+    private Long id;
+
+    /** 类型标识(唯一): spouse/parent/child/sibling/grandparent/grandchild */
+    private String typeKey;
+
+    /** 类型显示名(唯一,新增重名拒绝): 配偶/父母/子女/兄弟姐妹/祖父母/孙辈 */
+    private String typeName;
+
+    /** 辈分值(关系生成/选择器映射): 0=同辈, 1=父母, -1=子女, 2=祖辈, -2=孙辈 */
+    private Integer generationValue;
+
+    /** 排序序号 */
+    private Integer sortOrder;
+
+    /** 是否启用: 1=启用, 0=停用 */
+    private Integer enabled;
+
+    /** 备注 */
+    private String remark;
+
+    private Date createdAt;
+
+    private Date updatedAt;
+}

+ 7 - 0
cfc-backend/src/main/java/com/etotem/cfc/mapper/FamilyRelationTypeMapper.java

@@ -0,0 +1,7 @@
+package com.etotem.cfc.mapper;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.etotem.cfc.entity.FamilyRelationType;
+
+public interface FamilyRelationTypeMapper extends BaseMapper<FamilyRelationType> {
+}

+ 168 - 0
cfc-backend/src/main/java/com/etotem/cfc/service/AdminFamilyRelationService.java

@@ -0,0 +1,168 @@
+package com.etotem.cfc.service;
+
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.etotem.cfc.common.Result;
+import com.etotem.cfc.entity.FamilyRelationType;
+import com.etotem.cfc.entity.FamilyRelationship;
+import com.etotem.cfc.mapper.FamilyRelationTypeMapper;
+import com.etotem.cfc.mapper.FamilyRelationshipMapper;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Service;
+import org.springframework.util.StringUtils;
+
+import javax.annotation.Resource;
+import java.util.Date;
+import java.util.List;
+import java.util.regex.Pattern;
+
+/**
+ * 家庭关系类型字典管理(SC-A-04 / TC-A-10,能力键 admin.familyRelation.manage)。
+ *
+ * <p>Web 管理端关系类型 CRUD(列表/新增/编辑/停用)的数据载体 {@code family_relation_types};
+ * 停用前按 v2 模型检查 {@code family_relationships} 引用(relation_type = type_key,
+ * 同辈 spouse/sibling 类存在直接引用;直系称谓由 generation+性别派生计算,不走字典行)。
+ * 名称唯一(TC-A-10-E 新增重名拒绝)+ 注入防护(名称含注入 400 拒绝)。</p>
+ */
+@Slf4j
+@Service
+public class AdminFamilyRelationService {
+
+    /** typeKey 合法格式:小写字母开头 + 小写字母/数字/下划线 */
+    private static final Pattern TYPE_KEY_PATTERN = Pattern.compile("^[a-z][a-z0-9_]{0,49}$");
+
+    /** 名称/备注禁止的注入字符(SQL 注入/脚本注入,TC-A-10-E) */
+    private static final Pattern FORBIDDEN_CHARS = Pattern.compile("[<>\"'`;\\\\]");
+
+    @Resource
+    private FamilyRelationTypeMapper relationTypeMapper;
+
+    @Resource
+    private FamilyRelationshipMapper familyRelationshipMapper;
+
+    /** 管理端关系类型字典列表(含停用,按排序 + ID 升序) */
+    public Result<List<FamilyRelationType>> list() {
+        LambdaQueryWrapper<FamilyRelationType> wrapper = new LambdaQueryWrapper<FamilyRelationType>()
+                .orderByAsc(FamilyRelationType::getSortOrder)
+                .orderByAsc(FamilyRelationType::getId);
+        return Result.success(relationTypeMapper.selectList(wrapper));
+    }
+
+    /** 新增关系类型(type_key / type_name 唯一,重名拒绝;名称含注入 400 拒绝) */
+    public Result<FamilyRelationType> create(FamilyRelationType type) {
+        if (type == null) {
+            return Result.badRequest("参数不能为空");
+        }
+        Result<FamilyRelationType> checked = validateAndNormalize(type, null);
+        if (checked != null) {
+            return checked;
+        }
+        Date now = new Date();
+        type.setId(null);
+        type.setCreatedAt(now);
+        type.setUpdatedAt(now);
+        relationTypeMapper.insert(type);
+        log.info("家庭关系类型新增: id={}, key={}, name={}", type.getId(), type.getTypeKey(), type.getTypeName());
+        return Result.success(type);
+    }
+
+    /** 编辑关系类型(重名校验排除自身;不允许改 type_key) */
+    public Result<FamilyRelationType> update(FamilyRelationType type) {
+        if (type == null || type.getId() == null) {
+            return Result.badRequest("缺少 id,无法编辑关系类型");
+        }
+        FamilyRelationType exists = relationTypeMapper.selectById(type.getId());
+        if (exists == null) {
+            return Result.notFound("关系类型不存在: id=" + type.getId());
+        }
+        Result<FamilyRelationType> checked = validateAndNormalize(type, type.getId());
+        if (checked != null) {
+            return checked;
+        }
+        // type_key 是引用锚点(family_relationships.relation_type 同值),不允许变更
+        type.setTypeKey(exists.getTypeKey());
+        type.setCreatedAt(null);
+        type.setUpdatedAt(new Date());
+        relationTypeMapper.updateById(type);
+        log.info("家庭关系类型编辑: id={}, name={}", type.getId(), type.getTypeName());
+        return Result.success(type);
+    }
+
+    /**
+     * 停用关系类型(enabled=0)。
+     * SC-A-04 边界 + TC-A-10-E 步骤2:被 {@code family_relationships} 引用时拒绝,
+     * 提示先解绑(spouse/sibling 类通过 relation_type 直接引用;直系称谓由
+     * generation+性别派生,不构成字典行引用)。
+     */
+    public Result<Void> disable(Long id) {
+        if (id == null) {
+            return Result.badRequest("缺少 id,无法停用关系类型");
+        }
+        FamilyRelationType exists = relationTypeMapper.selectById(id);
+        if (exists == null) {
+            return Result.notFound("关系类型不存在: id=" + id);
+        }
+        long refs = familyRelationshipMapper.selectCount(
+                new LambdaQueryWrapper<FamilyRelationship>()
+                        .eq(FamilyRelationship::getRelationType, exists.getTypeKey())
+                        .or()
+                        .eq(FamilyRelationship::getRelationshipKey, exists.getTypeName()));
+        if (refs > 0) {
+            return Result.conflict("该关系类型已被 " + refs + " 条家庭关系引用,请先解绑后再停用");
+        }
+        exists.setEnabled(0);
+        exists.setUpdatedAt(new Date());
+        relationTypeMapper.updateById(exists);
+        log.info("家庭关系类型停用: id={}, key={}, name={}", id, exists.getTypeKey(), exists.getTypeName());
+        return Result.success(null);
+    }
+
+    /** 公共校验 + 缺省值归一化:失败返回 Result,成功返回 null(excludeId 用于编辑排除自身)。 */
+    private Result<FamilyRelationType> validateAndNormalize(FamilyRelationType type, Long excludeId) {
+        String key = type.getTypeKey();
+        if (!StringUtils.hasText(key)) {
+            return Result.badRequest("类型标识 typeKey 不能为空");
+        }
+        key = key.trim().toLowerCase();
+        if (!TYPE_KEY_PATTERN.matcher(key).matches()) {
+            return Result.badRequest("类型标识只能是小写字母开头的字母/数字/下划线");
+        }
+        type.setTypeKey(key);
+
+        String name = type.getTypeName();
+        if (!StringUtils.hasText(name)) {
+            return Result.badRequest("类型名称不能为空");
+        }
+        name = name.trim();
+        if (name.length() > 100) {
+            return Result.badRequest("类型名称过长(最多100字符)");
+        }
+        if (FORBIDDEN_CHARS.matcher(name).find() || FORBIDDEN_CHARS.matcher(key).find()) {
+            return Result.badRequest("类型名称/标识含非法字符,已拒绝");
+        }
+        type.setTypeName(name);
+
+        if (type.getSortOrder() == null) {
+            type.setSortOrder(0);
+        }
+        if (type.getEnabled() == null) {
+            type.setEnabled(1);
+        }
+        // type_key 唯一
+        FamilyRelationType keyDup = relationTypeMapper.selectOne(
+                new LambdaQueryWrapper<FamilyRelationType>()
+                        .eq(FamilyRelationType::getTypeKey, key)
+                        .last("LIMIT 1"));
+        if (keyDup != null && (excludeId == null || !keyDup.getId().equals(excludeId))) {
+            return Result.error("关系类型标识已存在: " + key);
+        }
+        // type_name 唯一(TC-A-10-E 新增重名拒绝)
+        FamilyRelationType nameDup = relationTypeMapper.selectOne(
+                new LambdaQueryWrapper<FamilyRelationType>()
+                        .eq(FamilyRelationType::getTypeName, name)
+                        .last("LIMIT 1"));
+        if (nameDup != null && (excludeId == null || !nameDup.getId().equals(excludeId))) {
+            return Result.error("关系类型名称已存在: " + name);
+        }
+        return null;
+    }
+}

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

@@ -2341,6 +2341,30 @@ CREATE TABLE IF NOT EXISTS family_relationships (
     INDEX idx_to (to_member_id)
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='家庭成员双向关系表';
 
+-- 家庭关系类型字典表(SC-A-04 关系类型 CRUD 管理,admin.familyRelation.manage;迁移494)
+-- v2 辈分重构后 relationship_types 已废弃 DROP(迁移169),本表重建字典作为管理端
+-- 关系类型列表/新增/编辑/停用的数据载体(表名避开历史 relationship_types 防启动清表)
+CREATE TABLE IF NOT EXISTS family_relation_types (
+    id                BIGINT AUTO_INCREMENT PRIMARY KEY,
+    type_key          VARCHAR(50)  NOT NULL UNIQUE COMMENT '类型标识: spouse/parent/child/sibling/grandparent/grandchild',
+    type_name         VARCHAR(100) NOT NULL COMMENT '类型显示名: 配偶/父母/子女/兄弟姐妹/祖父母/孙辈',
+    generation_value  INT DEFAULT 0 COMMENT '辈分值: 0=同辈, 1=父母, -1=子女, 2=祖辈, -2=孙辈',
+    sort_order        INT DEFAULT 0 COMMENT '排序序号',
+    enabled           INT DEFAULT 1 COMMENT '是否启用: 1=启用, 0=停用',
+    remark            VARCHAR(255) DEFAULT NULL COMMENT '备注',
+    created_at        DATETIME DEFAULT CURRENT_TIMESTAMP,
+    updated_at        DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='家庭关系类型字典表(关系类型 CRUD 管理)';
+
+-- 默认关系类型字典种子(迁移494 空表播种,运营可编辑/停用)
+INSERT IGNORE INTO family_relation_types (type_key, type_name, generation_value, sort_order, enabled) VALUES
+('spouse', '配偶', 0, 1, 1),
+('parent', '父母', 1, 2, 1),
+('child', '子女', -1, 3, 1),
+('sibling', '兄弟姐妹', 0, 4, 1),
+('grandparent', '祖父母', 2, 5, 1),
+('grandchild', '孙辈', -2, 6, 1);
+
 -- 【已废弃】relationship_types 表已删除(generation 辈分模型替代)
 
 -- 用户收货地址表

+ 18 - 1
docs/superpowers/api/API_REFERENCE.md

@@ -3181,7 +3181,7 @@ W0.2 双配置中心合并:`product_config` 已并入 `service_config`(唯
 
 | SC | 场景 | 现状 | 处置 |
 |----|------|------|------|
-| SC-A-04 | 关系类型 CRUD | 无 `/api/admin/relationship-types`;`relationship_types` 表已废弃 DROP,关系由 `family_relationships`(`/api/family/member/add|update` + `FamilyRelationshipService`)承载 | 无端点载体,需产品侧确认 |
+| SC-A-04 | 关系类型 CRUD | 已落地:`POST /api/admin/family-relation/types/{list,save,update,disable}`(`AdminFamilyRelationController`,字典表 `family_relation_types`,迁移494);v2 辈分重构后 `relationship_types` 表已废弃 DROP,关系仍由 `family_relationships` 承载 | 已实现(S-cfc-387 GREEN,2026-11-16;见 §4.66) |
 | SC-A-14 | 系统监控/告警 | 仅 `POST /api/system/health`(JVM/内存/CPU 探活),无告警规则/记录端点 | 无端点载体,需产品侧确认 |
 | SC-A-19 | 账号注销/数据导出工单处理 | 无运营工单端点;用户侧自助 `POST /api/user/deactivate`、`POST /api/user/data-export` 已实现 | 无端点载体,需产品侧确认 |
 | SC-A-20 | 限流/熔断配置 | 无 HTTP 配置端点;`RateLimitInterceptor`(Redis 滑动窗口)+ `AiGateway` 熔断为代码内置 | 无端点载体,需产品侧确认 |
@@ -3766,3 +3766,20 @@ W0.2 双配置中心合并:`product_config` 已并入 `service_config`(唯
 | SC-X-18 | 推送跨端送达 | 公众号模板消息 + 微信待办 webhook 已投产;小程序订阅消息(requestSubscribeMessage/subscribeMessage)前后端 0 命中,`WechatNotificationChannel` 预留禁用;cfc-langgraph 无推送 | 缺口 X-G-3,需产品侧确认 |
 > 本批仅登记缺口不实现,转产品/运维侧确认后由后续批次落地。
 *文档更新:2026-11-07(EVD-15 跨角色域剩余 8 SC 契约核对增补「跨角色域剩余」段落 4.65:双角色数据隔离越权 / 文章发布闭环 / 消息通知闭环 / 解绑重分配 / 注销数据导出 / 活动名额并发 / 多端登录互斥 / 推送跨端送达 + 命名回填 2 处 + 契约缺口 3 项。完整核验表见 `docs/superpowers/specs/2026-11-07-cross-role-contract.md`)*
+
+## 4.66 管理端-家庭关系类型(`/api/admin/family-relation`,SC-A-04,2026-11-16)
+> 来源:契约测试 `AdminFamilyRelationManageContractTest`(S-cfc-308 RED → S-cfc-387 GREEN,能力键 `admin.familyRelation.manage`);
+> 用例绑定 `tests/test-cases/admin.md` TC-A-10(功能)/ TC-A-10-E(异常)/ TC-A-10-P(权限);场景 `tests/user-scenarios/应用场景总览.md` SC-A-04。
+> v2 辈分重构后 `relationship_types` 表已废弃 DROP(迁移169),字典重建为 `family_relation_types`(迁移494,表名避开历史 DROP 防启动清表)。
+
+| 路径 | 说明 |
+|------|------|
+| `POST /api/admin/family-relation/types/list` | 关系类型字典列表(含停用,按 sort_order/id 升序;TC-A-10 查询) |
+| `POST /api/admin/family-relation/types/save` | 新增关系类型(type_key/type_name 唯一,重名拒绝;名称含注入 400,TC-A-10-E) |
+| `POST /api/admin/family-relation/types/update` | 编辑关系类型(重名校验排除自身;type_key 为引用锚点不可改) |
+| `POST /api/admin/family-relation/types/disable` | 停用关系类型(`family_relationships` 引用数 >0 时 409 提示先解绑,SC-A-04 边界 + TC-A-10-E) |
+> 载体 = `AdminFamilyRelationController` + `AdminFamilyRelationService` + `family_relation_types` 表。
+> 权限:类级挂 `/api/admin` 前缀(JwtInterceptor 整族强制登录)+ 控制器内 `@RequestAttribute("role")` 校验 admin/operator(非 admin 403,TC-A-10-P)。
+> 语义:项目统一 `@PostMapping`,列表/新增/编辑/停用按语义子路径承载(等价契约的 GET/POST/PUT/DELETE 动词语义)。
+> 停用引用语义:spouse/sibling 类经 `family_relationships.relation_type` 直接引用可被护栏拦截;直系称谓(父亲/母亲…)由 generation+性别派生计算,不构成字典行引用。
+*文档更新:2026-11-16(S-cfc-387 GREEN:SC-A-04 关系类型 CRUD 端点载体落地,关闭 §4.60.18 缺口行)*