caremate/docs/实施计划.md

爱伴·AI之旅 小程序 分期实施计划

依据：《小程序需求规格说明书 V3.0》《小程序项目详细设计说明书 V2.0》 日期：2026-09-04（V1.0）→ 2026-09-08（V1.1，追加 Phase9-15b）｜ 执行方式：按阶段顺序执行，每阶段完成 → 后端 mvn clean compile 验证 → 阶段评审 → git 提交并推送

---

执行总则

• 后端验收门槛：mvn clean compile（本机 MySQL 不可达，不做运行时验证）。
• 前端验收：train-frontend 以 HBuilderX 打包为准，本环境仅做代码评审；train-web 可 npm run build。
• 每阶段一个逻辑提交单元，commit message 用中文 conventional 风格（PhaseN: 描述）。
• 所有金额字段用整型分；接口统一 @PostMapping；响应统一 Result<T>；DI 用 @Resource。
• 新增表 DDL 写入 train-backend/src/main/resources/schema.sql，建表幂等。

---

阶段 1：基础层 — utils/format.js + 一期课堂管理验收

目标：补齐前端通用工具（时间/金额格式化），核查一期课堂管理三端现状是否完备。

文件：

• 创建：train-frontend/utils/format.js
• 修改：train-frontend/pages/mine/index.vue（若时间展示不合规则改）

任务：

• 创建 utils/format.js：parseDate(str)（ISO → 本地 Date 兼容）、formatDateTime(str)（yyyy-MM-dd HH:mm:ss）、formatDate(str)（yyyy-MM-dd）、fenToYuan(fen)（分→元保留2位）、timeAgo（可选）。
• 全局检索前端时间展示，将 new Date(str).toLocaleString() 替换为 formatDateTime()（无则跳过）。
• 评审：一期课堂管理 15 页面 + 31 接口 + 后台 12 路由是否与 SRS §6 对齐（抽查 index/group/vote/scoreboard 页面）。
• mvn clean compile（后端如无改动则跳过）。
• git 提交：Phase1: 前端新增utils/format.js通用工具（时间/金额格式化）

---

阶段 2：数据层 — 新增 4 张表 DDL + Entity + Mapper

目标：落地 train_enrollment / train_order / train_invite / train_course_material 四表及对应实体、Mapper。

文件：

• 修改：train-backend/src/main/resources/schema.sql
• 创建：entity/TrainEnrollment.java、entity/TrainOrder.java、entity/TrainInvite.java、entity/TrainCourseMaterial.java
• 创建：mapper/TrainEnrollmentMapper.java、mapper/TrainOrderMapper.java、mapper/TrainInviteMapper.java、mapper/TrainCourseMaterialMapper.java

任务：

• schema.sql 追加 4 张表 DDL（§3.3 设计：含幂等键 order_no UNIQUE、uk_code_invitee、索引）。
• 创建 4 个 Entity（Lombok @Data + @TableName，字段与 DDL 对齐，金额 Integer 分）。
• 创建 4 个 Mapper（extends BaseMapper）。
• mvn clean compile 通过。
• git 提交：Phase2: 新增报名/订单/转介/资料包表实体与Mapper

---

阶段 3：报名模块 — 后端接口 + 前端页面 + 后台页面

目标：报名全流程（班次浏览 → 报名单 → 支付占位）。

文件：

• 创建：controller/EnrollmentController.java（/api/enroll/classes|create|mine）
• 创建：dto/EnrollmentVO.java（班次报名视图：剩余名额、价格）
• 修改：train-frontend/utils/api.js（enroll 相关封装）
• 创建：train-frontend/pages/enroll/list.vue、train-frontend/pages/enroll/form.vue
• 修改：train-frontend/pages.json（注册页面）
• 创建：train-web/src/views/Enrollments.vue、train-web/src/api/enroll.js、路由注册

任务：

• EnrollmentController：classes（可报名班次含容量/价格/剩余名额）、create（生成报名单，带 inviteCode 则记转介）、mine。
• 容量校验：count(status in pending/paid) < capacity。
• api.js + enroll/list + enroll/form 页面（uni-app Vue2 规范）。
• train-web Enrollments.vue + 路由。
• mvn clean compile 通过。
• git 提交：Phase3: 报名模块（后端接口+小程序报名页+后台报名管理）

---

阶段 4：支付模块 — PayService + 回调 + 订单页面

目标：订单创建、微信支付（test-mode 模拟）、回调幂等入账。

