README.UserAgentTest

目的

本文面向后续 User Agent / Reviewer。目标不是介绍产品，而是把当前主分支已落地的功能面改写成一份可顺序执行、可打勾、可中断续跑的回归脚本。

这份文档默认你验证的是“成功态、结束态、回显态、跨模块一致性是否成立”。不以报错、空态、缺数据态作为通过依据；如果出现这些情况，应先回到环境准备或实现回归排查，而不是把异常现象当成可接受结果。

环境前提

验收必须在已准备好的环境中执行，至少保证主后端可用。
需要一个可工作的 LLM 通道；涉及推荐、个股分析、交易复盘、资讯清洗时，应提前确认当前通道能成功返回结果。
验证本地模型链路时，应保证 Ollama 已安装，服务可启动，且已拉取至少一个可用模型。
验证财务链路时，应保证 Financial Worker 可用；至少要能通过健康检查，并能成功执行一次手动采集。
非 SQLite 数据库连接串不得把用户名、密码写进已提交的 appsettings*.json；本地验证请使用环境变量、用户机密或被忽略的本地配置文件，并在启动前确认 ConnectionStrings / Database:ConnectionString 中没有明文 Password、Pwd、User Id 或 Uid。
建议准备 2 到 3 只代表性的 A 股股票样本：
- 一个有较完整本地资讯与新闻影响数据的样本。
- 一个已存在交易计划或适合起草交易计划的样本。
- 一个适合验证财报采集与财务报表展示的样本。
建议准备至少一条可复用的 traceId 来源样本，通常来自 股票推荐 的 feed 或 股票信息 的 LLM 分析结果，便于回归 治理开发者模式。
如果要验证 批量清洗待处理，准备环境中应保留少量 IsAiProcessed = false 的资讯样本，避免按钮流程只能落到“无数据可处理”。
如果要验证 🔄 重置，应只在测试环境或网络拦截/mock 下执行；不要要求真实删除用户数据。
本次执行建议在纸面或临时记录里固定 4 个上下文：样本股票代码、管理员账号、当前主 Provider、至少一个 traceId。

统一执行标记

以下标记在每个模块里统一复用，默认都按保守口径执行，不把“可能还没回来”当通过：

入口点：从哪里进入，以及进入后先找哪几个固定文案确认自己在对的页面。
输入示例：可直接照填的股票代码、模型名、追问示例。
操作：明确到按钮、输入框、页签、是否需要返回上一步。
等待时间：统一口径建议为 立即 = 0-1 秒、短等 = 1-3 秒、中等 = 3-10 秒、长等 = 10-30 秒、轮询 = 每 2 秒检查 1 次，最多 3 次。
可见状态：必须看到的 UI 变化，例如 保存设置 -> 保存中... -> 成功提示、清洗中... 第 n 轮 -> 列表刷新。
超时判定：超过该时间仍未进入下一状态，就判定卡住，不继续空等。
重试策略：优先一次页面内重试，再一次切页重进；超过两次仍失败就停止堆重试。
失败分流：至少记录当前模块、股票代码、按钮最终状态、错误文案、时间点；涉及 LLM 时补记 traceId，再转治理页或日志排查。

公共错误脱敏验收：LLM、Stocks、SSE、状态响应的用户可见错误文案和公开 JSON 不得暴露第三方网关 URL、token、api_key 或 Authorization Bearer 原文。

公共白屏防护验收：任一业务页子组件抛错时，应用主框架不应整页白屏；应出现 页面组件已进入可恢复错误态 或等价可恢复提示，并保留浏览器 console/error 日志，允许点击重试或切换页签恢复。

公共顶部状态验收：右上角连接状态应在 45 秒左右反映后端断连/恢复，顶部时钟应带日期上下文，形如 04-27 14:05:33，不再只显示孤立时间。

建议按下面这种句式执行并打勾：

操作：点击 保存设置。等待时间：短等。可见状态：按钮从 保存设置 变为 保存中...，随后出现 ✅ 通道配置已保存...。超时判定：10 秒仍停在 保存中...。重试策略：刷新一次页面后再点一次。失败分流：记录 provider、模型、错误文案。

顶层模块矩阵

当前导航结构以 5 个主业务 Tab 为主：股票信息、情绪轮动、全量资讯库、交易日志、股票推荐。LLM 设置、治理开发者模式、财务数据测试、财务工作者监控 需要从右上角 ⚙ 管理设置 进入，不再作为固定顶层并列页签。

