# 「叶雷讲数学」小程序 重构开发文档

| 项 | 内容 |
|---|---|
| 版本 | v1.0 |
| 日期 | 2026-09-29 |
| 状态 | 设计定稿，待开发 |
| 范围 | 小程序端 / 服务端 / 管理后台 / 数据端 |

---

## 1. 项目概述

### 1.1 背景

现有系统为「微信小程序 + 原生 PHP + MySQL 5.7 + 静态文件站点」的实现，可正常运行，但存在结构性问题：无鉴权体系、SQL 全字符串拼接、数据库无主键与约束、无正式管理后台、无支付能力、存在大量死代码与废弃表、服务端无版本控制。

本次重构的目标是：**在保持小程序用户侧外观与使用体验不变的前提下，把技术实现整体替换为规范化工程，并补齐支付与管理后台能力。**

### 1.2 目标

1. 用户侧无感升级：页面表现一致、已有数据零丢失、已购课程权限延续。
2. 技术实现规范化：分层、类型安全、边界校验、迁移管理、统一契约。
3. 补齐支付能力，使课程销售可自助完成。
4. 补齐管理后台，使运营脱离手写 SQL。

### 1.3 明确不做

- 不做微服务、K8s、服务网格。
- 不上 Redis / 消息队列（发货用「数据库状态机 + 定时查单」足够）。
- 不上 GraphQL。
- 不引入 Turborepo / Nx。
- 不重写小程序为 Taro / uni-app。
- 不补短信能力（触达改用微信订阅消息）。
- 不做 DDD 分层、CQRS、事件溯源。

---

## 2. 决策记录（ADR）

| 编号 | 决策 | 理由 | 影响 |
|---|---|---|---|
| ADR-001 | 放弃口令码，权益由订单驱动 | 支付上线后口令码仅剩线下分发用途，维护成本高于价值 | 删除 `课程口令码`、`课程口令码读取信息`；老用户走 legacy 权益迁移 |
| ADR-002 | 数据端保留 MySQL 5.7，不升级 | 用户明确要求 | Prisma `provider = mysql`；见 4.1 约束清单 |
| ADR-003 | 服务端与管理后台使用独立域名 | 用户要求 | Nginx 分站点；后端仍为同一 Node 进程 |
| ADR-004 | 小程序前端不重写，只重写 JS 层 | 保证「外观不变」 | 复用全部 `.wxml` / `.wxss` / `static/` |
| ADR-005 | `VideoDetailsPage` 保持现有实现逻辑不变 | 该页为对外宣传页 | 内容继续硬编码在前端，不迁入数据库 |
| ADR-006 | AppID 沿用 `wx3fbaf897825bf04f` | 换 AppID 等于重发小程序，用户与虚拟支付配置全部丢失 | 数据迁移无需做 openid 映射 |
| ADR-007 | 技术栈换为 Node + NestJS + Prisma | 用户选定 Node；管理后台与 API 可共享类型与校验 | 需自行维护 Node 进程守护与部署 |

---

## 3. 总体架构

### 3.1 架构图

```text
微信小程序
   |  https  api.yeomai.site/v1/*
   |  Authorization: Bearer <JWT>
   v
+----------------------------------------------------+
|  NestJS 单进程  :3000                              |
|   + /v1/*            小程序端接口                  |
|   + /admin/v1/*      管理后台接口（独立 JWT）      |
|   + /pay/notify      虚拟支付发货推送（XML 应答）  |
|   + @nestjs/schedule 每 5 分钟兜底查单             |
+----------------------------------------------------+
        |                 |                  |
        v                 v                  v
   MySQL 5.7        对象存储 / CDN      微信虚拟支付
   （宝塔）        static.yeomai.site   下单 / 推送 / 查单

管理后台（Next.js :3001）
   admin.yeomai.site        -> 后台前端
   admin-api.yeomai.site    -> 反代到同一 Node 进程 /admin/v1/*
```

### 3.2 域名规划

| 域名 | Nginx 指向 | 用途 |
|---|---|---|
| `api.yeomai.site` | `127.0.0.1:3000`（`/v1/*`） | 小程序接口 |
| `admin-api.yeomai.site` | `127.0.0.1:3000`（`/admin/v1/*`） | 管理后台接口 |
| `admin.yeomai.site` | `127.0.0.1:3001` | 管理后台前端 |
| `static.yeomai.site` | 对象存储 / CDN | 图片与 HLS 视频 |

> `api.yeomai.site` 沿用现有域名，小程序「request 合法域名」白名单无需改动。

### 3.3 小程序侧 MP 配置变更清单

| 项 | 是否需要改 | 说明 |
|---|---|---|
| `request` 合法域名 | 沿用则不用改 | 仅 `wx.request` / `uploadFile` / `downloadFile` / `connectSocket` 受白名单约束 |
| `<image>` / `<video>` 资源域名 | **不需要** | 组件引用的图片与音视频资源不受合法域名限制，故视频迁 CDN 无需改 MP 配置 |
| 虚拟支付发货推送 URL | 需要 | 填在【虚拟支付 → 基本配置】，非域名白名单 |
| 小程序简称 | iOS 支付需要 | 虚拟支付 → 基础配置 |
| 苹果 IAP 支付开关 | iOS 支付需要 | 虚拟支付 → 基础配置 |

### 3.4 宝塔部署拓扑

**软件依赖**：MySQL 5.7（沿用）、Node 版本管理器（Node 22 LTS）、Nginx。

**站点**：`api` / `admin-api` / `admin` 三个站点，各配 Let's Encrypt 证书。

**进程**：api 与 admin 分别用宝塔「Node 项目」+ PM2 守护。

**定时任务**：兜底查单使用进程内 `@nestjs/schedule`，不额外依赖系统 cron。数据库备份使用宝塔计划任务 `mysqldump`。

