Docs: 分期实施计划（8阶段，含验证与评审节点）

docs/实施计划.md

@@ -0,0 +1,190 @@
+# 爱伴·AI之旅 小程序 分期实施计划
+
+> **依据**：《小程序需求规格说明书 V2.0》《小程序项目详细设计说明书 V1.0》
+> **日期**：2026-09-04 ｜ **执行方式**：按阶段顺序执行，每阶段完成 → 后端 `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: 管理后台按角色过滤菜单与路由守卫`
+
+---
+
+## 阶段评审记录表
+
+| 阶段 | 评审日期 | 验证方式 | 结果 | commit |
+|---|---|---|---|---|
+| 1 | — | 代码评审 | ⬜ | — |
+| 2 | — | mvn compile | ⬜ | — |
+| 3 | — | mvn compile | ⬜ | — |
+| 4 | — | mvn compile | ⬜ | — |
+| 5 | — | mvn compile | ⬜ | — |
+| 6 | — | mvn compile | ⬜ | — |
+| 7 | — | mvn compile | ⬜ | — |
+| 8 | — | npm run build | ⬜ | — |
+
+---
+
+*爱伴 · AI之旅 小程序实施计划 V1.0 · 2026-09-04*