模块 / 页签	入口	本轮先看什么	异步重点	完成后立刻去哪里
股票信息	顶部页签 `股票信息`	`标的查询`、`专业图表终端`、侧栏 Tab	cache-first、图表、资讯、财报、交易计划	情绪轮动 / 交易日志 / 治理
情绪轮动	顶部页签 `情绪轮动`	市场阶段、`同步最新数据`、5/10/20 日窗口、数据审计面板	同步、窗口切换、板块详情	回股票信息看计划市场上下文
全量资讯库	顶部页签 `全量资讯库`	搜索、层级、情绪、`最近一次清洗结果`	批量清洗、继续/重开、请求响应详情、个股比对	回股票信息做一致性验证
交易日志	顶部页签 `交易日志`	`持仓总览`、`风险敞口`、`🧘 交易健康度`、`计划管理工作区`、`快速录入`	计划联动、录单保存、汇总刷新、AI 复盘、历史回显	回股票信息 / 计划卡核对
股票推荐	顶部页签 `股票推荐`	推荐前市场快照、历史推荐	SSE 首包、持续进度、结束态、追问	去治理开发者模式查 traceId
LLM 设置	右上角 `⚙ 管理设置` → `LLM 设置`	当前主渠道、编辑 Provider、新闻清洗渠道	保存即生效、Ollama 状态、测试连接	去股票推荐或股票信息做即刻验证
治理开发者模式	右上角 `⚙ 管理设置` → `治理开发者模式`	trace 检索、LLM 对话过程日志	trace 时间线、日志详情、Trace 跳转	反查推荐/个股分析链路
财务数据测试	右上角 `⚙ 管理设置` → `财务数据测试`	Worker 状态、采集配置、手动测试采集	手动采集、日志刷新	回股票信息 `财务报表`
财务工作者监控	管理设置 → 工作者	Worker 进程状态查看 / 启停控制	/api/stocks/financial/worker/*	回财务数据测试确认 Worker 一致

模块回归步骤

1. LLM 设置

入口点

操作：点击右上角 ⚙ 管理设置，选择 LLM 设置。定位锚点：页面内必须同时出现 当前主渠道、编辑 Provider、保存设置、新闻清洗渠道设置、🦙 Ollama 本地模型管理。等待时间：立即到 3 秒。超时判定：3 秒内仍停在登录态、空白或只剩 loading。重试策略：重新打开一次设置下拉并进入。

预置数据

准备一个当前已可用的 Provider，避免在回归中把唯一可用通道切坏。输入示例：远端模型可保留现有值；本地 Ollama 必须先启动并刷新出 已安装模型 列表，再从下拉里选择真实已安装项。失败分流：若不确定哪个 Provider 当前可用，先点 🔗 测试连接 再决定是否改动。

操作步骤

操作：查看 主渠道状态 与 当前主渠道 文案，确认页面加载的是当前真实生效通道，而不是默认占位。等待时间：立即。可见状态：当前主渠道：xxx 与 你正在编辑...保存后会立即生效 / 自动切换主渠道为该通道 提示同时可见。超时判定：3 秒内没有主渠道提示。
操作：在 编辑 Provider 下拉中选择要验证的通道；如是非 Ollama 通道，补齐 主 LLM API Key、Base URL、模型；如是 Ollama，确认 模型 已变成基于 已安装模型 的下拉，并自动落在某个真实已安装模型上，同时 模型常驻 (keep_alive) 的默认提示改为 5m，并明确 0 表示立即卸载，不再出现 -1（常驻）。若页面提示 当前未检测到已安装 Ollama 模型 或 请先到上方「🦙 Ollama 本地模型管理」启动并刷新 Ollama，则 保存设置 / 测试连接 应变灰不可点，并明确提示先去上方管理区拉取模型，不要继续保存。输入示例：远端可用 gpt-4o-mini；本地只选下拉里已安装项。等待时间：立即。可见状态：字段值切换后不丢失、不跳回旧 Provider。
操作：在 编辑 Provider 下拉中选择 Antigravity 或等价 Google 授权通道。等待时间：立即。可见状态：页面只显示 Google 授权登录状态和中性确认提示，不应出现 封号风险、非主力账号 这类恐吓式文案。
操作：先点击 🔗 测试连接。等待时间：远端通道 3-10 秒，本地 Ollama 通道 10-30 秒。可见状态：按钮 测试中...，然后出现 ✅ 成功或明确 ❌ 错误；如果 Ollama 当前没有可选已安装模型，按钮应直接保持禁用，并在当前区块提示先去上方 🦙 Ollama 本地模型管理 拉取模型，而不是继续请求；本地模型首次加载仍可能出现 ⏳ 请求超时 — 本地模型首次加载可能需要数分钟，请确认 Ollama 已运行。超时判定：远端 30 秒、本地 60 秒仍无结果。重试策略：仅重试 1 次；本地模型若仍超时，先去 Ollama 面板确认服务和模型。
操作：点击 保存设置。等待时间：1-3 秒。可见状态：按钮 保存设置 -> 保存中... -> 恢复可点，同时出现 ✅ 通道配置已保存，并已自动切换主渠道为「...」 或 ✅ 通道配置已保存，当前主渠道「...」已立即生效；如果当前是 Ollama 且页面未读到任何已安装模型，保存设置 应直接变灰不可点，并在当前区块提示先去上方 🦙 Ollama 本地模型管理 拉取模型，不接受“保存成功但模型其实未安装”的假成功态。超时判定：10 秒仍停留在 保存中...，或只有按钮恢复但没有成功/失败提示。重试策略：刷新一次后再保存一次。失败分流：记录 Provider、模型、错误文案。
操作：在 新闻清洗渠道设置 区修改 清洗渠道；如果选择的是 Ollama，确认 模型 也变成 已安装模型 下拉并自动落在某个真实已安装模型上；如果页面提示无已安装模型，则 保存 / 测试连接 应变灰不可点，并在当前区块明确提示先去上方 🦙 Ollama 本地模型管理 拉取模型，再返回本区继续操作。再设置 批次大小 (5-20) 并点击 保存。无论是直接选择 Ollama，还是 active -> ollama，有效批次都应支持 5-20；合法范围内的值保存后应原样回显，只有超出范围时才归一化到 5 或 20。等待时间：1-3 秒。可见状态：按钮 保存 -> 保存中... -> 恢复可点，旁边出现 ✅ 新闻清洗已改为跟随主渠道... 或 ✅ 新闻清洗渠道已切换为...；如果 Ollama 无已安装模型，不应继续发请求。超时判定：10 秒内无反馈。重试策略：仅重试 1 次；仍失败就不要继续做资讯清洗回归。
操作：进入 🦙 Ollama 本地模型管理。先看 服务状态，再按需点 ▶ 启动、⏹ 停止、🔄 刷新。等待时间：启动/停止 3-10 秒，刷新 1-3 秒。可见状态：状态在 未运行 / 启动中... / 运行中 / 停止中... / 未安装 之间变化，并且 ollamaMsg 给出明确反馈；如果机器上其实已经安装了 Ollama 但当前服务没跑，这里必须显示 未运行，同时保留 ▶ 启动 和 🔄 刷新 作为恢复入口，不能误报成 未安装 并展示安装引导；如果服务已运行但当前还没拉取模型，页面也应直接提示“服务已运行，但当前未检测到已拉取模型”，并引导用户去当前页下方 拉取模型 区域处理，而不是让用户误以为 Ollama 本体未安装。超时判定：10 秒后仍停在 启动中... 或 停止中...。重试策略：只重试一次 🔄 刷新；仍异常则停止本地模型相关验证。
操作：服务为 运行中 时，在 拉取模型 输入框填一个已有或准备拉取的模型名，点击 拉取。输入示例：gemma4:e4b。等待时间：长等，最多 30 秒先看是否进入 拉取中...，首次大模型拉取可再额外观察 1 次长等。可见状态：按钮 拉取 -> 拉取中...，随后 已安装模型 列表新增或刷新。超时判定：30 秒内没有任何进度文案或列表变化。重试策略：刷新一次状态；不要连续多次拉取同一模型。
操作：勾选 保持活跃（掉线自动重启），等待一次短观察。等待时间：3-10 秒。可见状态：勾选状态保留；若服务离线再刷新，应看到 检测到 Ollama 离线，自动重启中... 或保持 运行中。超时判定：勾选后立即掉回未勾选或服务持续 未运行。

等待与判定

主渠道保存链路以 10 秒为保守超时；超过 10 秒仍无成功或失败提示，就判定不收敛。
本地模型测试连接以 60 秒为保守上限；超过 60 秒仍只有转圈，不继续空等。
只要主渠道改动完成，1-3 秒内就应去下游页面做一次即时验证，不能只看本页成功提示就收工。

关键断言

保存设置 不只是写入配置，还会让 当前主渠道 立即变更或确认当前通道立即生效；若当前 Provider 是 Ollama，则必须来自 已安装模型 下拉，不能继续保留旧的手填失效模型。
新闻清洗渠道设置 保存后只影响清洗，不应改动主渠道显示；如果最终解析到 Ollama，包括 active -> ollama，有效批次也应按配置值生效，但只允许落在 5-20。
新闻清洗渠道设置 若选择 Ollama，也必须来自 已安装模型 下拉；没有已安装模型时应明确阻断，而不是假装已保存可用；若用户输入 12/20 等合法值，保存后应原样回显，只有越界输入才应被归一化到 5 或 20。
Archive background cleaning 命中 Ollama 时，也应按当前已保存的批次大小执行，不应把界面里已保存的 12/20 回写或降成 5。
Ollama 区的状态、按钮、模型列表和消息文案必须互相一致，不能出现 运行中 但无模型列表且刷新无反应的半成功态；也不能把“已安装但未运行”误报成 未安装，导致只剩安装提示而没有 启动 / 刷新 恢复路径。

失败分流

主渠道失败：记录 Provider、模型、错误文案、是否能 测试连接，再停止依赖 LLM 的模块回归。
新闻清洗渠道失败：主渠道验证可继续，但 全量资讯库 -> 批量清洗待处理 只做入口检查，不做成功态断言。
Ollama 失败：若远端主渠道可用，可继续远端 LLM 回归；若主渠道本来就是 Ollama，则后续依赖 LLM 的模块整体降级为阻塞。

交叉断言

完成本模块后，1-3 秒内去 股票推荐 发起一次请求，或去 股票信息 触发一次 AI 动作；应直接使用新通道，不应继续报未配置或落到旧 Provider。
如果刚保存了新闻清洗渠道，后续在 全量资讯库 做批量清洗时，不应再弹出与主渠道无关的旧错误。

2. 财务数据测试

入口点

操作：点击右上角 ⚙ 管理设置，选择 财务数据测试。定位锚点：页面内必须出现 Worker 状态、采集配置、手动测试采集、采集日志。等待时间：立即到 3 秒。超时判定：3 秒内仍未见这四个区块。

预置数据

准备一只适合验证财报的股票。输入示例：600519 或你本地已确认能采集的样本。失败分流：若样本本身长期无数据，换另一只股票，不把“空财报”直接当功能失败。

操作步骤

操作：先看顶部 Worker 状态，再点 刷新。等待时间：1-3 秒。可见状态：状态点和文字切到明确状态，而不是一直 unknown。超时判定：10 秒内状态不变且无附加说明。重试策略：再点一次 刷新；仍不变视为 Worker 状态未收敛。
操作：查看 采集配置 是否能正常回显；按需改 启用自动采集、频率、范围、起始日期 后点击 保存配置。等待时间：1-3 秒。可见状态：按钮恢复可点，出现 配置已保存 或明确失败文案。超时判定：10 秒内无任何反馈。
操作：在 手动测试采集 输入框填股票代码，点击 开始采集。输入示例：600519。等待时间：中等到长等，先看 3-10 秒是否进入结果态，最长观察 30 秒。可见状态：按钮 开始采集 -> 采集中... -> 恢复可点；结果区出现 ✅ 采集成功 或 ❌ 采集失败，并附 主渠道、耗时、报表 / 指标 / 分红 / 融资融券 计数。超时判定：30 秒仍停在 采集中...。重试策略：换一只股票再试 1 次；仍失败就不要继续财报回显断言。这里管理员页允许输入裸六码，后续回到 股票信息 时即使页面内部请求使用 sh600519 / sz000001 这类规范化代码，也应该能看到同一只股票的财报回显。
操作：如果结果区出现 ⚠️ 降级:，记录文案，但继续看是否仍有结构化计数返回。等待时间：立即。可见状态：允许降级提示，但不接受只有降级无任何结果计数的半空态。
操作：采集完成后，查看 采集日志 表格；必要时点 刷新。等待时间：1-3 秒。可见状态：日志表新增或更新当前股票记录，至少应有时间、股票、渠道、结果、耗时之一。超时判定：10 秒后日志区仍完全无变化。重试策略：点一次 刷新；仍无变化则记为“采集结果未落日志”。
操作：不要停留在本页。采集成功后 3-10 秒内切回 股票信息，同一只股票打开侧栏 Tab 财务报表，点击 🔄 刷新数据。等待时间：3-10 秒。可见状态：财务报表 区出现 ✅ 已通过 ... 获取 ... 期报表、核心指标卡、趋势表、报表摘要、分红记录，或对稀疏 PDF 数据明确提示“已通过/已获取 ... 期报表，但当前暂无可展示的结构化财务指标”。这里同一只股票允许管理员页使用 600519、股票信息页使用 sh600519 或 sz000001 之类规范化代码，财报数据仍应命中同一份本地数据。超时判定：30 秒内仍是 暂无财务数据 且刷新无变化。重试策略：轮询 3 次，每 2 秒一次，再判失败。

等待与判定

开始采集 到结果区出现成功或失败，以 30 秒为保守上限。
财务数据测试 -> 股票信息财务报表 的跨页回显，不要求绝对实时，但 10 秒内应开始有变化；30 秒仍无变化视为链路断裂。

关键断言

手动采集必须有明确结束态，不能只看到按钮恢复却没有结果区。
采集成功后，股票信息 -> 财务报表 至少要出现结构化卡片、成功提示，或对稀疏 PDF 数据的明确部分数据提示；不接受长期 暂无财务数据。
同一只股票在管理员页用裸六码手动采集后，股票信息 页即使使用 sh/sz 规范化 symbol 请求，也必须能直接回显同一份财报数据。
财报金额 API 契约为 CNY-yuan（人民币元）。THS/同花顺等以“万元”入库的来源，后端返回给 summary/trend/detail 前必须统一换算为“元”，前端再按元格式化为 亿/万。
用 600519 验证年度财报量级时，总资产、营业收入、净利润必须显示为亿元级：例如资产约 3038.35亿、营收约 1720.54亿、净利润约 853.10亿；不得显示为 3038.35万 / 1720.54万 / 853.10万。
若有降级提示，界面应显示本地化说明，不应出现原始异常堆栈。

失败分流

Worker 健康异常：停止本模块和 股票信息 -> 财务报表 的强断言，只记录阻塞。
采集成功但股票信息无回显：记录股票代码、采集时间、日志是否新增，再转股票财报链路排查。
日志区无新增：记录“结果区成功但日志未落地”，后续可继续看股票信息，但要单独标红。

交叉断言

同一只股票在 财务数据测试 成功后，回到 股票信息 -> 财务报表，不应还需要重新搜索另一只股票才能看到数据。
如果本页显示 主渠道: xxx，回到财报页的成功提示也应能体现相同渠道或至少不与之冲突。

3. 股票信息

入口点

顶部页签点击 股票信息。定位锚点：页内需出现 标的查询、搜索框 placeholder 输入股票代码/名称/拼音缩写、按钮 查询、图表区标题 专业图表终端、侧栏 Tab 交易计划 / 新闻影响 / AI 分析 / 全局总览 / 财务报表。等待时间：立即到 3 秒。

预置数据

至少准备 2 只股票：A 用于完整回归，B 用于切换后再切回验证工作区状态保留。输入示例：A=600519，B=另一只有本地资讯或计划样本的股票。
额外准备 1 只 ST 样本用于名称一致性回归。输入示例：搜索 *ST 四环 或 *ST八钢，用户可见名称应统一显示为 *ST四环、*ST八钢 这种紧凑格式；普通公司名里的合法空格不应被删除。

操作步骤

等待与判定

查询 到首屏首次回显，以 10 秒为保守上限；到各异步区补齐，以 30 秒为保守上限。
保存为 Pending 计划 到列表刷新，以 10 秒为保守上限。
录入执行 跳转到 交易日志，应在 3 秒内完成。

关键断言

失败分流

查询后长期空白：记录股票代码、是否出现搜索结果、是否有旧缓存回显，再转股票详情链路排查。
AI 分析 的本地模型完整研究卡住：记录股票代码、当前主 provider、模型名、最后一个可见阶段/角色、按钮最终文案，以及是否首次冷启动；不要把长时间无新阶段输出视为“只是模型慢”。
计划保存失败：记录弹窗内错误文案、计划是否局部保存、刷新后是否仍不存在。
跳转交易日志失败：记录是否切页、是否携带计划上下文、是否只打开了空白列表。

交叉断言

如果前面已经在 财务数据测试 成功采集，这里 财务报表 不应长期停留在 暂无财务数据。
之后做完 情绪轮动 后要再回本页打开计划弹窗，确认 市场上下文 随最新市场快照变化。
之后做完 全量资讯库 批量清洗后要回本页 新闻影响 或本地资讯区域，确认同一股票能对上资讯标题或标签。

4. 情绪轮动

当前任务状态提示：

本模块代码修复已完成。
当前主要验证目标是盘中 3 轮（4/21-4/23）。
如遇降级，必须核对 sectorEmptyBody 是否包含快照时间，以及 /api/market/audit 的 reasons 是否可读。

盘中日检执行命令：

python scripts/check-market-audit-once.py
关注项：sources 状态与 recentSyncs.reasons
日志落盘位置 logs/market-audit-check-*.json

入口点

顶部页签点击 情绪轮动。定位锚点：页面内应看到 情绪轮动 标题、按钮 同步最新数据、窗口切换 5日 / 10日 / 20日，以及 数据审计面板 或等价审计区块。等待时间：立即到 3 秒。

预置数据

本模块不要求指定个股，但建议提前记住一个主线板块名称，后面回 股票信息 时要比对计划弹窗里的 主线。
例外口径：如果本轮刚同步到的是 fresh degraded 快照，情绪轮动 允许把 同步不完整 视为可接受结果；但必须继续核对下面的降级 UI 断言，不能把原始错误码、0 分 / 0 置信 或误导性的旧榜单当成通过。

操作步骤

等待与判定

同步最新数据 可给到 30 秒，不把短时未完成直接当失败；但超过 30 秒仍无结果就判卡住。
比较窗口 和 板块详情 都是短链路，3 秒内应有可见变化。

关键断言

失败分流

同步失败：记录是否只有总览失败、是否只有详情失败，避免把整页都判死。
详情不刷新：记录左侧选中板块名称与右侧仍显示的旧板块名称，便于定位“选中态有了但数据没跟上”。

交叉断言

完成本模块后，不要超过 3-10 秒，立刻回 股票信息 打开 新建计划 或 编辑交易计划；应在 市场上下文 区看到接近本页的 阶段 / 主线 / 建议仓位 / 节奏。
回到股票信息时，计划弹窗里应看到 当前股票与主线方向一致 或 未明显对齐主线 之类的判断；若当前暂无快照，也至少要看到加载态或兜底提示，不应完全缺失 市场上下文 区块。

5. 全量资讯库

入口点

顶部页签点击 全量资讯库。定位锚点：页面内应出现 搜索、层级、情绪、检索、🧹 批量清洗待处理，以及页头 全量资讯库 和副标题 资讯归档控制台；不应再出现 News Archive Console。进入后台清洗链路后，更稳定的锚点以 最近一次清洗结果、继续后台清洗、重新开始清洗、查看最近请求 / 响应详情 为主。等待时间：立即到 3 秒。

预置数据

准备一个待清洗样本和一只可在 股票信息 比对的股票。输入示例：关键字可先用股票代码、公司简称或板块词。

操作步骤

等待与判定

检索和筛选以 10 秒为保守上限。
批量清洗的 启动请求 以 3 秒为保守上限；超过 3 秒还没进入页面内进度面板，就判定没有真正切到后台模式。
后台轮询观察以 30 秒为保守上限；若 已处理 / 剩余 / 累计轮次 仍在变化，可等满 30 秒再判。

关键断言

批量清洗待处理 不能只弹 toast；页面内必须保留 后台清洗状态 / 最近一次清洗结果 作为持久回显，并且在运行中就能看到真实 已处理 / 剩余 / 累计轮次 以及可展开、最新在上的最近请求 / 响应详情。
页头可读性汇总必须与当前筛选条件一致，至少包含 可读 数量/占比与 无原文（url_unavailable）数量/占比；不能只显示 total 而让用户无法判断归档新闻原文覆盖质量。
个股资讯卡片的 aiTarget 和 AiTags 不得污染底部 名称 / 代码 / 行业。例如茅台公告底部为 贵州茅台 / sh600519 / 酿酒行业 时，顶部不能显示 中国石化 这类其它股票标签；行业预期、经营数据 等通用标签可保留。
首轮可恢复无进展不能直接把页面打成“结束并等待手动恢复”；应保持运行态并给出自动重试提示，直到真正暂停、失败或完成。
自动重试 / 重试耗尽 文案必须明确当前是第几次重试、待处理资讯已保留，并提示可展开 最近请求 / 响应详情 查看原始返回；若确认是空响应、非 JSON 数组或 JSON 解析失败，还应提示先检查 LLM 设置 再继续或重新开始。
单次点击的核心通过条件是“快速启动后台任务 + 页面轮询显示真实进度”，不是等待一个长 POST 自己收口。
清洗后回 股票信息 比对时，应看到信息一致，不应出现资讯库已经有、股票信息完全断层的情况。

失败分流

若提示 当前没有待清洗资讯，这不是功能失败，但要记为“环境无样本”，不能替代成功态。
若启动后长期没有出现进度面板，记录点击时间、按钮文案、是否仍卡在单次请求，再停止该链路。
若面板长期停在 后台清洗进行中，记录最后的 已处理 / 剩余 / 累计轮次 和停留时长，再停止该链路，不继续空等。

交叉断言

如果前面在 LLM 设置 改过新闻清洗渠道，这里批量清洗的表现应与该配置一致；不应突然回退到主渠道旧错误。
之后去 股票信息 比对时，应看到什么：至少一个同标题、同情绪、同标签或同发布时间附近的资讯；不应看到什么：资讯库已经清洗成功，但股票信息完全仍是旧列表且无刷新迹象。

6. 股票推荐

入口点

顶部页签点击 股票推荐。定位锚点：页面内应出现 多角色分阶段辩论推荐系统、推荐前市场快照、实时市场上下文、历史推荐、Tab 推荐报告 / 辩论过程 / 团队进度、输入栏和发送按钮；不应再出现 13-Agent 多阶段辩论推荐系统、Realtime Context。等待时间：立即到 3 秒。

预置数据

确认前面 LLM 设置 已经是可用态。准备一条初始问题和一条追问。输入示例：初始问题 今天有什么值得关注的板块？；追问 半导体再深入看看...。

操作步骤

等待与判定

SSE 首包建议 3-10 秒内出现；30 秒无首包可视为严重异常。
单轮结束态建议 30 秒内收敛；若 feed 仍持续增长，可等满 30 秒再判。
追问有明确 90 秒超时口径；看到超时文案即记失败，不再主观猜测后台还会回来。

关键断言

推荐前市场快照 要在推荐前可见，不能整个模块直接盲发问题。
用户可见模块名和副标题应是自然中文；不要露出 13-Agent、Realtime Context 这类内部/英文标签。
禁用按钮必须能说明禁用原因；空输入追问必须通过 placeholder、title 或可见提示解释需要输入内容。
SSE 不只是开始和结束两个点，中间必须有持续进度或 feed 增量。
追问是“追加一轮”，不是覆盖上一轮。
追问/重跑切出新轮次后，顶部执行态、当前轮次、团队进度、辩论过程必须指向同一新轮次；不能出现顶部仍 执行中 但进度继续显示上一轮 已完成 的矛盾状态。
推荐报告、辩论过程和团队进度里的板块代码与名称必须保持一致；同一 code 不能在同一 session 内被显示为多个板块名。
至少拿到一个可供治理页回查的 traceId。

失败分流

首包超时：记录问题文本、状态条最后文案、是否拿到 traceId。
中途卡死：记录最后一个阶段名或角色名、已耗时、feed 最后一条内容。
追问失败：记录是 正在提交追问... 之后失败，还是 追问已提交... 后分析流没接上。

交叉断言

完成本模块后，不要超过 3 分钟，立刻去 治理开发者模式 用刚记录的 traceId 检索；应能查到时间线和日志。
如果本模块调用前刚改过 LLM 设置，这里不应继续使用旧通道或报“未配置”。

7. 治理开发者模式

入口点

操作：点击右上角 ⚙ 管理设置，选择 治理开发者模式。定位锚点：页面内应出现 检索 Trace、Trace 时间线、LLM 对话过程日志、刷新日志、LLM 日志详情 的入口区。等待时间：立即到 3 秒。若出现登录框，先用管理员账号进入。
操作：未登录状态下直接请求任一治理或管理数据接口，例如 /api/admin/source-governance/overview，应返回 401；使用管理员账号登录后再次访问，应能正常返回治理数据或页面内容。

预置数据

使用上一模块记录的 traceId。输入示例：直接粘贴从 股票推荐 或 股票信息 里记录的 traceId，不手工改写。

操作步骤

操作：把 traceId 粘进输入框 输入 traceId 检索日志，点击 检索 Trace。等待时间：1-3 秒。可见状态：按钮 检索 Trace -> 检索中... -> 恢复可点，下方出现 Trace 时间线 或 trace lines 文本。超时判定：10 秒内无返回。重试策略：核对是否多贴了空格，再重试 1 次。
操作：查看 Trace 时间线。等待时间：立即。可见状态：列表中应至少有 时间 | stage | domain | status 形式的多行，不应只是空数组。超时判定：检索成功但时间线为空。
操作：在 LLM 对话过程日志 区输入关键字，可直接粘 traceId，点击 刷新日志。等待时间：1-3 秒。可见状态：列表加载后，日志项头部应看到 status=...、provider=...、stages=...，并且每行可能有 Trace 按钮。超时判定：10 秒内一直 正在读取日志...。
操作：点任一日志项正文，打开 LLM 日志详情。等待时间：立即到 3 秒。可见状态：弹层出现 请求摘要、请求 JSON 美化视图、返回摘要、返回 JSON 美化视图、异常信息 中的至少一部分。超时判定：3 秒内无弹层。
操作：在日志详情里确认 traceId= 与当前追踪值一致。等待时间：立即。可见状态：详情头部 provider / model / traceId / stages 完整可读。失败分流：若详情里无 traceId 或 traceId 不匹配，记为“日志聚合错链”。
操作：点击日志项或修复队列/错误快照里的 Trace / 跳转 Trace。等待时间：1-3 秒。可见状态：页面内 trace 输入框或时间线刷新到对应 trace，不应按钮存在但无响应。超时判定：3 秒内无任何焦点变化。
操作：若前面股票推荐拿到的 traceId 查询不到，再换一条来自股票信息或其它 LLM 动作的 traceId 复测一次。等待时间：1-3 秒。目的是区分“单条 trace 丢失”和“治理页整体不可用”。

等待与判定

Trace 检索和日志刷新都以 10 秒为保守上限。
日志详情弹层和 Trace 跳转都是短链路，3 秒内应完成。

关键断言

同一 traceId 至少要在 Trace 时间线 或 LLM 对话过程日志 命中其一；理想状态是两边都能命中。
日志详情必须能看到脱敏摘要，而不是只有一堆空字段。
Trace / 跳转 Trace 按钮必须真能回到同一链路，不是装饰按钮。

失败分流

检索为空：记录 traceId、来源模块、生成时间。
时间线有数据但日志无数据：记为“治理链有 trace，无 LLM 审计明细”。
日志有数据但 Trace 跳转失效：记为“按钮断链”。

交叉断言

本模块检索的 traceId 应来自 股票推荐 或 股票信息，不是手工杜撰。
如果 股票推荐 的 traceId 能在这里查到，则说明 LLM 设置 -> 股票推荐 -> 治理 主链可闭环；查不到就不能把前面推荐链路当完全通过。

8. 交易日志

入口点

顶部页签点击 交易日志。定位锚点：页面内应看到 持仓总览、风险敞口、🧘 交易健康度、按钮 快速录入、设置本金、📝 生成复盘总结。等待时间：立即到 3 秒。
顶部页签点击 交易日志。定位锚点：页面内应看到 持仓总览、风险敞口、🧘 交易健康度、计划管理工作区、按钮 快速录入、设置本金、📝 生成复盘总结。等待时间：立即到 3 秒。

预置数据

如果是空环境，至少准备一次来自 股票信息 -> 当前交易计划 -> 录入执行 的带计划上下文进入；否则本模块只能验证 快速录入 基础链路。
准备一笔最小可录入交易。输入示例：股票代码可从搜索下拉选；备注可填 README 回归录单。

操作步骤

等待与判定

录单保存与汇总刷新以 10 秒为保守上限。
AI 复盘生成与历史写入以 30 秒为保守上限。
🔄 重置 是危险动作，只在测试环境或网络拦截/mock 下验证，不做真实用户数据删除和重试回放。

关键断言

从 股票信息 计划卡跳来的执行录入，必须带计划上下文，不应退化成完全手工空表单。
交易保存后，不只是列表新增，汇总卡、风险敞口、计划执行率也应刷新。
活跃计划 / 未完成计划如果展示当前持仓快照，应读取实时持仓值；已完成计划若展示执行快照，应保留历史值，不应继续跟着最新行情漂移。
计划管理工作区 选中计划后，计划卡本身应同时保留独立的 告警 与 执行摘要 视图；右侧 复盘工作区 与下方交易列表都要联动；此时再切换快捷筛选 仅看偏离 / 仅看无计划，交易列表需要继续在“已联动计划”的范围内真实变化，且工作区不应继续显示上一条记录的旧状态。
AI 复盘要同时满足“当前区可见正文”和“历史区有可回看的记录”。
🔄 重置 完成两次确认后，请求体必须包含 confirmText: RESET_ALL_TRADES；交易、持仓、复盘历史被清空，但 本金设置 和 交易计划 不应被误删。

失败分流

保存失败：记录表单字段是否完整、错误文案、是否有部分数据残留。
复盘失败：记录是正文未生成、历史未写入，还是二者都失败。
重置异常：记录成功/失败 toast 文案，以及是否误删了本金设置或交易计划。

交叉断言

若本模块是从 股票信息 -> 录入执行 进入，保存后回 股票信息 再看该计划，应能反映已执行痕迹或至少不再像未执行前那样无变化。
若保存时录入了偏差标签或说明，返回 股票信息 后该计划的执行回写也应出现对应的偏差/执行摘要，不应只在 交易日志 单页可见。
若刚完成 AI 复盘，再回到同页历史记录，最新一条应能回显刚生成内容，而不是只在当前面板短暂出现。

跨模块联动场景与同步时序

场景 A：LLM 设置 -> 股票推荐 / 股票信息

完成 LLM 设置 -> 保存设置 后，1-3 秒内去 股票推荐 发起一次轻量请求，或在 股票信息 触发一次 AI 动作。应看到什么：下游页面直接成功进入分析态或返回结果。不要看到什么：仍提示未配置、仍引用旧 Provider、只出现旧缓存错误。
如果刚改了 新闻清洗渠道设置，不要先去无关页面，优先在 3 分钟内做 全量资讯库 -> 批量清洗待处理。应看到什么：点击后 1-3 秒内出现 后台清洗状态 面板，按钮不再被单次长请求卡住，随后页面轮询显示真实进度、可展开的请求 / 响应详情，并在运行中提供 暂停后台清洗，暂停后提供 继续后台清洗 与 重新开始清洗；若首轮只是可恢复无进展，应保持运行并自动重试，而不是立刻结束；若当前最终解析到 Ollama，包括 active -> ollama，也应先快速返回再轮询，并观察每轮按当前已配置批次推进，而不是把本地 Ollama 固定按 5 条一轮硬跑。不要看到什么：仍沿用刚才修复前的老错误、仍期待本地 Ollama 用配置外的大批次一轮硬跑，或长时间卡死在单次请求里。

场景 B：财务数据测试 -> 股票信息财务报表

如果历史环境曾登录过旧版 财务数据测试，先直接进入该页。应看到什么：页面能继续携带管理员登录态请求 Worker 状态、采集配置和日志；刷新后仍可用。不要看到什么：LLM 设置可用但财务数据测试单页丢失管理员 token、请求变成未授权。
开始采集 成功后，3-10 秒内回 股票信息 同一股票的 财务报表 Tab，先点 🔄 刷新数据，再轮询每 2 秒一次，最多 3 次。应看到什么：成功提示、指标卡、趋势表、报表摘要、分红记录之一，或对稀疏 PDF 数据明确提示“已通过/已获取 ... 期报表，但当前暂无可展示的结构化财务指标”。不要看到什么：始终 暂无财务数据 且无任何刷新痕迹。
如果 30 秒内仍无回显，记录采集成功时间和日志行，再判 财务链路断在回显层。

场景 C：情绪轮动 -> 股票信息交易计划市场上下文

在 情绪轮动 完成 同步最新数据 后，3-10 秒内回 股票信息 打开 新建计划 或 编辑交易计划。应看到什么：弹窗内出现 市场上下文，且含 阶段 / 置信 / 主线 / 建议仓位 / 节奏。不要看到什么：完全无 市场上下文 区块，或内容与刚才主线明显无关。
如果当日市场快照较旧，可接受数值不完全一一相等，但不接受方向性完全相反且无任何说明。

场景 D：全量资讯库 -> 股票信息新闻影响

在 全量资讯库 完成 🧹 批量清洗待处理 后，3-10 秒内回 股票信息 同一只股票。应看到什么：至少能对上标题、标签、情绪或发布时间相近的一条资讯。不要看到什么：资讯库已清洗完成，但股票信息仍是明显旧内容且无刷新。
如果第一条样本对不上，允许换同一股票的第二条样本再验证 1 次；超过 2 条仍对不上，判一致性失败。

场景 E：股票推荐 -> 治理开发者模式

股票推荐 一轮完成后，立即记录 traceId，并在 3 分钟内进入 治理开发者模式 检索。应看到什么：Trace 时间线 有多行记录，LLM 对话过程日志 能看到对应 provider / stages / request/response 摘要。不要看到什么：时间线为空、日志为空、Trace 跳转无响应。
如果推荐页能看到 traceId，但治理页查不到，不能把推荐链路视为全通过。

场景 F：股票信息 -> 交易日志 -> 股票信息

在 股票信息 -> 当前交易计划 点击 录入执行 后，应在 3 秒内打开 交易日志 的 录入执行 弹窗。保存后，3-10 秒内返回 股票信息 同一计划区。应看到什么：计划相关状态或执行痕迹已有变化，至少不是完全无差别。不要看到什么：交易日志里保存成功，但股票信息计划区完全像没执行过一样。
在 交易日志 -> 持仓总览 点击任一持仓行，或聚焦该行后按 Enter / Space，应在 3 秒内跳回 股票信息 并自动搜索该 symbol。应看到什么：顶部选中 股票信息、搜索框为该 symbol、报价/图表切到同一标的、toast 已跳转到 xxx 股票信息。不要看到什么：只改变焦点、不切 Tab、不自动搜索，或点击可用但键盘不可用。
若返回后无变化，先点计划区 刷新 一次；仍无变化再判跨页执行回写失败。

场景 G：交易日志 AI 复盘 -> 复盘历史回显

在 交易日志 触发 今日复盘 或 本周复盘 后，30 秒内除了当前面板要有正文，📆 复盘历史 也要新增记录。应看到什么：最新历史项时间、类型、胜率与本次复盘相符。不要看到什么：正文一闪而过，但历史列表没有写入。
点击最新历史项后，应能再次打开同一条内容；若只能看当前面板、无法回看历史，记为闭环不成立。

9. 散户热度指标（K 线图子窗格）

入口与锚点

进入 股票信息 选择任一 A 股标的 → 打开 专业图表终端。定位锚点：图表区域下方应有可展开的子窗格列表。

前置数据

系统需有至少 2 天的论坛帖子采集数据（ForumPostCounts 表），否则散户热度将显示为"暂无数据"。可通过 POST /api/stocks/retail-heat/initial-collect 触发首次采集。

启用散户热度窗格

操作：在图表策略选择器中勾选 散户热度（默认不勾选）。等待时间：立即到 2 秒。可见状态：图表底部出现 散户热度 子窗格，含彩色 bar 图。

热度 bar 颜色验证

检查 bar 颜色是否符合温度色阶：深红（≥3.0 过热）、琥珀（≥2.0 偏热）、灰（0.7~~2.0 正常）、蓝（0.5~~0.7 偏冷）、深蓝（<0.5 冷清）。

tooltip 信息验证

操作：鼠标悬停在任一热度 bar 上。可见状态：tooltip 应显示 热度: X.XX 和 平台: N，其中 N 为当日数据来源平台数。

反向指标警告验证

操作：查看散户热度的帮助/图例。可见状态：应有 ⚠️ 这是一个反向指标！ 提示文字，以及 hot=考虑卖出、cold=买入机会（需排除 ST/垃圾股）的说明。

API 数据验证

操作：直接请求 GET /api/stocks/{symbol}/retail-heat?from=2026-04-01&to=2026-04-14（日期换为实际有数据的范围）。可见状态：返回 JSON 含 data 数组，每项有 date、dailyCount（日增量而非累计总量）、ma20、heatRatio、signal、platformCount。heatRatio 应在 0~5+ 范围波动，而非全部接近 1.0。

默认不可见

首次打开图表时，散户热度窗格不应自动出现，需要用户手动启用。

故障诊断

heatRatio 全部为 0 或全部为 1.0：检查 ForumPostCounts 表是否有至少 2 天数据、delta 计算是否正常。
tooltip 无 平台 字段：检查前端 chartStrategyRegistry.js 的 platformCount figure 是否存在。
bar 全为灰色：检查 signal 分布，可能数据采集天数不足导致 MA20 不够稳定。

10. 财务工作者监控

入口：点击右上角 ⚙ 管理设置 → 选择"工作者"标签

前置条件

后端 API 已启动（会自动启动 FinancialWorker）

回归项

#	操作	验收标准
10.1	进入"工作者"面板	面板正常渲染，状态卡显示「运行中」绿色指示灯、PID、心跳「刚刚」
10.2	等待 15 秒观察心跳	心跳时间持续更新（「刚刚」→「10 秒前」→ 刷新后回到「刚刚」）
10.3	查看当前活动	显示「空闲」或「采集中:XXXXXX」（中文）
10.4	点击"⏹️ 停止"	Toast 显示「停止指令已发送」，状态变为灰色「已停止」，按钮状态：停止禁用、启动可用
10.5	停止后等待 25 秒	无红色错误文字出现，当前活动行消失，心跳变为「上次: XX 秒前」
10.6	点击"▶️ 启动"	Toast 显示「启动指令已发送」，状态恢复绿色「运行中」，新 PID
10.7	点击"🔄 重启"	Toast 显示「重启指令已发送」，PID 变化，状态保持「运行中」
10.8	运行时长显示	运行中时显示「运行时长: X 分钟」，停止后消失
10.9	系统信息区域	运行中时显示数据目录和数据库路径，停止后信息区域消失
10.10	刷新页面后保持	F5 刷新后状态保持一致（URL 含 `?tab=financial-worker`）
10.11	确认"运行日志"区域可见	面板底部有控制台风格深色日志区，5 秒内自动加载日志
10.12	切换级别筛选	选择 ERROR 后只显示 ERROR 级别，选择全部恢复所有
10.13	点击"清空"	日志列表清空，旧日志不再出现，只有清空后产生的新日志才会显示
10.14	重启 Worker 后日志	日志自动重载，显示新 Worker 的启动日志
10.15	日志条数统计	底部"N 条日志"与实际显示条数一致

财报中心 (v0.4.0)

v0.4.0 新增页签 财报中心。本节给出最小回归路径，便于 User Agent 在 packaged 环境下快速签收。

入口点

入口：浏览器打开 http://localhost:5119/?tab=financial-center，或在桌面壳层切到顶部 财报中心 页签。
定位锚点：页面应出现 筛选 区（股票多选 / 报告期范围 / 报告类型 / 关键词）+ 列表表头 股票代码 / 名称 / 报告期 / 类型 / 来源渠道 / 采集时间 / 操作 + 右下角分页控件。
等待时间：立即到 3 秒。超时判定：5 秒内仍空白页面或控制台报红，即判失败。

列表回归

操作：不加任何筛选直接进入。可见状态：列表出现至少 1 行；底部分页显示 共 N 条。
操作：点击表头 报告期、采集时间 切换排序。可见状态：箭头方向变化，列表数据顺序明显改变；URL ?tab=financial-center 后追加 &sortField=...&sortDirection=...。
操作：调整 每页大小（10 / 20 / 50）。可见状态：列表行数随之变化，分页器页数同步更新。
操作：在 股票 多选选 1 只样本（如 600519），在 报告类型 多选勾 年度报告，在 报告期范围 设个区间。可见状态：列表只剩匹配项；筛选条件回写到 URL 查询串。

详情抽屉回归

操作：点列表中 操作 列的 详情，唤出右侧抽屉。可见状态：标题区显示 股票名称报告期；元数据 dl 含 来源渠道 Tag、采集时间；三表概览（资产负债 / 利润 / 现金流）展开。
关键断言：三表共 15 字段中至少 14 项有数字（仅 毛利润 允许显示 —，已知遗留 V040-S6-FU-1）；金额字段使用 万 / 亿 缩写但 tooltip 保留完整数值，基本每股收益 不做金额缩写。
关键断言：抽屉中不应出现 Report ID、Mongo/ObjectId、数据库主键等内部标识。
操作：点抽屉底部 sticky 重新采集。可见状态：按钮进入 采集中…，3-30 秒内出现成功 toast 或错误提示，列表 采集时间 字段刷新。

PDF 原件与降级空态

操作：在详情抽屉中点击 查看 PDF 原件。可见状态：若已有 PDF，弹出双栏对照面板，左侧可预览 PDF 原件，右侧可切换解析预览 / 投票详情 / 解析阶段。
操作：选择无 PDF 原件或采集降级的报告。可见状态：抽屉显示 该报告暂无 PDF 原件、采集 PDF 原件 等中性空态/降级提示，不应空白或报红。

关键词回归

操作：在 关键词 输入框输入 茅台，按回车。可见状态：列表只剩贵州茅台相关行；URL 串带 &keyword=茅台。
操作：清空关键词回车。可见状态：列表恢复未筛选状态。
已知遗留 V040-S6-FU-2：当前关键词由前端做二次过滤，仅在当前页 pageSize 内生效（关键词模式下前端会临时把 pageSize 拉到 100）；总匹配数超过 100 条时存在漏；后端全文匹配 v0.4.1 修复。

来源 Tag 回归

列表 来源渠道 列与抽屉元数据区都应出现彩色 Tag（如 eastmoney emweb / eastmoney datacenter / 同花顺 / pdf 等）。颜色未完全统一为已知 backlog V040-S3-FU-1。

失败分流

列表空：先确认环境内 financial_reports 是否真的有数据；再回 财务数据测试 → 开始采集 拉一只样本，再回本页验证。
抽屉三表整体为空：检查后端 /api/stocks/financial/reports/{id} 是否返回 dictBalance/dictIncome/dictCashFlow；若后端返回中文键带 * 前缀，前端字典已做剥离，理论上不应再整体为空。
重新采集长时间无回显：转 财务工作者监控 看 Worker 是否在运行 / 心跳。
console 出现红错：截图 + 控制台日志 + 当前 URL 一并记录，进治理日志面板用 traceId 反查。

v0.4.5 数据质量与 Worker 稳定性

#	场景	验收标准
1	财报数值单位	同一公司同一年度，不同来源（THS/PDF）营业收入数值一致（均为元单位）
2	Worker 自动重启	supervisor-status 显示 state=running, autoRestartCount 有值追踪
3	cninfo PDF 采集	采集面板触发 PDF 下载，带正确的 Accept-Encoding + UA 头
4	日期选择器	采集面板日期选择器可见，日历图标可点击
5	财报中心采集	财报中心页面点击"采集"按钮，展开内联面板，输入代码后可直接采集

v0.4.4 产品质量修复

#	场景	验收标准
1	Agent 推荐状态	失败的推荐任务显示正确失败状态，不显示「完成」
2	情绪轮动板块数据	概念/行业板块排行有数据，changePercent 为合理值（0-10%范围）
3	基本面字段	股票详情页显示流通市值、市盈率、量比（非空）
4	主力净流入一致性	列表页与详情页主力净流入数值一致
5	Worker 日志面板	Worker 运行中时，管理页日志面板显示日志条目
6	财报毛利润	财报中心利润表显示毛利润值（= 营业总收入 - 营业总成本）
7	财报搜索	搜索框输入代码可过滤对应股票的财报

PDF 原件对照与透明化解析 (v0.4.1 + v0.4.2N)

前置条件：已完成「财报中心 (v0.4.0)」章节的步骤 1-4（至少有 1 只股票的采集数据）。

步骤 1：验证 PDF 原件对照面板（财报中心入口）

操作：在 财报中心 列表中找到一条有数据的报告，点击展开详情抽屉。在抽屉中找到 📄 查看 PDF 原件 按钮并点击。
预期：弹出双栏对照面板 — 左栏嵌入 PDF 预览（iframe），右栏有 Tab 切换（解析预览 / 投票详情 / 解析阶段）。
超时判定：5 秒内未弹出面板或 PDF 区域持续空白 > 10 秒。

步骤 2：验证 PDF 原件对照面板（股票详情入口）

操作：进入 股票信息，选择一只已采集的股票，切换到 财务报表 Tab。找到报表头部区域的 📄 查看 PDF 原件 按钮并点击。
预期：弹出 Modal 对照面板，内容与步骤 1 一致。
检查：两个入口（财报中心抽屉 + 股票详情）打开的对照面板功能完全一致。

步骤 3：验证价格显示统一缩写 (NS2)

操作：在对照面板右栏「解析预览」Tab 中查看 parsedFields 键值对。同时在 财报中心 详情抽屉中查看三表数据（资产负债表、利润表、现金流量表）。
预期：所有金额字段显示缩写格式 — ≥1亿显示为 X.XX亿，≥1万显示为 X.XX万，<1万显示原值。鼠标悬停（tooltip）显示完整千分位数值。
检查：基本每股收益 字段不做缩写（它是每股值，通常 < 10）。
检查：股票信息 → 财务报表 的顶部核心指标卡（营业收入、净利润、总资产）同样显示缩写 + tooltip。

步骤 4：验证解析单元实际内容 (NS4)

操作：在对照面板右栏「解析预览」Tab 中找到分组的解析单元（按 table / narrative_section 等分组）。
预期：每个解析单元显示：类型 tag、页码范围按钮、section 名称、字段数。
操作：点击某个解析单元的折叠区域「提取文本」/ 「解析字段」。
预期：「提取文本」展开后显示该页范围内的完整提取文本（<pre> 格式，有滚动条）。「解析字段」展开后显示 key-value 表格。
检查：如果某个解析单元没有 extractedText，应 fallback 显示 snippet。

步骤 5：验证投票透明化 (NS5)

操作：切换到对照面板右栏「投票详情」Tab。
预期：显示当前提取器名称、投票置信度、字段总数、时间戳。
预期：下方「提取器对比」区域显示 3 个候选提取器卡片。
检查：胜出者标记为蓝色边框 + ✓ 胜出，失败者标记 ✗ 失败。
检查：每个候选卡片显示页数 + 文本长度（如 45 页 / 4.5万字符）。
检查：如有投票说明（votingNotes），显示在候选卡片下方。

步骤 6：验证阶段折叠面板 (NS6)

操作：切换到对照面板右栏「解析阶段」Tab。
预期：显示 5 阶段 timeline（下载→文本提取→提取器投票→结构化解析→入库），顶部摘要显示成功数/5 + 总耗时。
操作：点击某个阶段展开。
预期：展开后显示阶段详细信息（key-value 格式），如 download 阶段显示 filePath + fileSize，extract 阶段显示各提取器成功/页数。
检查：失败阶段有红色高亮 + 错误信息。

步骤 7：验证重新解析 PDF

操作：在对照面板中找到「重新解析 PDF」按钮并点击。
预期：按钮显示 loading spinner + 文案变为「解析中…」+ 按钮禁用。
预期：解析完成后自动刷新面板内容（解析单元、投票详情、阶段日志全部更新）。
超时判定：60 秒内未完成。

步骤 8：验证 PDF 选择器

操作：如果同一报告期有多份 PDF 文件（如主报告 + 摘要），查看对照面板顶部是否有 PDF 选择器下拉框。
预期：选择器默认选中 fieldCount > 0 的主报告（非摘要/英文版）。
操作：切换到另一份 PDF。
预期：左栏 PDF 预览和右栏解析内容同步切换。

步骤 9：验证 PDF 下载即保存 (NS3)

说明：此项需在新采集场景中验证。如果能触发新的 PDF 采集（如对未采集的股票调用 POST /api/pdf-collect/{symbol}），则在采集过程中（解析尚未完成时）检查 PDF 列表。
预期：下载完成但解析尚未完成的 PDF 已在列表中可见，可预览 PDF 文件。

失败分类

问题	严重度	说明
对照面板无法打开	BLOCKER	核心功能缺失
PDF iframe 空白超 10 秒	BLOCKER	预览不可用
金额字段无缩写（仍显示原始大数）	MAJOR	NS2 未生效
投票详情无候选卡片	MAJOR	NS5 未生效
阶段面板无法展开	MAJOR	NS6 未生效
重新解析按钮无 loading	NIT	UX 体验问题
tooltip 不显示	NIT	移动端无影响

财报 RAG 检索 (v0.4.2)

测试目标：验证 PDF 财报切块入库、中文分词、BM25 检索完整链路。

前置条件

至少一只股票已完成 PDF 采集解析（可先执行上方 PDF 原件对照步骤 1-3）

验证步骤

#	步骤	预期结果
1	确认 `%LOCALAPPDATA%\SimplerJiangAiAgent\App_Data\financial-rag.db` 存在	DB 文件已自动创建
2	用 sqlite3 或 DB Browser 打开 `financial-rag.db`，检查 `chunks` 表	有记录，每条含 chunk_id/symbol/text/tokenized_text
3	检查 `tokenized_text` 列	中文已被空格分词（如"贵州茅台营业收入"）
4	POST `/api/stocks/financial/rag/search` `{"query":"营业收入","symbol":"600519"}`	返回相关 chunks，含 score/section/text
5	POST `/api/stocks/financial/rag/search` `{"query":"净利润"}`	不限股票，返回多只股票的结果
6	POST `/api/stocks/financial/rag/search` `{"query":"","topK":5}`	返回 400 错误（query 不能为空）
7	重新解析一个 PDF（reparse），再查 chunks 表	旧 chunks 被删除，新 chunks 写入

失败分类

现象	级别	可能原因
`financial-rag.db` 不存在	🔴	Worker 启动异常
chunks 表为空	🟡	PDF 解析未触发切块（检查 Worker 日志）
tokenized_text 未分词	🔴	jieba.NET 初始化失败
搜索返回空	🟡	FTS5 索引未同步（检查 trigger）
reparse 后旧数据残留	🔴	DeleteChunksBySourceId 未执行

混合检索与 AI 集成 (v0.4.3)

测试目标：验证 Ollama embedding + sqlite-vec 向量检索、BM25+向量混合召回、Citation 引用链路、AI 路径集成、Embedding 管理 UI、FTS5 特殊字符安全。

前置条件

至少一只股票已完成 PDF 采集解析并入库 chunks（可先执行上方财报 RAG 检索步骤 1-3）
Ollama 已安装并运行（hybrid 模式需 bge-m3 模型；Ollama 不可用时自动降级为 BM25）

验证步骤

#	步骤	预期结果
1	POST `/api/stocks/financial/rag/search` `{"query":"营业收入","symbol":"600519","mode":"bm25"}`	返回相关 chunks，`mode` 字段为 `bm25`
2	POST `/api/stocks/financial/rag/search` `{"query":"营业收入","symbol":"600519","mode":"hybrid"}`	若 Ollama + bge-m3 可用则返回 hybrid 结果（`mode:"hybrid"`）；否则降级为 BM25（`mode:"bm25"`）
3	POST `/api/stocks/financial/rag/context` `{"query":"净利润增长原因","symbol":"600519"}`	返回 `citations` 数组和 `contextText`；每条 citation 含 chunk_id / text / section / score / source_file
4	GET `/api/stocks/financial/embedding/status`	返回 `model`（如 bge-m3）、`dimension`（如 1024）、`coverage`（已嵌入 chunk 比例）
5	停止 Ollama 服务后，POST `/api/stocks/financial/rag/search` `{"query":"营业收入","mode":"hybrid"}`	自动降级为 BM25，返回结果中 `mode:"bm25"`，无 500 错误或崩溃
6	进入 `管理设置 → LLM 设置 → Embedding 模型管理` 面板	面板显示 Ollama 在线状态、已安装 embedding 模型列表、安装/切换按钮
7	在 Embedding 面板点击检查状态	显示当前 embedding 模型名、向量维度、已覆盖 chunk 数量/比例
8	进入 `股票信息`，选择已采集股票，打开 `AI 分析` Tab，触发一次分析	分析结果包含 citation chips（如 `[年报 P.12]`），可展开查看原文片段
9	POST `/api/stocks/financial/rag/search` `{"query":"NEAR NOT * OR","symbol":"600519"}`	正常返回结果（可能为空），不返回 500 或 FTS5 语法错误

失败分类

现象	级别	可能原因
hybrid 模式返回 500	🔴	sqlite-vec 扩展未加载或 chunk_embeddings 表不存在
Ollama 离线时 hybrid 崩溃	🔴	OllamaEmbedder.IsAvailable 未正确检测
embedding/status 返回 404	🟡	路由未注册
citation chips 不可见	🟡	AI 路径未注入 RAG context 或前端未渲染 RagCitationList
FTS5 特殊字符返回 500	🔴	query sanitization 未生效
降级后 mode 字段仍显示 hybrid	🟡	返回 DTO 未反映实际检索模式

v0.4.6 多 Agent 路由与财报 RAG 闭环

#	场景	验收标准
1	意图分类	输入"这个股票贵不贵"，系统分类为 Valuation 意图，confidence ≥ 0.8
2	路由决策	Valuation 意图路由到 Research 管道，RequiresRag=true
3	RAG 工具注册	FundamentalsAnalyst/CompanyOverviewAnalyst 工具列表包含 FinancialReportRag
4	Recommend RAG	LeaderPicker/GrowthPicker 工具列表包含 financial_report_rag
5	Evidence Pack	EvidencePackBuilder 并行获取 RAG+财务指标+本地新闻
6	估值强制取证	LiveGate 估值问题注入证据上下文，无证据时显示降级提示
7	结论格式	估值/风险/财报问题输出包含结论/依据/假设/引用来源四段式
8	LiveGate 综合分析	估值问题 LiveGate 返回基于实际工具数据的深度分析（非计划草案），包含 PE/PB/ROE 等具体数字

FilesExpand file tree

README.UserAgentTest.md

Latest commit

History

README.UserAgentTest.md

File metadata and controls

README.UserAgentTest

目的

环境前提

统一执行标记

顶层模块矩阵

推荐回归顺序

模块回归步骤

1. LLM 设置

入口点

预置数据

操作步骤

等待与判定

关键断言

失败分流

交叉断言

2. 财务数据测试

入口点

预置数据

操作步骤

等待与判定

关键断言

失败分流

交叉断言

3. 股票信息

入口点

预置数据

操作步骤

等待与判定

关键断言

失败分流

交叉断言

4. 情绪轮动

入口点

预置数据

操作步骤

等待与判定

关键断言

失败分流

交叉断言

5. 全量资讯库

入口点

预置数据

操作步骤

等待与判定

关键断言

失败分流

交叉断言

6. 股票推荐

入口点

预置数据

操作步骤

等待与判定

关键断言

失败分流

交叉断言

7. 治理开发者模式

入口点

预置数据

操作步骤

等待与判定

关键断言

失败分流

交叉断言

8. 交易日志

入口点

预置数据

操作步骤

等待与判定

关键断言

失败分流

交叉断言

跨模块联动场景与同步时序

场景 A：LLM 设置 -> 股票推荐 / 股票信息

场景 B：财务数据测试 -> 股票信息财务报表