startup-plan/执行计划与任务清单.MD

# 知习执行计划与任务清单

> 最后更新：2026-05-19 | 依据：知识库设计 + 服务器部署方案 + 凭据信息

---

## 当前状态速览

| 资产 | 状态 |
|------|------|
| **4核4G 轻量云** (81.70.187.179) | ✅ 工具服务器 — Web + Gitea + Nginx，旧 MySQL/Redis 退役 |
| **8核32G 蜂驰云** (120.53.227.155) | ✅ 生产主服务器 — NestJS + MySQL + Redis + Qdrant + Gitea Runner |
| **域名 longde.cloud** | ✅ `api.longde.cloud` DNS 已切到 8核32G，HTTPS 已生效 |
| **数据库** | ✅ MySQL 8.0.46，zhixi_prod 已迁移，33 张表 |
| **后端代码** | ✅ NestJS 生产运行，build 通过，systemd 自启 |
| **Python RAG Worker** | 🔶 代码已部署到 /opt/zhixi/backend/rag-worker/，依赖 + systemd 待补 |
| **iOS 客户端** | ✅ 已基本完成 UI，待对接知识库 API |
| **Web 产品页** | ✅ 已上线，Web 仓库 CI/CD |

---

## 阶段一：8核32G 基础环境（✅ 已完成）

| # | 任务 | 状态 |
|---|------|------|
| 1.1 | 数据盘挂载到 /data + 子目录 | ✅ |
| 1.2 | 安装 Docker 29.1.3 + Docker Compose 2.40.3 | ✅ |
| 1.3 | 安装 Git + Node.js 22.22.2 + pnpm 11.1.3 + Python 3.11.15 | ✅ |
| 1.4 | 安全组配置（22/80/443 开，其余仅 127.0.0.1） | ✅ |
| 1.5 | 创建 deploy 用户 | ✅ |
| 1.6 | 安装 logrotate | ✅ |

---

## 阶段二：核心服务部署（✅ 已完成）

| # | 任务 | 状态 |
|---|------|------|
| 2.1 | Docker 部署 MySQL 8.0.46（innodb_buffer_pool_size=8G, max_connections=100） | ✅ |
| 2.2 | 创建 zhixi_prod 数据库 + zhixi_user 账号 | ✅ |
| 2.3 | Docker 部署 Redis 7（512MB, noeviction, AOF+RDB） | ✅ |
| 2.4 | Docker 部署 Qdrant（collection: zhixi_chunks, 1024d, Cosine, 1 shard）| ✅ |
| 2.5 | 三服务联通验证 | ✅ |

---

## 阶段三：数据库迁移与 ID 改造（✅ 已完成）

| # | 任务 | 状态 |
|---|------|------|
| 3.1 | ID 类型检查 | ✅ 已是 String(cuid)，无需改造 |
| 3.2 | Prisma migration 初始化 | ✅ 3 个 migration 已执行 |
| 3.3 | 数据迁移（4核→8核） | ✅ 无实际数据，结构重建即完成 |

---

## 阶段四：CI/CD 搭建（✅ 已完成）

| # | 任务 | 状态 |
|---|------|------|
| 4.1 | 8核32G 安装 gitea-runner-prod | ✅ systemd 自启，labels: prod/backend/rag/docker |
| 4.2 | 4核4G 安装 gitea-runner-web | ✅ systemd 自启，labels: ubuntu-latest |
| 4.3 | deploy-backend.yml | ✅ 4 步骤：checkout → infrastructure → rsync worker → health |
| 4.4 | deploy-web.yml | ✅ `/tmp/web-projects/.gitea/workflows/deploy.yml` 已验证 |
| 4.5 | Gitea Secrets 配置 | ✅ 密钥放在服务器本地 .env |
| 4.6 | Gitea 1.22.6 → 1.23.8 升级 | ✅ 修复 Actions 模板渲染 bug + UpdateTask 状态更新问题 |

---

## 阶段五：NestJS 后端迁移（✅ 已完成）

| # | 任务 | 状态 |
|---|------|------|
| 5.1 | clone api-server 到 /opt/zhixi/backend | ✅ |
| 5.2 | pnpm install + pnpm build | ✅ |
| 5.3 | systemd zhixi-api.service | ✅ 开机自启 |
| 5.4 | Nginx + Let's Encrypt HTTPS | ✅ api.longde.cloud SSL 已生效 |
| 5.5 | DNS api.longde.cloud → 8核32G | ✅ |
| 5.6 | iOS 可通过 HTTPS 访问 | ✅ API 正常返回 |

---

## 阶段六：知识库核心开发（🟡 进行中）

### 6-A：Prisma 数据模型（✅ 已完成）

| # | 任务 | 状态 |
|---|------|------|
| 6.1 | 新增 KnowledgeSource / KnowledgeChunk / ImportCandidate / BackupJob / MembershipPlan | ✅ |
| 6.2 | 增强 DocumentImport（sourceId/workerId/heartbeatAt/retryCount/step）| ✅ |
| 6.3 | 增强 UploadedFile（sha256/purpose）| ✅ |
| 6.4 | 增强 KnowledgeItem（sourceDeleted/snapshot 字段）| ✅ |
| 6.5 | migration 生成 + 生产部署 | ✅ 33 张表 |

