docs: rewrite root AGENTS.md - compact, high-signal, removes stale refs

AGENTS.md

@@ -1,144 +1,86 @@
-# 浠艾福 (XAF) - Project Knowledge Base
+# 浠艾福 (XAF) - Agent 工作指南
 
-**Branch:** cfclub (146 commits ahead of master)
+## 重要工作流（易错点）
 
-## OVERVIEW
-
-三方平台型家庭教育服务系统，连接客户（家长）、服务商（成长规划师/活动方/供应商）和平台运营三方角色。三端架构：Spring Boot 2.7.18 后端 + uni-app 微信小程序 + Vue 2 Web管理端。另有 `dan/danshop/` 独立商城子系统（Spring Boot 项目）。
-
-## STRUCTURE
+### 数据库迁移（`Unknown column` 错误处理流程）
 
 ```
-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/, family/, body/, mind/, action/, profile/, teacher/, games/, assessment/, shop/, ...)
-│   ├── components/      # 可复用组件 (RelationshipPicker, ContactCard, FamilyRelationGraph, ...)
-│   ├── 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/             # 需求/设计/测试文档
+错误日志 → 查 entity 类 → 查 schema.sql → DatabaseInitializer 加迁移 → 同步 schema.sql → mvn compile
 ```
 
-## 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 |
-
-## RELATIONSHIP MANAGEMENT
-
-| 实体 | 表 | 说明 |
-|------|----|------|
-| `RelationshipType` | `relationship_types` | 关系类型字典（typeKey/typeName/capabilityRole/sortOrder/enabled） |
-| `FamilyMember` | `family_members` | 家庭成员（relationshipType FK → typeKey, capabilityRole, showToFamily） |
-| `Contact` | `contacts` | 社会联系人（relationshipType → family/friend/partner/colleague/other, intimacyLevel） |
-| `GuideFamilyRelation` | `guide_family_relations` | 规划师-家庭绑定（relationType, status） |
-
-| 前端组件 | 用途 |
-|----------|------|
-| `RelationshipPicker.vue` | 关系类型选择器（自动加载 API，v-model 双向绑定） |
-| `FamilyRelationGraph.vue` | 家庭关系图（Canvas 绘制，信任度=颜色，沟通=线宽） |
-| `ContactCard.vue` | 联系人卡片 |
-| `ContactImport.vue` | 手机通讯录导入 |
-
-| API 端点 | 控制器 | 用途 |
-|----------|--------|------|
-| `/api/family/member/*` | `FamilyMembersController` | 添加/列表/切换/踢出/更新成员 |
-| `/api/family/member/relationship-types` | `FamilyMembersController` | 获取已启用的关系类型 |
-| `/api/admin/relationship-type/*` | `RelationshipTypeAdminController` | 管理端关系类型 CRUD |
-| `/api/bind/*` | `BindController` | 家长-规划师绑定 |
-| `/api/guide/bind/*` | `BindInviteController` | 规划师绑定邀请 |
-
-## 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 对话集成
-- 家庭成员关系编辑（前端：RelationshipPicker + family-members 编辑弹窗）
-- 关系类型 CRUD 管理（Web管理端 RelationshipTypes.vue）
-- 联系人管理（ContactCard, ContactImport, contact-detail）
-
-## COMMANDS
+- **唯一入口**: `DatabaseInitializer.runMigrations()` — 所有 DDL 迁移写在这里
+- **首选**: `ensureColumn(table, column, definition)` — 自动忽略"列已存在"异常
+- **必须同步 schema.sql**: 每次迁移后 schema.sql 的 `CREATE TABLE` 也必须同步更新
+- **迁移编号**: 搜索 `// 迁移` 找最新编号，递增
+- **幂等**: 所有迁移可重复执行
+
+### Git 工作流（易踩坑）
+
+- `git checkout -- file` 会丢弃**工作区和已 staged** 的改动（不可恢复）
+- `git stash pop` 会将 stash 内容合并到工作区，可能带入不相关的改动
+- 多模块同时修改时：用 `git add -p` 或分次 `git add` 精确控制 staged 范围
+- 提交前：`git diff --cached --stat` 检查 staged 内容是否仅包含目标文件
+
+### 新增 Controller/Service 前必做
+
+1. `mvn clean compile` — 验证无编译冲突
+2. 检查路由重复：`grep -rn '@Mapping' cfc-backend/src/.../controller/ | grep -oP '@\w+Mapping\("\K[^"]*' | sort -u`
+3. 检查 Bean 命名冲突：Spring 默认 Bean Name 为类名首字母小写，不同包的同名类会冲突
+
+## 项目结构
+
+| 模块 | 技术栈 | 端口 |
+|------|--------|------|
+| `cfc-backend/` | Spring Boot 2.7.18 + MyBatis-Plus + Java 8 | 9082 |
+| `cfc-frontend/` | uni-app 微信小程序 (Vue 2, Options API) | — |
+| `cfc-web/` | Vue 2 + Element UI 管理端 | 8082 |
+| `dan/danshop/` | 独立商城 Spring Boot | 8888 |
+
+## 常用命令
 
 ```bash
 # 后端
-cd cfc-backend && mvn clean compile   # 编译验证
+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
-# 通过微信开发者工具导入项目根目录
+npm run build                          # 生产构建 → rsync 到 192.168.16.251:/var/www/cfc-admin/
 
-# 管理端部署 (cfc-web)
-# 编译 → rsync 到 192.168.16.251
-cd cfc-web && npm run build && rsync -av --delete dist/ 192.168.16.251:/var/www/cfc-admin/
+# 小程序：npm install 后用微信开发者工具导入根目录
+# 管理端部署服务器脚本: bash /home/iwt/cfc-auto-deploy.sh
 
-# 服务器上有自动化部署脚本 /home/iwt/cfc-auto-deploy.sh
-# 可在 251 上执行: bash /home/iwt/cfc-auto-deploy.sh
-
-# 数据迁移 (从 sfms 导入历史数据)
+# 数据迁移 (sfms → zxyj)
 curl -X POST http://localhost:9082/api/migration/run
 ```
 
