浠艾福 (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
# 后端
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
