# 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/, 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/` | 请求/响应数据结构 |

## CODE MAP (关键符号)

| Symbol | Type | Location | Role |
|--------|------|----------|------|
| `AuthController` | Controller | `controller/auth/AuthController.java` | 微信登录、JWT 认证 |
| `TaskService` | Service | `service/TaskService.java` | 任务业务逻辑核心 |
| `User` | Entity | `entity/User.java` | 用户实体 (parent/child/teacher) |
| `Task` | Entity | `entity/Task.java` | 任务实体 |
| `DatabaseInitializer` | Config | `config/DatabaseInitializer.java` | 数据库迁移和初始化 |

## 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, family, guide, task, reward 子目录

## ANTI-PATTERNS (本项目禁止)

- **DO NOT** 在 Controller 直接操作 Mapper
- **DO NOT** 跳过 Service 层直接调用 Mapper  
- **DO NOT** 硬编码数据库连接，使用 `application.yml`
- **NEVER** 在代码中硬编码 JWT 密钥
- **NEVER** 使用 `@ts-ignore`、`as any` 绕过类型检查
- **NEVER** 跳过 JWT 认证直接调用需登录接口

## UNIQUE STYLES

- 双角色系统：家长端/孩子端，登录后根据 `role` 字段分流，家长端可切孩子端，切换过来的孩子端可退出切换，即时出需要密码。直接登录的孩子端不能切换到家长 端
- 指导师角色系统：指导师是个单独的角色，经过认证的指导师可以以指导师身份登录，指导师可切换自己作为家长端
- 积分机制：完成任务加分、超时扣分，逻辑在 `PointsService`
- 心愿审批流程：孩子创建 → 家长审批 → 扣减积分
- 街道地址匹配：四级地址结构（省市区街道），区域回退匹配逻辑

## COMMANDS

```bash
mvn clean install       # 编译打包
mvn spring-boot:run     # 启动开发服务器 (localhost:8080)
mvn test                # 运行测试 (目前只有1个测试类)
```

## NOTES

- 数据库：MySQL 8.0，地址 `192.168.16.251:3306/zxyj`
- 后端端口：8080，JWT 密钥在 `application.yml`
- 街道数据：使用静态种子数据，街道匹配有回退机制
- API冲突已修复：检查所有Controller确保无重复路径映射