cfc-backend

Spring Boot 2.7.18 后端服务，MyBatis-Plus ORM，JWT 认证。

WHERE TO LOOK

Task	Location	Notes
REST API 端点	`src/main/java/com/etotem/cfc/controller/`	按功能分组: admin/, auth/, assessment/, family/, guide/, task/, reward/
业务逻辑	`src/main/java/com/etotem/cfc/service/`	Service 命名: `XxxService.java`
数据实体	`src/main/java/com/etotem/cfc/entity/`	使用 MyBatis-Plus 注解
MyBatis Mapper	`src/main/java/com/etotem/cfc/mapper/`	接口文件，与XML映射对应
SQL 映射文件	`src/main/resources/mapper/`	MyBatis XML 文件
配置类	`src/main/java/com/etotem/cfc/config/`	JWT, Security, Swagger, DatabaseInitializer
DTO传输对象	`src/main/java/com/etotem/cfc/dto/`	请求/响应数据结构
数据迁移	`src/main/java/com/etotem/cfc/service/DataMigrationService.java`	sfms → cfc

CODE MAP (关键符号)

Symbol	Type	Location	Role
`AuthController`	Controller	`controller/auth/AuthController.java`	微信登录、JWT 认证
`TaskService`	Service	`service/TaskService.java`	任务业务逻辑核心
`DanAssessmentController`	Controller	`controller/DanAssessmentController.java`	DAN测评全链路（订单/预约/支付/结果）
`AssessmentAppointmentController`	Controller	`controller/assessment/AssessmentAppointmentController.java`	测评预约管理
`DataMigrationService`	Service	`service/DataMigrationService.java`	sfms → cfc 全量数据迁移
`User`	Entity	`entity/User.java`	用户实体 (parent/child/teacher)
`Task`	Entity	`entity/Task.java`	任务实体
`DanAssessmentResult`	Entity	`entity/DanAssessmentResult.java`	DAN测评结果（含孩子快照字段）
`DatabaseInitializer`	Config	`config/DatabaseInitializer.java`	数据库迁移和初始化
`SfmsDataSourceConfig`	Config	`config/SfmsDataSourceConfig.java`	sfms 多数据源配置

CONVENTIONS

分层架构: Controller → Service → Mapper，禁止跨层调用
ORM: MyBatis-Plus，实体使用 @TableName、@TableId(type = IdType.AUTO)
响应包装: 统一 Result<T> 返回，包含 code/message/data
认证: JWT Token，Header Authorization: Bearer {token}
命名: Controller 以 Controller 结尾，Service 以 Service 结尾
控制器分组: 按功能模块分为 admin, auth, assessment, family, guide, task, reward 等子目录
DI注解: 使用 @Resource 代替 @Autowired，字段名必须与类型默认 Bean Name 一致（如 PaymentService 的字段名必须为 paymentService）
接口方法: 所有接口统一使用 @PostMapping（POST 方法），禁止使用 @GetMapping/@PutMapping/@DeleteMapping

新增接口前: 必须运行 mvn clean compile 并启动项目验证无冲突；使用以下命令检查重复路由：

grep -rn '@GetMapping\|@PostMapping\|@PutMapping\|@DeleteMapping' src/main/java/com/etotem/cfc/controller/ | grep -oP '@\w+Mapping\("\K[^"]*' | sort -u

Bean名冲突检查: 新增 Controller/Service 时，确保类名不与其他包中的类重名（Spring 默认 Bean Name 为类名首字母小写）

ANTI-PATTERNS (本项目禁止)

