AtlasSQL 分期开发计划

本计划服务于两个目标：交付企业级 NL2SQL 系统；让学习者通过 AI 生成的实现，掌握业务、架构、测试和面试表达。

当前业务实现状态：尚未开始。 已有项目总纲；本次建立开发计划与学习站，不代表 V0 基础设施已完成。

原始资料位于仓库的 docs/PROJECT.md（目录名前有一个空格），代码风格约定位于 AGENT.md：追求简洁明了、易读易维护。保留原始资料与原有空目录 docs/plan，根目录 plan/ 是后续唯一任务台账。

怎样使用

1. 先读当前阶段目标、故事依赖和验收条件，选择最早未完成且依赖满足的任务。
2. 一次让 AI 完成一个任务或一个紧密相关的故事；先看输入/输出和验收，再看实现。
3. 完成后运行相应检查，在 plan/evidence/ 保存证据，更新学习站真实代码关系。
4. 仅将该任务的 - [ ] 改为 - [x]，保留任务 ID；未验证的任务保持未勾选。
5. altassql-book 启动和构建时同步计划；开发预览中保存计划会刷新。浏览器勾选框只展示仓库状态，不会写回文件。

故事编号 V2-S03，任务编号 V2-S03-T02。状态字段不承载进度；只有任务复选框是计数来源。任务被拆分时追加新 ID，已有 ID 不复用；依赖调整同时更新覆盖矩阵。

阶段路线

阶段	解决的问题	用户故事	任务	开发计划
V0	先建立真实、可复现、能暴露 NL2SQL 难题的数据环境。	7	27	企业数据与工程基础
V1	限定 Sales 的 10～15 张表，跑通最小安全链路并发现真实失败。	5	16	可测量的问数基线
V2	从大 Schema 中找到正确的表、字段、值和合法关联路径。	6	19	混合检索与 Schema Linking
V3	让“销售额怎么算”成为版本化业务资产，让生成 SQL 遵循统一口径。	6	19	业务语义与可信查询
V4	把业务理解、查询计划、安全执行和结果验证组成可治理的生产候选系统。	6	23	企业级安全问数 1.0
V5	复用 V4 受控能力，支持多步分析、多轮上下文与有预算的工具编排。	5	15	Agentic 数据分析师
V6	使每次模型、Prompt、检索和语义变更都能被评测、监控与回滚。	5	17	评测运营与持续演进

V0 全部数据基础 → V1 小范围可测基线 → V2 检索与链接 → V3 语义治理 → V4 企业级 1.0 → V5 Agent 分析 → V6 持续运营。

统一完成定义

任务只有同时满足以下条件，才可勾选：

• 业务行为符合任务及所属故事验收；正常和关键失败路径均有证据。
• 代码遵守 AGENT.md，依赖方向明确；配置无密钥，错误可定位。
• 相关检查通过：业务规则用单元测试，存储边界用集成测试，关键用户流程用端到端或演示记录；不为凑覆盖率重复实现。
• 记录真实执行命令、环境/数据版本、结果摘要、代码入口和遗留限制；测试失败不能被“已写测试”替代。
• 学习站更新该任务的“业务问题 → 代码入口 → 调用顺序 → 测试 → 取舍”；学习者能够用自己的话解释关键逻辑。

阶段完成要求全部任务及阶段规模/质量门槛达成。任务数比例只表示实现进度，不代表工作量、质量或上线准备度。故事一般需多次开发会话；不在未了解硬件和时间投入前虚构工期。

范围和细化决策

项目	原文要求	本次落地约定
基础设施	V0 起 PostgreSQL、Milvus、OpenSearch、Redis；无 pgvector 过渡	保留；开发数据可小，阶段验收仍要求规模证据
部署结构	完整企业级模块与基础设施	先模块化单体 + worker；模块边界不等于微服务
数据源方言	未明确第一种业务库	首先使用 PostgreSQL 业务库；与控制库分离；多方言后续按需求扩展
数量目标	30～50 指标、200+ 可信样例、500+ 问题为最终目标	指标与可信样例安排 V3 达成，500+ 题安排 V6 达成
基础安全	V1 SQLGlot + read-only；V4 完整治理	V1 必须只读、单语句、允许对象、超时；不推迟至 V4
多轮与图表	最终用户端功能	V4 完整图表，V5 结构化多轮和多步分析
语义发布回归	V3 发布前 Benchmark	V3 有必要回归；V6 扩展为完整运营平台
指标口径	总纲示例未完全定义退款/时间含义	V0 草案评审；书中例子标为教学假设，不能直接当生产定义

变更需要记录背景、影响任务、验收修改及原因；不通过删任务规避目标。

开发入口

• 需求覆盖矩阵
• 给 AI 的执行约定
• 验收证据模板