# 爱伴·AI之旅 训练营系统

**CareMate · AI Journey — Training Camp System**

> 一套面向AI技能培训的全端训练营系统，支持L0-L4五级课程体系、学员成长管理、现场投屏互动、团报裂变与完课证书发放。

---

## 目录

1. [项目概述](#项目概述)
2. [项目结构](#项目结构)
3. [技术栈](#技术栈)
4. [系统架构](#系统架构)
5. [快速开始](#快速开始)
6. [功能模块](#功能模块)
7. [数据库设计](#数据库设计)
8. [前端页面](#前端页面)
9. [后端接口](#后端接口)
10. [管理后台路由](#管理后台路由)
11. [开发规范](#开发规范)
12. [编码硬约束](#编码硬约束)
13. [外部依赖与阻塞项](#外部依赖与阻塞项)
14. [Git工作流](#git工作流)
15. [产品愿景](#产品愿景)

---

## 项目概述

「爱伴·AI之旅」（CareMate · AI Journey）是一套完整的AI技能培训训练营系统，覆盖学员从报名、学习、互动到完课的全生命周期管理。

**核心能力：**
- 五级课程体系（L0-L4），支持模块化半天制教学
- 班次管理与插班制，支持灵活排课
- 现场投屏大屏互动，提升课堂参与感
- 三本账分工、互教教学卡、两轮投票等教学互动机制
- 完课证书（CM编号体系）与防伪查验
- 32枚徽章 + 5段位成长体系
- 沙龙引流 → L0高频 → L1模块化 → L2系统 → L3陪跑 → L4讲师的完整漏斗

---

## 项目结构

```
train/                          # 单 git 仓库
├── train-backend/              # Spring Boot 2.7.18 / Java 8 / MyBatis-Plus 3.5.3.1
├── train-frontend/             # uni-app Vue2 小程序（学员端）
├── train-web/                  # Vue2 + Element UI 管理后台
├── docs/                       # 二次文档（SRS/详细设计/需求变更/合规核查）
└── AGENTS.md                   # AI Agent 工作规范
```

---

## 技术栈

| 端 | 技术栈 | 端口 |
|---|---|---|
| train-backend | Spring Boot 2.7.18 / Java 8 / MyBatis-Plus 3.5.3.1 / JWT | 9083 |
| train-frontend | uni-app Vue2 (@dcloudio 2.x) / HBuilderX 打包微信小程序 | — |
| train-web | Vue2 + vue-cli 5 + Element UI | — |
| 数据库 | MySQL 192.168.16.251:3306 / zxyj (cfc 同库) | 3306 |

---

## 系统架构

```
+-------------------+     +-------------------+     +-------------------+
|   train-frontend  |     |     train-web     |     |   train-backend   |
|   (微信小程序)    |     |   (管理后台)      |     |   (Spring Boot)   |
|   uni-app Vue2    |     |   Vue2 + Element  |     |   Java 8 / JWT    |
+--------+----------+     +--------+----------+     +--------+----------+
         |                        |                        |
         |     REST API (POST)    |     REST API (POST)   |
         +------------------------+------------------------+
                                  |
                         +--------v--------+
                         |   MySQL 3306    |
                         |   zxyj 数据库   |
                         | (cfc 同库)      |
                         +-----------------+
```

**架构说明：**
- 三端共享同一数据库，后端与 cfc 系统共用 `zxyj` 库
- 所有接口统一使用 `@PostMapping`，响应格式统一为 `Result<T>`
- JWT 密钥与 cfc 系统对齐，实现 token 互通

---

## 快速开始

### 环境要求

- JDK 8+
- Node.js 14+
- Maven 3.6+
- HBuilderX（小程序打包）
- 微信开发者工具

### 后端启动

```bash
cd train-backend
mvn clean compile          # 编译通过即提交（skipTests=true）
mvn spring-boot:run        # 启动服务，端口 9083
```

**数据库连接：**
- 地址：通过环境变量 `TRAIN_DB_URL` 配置（默认 `192.168.16.251:3306/zxyj`）
- 账号密码：通过 `TRAIN_DB_USERNAME` / `TRAIN_DB_PASSWORD` 环境变量配置
- Schema 由 `DatabaseInitializer` 启动时自动执行 `schema.sql`

### 前端（学员端 H5）

```bash
cd train-frontend
npm install
npm run dev:h5             # 开发模式
npm run build:h5           # 构建生产包
```

### 小程序打包

1. HBuilderX 导入 `train-frontend/` 目录
2. 运行 → 运行到微信开发者工具
3. 产物位于 `unpackage/dist/dev/mp-weixin/`

> ⚠️ 注意：`npm run build:mp-weixin` 的 dist 产物不完整，**必须使用 HBuilderX 打包**

### 管理后台

```bash
cd train-web
npm install
npm run dev                # 开发模式
npm run build              # 构建生产包
```

---

## 功能模块

### 已落地模块

| 阶段 | 提交范围 | 内容 |
|---|---|---|
| Phase1-8 | ce8db0b~6a08ebd | 基础框架（JWT/Schema/CURD/投屏大屏/后台角色路由） |
| Phase9-10 | 47301fb~9ba5889 | 课程现场投屏大屏 |
| Phase11 | 56a64fd | 班级码进班联动 enrollment |
| Phase12 | 372b4ec | 分享海报 sharePath/shareText |
| Phase13 | d811135 | FollowUpTask T+21/T+30 + PreClassReminderTask |
| Phase14 | afb30a1 | 团报发票与案例授权 |
| Phase15a-b | f1bdbe2~248714d | 课程双态（列表/主页）+ 管理端课程审核 |
| 登录统一 | c85d2ba~c9fa4cc | 浮层登录 + 全局守卫 + storage 兜底 |
| 报名重构 | 4605b2c~9f06216 | 报名挂课程 + 后台分配班次 + 按课程分组 |
| 合规修复 | b9d8daa | 移除学员端违规入口（SRS CR-003/022） |
| 课程增强 | 092ffb3~5371fda | 版块维护 + 资料维护 + 学员管理强化（SRS CR-013） |
| PhaseA3 | d5ab795 | vote/finish 两个 L1 券触发点 |
| 完善 | a2046b3 | 订阅消息真实推送 + 课前课后定时任务 + 海报小程序码 |
| Phase4 | 1efa4cc | 沙龙产品化与浠艾福活动打通 |
| Phase5 | 0c81bef | 完课证书编号体系（CM 格式）+ 防伪查验 |
| Phase6 | 5cb6b4d | 徽章与成长体系（32 枚徽章 + 5 段位 + 成长地图） |

### 待实现模块

| 阶段 | 内容 | 状态 |
|---|---|---|
| T1-T4 | 讲师平行资格体系（评教/合规笔试 2 年有效/课时费 200-1200） | 待实现 |

---

## 数据库设计

### 训练营业务表（31 张）

| 序号 | 表名 | 说明 |
|---|---|---|
| 1 | train_course | 课程（L0-L4 五级） |
| 2 | train_course_section | 课程版块（管理端维护） |
| 3 | train_class | 班次 |
| 4 | train_user | 学员用户 |
| 5 | train_group | 小组 |
| 6 | train_group_member | 组内成员 |
| 7 | train_assignment | 三本账分工 |
| 8 | train_submission | 成果上传 |
| 9 | train_teaching_card | 互教教学卡 |
| 10 | train_score | 积分流水 |
| 11 | train_vote | 两轮投票 |
| 12 | train_roadmap | 路演材料 |
| 13 | train_checkin | 装机打卡 |
| 14 | train_prep_check | 数据准备自检 |
| 15 | train_plan | 7 天行动计划 |
| 16 | train_coupon | 卡券 |
| 17 | train_survey | 测评兴趣调研 |
| 18 | train_admin | 管理后台账号 |
| 19 | train_audit_log | 审计日志 |
| 20 | train_enrollment | 报名单 |
| 21 | train_order | 支付订单 |
| 22 | train_invite | 转介绍关系 |
| 23 | train_course_material | 课前资料包 |
| 24 | train_screen_config | 班级投屏配置 |
| 25 | train_group_order | 团报订单 |
| 26 | train_group_order_member | 团报成员 |
| 27 | train_case | 学员案例 |
| 28 | train_salon | 沙龙期次 |
| 29 | train_certificate | 完课证书（CM 编号体系） |
| 30 | train_badge | 徽章目录（32 枚种子） |
| 31 | train_user_badge | 用户徽章 |

### cfc 共享表（只读引用）

- `users` — 用户表
- `activities` — 活动表
- `user_platform_balance` — 用户平台余额
- `tianpan_member_annual_energy` — 天盘会员年度能量

> 数据库与 cfc 系统共用 `zxyj` 库，`com.train.cfc` 包下的实体类映射 cfc 表结构，修改字段必须与 cfc 侧对齐。

---

## 前端页面

### TabBar 页面（4 个）

| 位置 | 页面 | 路径 |
|---|---|---|
| 首页 | index | pages/index/index |
| 任务 | checkin | pages/checkin/index |
| 课程 | course | pages/course/index |
| 我的 | mine | pages/mine/index |

### 子页面（25 个）

| 页面 | 路径 | 说明 |
|---|---|---|
| assignment | pages/assignment/index | 三本账分工 |
| badge | pages/badge/index | 成长地图 |
| case | pages/case/index | 案例授权 |
| class | pages/class/index | 进班 |
| course/detail | pages/course/detail | 课程主页 |
| enroll/list | pages/enroll/list | 课程报名 |
| enroll/form | pages/enroll/form | 报名信息 |
| group/index | pages/group/index | 我的小组 |
| group-order/index | pages/group-order/index | 团报 |
| group-order/create | pages/group-order/create | 发起团报 |
| group-order/detail | pages/group-order/detail | 团报详情 |
| login | pages/login/index | 登录页（已移除，改为首页浮层） |
| material | pages/material/index | 课前资料 |
| pay/index | pages/pay/index | 确认支付 |
| pay/result | pages/pay/result | 支付结果 |
| plan | pages/plan/index | 行动计划 |
| roadmap | pages/roadmap/index | 路演材料 |
| salon/list | pages/salon/list | 沙龙活动 |
| salon/form | pages/salon/form | 沙龙报名 |
| scoreboard | pages/scoreboard/index | 积分榜 |
| share/index | pages/share/index | 我的海报 |
| share/stats | pages/share/stats | 我的邀请 |
| survey | pages/survey/index | 兴趣调研 |
| teaching | pages/teaching/index | 教学卡 |
| upload | pages/upload/index | 成果上传 |
| verify | pages/verify/index | 校友身份校验 |
| vote | pages/vote/index | 路演投票 |

---

## 后端接口

### 学员端接口（19 个）

| 控制器 | 说明 |
|---|---|
| AuthController | 登录认证 |
| WxAuthController | 微信登录 |
| BadgeController | 徽章管理 |
| AssignmentController | 三本账分工 |
| CaseController | 学员案例 |
| CertVerifyController | 证书查验 |
| ClassController | 班次管理 |
| CourseController | 课程管理 |
| EnrollmentController | 报名管理 |
| GroupController | 小组管理 |
| GroupOrderController | 团报管理 |
| InviteController | 转介绍 |
| MaterialController | 课前资料 |
| OrderController | 订单支付 |
| PlanController | 行动计划 |
| SalonController | 沙龙管理 |
| SubmissionController | 成果上传 |
| UploadController | 文件上传 |
| VoteController | 两轮投票 |

### 管理端接口（12 个）

| 控制器 | 说明 |
|---|---|
| AdminAuthController | 管理员登录 |
| AdminBadgeController | 徽章管理 |
| AdminBizController | 业务管理 |
| AdminCaseController | 案例管理 |
| AdminClassController | 班次管理 |
| AdminCourseController | 课程管理 |
| AdminGroupOrderController | 团报管理 |
| AdminMaterialController | 资料管理 |
| AdminReviewController | 审核管理 |
| AdminSalonController | 沙龙管理 |
| AdminScreenController | 投屏配置 |
| AdminStatsController | 统计分析 |

---

## 管理后台路由

| 路由 | 说明 |
|---|---|
| /login | 登录页 |
| /screen | 课程现场投屏 |
| /dashboard | 数据看板 |
| /courses | 课程管理 |
| /classes | 班次管理 |
| /salons | 沙龙管理 |
| /enrollments | 报名管理 |
| /orders | 订单管理 |
| /group-orders | 团报管理 |
| /cases | 案例管理 |
| /groups | 小组管理 |
| /invites | 转介绍管理 |
| /materials | 资料管理 |
| /users | 学员管理 |
| /review/submissions | 成果审核 |
| /review/cards | 教学卡审核 |
| /review/roadmaps | 路演审核 |
| /scoreboard | 积分榜 |
| /manual-score | 手动积分 |
| /stats | 统计分析 |

---

## 开发规范

### 编码硬约束

#### 后端规范

1. **接口统一 @PostMapping**：禁止使用 `@GetMapping`、`@PutMapping`、`@DeleteMapping`
2. **依赖注入用 @Resource**：禁止使用 `@Autowired`，字段名 = 类名首字母小写
3. **响应统一 Result\<T\>**：所有接口返回 `com.train.common.Result` 格式
4. **分层架构**：Controller → Service → Mapper，禁止 Controller 直接操作 Mapper
5. **金额字段用整数**：单位为"分"，禁止使用 `double` / `float`

#### 前端规范（小程序）

1. **Vue2 Options API**：禁止使用 Composition API
2. **禁止可选链**：使用 `&&` 替代 `?.`
3. **禁止 CSS Grid**：使用 flexbox
4. **禁止 :key 运算符**：使用方法调用 `:key="getItemKey(item)"`
5. **禁止 :class 方法调用**：不能在 :class 绑定中调用方法
6. **禁止 new Date(string)**：使用 `parseDate()` 解析时间
7. **禁止 CSS 中文类名**：类名/选择器不能包含中文

#### 数据库规范

- 迁移脚本必须幂等（重复执行不报错）
- 加列/建表/索引用 try-catch 忽略"已存在"错误
- 每次迁移后同步更新 `schema.sql` 的完整定义

#### 时间显示规范

- 后端返回 ISO 8601 格式（`2026-08-15T14:30:00`）
- 展示时间：`yyyy-MM-dd HH:mm:ss`
- 仅日期：`yyyy-MM-dd`
- 禁止使用 `new Date(str).toLocaleString()`

---

## 外部依赖与阻塞项

| 编号 | 依赖项 | 影响范围 | 状态 |
|---|---|---|---|
| CR-004 | 校友白名单/邀请码数据 | 阻塞首课报名 | 待提供 |
| CR-023 | L0 招生海报真实报名二维码 | 阻塞招生 | 待提供 |
| CR-024 | 浠艾福菌群/DNA 脱敏样本 3-5 份 | 阻塞首课 | 待提供 |
| CR-026 | 商标检索 + 域名排查 + 英文名定稿 | 阻塞品牌对外 | 待确认 |

---

## Git 工作流

### 仓库信息

- **远程地址**：`http://git.iwintrue.com/liaoxg/caremate.git`
- **主分支**：`master`

### 提交规范

1. **Commit Message 格式**：中文 Conventional 风格
   ```
   Phase6: 徽章与成长体系
   登录统一: 浮层登录+全局守卫+storage兜底
   ```

2. **提交流程**：
   ```bash
   git status                    # 确认改动范围
   git diff                      # 检查具体变更
   git add <目标文件>            # 只 stage 目标文件
   git diff --cached --stat      # 确认 staged 内容
   git commit -m "PhaseX: 描述"  # 提交
   ```

3. **编译验证**：
   ```bash
   cd train-backend && mvn clean compile  # 编译通过即提交
   ```

### 注意事项

- JWT 密钥已与 cfc 对齐，**不要改回独立密钥**
- 品牌名固定为「爱伴·AI之旅」（CareMate · AI Journey），**勿回退为旧称**
- 本机 MySQL 通常不可达，**编译通过就提交**，不要因连不上库而卡住

### Windows/PowerShell 编码陷阱

PowerShell 把 UTF-8 当 GBK 解码，`git diff` / 终端输出的中文会显示为乱码——**是假乱码**。判断文件编码/JSON 合法性用 Node 或 read/grep 工具，不要信 PowerShell 的显示。

---

## 产品愿景

### V3.3 解决方案要点

1. **沙龙做引流**：4 类主题轮播 + 半日制 20 分钟流程，比做产物划算
2. **模块化教学**：L1/L2 模块化半天制 + L0 高频滚动（每周 ≥ 4 期），降低报名门槛
3. **插班制**：模块化能成立的唯一前提
4. **五段位成长主线**：见习 → 启航 → 专精 → 系统师 → 讲师
5. **徽章体系**：32 枚徽章（12 模块 + 5 课程 + 6 技能 + 5 里程碑 + 4 讲师）
6. **讲师资格阶梯**：T1-T4（评教/合规笔试 2 年有效/课时费 200-1200）

### 完整漏斗

```
沙龙引流 → L0 高频（家立方-AI管家成长营）
         → L1 模块化 → L2 系统 → L3 陪跑 → L4 讲师
```

---

## 文档

详细设计文档、SRS 需求规格、需求变更记录、合规核查结果等，参见 `docs/` 目录。

AI Agent 工作规范参见 `AGENTS.md`。

---

*最后更新：2026-09*