DO NOT 在 Controller 直接操作 Mapper
DO NOT 跳过 Service 层直接调用 Mapper
DO NOT 硬编码数据库连接，使用 application.yml
NEVER 在代码中硬编码 JWT 密钥
NEVER 使用 @ts-ignore、as any 绕过类型检查
NEVER 跳过 JWT 认证直接调用需登录接口
NEVER 使用 @Resource(name="xxx") 与字段名不一致的注入方式，保持字段名与类型默认 Bean Name 一致
NEVER 使用 @GetMapping/@PutMapping/@DeleteMapping — 统一使用 @PostMapping
NEVER 直接 new XxxMapper() — Mapper 必须通过 @Resource 注入
NEVER 使用 awk '!seen[$0]++' 对 Java 源文件去重 — 会删除合法的重复行（如多个方法的 } 闭合括号）

UNIQUE STYLES

双角色系统：家长端/孩子端，登录后根据 role 字段分流，家长端可切孩子端，切换过来的孩子端可退出切换，即时出需要密码。直接登录的孩子端不能切换到家长端
成长规划师角色系统：成长规划师是个单独的角色，经过认证的成长规划师可以以成长规划师身份登录，成长规划师可切换自己作为家长端
积分机制：完成任务加分、超时扣分，逻辑在 PointsService
心愿审批流程：孩子创建 → 家长审批 → 扣减积分
测评订单：家长申请 → 选择规划师 → 孩子信息快照 → 支付 → 规划师录入结果
街道地址匹配：四级地址结构（省市区街道），区域回退匹配逻辑
孩子快照：每次测评时保存孩子身高/体重/学校等动态信息到 DanAssessmentResult
多数据源：cfc 主库 spring.datasource.* + sfms 源库 sfms.datasource.*（只读）

DATABASE MIGRATION WORKFLOW

当出现 Unknown column 'xxx' in 'field list' 等字段不存在错误，或需要进行表结构变更时，按以下流程处理：

工作流程

错误日志定位 → 查找实体类 → 检查 schema.sql → 添加迁移 → 同步 schema.sql → 编译验证

Step 1: 诊断错误

后端日志中出现类似以下错误：

Unknown column 'xxx' in 'field list'
Table 'xxx' doesn't exist

从错误信息中提取：表名、列名/对象名，并从异常堆栈找到触发点（哪个 Service/Controller）。

Step 2: 查找实体与建表 SQL

在 entity/ 目录找到对应实体类，确认字段已定义（@TableField 或成员变量）
在 src/main/resources/schema.sql 中找到该表的 CREATE TABLE 语句，确认列是否已包含

Step 3: 判断修复位置

情况	修复方式
schema.sql 建表语句有该列，但生产库没有（旧表）	只需在 `DatabaseInitializer.runMigrations()` 添加 ALTER TABLE
schema.sql 没有该列，实体也没有	在实体添加字段 + schema.sql 建表语句补列 + DatabaseInitializer 加迁移
全新表	schema.sql 添加 CREATE TABLE + DatabaseInitializer 的 runMigrations() 加迁移
仅调整约束/类型/默认值	DatabaseInitializer.runMigrations() 加 MODIFY COLUMN

Step 4: 在 DatabaseInitializer 添加迁移

DatabaseInitializer.java 的 runMigrations() 方法是所有 DDL 迁移的唯一入口。

添加列（首选 ensureColumn 辅助方法）

ensureColumn(table, column, definition) 是已有的辅助方法（第 4099 行），自动处理重复列异常：

// 迁移N: xxx表添加yyy字段
ensureColumn("table_name", "column_name", "VARCHAR(50) COMMENT '字段说明'");

ensureColumn 不可用时（如需要 MODIFY / 多个列在同一个 try 块），使用标准模式：

// 迁移N: xxx表添加yyy字段（原因描述/需求编号）
try {
    jdbcTemplate.execute("ALTER TABLE xxx ADD COLUMN yyy VARCHAR(50) COMMENT '字段说明'");
    log.info("已添加yyy列到xxx表");
} catch (Exception e) {
    // 列已存在，忽略错误
}

创建新表

// 迁移N: 创建 xxx 表（功能描述）
try {
    jdbcTemplate.execute("CREATE TABLE IF NOT EXISTS xxx (" +
            "id BIGINT AUTO_INCREMENT PRIMARY KEY, " +
            "...字段定义..." +
            "INDEX idx_xxx (column)" +
            ") ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='表注释'");
    log.info("已创建xxx表");
} catch (Exception e) {
    // 表已存在，忽略错误
}

