浠艾福 (XAF) - Project Knowledge Base

Branch: cfclub Updated: 2026-06-19

OVERVIEW

三方平台型家庭教育服务平台。家长 + 孩子 + 服务商(成长规划师/供应商) + 平台运营。三端架构：Spring Boot 2.7.18 (Java 8) 后端 + uni-app Vue 2 微信小程序 + Vue 2 + Element UI Web 管理端。

关键数字：100+ Java 文件、~50 小程序页面、29 Web 管理页面、47+ 数据实体、60+ 控制器。

STRUCTURE

cfc/
├── cfc-backend/                       # Spring Boot 后端 (port 9082)
│   └── src/main/java/com/etotem/cfc/
│       ├── controller/                # 60+ 控制器，按功能子包分组
│       ├── service/                   # 业务逻辑层
│       ├── entity/                    # MyBatis-Plus 实体 (@Data + @TableName)
│       ├── mapper/                    # MyBatis-Plus Mapper 接口
│       ├── dto/                       # 数据传输对象 (~120 个)
│       ├── config/                    # JWT / 多数据源 / DatabaseInitializer / WebConfig
│       ├── common/                    # Result, ProductStatus
│       └── task/                      # 定时任务 (RepeatTaskGenerator, PointsExpireTask 等)
│
├── cfc-frontend/                      # uni-app 微信小程序
│   ├── pages/                         # ~50 页面
│   ├── components/                    # 29 个可复用组件
│   ├── store/index.js                 # Vuex 角色状态管理
│   ├── utils/api.js                   # 1247 行 API 封装
│   ├── config.js                      # 环境感知 API 地址
│   └── pages.json                     # 5-Tab: 首页/身体/心智/关系/我的（TabBar 文案，非五维维度名）
│
├── cfc-web/                           # Vue 2 + Element UI Web 管理端
│   └── src/
│       ├── views/                     # admin/ + teacher/
│       ├── router/                    # 角色权限守卫
│       └── store/                     # 认证状态
│
├── docs/                              # 需求/设计/测试文档
├── tests/                             # unit/integration/e2e (基础设施不完整)
└── .superpowers/                      # superpowers 配置

WHERE TO LOOK

Task	Location	Notes
REST API	`cfc-backend/.../controller/`	按功能模块分组子目录
业务逻辑	`cfc-backend/.../service/`	命名: `XxxService.java`
数据实体	`cfc-backend/.../entity/`	MyBatis-Plus `@TableName` + `@Data`
配置	`cfc-backend/.../config/`	JWT / 多数据源 / DatabaseInitializer / WebConfig
通用响应	`cfc-backend/.../common/Result.java`	`Result<T>` (code/message/data)
小程序页面	`cfc-frontend/pages/`	需在 `pages.json` 注册
小程序 API	`cfc-frontend/utils/api.js`	统一 `request()` 封装，含自定义 header
小程序配置	`cfc-frontend/config.js`	环境自动检测 (develop/trial/release)
小程序状态	`cfc-frontend/store/index.js`	Vuex: token/role/currentRole/isSwitchedChild
Web 前端	`cfc-web/src/views/` + `router/index.js`	角色权限路由
Web API	`cfc-web/src/api/`	axios 封装
数据库配置	`cfc-backend/src/main/resources/application.yml`	主库 `zxyj` + sfms 源库
SQL 迁移	`cfc-backend/src/main/resources/schema*.sql` + `DatabaseInitializer.java`	启动时自动执行
测试	`tests/`	unit/integration/e2e

CRITICAL CONFIG (不查会错)

后端端口：9082（不是 8080）
数据库名：zxyj（不是 cfc），地址 192.168.16.251:3306，账号 zxyj / zxyj@123
sfms 源库：bianwoyou.mysql.rds.aliyuncs.com:3305/sfms，账号 sfms / sfms@123
JWT secret：cfc-secret-key-2026-spring-boot-jwt-token，过期 24h
微信测试模式：wechat.test-mode: true，使用 13800138000 模拟手机号
Dify AI：http://dify.bianwoyou.cn/v1 with API key
小程序 AppID：wx5ba8038ef16fb245
Web 端口：8082

COMMANDS

# 后端
cd cfc-backend && mvn clean compile   # 编译验证（必做）
mvn spring-boot:run                    # 启动 localhost:9082
mvn test                               # 运行测试（目前只有1个测试类）

# 小程序（需微信开发者工具）
cd cfc-frontend && npm install && npm run dev:mp-weixin

# Web 管理端
cd cfc-web && npm install && npm run serve  # localhost:8082

# 数据迁移
curl -X POST http://localhost:9082/api/migration/run

CONVENTIONS

后端

