历阶 Helix-α 冲刺 Day5

目录

一、站立式会议

会议照片

二、项目燃尽图

三、昨日至今进展总览

• Day4 已完成用户记忆接入、排期交互和甘特图基础操作。今天围绕“复习闭环、正文读入和页面交互收口”继续推进，使系统从“能安排学习任务”进一步具备“能按遗忘规律复习、读取真实资料并完成交互验收”的能力。
  • FSRS 复习调度：接入独立 Python py-fsrs 服务，实现复习评分、下一次复习日计算和 FSRS 状态持久化；补充复习重新做题流程，将题目判分结果关联到 Good/Again 等评分；FSRS 服务异常时进入“待计算”状态，避免复习结果丢失；到期复习任务自动排在今日列表第一条；复习接口增加幂等提交处理，重复提交不会重复计算或重复更新复习记录。
  • 记忆与对话持久化：完成聊天记录 localStorage 持久化，使用 helix_chat_history 保存最多 30 轮对话，刷新页面后历史记录和 compact 摘要不会丢失；Mem0 写入端只接收用户原话，不再将助手回复写入记忆，并过滤存量助手视角记录，减少错误记忆污染。
  • 复习规则与数据迁移：实现复习日由服务端统一计算，前端不能直接修改复习状态和复习日期；普通学习任务仍支持手动改期，FSRS 复习任务保持只读；补齐 _setup/migrate.sql 中的 Day5 字段，包括 subtasks.review_count、task_traces.review_date、familiar_count、fuzzy_count、pending_count 和 summary，并完成全新数据库初始化验证。
  • 正文检索与读入：在 Tavily 真实链接检索基础上接入 readers FastAPI 服务，使用 trafilatura 提取网页正文，并提供标题兜底；Web 侧新增正文读入客户端，检索结果可并行读入正文；正文达到最低长度后写入 body_ready/body_ref，过短或无法读取的内容按规则排除；readers 服务不可用时保留真实链接并进入降级流程，不报错、不编造正文。
  • 前端交互收口：修复今日面板步骤详情弹窗按钮回调，补充练习、跳转详情和复制提示词功能；增加 AI 讲解卡片提示词全文预览并抽取共享提示词模板；甘特图新增按计划筛选和普通任务跨周、跨月改期；详情弹窗、任务详情页和今日面板统一隐藏 FSRS 复习任务的改期入口；修复预览草稿与正式计划步骤 id 冲突导致的 React key 警告，并调整复习提示文案。
  • 布局与导航收口：修复任务详情页和今日看板两栏右栏被左栏滚动绑架的问题，右栏改为独立滚动；修复任务列表 L1–L6 标签与统计行重叠；今日面板未来复习日按复习日归组置顶，新增「待复习」状态筛选并调整默认筛选；修复今日面板/天梯跳转任务详情的弹窗残留，详情页自动定位并高亮目标步骤。
  • 测试与验证：完成 FSRS 正常评分、固定日期、非法评分、缺少时区、服务异常和重复提交测试；完成数据库全新初始化和生产构建验证；完成正文在线读入、正文落库、readers 服务停机降级、TypeScript 检查和 ESLint 验证；完成详情弹窗、甘特筛选、跨周改期、复习任务只读入口、右栏独立滚动、标签间距、待复习筛选和步骤定位的浏览器验收。
  • 代码签入：FSRS 及数据库修复提交 47ec79f、7cb1e9b；正文读入及分析链路提交 ce58111、87e05c2；前端交互收口提交 c125c2a、布局与导航修复提交 df943cb，相关代码已推送至团队仓库 dev 分支。
  • 约定保持不变：API Key 和其他密钥不进入 Git；各服务使用本地环境变量配置并在启动后验证；复习状态和复习日期由服务端及 FSRS 服务统一管理，前端只负责展示和提交复习结果。

四、成员进展

AI 技术员工作记录

五、代码签入与测试结果记录

代码签入记录

提交记录截图：

工作项（Issue）

工作项列表：https://devcloud.cn-north-4.huaweicloud.com/projectman/scrum/08ad145e89cd43d89513e75bf09dd94e/workitem/backlog

工作项列表截图：

测试等其他工作结果

