cfc/AGENTS.md

浠艾福 (XAF) - Project Knowledge Base

Branch: cfclub (146 commits ahead of master)

OVERVIEW

三方平台型家庭教育服务系统，连接客户（家长）、服务商（成长规划师/活动方/供应商）和平台运营三方角色。三端架构：Spring Boot 2.7.18 后端 + uni-app 微信小程序 + Vue 2 Web管理端。另有 dan/danshop/ 独立商城子系统（Spring Boot 项目）。

STRUCTURE

cfc/
├── cfc-backend/     # Spring Boot 2.7.18, MyBatis-Plus, JWT, Java 8
│   └── src/main/java/com/etotem/cfc/
│       ├── controller/   # 按功能子包: admin, auth, assessment, family, guide, task, reward, energy, sncp, market, vendor, payment, stats, streak
│       ├── service/      # 业务逻辑
│       ├── entity/       # MyBatis-Plus 实体
│       ├── config/       # JWT / 多数据源 / DatabaseInitializer
│       └── common/       # Result<T>, JwtUtil
├── cfc-frontend/    # uni-app 微信小程序 (Vue 2, Options API)
│   ├── pages/           # 页面 (index/, body/, mind/, action/, profile/, teacher/, games/, assessment/, shop/, ...)
│   ├── pages.json       # TabBar (首页/身体/心智/行动/我的) + 分包注册
│   ├── config.js        # 环境自适应 baseUrl (develop/trial/release)
│   └── store/           # Vuex 双角色状态
├── cfc-web/          # Vue 2 + Element UI 管理端
│   └── src/
│       ├── views/       # admin/ + teacher/ 视图
│       ├── router/      # 角色权限路由守卫
│       └── store/       # 认证状态
├── dan/danshop/      # 独立商城 Spring Boot 子系统 (localhost:8888)
├── tests/            # unit, integration, e2e (Playwright)
└── docs/             # 需求/设计/测试文档

KEY FACTS

项目	命令/端口	备注
后端	mvn clean compile / mvn spring-boot:run	localhost:9082
小程序	npm install → 微信开发者工具导入	dev:mp-weixin 需通过 uni-app CLI 或 HBuilderX
Web管理端	npm run serve	localhost:8082
数据库	192.168.16.251:3306/zxyj	账号 zxyj / zxyj@123
sfms源库	bianwoyou.mysql.rds.aliyuncs.com:3305/sfms	只读，用于数据迁移
Danshop	localhost:8888	独立 Spring Boot 商城子系统
数据迁移	curl -X POST http://localhost:9082/api/migration/run	sfms → zxyj

CONVENTIONS

• 接口: 统一 @PostMapping，禁止 @GetMapping/@PutMapping/@DeleteMapping
• ORM: MyBatis-Plus @TableName + @TableId(type = IdType.AUTO)
• 响应: 统一 Result<T> (code/message/data)
• 认证: JWT Bearer Token，Authorization Header；JwtInterceptor 拦截 /api/**（8个公开路径除外）
• DI: @Resource 替代 @Autowired，字段名匹配默认 Bean Name
• 角色控制: 控制器内手动检查 @RequestAttribute("role")
• 小程序限制: 禁止可选链 ?.（用 && 替代）、禁止 CSS Grid（用 flexbox）
• 新增Controller/Service: 检查类名是否与其他包重名（Spring Bean Name 冲突）
• 新增路由: 运行 grep -rn '@Mapping' cfc-backend/src/.../controller/ | grep -oP '@\w+Mapping\("\K[^"]*' | sort -u 检查重复

UNIQUE STYLES

• 双角色: 家长端可切换查看孩子视角；直接登录的孩子端不能切换到家长端
• 成长规划师: role=teacher，可登录规划师端，也可切换回家长视角
• 五维能量: 身/心/智/行/富维度体系，能量按比例分配
• 测评订单: 家长申请 → 选择规划师 → 孩子快照 → 支付 → 规划师录入结果
• 四级地址: 省市区街道，区域回退匹配
• 多数据源: cfc 主库 + sfms 只读源（SfmsDataSourceConfig）
• 环境自适应: 小程序 config.js 通过 uni.getAccountInfoSync() 自动切换 develop/trial/release 的 API 地址
• 测试模式: wechat.test-mode: true 跳过微信 API，使用模拟数据

cfclub 新特性

• 家庭邀请二维码（小程序码+令牌+落地页）
• 健康报告 PDF 上传与解析
• 文章发布-审核系统
• 饮食推荐系统（前端+后端）
• 维度配置与知识库管理（Web管理端）
• 家庭关系图重设计
• 成长记录重构
• Dify AI 对话集成

COMMANDS

# 后端
cd cfc-backend && mvn clean compile   # 编译验证
mvn spring-boot:run                    # 启动 (localhost:9082)
mvn test                               # 运行测试

# Web管理端
cd cfc-web && npm run serve            # 开发 (localhost:8082)
npm run build                          # 生产构建
npm test                               # Jest 测试

# 小程序 (uni-app, 需全局 CLI 或 HBuilderX)
cd cfc-frontend && npm install
# 通过微信开发者工具导入项目根目录

# 数据迁移 (从 sfms 导入历史数据)
curl -X POST http://localhost:9082/api/migration/run

HIERARCHICAL INSTRUCTION FILES

• cfc-backend/AGENTS.md — 后端详细规范
• cfc-frontend/AGENTS.md — 小程序前端规范
• cfc-web/AGENTS.md — Web管理端规范
• tests/AGENTS.md — 分层测试策略

@RTK.md