docs: update AGENTS.md for cfclub branch (146 commits ahead)

重构项目知识库文档，更新分支状态、新增 danshop 子系统、补充 cfclub 新特性等。

Ultraworked with Sisyphus

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>

AGENTS.md

@@ -1,238 +1,109 @@
 # 浠艾福 (XAF) - Project Knowledge Base
 
-**Generated:** 2026-06-06
-**Commit:** {CURRENT_COMMIT}
-**Branch:** master
+**Branch:** cfclub (146 commits ahead of master)
 
 ## OVERVIEW
 
-三方平台型家庭教育服务系统，连接客户（家长）、服务商（成长规划师/活动方/供应商）和平台运营三方角色。三端架构：Spring Boot 2.7.18 后端 + uni-app 微信小程序 + Vue 2 Web管理端。
+三方平台型家庭教育服务系统，连接客户（家长）、服务商（成长规划师/活动方/供应商）和平台运营三方角色。三端架构：Spring Boot 2.7.18 后端 + uni-app 微信小程序 + Vue 2 Web管理端。另有 `dan/danshop/` 独立商城子系统（Spring Boot 项目）。
 
 ## STRUCTURE
 
 ```
 cfc/
-├── cfc-backend/       # Spring Boot 后端服务
+├── cfc-backend/     # Spring Boot 2.7.18, MyBatis-Plus, JWT, Java 8
 │   └── src/main/java/com/etotem/cfc/
-│       ├── 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)
-│
-├── cfc-frontend/      # uni-app 微信小程序
-│   ├── pages/          # 页面 (20+ 目录)
-│   │   ├── index/      # 首页（角色分流）
-│   │   ├── assessment/ # 测评申请/下单/报告 (6页)
-│   │   ├── growth/     # 成长档案
-│   │   ├── guide/      # 成长规划师功能
-│   │   ├── parent/     # 家长专属 (预约/市场/心愿)
-│   │   ├── teacher/    # 规划师端 (预约管理)
-│   │   └── ...         # tasks, rewards, profile 等
-│   ├── App.vue         # 应用入口 (自动登录, 全局请求)
-│   ├── store/          # Vuex (双角色状态管理)
-│   └── utils/          # API调用封装
-│
-├── cfc-web/           # Vue 2 + Element UI Web管理端
+│       ├── 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/)
-│       ├── api/        # API封装
-│       ├── router/     # Vue Router (角色权限守卫)
-│       └── store/      # Vuex (认证状态)
-│
-├── docs/               # 文档
-│   ├── superpowers/    # AI开发工具配置
-│   ├── 需求分析/       # 需求分析文档
-│   ├── 系统设计/       # 系统设计文档
-│   └── 系统测试/       # 测试报告
-│
-└── tests/              # 分层测试 (unit/integration/e2e)
+│       ├── views/       # admin/ + teacher/ 视图
+│       ├── router/      # 角色权限路由守卫
+│       └── store/       # 认证状态
+├── dan/danshop/      # 独立商城 Spring Boot 子系统 (localhost:8888)
+├── tests/            # unit, integration, e2e (Playwright)
+└── docs/             # 需求/设计/测试文档
 ```
 
-## WHERE TO LOOK
-
-| Task | Location | Notes |
-|------|----------|-------|
-| 添加 REST API | `cfc-backend/.../controller/` | 按功能模块分组 |
-| 修改业务逻辑 | `cfc-backend/.../service/` | 命名: `XxxService.java` |
-| 添加数据实体 | `cfc-backend/.../entity/` | MyBatis-Plus @TableName |
-| 数据库迁移 | `cfc-backend/.../config/DatabaseInitializer.java` | 启动时自动执行 |
-| 多数据源 | `cfc-backend/.../config/SfmsDataSourceConfig.java` | sfms 只读源 |
-| 数据迁移 | `cfc-backend/.../service/DataMigrationService.java` | 从sfms导入历史数据 |
-| 添加小程序页面 | `cfc-frontend/pages/` | 需在 pages.json 注册 |
-| 前端API | `cfc-frontend/utils/api.js` | 后端接口封装 |
-| 修改全局样式 | `cfc-frontend/uni.scss` | SCSS变量 |
-| Web前端 | `cfc-web/src/views/` + `src/router/index.js` | 角色菜单+路由 |
-| 数据库配置 | `cfc-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 → cfc 全量迁移 |
-| `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 多数据源 |
+## 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
 
-- **后端:** 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** 在微信小程序模板中使用可选链 `?.` (不支持)
+- **接口:** 统一 `@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`)，可登录规划师端，也可切换回家长视角
-- **积分机制:** 完成任务加分、超时扣分 (`PointsService`)
-- **心愿审批:** 孩子创建 → 家长审批 → 扣减积分
+- **双角色:** 家长端可切换查看孩子视角；直接登录的孩子端不能切换到家长端
+- **成长规划师:** `role=teacher`，可登录规划师端，也可切换回家长视角
+- **五维能量:** 身/心/智/行/富维度体系，能量按比例分配
 - **测评订单:** 家长申请 → 选择规划师 → 孩子快照 → 支付 → 规划师录入结果