添加索引

try {
    jdbcTemplate.execute("ALTER TABLE xxx ADD INDEX idx_xxx (column)");
    log.info("已添加idx_xxx索引到xxx表");
} catch (Exception e) {
    // 索引已存在，忽略错误
}

修改字段

try {
    jdbcTemplate.execute("ALTER TABLE xxx MODIFY COLUMN yyy VARCHAR(100) COMMENT '新注释'");
    log.info("已修改xxx.yyy字段");
} catch (Exception e) {
    // 修改失败，忽略错误
}

Step 5: 同步 schema.sql

schema.sql 中保持该表最新的完整定义：

新增列：在 schema.sql 对应表的 CREATE TABLE 语句中也加上该列定义（保持建表即包含所有列）
新建表：在 schema.sql 追加该表的 CREATE TABLE IF NOT EXISTS 语句
仅修改约束/默认值：无需更新 schema.sql
迁移中 CREATE TABLE IF NOT EXISTS 创建的表：也追加到 schema.sql（保持 schema.sql 为完整定义快照）

Step 6: 验证

mvn clean compile   # 编译验证通过即可

迁移代码是幂等的（try-catch 忽略已存在的列/表/索引），无需运行时验证。

规范要点

迁移编号：按现有顺序递增（当前最大编号 迁移N，在文件末尾搜索 // 迁移 确认最新编号）
注释格式：// 迁移N: 表名操作说明（原因/需求编号）
日志：每个成功的 ALTER/CREATE 后加 log.info()，失败统一用空 catch 或 // 忽略
幂等性：所有迁移必须可重复执行而不报错（try-catch 包裹 + 列存在检查）
辅助方法：优先使用 ensureColumn() 添加列，它自动处理重复列异常；原始 try-catch 模式用于索引/表/非标准操作
同步原则：对 schema.sql 的每一条 DDL 变更，必须在 DatabaseInitializer 中有对应的迁移，反之亦然——两者保持最终一致

COMMANDS

mvn clean compile        # 编译验证（唯一验证方式）
mvn spring-boot:run      # 启动开发服务器 (localhost:9082)
mvn test                 # 运行测试 (目前只有1个测试类)

Python LangGraph 服务（部署到 ai.etotem.com.cn）

cd cfc-langgraph && pip install -r requirements.txt && uvicorn src.app:app --port 9000 ```

工作流程

修改代码后执行 mvn clean compile 验证编译通过
编译通过即视为验证完成，不做运行时/启动验证

NOTES

数据库：MySQL 8.0，地址 192.168.16.251:3306/cfc
后端端口：9082，JWT 密钥在 application.yml
街道数据：使用静态种子数据，街道匹配有回退机制
API冲突已修复：检查所有Controller确保无重复路径映射
sfms 源库连接信息在 application.yml 的 sfms.datasource.*
数据迁移 POST /api/migration/run

后端接口规范

后台/api的接口规范都用post方式

AGENTS.md 10 KB Verlauf Originalformat

cfc-backend

WHERE TO LOOK

CODE MAP (关键符号)

CONVENTIONS

ANTI-PATTERNS (本项目禁止)

UNIQUE STYLES

DATABASE MIGRATION WORKFLOW

工作流程

Step 1: 诊断错误

Step 2: 查找实体与建表 SQL

Step 3: 判断修复位置

Step 4: 在 DatabaseInitializer 添加迁移

添加列（首选 ensureColumn 辅助方法）

创建新表

添加索引

修改字段

Step 5: 同步 schema.sql

Step 6: 验证

规范要点

COMMANDS

Python LangGraph 服务（部署到 ai.etotem.com.cn）

工作流程

NOTES

后端接口规范

AGENTS.md 10 KB

Verlauf Originalformat