# 浠艾福 (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/, 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/             # 需求/设计/测试文档
```

## 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

```bash
# 后端
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
# 通过微信开发者工具导入项目根目录

# 管理端部署 (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/

# 服务器上有自动化部署脚本 /home/iwt/cfc-auto-deploy.sh
# 可在 251 上执行: bash /home/iwt/cfc-auto-deploy.sh

# 数据迁移 (从 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