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 的调用层。没有宣称已完成前端集成或生产部署。