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

# 共同开发任务板

> 实名分工见 [团队工作计划](TEAM_WORKPLAN.md)。每项任务仍须在 Gitea Issue 中补充预计完成时间、验收记录和关联合并请求。

| 编号 | 模块 | 任务 | 负责人 | 状态 |
|---|---|---|---|---|
| T01 | 前端 | 验证 Vue 页面启动、补充截图 | 吉海燕 | 进行中（生产构建及登录/角色/核心管理流程浏览器联调已通过；账户设置等剩余验收见下文） |
| T02 | 后端 | 验证 FastAPI `/docs`、`/api/health` | 范涵宇 | 已完成自动化/真实 HTTP 验证；待目标 Docker 环境复核 |
| T03 | 数据库 | 启动 PostgreSQL 并验证知识入库 | 范涵宇 | 已用隔离 PostgreSQL 完成迁移与回归；本机 Docker Compose 验收受阻 |
| T04 | 文档 | 明确接口字段、知识来源审核规则 | 杨星萱 | 待办 |
| T05 | 知识库 | 设计 sources/documents/chunks/version 表 | 范涵宇 | 已完成（迁移、发布快照和接口已合入；待 Docker 联调） |
| T06 | 检索 | 实现关键词检索基线 | 范涵宇 | 已完成（已核验知识 BM25 与检索历史已合入） |
| T07 | 向量 | 评估 Embedding 并实现 pgvector | 范涵宇 | 已完成（本地模型、精确向量和 RRF 已合入；待真实领域评测） |
| T08 | RAG | 集成 LLM 与来源展示 | 范涵宇 | 协议基础已合入（Responses 请求/解析调整已在独立分支通过验证，待审；生成模型选型与实际调用延期） |
| T09 | 实验 | 构建可核验问题集及评分规范 | 杨星萱 | 待办 |
| T10 | 工程 | 补充测试、Alembic、鉴权与部署 | 范涵宇（主）、全员 | 进行中（迁移、认证、CSRF、224项回归及浏览器核心流程已通过；Docker/HTTPS/部署待验收） |

## 2026-10-15 首次联调记录

- 已创建本机 `backend/.venv`（Python 3.12）并安装后端依赖；该目录由 Git 忽略。
- 已安装前端依赖，`npm run build` 通过。构建中发现并修复了问答来源 URL 可为 `null` 时的 TypeScript 类型不一致。
- 已使用临时 Uvicorn 服务（关闭数据库生命周期初始化）验证 `GET /api/health` 返回 `200` 和预期状态数据，验证后服务已关闭。
- 本机 Docker CLI 已安装，但 Docker Desktop 引擎无法启动，且 WSL 尚未处于可用状态。因此尚未执行 PostgreSQL 容器启动、知识条目新增/读取、默认生命周期启动和浏览器端联调。
- 后续操作：重启 Windows 后启动 Docker Desktop；确认 `docker version` 能显示 Server 信息，再在项目根目录运行 `docker compose up -d db`，随后继续 T02、T03 和 T01 的剩余验收。

## 2026-10-15 后端阶段 1–2 分支验收

分支：`feat/backend-knowledge-management`。以下为分支验收结果，须经既定审阅流程合入后再关闭任务；不覆盖前述其他环境的历史记录。

| 范围 | 已完成的验证 | 剩余事项 |
|---|---|---|
| T02 | 默认生命周期真实启动 Uvicorn；HTTP `/docs`、健康检查、数据库就绪检查通过 | 合并请求审阅、团队环境复核 |
| T03 | 真实 PostgreSQL 16 测试实例完成迁移、知识录入和读取；后端进程重启后数据仍可读取 | 当前主机 Docker 守护进程未运行，启动需管理员权限；Compose 容器与浏览器端联调待复核 |
| T05（阶段 2 范围） | 来源、文档、知识关联、版本、人工审核、软删除和历史快照；验证旧基础表迁移保留数据 | `chunks` 和索引版本留到检索阶段；字段与前端、资料负责人共同确认 |
| T10（部分） | Alembic 迁移、并发版本检查、PostgreSQL 自动化测试、启动说明 | 登录鉴权、限流、生产部署留到后续工程阶段 |

