From 3c7b0a3a5e03765686a8dccaedb9a707b9e762c3 Mon Sep 17 00:00:00 2001
From: jhy <184825448@qq.com>
Date: Thu, 15 Oct 2026 17:25:08 +0800
Subject: [PATCH] docs: sync team execution guide

---
 docs/TEAM_WORKPLAN.md | 166 +++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 163 insertions(+), 3 deletions(-)

diff --git a/docs/TEAM_WORKPLAN.md b/docs/TEAM_WORKPLAN.md
index 96d7d01..e97b955 100644
--- a/docs/TEAM_WORKPLAN.md
+++ b/docs/TEAM_WORKPLAN.md
@@ -20,7 +20,167 @@
 4. 合并请求至少由一名非作者审查。页面改动附截图；后端改动附测试命令和结果；数据库改动附迁移/初始化说明。
 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. 由非作者成员审查；发现问题在合并请求讨论中处理，不私下覆盖他人提交。
+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. 整理软著材料初稿，逐项与范涵宇代码、吉海燕页面和最终演示核对。
+
+## 五、阶段工作与验收
 
 | 阶段与时间 | 范涵宇：后端/数据库 | 吉海燕：前端/集成 | 杨星萱：知识库/实验/文档 | 阶段验收 |
 |---|---|---|---|---|
@@ -32,7 +192,7 @@
 | 阶段 6：实验与系统测试（11/8—11/11） | 固定模型/检索配置，导出检索、耗时与调用日志，修复重大缺陷 | 支持实验结果导入/展示，完成跨浏览器回归测试 | 主导 A/B/C 对照实验、人工评分、统计和案例分析 | 真实记录 LLM-only、关键词 RAG、混合检索 RAG 的正确性、可追溯性、响应时间和成本 |
 | 阶段 7：软著材料与 V1.0 发布（11/12—11/14） | 清理源码、依赖、配置与部署脚本；准备发布版本 | 整理页面截图、演示流程和前端构建产物说明 | 完成用户手册、软著材料初稿、实验与资料归档 | 代码、文档、截图和实际功能一致；经全员核验后创建 `v1.0.0` 标签 |
 
-## 四、各成员持续工作清单
+## 六、各成员持续工作清单
 
 ### 范涵宇
 
@@ -55,7 +215,7 @@
 - 建立测试问题集和人工评分表，实验结果必须能回溯到测试问题、检索日志和评分记录。
 - 维护项目说明、用户手册、软著材料和论文实验素材，确保表述不超出系统实际功能。
 
-## 五、完成判定
+## 七、完成判定
 
 一个任务只有同时满足以下条件才能标记完成：