# 共同开发任务板

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

| 编号 | 模块 | 任务 | 负责人 | 状态 |
|---|---|---|---|---|
| T01 | 前端 | 验证 Vue 页面启动、补充截图 | 吉海燕 | 进行中（生产构建已通过；登录、账户设置与角色导航已合入，待浏览器 Cookie 联调） |
| 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 与来源展示 | 范涵宇 | 暂缓（已确定 DeepSeek，待明确恢复外部模型调用授权） |
| T09 | 实验 | 构建可核验问题集及评分规范 | 杨星萱 | 待办 |
| T10 | 工程 | 补充测试、Alembic、鉴权与部署 | 范涵宇（主）、全员 | 进行中（迁移、认证、CSRF 与自动化回归已完成；本机 pytest/Docker/部署验收待补） |

## 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`。