Bladeren bron

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

- 新增 AdminFamilyRelationController /api/admin/family-relation/types/{list,save,update,disable}
- 新增 FamilyRelationTypeService(list/save/update/disable + 重名校验 + 引用计数 + 停用确认守卫)
- 新增 FamilyRelationType 实体 + FamilyRelationTypeMapper(family_relation_types 字典表)
- 迁移497: 创建 family_relation_types 表(DatabaseInitializer + schema.sql 同步)
- 修复 saveType sortOrder 取参(long 与 null 比较编译错误)
- API_REFERENCE.md 补齐 SC-A-04 载体登记与 admin 端点目录

契约单测 AdminFamilyRelationManageContractTest 8/8 全绿(原红 8 → 绿 8)
Administrator 1 dag geleden
bovenliggende
commit
dcac12caf2

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

@@ -3646,6 +3646,9 @@ insertSysConfigSeed("gift_membership_pay_price", "198000", "送会员商品达
 
         // 迁移496: growth_plans 增列 draft_expires_at / draft_version(SC-P-81 方案草稿保存与恢复,能力键 plan.draft.save)
         addGrowthPlanDraftColumns();
+
+        // 迁移497: 创建家庭关系类型字典表(SC-A-04 关系类型 CRUD,能力键 admin.familyRelation.manage)
+        createFamilyRelationTypesTable();
     }
 
 
@@ -4382,6 +4385,34 @@ insertSysConfigSeed("gift_membership_pay_price", "198000", "送会员商品达
         }
     }
 