文件：

• 创建：service/PayService.java、controller/OrderController.java（/api/pay/create|status|cancel|notify）
• 创建：train-frontend/pages/pay/index.vue、train-frontend/pages/pay/result.vue
• 修改：train-frontend/utils/api.js、pages.json
• 创建：train-web/src/views/Orders.vue、train-web/src/api/order.js、路由注册

任务：

• PayService：createOrder（生成 order_no → 模拟 prepay）、handleNotify（test-mode 下由 create 直接置 paid）、校验幂等。
• OrderController：create/status/cancel/notify（notify 公开路径）。
• JwtInterceptor 白名单追加 /api/pay/notify。
• 前端 pay/index（展示金额+模拟支付按钮+轮询 status）、pay/result。
• train-web Orders.vue（订单列表+退款占位）。
• mvn clean compile 通过。
• git 提交：Phase4: 支付模块（test-mode 模拟支付+订单状态机）

---

阶段 5：裂变模块 — 海报/邀请码/激励/漏斗

目标：专属海报、转介绍关系、激励发放、后台漏斗。

文件：

• 创建：controller/InviteController.java（/api/invite/myposter|stats）
• 创建：controller/admin/AdminBizController.java（/api/admin/invite/funnel）
• 创建：train-frontend/pages/share/index.vue、train-frontend/pages/share/stats.vue
• 修改：train-frontend/utils/api.js、pages.json
• 创建：train-web/src/views/Invites.vue、train-web/src/api/invite.js、路由注册

任务：

• InviteController：myposter（返回 invite_code + 海报 URL 占位）、stats（邀请数/成功数/权益数）。
• AdminBizController.funnel：转介绍漏斗（inviter → invited → paid → rewarded）。
• 支付成功回调中联动：被邀请人 paid → 更新 invite.successful → 发放激励卡券（复用 PlanController.grantCoupon）。
• 前端 share/index（海报展示+保存图片）、share/stats。
• train-web Invites.vue 漏斗表格。
• mvn clean compile 通过。
• git 提交：Phase5: 裂变分享模块（海报/邀请码/激励发放/转介漏斗）

---

阶段 6：课前资料包 + 订阅消息通知

目标：课前资料管理（后台配置 + 学员端查看），订阅消息骨架。

文件：

• 创建：controller/MaterialController.java（/api/class/materials）
• 创建：controller/admin/AdminMaterialController.java（/api/admin/material/list|save）
• 创建：train-frontend/pages/material/index.vue
• 修改：train-frontend/utils/api.js、pages.json
• 创建：train-web/src/views/Materials.vue、路由注册

任务：

• MaterialController：学员端按班次（回退通用）拉取资料列表。
• AdminMaterialController：list / save（幂等 upsert）。
• 订阅消息：service/SubscribeMessageService.java 骨架（sendSubscribeMessage 留 test-mode 打日志）。
• 前端 material/index（文件列表 + 预览占位）。
• train-web Materials.vue。
• mvn clean compile 通过。
• git 提交：Phase6: 课前资料包+订阅消息骨架

---

阶段 7：课后证书 + T+ 定时任务 + 卡券核销

目标：完课证书生成、T+ 跟进定时任务、卡券核销。

文件：

• 创建：service/CertService.java、service/FollowUpTask.java（@Scheduled）
• 修改：controller/PlanController.java（追加 /api/plan/cert、/api/coupon/redeem）
• 修改：train-frontend/pages/mine/index.vue（证书/核销入口）

任务：

• PlanController.cert：校验离场验收 6 项 → 生成证书号（复用 coupon code 生成规则或独立 C- 前缀）。
• PlanController.couponRedeem：status unused→used 幂等。
• FollowUpTask：T+1/T+3/T+7 提醒记录（写 audit_log 或发订阅消息），@EnableScheduling。
• mine 页面入口。
• mvn clean compile 通过。
• git 提交：Phase7: 完课证书+卡券核销+T+跟进定时任务

---

阶段 8：后台权限菜单过滤

目标：train-web 菜单按角色过滤（admin 全量 / lecturer 审核评分 / assistant 限负责组）。

文件：

• 修改：train-web/src/views/Layout.vue、train-web/src/router/index.js

任务：

• 定义菜单可见性映射（role → 菜单项集合）。
• Layout.vue 按 store 中 role 过滤菜单渲染。
• 路由守卫补充：assistant 越权访问非审核页 → 重定向。
• npm run build 通过（若本环境可执行）。
• git 提交：Phase8: 管理后台按角色过滤菜单与路由守卫

