87 lines
10 KiB
Markdown
87 lines
10 KiB
Markdown
# 任务拆解清单（详细版）
|
||
|
||
本文档将整个开发过程拆解为可执行的工作包，包含优先级、工时估算、依赖关系和里程碑。所有任务均覆盖核心功能、测试、部署及新增需求（单点测试、拖拽排序、独立模型选择、PDF导出）。
|
||
|
||
## 优先级说明
|
||
- **P0**：核心功能，必须完成才能可用。
|
||
- **P1**：重要功能，提升体验。
|
||
- **P2**：优化和增强。
|
||
|
||
---
|
||
|
||
## 阶段一：基础设施与核心服务 (第1~2周)
|
||
|
||
| ID | 任务 | 子任务 | 工时(h) | 优先级 | 依赖 | 里程碑 |
|
||
|----|------|--------|---------|--------|------|--------|
|
||
| 1.1 | 需求分析与架构评审 | - 编写详细需求文档（含用户故事）<br>- 数据库模型设计评审（ER图、字段说明）<br>- 技术选型最终确认（含PDF导出库调研） | 24 | P0 | - | 架构基线完成 |
|
||
| 1.2 | 开发环境搭建 | - 配置后端虚拟环境，安装 FastAPI、SQLAlchemy、Celery、PyPDF2等<br>- 配置前端项目（Vite + React + TS + Ant Design）<br>- Docker Compose 定义基础服务（Postgres、Redis） | 16 | P0 | 1.1 | 可运行空框架 |
|
||
| 1.3 | 数据库与 ORM | - 使用 Alembic 创建初始迁移，建表（models, templates, generation_points, tasks, system_config）<br>- 编写 SQLAlchemy 模型（含`order`字段用于生成点排序）<br>- 实现数据库会话依赖注入 | 24 | P0 | 1.2 | 数据库就绪 |
|
||
| 1.4 | 文件存储服务 | - 实现文件上传、下载、删除工具类<br>- 配置存储根目录和路径生成规则（区分模板、参考文件、结果） | 16 | P0 | 1.3 | 文件操作可用 |
|
||
|
||
## 阶段二：核心业务逻辑 (第3~5周)
|
||
|
||
| ID | 任务 | 子任务 | 工时(h) | 优先级 | 依赖 | 里程碑 |
|
||
|----|------|--------|---------|--------|------|--------|
|
||
| 2.1 | 文档处理服务（含PDF导出） | - 集成 Aspose.Words (或 Mammoth + python-docx) 实现 docx ↔ HTML 转换<br>- 实现 `docx_to_html` 和 `html_to_docx` 函数<br>- 实现 `docx_to_pdf` 函数（使用 python-docx + reportlab 或 Aspose）<br>- 单元测试转换效果（包含表格、图片、样式） | 48 | P0 | 1.4 | 文档转换与导出达标 |
|
||
| 2.2 | AI 模型管理 API | - 实现 CRUD 接口<br>- API Key 加密存储（Fernet）<br>- 启用/禁用切换<br>- 列表查询过滤（启用/全部） | 24 | P0 | 1.3 | 模型管理功能完备 |
|
||
| 2.3 | 模板管理 API | - 上传接口（接收文件，存储并转换 HTML）<br>- 获取 HTML 内容（含模板基本信息）<br>- 更新 HTML（并同步转回 docx）<br>- 下载接口（支持 docx 和 pdf 格式参数） | 32 | P0 | 2.1, 1.4 | 模板 CRUD 完成 |
|
||
| 2.4 | 生成点管理 API | - 创建、列表、更新、删除生成点<br>- 关联模板和模型校验<br>- 参考文件上传处理<br>- 支持 `order` 字段（用于排序） | 24 | P0 | 2.2, 2.3 | 生成点可标注 |
|
||
| 2.5 | 生成点顺序管理 | - 提供批量更新接口（接收生成点ID列表顺序）<br>- 前端拖拽排序时调用此接口 | 8 | P1 | 2.4 | 排序功能可用 |
|
||
|
||
## 阶段三：异步任务与 AI 集成 (第6~7周)
|
||
|
||
| ID | 任务 | 子任务 | 工时(h) | 优先级 | 依赖 | 里程碑 |
|
||
|----|------|--------|---------|--------|------|--------|
|
||
| 3.1 | AI 调用适配器 | - 设计工厂模式，支持 openai, azure, custom<br>- 实现各供应商的请求构建和响应解析<br>- 编写异步调用函数（httpx）<br>- 支持超时、重试配置 | 32 | P0 | 2.2 | 可成功调用不同模型 |
|
||
| 3.2 | 参考文件解析器 | - 实现提取 .txt, .docx, .pdf 文本内容的功能<br>- 使用 python-docx, PyPDF2 等库 | 16 | P0 | 1.4 | 提取文本成功 |
|
||
| 3.3 | Celery 任务定义 | - **3.3.1** Celery 配置与连接（4h）<br>- **3.3.2** 任务函数骨架（加载模板、获取生成点，按 order 排序）（8h）<br>- **3.3.3** 参考文件解析集成（4h）<br>- **3.3.4** AI 调用与结果插入（基于偏移量或 XPath）（12h）<br>- **3.3.5** 文档保存（docx）与状态更新（8h）<br>- **3.3.6** 异常处理与重试逻辑（12h）<br>**合计** | 48 | P0 | 3.1, 3.2, 2.3, 2.4, 2.5 | 可端到端生成文档 |
|
||
| 3.4 | 任务管理 API | - 触发生成任务接口（创建 task 记录，启动 Celery）<br>- 查询任务状态（含进度百分比）<br>- 下载结果接口（支持 docx 和 pdf）<br>- 取消任务接口（可选） | 20 | P0 | 3.3 | 任务管理可用 |
|
||
| 3.5 | 单个生成点测试功能 | - 提供 API 允许用户测试单个生成点（不保存文档）<br>- 返回 AI 生成结果预览（可返回纯文本或HTML）<br>- 前端在标注弹窗中增加“测试”按钮，展示结果 | 16 | P1 | 3.1, 3.2 | 单点测试可用 |
|
||
|
||
## 阶段四：前端开发 (第5~9周，与后端并行)
|
||
|
||
| ID | 任务 | 子任务 | 工时(h) | 优先级 | 依赖 | 里程碑 |
|
||
|----|------|--------|---------|--------|------|--------|
|
||
| 4.1 | 页面路由与布局 | - 使用 React Router 定义路由（/templates, /editor/:id, /models, /tasks, /settings）<br>- 整体布局（侧边栏 + 内容区） | 12 | P0 | 1.2 | 框架搭建 |
|
||
| 4.2 | 模型管理页面 | - 列表展示（表格 + 分页）<br>- 新建/编辑弹窗表单（含供应商、API Key、扩展参数JSON编辑器）<br>- 启用/禁用开关<br>- 删除确认<br>- 设置全局默认模型（单选按钮） | 24 | P0 | 2.2 | 模型管理交互完整 |
|
||
| 4.3 | 模板列表与上传 | - 列表页面（卡片或表格，含名称、创建时间、操作按钮）<br>- 上传文件组件（支持拖拽，仅 .docx）<br>- 点击“编辑”跳转到编辑器页 | 16 | P0 | 2.3 | 可上传和查看模板 |
|
||
| 4.4 | 模板编辑器（核心） | **拆解为以下子任务**：<br>- **4.4.1** 集成 TinyMCE，加载 HTML 内容，保存时调用更新接口（8h）<br>- **4.4.2** 实现选区监听与高亮标注（监听 mouseup，显示浮动按钮“设为AI生成点”）（12h）<br>- **4.4.3** 生成点弹窗表单：提示词、参考文件上传（拖拽）、模型下拉（独立选择），并集成“测试”按钮（调用3.5）（16h）<br>- **4.4.4** 生成点列表（右侧面板），显示每个点的摘要，支持删除、编辑（修改弹窗）（8h）<br>- **4.4.5** 标注区域与实际选区偏移量同步（确保插入位置准确）（4h）<br>- **4.4.6** 支持拖拽排序生成点（使用 react-beautiful-dnd 等），更新顺序（4h）<br>**合计** | 52 | P0 | 4.3, 2.4, 4.2, 3.5, 2.5 | 可编辑并标注 |
|
||
| 4.5 | 生成任务执行与监控 | - 页面内“生成文档”按钮（可放在编辑器底部或工具栏）<br>- 弹出确认框，显示所有生成点列表（可勾选跳过个别）<br>- 提交后显示任务进度条（轮询状态，含进度百分比）<br>- 完成后自动显示下载按钮（支持 docx 和 pdf 格式切换） | 28 | P0 | 3.4 | 完整生成流程 |
|
||
| 4.6 | 任务历史页面 | - 表格列出所有任务（模板名称、状态、开始/完成时间）<br>- 状态为“已完成”的可以下载（格式选择）<br>- 状态为“进行中”的显示进度，可取消（可选） | 16 | P1 | 3.4 | 任务可追溯 |
|
||
| 4.7 | 系统设置页面 | - 展示可编辑的系统配置（全局默认模型、最大并发数、超时时间等）<br>- 调用后端接口读写 system_config | 12 | P1 | 2.2 | 设置可用 |
|
||
|
||
## 阶段五：测试与优化 (第10~11周)
|
||
|
||
| ID | 任务 | 子任务 | 工时(h) | 优先级 | 依赖 | 里程碑 |
|
||
|----|------|--------|---------|--------|------|--------|
|
||
| 5.1 | 集成测试 | - 端到端测试（上传 → 标注（含拖拽排序）→ 单点测试 → 生成 → 下载）<br>- 测试不同供应商模型调用<br>- 测试参考文件多种格式（txt, docx, pdf）<br>- 测试导出 PDF 功能<br>- 异常场景（网络超时、文件损坏、AI 返回错误） | 48 | P0 | 所有前序 | 功能稳定 |
|
||
| 5.2 | 性能调优 | - 优化大文档转换速度（异步处理）<br>- 数据库查询添加索引（template_id, status）<br>- 调整 Celery 并发参数<br>- 优化前端渲染（虚拟列表等） | 16 | P1 | 5.1 | 响应达标 |
|
||
| 5.3 | 安全加固 | - 检查 API Key 加密流程<br>- 文件上传类型和大小限制（限制50MB）<br>- 添加 CORS 配置<br>- 输入校验（防止 XSS） | 8 | P0 | 5.1 | 安全合规 |
|
||
| 5.4 | 文档编写 | - 用户手册（操作指南，含截图）<br>- 部署文档（Docker 详细步骤）<br>- API 文档（由 FastAPI 自动生成，补充说明） | 24 | P1 | - | 交付文档完整 |
|
||
|
||
## 阶段六：部署上线 (第12周)
|
||
|
||
| ID | 任务 | 子任务 | 工时(h) | 优先级 | 依赖 | 里程碑 |
|
||
|----|------|--------|---------|--------|------|--------|
|
||
| 6.1 | Docker 化所有服务 | - 编写 Dockerfile（后端、前端、Celery）<br>- 编写 docker-compose.yml 整合所有服务（postgres, redis, backend, celery-worker, nginx） | 16 | P0 | 所有 | 可容器化运行 |
|
||
| 6.2 | 生产环境配置 | - 配置环境变量（数据库、Redis、密钥等）<br>- 配置 Nginx 反向代理（前端静态 + 后端 API 转发）<br>- 配置 SSL（可选） | 8 | P0 | 6.1 | 生产就绪 |
|
||
| 6.3 | 部署测试 | - 在测试服务器上部署，验证全部功能（含 PDF 导出） | 8 | P0 | 6.2 | 上线成功 |
|
||
|
||
## 里程碑总览
|
||
|
||
| 里程碑 | 预计完成时间 | 关键交付 |
|
||
|--------|--------------|----------|
|
||
| M1: 架构与数据库就绪 | 第2周末 | 需求文档、数据库设计、环境搭建、文件存储 |
|
||
| M2: 核心 API 完成 | 第5周末 | 模板、模型、生成点 CRUD 完成，文档转换与导出（含PDF） |
|
||
| M3: 异步生成能力 | 第7周末 | Celery 任务可端到端生成文档，单点测试可用 |
|
||
| M4: 前端完整交互 | 第9周末 | 所有页面可用（含拖拽排序、任务历史、系统设置），生成流程顺畅 |
|
||
| M5: 测试与稳定 | 第11周末 | 通过集成测试，性能优化，安全加固 |
|
||
| M6: 正式上线 | 第12周末 | Docker 部署，生产环境运行 |
|
||
|
||
## 总工时估算
|
||
|
||
- 开发：约 **468 人时**（按 8h/天 ≈ 58.5 人天）
|
||
- 含新增功能（单点测试、PDF导出、拖拽排序、系统设置）和细化拆分
|
||
- 测试与部署额外计入，总项目周期约 **12 周**（建议 4~5 人并行开发）
|
||
|
||
--- |