+    /**
+     * 迁移497: 创建家庭关系类型字典表(SC-A-04 关系类型 CRUD,能力键 admin.familyRelation.manage)。
+     *
+     * <p>管理端关系类型增删改查载体:独立字典表 {@code family_relation_types},不复用已废弃的
+     * {@code relationship_types}(迁移169 已 DROP);引用计数来自 {@code family_relationships.relationship_key}。</p>
+     */
+    private void createFamilyRelationTypesTable() {
+        try {
+            jdbcTemplate.execute("CREATE TABLE IF NOT EXISTS family_relation_types ("
+                    + "id BIGINT AUTO_INCREMENT PRIMARY KEY, "
+                    + "type_key VARCHAR(50) NOT NULL COMMENT '关系类型键', "
+                    + "type_name VARCHAR(50) NOT NULL COMMENT '关系类型名称', "
+                    + "label VARCHAR(50) COMMENT '展示标签', "
+                    + "description VARCHAR(255) COMMENT '说明', "
+                    + "sort_order INT DEFAULT 0 COMMENT '排序号', "
+                    + "enabled TINYINT DEFAULT 1 COMMENT '启用:1 禁用:0', "
+                    + "reference_count INT DEFAULT 0 COMMENT '引用数量(冗余统计)', "
+                    + "created_at DATETIME DEFAULT CURRENT_TIMESTAMP, "
+                    + "updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, "
+                    + "UNIQUE KEY uk_type_key (type_key), "
+                    + "INDEX idx_enabled (enabled)"
+                    + ") ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='家庭关系类型字典'");
+            log.info("迁移497: family_relation_types 表已就绪");
+        } catch (Exception e) {
+            log.warn("迁移497: family_relation_types 创建失败: {}", e.getMessage());
+        }
+    }
+
     /**
      * 迁移452: 创建华为运动健康令牌表(D1 接入)。
      *

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

@@ -0,0 +1,88 @@
+package com.etotem.cfc.controller.admin;
+
+import com.etotem.cfc.common.Result;
+import com.etotem.cfc.entity.FamilyRelationType;
+import com.etotem.cfc.service.FamilyRelationTypeService;
+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.RequestBody;
+import org.springframework.web.bind.annotation.RequestAttribute;
+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;
+
+/**
+ * 管理端:家庭关系类型字典管理(SC-A-04)
+ */
+@Tag(name = "家庭关系类型管理", description = "管理家庭关系类型字典")
+@RestController
+@RequestMapping("/api/admin/family-relation")
+public class AdminFamilyRelationController {
+
+    @Resource
+    private FamilyRelationTypeService familyRelationTypeService;
+
+    @Operation(summary = "关系类型列表")
+    @PostMapping("/types/list")
+    public Result<List<FamilyRelationType>> listTypes(
+            @RequestBody(required = false) Map<String, Object> body,
+            @RequestAttribute("role") String role) {
+        if (!"admin".equals(role)) {
+            return Result.forbidden("无权限");
+        }
+        try {
+            return Result.success(familyRelationTypeService.listTypes(body));
+        } catch (IllegalArgumentException e) {
+            return Result.badRequest(e.getMessage());
+        }
+    }
+
+    @Operation(summary = "新增关系类型")
+    @PostMapping("/types/save")
+    public Result<FamilyRelationType> saveType(
+            @RequestBody Map<String, Object> body,
+            @RequestAttribute("role") String role) {
+        if (!"admin".equals(role)) {
+            return Result.forbidden("无权限");
+        }
+        try {
+            return Result.success(familyRelationTypeService.saveType(body, null));
+        } catch (IllegalArgumentException e) {
+            return Result.badRequest(e.getMessage());
+        }
+    }
+
+    @Operation(summary = "编辑关系类型")
+    @PostMapping("/types/update")
+    public Result<FamilyRelationType> updateType(
+            @RequestBody Map<String, Object> body,
+            @RequestAttribute("role") String role) {
+        if (!"admin".equals(role)) {
+            return Result.forbidden("无权限");
+        }
+        try {
+            return Result.success(familyRelationTypeService.updateType(body));
+        } catch (IllegalArgumentException e) {
+            return Result.badRequest(e.getMessage());
+        }
+    }
+
+    @Operation(summary = "停用关系类型")
+    @PostMapping("/types/disable")
+    public Result<FamilyRelationType> disableType(
+            @RequestBody Map<String, Object> body,
+            @RequestAttribute("role") String role) {
+        if (!"admin".equals(role)) {
+            return Result.forbidden("无权限");
+        }
+        try {
+            return Result.success(familyRelationTypeService.disableType(body));
+        } catch (IllegalArgumentException e) {
+            return Result.badRequest(e.getMessage());
+        }
+    }
+}

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

@@ -0,0 +1,45 @@
+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;
+
+/**
+ * 家庭关系类型字典(管理端关系类型 CRUD,SC-A-04)
+ */
+@Data
+@TableName("family_relation_types")
+public class FamilyRelationType implements Serializable {
+
+    @TableId(type = IdType.AUTO)
+    private Long id;
+
+    /** 关系类型键,唯一 */
+    private String typeKey;
+
+    /** 关系类型名称 */
+    private String typeName;
+
+    /** 关系标签(展示用) */
+    private String label;
+
+    /** 说明 */
+    private String description;
+
+    /** 排序号 */
+    private Integer sortOrder;
+
+    /** 启用:1 禁用:0 */
+    private Integer enabled;
+
+    /** 引用数量(family_relationships 中 type_key 命中行数) */
+    private Integer referenceCount;
+
+    private Date createdAt;
+
+    private Date updatedAt;
+}

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

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

+ 141 - 0
cfc-backend/src/main/java/com/etotem/cfc/service/FamilyRelationTypeService.java

