# 浠艾福 (XAF) - Project Knowledge Base

**Generated:** 2026-06-06
**Commit:** {CURRENT_COMMIT}
**Branch:** master

## OVERVIEW

三方平台型家庭教育服务系统，连接客户（家长）、服务商（成长规划师/活动方/供应商）和平台运营三方角色。三端架构：Spring Boot 2.7.18 后端 + uni-app 微信小程序 + Vue 2 Web管理端。

## STRUCTURE

```
cfc/
├── cfc-backend/       # Spring Boot 后端服务
│   └── src/main/java/com/etotem/cfc/
│       ├── controller/ # REST API (按功能分组)
│       │   ├── admin/      # 管理端
│       │   ├── assessment/ # 测评订单/预约
│       │   ├── auth/       # 认证
│       │   ├── family/     # 家庭管理
│       │   ├── growth/     # 成长档案
│       │   ├── guide/      # 成长规划师
│       │   ├── parent/     # 家长端
│       │   ├── reward/     # 奖励
│       │   ├── sncp/       # 社区/活动
│       │   ├── task/       # 任务
│       │   └── wish/       # 心愿单
│       ├── service/     # 业务逻辑
│       ├── entity/      # MyBatis-Plus 实体 (47个)
│       ├── mapper/      # MyBatis-Plus Mapper
│       ├── dto/         # 数据传输对象
│       ├── config/      # 配置 (JWT, 多数据源, DatabaseInitializer)
│       └── common/      # 公共类 (Result, JwtUtil)
│
├── cfc-frontend/      # uni-app 微信小程序
│   ├── pages/          # 页面 (20+ 目录)
│   │   ├── index/      # 首页（角色分流）
│   │   ├── assessment/ # 测评申请/下单/报告 (6页)
│   │   ├── growth/     # 成长档案
│   │   ├── guide/      # 成长规划师功能
│   │   ├── parent/     # 家长专属 (预约/市场/心愿)
│   │   ├── teacher/    # 规划师端 (预约管理)
│   │   └── ...         # tasks, rewards, profile 等
│   ├── App.vue         # 应用入口 (自动登录, 全局请求)
│   ├── store/          # Vuex (双角色状态管理)
│   └── utils/          # API调用封装
│
├── cfc-web/           # Vue 2 + Element UI Web管理端
│   └── src/
│       ├── views/      # 页面 (admin/ + teacher/)
│       ├── api/        # API封装
│       ├── router/     # Vue Router (角色权限守卫)
│       └── store/      # Vuex (认证状态)
│
├── docs/               # 文档
│   ├── superpowers/    # AI开发工具配置
│   ├── 需求分析/       # 需求分析文档
│   ├── 系统设计/       # 系统设计文档
│   └── 系统测试/       # 测试报告
│
└── tests/              # 分层测试 (unit/integration/e2e)
```

## WHERE TO LOOK

| Task | Location | Notes |
|------|----------|-------|
| 添加 REST API | `cfc-backend/.../controller/` | 按功能模块分组 |
| 修改业务逻辑 | `cfc-backend/.../service/` | 命名: `XxxService.java` |
| 添加数据实体 | `cfc-backend/.../entity/` | MyBatis-Plus @TableName |
| 数据库迁移 | `cfc-backend/.../config/DatabaseInitializer.java` | 启动时自动执行 |
| 多数据源 | `cfc-backend/.../config/SfmsDataSourceConfig.java` | sfms 只读源 |
| 数据迁移 | `cfc-backend/.../service/DataMigrationService.java` | 从sfms导入历史数据 |
| 添加小程序页面 | `cfc-frontend/pages/` | 需在 pages.json 注册 |
| 前端API | `cfc-frontend/utils/api.js` | 后端接口封装 |
| 修改全局样式 | `cfc-frontend/uni.scss` | SCSS变量 |
| Web前端 | `cfc-web/src/views/` + `src/router/index.js` | 角色菜单+路由 |
| 数据库配置 | `cfc-backend/src/main/resources/application.yml` | MySQL + sfms |
| 需求/设计文档 | `docs/需求分析/`, `docs/系统设计/` | Markdown格式 |
| 分层测试 | `tests/` | unit/integration/e2e |

## CODE MAP

