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

共同开发任务板

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

编号	模块	任务	负责人	状态
T01	前端	验证 Vue 页面启动、补充截图	吉海燕	进行中（生产构建已通过，待浏览器启动验证）
T02	后端	验证 FastAPI /docs、/api/health	范涵宇	进行中（/api/health 已通过，待数据库就绪后验证完整启动和 /docs）
T03	数据库	启动 PostgreSQL 并验证知识入库	范涵宇	受阻（Docker Desktop/WSL 引擎尚未就绪）
T04	文档	明确接口字段、知识来源审核规则	杨星萱	待办
T05	知识库	设计 sources/documents/chunks/version 表	范涵宇	待办
T06	检索	实现关键词检索基线	范涵宇	待办
T07	向量	评估 Embedding 并实现 pgvector	范涵宇	待办
T08	RAG	集成 LLM 与来源展示	范涵宇	待办
T09	实验	构建可核验问题集及评分规范	杨星萱	待办
T10	工程	补充测试、Alembic、鉴权与部署	范涵宇（主）、全员	待办

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 合入 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 和前端交接见 认证接口契约。
• 实际验证：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。本阶段仍是有限语料的同步文本快照；Docker/浏览器验收、独立 T05 Issue 补建及后续 Embedding 方案选择仍有待完成。

2026-10-16 T07：本地 Embedding 与资源评估

• 用户选择先评估本地开源模型与本机资源；从最新 dev 独立创建 feat/backend-local-embedding-evaluation，不依赖仍待审的 #6/#7/#8。

• 实现不在普通启动流程加载模型的 Provider、固定 revision 与空间身份、维度/有限数/L2 校验、真实 token 上限拒绝及独立 CPU 评估 CLI。可选依赖和模型缓存与默认后端环境分开。

• 固定 BGE small/base 中文模型，CPU 线程 2、batch 8、各输入形状预热一次后重复 5 次。单查询中位数分别 8.927/52.912 ms，独立进程峰值 RSS 531.2/865.5 MiB；两者实际运行、向量校验与超限拒绝通过。

• 项目资料台账目前只有占位行，本轮采用事先固定的 12 文本/10 问题合成样本，仅验证流程。small 的合成 Hit@1/Recall@3/MRR@3 为 0.90，base 为 1.00；不是实际文旅质量或论文结论，保留 small 的错误案例，不据此冻结正式默认模型。

• 固定配置、完整指标定义、输入哈希、复现命令和限制见 本地模型评估。原始运行报告、权重、虚拟环境只保存在本机 Git 元数据目录，不入库。

• 向量数据库/空间隔离、索引构建、向量/RRF 检索、真实已核验问题集和浏览器/部署验收仍待后续推进；本轮没有把这些标记为完成。

• 本独立分支实际验证：ruff check .、ruff format --check . 通过；pytest -q 49 passed，包含当前 dev 的 PostgreSQL/HTTP 基线与新增轻量契约/指标用例。small/base 另由独立模型环境真实执行；可选依赖在新建空环境中完成 CPU wheel 安装与后续依赖解析验证。先前 #7/#8 的 70/91 项结果属于各自分支，不混同为本独立分支的测试计数。

2026-10-16 T07：向量存储与精确检索集成

• 新分支 feat/backend-vector-retrieval 组合待审 #8 与 #9，继承 #7/#6，不等待合并、不覆盖其分支。已保留双方全部阶段文档，依赖组合基线为 bd0b738，本阶段差异从其后查看。
• 新增 0006_vectors：固定空间、向量版本、chunk 向量、向量状态与发布历史；复合外键限定文本版本/空间/维度，数据库检查实际维度及单位范数。迁移/降级保留目录、文本 chunks/发布、账号和检索日志。
• 仅对当前有效的文本发布构建完整向量快照。加载/编码不占目录发布锁，完成后重新核对审核指纹、修订、文本代数和 chunks；模型/token/数据库/竞争失败均不留下半成品。向量发布有独立乐观代数和历史，过期资料拒绝用于当前查询。
• 增加管理员构建/发布/空间/历史接口、公开精确余弦检索、keyword/vector 历史判别联合和前端类型调用层。运行离线优先、默认关闭、延迟加载，单进程编码忙时立即 503；最多 2000 chunks，不静默截断 token 或语料。
• 实际验证：常规 pytest -q 153 passed, 1 skipped；该 skip 是须显式启用的真实模型用例，另在独立 CPU 环境执行并 1 passed。真实固定 small 完成 HTTP 构建/发布、512 维 pgvector 入库、检索与后端进程重启后的指针/结果/历史一致。轻量测试使用坐标 fixture 验证 SQL、同宽/不同宽空间、版本竞争、锁外推理、失败回滚、权限和迁移，不冒充实际模型评测。ruff check、ruff format --check 与前端 npm run build 通过。
• 完整字段与运行/回滚步骤见 VECTOR_API.md。RRF、ANN、RAG、真实已核验领域问题集、Docker 容器与前端浏览器验收仍待后续推进，本轮不把合成文字测试当作领域质量结论。