# 知心益家 (ZXYJ) - Project Knowledge Base

**Generated:** 2026-04-09
**Commit:** 20fbc81
**Branch:** master

## OVERVIEW

家庭教育任务管理小程序，积分奖励激励孩子自主完成任务。双端架构：Spring Boot 后端 + uni-app 微信小程序。

## STRUCTURE

```
zxyj/
├── zxyj-backend/       # Spring Boot 后端服务
│   └── src/main/java/com/zxyj/
│       ├── controller/ # REST API (已重组为子目录)
│       │   ├── admin/    # 管理端控制器
│       │   ├── auth/     # 认证控制器
│       │   ├── family/   # 家庭管理控制器
│       │   ├── guide/    # 成长规划师控制器
│       │   ├── task/     # 任务控制器
│       │   └── reward/   # 奖励控制器
│       ├── service/    # 业务逻辑
│       ├── entity/     # JPA 实体 (Task, Reward, User, etc.)
│       ├── mapper/     # MyBatis-Plus Mapper
│       ├── dto/        # 数据传输对象
│       ├── config/     # 配置类 (Security, JWT, Swagger)
│       └── common/     # 公共类 (Result, JwtUtil)
│
├── zxyj-frontend/      # uni-app 小程序前端
│   ├── pages/          # 页面组件 (login, index, tasks, rewards, profile)
│   ├── App.vue         # 应用入口
│   └── manifest.json   # uni-app 配置
│
├── zxyj-web/           # Vue.js Web管理端
│   └── src/
│       ├── views/      # 页面组件
│       ├── api/        # API调用
│       └── router/     # 路由配置
│
└── docs/               # 文档
    ├── superpowers/    # AI 开发工具配置
    ├── specs/          # 设计文档
    ├── plans/          # 实现计划
    ├── 需求分析/       # 需求分析文档
    ├── 系统设计/       # 系统设计文档
    └── 系统测试/       # 系统测试文档
```

## JAVA LSP 配置

### JDTLS 安装状态

- **JDTLS 路径**: `E:\develop\jdtls`
- **JDK 21 路径**: `E:\develop\Java\jdk-21.0.10+7`
- **启动脚本**: `E:\develop\jdtls\bin\jdtls-launch.bat`

### VSCode 配置

`.vscode/settings.json` 已配置:
```json
{
  "java.configuration.runtimes": [
    { "name": "JavaSE-1.8", "path": "E:\\develop\\Java\\jdk1.8.0_181", "default": true },
    { "name": "JavaSE-21", "path": "E:\\develop\\Java\\jdk-21.0.10+7" }
  ],
  "java.home": "E:\\develop\\Java\\jdk1.8.0_181",
  "java.jdt.ls.java.home": "E:\\develop\\Java\\jdk-21.0.10+7"
}
```

## WHERE TO LOOK

| Task | Location | Notes |
|------|----------|-------|
| 添加 REST API | `zxyj-backend/src/main/java/com/zxyj/controller/` | 按功能分组: admin/, auth/, family/, guide/, task/, reward/ |
| 修改业务逻辑 | `zxyj-backend/src/main/java/com/zxyj/service/` | Service 命名: `XxxService.java` |
| 添加数据实体 | `zxyj-backend/src/main/java/com/zxyj/entity/` | 使用 MyBatis-Plus 注解 |
| SQL 查询 | `zxyj-backend/src/main/resources/mapper/` | MyBatis XML 文件 |
| 添加小程序页面 | `zxyj-frontend/pages/` | 需在 pages.json 注册 |
| 修改页面样式 | `zxyj-frontend/uni.scss` | 全局样式变量 |
| 数据库配置 | `zxyj-backend/src/main/resources/application.yml` | MySQL 连接 |
| 需求分析文档 | `docs/需求分析/` | 需求分析与范围说明 |
| 系统设计文档 | `docs/系统设计/` | 总体/详细设计说明 |
| 系统测试文档 | `docs/系统测试/` | 测试计划、用例与报告 |

## CODE MAP

| Symbol | Type | Location | Role |
|--------|------|----------|------|
| `AuthController` | Controller | `controller/auth/AuthController.java` | 微信登录、JWT 认证 |
| `AdminController` | Controller | `controller/admin/AdminController.java` | 管理端API |
| `TaskController` | Controller | `controller/task/TaskController.java` | 任务 CRUD、审核 |
| `RewardController` | Controller | `controller/reward/RewardController.java` | 心愿兑换、审批 |
| `TaskService` | Service | `service/TaskService.java` | 任务业务逻辑 |
| `User` | Entity | `entity/User.java` | 用户实体 (家长/孩子) |
| `Task` | Entity | `entity/Task.java` | 任务实体 |
| `Reward` | Entity | `entity/Reward.java` | 心愿奖励实体 |

## CONVENTIONS

- **后端:** Spring Boot 标准分层架构 (Controller → Service → Mapper)
- **控制器分组:** 按功能模块分为 admin, auth, family, guide, task, reward
- **ORM:** MyBatis-Plus，使用 `@TableName`、`@TableId` 注解
- **API 响应:** 统一使用 `Result<T>` 包装，包含 code、message、data
- **认证:** JWT Token，放在 Header `Authorization: Bearer {token}`
- **前端:** uni-app Vue 2 语法，小程序原生组件
- **Web前端:** Vue 2 + Element UI

## ANTI-PATTERNS

- **DO NOT** 在 Controller 中直接操作数据库
- **DO NOT** 硬编码 API 地址，使用 `config.baseUrl`
- **DO NOT** 在前端存储敏感信息 (密码、密钥)
- **NEVER** 跳过 JWT 认证直接调用需登录接口
- **ALWAYS** 使用 `Result.success()` / `Result.error()` 返回 API 响应

## UNIQUE STYLES

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

## COMMANDS

```bash
# 后端开发
cd zxyj-backend
mvn clean install          # 编译打包
mvn spring-boot:run        # 启动开发服务器 (localhost:8080)

# 前端开发
cd zxyj-frontend
npm install                # 安装依赖
npm run dev:mp-weixin      # 开发模式 (微信小程序)

# Web前端开发
cd zxyj-web
npm run serve              # 开发模式 (localhost:8082)

# 数据库初始化
mysql -u root -p zxyj < zxyj-backend/src/main/resources/schema.sql
```

## NOTES

- 数据库：MySQL 8.0，地址 `192.168.16.251:3306/zxyj`
- 后端端口：8080，JWT 密钥在 `application.yml`
- 小程序 AppID：`wx5ba8038ef16fb245`
- Swagger API 文档：`http://localhost:8080/swagger-ui.html`
- `.idea/`、`系统功能/` 为 IDE 配置，不影响构建

## HIERARCHICAL DOCUMENTATION

本项目使用分层AGENTS.md文档系统：

```
zxyj/
├── AGENTS.md                      # 项目总览 (本文件)
├── zxyj-backend/AGENTS.md         # 后端详细文档
├── zxyj-frontend/AGENTS.md        # 小程序前端文档
├── zxyj-web/AGENTS.md             # Web管理端文档
├── docs/superpowers/AGENTS.md     # AI开发工具配置
├── docs/需求分析/                # 需求分析文档
├── docs/系统设计/                # 系统设计文档
├── docs/系统测试/                # 系统测试文档
└── tests/AGENTS.md                # 测试策略文档
```

每个子目录的AGENTS.md提供该模块的详细信息和特定约定。