2026-10-27 对 web 工程做了一轮功能测试。测试环境：本地 npm run dev（localhost:3000），访客演示模式（未登录，前端回退 mock 数据），Chrome 浏览器，视口 1440×900。本轮共发现 7 个问题，分别位于历史与成就导入存档、笔记库账号隔离、AI 助手对话持久化、登录态改期状态同步、任务列表完成/归档筛选、演示日期口径和刷新首帧身份。

问题一（中优先级，功能缺陷）：点击「导入存档」按钮后跳转到「AI 助手」页

冲刺归属：Day 2 视图搭建阶段遗留的占位实现。按钮保留了原型的 data-action="act-import" 标识，但 onClick 被写成 router.push('/app?view=studio')，没有实现原型的 importData()；旁边的「导出 JSON」「分享路径」「重置演示数据」都已接真实处理函数，唯独「导入存档」是静默跳转占位，AI 助手页也没有粘贴存档的导入入口。

复现与表现：进入「历史与成就」→ 右侧「数据」面板 → 点击「导入存档」，没有文件选择框，页面直接跳到 AI 助手，导入流程无法开始。

修复建议：参照原型 importData() 动态创建 <input type="file" accept=".json,application/json"> 并触发选择，读取文件后 JSON.parse 校验并合并进当前状态（未登录走本地存储，登录态调用后端导入接口），成功/失败分别 toast「已导入 N 单计划，进度已接上」/「导入失败：文件不是合法的 JSON 存档」；演示模式至少应弹出文件选择并提示「当前为演示模式」，不要静默跳转。修复后按「导出 JSON → 重置演示数据 → 导入存档」走完整闭环，确认计划、进度和关键词都能还原。

问题二（高优先级，数据隔离缺陷）：新用户登录后笔记库显示访客遗留内容

冲刺归属：Day 4 用户记忆的账号隔离遗漏。Day 4 已要求「记忆按账号隔离」，但隔离只覆盖 Mem0 记忆和计划数据，没有覆盖笔记存储；Day 5 的 FSRS 复习闭环依赖正确的账号数据，本问题会继续污染后续统计。

复现与表现：访客状态记若干笔记 → 退出并注册/登录一个全新用户 → 进入笔记库，看到的仍是访客和演示笔记，刷新、重新登录都不变。

根因：笔记尚未接后端，notesStore.ts 使用全局固定键 helix-notes，键里不带用户标识；登录/登出流程没有清空或切换该键，服务端首帧还用 seed 演示笔记兜底。计划数据在登录后会切到后端按用户隔离，笔记连这个切换都没有，这就是「新用户看到别人笔记」的完整链路。

修复建议：短期把存储键按身份区分（如 helix-notes:<userId>），ensureNotesLoaded() 增加用户参数，登录/登出时重新加载；至少要在登录成功时清掉访客遗留并提示「已进入个人空间」。中期把笔记接入后端，与计划数据同套路。修复后按「访客记笔记 → 登录新用户看笔记库 → 退出回访客态」三个状态回归，确认三个视图互不串数据。

问题三（中优先级，功能缺陷）：AI 助手对话记录切页或刷新后丢失

冲刺归属：Day 3 大模型接入时的会话持久化缺口；Day 4 的 Mem0 只负责长期记忆，不保存对话轮次。

复现与表现：在「自由对话」进行几轮对话，或用「新建计划」走一次七步分析生成草案 → 通过侧边栏跳到其他页面再返回，对话区恢复成初始状态，轮次、分析会话和草案全部消失，只剩欢迎语。

根因：对话历史只存在于 AI 助手的组件级 React state；工作台按 ?view= 每次只渲染一个页面组件，切页时 AiAssistant 整体卸载，切回时重新挂载，state 回到初始值。前后端都没有对话持久化作为兜底，历史唯一载体就是前端内存。

状态与修复：已修。Day5 提交 5f4d175 在 AiAssistant.tsx 增加 helix_chat_history 读写、懒加载、轮次变化写回、compact 摘要同步和最多 30 轮截断；本次复测刷新页面后两轮对话完整保留，第二次回复还能引用上一轮记下的复习习惯。

问题四（高优先级，功能缺陷）：登录态甘特拖拽改期提示成功但任务条不移动

冲刺归属：Day 2 接口骨架阶段的联调遗漏，出在前端 API 封装层对接口响应的拆包上。

复现与表现：以普通用户登录 → 进入甘特图 → 将任务条从 10月17日 拖到 10月16日 → toast 正常提示「已改期到 10月16日」，但任务条仍在 10月17日；刷新页面后任务条才出现在 10月16日，说明后端已改成功，只有当前页面没更新。