> ⚠️ **阶段 0 必须先验证**：宝塔的 Node 项目管理器对 pnpm workspace 支持有限。备选方案为「本地或 CI 构建后仅部署产物」，或将 `apps/api` 配置为独立启动目录。此项若不通，会阻塞整个部署流程。

---

## 4. 数据端设计

### 4.1 MySQL 5.7 约束清单

保留 5.7 意味着以下限制必须写进开发规范：

| 约束 | 影响 | 应对 |
|---|---|---|
| 无 `CHECK` 约束（语法可解析但不生效） | 不能用数据库层做值域校验 | 校验下沉到应用层（zod）；关键枚举值靠代码约束 |
| 无 `utf8mb4_0900_ai_ci`（8.0 才有） | 排序规则需换 | 统一使用 `utf8mb4_general_ci` |
| 无窗口函数 | 统计类 SQL 受限 | 统计数据在应用层聚合 |
| 单列索引键长限制 | 若行格式为 COMPACT/REDUNDANT，键上限 767 字节，utf8mb4 下 `VARCHAR(255)` 建唯一索引会失败 | 所有需建索引的字符字段长度控制在 `VARCHAR(64)` 以内 |
| 已 EOL（2023-10） | 无安全补丁 | 接受风险；必须保证每日备份可用 |

> ⚠️ **Prisma 与 5.7 的实际坑**：`prisma migrate dev` 需要创建 shadow database，要求数据库账号具备 `CREATE DATABASE` 权限。宝塔创建的 MySQL 用户默认没有该权限。
>
> 解决方案（二选一）：
> 1. 为迁移专用账号授予 `CREATE` / `DROP` 权限（推荐，本机开发用）。
> 2. 在本地生成迁移 SQL（`prisma migrate diff`），生产端仅执行 `prisma migrate deploy`。

### 4.2 表清单与映射：20 张 → 16 张

| 旧表 | 新表 | 处理 |
|---|---|---|
| `用户信息` (284) | `users` | 迁移，结构重写 |
| `用户已购课程` (48) | `entitlements` | 迁移为 `source = legacy` |
| `课程口令码读取信息` (10) | `courses` | 升级为正式课程表 |
| `视频课程数据` (841) | `lessons` | 迁移 |
| `免费视频课程数据` | `free_lessons` | 迁移 |
| `首页课程列表` (5) | `home_courses` | 迁移 |
| `首页免费课程列表` (3) | `home_free_courses` | 迁移 |
| `首页横幅图片` (3) | `banners` | 迁移 |
| `网页列表` (2) | `articles` | 迁移 |
| `课程页面Tips` (2) | `course_tips` | 迁移 |
| `cloudconfig` (13) | `settings` | 迁移，数字 ID 改字符串 key |
| `课程口令码` (5) | `legacy_redeem_codes` | **保留原样**，见 9.4 |
| `网页数据` | — | 废弃 |
| `课程页面Tips2` | — | 废弃 |
| `首页课程列表2` | — | 废弃 |
| `首页免费课程列表2` | — | 废弃 |
| `首页横幅图片2` | — | 废弃 |
| `网页列表2` | — | 废弃 |
| `免费视频课程数据2` | — | 废弃 |
| `验证码发送` | — | 废弃（不做短信） |
| — | `orders` | 新增 |
| — | `payment_notify_log` | 新增 |
| — | `products` | 新增 |
| — | `admin_users` | 新增 |

### 4.3 通用规范

- 表名、字段名一律英文 `snake_case`。
- 主键统一 `id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY`。
- 时间统一 `DATETIME`，**存 UTC**，展示层转 `Asia/Shanghai`。
- 金额统一 `INT UNSIGNED`，单位**分**，全程不换算。
- 状态字段用 `TINYINT` + 代码内枚举，不使用中文字符串。
- 字符集 `utf8mb4`，排序规则 `utf8mb4_general_ci`。
- 外键约束一律不建（由应用层保证），避免迁移与批量操作受限。

### 4.4 关键表结构

#### users

| 字段 | 类型 | 约束 | 说明 |
|---|---|---|---|
| id | BIGINT UNSIGNED | PK | |
| openid | VARCHAR(64) | NOT NULL UNIQUE | 微信 openid，最长 28 字符 |
| nickname | VARCHAR(32) | NULL | 用户名，前端限制 8 字符 |
| headicon_id | INT UNSIGNED | NOT NULL DEFAULT 0 | 头像序号 |
| wx_session_key | VARCHAR(255) | NULL | 加密存储，**虚拟支付签名必需** |
| session_key_updated_at | DATETIME | NULL | 用于判断是否需重新登录刷新 |
| status | TINYINT | NOT NULL DEFAULT 1 | 1 正常 / 0 封禁 |
| registered_at | DATETIME | NOT NULL | |
| last_login_at | DATETIME | NULL | |
| created_at / updated_at | DATETIME | NOT NULL | |

> `wx_session_key` 必须加密存储（AES-256-GCM，密钥来自环境变量）。明文存储等同于泄露用户态签名能力。

#### courses

| 字段 | 类型 | 约束 | 说明 |
|---|---|---|---|
| id | BIGINT UNSIGNED | PK | |
| code | VARCHAR(64) | NOT NULL UNIQUE | **保留原 64 位 sha256 串原值** |
| title | VARCHAR(128) | NOT NULL | |
| intro | VARCHAR(255) | NULL | |
| cover_image | VARCHAR(255) | NULL | 封面文件名 |
| price_fen | INT UNSIGNED | NOT NULL DEFAULT 0 | 展示价，实际以 `products` 为准 |
| status | TINYINT | NOT NULL DEFAULT 1 | 0 下架 / 1 上架 |
| sort_order | INT | NOT NULL DEFAULT 0 | |
| created_at / updated_at | DATETIME | NOT NULL | |

> 🔴 **`code` 字段绝对不能改写。** 它同时是视频目录名（`Course/{code}/{chapter}/{play}/playlist.m3u8`）与封面名（`Course/{code}.png`），一旦改动，全部付费媒体资源立即失效。

