Files
lpt-meta/.agents/notes/proposed/process/2026-11-20-prod-keep-learning-history.md
T
cat-shark c716f5c8db docs: 补记范围相关导图与 prod 升级方案
- 待办:复习总览改为「上次编辑的导图」,任务页相关导图不再区分草稿/已结束
- 新增笔记:总览按所选标签列出保存过的导图
- 新增提案:prod 只保留学习记录后原地升级
2026-11-22 21:41:26 +08:00

204 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Agent Note: prod 只保留学习记录后原地升级到新结构
Status: proposed
## Problem
prod 库 `lpt_prod` 停在 Flyway `20260706.1`(15 个迁移),dev 头是 `20261118.2`,中间 **24 个迁移(20 个 SQL + 4 个 Java)** 一次都没跑过。这批迁移里 `V20261116_1` 删掉旧的回忆存储、`V20261118_1` 清空回忆相关数据,属于破坏性变更;`V20261009_7` 还会把学习报告从单列 `content` 改名成 `free_summary`,并把知识碎片的 `session_num` 改名成 `context_num`、按会话回填内容归属。
同时按「分支绑定部署」规则,prod 只能从 `master` 出包,而 dev 头分别领先 master:lpt-be 67 个提交、lpt-fe 84 个、lpt-ai 20 个。也就是说,升级前必须先做一次显式的 `master → dev → master` 合并,并且三个仓库同批出包。
prod 里还有一批维护者不再需要的数据:学习预期 23 条、标准导图 3 张、3 个已软删的学习任务(名字是 `1` / `123`)等。维护者要求**只保留学习任务(在用 6 个)、学习会话(时长)、学习报告、知识碎片**,其余直接移除。这批数据只在这台机器的 MySQL 里(hostPath `/vol1/lpt/mysql/prod/data`),没有第二份。
两个目标要一次完成:结构升到 dev 头,数据裁剪到保留清单。
## 现状核对
2026-11-20 从 `lpt-prod` 的 MySQL 直接读出,未经任何修改:
| 表 | 行数 | 处理 |
|---|---:|---|
| `user` | 1(`admin`,BCrypt) | 保留(登录用) |
| `tasks` | 9(6 在用 + 3 已软删) | 保留 6 个在用;3 个软删任务删除 |
| `study_sessions` | 30(2025-10-20 ~ 2026-10-29,全部 `ENDED`) | 全部保留 |
| `study_reports` | 30(与会话 1:1,纯文本 3~684 字) | 全部保留,正文落自由总结 |
| `study_report_fragments` | 38(全部挂在存在的会话上) | 全部保留 |
| `study_expectations` | 23 | 移除 |
| `review_standard_mind_maps` | 3 | 移除 |
| `review_mind_maps` / `review_recall_records` / `task_applications` / `user_priority_weights` / `test_table` | 0 | 移除(本就为空) |
数据基线(升级后必须保持一致,负数那行见「待确认」):
| 项 | 值 |
|---|---|
| 会话数 | 30 |
| `SUM(actual_time)` | 111 695 秒 |
| `SUM(effective_time)` | 97 495 秒(负数那行按 0 算则为 98 994 秒) |
| 花果事考(`TASK-20261008-380034`) | 22 次会话 / 实际 94 004 秒 / 有效 83 323 秒 / 碎片 31 条 |
| 麻省理工开放课程 线性代数(`TASK-20251019-383352`) | 4 次 / 12 470 / 12 470 / 0 条 |
| 斯坦福21秋季:实用机器学习中文版(`TASK-20251019-331417`) | 3 次 / 2 815 / **-704** / 2 条 |
| stm32 铁头山羊课程(`TASK-20261022-751979`) | 1 次 / 2 406 / 2 406 / 5 条 |
其他事实:
- 无重复 `task_num` / `session_num`、无孤儿碎片或会话、无空正文,`V20261009_3` 的唯一约束与 `V20261009_5` 的类型转换不会因脏数据失败;唯一异常是会话 5 的有效时间 `-1499` 秒、效率比 `-0.74`。
- 备份 CronJob 每天 03:00 全库 dump 到 `/vol1/lpt/backup/prod`,保留 14 天,单份 3.9 MB;磁盘剩 7.1 TB。最新一份是 2026-11-20 03:00。
- 旧镜像 tag(回滚要用,recorded 2026-11-20):
- `192.168.123.199:5000/lpt-be:fbc2650625f0262d8f3006f4217a1a12603281ed-1794121607`
- `192.168.123.199:5000/lpt-fe:2505edeae7155eb8ab86476c0663939245764fde-1794122526`
- `192.168.123.199:5000/lpt-ai:09670673dea326ed1161241931523bd054661513-1794122158`
- `master → dev` 三个仓库都能干净合并(`git merge-tree` 无冲突)。
## Proposal
```mermaid
flowchart TD
A[冻结写入<br/>lpt-fe / lpt-be / lpt-ai 副本数改 0] --> B[整库 dump + 保留表 dump<br/>NAS 与本机各一份]
B --> C[还原到 lpt_prod_verify<br/>核对 5 张表行数与合计时长]
C -->|不一致| R[停止,先修备份]
C -->|一致| D[合并 master→dev→master<br/>be / fe / ai 同批]
D --> E[dev 出包<br/>24 个迁移跑在 dev 库]
E --> F[prod 副本演练<br/>lpt_prod_rehearsal]
F -->|失败| G[只新增迁移修复<br/>重建演练库重跑]
G --> F
F -->|通过| H[部署新 lpt-be 到 prod<br/>Flyway 跑 24 个迁移]
H -->|失败| X[回滚:还原 dump + 回退镜像]
H --> I[按保留清单清库<br/>提交前后行数]
I --> J[部署 lpt-fe / lpt-ai<br/>恢复副本数]
J --> K[验收:SQL + 页面 + 导出接口]
K -->|不通过| X
K --> L[结束维护窗口]
```
### 相位 0:冻结与取证(维护窗口开始)
1. 记录旧镜像 tag(上面已列),确认 registry 里仍能拉取。
2. 停写:`kubectl -n lpt-prod scale deploy lpt-fe lpt-be lpt-ai --replicas=0`,MySQL 不动。
3. 在 MySQL Pod 里取三份 dump(都带 `--single-transaction --routines --events --triggers --default-character-set=utf8mb4`):
- `pre-migration-all.sql`:`--all-databases`,整库还原用;
- `pre-migration-lpt_prod.sql`:只导 `lpt_prod`,演练用;
- `keep-only.sql`:只导 `user tasks study_sessions study_reports study_report_fragments`,数据取证件。
4. 三份都写 `/vol1/lpt/backup/prod/manual/<ts>/` 并 `sha256sum`,再把整库那份拷到本机 `~/lpt-prod-backups/<ts>/`。
5. 还原 `pre-migration-lpt_prod.sql` 到临时库 `lpt_prod_verify`,核对 5 张表行数与上表一致;一致才继续,否则停。核对完删掉临时库。
6. 记录基线数字(上表)到一本执行记录里,后续每一步都跟它比。
### 相位 1:出包与演练(维护窗口之前完成)
1. `master → dev` 合并三个仓库,跑测试;再 `dev → master` 合并。三仓同批推。
2. 从 `dev` 触发 lpt-be 的出包(`environment=dev`)。这一步会让 24 个迁移先跑在 dev 库(MySQL 9、94 条会话)上,验证 Flyway 能启动;失败就只影响 dev。
3. 演练:在 prod 的 MySQL 8.0 上建 `lpt_prod_rehearsal`,导入 `pre-migration-lpt_prod.sql`;用第 2 步打出来的镜像起一个一次性 Pod(不改 Deployment),把 `SPRING_DATASOURCE_URL` 指到演练库,等日志出现 `Successfully applied 24 migrations` 与 `Started` 后核对:
- `flyway_schema_history` 头为 `20261118.2`,24 条 `success=1`,无失败行;
- 保留表行数、`SUM(actual_time)`、`SUM(effective_time)` 与基线一致;
- 30 条报告 `free_summary` 全非空、`session_summary` / `expectation_verdict` 全为 NULL;
- 38 条碎片 `context_type='SESSION'`、`context_num` 等于旧 `session_num`、`owner_task_num` 全部解析到 4 个任务(31 / 2 / 5);
- 计时列已是 `DOUBLE`,负数那条仍是 `-1499`;
- 其余表为空(或仅 `user_tags` / `markers` 有迁移回填的标签,见「待确认」)。
4. 在同一份演练库上再跑一遍清理 SQL,确认前后行数符合预期;确认后删掉演练库。
5. 演练不通过:只允许**新增**迁移修复,不改已发布的 15 个旧迁移,重建演练库重跑。不通过不进 prod。
### 相位 2:升级 prod
1. 确认 FE/BE/AI 仍是 0 副本、重复确认整库 dump 的 sha256。
2. 从 `master` 触发 lpt-be 的 `environment=prod` 出包。Flyway 在启动时跑 24 个迁移;观察启动日志与 readiness,失败立即停,走回滚。
3. 按验收标准第 1~5 条核对,任何一条不符就停,不进清理。
### 相位 3:按保留清单清理
用一个一次性 SQL 在 `lpt_prod` 上执行(**不写成 Flyway 迁移**,理由见备选)。脚本放在 `lpt-be/ops/prod-keep-learning-history.sql`,只含 DELETE,前后各打一次行数:
```sql
START TRANSACTION;
DELETE FROM study_expectations;
DELETE FROM review_mind_maps;
DELETE FROM review_standard_mind_maps;
DELETE FROM review_tag_mind_maps;
DELETE FROM review_recalls;
DELETE FROM review_recall_receipts;
DELETE FROM review_recall_requests;
DELETE FROM review_recall_owner_locks;
DELETE FROM review_guidance_conversations;
DELETE FROM task_applications;
DELETE FROM user_priority_weights;
DELETE FROM user_review_preferences;
DELETE FROM ai_tasks;
DELETE FROM ai_usage_records;
DELETE FROM test_table;
DELETE FROM markers;
DELETE FROM user_tags;
DELETE FROM tasks WHERE deleted = 1;
COMMIT;
```
- 会话、报告、碎片、`user`、6 个在用任务不动。
- 只删行、不删表:表结构还要给新版本用。
- `markers` / `user_tags` 里是 `V20261115_5` 按任务名回填的标签(38 条标记 + 至多 4 个标签名),属于「其余数据」,默认删;要保留按标签回顾历史的能力就跳过这两条 DELETE。
### 相位 4:全栈上线
1. 从 `master` 触发 lpt-fe、lpt-ai 的 `environment=prod` 出包(三者同批)。
2. 三个 Deployment 副本数恢复 1,确认 readiness。
3. 走验收标准第 6~8 条,通过后结束维护窗口。
### 回滚
触发条件:迁移报错、行数或合计不符、关键页面 500。
1. 三个 Deployment 副本数改 0。
2. `DROP DATABASE lpt_prod; CREATE DATABASE lpt_prod CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci;`,导入 `pre-migration-all.sql`。
3. `kubectl set image` 把三个 Deployment 指回上面记录的旧 tag,副本数恢复 1。
4. 用 `admin` 登录、核对 5 张表行数与基线,再排查问题。
**Flyway 迁移不可逆,镜像回滚不等于数据回滚**:只要库被改过,就必须整库还原。dump 在 NAS 与本机各留一份,保留 30 天。
## Alternatives considered
### 为什么不在空库重建后导入
当 `baseline-on-migrate: true` 时,空库会先 baseline 到版本 1,再把 39 个迁移全部跑一遍,所以「建空库」并不省迁移;反而要自己写导入脚本,并手工复刻 `V20261009_7` 的报告改名、碎片上下文改名和归属回填、`V20261115_5` 的标签回填。做的事情更多,出错面更大,收益只是表里少 0 行。
### 为什么不在 prod 直接升级、跳过演练
迁移一旦在 prod 上开始就没有回退键,失败只能整库还原并回退镜像,维护窗口不可控。演练用 prod 的 MySQL 8.0 和同一条 dump,成本约半小时,能提前暴露 SQL 与 Java 迁移在 8.0 上的差异(dev 是 MySQL 9)。
### 为什么清理不写成 Flyway 迁移
迁移会在 dev 也执行,把 dev 的测试数据删掉;而且数据裁剪不是结构变更,不该由版本化迁移驱动。写成一次性 SQL、执行前后打行数,既能审计也不污染 dev。
### 为什么三个仓库必须同批
`V20261116_1` 之后旧回忆端点与请求体都不存在,be/fe/ai 单独上线会出现 400/404;分支绑定规则也要求 `master` 配 `master` 同批发布。
### 为什么保留在用任务
学习时长、报告、碎片都按任务查询与展示:没有任务行,会话的 `task_num`、碎片的 `owner_task_num` 就成了指向不存在对象的字符串,三类数据在界面上没有入口。任务本身的名称也是这些记录的唯一可读归属。
## Acceptance criteria
1. `flyway_schema_history` 最大版本 `20261118.2`,新增 24 条 `success=1`,无失败行。
2. 行数:`user` 1、`tasks`(`deleted=0`)6、`study_sessions` 30、`study_reports` 30、`study_report_fragments` 38。
3. 合计:`SUM(actual_time)=111695`、`SUM(effective_time)=97495`(若修正负数则为 98994),按任务的四个数字与基线表一致。
4. 30 条报告 `free_summary` 非空、`session_summary` 与 `expectation_verdict` 全为 NULL。
5. 38 条碎片:`context_type='SESSION'`、`context_num` 等于旧 `session_num`、`owner_task_num` 非空且指向在用的 4 个任务。
6. 其余业务表 0 行:`study_expectations`、`review_*`、`task_applications`、`user_priority_weights`、`user_review_preferences`、`ai_tasks`、`ai_usage_records`、`test_table`、`markers`、`user_tags`。
7. `admin` 登录后:学习页 6 个任务、各任务累计有效学习时间与基线一致;复习详情能看到 30 条历史报告(正文在「自由总结」);知识碎片 38 条、归属正确;学习预期、导图、回忆、标签为空态。
8. `GET /export/range?format=json` 返回 30 条报告、38 条碎片与对应会话,作为「数据已取到且可读」的最终证明。
## Risks
- **迁移不可回滚**:MySQL 的 DDL 部分不是事务性的,失败可能停在半途。唯一兜底是整库 dump 还原;所以 dump 必须先在 `lpt_prod_verify` 上证明可还原。
- **`V20261009_3` 唯一约束**:历史数据有重复编号会直接让升级失败。已核对无重复;演练会再确认一次。
- **`V20261009_5` 计时列改类型**:30 行值都合法(含负数),失败风险低;负数不会被迁移修正。
- **报告只剩一段**:30 条历史报告只有「自由总结」,另两段永远为空。这是维护者确认过的取舍。
- **负数会话**:不修正时累计有效时间少 1 499 秒(约 25 分钟),页面按 0 显示单条但累计值会被拉低。
- **清理脚本依赖迁移后的表名**:只能在升级完成、核对通过后执行;在旧库或未升级的 dev 上会报表不存在。
- **流水线的自动回滚只回镜像**:迁移已经落库,自动回滚后旧镜像无法在新结构上正常工作,必须按「回滚」段手工还原。
- **演练库与 prod 同实例**:演练会占少量连接与磁盘(数据 50 KB 级),但绝不能指向 `lpt_prod`;一次性 Pod 的 `SPRING_DATASOURCE_URL` 要落成明文写清库名。
## 待确认
1. 会话 5 的 `effective_time=-1499`、效率比 `-0.74`:默认置 `0` / `0`(旧缺陷产物,不是真实学习时间);要保留原值也能做,只是累计值会少 25 分钟。
2. `markers` / `user_tags` 里迁移回填的任务名标签:默认随「其余数据」一起删;若想保留按标签回顾历史的能力,跳过这两条 DELETE。
3. 维护窗口时长:预计 40 分钟(冻结与备份验证 15 分钟、迁移 2 分钟、核对 5 分钟、清理 1 分钟、前端与验收 15 分钟),演练放在窗口之前。