根因：后端 PATCH 返回 { subtask: {...} } 的包装结构，reviewSubtask 用 .then((data) => data.subtask) 正确拆包，patchSubtask 漏了这一步，直接把包装对象当步骤数据返回。markStep 拿到的 updated 是包装对象，date/completed/mastery 全部为 undefined，本地状态按回退值更新，所以 toast 成功但画面不动。影响面不止改期：登录态下打卡会「勾选状态不变、刷新后突然完成」，掌握度也会被临时显示为「未评估」。

修复建议：给 patchSubtask 补上与 reviewSubtask 相同的 .then((data) => data.subtask)；在 markStep 里对缺字段做防御，避免今后同类拆包错误再以「提示成功但画面不动」的形态出现。按「登录态拖拽改期 → 打卡 → 标记掌握度 → 复习评分」顺序回归，这几条都走同一个 markStep 通道。

问题五（中优先级，功能与交互缺陷）：「已完成」「已归档」页签空态文案错误，且完成态不可达

冲刺归属：Day 2 状态模型阶段的闭环遗漏。状态筛选器与空态文案属于 Day 2 视图组件交付范围，计划生命周期也在 Day 2 定义，但「计划如何到达完成态」这条业务路径一直没有落地。

复现与表现：以普通用户登录（名下有进行中的计划）→ 进入「我的任务」→ 依次点击「已完成」「已归档」，两个页签都显示与「全部」空态相同的「还没有计划」+「去 AI 助手新建」，用户明明有计划，引导方向也不对。

根因：两层问题叠加。文案层，TasksList.tsx 的空态对所有页签共用一套文案，只有搜索词才显示「没有匹配的计划」。闭环层，「已完成」筛选的是 status === 'done'，但全产品三处 patchTaskStatus 调用都只做「归档 ↔ 恢复」切换；后端 refreshTaskTrace 在步骤全部完成时也只更新统计表，不会把 tasks.status 置为 done。因此 done 是用户永远无法达到的状态，「已完成」页签永远是空的。

修复建议：空态按页签区分文案，「已完成」提示「把计划里所有台阶打卡完成后，在计划菜单里标记完成即可出现在这里」，「已归档」提示「还没有归档的计划」；补「标记计划完成」入口（patchTaskStatus 已支持 'done'），或在 refreshTaskTrace 检测 pendingCount === 0 时自动置为 done。按「全部打卡 → 出现在已完成 → 归档 → 出现在已归档 → 恢复 → 回到进行中」的生命周期回归。

问题六（中优先级，设计缺陷）：系统「今天」固定为 10月15日，与真实日期不符

冲刺归属：Day 1 任务规划阶段的设计遗留。原型期为与 seed 排期对齐，把「今天」固定为 2026-10-15，代码注释明确写着「P2 对接真实后端后改为真实日期」；Day 5 后端与 FSRS 已上线，这笔迁移仍未兑现。

复现与表现：打开今日看板、甘特图、历史与成就等日期敏感页面，页面顶部、「今天」高亮列、打卡日期都把 10月15日 当作今天，而真实日期已是 10月27日；登录用户还会看到 10/15 的展示轴与 FSRS 按真实时钟排出的未来复习日同屏并存。

根因：dates.ts 的 export const today = '2026-10-15' 被全项目 23 处文件直接 import，包括今日看板分组、甘特图周视图与落点守卫、天梯与历史页的「本周」口径，甚至服务端 AI 草稿排期也拿它当当前日期；而 Day5 的 FSRS 在服务端用 new Date() 计算复习日，形成双时间轴冲突。访客演示固定日期本身合理，问题在登录态没有按注释承诺切换到真实日期，且演示模式没有「演示时间轴」声明。

修复建议：未登录保留固定演示轴，在顶栏或甘特图标题旁加「演示时间轴 · 基准日 10月15日」标识；登录态把 today 从常量改为 todayOf(isGuest)（或经 SessionProvider 注入），访客返回固定值、登录返回 iso(new Date())，weekStart/weekDays 同步参数化；服务端 AI 草稿与 analyze 排期一并改用真实时钟；seed 排期按真实今天相对偏移重新生成，或接受登录态显示为历史数据。按「登录看板/甘特高亮 → 打卡时间戳 → FSRS 复习日 → 访客演示轴」顺序回归。

