# AI 工作计划（每次打开项目必读）

> 每次豆包打开这个项目，先按以下顺序读文件：
> 1. **先读完整诊断报告**（了解全貌：所有问题、所有方案、所有验收标准）
> 2. **再读本工作计划**（知道现在是第几周、该做什么）
> 3. 然后按计划推进

---

## 必读文件清单

| 顺序 | 文件 | 路径 | 作用 |
|---|---|---|---|
| 0️⃣ 必读 | 工作总控（唯一真源） | `工作总控.md` | 硬规则+布局锁死+专家闸门+当前变更记录；与本计划冲突时以此为准 |
| 0️⃣ 必读 | 新会话启动SOP | `新会话SOP.md` | 启动清单+10条硬规则+必跑脚本 |
| 1️⃣ 必读 | 完整诊断报告（约14.9万字节） | `系统交付级诊断报告.md` | 了解系统全貌：有什么问题、为什么、怎么解决、验收标准、12周路线图 |
| 2️⃣ 必读 | 本工作计划 | `AI_WORK_PLAN.md` | 知道现在是第几周、该做什么 |
| 3️⃣ 按需读 | 代码文件 | 看具体任务再读 | 改哪里就读哪里 |

> ⚠️ 注意：完整诊断报告约149KB，不用每次全读，知道在那里、需要查的时候再翻就行。
> 体系挂接：工作总控/SOP（运行维护线）→ 本计划+诊断报告（交付提升线），两条线已互相引用。

---

## 项目背景

## 项目背景

- **项目名称：** 水利智学系统（一造管理考试学习系统）
- **部署架构：** 华为电脑=本地服务器+华为平板/手机=移动端+离线同步
- **当前阶段：** 从"能跑"到"可交付"的大提升行动
- **综合完成度：** 约45%

---

## 核心原则

1. **数据质量是核心**：知识库=大脑，大脑不行其他都白搭
2. **分步推进**：保现状→补核心→提质量→做优化
3. **不按下葫芦浮起瓢**：改数据结构前先备份，改完跑回归测试
4. **所有数字必须实查**：不能猜，跑脚本验证
5. **先公共后业务**：底座先做好，上面的功能才有标准

---

## 当前系统真实现状（实查数据）

### 数据库
- 总表：124张（26张deprecated_旧表）
- 题库：2681题
- 错题本：571条（SM-2字段全齐）
- 知识点：235个
- 知识框架：137条
- 知识库主表：空（0行）
- RAG向量库：空（0行）
- 同步记录：0条
- 自动备份记录：0条

### 代码
- 后端：288个Python文件，约752个API端点
- 前端：26个JS文件，21024行
- 硬编码颜色：2110处
- 综合完成度：约45%

---

## 6周推进计划（按顺序做，不要跳）

### 第1周：数据底座（只做数据，不做功能）

| 天 | 任务 | 产出 | 验收标准 |
|---|---|---|---|
| Day1-2 | 建标准章节表（6章24节） | 章节表 | 表建好 |
| Day3 | 批量UPDATE章节字段 | 数据迁移 | 抽100道正确率≥95% |
| Day4 | 知识点标准化（118种→50个标准考点） | 知识点表 | 标准知识点表 |
| Day5 | 过时题清理（25道：PPP/BOT/特许经营/营业税） | 标记完成 | 刷不到过时题 |

**本周不做：** 不改前端、不改AI、不改同步

---

### 第2-3周：知识库（基于已有框架，灌数据+对接旧版）

| 周 | 天 | 任务 | 产出 |
|---|---|---|---|
| 第2周 | Day1-2 | 对接旧版PDF数据（deprecated_file_content_block 6万多行） | 数据迁移 |
| 第2周 | Day3 | 按章节分块 | 1000+块 |
| 第2周 | Day4-5 | 灌RAG向量库（用已有build_rag_index.py） | rag_embeddings有数据 |
| 第3周 | Day1-2 | AI解析流程改造（先检索再生成） | 新流程 |
| 第3周 | Day3 | Prompt优化+解析带章节定位 | 每道解析标出处 |
| 第3周 | Day4 | 测试50道AI解析 | 成功率≥80% |
| 第3周 | Day5 | 关联口诀 | 解析带出口诀 |

**本周不做：** 不改刷题界面、不改同步、不做移动端

---

### 第4周：功能闭环（基于知识库做功能）

| 天 | 任务 | 产出 |
|---|---|---|
| Day1-2 | 错题本艾宾浩斯接线（后端due_today接口+前端接线） | 真的能复习 |
| Day3 | 薄弱点推荐 | 根据错题推荐知识点 |
| Day4 | 快速笔记功能 | 转闪卡边上加快捷笔记 |
| Day5 | 回归测试 | 核心流程不回归 |

---

### 第5周：同步+移动端

| 天 | 任务 | 产出 |
|---|---|---|
| Day1 | 版本号机制（/version接口） | 移动端能查版本 |
| Day2-3 | 离线写队列（IndexedDB+批量推送） | 离线答题不丢 |
| Day4-5 | 移动端适配（汉堡菜单+按钮大小+字体适配） | 手机能正常用 |

---

### 第6周：收尾验收

| 天 | 任务 | 产出 |
|---|---|---|
| Day1-2 | 代码整理（公共服务+大文件拆分） | 可维护性提升 |
| Day3 | 文档编写（部署指南+用户手册+验收报告） | 4个核心文档 |
| Day4 | 测试验收 | 验收报告 |
| Day5 | 版本快照 | v8.0交付版 |

---

## 安全保障（每步必做）

### 改之前
- [ ] 完整备份数据库
- [ ] 备份要改的文件
- [ ] 列清楚今天改什么、不改什么

### 改之后
- [ ] 跑语法检查（node verify.cjs）
- [ ] 同步到static（node sync.cjs）
- [ ] 跑核心流程回归（刷题→解析→错题本）
- [ ] 跑数据自检脚本

### 改坏了
- [ ] 恢复数据库备份
- [ ] 恢复代码备份
- [ ] 记录这次什么问题、为什么、下次怎么避免

---

## 已知问题清单（优先级排序）

### P0 必须先解决
1. 知识库空（rag_embeddings 0行）
2. 章节字段混乱（118种格式）
3. 过时题没清理（还有25道）
4. 自动备份没跑

### P1 第二阶段解决
5. 错题本艾宾浩斯假按钮
6. 同步没跑通
7. 移动端没适配
8. 薄弱点推荐不准

### P2 第三阶段解决
9. 代码质量差（43/100分）
10. 硬编码颜色2110处
11. 大文件拆分
12. 文档不全

---

## 关键文件路径

- 主数据库：`backend/data/shuili_exam.db`
- 主修改文件：`frontend/modules/question/question-practice.js`
- 后端API目录：`backend/api/v1/`
- 前端模块目录：`frontend/modules/`
- 诊断报告：`系统交付级诊断报告.md`
- 本计划文件：`AI_WORK_PLAN.md`

---

## 每次开工前检查

1. 读这个文件
2. 看看现在是第几周、该做什么
3. 确认前一周的验收标准都达标了
4. 开始干活

---

**版本：** v1.0
**创建日期：** 2026-09-20
**最后更新：** 2026-09-20