| Symbol | Type | Location | Role |
|--------|------|----------|------|
| `AuthController` | Controller | `auth/AuthController.java` | 微信登录、JWT 认证 |
| `AdminController` | Controller | `admin/AdminController.java` | 管理端API |
| `AssessmentOrderController` | Controller | `assessment/AssessmentOrderController.java` | 测评订单 CRUD、支付 |
| `AssessmentAppointmentController` | Controller | `assessment/AssessmentAppointmentController.java` | 测评预约管理 |
| `TaskService` | Service | `service/TaskService.java` | 任务业务逻辑 |
| `DataMigrationService` | Service | `service/DataMigrationService.java` | sfms → cfc 全量迁移 |
| `User` | Entity | `entity/User.java` | 用户 (parent/child/teacher) |
| `Task` | Entity | `entity/Task.java` | 任务 |
| `DanAssessmentResult` | Entity | `entity/DanAssessmentResult.java` | DAN测评结果 (含孩子快照) |
| `DatabaseInitializer` | Config | `config/DatabaseInitializer.java` | 数据库迁移和初始化 |
| `SfmsDataSourceConfig` | Config | `config/SfmsDataSourceConfig.java` | sfms 多数据源 |

## CONVENTIONS

- **后端:** Spring Boot 标准分层 (Controller → Service → Mapper)
- **控制器分组:** 按功能模块子目录 (admin, auth, assessment, family, guide 等)
- **ORM:** MyBatis-Plus，`@TableName` + `@TableId(type = IdType.AUTO)`
- **API 响应:** 统一 `Result<T>` (code/message/data)
- **认证:** JWT Bearer Token，`Authorization` Header
- **DI:** `@Resource` 代替 `@Autowired`，字段名匹配默认 Bean Name
- **接口方法:** 统一 `@PostMapping`，禁止 `@GetMapping/@PutMapping/@DeleteMapping`
- **前端:** uni-app Vue 2 Options API
- **Web前端:** Vue 2 + Element UI，路由守卫处理角色权限

## ANTI-PATTERNS

- **DO NOT** 在 Controller 中直接操作 Mapper
- **DO NOT** 硬编码 API 地址，使用配置
- **DO NOT** 在前端存储敏感信息
- **NEVER** 使用 `@GetMapping/@PutMapping/@DeleteMapping` — 统一 `@PostMapping`
- **NEVER** 使用 `@Resource(name="xxx")` 与字段名不一致
- **NEVER** 跳过 JWT 认证调用需登录接口
- **NEVER** 在微信小程序模板中使用可选链 `?.` (不支持)

## UNIQUE STYLES

- **双角色系统:** 家长端/孩子端，`role` 字段分流。家长端可切换查看孩子视角，切换回来的孩子端退出切换需密码
- **成长规划师:** 独立角色(`teacher`)，可登录规划师端，也可切换回家长视角
- **积分机制:** 完成任务加分、超时扣分 (`PointsService`)
- **心愿审批:** 孩子创建 → 家长审批 → 扣减积分
- **测评订单:** 家长申请 → 选择规划师 → 孩子快照 → 支付 → 规划师录入结果
- **街道地址:** 四级地址结构（省市区街道），区域回退匹配
- **多数据源:** cfc 主库 + sfms 源库 (只读迁移)

## COMMANDS

```bash
# 后端
cd cfc-backend && mvn clean compile  # 编译验证
mvn spring-boot:run                   # 启动 (localhost:8080)

# 前端小程序
cd cfc-frontend && npm run dev:mp-weixin

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

# 迁移 sfms 历史数据
curl -X POST http://localhost:8080/api/migration/run
```

## NOTES

- 数据库: MySQL 8.0 `192.168.16.251:3306/cfc` (账号: cfc/cfc@123)
- sfms 源库: 同服务器 `sfms` 库 (需在 application.yml 确认)
- 后端端口: 8080, Web端口: 8082
- 小程序 AppID: `wx5ba8038ef16fb245`
- JWT 密钥在 `application.yml`，测试模式跳过微信API
- `.idea/`, `系统功能/`, `unpackage/`, `dist/` 为构建产物，不提交

## HIERARCHICAL DOCUMENTATION

```
cfc/
├── AGENTS.md                       # 项目总览 (本文件)
├── cfc-backend/AGENTS.md          # 后端详细文档
├── cfc-frontend/AGENTS.md         # 小程序前端文档
├── cfc-web/AGENTS.md              # Web管理端文档
├── tests/AGENTS.md                 # 测试策略文档
├── docs/superpowers/AGENTS.md      # AI开发工具配置
└── docs/需求分析/ 系统设计/ 系统测试/  # 需求/设计/测试文档
```