cfc/AGENTS.md

知心益家 (ZXYJ) - Project Knowledge Base

Generated: 2026-05-07 Commit: {CURRENT_COMMIT} Branch: master

OVERVIEW

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

STRUCTURE

zxyj/
├── zxyj-backend/       # Spring Boot 后端服务
│   └── src/main/java/com/zxyj/
│       ├── controller/ # REST API (按功能分组)
│       │   ├── admin/      # 管理端
│       │   ├── assessment/ # 测评订单/预约
│       │   ├── auth/       # 认证
│       │   ├── family/     # 家庭管理
│       │   ├── growth/     # 成长档案
│       │   ├── guide/      # 成长规划师
│       │   ├── parent/     # 家长端
│       │   ├── reward/     # 奖励
│       │   ├── sncp/       # 社区/活动
│       │   ├── task/       # 任务
│       │   └── wish/       # 心愿单
│       ├── service/     # 业务逻辑
│       ├── entity/      # MyBatis-Plus 实体 (47个)
│       ├── mapper/      # MyBatis-Plus Mapper
│       ├── dto/         # 数据传输对象
│       ├── config/      # 配置 (JWT, 多数据源, DatabaseInitializer)
│       └── common/      # 公共类 (Result, JwtUtil)
│
├── zxyj-frontend/      # uni-app 微信小程序
│   ├── pages/          # 页面 (20+ 目录)
│   │   ├── index/      # 首页（角色分流）
│   │   ├── assessment/ # 测评申请/下单/报告 (6页)
│   │   ├── growth/     # 成长档案
│   │   ├── guide/      # 成长规划师功能
│   │   ├── parent/     # 家长专属 (预约/市场/心愿)
│   │   ├── teacher/    # 规划师端 (预约管理)
│   │   └── ...         # tasks, rewards, profile 等
│   ├── App.vue         # 应用入口 (自动登录, 全局请求)
│   ├── store/          # Vuex (双角色状态管理)
│   └── utils/          # API调用封装
│
├── zxyj-web/           # Vue 2 + Element UI Web管理端
│   └── src/
│       ├── views/      # 页面 (admin/ + teacher/)
│       ├── api/        # API封装
│       ├── router/     # Vue Router (角色权限守卫)
│       └── store/      # Vuex (认证状态)
│
├── docs/               # 文档
│   ├── superpowers/    # AI开发工具配置
│   ├── 需求分析/       # 需求分析文档
│   ├── 系统设计/       # 系统设计文档
│   └── 系统测试/       # 测试报告
│
└── tests/              # 分层测试 (unit/integration/e2e)

WHERE TO LOOK

Task	Location	Notes
添加 REST API	zxyj-backend/.../controller/	按功能模块分组
修改业务逻辑	zxyj-backend/.../service/	命名: XxxService.java
添加数据实体	zxyj-backend/.../entity/	MyBatis-Plus @TableName
数据库迁移	zxyj-backend/.../config/DatabaseInitializer.java	启动时自动执行
多数据源	zxyj-backend/.../config/SfmsDataSourceConfig.java	sfms 只读源
数据迁移	zxyj-backend/.../service/DataMigrationService.java	从sfms导入历史数据
添加小程序页面	zxyj-frontend/pages/	需在 pages.json 注册
前端API	zxyj-frontend/utils/api.js	后端接口封装
修改全局样式	zxyj-frontend/uni.scss	SCSS变量
Web前端	zxyj-web/src/views/ + src/router/index.js	角色菜单+路由
数据库配置	zxyj-backend/src/main/resources/application.yml	MySQL + sfms
需求/设计文档	docs/需求分析/, docs/系统设计/	Markdown格式
分层测试	tests/	unit/integration/e2e

CODE MAP

Symbol	Type	Location	Role
AuthController	Controller	auth/AuthController.java	微信登录、JWT 认证
AdminController	Controller	admin/AdminController.java	管理端API
AssessmentOrderController	Controller	assessment/AssessmentOrderController.java	测评订单 CRUD、支付
AssessmentAppointmentController	Controller	assessment/AssessmentAppointmentController.java	测评预约管理
TaskService	Service	service/TaskService.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

• 后端: Spring Boot 标准分层 (Controller → Service → Mapper)
• 控制器分组: 按功能模块子目录 (admin, auth, assessment, family, guide 等)
• ORM: MyBatis-Plus，@TableName + @TableId(type = IdType.AUTO)
• API 响应: 统一 Result<T> (code/message/data)
• 认证: JWT Bearer Token，Authorization Header
• DI: @Resource 代替 @Autowired，字段名匹配默认 Bean Name
• 接口方法: 统一 @PostMapping，禁止 @GetMapping/@PutMapping/@DeleteMapping
• 前端: uni-app Vue 2 Options API
• Web前端: Vue 2 + Element UI，路由守卫处理角色权限

ANTI-PATTERNS

• DO NOT 在 Controller 中直接操作 Mapper
• DO NOT 硬编码 API 地址，使用配置
• DO NOT 在前端存储敏感信息
• NEVER 使用 @GetMapping/@PutMapping/@DeleteMapping — 统一 @PostMapping
• NEVER 使用 @Resource(name="xxx") 与字段名不一致
• NEVER 跳过 JWT 认证调用需登录接口
• NEVER 在微信小程序模板中使用可选链 ?. (不支持)

UNIQUE STYLES

• 双角色系统: 家长端/孩子端，role 字段分流。家长端可切换查看孩子视角，切换回来的孩子端退出切换需密码
• 成长规划师: 独立角色(teacher)，可登录规划师端，也可切换回家长视角
• 积分机制: 完成任务加分、超时扣分 (PointsService)
• 心愿审批: 孩子创建 → 家长审批 → 扣减积分
• 测评订单: 家长申请 → 选择规划师 → 孩子快照 → 支付 → 规划师录入结果
• 街道地址: 四级地址结构（省市区街道），区域回退匹配
• 多数据源: zxyj 主库 + sfms 源库 (只读迁移)

COMMANDS

# 后端
cd zxyj-backend && mvn clean compile  # 编译验证
mvn spring-boot:run                   # 启动 (localhost:8080)

# 前端小程序
cd zxyj-frontend && npm run dev:mp-weixin

# Web管理端
cd zxyj-web && npm run serve          # (localhost:8082)

# 迁移 sfms 历史数据
curl -X POST http://localhost:8080/api/migration/run

NOTES

• 数据库: MySQL 8.0 192.168.16.251:3306/zxyj (账号: zxyj/zxyj@123)
• sfms 源库: 同服务器 sfms 库 (需在 application.yml 确认)
• 后端端口: 8080, Web端口: 8082
• 小程序 AppID: wx5ba8038ef16fb245
• JWT 密钥在 application.yml，测试模式跳过微信API
• .idea/, 系统功能/, unpackage/, dist/ 为构建产物，不提交

HIERARCHICAL DOCUMENTATION

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