227 lines
17 KiB
Markdown
227 lines
17 KiB
Markdown
# 三人团队工作计划
|
||
|
||
> 项目：边疆红驿那拉提文旅智能问答系统 V1.0
|
||
> 周期：2026 年 10 月 16 日—11 月 14 日
|
||
> 本计划明确主责与交付边界；主责人对任务关闭负责，配合人对自身交付物负责。
|
||
|
||
## 一、成员职责与边界
|
||
|
||
| 成员 | 角色 | 主责范围 | 主要交付物 | 边界 |
|
||
|---|---|---|---|---|
|
||
| 范涵宇 | 后端、数据库与检索负责人 | FastAPI、PostgreSQL/pgvector、数据模型、检索、RAG、部署与后端测试 | 数据库表、API、检索服务、RAG 服务、运行/部署说明 | 数据库结构和 API 字段由其主责；变更前须通知吉海燕。不得将真实密钥提交到仓库。 |
|
||
| 吉海燕 | 前端与系统集成负责人 | Vue 页面、接口调用、交互体验、异常状态、浏览器验收、演示截图 | 问答、知识管理、来源更新、实验评估页面；接口联调记录 | 前端只能通过 `/api` 访问服务，不得直连数据库或保存服务端密钥。接口字段变化须先与范涵宇确认。 |
|
||
| 杨星萱 | 知识库、实验与文档负责人 | 资料收集/核验、来源登记、测试问题集、人工评分、项目与软著文档 | 可核验资料清单、审核规范、实验记录、使用说明、软著材料初稿 | 未审核资料不得进入正式检索。不得虚构来源、实验数据或结论；不直接修改数据库结构。 |
|
||
|
||
## 二、协作约定
|
||
|
||
1. `main` 只放稳定可演示版本；`dev` 是团队集成分支；每人从 `dev` 创建 `feat/<模块>-<描述>` 分支。
|
||
2. 每项工作先建 Gitea Issue，写明负责人、验收标准、分支名和预计完成日期；完成后提交合并请求。
|
||
3. 数据库结构、Pydantic Schema、`/api` 接口字段、Embedding 模型和实验口径属于公共边界，修改前须在 Issue 中说明并通知相关成员。
|
||
4. 范涵宇、杨星萱的合并请求由吉海燕审阅批准后才能合并到 `dev`；吉海燕自己的前端合并请求由 Codex 在本项目对话中审阅，只有收到明确的“批准合并”结论后才能合并。页面改动附截图；后端改动附测试命令和结果；数据库改动附迁移/初始化说明。
|
||
5. 知识条目必须保留标题、分类、正文、来源链接、采集日期、核验状态和核验说明。杨星萱审核后，范涵宇才可纳入正式检索索引。
|
||
|
||
## 三、开始工作前：所有成员照此执行
|
||
|
||
### 1. 首次拉取与分支
|
||
|
||
```powershell
|
||
git clone https://gitea.kronecker.cc/saint/border-red-post-nalati.git
|
||
cd border-red-post-nalati
|
||
git switch dev
|
||
git pull --ff-only origin dev
|
||
```
|
||
|
||
开始一个新任务前，先同步 `dev`，再创建自己的功能分支：
|
||
|
||
```powershell
|
||
git switch dev
|
||
git pull --ff-only origin dev
|
||
git switch -c feat/<模块>-<简短描述>
|
||
```
|
||
|
||
示例：`feat/frontend-knowledge-page`、`feat/backend-source-api`、`docs/knowledge-review-rule`。不要在 `main` 或共享 `dev` 上直接修改功能代码。
|
||
|
||
### 2. 每个任务必须留下的记录
|
||
|
||
1. 在 Gitea 建立 Issue：写清目标、负责人、验收条件、分支名和预计完成日期。
|
||
2. 开发完成后提交合并请求到 `dev`：说明改动文件、测试命令和结果；前端附截图，数据库附初始化/迁移说明。
|
||
3. 范涵宇、杨星萱的合并请求由吉海燕审阅并明确批准后才能合并；吉海燕自己的前端合并请求由 Codex 审阅，只有收到明确的“批准合并”结论后才能合并。发现问题在合并请求讨论中处理，不私下覆盖他人提交。
|
||
4. 合并后更新 `docs/TASKS.md` 的状态，并在 Issue 写明“已完成、阻塞原因或下一步”。
|
||
|
||
### 3. 公共边界速查
|
||
|
||
| 变更内容 | 发起人 | 必须通知 | 交付要求 |
|
||
|---|---|---|---|
|
||
| 数据库表、字段、迁移 | 范涵宇 | 吉海燕、杨星萱 | 字段说明、初始化或迁移方式、回滚说明 |
|
||
| `/api` 路径、请求/响应字段 | 范涵宇 | 吉海燕 | Pydantic Schema、请求示例、响应示例 |
|
||
| 前端页面字段和交互 | 吉海燕 | 范涵宇 | 页面截图、接口依赖、异常/空态说明 |
|
||
| 正式入库资料、审核规则 | 杨星萱 | 范涵宇 | 来源台账、核验结论、入库范围 |
|
||
| 实验问题、指标、评分规则 | 杨星萱 | 全员 | 问题集版本、评分表、实验配置 |
|
||
|
||
## 四、成员执行手册
|
||
|
||
### 范涵宇：后端、数据库与检索
|
||
|
||
**日常工作目录**：`backend/`、`docker-compose.yml`、数据库相关文档。
|
||
**对接对象**：接口字段先给吉海燕；可入库资料和审核状态由杨星萱确认。
|
||
|
||
#### 阶段 1 的第一天
|
||
|
||
1. 重启后启动 Docker Desktop，确认 `docker version` 同时显示 Client 和 Server。
|
||
2. 在仓库根目录执行 `docker compose up -d db`；用 `docker compose ps` 确认 `nalati-postgres` 为运行状态。
|
||
3. 进入 `backend/`，复制 `.env.example` 为 `.env`（若 `.env` 已存在则只检查，不覆盖），激活虚拟环境并运行 `uvicorn app.main:app --reload`。
|
||
4. 用浏览器或 PowerShell 验证：`GET /api/health`、`GET /api/knowledge`、`POST /api/knowledge`。
|
||
5. 将实际命令、接口响应、失败原因写入 T02/T03 的 Gitea Issue；数据库可用后通知吉海燕开展浏览器联调。
|
||
|
||
**阶段 1 交付物**：可启动的 PostgreSQL 容器、可默认启动的 FastAPI、知识新增与读取接口验收记录。
|
||
**验收**：重启后数据仍存在；`/docs` 能看到四个基础接口；前端可调用新增和列表接口。
|
||
|
||
#### 阶段 2：知识管理接口
|
||
|
||
1. 根据杨星萱确认的资料字段，设计 `sources`、`documents`、知识条目/审核相关表，不删除已有 `knowledge_items` 数据。
|
||
2. 使用 Pydantic 明确定义创建、查询、更新、审核输入输出；日期返回 ISO 8601，字段统一 `snake_case`。
|
||
3. 实现来源、文档、知识条目的增删改查与分页/筛选所需接口；接口变更先在 Issue 给出示例。
|
||
4. 为关键接口补充成功、参数错误、资料不存在三类验证；更新架构与接口文档。
|
||
|
||
**交给吉海燕**：稳定 API 路径、字段表和示例 JSON。
|
||
**交给杨星萱**：可填写/导入的字段清单与审核状态含义。
|
||
|
||
#### 阶段 3—4：检索与 RAG
|
||
|
||
1. 实现独立的关键词检索，返回文档 ID、片段、来源、排序分数和耗时。
|
||
2. 定义统一 Embedding Provider；记录模型名、版本和向量维度，禁止混用不同向量空间。
|
||
3. 建立 pgvector 向量存储与相似度检索；实现 RRF 混合排序，三种模式均可单独调用。
|
||
4. 接入大模型前先固定上下文格式和“知识不足时不确定回答”的提示词；回答保存引用来源和检索日志。
|
||
5. 将可复现实验配置、接口参数和日志导出方式交给杨星萱。
|
||
|
||
#### 阶段 5—7：稳定性、实验与发布
|
||
|
||
1. 修复联调问题，补充基础自动化测试、迁移方案和环境变量说明。
|
||
2. 为实验导出检索模式、命中条目、耗时、模型版本和调用成本；冻结实验期间的配置。
|
||
3. 发布前检查 `.env`、真实 API Key、测试数据和开发日志未进入 Git；提供可复现启动命令。
|
||
4. 与全员核对功能、截图、说明书一致后，准备 `v1.0.0` 发布内容。
|
||
|
||
### 吉海燕：前端与系统集成
|
||
|
||
**日常工作目录**：`frontend/`，重点为 `frontend/src/App.vue`、`frontend/src/api.ts`、`frontend/src/style.css`。
|
||
**对接对象**：只通过 `/api` 与范涵宇对接；接口字段变更未确认前不自行猜测后端行为。
|
||
|
||
#### 阶段 1 的第一天
|
||
|
||
```powershell
|
||
cd frontend
|
||
npm ci
|
||
npm run dev
|
||
```
|
||
|
||
1. 打开 `http://localhost:5173`，确认四个导航页可以切换，页面没有白屏或控制台构建错误。
|
||
2. 执行 `npm run build`，构建失败优先修复 TypeScript、Vue 模板或依赖问题。
|
||
3. 后端未启动时，确认界面明确显示“API 未连接/无法读取知识库”，不能伪装为成功数据。
|
||
4. 后端数据库联通后执行真实流程：新增知识、保存、刷新列表、重新打开页面确认数据仍在。
|
||
5. 截取问答页、知识管理页、来源与更新页、实验评估页的清晰截图，保留用于软著材料。
|
||
|
||
**阶段 1 交付物**：前端启动/构建记录、四页截图、知识新增与刷新联调记录。
|
||
**验收**：`npm run build` 通过；Vite 可访问；后端可用时完成“新增—刷新—保留”闭环。
|
||
|
||
#### 阶段 2：知识管理页面
|
||
|
||
1. 将所有 HTTP 请求集中在 `src/api.ts`，为知识条目、来源、审核状态定义 TypeScript 类型；禁止使用 `any` 掩盖接口变化。
|
||
2. 完成新增、列表、搜索、编辑、删除/撤销（以后端最终接口为准）、来源跳转与审核状态展示。
|
||
3. 设计空数据、加载中、保存成功、字段校验、网络失败、后端错误五类状态。
|
||
4. 新增字段先根据范涵宇提供的 Schema 修改 API 层，再修改页面；完成后附接口联调截图。
|
||
|
||
#### 阶段 3—4：检索与问答页面
|
||
|
||
1. 增加关键词、向量、混合检索模式选择；展示检索结果、排序、耗时与来源链接。
|
||
2. 问答页面展示用户问题、回答、引用来源、知识不足提示、加载中和网络错误。
|
||
3. 不把“待审核”资料显示为已核验依据；来源链接为空时不生成无效跳转。
|
||
4. 保持移动端/窄窗口可用；每个重要交互给出可重复操作步骤。
|
||
|
||
#### 阶段 5—7：集成、实验与交付
|
||
|
||
1. 完成四个页面的主流程、空态和错误态，按杨星萱的实验字段展示结果但不填写虚构数值。
|
||
2. 在每次后端变更后做回归：健康状态、知识管理、检索结果、问答来源。
|
||
3. 输出软著所需页面截图、演示流程和前端依赖/构建说明。
|
||
4. 发布前用干净环境执行 `npm ci && npm run build`，记录版本和构建结果。
|
||
|
||
### 杨星萱：知识库、实验与文档
|
||
|
||
**日常工作目录**：`docs/`、资料台账与实验记录；正式数据入库前先与范涵宇确认字段。
|
||
**对接对象**：向范涵宇提供已审核资料与字段；向吉海燕提供页面文案、来源呈现规则和实验展示字段。
|
||
|
||
#### 阶段 1 的第一天
|
||
|
||
1. 建立资料台账，每条资料至少包含：标题、类别、来源名称、URL、获取日期、正文摘要、真实性判断、核验日期、核验人、状态和备注。
|
||
2. 定义状态：`pending`（待核验）、`verified`（可正式使用）、`rejected`（不采用）；将判断标准写入 T04 对应 Issue。
|
||
3. 建立验收记录，记录每次联调的日期、人员、环境、操作、预期结果、实际结果和截图/日志位置。
|
||
4. 先收集资料，不把未经核验的网页内容直接当作那拉提事实写入系统。
|
||
|
||
**阶段 1 交付物**：资料台账模板、审核规则、联调验收记录模板。
|
||
**验收**：另外两位成员能按模板登记一条资料和一次测试结果，无歧义。
|
||
|
||
#### 阶段 2：资料与审核
|
||
|
||
1. 按红色文化、旅游资源、民宿服务、交通出行等分类收集 30—50 条候选资料。
|
||
2. 每条资料至少做一次来源核验；信息缺失、过期或来源不可靠时保持 `pending` 或标记 `rejected`。
|
||
3. 向范涵宇提供“已核验可入库”清单，向吉海燕提供来源展示所需名称、链接和状态文案。
|
||
4. 记录资料版本与更新时间，为后续向量重建和论文数据集说明保留依据。
|
||
|
||
#### 阶段 3—4：测试集、来源核验与案例
|
||
|
||
1. 编写 20—30 个覆盖四类主题的测试问题；每题记录预期知识点、允许引用来源和“资料不足”情形。
|
||
2. 对关键词、向量、混合检索的结果检查是否命中正确资料，记录错误类型而非只写“好/不好”。
|
||
3. 对 RAG 回答核对“回答是否正确”和“来源是否真正支持回答”，整理成功案例与失败案例。
|
||
4. 任何实验分数必须来自实际运行、检索日志与人工评分，不得先写结论后补数据。
|
||
|
||
#### 阶段 5—7：文档、实验与软著
|
||
|
||
1. 编写用户手册：安装、启动、知识录入、审核、问答、来源查看和常见问题；与吉海燕截图逐一对应。
|
||
2. 制定评分表，统计 A（LLM-only）、B（关键词 RAG）、C（混合检索 RAG）的正确性、可追溯性、无依据回答、响应时间和成本。
|
||
3. 整理实验原始记录、统计结果、局限性和论文可用图表素材；不将原型功能描述为已实现功能。
|
||
4. 整理软著材料初稿，逐项与范涵宇代码、吉海燕页面和最终演示核对。
|
||
|
||
## 五、阶段工作与验收
|
||
|
||
| 阶段与时间 | 范涵宇：后端/数据库 | 吉海燕：前端/集成 | 杨星萱：知识库/实验/文档 | 阶段验收 |
|
||
|---|---|---|---|---|
|
||
| 阶段 1：环境联调（10/16—10/18） | 处理 Docker、WSL、PostgreSQL；验证建表、`/api/health`、知识新增/读取 | 启动 Vue，验证 API 连接和“新增知识—列表刷新”流程，补浏览器截图 | 建立资料登记模板、审核状态定义和验收记录模板 | 浏览器端可新增知识，刷新后数据仍存在；团队成员可按 README 启动 |
|
||
| 阶段 2：知识管理（10/19—10/23） | 设计并实现来源、文档、知识条目和审核相关表/API | 完成知识新增、列表、编辑、来源和审核状态页面 | 收集并登记首批 30—50 条可核验资料，完成初步分类与来源核验 | 可管理、查询并追溯首批知识；未审核条目有明确状态 |
|
||
| 阶段 3：关键词、向量与混合检索（10/24—10/29） | 实现关键词检索、Embedding Provider、pgvector 检索和 RRF 融合；记录排序与耗时 | 增加检索模式选择、检索结果/来源/耗时展示 | 编写 20—30 个测试问题，标注问题类别、期望证据与答案要点 | 同一问题能比较关键词、向量、混合三种模式，结果可复现 |
|
||
| 阶段 4：RAG 问答与来源追溯（10/30—11/3） | 接入 LLM API，完成上下文组装、提示词、知识不足提示、问答与检索日志 | 完成问答历史、引用来源卡片、加载和错误状态 | 审核回答是否受来源支持，整理正反例与失败案例 | 系统回答带来源；资料不足时不作确定性编造 |
|
||
| 阶段 5：前端完善与系统集成（11/4—11/7） | 修复接口问题，补基础自动化测试，整理配置和启动说明 | 完成四个页面的主要流程、空态、错误提示和演示路径 | 编写用户操作说明、接口验收清单和知识维护说明 | 可在浏览器完成“录入—审核—检索—问答—查看来源”主流程 |
|
||
| 阶段 6：实验与系统测试（11/8—11/11） | 固定模型/检索配置，导出检索、耗时与调用日志，修复重大缺陷 | 支持实验结果导入/展示，完成跨浏览器回归测试 | 主导 A/B/C 对照实验、人工评分、统计和案例分析 | 真实记录 LLM-only、关键词 RAG、混合检索 RAG 的正确性、可追溯性、响应时间和成本 |
|
||
| 阶段 7：软著材料与 V1.0 发布（11/12—11/14） | 清理源码、依赖、配置与部署脚本；准备发布版本 | 整理页面截图、演示流程和前端构建产物说明 | 完成用户手册、软著材料初稿、实验与资料归档 | 代码、文档、截图和实际功能一致；经全员核验后创建 `v1.0.0` 标签 |
|
||
|
||
## 六、各成员持续工作清单
|
||
|
||
### 范涵宇
|
||
|
||
- 维护后端代码质量、数据库连接和接口文档。
|
||
- 每次 API 或数据库变更后，在 Issue 中给出请求示例、响应示例和启动/迁移方式。
|
||
- 保证关键词、向量、混合检索可独立调用，并保留检索日志。
|
||
- 管理服务端环境变量，绝不提交 `.env`、API Key 或数据库真实密码。
|
||
|
||
### 吉海燕
|
||
|
||
- 所有前端请求集中在 `frontend/src/api.ts`，不在页面中散落重复请求逻辑。
|
||
- 每个后端功能完成后进行浏览器联调，记录成功、异常和空数据状态。
|
||
- 为知识管理、问答来源、实验页面保留可用于软著的清晰截图。
|
||
- 每次页面改动在合并请求中说明访问路径、测试步骤和截图。
|
||
|
||
### 杨星萱
|
||
|
||
- 建立资料来源台账，至少记录来源名称、URL、获取日期、类别、真实性判断和核验人。
|
||
- 制定“可入库/待核验/不采用”的审核规则；不确定的资料保持待核验。
|
||
- 建立测试问题集和人工评分表，实验结果必须能回溯到测试问题、检索日志和评分记录。
|
||
- 维护项目说明、用户手册、软著材料和论文实验素材，确保表述不超出系统实际功能。
|
||
|
||
## 七、完成判定
|
||
|
||
一个任务只有同时满足以下条件才能标记完成：
|
||
|
||
1. 代码或资料已进入相应分支，并有可追溯的提交和 Issue。
|
||
2. 有明确的验收步骤、测试结果或可核验资料。
|
||
3. 公共接口、文档和任务状态已同步更新。
|
||
4. 无真实密钥、个人隐私数据和未经授权的材料。
|
||
5. 合并请求按既定审阅权限获批后合入 `dev`；阶段验收并经吉海燕确认后再合入 `main`。
|