知心益家 (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 已配置:

{
  "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

# 后端开发
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提供该模块的详细信息和特定约定。

AGENTS.md 7.2 KB Histórico Raw