#### lessons（付费课时）

| 字段 | 类型 | 约束 | 说明 |
|---|---|---|---|
| id | BIGINT UNSIGNED | PK | |
| course_id | BIGINT UNSIGNED | NOT NULL | → courses.id |
| play_id | VARCHAR(64) | NOT NULL | **原值保留**，参与视频路径 |
| chapter_id | VARCHAR(64) | NOT NULL | **原值保留**，参与视频路径 |
| chapter_title | VARCHAR(255) | NULL | |
| lesson_title | VARCHAR(255) | NULL | |
| duration | VARCHAR(16) | NULL | 原为字符串，保留 |
| published_at | DATETIME | NULL | |
| cover_image | VARCHAR(255) | NULL | |
| sort_order | INT | NOT NULL DEFAULT 0 | |

索引：`UNIQUE(course_id, chapter_id, play_id)`、`INDEX(course_id, sort_order)`。

#### entitlements（权益 — 播放鉴权唯一入口）

| 字段 | 类型 | 约束 | 说明 |
|---|---|---|---|
| id | BIGINT UNSIGNED | PK | |
| user_id | BIGINT UNSIGNED | NOT NULL | → users.id |
| course_id | BIGINT UNSIGNED | NOT NULL | → courses.id |
| source | TINYINT | NOT NULL | 1 订单 / 2 老数据 / 3 后台发放 / 4 旧口令码 |
| ref_id | BIGINT UNSIGNED | NULL | 订单 id 或操作人 id |
| granted_at | DATETIME | NOT NULL | |
| expire_at | DATETIME | NULL | NULL 表示永久 |
| note | VARCHAR(255) | NULL | |

索引：`UNIQUE(user_id, course_id)`、`INDEX(user_id)`。

> 抽掉口令码后，权益来源仍有三种（订单 / 老数据 / 后台发放）。**播放鉴权只查这一张表**，避免三条分支三处 bug。

#### orders

| 字段 | 类型 | 约束 | 说明 |
|---|---|---|---|
| id | BIGINT UNSIGNED | PK | |
| out_trade_no | VARCHAR(32) | NOT NULL UNIQUE | 本地业务单号 |
| user_id | BIGINT UNSIGNED | NOT NULL | |
| course_id | BIGINT UNSIGNED | NOT NULL | |
| product_id | VARCHAR(64) | NOT NULL | 微信虚拟支付道具 ID |
| quantity | INT UNSIGNED | NOT NULL DEFAULT 1 | |
| amount_fen | INT UNSIGNED | NOT NULL | |
| status | TINYINT | NOT NULL | 0 待支付 / 1 已支付 / 2 已发货 / 3 已退款 / 4 已关闭 |
| env | TINYINT | NOT NULL DEFAULT 0 | 固定 0 |
| wx_order_id | VARCHAR(64) | NULL UNIQUE | 平台单号，**幂等依据** |
| attach | VARCHAR(255) | NULL | 透传字段 |
| created_at / paid_at / delivered_at / refunded_at | DATETIME | NULL | |

索引：`INDEX(user_id, created_at)`、`INDEX(status, created_at)`。

#### payment_notify_log

| 字段 | 类型 | 说明 |
|---|---|---|
| id | BIGINT UNSIGNED PK | |
| wx_order_id | VARCHAR(64) | |
| out_trade_no | VARCHAR(32) | |
| event | VARCHAR(64) | 如 `xpay_goods_deliver_notify` |
| raw_body | MEDIUMTEXT | 原始 XML，用于重放与排查 |
| processed | TINYINT | |
| err_msg | VARCHAR(255) | |
| created_at | DATETIME | |

索引：`INDEX(wx_order_id)`。

#### products

| 字段 | 类型 | 说明 |
|---|---|---|
| id | BIGINT UNSIGNED PK | |
| course_id | BIGINT UNSIGNED | → courses.id |
| wx_product_id | VARCHAR(64) UNIQUE | MP 后台道具 ID |
| name | VARCHAR(128) | |
| price_fen | INT UNSIGNED | 必须与 MP 后台道具价格一致 |
| status | TINYINT | |

#### admin_users

| 字段 | 类型 | 说明 |
|---|---|---|
| id | BIGINT UNSIGNED PK | |
| username | VARCHAR(64) UNIQUE | |
| password_hash | VARCHAR(255) | argon2id |
| display_name | VARCHAR(64) | |
| role | TINYINT | 1 超管 / 2 运营 |
| totp_secret | VARCHAR(64) NULL | 二次验证 |
| status | TINYINT | |
| last_login_at | DATETIME | |

#### legacy_redeem_codes（旧口令码留存）

原样保留 5 条记录，用于凭证备查与人工核销，不参与任何自动流程。

| 字段 | 类型 | 说明 |
|---|---|---|
| id | BIGINT UNSIGNED PK | |
| code | VARCHAR(64) UNIQUE | 原口令码 |
| course_id | BIGINT UNSIGNED | → courses.id |
| remaining_uses | INT | 原剩余有效次数 |
| expires_at | DATETIME NULL | 原口令结束日期 |
| note | VARCHAR(255) | 备注 |

#### settings

数字 ID 迁移为字符串 key，附映射关系（见 9.3）。

| 字段 | 类型 | 说明 |
|---|---|---|
| id | BIGINT UNSIGNED PK | |
| key | VARCHAR(64) UNIQUE | 如 `site.version` |
| value | VARCHAR(255) | |
| remark | VARCHAR(255) | 原「注释」字段 |

#### 内容类表（结构相近）

`home_courses`、`home_free_courses`、`banners`、`articles`、`course_tips`、`free_lessons` 均为「内容 + 排序 + 状态」结构，统一包含：

```text
id, <业务字段...>, cover_image/filename, sort_order, status, created_at, updated_at
```

其中 `articles` 额外包含 `legacy_page_id VARCHAR(32)`。

