Преглед изворни кода

feat(S-cfc-324,mind.model.manage): 舌诊/情绪模型版本管理实现(SC-A-21)

- MindModel 实体 + MindModelMapper(modelType/version/enabled/fallbackVersion)
- MindModelManageService:listAll/online/offline/isEnabled,offline 三参含 fallbackVersion
  未指定回退方案拒绝下线(Result 400),非法/未知版本返回 400
- MindModelManageController(/api/admin/mind-model: list/online/offline,统一 @PostMapping)
- schema.sql 落地 mind_model 建表 + DatabaseInitializer 迁移470(幂等)
- API_REFERENCE §4.13 同步全新端点

使 MindModelManageContractTest 11/11 转绿(RED 10 失败 → GREEN 0 失败)。
zxyj-langgraph пре 5 дана
родитељ
комит
d571b5d9

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

@@ -3519,6 +3519,10 @@ insertSysConfigSeed("gift_membership_pay_price", "198000", "送会员商品达
         } catch (Exception e) {
             log.warn("迁移469: five_dimension_scores.source_type 注释校准失败(幂等容忍): {}", e.getMessage());
         }
+
+        // 迁移470: 创建模型管理表 mind_model
+        //(mind.model.manage · SC-A-21 舌诊/情绪模型版本/开关:版控/上下线/下线前回退方案)
+        createMindModelTable();
     }
 
     /**
@@ -15787,6 +15791,31 @@ log.info("迁移298: 已为无 openid 的 child 账号补齐 family_members 记
         }
     }
 
+    /**
+     * 迁移470: 创建模型管理表 mind_model(能力键 mind.model.manage · SC-A-21 舌诊/情绪模型版本/开关)。
+     *
+     * <p>承载模型版本/开关数据载体(AC-1):model_type(emotion|tongue)、version、enabled(上下线开关)、
+     * fallback_version(下线前回退方案,AC-3);uk_model_type_version 唯一约束保证同一类型下版本唯一。
+     * 幂等(CREATE TABLE IF NOT EXISTS)。</p>
+     */
+    private void createMindModelTable() {
+        try {
+            jdbcTemplate.execute("CREATE TABLE IF NOT EXISTS mind_model ("
+                    + "id BIGINT AUTO_INCREMENT PRIMARY KEY, "
+                    + "model_type VARCHAR(32) NOT NULL COMMENT '模型类型: emotion(情绪)/tongue(舌诊)', "
+                    + "version VARCHAR(64) NOT NULL COMMENT '模型版本号(如 v1/v2)', "
+                    + "enabled TINYINT DEFAULT 1 COMMENT '上下线开关: 1=上线 0=下线', "
+                    + "fallback_version VARCHAR(64) NULL COMMENT '下线前回退版本(回退方案,AC-3)', "
+                    + "created_at DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', "
+                    + "updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', "
+                    + "UNIQUE KEY uk_model_type_version (model_type, version) "
+                    + ") ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='舌诊/情绪模型版本管理(SC-A-21)'");
+            log.info("迁移470: 已创建 mind_model 表");
+        } catch (Exception e) {
+            log.warn("迁移470: 创建 mind_model 表失败(可能已存在): {}", e.getMessage());
+        }
+    }
+
     /** 幂等 upsert 维度种子:按 dimension_code 存在则补 source_system/legacy_alias,不存在则插入。 */
     private void upsertDimensionSeed(String code, String name, String dimensionType, Long parentId,
                                      int sort, String sourceSystem, String nodeKind,

+ 48 - 0
cfc-backend/src/main/java/com/etotem/cfc/controller/admin/MindModelManageController.java

@@ -0,0 +1,48 @@
+package com.etotem.cfc.controller.admin;
+
+import com.etotem.cfc.common.Result;
+import com.etotem.cfc.entity.MindModel;
+import com.etotem.cfc.service.MindModelManageService;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.web.bind.annotation.PostMapping;
+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;
+
+/**
+ * 舌诊/情绪模型版本管理(能力键 mind.model.manage · SC-A-21)。
+ *
+ * <p>平台运营内部模型管理:版本列表(list)/ 上线(online)/ 下线(offline,须指定回退版本)。
+ * 所有接口统一 {@code @PostMapping}。</p>
+ */
+@Slf4j
+@RestController
+@RequestMapping("/api/admin/mind-model")
+public class MindModelManageController {
+
+    @Resource
+    private MindModelManageService mindModelManageService;
+
+    /** 版本列表(版控,AC-2)。 */
+    @PostMapping("/list")
+    public Result<List<MindModel>> list() {
+        return mindModelManageService.listAll();
+    }
+
+    /** 上线(AC-2);请求体: { "modelType": "emotion|tongue", "version": "v1" }。 */
+    @PostMapping("/online")
+    public Result<Void> online(@RequestBody Map<String, String> params) {
+        return mindModelManageService.online(params.get("modelType"), params.get("version"));
+    }
+
+    /** 下线(AC-3 须指定回退版本);请求体: { "modelType": "emotion|tongue", "version": "v1", "fallbackVersion": "v1" }。 */
+    @PostMapping("/offline")
+    public Result<Void> offline(@RequestBody Map<String, String> params) {
+        return mindModelManageService.offline(
+                params.get("modelType"), params.get("version"), params.get("fallbackVersion"));
+    }
+}

+ 39 - 0
cfc-backend/src/main/java/com/etotem/cfc/entity/MindModel.java

@@ -0,0 +1,39 @@
+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;
+
+/**
+ * 舌诊/情绪模型版本管理实体(能力键 mind.model.manage · SC-A-21)。
+ *
+ * <p>承载模型版本/开关的数据载体:{@code modelType}(emotion|tongue)、{@code version}、
+ * {@code enabled}(上下线开关)、{@code fallbackVersion}(下线前回退方案)。</p>
+ */
+@Data
+@TableName("mind_model")
+public class MindModel implements Serializable {
+
+    @TableId(type = IdType.AUTO)
+    private Long id;
+
+    /** 模型类型: emotion(情绪)/tongue(舌诊)。 */
+    private String modelType;
+
+    /** 模型版本号(如 v1/v2)。 */
+    private String version;
+
+    /** 上下线开关: 1=上线 0=下线。 */
+    private Integer enabled;
+
+    /** 下线前回退版本(AC-3:未指定回退方案不得下线)。 */
+    private String fallbackVersion;
+
+    private Date createdAt;
+
+    private Date updatedAt;
+}

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

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

+ 128 - 0
cfc-backend/src/main/java/com/etotem/cfc/service/MindModelManageService.java

@@ -0,0 +1,128 @@
+package com.etotem.cfc.service;
+
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.etotem.cfc.common.Result;
+import com.etotem.cfc.entity.MindModel;
+import com.etotem.cfc.mapper.MindModelMapper;
+import lombok.extern.slf4j.Slf4j;
+import org.apache.commons.lang3.StringUtils;
+import org.springframework.stereotype.Service;
+
+import javax.annotation.Resource;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.regex.Pattern;
+
+/**
+ * 舌诊/情绪模型版本管理服务(能力键 mind.model.manage · SC-A-21)。
+ *
+ * <p>契约 AC 条款:</p>
+ * <ul>
+ *   <li><b>AC-2 版控/上下线</b>:{@code listAll} 版本列表、{@code online}/{@code offline} 上下线入口、{@code isEnabled} 开关查询。</li>
+ *   <li><b>AC-3 下线前回退方案</b>:{@code offline} 必须指定 {@code fallbackVersion},未指定回退方案时拒绝下线(Result 400)。</li>
+ *   <li><b>AC-4 非法版本 400</b>:对非法/未知版本的操作返回 Result code 400。</li>
+ * </ul>
+ *
+ * <p>注意:契约单测以无参构造直接实例化宿主(mapper 未装配为 null),服务逻辑对 null mapper 防御式兜底
+ * (未知版本/非法版本一律 400),保证行为级契约在无 DB 环境下可判定。</p>
+ */
+@Slf4j
+@Service
+public class MindModelManageService {
+
+    /** 版本号规范:v 开头 + 数字(如 v1、v2)。 */
+    private static final Pattern VERSION_PATTERN = Pattern.compile("^v\\d+$");
+
+    @Resource
+    private MindModelMapper mindModelMapper;
+
+    /**
+     * 版本列表(版控,AC-2):按模型类型 + 版本升序返回全部模型版本。
+     */
+    public Result<List<MindModel>> listAll() {
+        if (mindModelMapper == null) {
+            return Result.success(new ArrayList<>());
+        }
+        return Result.success(mindModelMapper.selectList(
+                new LambdaQueryWrapper<MindModel>()
+                        .orderByAsc(MindModel::getModelType)
+                        .orderByAsc(MindModel::getVersion)));
+    }
+
+    /**
+     * 上线(AC-2/AC-4):将指定版本置为 enabled=1。
+     * 非法/未知版本返回 Result code 400。
+     */
+    public Result<Void> online(String modelType, String version) {
+        if (StringUtils.isBlank(modelType) || StringUtils.isBlank(version)) {
+            return Result.badRequest("模型类型与版本不能为空");
+        }
+        if (!VERSION_PATTERN.matcher(version).matches()) {
+            return Result.badRequest("非法模型版本号:" + version + "(应为 v+数字,如 v1)");
+        }
+        MindModel model = queryByTypeAndVersion(modelType, version);
+        if (model == null) {
+            return Result.badRequest("未知模型版本,无法上线:" + modelType + "@" + version);
+        }
+        if (model.getEnabled() != null && model.getEnabled() == 1) {
+            return Result.success();
+        }
+        model.setEnabled(1);
+        mindModelMapper.updateById(model);
+        log.info("mind.model.manage: 模型上线 modelType={}, version={}", modelType, version);
+        return Result.success();
+    }
+
+    /**
+     * 下线(AC-2/AC-3/AC-4):将指定版本置为 enabled=0 并记录回退版本。
+     * 未指定回退版本(fallbackVersion 为空)时拒绝下线,返回 Result code 400;
+     * 非法/未知版本返回 Result code 400。
+     */
+    public Result<Void> offline(String modelType, String version, String fallbackVersion) {
+        if (StringUtils.isBlank(modelType) || StringUtils.isBlank(version)) {
+            return Result.badRequest("模型类型与版本不能为空");
+        }
+        if (StringUtils.isBlank(fallbackVersion)) {
+            return Result.badRequest("下线前必须指定回退版本(fallbackVersion)");
+        }
+        if (!VERSION_PATTERN.matcher(version).matches()) {
+            return Result.badRequest("非法模型版本号:" + version + "(应为 v+数字,如 v1)");
+        }
+        MindModel model = queryByTypeAndVersion(modelType, version);
+        if (model == null) {
+            return Result.badRequest("未知模型版本,无法下线:" + modelType + "@" + version);
+        }
+        model.setEnabled(0);
+        model.setFallbackVersion(fallbackVersion);
+        mindModelMapper.updateById(model);
+        log.info("mind.model.manage: 模型下线 modelType={}, version={}, fallbackVersion={}",
+                modelType, version, fallbackVersion);
+        return Result.success();
+    }
+
+    /**
+     * 开关查询(AC-1/AC-2):指定模型类型是否存在已上线版本(enabled=1)。
+     */
+    public boolean isEnabled(String modelType) {
+        if (mindModelMapper == null || StringUtils.isBlank(modelType)) {
+            return false;
+        }
+        MindModel model = mindModelMapper.selectOne(
+                new LambdaQueryWrapper<MindModel>()
+                        .eq(MindModel::getModelType, modelType)
+                        .eq(MindModel::getEnabled, 1)
+                        .last("LIMIT 1"));
+        return model != null;
+    }
+
+    /** 按模型类型 + 版本精确查询(映射唯一键 uk_model_type_version)。 */
+    private MindModel queryByTypeAndVersion(String modelType, String version) {
+        if (mindModelMapper == null) {
+            return null;
+        }
+        return mindModelMapper.selectOne(
+                new LambdaQueryWrapper<MindModel>()
+                        .eq(MindModel::getModelType, modelType)
+                        .eq(MindModel::getVersion, version));
+    }
+}

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

@@ -7239,3 +7239,17 @@ CREATE TABLE IF NOT EXISTS mind_psychological_assessments (
     INDEX idx_member_date (member_id, assessment_date),
     INDEX idx_guide (guide_id)
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='心理测评记录(舌诊/情绪统一录入,SC-T-25)';
+
+-- ============================================================
+-- 模型管理表(迁移470,mind.model.manage · SC-A-21 舌诊/情绪模型版本/开关)
+-- ============================================================
+CREATE TABLE IF NOT EXISTS mind_model (
+    id BIGINT AUTO_INCREMENT PRIMARY KEY,
+    model_type VARCHAR(32) NOT NULL COMMENT '模型类型: emotion(情绪)/tongue(舌诊)',
+    version VARCHAR(64) NOT NULL COMMENT '模型版本号(如 v1/v2)',
+    enabled TINYINT DEFAULT 1 COMMENT '上下线开关: 1=上线 0=下线',
+    fallback_version VARCHAR(64) NULL COMMENT '下线前回退版本(回退方案,AC-3)',
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
+    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
+    UNIQUE KEY uk_model_type_version (model_type, version)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='舌诊/情绪模型版本管理(SC-A-21)';

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

@@ -785,6 +785,7 @@ find cfc-backend/src/main/java -name "*XxxService.java" -o -name "*XxxController
 | `/api/admin/knowledge-base/*` | 知识库管理 |
 | `/api/admin/notices/*` | 公告管理 |
 | `/api/admin/innate-portrait-config/*` | 先天画像来源权重配置(list/update/invalidate) |
+| `/api/admin/mind-model/*` | 舌诊/情绪模型版本管理(mind.model.manage · SC-A-21):list 版本列表 / online 上线 / offline 下线(须指定 fallbackVersion 回退版本) |
 | `/api/admin/numsoul-detail-config/*` | 数字能量详细配置(list/create/update/delete) |
 | `/api/admin/package-templates/*` | 套餐模板 |
 | `/api/admin/ppoint-config/*` | P点配置(品类级比例+商品级固定值) |