验证环境：Python 3.11；使用可选 `pgserver` 启动独立 PostgreSQL 16.2 测试实例并启用 pgvector。该方式用于验证 SQL 和接口，不等同于 Docker 容器验收。

实际命令与结果（在 `backend/` 执行）：

- `ruff check .`：通过。
- `ruff format --check .`：通过。
- `pytest -q`：22 passed；依赖库产生一条 TestClient 弃用提示，不影响本轮用例。
- 覆盖：新库迁移、已有基础表接管、重复升级、阶段 2 降级后基础正文保留、ORM 与迁移结构一致、审核前置条件、正文/来源/文档变更后重新审核、历史快照、软删除引用保护、筛选与分页、并发写入冲突、跨域预检、真实 HTTP 与服务重启持久化。

所有测试正文、来源和审核人均为占位数据，临时数据库不入库。当前问答仍是占位接口，未开展论文对照实验。Issue、合并请求和最终批准结论须补入 Gitea 后按团队规则归档。

## 2026-10-15 合并后续开发：关键词检索基线

- 阶段 2 后端功能已通过普通功能分支的 [PR #4](https://gitea.kronecker.cc/saint/border-red-post-nalati/pulls/4) 合入 `dev`（合并提交 `4d437ca`），包含测试客户端依赖修正。旧 AGit PR #2 仍打开，不作为该批功能是否已合入的唯一判据。
- 从最新 `dev` 创建 `feat/backend-keyword-retrieval`，推进 T06 的独立关键词接口与检索记录。T05 的持久化切分/索引版本、T07 的模型评估和向量检索仍待后续实现。
- 当前主机 Docker 服务仍未运行；本轮继续使用隔离 PostgreSQL 做接口与迁移测试，不把容器或浏览器端联调标记为完成。独立任务 Issue 仍须补齐。
- 新增检索接口、中文分词和 BM25 基线、有效审核筛选、原文片段、来源与版本、语料指纹及检索历史；前端调用层同步类型与接口，页面接入由前端继续联调。
- 分支验证：`ruff check .`、`ruff format --check .`、`pytest -q`；本轮 42 项 PostgreSQL/单元/真实 HTTP 测试通过，覆盖手算分数、标题权重、排序复现、审核边界、来源失效、容量拒绝、迁移兼容和服务重启后的检索历史。前端 `npm run build` 通过，包含新增检索调用类型的检查。全部使用占位资料，不是论文实验结果。

## 2026-10-16 Issue #5：认证与角色权限

- 按继续开发的授权，在 `feat/backend-auth-sessions` 推进 T10 的认证部分；叠加 PR #6（`8ac9dca`），不等待其合并，不自行批准或合并。PR #6 与本分支分别保持可追踪记录。
- 实现注册、登录、退出、当前会话、本人资料修改、改密及管理员用户列表；注册拒绝角色字段，知识/来源/文档管理及检索历史均由服务端要求 admin。
- 新增 `0004_auth_sessions`，保存 Argon2id 密码哈希、会话摘要与到期/凭据版本、共享认证请求预算；不预置用户，提供本机隐藏密码输入的管理员初始化命令。迁移和回滚保留知识及检索记录。
- 默认 Secure/HttpOnly/SameSite Cookie；写操作校验明确 Origin 及当前会话 CSRF。改密使所有旧会话失效，退出持久化撤销；参数错误不回显密码。字段、来源、CSRF 和前端交接见 [认证接口契约](AUTH_API.md)。
- 实际验证：`ruff check .`、`ruff format --check .` 通过；`pytest -q` **70 passed**，包含认证、授权、CSRF、输入越权、过期/轮换/撤销、限额、迁移及既有知识/检索回归；真实 HTTP 服务重启验证会话恢复和退出后不再有效。前端 `npm run build` 通过。
- 当前仍使用隔离 PostgreSQL 做自动化验证；Docker 容器、前端登录/角色页面及真实浏览器端流程仍待验收。远程 main 的注册原型最低密码提示需要按本契约同步到 15 字符，并接入带 Cookie/CSRF 的调用层。没有宣称已完成前端集成或生产部署。

## 2026-10-16 T05：持久化 chunks 与索引版本

- 分支 `feat/backend-chunk-index-versions` 叠加待审 PR #7（`f9827fe`），继承 #6；不等待合并继续后端阶段，同时保留各 PR 的审阅记录。
- 新增 `0005_chunk_indexes`：版本、原文切分及出处、发布状态单例、逐次发布记录。构建 ready 快照与发布分开，保留字符偏移、内容哈希、知识/来源/文档版本和语料指纹。
- 知识、来源、文档写入与构建/发布共用数据库行锁；目录修订与实际语料指纹一起决定当前性，旧构建/旧代数拒绝发布。构建或发布失败完整回滚，旧发布指针及历史不丢失。
- 管理接口统一要求 admin 与写入 CSRF；前端只同步类型和调用层，页面仍待联调。现有关键词基线行为不变，向量、ANN、RRF 与 RAG 未在本阶段实现。
- 实际验证：`ruff check .`、`ruff format --check .` 通过；`pytest -q` **91 passed**（隔离 PostgreSQL 16 + pgvector），包含真实锁竞争、失败构建/发布的数据库约束回滚、迁移保留账号/知识/检索记录、原文重建与来源快照、真实 HTTP 重启后的发布指针和 chunks 持久化。修正了发布时间在 UTC 与数据库时区之间表示不一致的问题，索引接口统一 UTC 输出。前端 `npm run build` 通过。
- 完整请求/响应、切分/容量、失效策略及回滚说明见 [INDEX_API.md](INDEX_API.md)。本阶段仍是有限语料的同步文本快照；Docker/浏览器验收、独立 T05 Issue 补建及后续 Embedding 方案选择仍有待完成。


## 2026-10-16 T07：合并后的 RRF 混合检索

- 本地模型评估和向量持久化/精确检索分别经 PR #11/#13 合入 `dev`；#9/#10 是被替代的旧 AGit 入口。读取已确认合并结果后，从最新 `dev` 创建 `feat/backend-rrf-retrieval`，遵循每阶段 PR 合并后才开发下一阶段。
- 新增公开 chunk 正文 BM25 与 RRF 接口，三种 chunk 模式限定同一文本快照及分类；原条目关键词接口保留独立口径。固定 k=60、等权、每路候选预算，记录两路完整候选排名/原始分数、贡献、模型空间、切分/BM25/分词参数与出处。前端仅同步调用与历史类型。
- 模型编码在发布锁外，完成后重新检查审核语料、文本/向量代数与空间；两路排序和记录保存受同一事务保护。竞争、模型或写入失败不保存部分混合结果；2000 chunks 容量与原向量阶段一致。没有新增数据库迁移。完整字段、比较口径及回滚见 [HYBRID_API.md](HYBRID_API.md)。
- 常规测试 `pytest -q` **180 passed, 1 skipped**（真实模型专项须显式启用）；新增 27 项覆盖手算排序/融合、候选截断/缺席/同分、相同粒度及分类、原文、历史、权限、编码期间锁释放和版本竞争、损坏/失效快照、失败回滚与容量。`ruff check`、`ruff format --check` 和前端 `npm run build` 通过。真实模型专项在独立 CPU 环境另执行 **1 passed**：固定 BGE small 经真实 HTTP 完成向量/混合/关键词 chunk 查询，进程重启后两路候选排名、结果和历史保持一致。首次专项请求因 candidate_k 小于默认 top_k 被按契约拒绝，修正测试请求后通过；未改变该输入约束。
- Issue #5 本轮复查无新评论，后端实现已合入，前端登录/CSRF/角色页面及浏览器流程仍待交接；Docker 容器、核验领域语料/问题集、正式模型冻结与领域评测同样未验收。所有新增自动化资料均为合成测试，不作为文旅事实或论文分数。下一阶段须等待本轮 PR 真正合入 `dev`。


## 2026-10-16 T08：证据与 OpenAI 兼容请求契约

- RRF 经 PR #14 真正合入 `dev` 并核对 head/merge 祖先关系后，从最新 `dev` 创建唯一阶段分支 `feat/backend-rag-context`。用户明确“模型先不急”，随后要求“先以OpenAI通用请求格式进行开发”；本轮完成协议和证据准备，不选择生成模型或发起真实调用。
- 新增管理员 `POST/GET /api/rag/contexts` 及详情接口，写操作沿用 Cookie/Origin/CSRF；只接受服务端 chunk 检索记录，复核当前审核语料、文本/向量发布、空间、原文及出处，持久化完整证据、排除原因、提示词版本、请求体与哈希。
- OpenAI 兼容 Chat Completions 请求构造支持明确的 model/messages、角色及输出预算字段；纯响应解析校验单候选、结束原因、引用编号和可选 token 用量。截断/拒绝/无引用等不作为有效答案；引用通过只表示结构候选，不表示事实已核验。
- 新增迁移 `0007_rag_contexts`，失败写入完整回滚，历史保留当时快照；回滚保留知识、账号、文本/向量发布和检索记录。当前 `/api/chat` 仍为原占位，准备结果固定 `prepared_request/model_called=false`。完整协议、字符预算与后续 token/模型边界见 [RAG_CONTEXT_API.md](RAG_CONTEXT_API.md)。
- 实际验证：`pytest -q` **224 passed, 1 skipped**；较上一阶段新增 43 项上下文/协议/权限/失效/预算/原文/失败回滚/真实 HTTP 重启用例，另新增 1 项上下文迁移降级保留数据验证。skip 为既有须显式启用的真实 Embedding 用例，本轮未重跑真实模型专项，不沿用旧结果冒充生成模型验证。`ruff check`、`ruff format --check` 通过。前端调用层同步，构建在补齐依赖后通过。
- PR #16 已合入的认证路由引用了 `vue-router`，原 package.json/锁文件未声明；本轮补充匹配现有 Vue 3 的 vue-router 4 依赖及锁记录，保留其他依赖原版本和平台元数据。前端 `npm run build` 通过；浏览器实际 Cookie/CSRF/角色及容器验收仍待完成。
- 本轮所有测试为协议/合成资料或坐标 fixture，没有真实生成模型请求、质量分数或费用。生成模型选择和服务凭据保持延期，不重复索要；本阶段提交 PR 后等待实际合入，再继续下一项可独立验收的后端任务。


## 2026-10-16 真实浏览器联调与阶段验收收尾

- 上下文阶段已通过真正 merged 的替代 PR #23 合入 dev；完整 backend 树及专用 RAG 契约/API 类型与原 #17 一致，通用文档保留集成更新，已记录重放等价依据。旧 #17 打开不阻塞后续阶段。
- 从最新 dev 创建 `test/backend-browser-acceptance`，用隔离 PostgreSQL16/pgvector、默认 FastAPI 生命周期、Vite 与真实浏览器走通管理员登录/刷新会话、来源/知识/文档录入、审核、文本与真实 BGE small 向量发布、RRF 原文来源展示，以及普通用户菜单/路由限制和退出。
- 修正页面联调发现的采集时间缺失、审核/文档导航入口和过期功能说明；后端审核/授权不放宽，不猜测历史资料采集时间。具体路径、HTTP 与浏览器证据分工及合成截图见 [BROWSER_ACCEPTANCE.md](BROWSER_ACCEPTANCE.md)。
- 独立 HTTP 检查确认匿名401、普通用户八类管理资源403、缺失CSRF/错误Origin403、退出后401；目录写入使旧发布409，重新发布后恢复真实检索；准备上下文仍为 model_called=false。合成数据和本机运行环境、原始记录、凭据不入库。
- 该轮验收收尾了T02的真实浏览器API连接、T05知识录入/审核与文本/向量页面核心流程、Issue #5登录/Cookie/CSRF/角色的主要浏览器路径。Docker、HTTPS、多浏览器、浏览器改密及历史元数据修订页面仍待验收；生成模型和领域评测继续延期。本轮 `pytest -q backend/tests` **224 passed, 1 skipped**，`ruff check`、`ruff format --check` 和前端 `npm run build` 均通过；常规 skip 为须显式启用的真实模型专项，本轮另外通过浏览器与独立 HTTP 实际运行了固定 BGE small。

## 2026-10-16 T07/T10：可复现历史导出

- 浏览器联调与录入修正经 [PR #29](https://gitea.kronecker.cc/saint/border-red-post-nalati/pulls/29) 真正合入 dev，已核对 head/merge 都在最新 dev 祖先链；再从最新 dev 创建唯一阶段分支 `feat/backend-retrieval-export`。
- 新增管理员/Origin/CSRF 保护的 `POST /api/retrieval/exports`，按明确 UUID 导出 JSONL，保留四模式原保存的查询、命中、原始分数、两路候选、模型/语料/切分参数、来源和耗时；可选择关联的准备上下文。条目与 chunk 粒度分开，生成模型使用量和费用为未采集，不伪造生成调用或实验分数。
- 一个 SQL 语句读取历史快照，保留旧版本而不重新检索；导出前完整校验，最多100条检索/100条上下文/8MiB，不静默截断，不返回部分文件。不新增数据库迁移或环境配置。
- 前端仅增加下载类型与调用层，复用 Cookie/CSRF/错误处理，不新增页面；真实浏览器下载与实验展示留给后续集成。完整字段、摘要核对、复现与回滚见 [RETRIEVAL_EXPORT_API.md](RETRIEVAL_EXPORT_API.md)。
- 专项测试 **30 passed**，包括真实 PostgreSQL 并发快照和 HTTP 重启导出；完整回归 **254 passed, 1 skipped**（skip 为须显式启用的真实 Embedding 专项），`ruff check` 与 `ruff format --check` 通过。前端会话下载契约 **3 passed**，类型与生产构建通过。测试使用合成资料与坐标 fixture，未重跑模型推理或调用生成模型。


## 2026-10-17 T08：Responses 协议调整

- 从最新 dev 创建独立 `feat/backend-responses-protocol`，不依赖待审的采集时间/浏览器 PR #44。新准备默认使用 Responses：固定 instructions 与 user input_text、max_output_tokens、非流式 output 解析；模型和真实服务接入继续延期。
- 新配置明确 protocol/provider_profile；提供 compatible、openai、deepseek、bailian 档案。DeepSeek 省略不受支持的 store，其他档案显式 store=false；百炼限制 temperature 小于2。旧 Chat Completions 参数拒绝，不自动探测、换协议或重试。档案通过离线契约验证，不代表已对真实供应商调用或通过全部模型能力验证。
- 解析区分 completed/incomplete/refused/failed，reasoning 不充当答案；拒绝工具、异常状态和错误引用。保存实际模型标识及可选输入/输出、缓存/推理 token 用量，不估算费用。字符预算仍不是模型 token 预算。
- 保留旧准备快照的完整配置、请求体、哈希与 JSONL 字节；两种协议可混合读取/导出。API路径与迁移不变，仍为0007；新请求使用 Responses，旧协议仅用于历史校验。字段、厂商差异、范围和回滚限制见 [RAG_CONTEXT_API.md](RAG_CONTEXT_API.md)。
- 本轮 `pytest -q backend/tests/test_rag.py backend/tests/test_exports.py` **113 passed**；完整 `pytest -q backend/tests` **294 passed, 1 skipped**。skip 为显式启用的真实 Embedding 专项，本轮不运行模型。ruff检查/格式检查及前端类型/生产构建通过；未修改页面交互，不宣称新增浏览器验收。