-- **街道地址:** 四级地址结构（省市区街道），区域回退匹配
-- **多数据源:** cfc 主库 + sfms 源库 (只读迁移)
+- **四级地址:** 省市区街道，区域回退匹配
+- **多数据源:** cfc 主库 + sfms 只读源（`SfmsDataSourceConfig`）
+- **环境自适应:** 小程序 `config.js` 通过 `uni.getAccountInfoSync()` 自动切换 develop/trial/release 的 API 地址
+- **测试模式:** `wechat.test-mode: true` 跳过微信 API，使用模拟数据
+
+## cfclub 新特性
+
+- 家庭邀请二维码（小程序码+令牌+落地页）
+- 健康报告 PDF 上传与解析
+- 文章发布-审核系统
+- 饮食推荐系统（前端+后端）
+- 维度配置与知识库管理（Web管理端）
+- 家庭关系图重设计
+- 成长记录重构
+- Dify AI 对话集成
 
 ## COMMANDS
 
 ```bash
 # 后端
-cd cfc-backend && mvn clean compile  # 编译验证
-mvn spring-boot:run                   # 启动 (localhost:8080)
-
-# 前端小程序
-cd cfc-frontend && npm run dev:mp-weixin
+cd cfc-backend && mvn clean compile   # 编译验证
+mvn spring-boot:run                    # 启动 (localhost:9082)
+mvn test                               # 运行测试
 
 # Web管理端
-cd cfc-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/cfc` (账号: cfc/cfc@123)
-- sfms 源库: 同服务器 `sfms` 库 (需在 application.yml 确认)
-- 后端端口: 8080, Web端口: 8082
-- 小程序 AppID: `wx5ba8038ef16fb245`
-- JWT 密钥在 `application.yml`，测试模式跳过微信API
-- `.idea/`, `系统功能/`, `unpackage/`, `dist/` 为构建产物，不提交
-
-## HIERARCHICAL DOCUMENTATION
-
-```
-cfc/
-├── AGENTS.md                       # 项目总览 (本文件)
-├── cfc-backend/AGENTS.md          # 后端详细文档
-├── cfc-frontend/AGENTS.md         # 小程序前端文档
-├── cfc-web/AGENTS.md              # Web管理端文档
-├── tests/AGENTS.md                 # 测试策略文档
-├── docs/superpowers/AGENTS.md      # AI开发工具配置
-└── docs/需求分析/ 系统设计/ 系统测试/  # 需求/设计/测试文档
-```
-
-## Behavioral Guidelines for Agent Roles
-
-These guidelines apply to all AI agents in this project. They are automatically added when a new role is created via `/init-agent --new`.
-
-# Behavioral Guidelines
-
-General principles to reduce common LLM coding mistakes. Merge with role-specific instructions as needed.
-
-**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+cd cfc-web && npm run serve            # 开发 (localhost:8082)
+npm run build                          # 生产构建
+npm test                               # Jest 测试
 
-## 1. Think Before Coding
+# 小程序 (uni-app, 需全局 CLI 或 HBuilderX)
+cd cfc-frontend && npm install
+# 通过微信开发者工具导入项目根目录
 
-**Don't assume. Don't hide confusion. Surface tradeoffs.**
-
-Before implementing:
-- State your assumptions explicitly. If uncertain, ask.
-- If multiple interpretations exist, present them — don't pick silently.
-- If a simpler approach exists, say so. Push back when warranted.
-- If something is unclear, stop. Name what's confusing. Ask.
-
-## 2. Simplicity First
-
-**Minimum code that solves the problem. Nothing speculative.**
-
-- No features beyond what was asked.
-- No abstractions for single-use code.
-- No "flexibility" or "configurability" that wasn't requested.
-- No error handling for impossible scenarios.
-- If you write 200 lines and it could be 50, rewrite it.
-
-Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
-
-## 3. Surgical Changes
-
-**Touch only what you must. Clean up only your own mess.**
-
-When editing existing code:
-- Don't "improve" adjacent code, comments, or formatting.
-- Don't refactor things that aren't broken.
-- Match existing style, even if you'd do it differently.
-- If you notice unrelated dead code, mention it — don't delete it.
-
-When your changes create orphans:
-- Remove imports/variables/functions that YOUR changes made unused.
-- Don't remove pre-existing dead code unless asked.
-
-The test: Every changed line should trace directly to the user's request.
-
-## 4. Goal-Driven Execution
-
-**Define success criteria. Loop until verified.**
-
-Transform tasks into verifiable goals:
-- "Add validation" → "Write tests for invalid inputs, then make them pass"
-- "Fix the bug" → "Write a test that reproduces it, then make it pass"
-- "Refactor X" → "Ensure tests pass before and after"
-
-For multi-step tasks, state a brief plan:
-```
-1. [Step] → verify: [check]
-2. [Step] → verify: [check]
-3. [Step] → verify: [check]
+# 数据迁移 (从 sfms 导入历史数据)
+curl -X POST http://localhost:9082/api/migration/run
 ```
 
-Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+## HIERARCHICAL INSTRUCTION FILES
 
----
+- `cfc-backend/AGENTS.md` — 后端详细规范
+- `cfc-frontend/AGENTS.md` — 小程序前端规范
+- `cfc-web/AGENTS.md` — Web管理端规范
+- `tests/AGENTS.md` — 分层测试策略
 
-*These guidelines are working if: fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.*
+@RTK.md