AtlasSQL · 学习手册

切换主题

V0｜企业数据与工程基础 ​

状态：开发中。V0-S01～V0-S03 已完成；本文件是勾选状态的唯一来源。 依据：原始总纲第 35 节；以下故事、编号、接口与验收细则为本次实施设计。

阶段目标 ​

先建立真实、可复现、能暴露 NL2SQL 难题的数据环境。

  • 进入条件：无；先阅读项目总纲与本计划约定。
  • 规模 / 质量约束：7 个域、50～80 张表、600～1000 个字段；可生成百万级数据；100～150 道初始题。轻量数据仅用于开发自测，不替代阶段验收。
  • 阶段依赖：V0 → V1 → V2 → V3 → V4 → V5 → V6。故事内任务按编号顺序执行，故事间按下列依赖执行。
  • 建议路径均为规划位置，尚未存在；实现时允许简化文件拆分，但必须更新学习站真实代码索引。
  • 完成标准：本期任务全部满足 通用 DoD，证据登记到 验收记录。

V0-S01｜工程骨架与环境配置 ​

用户故事：作为开发者希望用统一命令启动工程，避免 AI 每次采用不同约定。

依赖：无。
建议落点：server/api、server/config.py、deploy、tests。
学习目标：模块化单体、配置分层、迁移与可复现构建。

开发任务 ​

  • V0-S01-T01 建立 Python 3.12+ / FastAPI / Pydantic / SQLAlchemy / Alembic 工程与 Next.js web、admin 应用骨架；补充根目录运行说明和版本锁文件。
  • V0-S01-T02 配置 Docker Compose：控制库 PostgreSQL、隔离的业务库、Milvus 及其依赖、OpenSearch、Redis；提供健康检查、持久卷和 .env.example。
  • V0-S01-T03 为配置增加类型校验与密钥脱敏；提供 liveness / readiness 接口和依赖不可用时的明确错误。
  • V0-S01-T04 建立格式检查、静态检查、pytest 与前端构建的 CI；记录本机资源用量、启动时间和降低数据量的开发参数。

验收场景 ​

全新环境按 README 可启动；停止 OpenSearch 后 readiness 失败而 liveness 仍成功；缺少必要配置时启动报出可定位错误。

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

V0-S02｜零售业务建模与指标口径草案 ​

用户故事：作为数据分析师希望先知道每张表一行代表什么，避免重复汇总与业务歧义。

依赖：V0-S01。
建议落点：datasets/schema、datasets/dictionary、semantic_models/drafts。
学习目标：事实粒度、维度、快照、桥表、指标可加性。

开发任务 ​

  • V0-S02-T01 为 Sales、Product、Customer、Store、Inventory、Finance、Marketing 分配表清单，合计 50～80 表和 600～1000 字段；输出域关系图。
  • V0-S02-T02 为每张表记录主键、外键、粒度、权威来源、时间含义、状态枚举、敏感等级和历史策略；覆盖多事实、一对多、多对多和快照。
  • V0-S02-T03 定义销售额、订单量、客单价、毛利率等首批指标草案，明确支付/订单时间、退款归属、时区、含税与否和零分母；由模拟业务负责人评审。
  • V0-S02-T04 生成可重复执行的迁移与只读业务账户，分离控制库身份和业务查询身份；设计区域和门店权限测试数据。

验收场景 ​

ER 图中的每个关系都有键与基数；订单明细与退款明细直接连接的反例能解释重复放大；指标冲突明确记录而非静默决定。

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

V0-S03｜确定性模拟数据与质量检查 ​

用户故事：作为测试工程师希望每次运行得到相同数据，才能判断模型变化是否真的带来改进。

依赖：V0-S02。
建议落点：datasets/generator、scripts/seed_data、tests/data。
学习目标：随机种子、数据分布、边界夹具与幂等导入。

开发任务 ​

  • V0-S03-T01 实现固定 seed、固定业务时钟、批量写入的数据生成器；提供 tiny、dev、scale 配置和安全的目标库校验。
  • V0-S03-T02 生成跨年销售、付款/退款、门店变更、库存快照、营销多对多和会员历史；包含空值、同名商品、内部编码及取消/测试订单。
  • V0-S03-T03 实现外键、金额对账、状态一致性和指标手算夹具校验；用明确配置隔离用于失败测试的脏数据。
  • V0-S03-T04 运行百万级 scale 数据生成并记录行数、耗时、空间、seed、schema_version、dataset_version 和快照校验摘要；提供安全重置命令。

验收场景 ​

相同 seed 和版本的 tiny 数据业务摘要一致；退款与订单金额可对账；scale 验收有实测记录，不能用配置宣称已生成百万行。

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

V0-S04｜数据源与元数据中心 ​