问题七（低优先级，交互缺陷）：登录用户刷新瞬间闪现访客演示态「林知」

冲刺归属：Day 2 会话链路的遗留。账号会话接口在 Day 2 交付，但「服务端首帧注入真实会话」没有做，会话校验只发生在客户端 effect 里。

复现与表现：以普通用户登录 → 停留任意页面 → F5 刷新，刷新后的短暂瞬间顶栏显示演示用户「林知」+「访客空间」，数据区也先渲染一份演示计划，随后才跳成登录用户自己的内容；每次刷新都复现。

根因：顶栏首帧用 fallbackUser() 取 seedState.user（林知），目的是保证 SSR/CSR 一致、避免 hydration 不匹配；真实身份在 useEffect 请求 /api/auth/me 返回后才覆盖。数据层的 useAppData 首帧同样以 seed 演示计划渲染，等接口返回后才替换，于是「演示身份 + 演示数据」一起闪。登录态最终会显示正确用户，只是闪现而非错误停留。

修复建议：正解是把会话判断提前到服务端——/app 本身是服务端组件且有 HttpOnly Cookie，可用 cookies() 读取会话并把真实用户作为 prop 传给 TopBar，客户端 /me 退化为兜底校准；数据层同理可把服务端已知 plans 首帧传入，或先显示骨架。短期可用「身份未确认前渲染中性占位（···）」而不是错误身份。注意不要用 useState 同步读 localStorage 缓存身份，SSR 阶段没有 localStorage，仍会引入 hydration 不匹配。按「登录刷新 N 次 → 无痕访客首帧 → 登录/退出切换」回归。

本轮 7 个问题中，问题三已随 Day5 5f4d175 修复；问题二和问题四涉及账号数据隔离与登录态状态同步，建议优先处理；其余问题已记录为后续迭代项。

六、程序/模块最新运行效果

以下截图取自本地运行的最新 dev 代码（演示日期固定为 2026-10-15）。为展示到期复习状态，演示数据将“两遍笔记对比复盘”的 FSRS 复习日调整为当天。

今日复习行

今日面板将到期复习任务置顶到“待复习 · 知识点重做”，展示复习日期、还糊 掌握状态和“重做练习后提交结果”入口。

复习重新做题与 FSRS 判定

复习任务先重做本知识点的 3 道练习题，按答对题数判定是否达标；通过后提示按 FSRS Good 更新掌握状态，未通过则按 Again 保留 还糊 并安排下一次复习。提交时由服务端统一计算复习日，前端只负责展示与提交结果。

复习任务详情与提示词预览

详情抽屉展示复习节点、掌握标记和完整学习提示词，可先通读再复制；复习任务不显示改期入口，改期只在甘特图对普通学习任务开放。抽屉内的“绑定资源”同时展示检索到的已核验真实链接及存活、权威、新鲜度三维信息。

甘特图计划筛选与 FSRS 复习日

甘特图支持按计划筛选；普通学习任务可拖拽或点选跨周改期，FSRS 复习日以独立复习条展示并保持只读，底部同步显示下一次复习日期。

AI 助手聊天记录刷新保留

聊天记录写入 helix_chat_history，刷新页面后历史对话和上下文仍然保留；第二张截图为刷新后的页面，两轮对话完整保留，且第二次回复能引用上一轮记下的复习习惯。

七、下一步计划

明天（Day6）将围绕“检索 + 正文读入 + 场景完善”继续推进：

1. 完善检索与正文读入链路：继续稳定 Tavily 检索和降级处理，接入 trafilatura 网页正文抽取以及 Docling 对 PDF、Word、PPT 的正文读取，将检索结果和正文材料统一接入四段分析流程，完善 body_ready、body_ref 等字段展示与落库。
2. 补齐真实使用场景：完善新建计划、检索结果为空、链接失效、正文过短、正文服务不可用等场景；增加检索结果去重、死链处理、正文读取超时和降级提示，确保系统不编造链接或正文，并支持用户查看已读入的正文材料。
3. 完成当日测试与冲刺记录：补充 Tavily 检索正常与降级、网页正文抽取、PDF/Word/PPT 读取、正文落库和服务异常测试；完成检索结果接入四段分析流水线的联调，修复发现的问题并发布 Day6 冲刺随笔，为 Day7 全链路联调和演示准备提供稳定版本。