V1｜可测量的问数基线

状态：已完成。任务勾选状态以本文件为唯一来源。 依据：原始总纲第 36 节；以下故事、编号、接口与验收细则为本次实施设计。

阶段目标

限定 Sales 的 10～15 张表，跑通最小安全链路并发现真实失败。

• 进入条件：V0 验收通过；选择并冻结 Sales 子集。
• 规模 / 质量约束：形成可复现 Baseline 与失败分类；不预设准确率，不将示意百分比当实测。
• 阶段依赖：V0 → V1 → V2 → V3 → V4 → V5 → V6。故事内任务按编号顺序执行，故事间按下列依赖执行。
• 建议路径均为规划位置，尚未存在；实现时允许简化文件拆分，但必须更新学习站真实代码索引。
• 完成标准：本期任务全部满足 通用 DoD，证据登记到 验收记录。

V1-S01｜问数契约与固定范围

用户故事：作为业务用户希望提交问题并得到可理解的成功、澄清或拒绝状态。

依赖：V0-S07。
建议落点：server/api/query、server/orchestrator、server/domain。
学习目标：请求状态机、明确依赖、领域边界。

开发任务

• V1-S01-T01 定义 QueryRequest / QueryResponse / QueryTrace 契约，包含 question、session_id、trace_id、status、SQL、列、行和错误码。
• V1-S01-T02 固定 Sales 的 10～15 张表和允许字段清单；明确 V1 无跨域自动检索，多义指标采用显式草案或澄清。
• V1-S01-T03 建立显式函数调用的 QueryOrchestrator，传递身份、数据版本、模型版本与超时预算；保存请求与状态。

验收场景

销售问题进入固定链路；库存问题返回范围限制；空问题与过长问题被校验，内部异常不原样暴露给用户。

完成后应提供：相关测试或演示命令、实际结果、真实代码入口和一段“为什么这样做”的说明。仅创建文件不满足验收。

V1-S02｜模型网关与基线生成

用户故事：作为开发者希望模型调用统一记录与替换，避免业务模块绑定 SDK。

依赖：V1-S01。
建议落点：server/llm、server/generation。
学习目标：Provider 适配、结构化响应、Prompt 可复现。

开发任务

• V1-S02-T01 定义 LLMGateway 输入输出与异常，接入一个实际可用 Provider；提供确定性 fake 用于离线开发和超时测试。
• V1-S02-T02 实现版本化 Prompt Builder，加入固定 schema、方言、允许范围与示例；记录 prompt_hash、模型参数和 token 用量。
• V1-S02-T03 解析结构化 SQL 输出，限制输出长度与模型重试；对无 SQL、格式错误、限流、超时返回类型化失败。

验收场景

同一请求可用 fake 重放；切换 Provider 不修改 orchestrator；日志中没有 API Key 或业务敏感值。

完成后应提供：相关测试或演示命令、实际结果、真实代码入口和一段“为什么这样做”的说明。仅创建文件不满足验收。

V1-S03｜最小 SQL 安全与只读执行

用户故事：作为平台管理员希望即使是基线版本也不能执行写操作或无限查询。

依赖：V1-S02。
建议落点：server/validation、server/execution。
学习目标：AST 检查、最小权限、超时与结果上限。

开发任务

• V1-S03-T01 用 SQLGlot 验证单条查询 AST、允许表字段和函数；拒绝 DDL/DML、多语句、SELECT INTO、写 CTE 与危险函数。
• V1-S03-T02 实现只读账号和只读事务执行，配置 statement_timeout、并发上限、最大返回行数；正确关闭连接并支持取消。
• V1-S03-T03 将生成、校验、执行串联；为嵌套查询、注释绕过、未知列和慢查询建立正反例，确认无效 SQL 到不了执行器。

验收场景

正常 SELECT 成功；包含写 CTE 的 SELECT 被拒；超时后连接池仍可服务；返回行数有限且截断标记明确。

完成后应提供：相关测试或演示命令、实际结果、真实代码入口和一段“为什么这样做”的说明。仅创建文件不满足验收。

V1-S04｜用户端结果与基础解释

用户故事：作为业务用户希望看到表格、SQL 和数据来源，而不只看到模型一句话。

依赖：V1-S03。
建议落点：apps/web、server/api、server/generation/answer。
学习目标：前后端契约、错误展示、证据约束。

开发任务

• V1-S04-T01 实现提问、处理中、成功表格、空结果、澄清、拒绝和失败状态；提供 SQL 与使用表字段的详情。
• V1-S04-T02 将列类型映射到展示格式，保留金额精度和日期时区；明确空值、截断结果和执行时间。
• V1-S04-T03 生成仅依据返回结果的摘要，为请求错误提供 trace_id；防止重复提交和把原始 SQL/模型 HTML 直接注入页面。

验收场景

空结果不会显示“销售额为零”；摘要数值与表格一致；请求失败可重试且用户输入保留。

完成后应提供：相关测试或演示命令、实际结果、真实代码入口和一段“为什么这样做”的说明。仅创建文件不满足验收。

V1-S05｜Trace 与失败分类基线

用户故事：作为数据分析师希望知道错误发生在哪一层，为 V2 提供改进依据。

依赖：V1-S03、V0-S06。
建议落点：server/observability、server/evaluation、apps/admin。
学习目标：分阶段定位、错误归因、基线与变量控制。

开发任务

• V1-S05-T01 记录生成、校验、执行阶段耗时、候选 SQL、脱敏错误、模型/Prompt/数据版本；管理端增加 Trace 列表与详情。
• V1-S05-T02 在冻结 Sales 子集运行评测，记录语法有效率、执行正确率、首次成功率、时延与 token 成本。
• V1-S05-T03 人工复核失败，标注 Wrong Table/Column/Join/Value/Metric/Time/Aggregation、Syntax Error 与无法确定原因。
• V1-S05-T04 输出错误样本、分母和对比基线；据高频根因排序 V2 工作，更新学习站实测报告与代码导读。

验收场景

每个失败可回到题目、SQL 和 trace；报告中同时给样本数与环境；没有实测时结果保持“待测”。

完成后应提供：相关测试或演示命令、实际结果、真实代码入口和一段“为什么这样做”的说明。仅创建文件不满足验收。

阶段演示与复盘

1. 从本期故事选一条完整用户流程，按输入 → 中间产物 → 输出演示。
2. 演示上述验收中的一个失败/拒绝场景，解释负责处理的模块。
3. 固定环境和数据版本，提交本期验收报告；未达到的目标登记阻塞原因。
4. 在学习站 stages/v1.md 补充已实现代码入口、调用关系、实测结果及面试复述。
5. 复查本期 5 个用户故事、16 个开发任务的证据，再由执行者勾选。

复盘问题：本期解决了上一期哪类具体失败？增加了什么复杂度？有什么证据证明收益？下一期需要解决什么剩余问题？