# 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

```bash
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`