### 6-B：后端模块（✅ 已完成）

| # | 任务 | 状态 |
|---|------|------|
| 6.6 | KnowledgeSource 模块（CRUD + 创建时自动生成 DocumentImport）| ✅ |
| 6.7 | ImportCandidate 模块（查询/接受/拒绝/批量接受，接受时自动生成 KnowledgeItem）| ✅ |
| 6.8 | 内部 RAG API（任务轮询/认领/心跳/状态/chunks/candidates）| ✅ @Public 绕过 JWT |

### 6-C：Python RAG Worker（✅ 已完成部署）

| # | 任务 | 状态 |
|---|------|------|
| 6.9 | main.py 主循环（轮询→认领→执行）| ✅ |
| 6.10 | parser.py（PDF/DOCX/TXT/MD/CSV/XLSX + OCR）| ✅ |
| 6.11 | chunker.py（512 tokens + 64 overlap + 中文分句保护）| ✅ |
| 6.12 | embedder.py（bge-m3 via 硅基流动）| ✅ |
| 6.13 | indexer.py（Qdrant upsert + 检索 + 软删除）| ✅ |
| 6.14 | candidate_generator.py（DeepSeek 生成候选知识点）| ✅ |
| 6.15 | import_pipeline.py（完整导入流程编排）| ✅ |
| 6.15a | 代码推送到 8核32G `/opt/zhixi/backend/rag-worker/` | ✅ |
| 6.15b | .env 配置（API 密钥 / endpoint）| ✅ |
| 6.15c | pip install -r requirements.txt | ✅ 28+ packages via tencentyun mirror |
| 6.15d | 创建 systemd zhixi-worker.service | ✅ enabled active，轮询正常 |

### 6-D：AI Provider（✅ 已完成）

| # | 任务 | 状态 |
|---|------|------|
| 6.16 | DeepSeek 官方 API Key | ✅ |
| 6.17 | 硅基流动 API Key（embedding/rerank/vision）| ✅ |
| 6.18 | 百度 OCR | ✅ AppID 7767914，密钥已存入凭据 |

---

## 阶段七：学习引擎（⚪ 待开始）

| # | 任务 | 状态 |
|---|------|------|
| 7.1 | 主动回忆接口 | ⏳ |
| 7.2 | AI 诊断（DeepSeek thinking → FocusItem）| ⏳ |
| 7.3 | 复习卡生成 | ⏳ |
| 7.4 | 学习记录 | ⏳ |

---

## 阶段八：知识库对话（⚪ 待开始）

| # | 任务 | 状态 |
|---|------|------|
| 8.1 | RAG 检索 pipeline（Top-50 → rerank Top-5~8）| ⏳ |
| 8.2 | 知识库对话接口（answer + citations + suggestedActions）| ⏳ |
| 8.3 | Chat session + messages | ⏳ |

---

## 阶段九：运维配套（⚠️ 部分完成）

| # | 任务 | 状态 |
|---|------|------|
| 9.1 | MySQL 每日备份 + 同步 COS | ⏳ |
| 9.2 | Qdrant 每日快照 + 同步 COS | ⏳ |
| 9.3 | Stale job recovery（定时任务）| ⏳ |
| 9.4 | 定时物理清理 | ⏳ |
| 9.5 | /health 端点 | ✅ GET /api 返回 {"status":"ok"} |

---

## 阶段十：额度与后台（⚪ 待开始）

| # | 任务 | 状态 |
|---|------|------|
| 10.1 | membership_plans 表 | ✅ 表已建，待填充数据 |
| 10.2 | 额度检查中间件 | ⏳ |
| 10.3 | 后台管理 API | ⏳ |
| 10.4 | AI 成本日志 | ⏳ |

---

## 待办速查（5/20 更新）

1. ~~🔴 **Python Worker 补全部署**~~ ✅ 已完成 — systemd zhixi-worker.service 运行中
2. ~~🔴 **4核4G 安装 gitea-runner-web**~~ ✅ 已完成 — 单一 runner 覆盖两端
3. ~~🟡 **百度 OCR 开通**~~ ✅ 已完成 — AppID 7767914，密钥已存
4. ~~🟡 **COS Bucket 验证**~~ ✅ Bucket `zhixi-1259685406` 存在，SecretId/Key 已验证可访问
5. ~~🟡 **Rerank 模块代码**~~ ✅ reranker.py 已推送，bge-reranker-v2-m3 验证通过
6. ~~🔴 **CI/CD 流水线修复**~~ ✅ 精简为 4 步，Runner 正确匹配，Gitea 升级到 1.23.8
7. 🟡 **知识库对话接口**（RAG 检索→rerank→DeepSeek 回答+citations）
8. 🟡 **知识库级联删除**
9. 🟢 **MySQL/Qdrant 备份脚本 + cron**
10. 🟢 **物理清理定时任务**
11. ⬜ **阶段七：学习引擎**（ActiveRecall→AIAnalysis→FocusItem→ReviewCard）
12. ⬜ **阶段八：知识库对话**（Chat session + 多轮对话）
13. ⬜ **阶段十：后台管理 + 额度检查**