---

阶段 9：课程现场投屏 — 大屏页

目标：train-web 新增投屏大屏页 /screen，面向教室大屏展示课堂实时数据（积分榜/签到/完课进度/小组进展矩阵/投票结果/课程资料）。

文件：

• 创建：train-web/src/views/Screen.vue、train-web/src/api/screen.js
• 修改：train-web/src/router/index.js

任务：

• Screen.vue：轮询拉取班级实时数据 → 分模块展示（积分榜 / 签到 / 完课进度 / 小组进展矩阵 / 投票结果 / 课程资料）。
• 路由 /screen 注册。
• npm run build 通过。
• git 提交：Phase9: 课程现场投屏大屏页

---

阶段 10：投屏配置化 + 环节计时 + 投票录入

目标：投屏按 train_screen_config 开关显示；课程计时与环节进度；小组进展矩阵；投票结果录入与展示。

文件：

• 创建：controller/admin/AdminScreenController.java（config/get|save|step|start|reset|vote/record）、entity/TrainScreenConfig.java、mapper/TrainScreenConfigMapper.java
• 修改：train-backend/src/main/resources/schema.sql、train-web/src/views/Screen.vue

任务：

• 新增 train_screen_config 表 DDL（8 个模块开关 + agenda 环节 JSON + current_step + banner）。
• AdminScreenController：config/get、config/save、step（切换环节）、start、reset、vote/record。
• Screen.vue 按配置渲染模块；计时器展示当前环节剩余时间。
• mvn clean compile + npm run build 通过。
• git 提交：Phase10: 投屏按课程配置显示, 课程计时与环节进度, 小组进展矩阵, 投票结果录入与展示, 课程资料展示

---

阶段 11：班级码进班联动报名确认

目标：学员进班后联动 train_enrollment 确认状态（FR-ENROLL-03：班级码进班 → enrollment 置 confirmed）。

文件：

• 修改：controller/ClassController.java、service/EnrollmentService.java（或直连 Mapper）

任务：

• 进班接口：按 class_id + invite_code 关联 enrollment → 状态 pending/paid → confirmed。
• mvn clean compile 通过。
• git 提交：Phase11: 班级码进班后联动enrollment确认（FR-ENROLL-03）

---

阶段 12：分享海报字段扩充

目标：train_invite 增加 share_path / share_text；小程序展示分享文案与二维码占位。

文件：

• 修改：train-backend/src/main/resources/schema.sql、entity/TrainInvite.java、controller/InviteController.java
• 修改：train-frontend/pages/share/index.vue

任务：

• schema.sql 补列 share_path / share_text（幂等 ALTER）。
• InviteController.myposter 返回分享文案+跳转路径。
• share/index 展示分享文案 + 二维码占位图。
• mvn clean compile 通过。
• git 提交：Phase12: 分享海报增加sharePath与shareText字段，小程序展示分享文案与二维码占位

---

阶段 13：课后 T+ 定时任务补充 + 课前提醒

目标：FollowUpTask 补 T+21/T+30；新增 PreClassReminderTask 课前 T-7/T-3/T-1 提醒记录。

文件：

• 修改：service/FollowUpTask.java、service/PreClassReminderTask.java（新建）

任务：

• FollowUpTask：补充 T+21 复盘会 / T+30 留存统计记录生成。
• PreClassReminderTask：T-7/T-3/T-1 按班次开课时间写提醒记录。
• mvn clean compile 通过。
• git 提交：Phase13: FollowUpTask补T+21/T+30，新增PreClassReminderTask(T-7/T-3/T-1)

---

阶段 14：团报（多学员一单+开票）& 案例授权

目标：train_group_order / train_group_order_member / train_case 三表 + 团报流程（发起/支付/开票）+ 案例采集→授权→回流。

文件：

• 创建：entity/TrainGroupOrder.java、entity/TrainGroupOrderMember.java、entity/TrainCase.java 及 Mapper；controller/GroupOrderController.java、controller/CaseController.java、controller/admin/AdminGroupOrderController.java、controller/admin/AdminCaseController.java
• 创建：train-frontend/pages/group-order/{index,create,detail}.vue、train-frontend/pages/case/index.vue
• 创建：train-web/src/views/GroupOrders.vue、train-web/src/views/Cases.vue + 路由
• 修改：train-backend/src/main/resources/schema.sql、pages.json、train-web/src/router/index.js