分层: Controller → Service → Mapper，禁止跨层调用
ORM: MyBatis-Plus，@TableName + @TableId(type = IdType.AUTO)
响应: 统一 Result<T>（code/message/data），成功 code=200，错误 code=500/400
认证: JWT Bearer Token，JwtInterceptor 拦截 /api/**，约 15 个公开路径放行
异常处理: 仅 GlobalExceptionHandler 处理 IllegalArgumentException → 400
DI: @Resource 优先（180+ 处），@Autowired 仅 3 处（AdminGuideController.java）
Lombok: 全项目使用（实体 @Data, 日志 @Slf4j, 配置类等）
Swagger: 每个 Controller 类有 @Tag，62 个文件含 Swagger 注解
CORS: WebConfig 全放通
上传: ./uploads/ 目录，通过 /uploads/** 静态资源访问
定时任务: task/ 包下，含任务重复生成器、积分过期、连续签到重置等

接口方法 (重要 - 规则与实际有偏差)

声明的规则：统一 @PostMapping，禁止 @GetMapping/@PutMapping/@DeleteMapping。

实际情况：9 个控制器违反此规则，主要分布在：

DanAssessmentController — 12 个 @GetMapping（测评结果查询）
WishController — 6 个 @PutMapping/@DeleteMapping（心愿状态变更）
GuideManagementController、GuideFamilyTaskController — PUT/DELETE
TaskTemplatePackageController — PUT/DELETE
其他零星违反

→ 新代码尽量用 @PostMapping，但改造已有 @GetMapping/@PutMapping/@DeleteMapping 前需确认。

前端小程序

Vue 2 Options API，生命周期 onLoad/onShow（非 mounted）
禁止可选链 ?. — 仅 1 个文件违规（teacher-profile.vue 2 处），一律用 && 替代
禁止 CSS Grid — 用 flexbox
API 调用: uni.request + 自定义 header X-User-Id + Authorization: Bearer
环境自动检测: uni.getAccountInfoSync().miniProgram.envVersion（develop/trial/release）
4 套 API Base URL: localhost:9082 / cfc.iwintrue.com / cfc.etotem.com.cn + danshop 独立地址
DanShop 电商模块: 独立服务（port 8081/8888），通过 danshopRequest() 调用
TabBar 5 标签: 首页/身体/心智/关系/我的（TabBar 文案，非五维维度名），角色感知（家长/孩子/规划师展示不同内容）
页面注册仅子包: pages.json

Web 管理端

Vue 2 + Element UI，Options API
Element UI 补丁: main.js 中修补 el-submenu 的 removeTabindex null 错误
路由守卫: router.beforeEach 验证 token → 调 /api/admin-auth/info → 角色分流
Layout 遮罩防御: v-modal { display: none !important }
路由错误抑制: 覆盖 VueRouter.prototype.push 捕获 Redirected 导航错误

UNIQUE STYLES

双角色系统: 家长 parent ↔ 孩子 child 切换，currentRole 状态标记，切回需密码
教师角色: teacher 独立角色，可登录规划师端，也可切回家长视角；isSwitchedTeacher 状态标记
角色字段: 数据库 role ENUM + 多角色 roles 字段；vendor_type 次级角色
积分机制: 任务完成加分、超时扣分，PointsService 处理
心愿审批: 孩子创建 → 家长审批定价 → 扣减积分 → 确认收货
测评订单: 家长申请 → 选规划师 → 孩子信息快照 → 支付 → 规划师录入结果
四级地址: 省市区街道，回退匹配，StreetController 提供 API
孩子快照: 测评时保存身高/体重/学校到 DanAssessmentResult
多数据源: cfc 主库 + sfms 源库（只读迁移）
五维能量: 身(body)/心(mind)/智(wisdom)/行(behavior)/富(wealth)，EnergyService
- TabBar 第4标签显示为"关系"，但五维维度名是"行"（行为决定关系）
AI 聊天: Dify 后端，AIChatController + 独立 pages/ai/chat.vue
电商: DanShop 独立服务，danshopRequest() 调用，含完整购物车/订单/物流
推广裂变: 佣金/提现/团队，CommissionController/WithdrawalController

ANTI-PATTERNS

DO NOT 在 Controller 中直接操作 Mapper
DO NOT 硬编码 API 地址（用 config.js 或 application.yml）
DO NOT 在前端存敏感信息（密码、密钥）
NEVER 使用 @Resource(name="xxx") 与字段名不一致
NEVER 跳过 JWT 认证直接调用需登录接口
NEVER 使用 @GetMapping/@PutMapping/@DeleteMapping — 统一 @PostMapping（除非确认改造范围）
NEVER 在小程序模板中用 ?.（用 &&）
NEVER 对 Java 源文件用 awk '!seen[$0]++' 去重（会删合法重复行）
NEVER 直接 new XxxMapper() — 必须通过 @Resource 注入

VERIFICATION WORKFLOW

改后端 → mvn clean compile 确认编译通过
mvn spring-boot:run 确认应用正常启动（显示 Started）
测试相关 API 端点
改前端 → npm run dev:mp-weixin 或 npm run serve（Web 端）
lsp_diagnostics 检查改过的文件

HIERARCHICAL DOCUMENTATION

cfc/
├── AGENTS.md                       # 本文件
├── cfc-backend/AGENTS.md          # 后端详细文档
├── cfc-frontend/AGENTS.md         # 小程序前端文档
├── cfc-web/AGENTS.md              # Web管理端文档
├── tests/AGENTS.md                 # 测试策略文档（基础设施不完整）
└── docs/                           # 需求/设计/测试文档

AGENTS.md 10.0 KB Historia Raaka