|
|
@@ -1,168 +1,190 @@
|
|
|
# 浠艾福 (XAF) - Project Knowledge Base
|
|
|
|
|
|
-**Generated:** 2026-06-06
|
|
|
-**Commit:** {CURRENT_COMMIT}
|
|
|
-**Branch:** master
|
|
|
+**Branch:** cfclub
|
|
|
+**Updated:** 2026-06-19
|
|
|
|
|
|
## OVERVIEW
|
|
|
|
|
|
-三方平台型家庭教育服务系统，连接客户（家长）、服务商（成长规划师/活动方/供应商）和平台运营三方角色。三端架构：Spring Boot 2.7.18 后端 + uni-app 微信小程序 + Vue 2 Web管理端。
|
|
|
+三方平台型家庭教育服务平台。家长 + 孩子 + 服务商(成长规划师/供应商) + 平台运营。三端架构：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 后端服务
|
|
|
+├── cfc-backend/ # Spring Boot 后端 (port 9082)
|
|
|
│ └── 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)
|
|
|
+│ ├── 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/ # 页面 (20+ 目录)
|
|
|
-│ │ ├── index/ # 首页（角色分流）
|
|
|
-│ │ ├── assessment/ # 测评申请/下单/报告 (6页)
|
|
|
-│ │ ├── growth/ # 成长档案
|
|
|
-│ │ ├── guide/ # 成长规划师功能
|
|
|
-│ │ ├── parent/ # 家长专属 (预约/市场/心愿)
|
|
|
-│ │ ├── teacher/ # 规划师端 (预约管理)
|
|
|
-│ │ └── ... # tasks, rewards, profile 等
|
|
|
-│ ├── App.vue # 应用入口 (自动登录, 全局请求)
|
|
|
-│ ├── store/ # Vuex (双角色状态管理)
|
|
|
-│ └── utils/ # API调用封装
|
|
|
+├── 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管理端
|
|
|
+├── cfc-web/ # Vue 2 + Element UI Web 管理端
|
|
|
│ └── src/
|
|
|
-│ ├── views/ # 页面 (admin/ + teacher/)
|
|
|
-│ ├── api/ # API封装
|
|
|
-│ ├── router/ # Vue Router (角色权限守卫)
|
|
|
-│ └── store/ # Vuex (认证状态)
|
|
|
-│
|
|
|
-├── docs/ # 文档
|
|
|
-│ ├── superpowers/ # AI开发工具配置
|
|
|
-│ ├── 需求分析/ # 需求分析文档
|
|
|
-│ ├── 系统设计/ # 系统设计文档
|
|
|
-│ └── 系统测试/ # 测试报告
|
|
|
+│ ├── views/ # admin/ + teacher/
|
|
|
+│ ├── router/ # 角色权限守卫
|
|
|
+│ └── store/ # 认证状态
|
|
|
│
|
|
|
-└── tests/ # 分层测试 (unit/integration/e2e)
|
|
|
+├── 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 |
|
|
|
-| 数据库迁移 | `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 多数据源 |
|
|
|
+| 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
|
|
|
|
|
|
-## CONVENTIONS
|
|
|
+## COMMANDS
|
|
|
|
|
|
-- **后端:** 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，路由守卫处理角色权限
|
|
|
+```bash
|
|
|
+# 后端
|
|
|
+cd cfc-backend && mvn clean compile # 编译验证（必做）
|
|
|
+mvn spring-boot:run # 启动 localhost:9082
|
|
|
+mvn test # 运行测试（目前只有1个测试类）
|
|
|
|
|
|
-## ANTI-PATTERNS
|
|
|
+# 小程序（需微信开发者工具）
|
|
|
+cd cfc-frontend && npm install && npm run dev:mp-weixin
|
|
|
|
|
|
-- **DO NOT** 在 Controller 中直接操作 Mapper
|
|
|
-- **DO NOT** 硬编码 API 地址，使用配置
|
|
|
-- **DO NOT** 在前端存储敏感信息
|
|
|
-- **NEVER** 使用 `@GetMapping/@PutMapping/@DeleteMapping` — 统一 `@PostMapping`
|
|
|
-- **NEVER** 使用 `@Resource(name="xxx")` 与字段名不一致
|
|
|
-- **NEVER** 跳过 JWT 认证调用需登录接口
|
|
|
-- **NEVER** 在微信小程序模板中使用可选链 `?.` (不支持)
|
|
|
+# Web 管理端
|
|
|
+cd cfc-web && npm install && npm run serve # localhost:8082
|
|
|
|
|
|
-## UNIQUE STYLES
|
|
|
+# 数据迁移
|
|
|
+curl -X POST http://localhost:9082/api/migration/run
|
|
|
+```
|
|
|
|
|
|
-- **双角色系统:** 家长端/孩子端，`role` 字段分流。家长端可切换查看孩子视角，切换回来的孩子端退出切换需密码
|
|
|
-- **成长规划师:** 独立角色(`teacher`)，可登录规划师端，也可切换回家长视角
|
|
|
-- **积分机制:** 完成任务加分、超时扣分 (`PointsService`)
|
|
|
-- **心愿审批:** 孩子创建 → 家长审批 → 扣减积分
|
|
|
-- **测评订单:** 家长申请 → 选择规划师 → 孩子快照 → 支付 → 规划师录入结果
|
|
|
-- **街道地址:** 四级地址结构（省市区街道），区域回退匹配
|
|
|
-- **多数据源:** cfc 主库 + sfms 源库 (只读迁移)
|
|
|
+## CONVENTIONS
|
|
|
|
|
|
-## COMMANDS
|
|
|
+### 后端
|
|
|
+
|
|
|
+- **分层**: 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` 导航错误
|
|
|
|
|
|
-```bash
|
|
|
-# 后端
|
|
|
-cd cfc-backend && mvn clean compile # 编译验证
|
|
|
-mvn spring-boot:run # 启动 (localhost:8080)
|
|
|
+## UNIQUE STYLES
|
|
|
|
|
|
-# 前端小程序
|
|
|
-cd cfc-frontend && npm run dev:mp-weixin
|
|
|
+- **双角色系统**: 家长 `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`
|
|
|
|
|
|
-# Web管理端
|
|
|
-cd cfc-web && npm run serve # (localhost:8082)
|
|
|
+## ANTI-PATTERNS
|
|
|
|
|
|
-# 迁移 sfms 历史数据
|
|
|
-curl -X POST http://localhost:8080/api/migration/run
|
|
|
-```
|
|
|
+- **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` 注入
|
|
|
|
|
|
-## NOTES
|
|
|
+## VERIFICATION WORKFLOW
|
|
|
|
|
|
-- 数据库: 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/` 为构建产物，不提交
|
|
|
+1. 改后端 → `mvn clean compile` 确认编译通过
|
|
|
+2. `mvn spring-boot:run` 确认应用正常启动（显示 Started）
|
|
|
+3. 测试相关 API 端点
|
|
|
+4. 改前端 → `npm run dev:mp-weixin` 或 `npm run serve`（Web 端）
|
|
|
+5. `lsp_diagnostics` 检查改过的文件
|
|
|
|
|
|
## HIERARCHICAL DOCUMENTATION
|
|
|
|
|
|
```
|
|
|
cfc/
|
|
|
-├── AGENTS.md # 项目总览 (本文件)
|
|
|
+├── AGENTS.md # 本文件
|
|
|
├── cfc-backend/AGENTS.md # 后端详细文档
|
|
|
├── cfc-frontend/AGENTS.md # 小程序前端文档
|
|
|
├── cfc-web/AGENTS.md # Web管理端文档
|
|
|
-├── tests/AGENTS.md # 测试策略文档
|
|
|
-├── docs/superpowers/AGENTS.md # AI开发工具配置
|
|
|
-└── docs/需求分析/ 系统设计/ 系统测试/ # 需求/设计/测试文档
|
|
|
-```
|
|
|
+├── tests/AGENTS.md # 测试策略文档（基础设施不完整）
|
|
|
+└── docs/ # 需求/设计/测试文档
|
|
|
+```
|