任务：

• 三表 DDL：grouporder（开票字段 invoice*）、group_order_member（名单，支付成功逐人生成 enrollment）、case（脱敏案例+授权状态机）。
• 学员端：发起团报 create / mine / detail / pay；案例 mine / decide。
• 后台：group-order list/members、case list/publish。
• 支付回调：group_order paid → 逐人生成 enrollment → confirmed 进班。
• mvn clean compile 通过。
• git 提交：Phase14: 团报发票与案例授权

---

阶段 15a：小程序可见功能补齐

目标：补齐待支付取消、继续支付、小组设置为发言人等可见交互。

文件：

• 修改：train-frontend/pages/pay/index.vue、train-frontend/pages/group/index.vue、utils/api.js

任务：

• pay 页：待支付订单支持取消 / 继续支付。
• group 页：支持设置为发言人交互。
• git 提交：Phase15a: 补齐小程序可见功能（待支付取消/继续支付/小组设置为发言人）

---

阶段 15b：课程双态（课程中心化底座）

目标：课程双态（未进班可浏览/已进班可上课）+ 课程 tab + 列表进班 + 管理员审核 + 课程主页。

文件：

• 创建：controller/admin/AdminCourseController.java、entity/TrainCourse.java（双态字段）、train-frontend/pages/course/index.vue、train-frontend/pages/course/detail.vue
• 修改：pages.json（tabBar 课程）、train-web/src/router/index.js（/courses）

任务：

• 课程状态 draft/active；课程主页聚合报名/进班/课程内容。
• tabBar 由「路演投票」切换为「课程」。
• 管理员审核进班（enrollment reviewing→confirmed→train_user.class_id 回填）。
• mvn clean compile 通过。
• git 提交：Phase15b: 课程双态 课程tab/列表进班/管理员审核/课程主页

---

阶段 16：课程中心化重构 + 报名挂课程 + 登录态统一（Phase15b 后续）

目标：V3.0 需求（课程中心化、报名=报课程、首页浮层登录+全局守卫）落地到代码。

文件：

• 修改：train-frontend（tabBar/首页/报名表单/课程主页/守卫）、train-backend（EnrollmentController courseId 主导、AdminCourseController）、train-web（/courses）

任务：

• 课程内功能与日常功能入口分离（9de2386）。
• tabBar 课程直进课程主页（9666a38）→ 课程为列表+首页按前中后阶段展示（6c45a3c）。
• 报名挂课程：enrollment 冗余 courseId、后端接口回填课程信息（4605b2c）；报名中心按课程分组展示班次（575de83）；报名只报课程、班次审核分配，新增课程管理/班级维度分组/按签到重分/助教调班（9f06216）。
• 登录态统一：未登录可浏览课程但操作需登录（c85d2ba）；group/mine 未入组静默（4fc2fd3）；守卫 storage 兜底（c9fa4cc）。
• mvn clean compile 通过。
• git 提交（按上述 commit 粒度逐个提交）。

---

阶段评审记录表

阶段	评审日期	验证方式	结果	commit
1	2026-09-04	mvn compile	✅	b20c487
2	2026-09-04	mvn compile	✅	8b82ea9
3	2026-09-04	mvn compile	✅	1e073a0
4	2026-09-04	mvn compile	✅	c7f8b50
5	2026-09-04	mvn compile	✅	08fe3c0
6	2026-09-05	mvn compile	✅	0065895
7	2026-09-05	mvn compile	✅	2fdc435
8	2026-09-05	npm run build	✅	6a08ebd
9	2026-09-05	mvn compile + build	✅	47301fb
10	2026-09-05	mvn compile + build	✅	9ba5889
11	2026-09-05	mvn compile	✅	56a64fd
12	2026-09-06	mvn compile	✅	372b4ec
13	2026-09-06	mvn compile	✅	d811135
14	2026-09-06	mvn compile	✅	afb30a1
15a	2026-09-06	前端构建评审	✅	f1bdbe2
15b	2026-09-06	mvn compile + 前端评审	✅	248714d
16	2026-09-07~08	mvn compile + 前端评审	✅	9de2386 9666a38 6c45a3c 4605b2c 575de83 9f06216 c85d2ba 4fc2fd3 c9fa4cc

---

爱伴 · AI之旅 小程序实施计划 V1.1 · 2026-09-08