用户故事：作为数据管理员希望登记数据源并同步元数据，让后续检索建立在可信结构上。

依赖：V0-S01、V0-S02。
建议落点：server/datasource、server/metadata、migrations。
学习目标：控制面、幂等同步、数据库反射、人工注释保护。

开发任务 ​

  • V0-S04-T01 实现数据源登记、连接测试、最小权限检查与凭据引用；管理接口仅允许管理员访问且响应不回显密钥。
  • V0-S04-T02 采集表、列、键、索引、类型、可空性、注释、统计与经过脱敏的样例值，落入 PostgreSQL 元数据模型。
  • V0-S04-T03 支持业务名、别名、域、粒度、权威来源、敏感性人工补充；增量同步保留人工字段并标记删除对象。
  • V0-S04-T04 通过 Celery + Redis 执行同步任务，记录状态、幂等键、重试次数和 schema_version；用新增/改名/删除列夹具验证差异报告。

验收场景 ​

重复同步不产生重复元数据；删除列成为失效对象；源数据库断连任务失败可重试且不发布半成品快照。

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

V0-S05｜索引基础与缓存约定 ​

用户故事：作为平台工程师希望索引可从控制库重建，避免三个存储成为三个互相矛盾的真相。

依赖：V0-S04。
建议落点：server/search、server/llm/embedding、server/metadata/jobs。
学习目标：派生索引、最终一致性、版本与可观测重试。

开发任务 ​

  • V0-S05-T01 定义稳定文档 ID、对象类型、域、授权标签和 metadata_version；设计 OpenSearch mapping 与 Milvus collection schema。
  • V0-S05-T02 抽象 EmbeddingProvider，接入 BGE-M3 并保存模型版本和维度；以任务方式构建首批 schema 索引。
  • V0-S05-T03 实现控制库同步状态、失败重试与索引重建命令；索引发布前核对对象数和版本，禁止新旧快照混用。
  • V0-S05-T04 定义 Redis key 的数据源/版本/授权命名空间、TTL 与失效触发；通过基础写入/查询/失效 smoke 检查验证四类基础设施连通。

验收场景 ​

移除派生索引后可用控制库重建；嵌入维度变更不能直接写旧 collection；失败索引不会被标记为已发布。

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

V0-S06｜Benchmark v1 与数据隔离 ​

用户故事：作为评测负责人希望有独立题库和可信答案，为所有后续阶段提供可比较基准。

依赖：V0-S03、V0-S04。
建议落点：benchmarks/v1、server/evaluation、tests/fixtures。
学习目标：Gold SQL、结果比较、泄漏防范、实验固定变量。

开发任务 ​

  • V0-S06-T01 编写 100～150 道题，覆盖单表、Join、聚合、Top N、时间、同比/环比、值映射、指标、歧义和权限；各类至少有代表样本。
  • V0-S06-T02 记录 question_id、问题、Gold SQL 或预期拒绝/澄清、结果摘要、所需域/表/列/指标、身份、难度、固定日期和数据版本。
  • V0-S06-T03 将训练示例、调优集与锁定测试集按问题家族分离；Verified Query 不得收录锁定测试集及其近似改写。
  • V0-S06-T04 编写只读 Gold SQL 执行与结果比较工具；声明排序、集合/多重集、金额 Decimal 容差、NULL 和零分母规则并人工抽查。

验收场景 ​

同一快照重复跑 Gold 结果一致；故意调换行序不会误判无序查询，重复行不会被集合去重掩盖；拒绝题不要求危险 Gold SQL。

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

V0-S07｜基础管理界面与阶段复盘 ​

用户故事：作为学习者希望看见业务模型和同步状态，并能解释工程为什么这样划分。

依赖：V0-S04、V0-S05、V0-S06。
建议落点：apps/admin、altassql-book/stages、plan/evidence。
学习目标：API 分层、表单状态、从需求追溯到代码。

开发任务 ​

  • V0-S07-T01 实现数据源、域、表字段详情、同步任务状态页面；提供加载、空数据、校验失败和无权限状态。
  • V0-S07-T02 执行 V0 完整验收：四类设施、全部表字段、百万级数据、元数据同步和初始题库；记录实际命令与产物路径。
  • V0-S07-T03 更新学习站 V0 章节，补充真实入口、调用顺序、迁移关系、一个失败案例和设计决策；完成任务证据登记。

验收场景 ​

可从界面定位一张表的粒度、字段与同步版本；能脱离 AI 口述“控制库、业务库、索引”的区别；未通过规模验收时不标记阶段完成。

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

阶段演示与复盘 ​

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

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

需求 → 代码 → 验证 → 复盘

AtlasSQL · 企业级工程与学习实践