border-red-post-nalati/docs/TEAM_WORKPLAN.md

三人团队工作计划

项目：边疆红驿那拉提文旅智能问答系统 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. 首次拉取与分支

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，再创建自己的功能分支：

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 的第一天

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。