> 🔴 **封面与图片文件名迁移时一律原样保留。** 原因：小程序里的图片地址是拼出来的——
>
> - 首页新课：`Images/NewCourse/{课程名称}.png`
> - 首页试听：`Images/FreeCourse/{课程名称}.png`
> - 轮播：`Images/Banner/{图片名}`
> - 知识速通：`WebPages/{网页id}.png`
> - 付费课封面：`Course/{course.code}.png`
>
> 任何字段被「规范化改写」，对应图片立刻 404。

### 4.5 首页内容块与课程的对应关系

注意首页「新课上线」与付费课程**不是一一对应**：

| 首页新课条目（5 条） | 对应付费课程 |
|---|---|
| 几何模型封面 | 几何模型 |
| 中考数学压轴大招封面 | 中考数学压轴大招 |
| 七年级同步课程封面2 | 7年级同步课程 |
| 八年级同步课程 | 8年级同步课程 |
| 九年级同步课程 | 9年级同步课程 |

以下 5 门课程**不在首页展示**，仅在「知识」页与购买入口出现：7/8/9 年级数学同步视频课（北师大）、梁老师中考数学一轮/二轮满分冲刺。

`home_courses` 需要新增 `course_id` 可空字段，建立「首页长图页 → 可购买课程」的关联，用于挂载购买按钮。

---

## 5. 服务端设计

### 5.1 技术栈

| 项 | 选型 |
|---|---|
| 运行时 | Node 22 LTS |
| 语言 | TypeScript（strict，禁止 `any`） |
| 框架 | NestJS |
| ORM / 迁移 | Prisma（`provider = mysql`） |
| 校验 | zod（与管理后台共享 `packages/shared`） |
| 鉴权 | `@nestjs/jwt` + argon2 |
| 日志 | pino |
| 定时任务 | `@nestjs/schedule` |
| 文档 | Swagger 自动生成 |
| 测试 | vitest + supertest |
| 仓库 | pnpm workspaces 单仓 |

### 5.2 目录结构

```text
apps/api/src/
├─ modules/
│  ├─ auth/           code2Session、sessionKey 托管、JWT 签发
│  ├─ users/
│  ├─ courses/        课程与课时
│  ├─ entitlements/   权益（播放鉴权唯一入口）
│  ├─ home/           banner / 新课 / 试听 / 文章 / 配置
│  ├─ orders/         下单、订单查询
│  ├─ payments/       签名、发货推送、兜底查单
│  ├─ media/          签名播放地址签发
│  └─ admin/          管理后台接口（独立守卫）
├─ legacy/            /API/*.php 兼容层（过渡用，阶段 8 删除）
├─ common/            统一响应拦截器 / 异常过滤器 / 守卫 / 装饰器
└─ main.ts
```

### 5.3 接口清单

#### 小程序端 `/v1/*`

| 方法 | 路径 | 鉴权 | 说明 |
|---|---|---|---|
| POST | `/v1/auth/wx-login` | 否 | code 换 token，同时托管 sessionKey |
| POST | `/v1/auth/refresh` | 否 | 刷新 token |
| POST | `/v1/auth/logout` | 是 | 注销 |
| GET | `/v1/config` | 否 | 站点配置 |
| GET | `/v1/banners` | 否 | 首页轮播 |
| GET | `/v1/home/courses` | 否 | 首页新课列表 |
| GET | `/v1/home/free-courses` | 否 | 首页免费试听入口 |
| GET | `/v1/articles` | 否 | 知识速通列表（分页） |
| GET | `/v1/articles/:id` | 否 | 文章详情 |
| GET | `/v1/tips` | 否 | 课程页文案 |
| GET | `/v1/courses` | 可选 | 课程列表（含未购买，用于购买入口） |
| GET | `/v1/courses/:code` | 可选 | 课程详情 |
| GET | `/v1/courses/:code/lessons` | 是 | 课时列表，**校验权益** |
| GET | `/v1/courses/:code/play` | 是 | 签发播放地址，**校验权益 + URL 签名** |
| GET | `/v1/free-lessons` | 否 | 免费试听课时 |
| GET | `/v1/me` | 是 | 个人资料 |
| PATCH | `/v1/me` | 是 | 修改昵称 / 头像 |
| GET | `/v1/me/entitlements` | 是 | 我的课程 |
| POST | `/v1/orders` | 是 | 下单，返回 payData |
| GET | `/v1/orders/:outTradeNo` | 是 | 查询订单状态 |
| POST | `/v1/payments/notify` | 签名 | 发货推送（微信调用，返回 XML） |

#### 管理后台 `/admin/v1/*`

| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/admin/v1/auth/login` | 管理员登录 |
| GET | `/admin/v1/stats` | 数据看板 |
| GET/PATCH | `/admin/v1/users`、`/users/:id` | 用户管理 |
| CRUD | `/admin/v1/courses` | 课程管理 |
| CRUD | `/admin/v1/lessons` | 课时管理 |
| CRUD | `/admin/v1/home-courses` | 首页新课长图 |
| CRUD | `/admin/v1/home-free-courses` | 首页试听 |
| CRUD | `/admin/v1/banners` | 轮播图 |
| CRUD | `/admin/v1/articles` | 文章 |
| GET/PUT | `/admin/v1/settings` | 系统配置 |
| GET | `/admin/v1/orders` | 订单列表 |
| POST | `/admin/v1/orders/:id/refund` | 发起退款（Android） |
| GET/POST/DELETE | `/admin/v1/entitlements` | 权益发放 / 回收 |
| POST | `/admin/v1/legacy-codes/redeem` | 旧口令码人工核销 |

### 5.4 统一契约

**响应体**

```json
{ "code": 0, "message": "ok", "data": {}, "requestId": "..." }
```

**错误码分段**

| 区间 | 含义 |
|---|---|
| 0 | 成功 |
| 1000–1999 | 通用（参数错误、资源不存在） |
| 2000–2999 | 鉴权（未登录、token 过期、无权限） |
| 3000–3999 | 业务（无权益、课程下架） |
| 4000–4999 | 支付（订单状态非法、签名失败） |
| 5000+ | 服务端异常 |

HTTP 状态码独立正确（401 / 403 / 404 / 422 / 500）。分页统一 `?page=&pageSize=`，返回 `{ items, total, page, pageSize }`。

### 5.5 鉴权设计

```text
小程序
  wx.login -> code
    -> POST /v1/auth/wx-login
    -> 服务端 code2Session 换 openid + sessionKey
    -> upsert users，加密存储 sessionKey
    -> 返回 accessToken(2h) + refreshToken(30d)