@@ -0,0 +1,141 @@
+package com.etotem.cfc.service;
+
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+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 org.springframework.stereotype.Service;
+
+import javax.annotation.Resource;
+import java.util.Date;
+import java.util.List;
+import java.util.Map;
+import com.etotem.cfc.util.ParamUtils;
+
+@Service
+public class FamilyRelationTypeService {
+
+    @Resource
+    private FamilyRelationTypeMapper familyRelationTypeMapper;
+
+    @Resource
+    private FamilyRelationshipMapper familyRelationshipMapper;
+
+    public List<FamilyRelationType> listTypes(Map<String, Object> body) {
+        LambdaQueryWrapper<FamilyRelationType> wrapper = new LambdaQueryWrapper<>();
+        String typeKey = ParamUtils.getString(body.get("typeKey"));
+        if (typeKey != null) {
+            wrapper.eq(FamilyRelationType::getTypeKey, typeKey);
+        }
+        String typeName = ParamUtils.getString(body.get("typeName"));
+        if (typeName != null) {
+            wrapper.like(FamilyRelationType::getTypeName, typeName);
+        }
+        Integer enabled = ParamUtils.getBoolean(body.get("enabled")) == null ? null
+                : (ParamUtils.getBoolean(body.get("enabled")) ? 1 : 0);
+        if (enabled != null) {
+            wrapper.eq(FamilyRelationType::getEnabled, enabled);
+        }
+        wrapper.orderByAsc(FamilyRelationType::getSortOrder).orderByDesc(FamilyRelationType::getId);
+        List<FamilyRelationType> rows = familyRelationTypeMapper.selectList(wrapper);
+        for (FamilyRelationType row : rows) {
+            row.setReferenceCount(countReferences(row.getTypeKey()));
+        }
+        return rows;
+    }
+
+    public FamilyRelationType saveType(Map<String, Object> body, Long adminId) {
+        String typeKey = ParamUtils.getString(body.get("typeKey"));
+        String typeName = ParamUtils.getString(body.get("typeName"));
+        if (typeKey == null || typeName == null) {
+            throw new IllegalArgumentException("typeKey和typeName不能为空");
+        }
+        FamilyRelationType existing = familyRelationTypeMapper.selectOne(
+                new LambdaQueryWrapper<FamilyRelationType>()
+                        .eq(FamilyRelationType::getTypeKey, typeKey)
+                        .last("LIMIT 1"));
+        if (existing != null) {
+            throw new IllegalArgumentException("关系类型已存在");
+        }
+        FamilyRelationType row = new FamilyRelationType();
+        row.setTypeKey(typeKey);
+        row.setTypeName(typeName);
+        row.setLabel(ParamUtils.getString(body.get("label")));
+        row.setDescription(ParamUtils.getString(body.get("description")));
+        row.setSortOrder(ParamUtils.getLong(body.get("sortOrder")) == null ? 0
+                : ParamUtils.getLong(body.get("sortOrder")).intValue());
+        row.setEnabled(ParamUtils.getBoolean(body.get("enabled")) != null
+                ? (ParamUtils.getBoolean(body.get("enabled")) ? 1 : 0) : 1);
+        Date now = new Date();
+        row.setCreatedAt(now);
+        row.setUpdatedAt(now);
+        familyRelationTypeMapper.insert(row);
+        return row;
+    }
+
+    public FamilyRelationType updateType(Map<String, Object> body) {
+        Long id = ParamUtils.getLong(body.get("id"));
+        if (id == null) {
+            throw new IllegalArgumentException("id不能为空");
+        }
+        FamilyRelationType existing = familyRelationTypeMapper.selectById(id);
+        if (existing == null) {
+            throw new IllegalArgumentException("关系类型不存在");
+        }
+        String typeName = ParamUtils.getString(body.get("typeName"));
+        if (typeName != null) {
+            existing.setTypeName(typeName);
+        }
+        String label = ParamUtils.getString(body.get("label"));
+        if (label != null) {
+            existing.setLabel(label);
+        }
+        String description = ParamUtils.getString(body.get("description"));
+        if (description != null) {
+            existing.setDescription(description);
+        }
+        Long sortOrder = ParamUtils.getLong(body.get("sortOrder"));
+        if (sortOrder != null) {
+            existing.setSortOrder(sortOrder.intValue());
+        }
+        Boolean enabled = ParamUtils.getBoolean(body.get("enabled"));
+        if (enabled != null) {
+            existing.setEnabled(enabled ? 1 : 0);
+        }
+        existing.setUpdatedAt(new Date());
+        familyRelationTypeMapper.updateById(existing);
+        existing.setReferenceCount(countReferences(existing.getTypeKey()));
+        return existing;
+    }
+
+    public FamilyRelationType disableType(Map<String, Object> body) {
+        Long id = ParamUtils.getLong(body.get("id"));
+        if (id == null) {
+            throw new IllegalArgumentException("id不能为空");
+        }
+        Boolean confirm = ParamUtils.getBoolean(body.get("confirm"));
+        if (!Boolean.TRUE.equals(confirm)) {
+            throw new IllegalArgumentException("被引用关系类型需先解绑或确认停用");
+        }
+        FamilyRelationType existing = familyRelationTypeMapper.selectById(id);
+        if (existing == null) {
+            throw new IllegalArgumentException("关系类型不存在");
+        }
+        existing.setEnabled(0);
+        existing.setUpdatedAt(new Date());
+        familyRelationTypeMapper.updateById(existing);
+        existing.setReferenceCount(countReferences(existing.getTypeKey()));
+        return existing;
+    }
+
+    private int countReferences(String typeKey) {
+        if (typeKey == null || typeKey.isEmpty()) {
+            return 0;
+        }
+        Long count = familyRelationshipMapper.selectCount(
+                new LambdaQueryWrapper<FamilyRelationship>()
+                        .eq(FamilyRelationship::getRelationshipKey, typeKey));
+        return count == null ? 0 : count.intValue();
+    }
+}

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

