صفحهٔ اصلی گشت‌و‌گذار راهنما
ثبت نام ورود
liaoxg
/
cfc
1
1
انشعاب 0
پرونده‌ها مشکلات 0 درخواست واکشی 0 ویکی
درخت: b6fcae308e
شاخه‌ها تگ‌ها
cfc
/
AGENTS.md

AGENTS.md 6.8 KB
تاريخچه خام

浠艾福 (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
# 通过微信开发者工具导入项目根目录

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