管理员
  admin_users + argon2 校验 + 独立 JWT（不同 audience）
  小程序 token 访问 /admin/v1/* 一律 403
```

要点：

1. openid **不再作为身份凭证传递**，改为 JWT。解决现网「拿到别人 openid 即可查其已购课程」的问题。
2. sessionKey 必须服务端托管，因为虚拟支付 `signature` 依赖它。
3. accessToken 与 refreshToken 使用不同密钥或不同 audience。

### 5.6 兼容层策略

在 `/API/*.php` 原路径上原样实现现有接口，**返回体与现网逐字节一致**。

**目的**：让小程序零改动即可切到新后端。风险从「全站重写」降为「换后端，先验证再切流量」。

**性质**：临时产物。随阶段 8 的前端改造一并删除。

#### 接口对照表

| 现有前端函数 | 现路径 | 新接口 | 备注 |
|---|---|---|---|
| ApiGetConfig | `/API/ApiGetConfig.php` | `GET /v1/config` | |
| ApiGetUserOpenID | `/API/ApiGetUserOpenID_Yelay.php` | 内部化，不对外 | |
| ApiGetUserDataFromDB | `/API/ApiGetOrInsertUserDataFromDB.php` | `GET /v1/me` | |
| ApiGetUserCourseDataFromDB | `/API/ApiGetUserCourseDataFromDB.php` | `GET /v1/me/entitlements` | |
| ApiGetBannerImg | `/API/ApiGetBannerImg.php` | `GET /v1/banners` | |
| ApiGetIndexCourseList | `/API/ApiGetIndexCourseList.php` | `GET /v1/home/courses` | |
| ApiGetIndexFreeCourseList | `/API/ApiGetIndexFreeCourseList.php` | `GET /v1/home/free-courses` | |
| ApiGetWebPagesFromDB | `/API/ApiGetWebPagesFromDB.php` | `GET /v1/articles` | 顺带修掉 varchar 排序 bug |
| ApiGetWebPageContent | 已弃用 | 不实现 | |
| ApiGetFreeCourseData | `/API/ApiGetFreeCourseData.php` | `GET /v1/free-lessons` | |
| ApiGetCourseData | `/API/ApiGetCourseData.php` | `GET /v1/courses/:code/lessons` | 鉴权改为查 entitlements |
| ApiLogin | `/API/ApiLogin.php` | `POST /v1/auth/wx-login` | 语义变化 |
| ApiLogout | `/API/ApiLogout.php` | `POST /v1/auth/logout` | |
| ApiChangeInfo | `/API/ApiChangeInfo.php` | `PATCH /v1/me` | |
| ApiGetTips | `/API/ApiGetTips.php` | `GET /v1/tips` | |
| ApiPasswordCodeValidate | `/API/ApiPasswordCodeValidate.php` | 废弃 | |
| ApiGetPasswordCode | `/API/ApiGetPasswordCode.php` | 废弃 | |
| ApiAddPasswordCode | `/API/ApiAddPasswordCode.php` | 废弃 | |
| ApiAddPasswordCodeBefor | `/API/ApiAddPasswordCodeBefor.php` | 废弃 | |
| ApiChangePasswordCode | `/API/ApiChangePasswordCode.php` | 废弃 | |
| ApiDeletePasswordCode | `/API/ApiDeletePasswordCode.php` | 废弃 | |

#### 服务端直接删除的文件

`SMS/`（整套）、`mail.php`、`ApiGetUUID.php`、`ApiGetShortUUID.php`、`ApiGetContact.php`、`ApiChangeUserInfo.php`、`ApiChangeUserInfo_yelay.php`、`ApiGetUserOpenID.php`（旧 AppID）、`已弃用ApiGetWebPageContent.php`、`ApiGetCourseID.php`。

---

## 6. 支付设计

### 6.1 流程

```text
用户点「购买」
  |
  +- (1) POST /v1/orders { courseCode }
  |      服务端生成唯一 out_trade_no，订单落库 status=created
  |      返回 signData + paySig + signature
  |
  +- (2) 前端 wx.requestVirtualPayment({ mode: 'short_series_goods', ... })
  |
  +- (3) 支付成功后，微信推送发货通知
  |      POST /v1/payments/notify（XML）
  |      按 wx_order_id 幂等 -> 写 entitlements -> order.status=delivered
  |      返回 <xml><ErrCode>0</ErrCode>...</xml>
  |
  +- (4) 推送丢失时，@nestjs/schedule 每 5 分钟 query_order 补发
```

### 6.2 必须遵守的纪律

1. **发货只认「发货推送」和「查单」**。前端支付 `success` 回调不作为发货依据——用户中途退出会丢失回调。
2. **幂等键使用平台单号 `wx_order_id`**，不是自己的 `out_trade_no`。
3. 签名 `post_body` 必须与实际发出的字符串**逐字节一致**：不格式化、不改键顺序。
4. 状态机严格单向：`created → paid → delivered → refunded`，禁止跳状态。
5. 发货推送与应答消息体均为 **XML**。
6. 查单接口参数名是 `order_id`（传 `out_trade_no`），**不是** `out_trade_no`。

### 6.3 签名算法

```text
# paySig（服务端计算，密钥为 AppKey）
msg     = uri + '&' + post_body
paySig  = HMAC_SHA256(appkey, msg)

# signature（用户态签名，密钥为该用户的 sessionKey）
signature = HMAC_SHA256(session_key, post_body)
```

- C 端下单：`uri` 固定为 `requestVirtualPayment`
- B 端接口：`uri` 为实际路径，如 `/xpay/query_order`

### 6.4 商品配置

10 门课程 = 10 个道具，需先在 MP 后台【道具管理】创建并发布，拿到道具 ID 与价格，写入 `products` 表。`signData.goodsPrice` 必须与后台价格一致（单位：分）。

### 6.5 费率与限制

| 项 | 值 |
|---|---|
| 个人主体月限额 | 10 万元（全终端合计） |
| Android 结算 | T+3，费率 1% |
| iOS 结算 | 约 45–60 天，Apple 佣金 12% |
| iOS 最低微信版本 | 8.0.68 |
| iOS 退款 | 用户向 App Store 申请，开发者无法主动退 |
| Android 退款 | 开发者可主动发起 |

> 定价必须把 iOS 的 12% 佣金计入成本。

---

## 7. 管理后台设计

### 7.1 概况

| 项 | 内容 |
|---|---|
| 域名 | `admin.yeomai.site` |
| 接口 | `admin-api.yeomai.site` → 同一 Node 进程 `/admin/v1/*` |
| 技术 | Next.js + TypeScript + shadcn/ui + TanStack Table |
| 登录 | 独立账号密码（argon2），与微信用户体系完全隔离；可选 TOTP |

### 7.2 功能清单

1. **数据看板**：用户数、订单数、成交额、课程销量。
2. **用户管理**：查询、改昵称头像、封禁。
3. **课程管理**：课程 CRUD、上下架、排序、封面。
4. **课时管理**：按课程列出课时，编辑标题/章节/排序。
5. **权益管理**：手动发放、回收、按用户查权益（**替代原发码功能**）。
6. **订单管理**：列表、详情、状态、发起退款（Android）。
7. **旧口令码核销**：输入口令码 + 选择用户 → 扣减次数 → 发放权益。
8. **内容管理**：Banner、首页新课长图、首页试听入口、文章、课程页文案。
9. **系统配置**：`settings` 表全部键值。

---

## 8. 小程序端设计

### 8.1 保持不变的项

- 全部 `.wxml` / `.wxss` / `static/` 图片 / 图标 / 布局 / 交互手势。
- tabBar 三项：首页、知识、我的。
- 页面跳转关系与参数。
- 所有对外图片与视频资源地址。

> 「外观不变」的实现方式：**样式与布局文件直接复用，只重写 JS 层**。这样外观天然一致，无需做像素级走查。

### 8.2 页面清单：11 → 10

| 页面 | 路径 | 处理 |
|---|---|---|
| 首页 | `pages/index/index` | 保留 |
| 知识 | `pages/kecheng/kecheng` | 保留 + 扩展购买入口 |
| 我的 | `pages/wode/wode` | 保留 |
| 登录/退出 | `pages/LoginOrOutDetails/LoginOrOutDetails` | 保留，逻辑简化 |
| 文章详情 | `pages/WebPageDetails/WebPageDetails` | 保留 |
| 付费课播放 | `pages/VideoDetails/VideoDetails` | 保留 + 购买按钮 |
| 新课长图 | `pages/IndexNewCourseDetails/IndexNewCourseDetails` | 保留 + 购买按钮 |
| 免费试听播放 | `pages/IndexFreeCourseDetails/IndexFreeCourseDetails` | 保留 |
| 修改资料 | `pages/ChangeUserInfo/ChangeUserInfo` | 保留 |
| **介绍宣传页** | `pages/VideoDetailsPage/VideoDetailsPage` | **保留，实现逻辑不变** |
| 隐藏管理台 | `pages/SetPasswordCode/SetPasswordCode` | **删除**（功能迁至管理后台） |

### 8.3 VideoDetailsPage 特殊说明

该页面是对外宣传页（初中数学公式定理资料，21 张图片，指向 `WebPages/2/1.jpg` ~ `21.jpg`）。

现有实现：

```text
VideoDetailsPage.wxml
  1  <text>VideoDetailsPage</text>
  2  <text>富文本测试</text>
  3  <Parser html="{{htmlSnip}}" />
```

正文 HTML 硬编码在 `VideoDetailsPage.js` 的 `htmlSnip` 常量中，经 Parser 组件渲染。

**处理方式（ADR-005）**：实现逻辑保持不变——不迁入数据库、不改由后台维护。Parser 组件替换为 npm 维护版后，该页对外行为完全一致。

> ⚠️ **该页路径必须原样保留。** 代码中虽然没有跳转引用，但 `sitemap.json` 为全量允许索引，且可通过小程序码、分享、搜一搜直达。路径变更会导致已分发的入口失效。

### 8.4 需要重写的部分

1. **请求层**：新增统一 `request` 封装，自动附带 token、统一错误提示、401 自动重新登录。替代现有 21 个函数各自手写 `wx.request` + Promise 的写法。
2. **状态层**：新增极简状态模块，替代散落在各页面的 `wx.getStorageSync('UserInfoCache')`。
3. **Parser**：自研 `Parser/` 组件替换为 npm 维护版 `mp-html`（对外行为一致，`VideoDetailsPage` 与文章页不受影响）。
4. **移除轮询**：删除 `kecheng.js` 中 10ms × 500 次的登录等待轮询，改为 Promise 完成后驱动。
5. **修复首启竞态**：`index.js` / `wode.js` 在 `data` 中同步读取异步写入的 `Config` 缓存，首次安装必然报错。
6. **清理**：删除 `LoginOrOutDetails.js` 中大段注释掉的旧上传代码。

### 8.5 购买入口（唯一新增 UI）

> ⚠️ 加入支付后需要新增购买入口，这是「外观完全不变」的**唯一例外**——现有系统没有任何商品列表或购买按钮，付费课全靠口令码兑换。

采用最小侵入方案，复用现有视觉语言：

1. **首页长图页**（`IndexNewCourseDetails`）底部增加「立即购买」按钮，对应 `home_courses.course_id`。
2. **知识页**（`kecheng`）在有课时把未购课程一并列出（锁定态），点入课程详情页购买。

不新增 tab、不新增页面类型。

---

## 9. 数据迁移方案

### 9.1 迁移前体检结论

对生产库做过完整性校验，结果如下：

| 检查项 | 结果 |
|---|---|
| 课程目录数 | 10 门 |
| 有课时的课程 | 10 门 |
| 被购买过的课程 | 10 门 |
| 购买记录指向但目录中不存在的课程 | 无 |
| 有课时但目录中不存在的课程 | 无 |
| 目录中有但无课时的课程 | 无 |

**结论：零孤儿数据，映射关系完整，迁移无需人工补救。**

### 9.2 迁移映射

| 源 | 目标 | 关键处理 |
|---|---|---|
| `用户信息` | `users` | 字段改名；时间字段转 UTC |
| `用户已购课程` | `entitlements` | `source = legacy`，`granted_at = 购课日期`；48 条 |
| `课程口令码读取信息` | `courses` | `课程id → code`（原值保留） |
| `视频课程数据` | `lessons` | `章节id` / `播放id` 原值保留；841 条 |
| `免费视频课程数据` | `free_lessons` | |
| `首页课程列表` | `home_courses` | `课程名称` 原值保留（图片路径依赖） |
| `首页免费课程列表` | `home_free_courses` | 同上 |
| `首页横幅图片` | `banners` | `图片名` 原值保留 |
| `网页列表` | `articles` | `网页id → legacy_page_id`（图片路径依赖） |
| `课程页面Tips` | `course_tips` | |
| `cloudconfig` | `settings` | 数字 ID → 字符串 key，见 9.3 |
| `课程口令码` | `legacy_redeem_codes` | 原样保留，见 9.4 |

### 9.3 settings 键映射

| 原 ID | 原 value | 新 key | 说明 |
|---|---|---|---|
| 0 | 占空 | — | 废弃 |
| 1 | V0.0.9 | `site.version` | 版本 |
| 2 | 付费课程 | `home.title.paid` | 标题 |
| 3 | 试听课程 | `home.title.trial` | 标题 |
| 4 | 公开课程 | `home.title.public` | 标题 |
| 5 | Yelaymaths | `profile.qrcode_image` | 二维码图片名 |
| 6 | 50 | `profile.headicon_count` | 头像数量 |
| 7 | 修改资料 | `profile.menu.change_info` | 我的页面 |
| 8 | 好友分享 | `profile.menu.share` | 我的页面 |
| 9 | 在线沟通 | `profile.menu.contact` | 我的页面 |
| 10 | 添加微信：叶雷讲数学 | `profile.menu.wechat` | 我的页面 |
| 11 | 我是有底线的！ | `home.footer_text` | 首页触底提示 |
| 12 | 长按识别二维码 | `profile.qrcode_caption` | 图片标题 |

### 9.4 旧口令码处理（待确认）

**现状**：`课程口令码` 表中有 5 条记录，剩余有效次数合计 18 次。

| 口令码 | 课程 | 剩余次数 |
|---|---|---|
| 202601 | 7年级数学同步视频课（北师大） | 3 |
| 202602 | 8年级数学同步视频课（北师大） | 3 |
| 202603 | 9年级数学同步视频课（北师大） | 3 |
| 202604 | 梁老师中考数学一轮满分冲刺 | 5 |
| 202605 | 梁老师中考数学二轮满分冲刺 | 4 |

**技术事实**：口令码是「次数池」，**表结构中不含用户字段**，即无法从数据推导出这 18 次分别属于谁。因此**无法自动转换成「某用户已购买某课程」的记录**——缺少用户维度。

**本方案的处理（无损、可兜底）**：

1. 5 条记录原样迁入 `legacy_redeem_codes`，作为凭证留存。
2. 管理后台提供「旧口令码核销」功能：输入口令码 + 选择用户 → 扣减 `remaining_uses` → 写入 `entitlements(source = legacy_code)`。
3. 当持有旧码的用户来访时，运营在后台一键发放权益，业务闭环完整。

> ❓ **需要确认**：若本意是「这 18 次已经卖给具体学生、且手上有对应名单」，应**直接按名单批量生成** `entitlements(source = legacy)` 记录，而不是走核销流程。请提供名单或确认按上述核销方案执行。

### 9.5 迁移步骤

1. 全量备份生产库与 `Images/`、`WebPages/`、`Course/`、`FreeVideos/` 目录。
2. 建立新库与数据库账号。
3. 执行 `prisma migrate deploy` 建表。
4. 执行迁移脚本（`tools/migrate-legacy/`），要求：**幂等、可重复执行、逐步计数校验**。
5. 数据校验：
   - 逐表行数比对。
   - 随机抽取 10 个用户，比对迁移前后「已购课程集合」是否完全一致。
   - 校验每个 `entitlement.course_id` 在 `courses` 中均存在。
   - 校验 `courses.code` 与源数据逐字节一致。
6. 在 staging（`api_yeomai_site_develop`）跑通全部接口。
7. 生产切换，**旧库保留只读**作为回滚路径。

### 9.6 回滚方案

- 切换期 PHP 服务与 Node 服务在同一台机器共存。
- 小程序端在兼容层阶段未改动，回滚只需切换域名解析。
- 数据库切换前做全量快照，出问题直接回退。

---

## 10. 实施路线图

| 阶段 | 内容 | 工期 | 交付物 |
|---|---|---|---|
| 0 准备 | 宝塔 Node 环境试通（**最大未知项**）；备份；建 monorepo；确认 MySQL 账号权限 | 1–2 天 | 可运行的部署链路 |
| 1 数据端 | Prisma schema + 迁移 + 数据字典 + 迁移脚本 + 校验 | 3–4 天 | 新库可用，数据完整 |
| 2 服务端骨架 | NestJS + Prisma + zod + pino + Swagger；统一响应/异常/守卫；鉴权 + sessionKey 托管 | 4–5 天 | `/v1` 核心接口可用 |
| 3 兼容层 | `/API/*.php` 原样实现 + 逐接口对拍测试；staging 用小体验证 | 5–7 天 | 小程序可切新后端 |
| 4 生产切换 | 切域名，保留回滚路径 | 1 天 | 生产运行在 Node 上 |
| 5 管理后台 | Next.js 后台全功能；删除小程序隐藏管理页 | 1–2 周 | 运营可脱离 SQL |
| 6 支付 | 开通虚拟支付 → 道具 → 下单/推送/幂等/兜底 → 订单状态机 | 1–2 周 | 可自助购买 |
| 7 视频防盗链 | 对象存储 + CDN 签名 + `/play` 接口 | 3–5 天 | 付费内容不可直链 |
| 8 前端规范化 | request 封装、状态模块、去轮询、换 Parser、新增购买入口；删兼容层与死代码 | 4–5 天 | 全量切 `/v1` |

**总计约 6–8 周。**

> 顺序原则：**先让新后端原样接管（阶段 1–4），再谈支付（阶段 6）。** 支付本身不难，难的是把它塞进一个没有鉴权、没有订单表、没有后台的系统里。

---

## 11. 风险登记册

| 编号 | 风险 | 影响 | 应对 | 阶段 |
|---|---|---|---|---|
| R1 | 宝塔 Node 项目管理器对 pnpm workspace 支持不足 | 阻塞部署 | 阶段 0 先行验证；备选「CI 构建后仅部署产物」 | 0 |
| R2 | MySQL 5.7 账号无 `CREATE DATABASE` 权限导致 Prisma shadow DB 失败 | 阻塞迁移 | 授权，或本地 `migrate diff` + 生产 `migrate deploy` | 1 |
| R3 | `courses.code` 被改写 | 全部视频资源失效 | 迁移脚本禁止改写；加校验断言 | 1 |
| R4 | 封面 / 图片文件名被改写 | 图片 404 | 迁移脚本原值透传；加校验断言 | 1 |
| R5 | 时间字段未做 UTC 转换 | 订单时间偏移 8 小时 | 迁移时显式转换 + 抽样核对 | 1 |
| R6 | 18 次旧口令码归属不明 | 用户投诉 | 保留原表 + 后台核销入口；或按名单批量发放 | 1 / 5 |
| R7 | `VideoDetailsPage` 路径变更 | 已分发的入口失效 | 路径原样保留 | 8 |
| R8 | `sessionKey` 泄漏 | 用户态签名可被伪造 | 加密存储；日志脱敏 | 2 |
| R9 | 发货推送丢失 | 用户付款未开通 | 双通道：推送 + 定时查单 | 6 |
| R10 | iOS 12% 佣金与 45–60 天结算 | 毛利与现金流 | 定价计入佣金；预留周转 | 6 |
| R11 | 宝塔 MySQL 5.7 已 EOL | 无安全补丁 | 接受；保证每日备份可恢复 | 全部 |
| R12 | 生产密钥曾在 git / dump 中泄露 | 数据与资金风险 | 全部轮换：DB 密码、阿里云 AK/SK、邮箱授权码、小程序 AppSecret | 0 |

---

## 12. 待确认事项

| 编号 | 事项 | 现状 | 需要 |
|---|---|---|---|
| Q1 | 旧口令码的 18 次剩余次数 | 无用户维度，无法自动转成「用户已购买」 | 确认按 9.4 核销方案执行，或提供持有者名单 |
| Q2 | `VideoDetailsPage` 的实际访问入口 | 代码中无跳转引用，但可能经小程序码 / 搜索直达 | 确认是否对外分发过；若通过小程序码分发，路径必须保留 |
| Q3 | 头像资源数量 | `cloudconfig` 记录为 50，`Images/Headicons/` 实际 51 个文件 | 确认有效范围 |
| Q4 | 三大内容块是否全保留 | 默认全部保留 | 确认无内容需要下线 |

---

## 附录 A：目标仓库结构

```text
yelaymaths/
├─ apps/
│  ├─ api/                    # NestJS 服务端
│  │  ├─ src/
│  │  │  ├─ modules/
│  │  │  ├─ legacy/           # 兼容层（临时）
│  │  │  ├─ common/
│  │  │  └─ main.ts
│  │  ├─ prisma/
│  │  │  ├─ schema.prisma
│  │  │  └─ migrations/
│  │  └─ test/
│  ├─ admin/                  # Next.js 管理后台
│  └─ mp/                     # 微信小程序（原生）
├─ packages/
│  ├─ shared/                 # zod schema、枚举、DTO 类型
│  └─ tsconfig/               # 共享 TS / ESLint 预设
├─ tools/
│  └─ migrate-legacy/         # 老库 → 新库迁移脚本
├─ docs/
│  └─ 重构开发文档.md
├─ docker-compose.yml
└─ .gitlab-ci.yml
```

## 附录 B：现有 10 门付费课程

| course.code 前缀 | 课程名 |
|---|---|
| `98869f2f771e…` | 几何模型 |
| `1e7d43480f4e…` | 中考数学压轴大招 |
| `1da939cf5f61…` | 7年级同步课程 |
| `0656b64f6e60…` | 8年级同步课程 |
| `2e52fbb3c8d9…` | 9年级同步课程 |
| `cf944197d5fb…` | 7年级数学同步视频课（北师大） |
| `b711b037fb7b…` | 8年级数学同步视频课（北师大） |
| `6ec33e18e8ab…` | 9年级数学同步视频课（北师大） |
| `25caa811c67c…` | 梁老师中考数学一轮满分冲刺(视频+讲义) |
| `77d091c27378…` | 梁老师中考数学二轮满分冲刺(视频+讲义) |