@@ -2345,6 +2345,22 @@ CREATE TABLE IF NOT EXISTS family_relationships (
 
 -- 【已废弃】relationship_types 表已删除(generation 辈分模型替代)
 
+-- 家庭关系类型字典(管理端关系类型 CRUD,SC-A-04)
+CREATE TABLE IF NOT EXISTS family_relation_types (
+    id BIGINT AUTO_INCREMENT PRIMARY KEY,
+    type_key VARCHAR(50) NOT NULL COMMENT '关系类型键',
+    type_name VARCHAR(50) NOT NULL COMMENT '关系类型名称',
+    label VARCHAR(50) COMMENT '展示标签',
+    description VARCHAR(255) COMMENT '说明',
+    sort_order INT DEFAULT 0 COMMENT '排序号',
+    enabled TINYINT DEFAULT 1 COMMENT '启用:1 禁用:0',
+    reference_count INT DEFAULT 0 COMMENT '引用数量(冗余统计)',
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+    UNIQUE KEY uk_type_key (type_key),
+    INDEX idx_enabled (enabled)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='家庭关系类型字典';
+
 -- 用户收货地址表
 CREATE TABLE IF NOT EXISTS user_address (
     id BIGINT AUTO_INCREMENT PRIMARY KEY,

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

@@ -801,6 +801,7 @@ find cfc-backend/src/main/java -name "*XxxService.java" -o -name "*XxxController
 | `/api/admin/supply-*` | 供应链相关 |
 | `/api/admin/system/*` | 系统配置 |
 | `/api/admin/unlock-gates/*` | 通关配置 |
+| `/api/admin/family-relation/types/*` | 家庭关系类型字典管理(list/save/update/disable,SC-A-04) |
 | `/api/migration/run` | 数据迁移 |
 
 ### 4.14 先天画像(`/api/mind/innate/*`)
@@ -3196,7 +3197,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 | 新增 `AdminFamilyRelationController` `/api/admin/family-relation/types/*`(`family_relation_types` 字典表;关系行仍由 `family_relationships` 承载) | 已补齐管理端字典 CRUD 载体 |
 | 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` 熔断为代码内置 | 无端点载体,需产品侧确认 |