项目全景：AtlasSQL 要解决什么
AtlasSQL 要把企业业务人员的自然语言，可靠地映射到数据模型、指标定义和权限体系，再生成安全可执行、业务语义正确的 SQL。它的学习价值在于：每一次架构演进，都能用上一版的真实失败来解释。
业务背景
NovaRetail 是模拟的中大型零售集团，经营线上商城、线下门店和会员体系。销售、库存、营销与财务数据分布在多个系统，普通业务用户既不知道表结构，也不一定知道指标口径。
传统问数需要业务提出问题、分析师找表并确认口径、写 SQL、取数、再确认。AtlasSQL 希望缩短这个过程，同时保留口径、权限与审计边界。
六层核心能力
| 层 | 负责的问题 | 验证方式 |
|---|---|---|
| Metadata Intelligence | 数据在哪里，一行是什么含义 | 采集完整性、粒度与关系校验 |
| Retrieval & Linking | 哪些表列和值与问题对应 | 召回率、链接与路径准确性 |
| Business Semantics | “净销售额”到底怎么算 | 指标规则、版本回归 |
| Planning & Generation | 如何组织计算并表达为 SQL | IR 校验、SQL 与 Gold 对比 |
| Governance & Execution | 用户能查吗，数据库承受得住吗 | 授权拒绝、成本与只读测试 |
| Evaluation & Ops | 升级是否退化，出错如何定位 | 逐题评测、Trace、发布门禁 |
企业级与教学型如何同时成立
企业级体现在约束可执行：索引有版本，SQL 有检查，权限贯穿检索与执行，失败可定位，升级可回归。多引入几个中间件本身不证明企业级。
教学型体现在演进可解释：V1 故意保留固定小 Schema 的简单基线；V2 对准选表、选列和值错误；V3 处理业务口径；V4 完善计划与治理。V5 再引入 Agent，避免框架掩盖基础流程。
代码风格遵守仓库 AGENT.md：不要炫技，保持简洁、易读、易维护。优先显式调用、明确类型和可复现用例；每增加一个抽象，都应指出它隔离了什么变化。
当前事实与目标
| 项目 | 当前状态 | 计划目标 |
|---|---|---|
| 业务代码 | 尚未建立 | FastAPI + Next.js 两个产品端 |
| 数据基础 | 只有模型设计要求 | 7 域、50～80 表、600～1000 字段 |
| 数据量 | 尚未生成 | 百万到千万级模拟数据 |
| 指标 / 可信查询 | 尚未建设 | 30～50 指标、200+ 样例 |
| Benchmark | 尚未建设 | V0 100～150 题，最终 500+ |
| 准确率 / 性能 | 待测 | 按各期目标与实际环境验证 |
| 本次交付 | 文档与学习工具 | 40 个故事、136 个任务、学习手册 |
原始总纲里给出的 88.7% → 91.2%、P95 5.4s → 4.8s 等属于展示示例，不是项目成绩。总纲引用的厂商实践也保留为原文背景，不作为本项目已验证的证据。
范围边界
本轮先覆盖零售业务和 PostgreSQL 业务库，数据源适配接口为未来扩展保留边界。跨异构数据库联邦执行、复杂租户计费、任意 Python 分析沙箱均不属于当前计划。企业权限先实现用户、角色、域、区域、门店与列级约束。
Next.js 是未来业务端技术；VitePress 是当前学习站。二者服务不同读者，不相互替代。