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** | ✅ 代码完成，待部署到服务器 |
| **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 自启 |
| 4.2 | 4核4G 安装 gitea-runner-web | ⏳ 待安装 |
| 4.3 | deploy-backend.yml | ⏳ 待编写 |
| 4.4 | deploy-web.yml | ⏳ 待编写 |
| 4.5 | Gitea Secrets 配置 | ⏳ 待配置 |

---

## 阶段五：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-D：AI Provider（✅ 已配置）

| # | 任务 | 状态 |
|---|------|------|
| 6.16 | DeepSeek 官方 API Key | ✅ |
| 6.17 | 硅基流动 API Key（embedding/rerank/vision）| ✅ |
| 6.18 | 百度 OCR | ⏳ 待开通 |

---

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

| # | 任务 | 状态 |
|---|------|------|
| 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 成本日志 | ⏳ |

---

## 待办速查（明天优先）

1. 🔴 **Python Worker 部署** — 在 8核32G 安装依赖 `pip3.11 install -r requirements.txt`，配置 .env，编写 systemd service
2. 🔴 **COS Bucket 创建** — 腾讯云控制台创建 `zhixi-prod` bucket，配置 SecretId/SecretKey
3. 🟡 **百度 OCR 开通**
4. 🟡 **4核4G 安装 gitea-runner-web**
5. 🟡 **deploy-backend.yml / deploy-web.yml 编写**