V3｜业务语义与可信查询
状态：待开发。全部任务默认未完成；本文件是勾选状态的唯一来源。 依据：原始总纲第 38 节；以下故事、编号、接口与验收细则为本次实施设计。
阶段目标
让“销售额怎么算”成为版本化业务资产，让生成 SQL 遵循统一口径。
- 进入条件：V2 召回与链接接口稳定，V0 指标草案可评审。
- 规模 / 质量约束：建立 30～50 个核心指标及累计 200+ Verified Queries（本次将最终数量目标安排于 V3），全部具有版本与审核证据。
- 阶段依赖：V0 → V1 → V2 → V3 → V4 → V5 → V6。故事内任务按编号顺序执行，故事间按下列依赖执行。
- 建议路径均为规划位置，尚未存在；实现时允许简化文件拆分，但必须更新学习站真实代码索引。
- 完成标准：本期任务全部满足 通用 DoD，证据登记到 验收记录。
V3-S01｜语义模型与指标注册表
用户故事：作为数据分析师希望显式定义指标粒度和适用范围，避免各部门计算不一致。
依赖：V2-S06。
建议落点：server/semantic、semantic_models、migrations。
学习目标：语义层、可加性、实体与度量。
开发任务
- V3-S01-T01 定义 Metric、Measure、Dimension、Entity、Filter、Relationship、Glossary、FiscalCalendar 模型与校验规则。
- V3-S01-T02 实现指标表达式、依赖字段、强制过滤、允许维度、时间角色、单位、币种和同义词注册；指标 ID 不以展示名作为主键。
- V3-S01-T03 按业务域整理 30～50 个核心指标，以手算数据验证销售额、客单价、毛利率、复购率和库存快照汇总方式。
验收场景
毛利率由聚合收入和成本计算而非平均行级比例；库存期末值不能跨天简单求和；不兼容维度被拒绝。
完成后应提供：相关测试或演示命令、实际结果、真实代码入口和一段“为什么这样做”的说明。仅创建文件不满足验收。
V3-S02｜语义生命周期与发布
用户故事：作为业务负责人希望口径更新先回归再发布，并能回滚旧版本。
依赖：V3-S01。
建议落点：server/semantic/lifecycle、server/evaluation、apps/admin。
学习目标：状态机、不可变版本、发布原子性。
开发任务
- V3-S02-T01 实现 Draft → Testing → Published → Deprecated 状态机、版本快照和变更审计；已发布版本禁止原地修改。
- V3-S02-T02 将发布与相关 Benchmark 回归、审核结果绑定；前端提供版本差异、测试结果和发布/回滚操作。
- V3-S02-T03 发布后原子切换 active_version，触发 Milvus/OpenSearch 重建与 Redis 失效；保留旧快照支持在途请求和回滚。
验收场景
回归失败不能发布；请求开始时固定语义版本，发布中途不会混用新旧口径；回滚后查询及索引版本一致。
完成后应提供：相关测试或演示命令、实际结果、真实代码入口和一段“为什么这样做”的说明。仅创建文件不满足验收。
V3-S03｜术语、维度与业务规则管理
用户故事：作为业务用户希望自然表达能被组织术语解释，而不是依赖一个巨大 Prompt。
依赖：V3-S01。
建议落点：server/semantic/glossary、server/linking、apps/admin。
学习目标：术语冲突、规则组合、语义链接。
开发任务
- V3-S03-T01 实现术语、同义词、维度和规则管理界面，关联域、负责人、版本和权威定义。
- V3-S03-T02 建立 semantic_embeddings / business_term_embeddings 与 lexical 索引，接入统一检索与授权过滤。
- V3-S03-T03 将意图片段链接到指标 ID 与维度 ID；处理同名指标、财年/自然年、订单/支付时间冲突并输出澄清。
验收场景
“销售收入”匹配的指标带口径版本；财务与销售同名口径冲突可见；未发布定义不会进入线上上下文。
完成后应提供：相关测试或演示命令、实际结果、真实代码入口和一段“为什么这样做”的说明。仅创建文件不满足验收。
V3-S04｜Verified Query 仓库
用户故事：作为分析师希望审核过的问题与 SQL 成为可复用经验，而不会污染测试集。
依赖：V3-S02、V2-S02。
建议落点：server/semantic/verified_queries、apps/admin、benchmarks。
学习目标：动态 few-shot、审核、数据泄漏。
开发任务
- V3-S04-T01 实现问题、SQL、域、语义/schema 版本、描述、标签、审核人/时间与版本存储，维护 draft/verified/invalid 状态。
- V3-S04-T02 审核前执行语法、版本兼容与只读结果校验；构建累计 200+ 样例，近似重复与锁定测试家族必须隔离。
- V3-S04-T03 接入问题/SQL embedding 与文本索引，按域、权限、版本动态选择 Top K；模型上下文引用来源 ID。
- V3-S04-T04 支持样例搜索、审批、失效和历史；语义或 schema 变动后重验依赖样例，不自动继承可信状态。
验收场景
无权限或旧版本样例不能被召回；人工审核有可追溯证据；200 条重复改写不能冒充 200 个有效覆盖样例。
完成后应提供：相关测试或演示命令、实际结果、真实代码入口和一段“为什么这样做”的说明。仅创建文件不满足验收。
V3-S05｜语义上下文组装与问数展示
用户故事：作为业务用户希望看见生成 SQL 采用的指标、规则和参考样例。
依赖：V3-S03、V3-S04。
建议落点：server/generation/context、server/generation、apps/web。
学习目标：上下文边界、Prompt 注入防护、口径可解释性。
开发任务
- V3-S05-T01 组合 selected schema、join path、语义定义、值映射、业务规则和 verified examples，约束 token 预算并保存来源。
- V3-S05-T02 明确元数据注释和样例文本为不可信数据；过滤越权对象，禁止其中指令覆盖系统策略。
- V3-S05-T03 在基线生成器中接入语义 Context；结果页展示指标定义、过滤、维度、时间窗口和版本。
验收场景
销售额 SQL 包含有效状态和排除测试数据规则；含“忽略权限”的表注释不能改变系统策略；上下文裁剪不丢强制规则。
完成后应提供：相关测试或演示命令、实际结果、真实代码入口和一段“为什么这样做”的说明。仅创建文件不满足验收。
V3-S06｜业务语义回归与复盘
用户故事：作为评测负责人希望证明指标口径正确，而不只证明 SQL 可以运行。
依赖：V3-S05。
建议落点：server/evaluation/semantic、benchmarks、altassql-book/stages。
学习目标：语义正确性、指标归因、可信样例覆盖。
开发任务
- V3-S06-T01 新增指标、强制过滤、粒度、时间、财年、退款与多事实专题样本，并与锁定测试集保持隔离。
- V3-S06-T02 比较 V2/V3 的 Wrong Metric、Wrong Time、Wrong Aggregation 和整体执行结果；归因新增检索的成本。
- V3-S06-T03 记录至少一个“表列都对但指标错”的修复过程，更新语义模型教程、真实代码入口与任务证据。
验收场景
结果正确性同时有 Gold/规则与人工复核证据；不能靠 LLM 自评分宣布准确；发布回归可重复运行。
完成后应提供：相关测试或演示命令、实际结果、真实代码入口和一段“为什么这样做”的说明。仅创建文件不满足验收。
阶段演示与复盘
- 从本期故事选一条完整用户流程，按输入 → 中间产物 → 输出演示。
- 演示上述验收中的一个失败/拒绝场景，解释负责处理的模块。
- 固定环境和数据版本，提交本期验收报告；未达到的目标登记阻塞原因。
- 在学习站
stages/v3.md补充已实现代码入口、调用关系、实测结果及面试复述。 - 复查本期 6 个用户故事、19 个开发任务的证据，再由执行者勾选。
复盘问题：本期解决了上一期哪类具体失败？增加了什么复杂度？有什么证据证明收益？下一期需要解决什么剩余问题？