-## HIERARCHICAL INSTRUCTION FILES
+## 数据库
+
+- 地址：`192.168.16.251:3306/zxyj`（账号 `zxyj / zxyj@123`）
+- 只读源库：`bianwoyou.mysql.rds.aliyuncs.com:3305/sfms`（`SfmsDataSourceConfig` 配置）
+- 建表定义：`cfc-backend/src/main/resources/schema.sql`（完整快照）
+- 迁移入口：`cfc-backend/src/main/java/com/etotem/cfc/config/DatabaseInitializer.java`
+
+## 核心框架约定
+
+- **接口**: 统一 `@PostMapping`，禁止 `@GetMapping/@PutMapping/@DeleteMapping`
+- **ORM**: MyBatis-Plus `@TableName` + `@TableId(type = IdType.AUTO)`
+- **响应**: `Result<T>` (code/message/data)
+- **认证**: JWT Bearer Token，`JwtInterceptor` 拦截 `/api/**`（8个公开路径除外）
+- **DI**: `@Resource`，字段名必须与类型默认 Bean Name 一致
+- **角色控制**: 控制器内手动检查 `@RequestAttribute("role")`
+
+## 小程序限制
+
+- 禁止可选链 `?.`（用 `&&` 替代）
+- 禁止 CSS Grid（用 flexbox）
+- Vue 2 Options API，禁止 Composition API
 
-- `cfc-backend/AGENTS.md` — 后端详细规范
-- `cfc-frontend/AGENTS.md` — 小程序前端规范
-- `cfc-web/AGENTS.md` — Web管理端规范
-- `tests/AGENTS.md` — 分层测试策略
+## 子模块详细规范
 
-@RTK.md
+| 文件 | 内容 |
+|------|------|
+| `cfc-backend/AGENTS.md` | 后端详细规范 + 数据库迁移工作流 |
+| `cfc-frontend/AGENTS.md` | 小程序前端规范 |
+| `cfc-web/AGENTS.md` | Web管理端规范 |
+| `tests/AGENTS.md` | 分层测试策略 |