cfc/zxyj-backend/AGENTS.md

zxyj-backend

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

WHERE TO LOOK

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

CODE MAP (关键符号)

Symbol	Type	Location	Role
AuthController	Controller	controller/auth/AuthController.java	微信登录、JWT 认证
TaskService	Service	service/TaskService.java	任务业务逻辑核心
AssessmentOrderController	Controller	controller/assessment/AssessmentOrderController.java	测评订单（创建/详情/支付）
AssessmentAppointmentController	Controller	controller/assessment/AssessmentAppointmentController.java	测评预约管理
DataMigrationService	Service	service/DataMigrationService.java	sfms → zxyj 全量数据迁移
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/zxyj/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
• 多数据源：zxyj 主库 spring.datasource.* + sfms 源库 sfms.datasource.*（只读）

COMMANDS

mvn clean compile        # 编译验证
mvn spring-boot:run      # 启动开发服务器 (localhost:8080)
                         # 注意：每次完成后端任务后，必须通过此命令启动验证应用能正常启动
mvn test                 # 运行测试 (目前只有1个测试类)

工作流程

1. 修改代码后执行 mvn clean compile 验证编译通过
2. 执行 mvn spring-boot:run 启动应用
3. 验证应用启动成功（控制台显示 Started 字样）
4. 测试相关接口确保功能正常

NOTES

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