cfc/AGENTS.md

知心益家 (ZXYJ) - Project Knowledge Base

Generated: 2026-04-04 Commit: Current Branch: main

OVERVIEW

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

STRUCTURE

zxyj/
├── zxyj-backend/       # Spring Boot 后端服务
│   └── src/main/java/com/zxyj/
│       ├── controller/ # REST API (AuthController, TaskController, etc.)
│       ├── 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/           # Web 前端 (生成文件，跳过)
│
└── docs/               # 文档
    ├── superpowers/    # AI 开发工具配置
    ├── specs/          # 设计文档
    └── plans/          # 实现计划

WHERE TO LOOK

Task	Location	Notes
添加 REST API	zxyj-backend/src/main/java/com/zxyj/controller/	Controller 命名: XxxController.java
修改业务逻辑	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 连接

CODE MAP

Symbol	Type	Location	Role
AuthController	Controller	controller/AuthController.java	微信登录、JWT 认证
TaskController	Controller	controller/TaskController.java	任务 CRUD、审核
RewardController	Controller	controller/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)
• ORM: MyBatis-Plus，使用 @TableName、@TableId 注解
• API 响应: 统一使用 Result<T> 包装，包含 code、message、data
• 认证: JWT Token，放在 Header Authorization: Bearer {token}
• 前端: uni-app Vue 2 语法，小程序原生组件

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

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

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

# 数据库初始化
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 配置，不影响构建