课程地图：从数仓到 Data Agent 产品

1. 课程目标

这套课程的目标不是教会学习者复制一个仓库，而是建立一套可迁移的方法：面对一个新的业务领域，能够从问题清单出发，设计数据模型和指标契约，再构建受控、可评测、可交付的 Data Agent。

课程最终交付一个完整项目，但项目只是方法的载体。

先用这张图建立“模型、语义层、查询服务、安全执行、可信回答”的整体认知，再进入各章的实现细节。

2. 三条学习路径

路径 A：数据工程师

重点章节：01 -> 02 -> 03 -> 06 -> 10

学习目标：掌握 AI 应用需要怎样的数仓、语义层、安全查询和评测底座。第 4、5 章只需要理解 Agent 如何消费这些能力。

路径 B：后端与 AI 应用工程师

重点章节：01 -> 03 -> 04 -> 05 -> 06 -> 07 -> 09

学习目标：掌握规则和大模型的职责拆分、结构化规划、工具调用、上下文持久化和报告快照。

路径 C：独立开发者与交付负责人

建议完整学习 01 -> 10。

学习目标：不仅做出功能，还能定义边界、准备评测、部署系统并形成可售卖的交付包。

3. 章节依赖

01 业务问题与产品边界
        |
        v
02 数仓模型 -----> 03 指标语义层
                         |
                         v
04 规则型 Agent -> 05 大模型规划器
                         |
                         v
06 SQL 安全与执行 -> 07 多轮会话与下钻
                         |
                         v
08 Web 工作台 -----> 09 报告版本化
                         |
                         v
                 10 评测、部署与售卖

第 2 章和第 3 章是整套课程的地基。跳过它们直接学习大模型规划，容易做出一个会写 SQL、但不知道业务口径是否正确的聊天工具。

4. 章节说明

第 1 章：业务问题与产品边界

核心问题：为什么 Data Agent 不能从聊天界面开始设计？

学习内容：目标用户、标准问题、可信回答契约、已实现能力和暂不承诺的边界。

动手产物：20 个标准问题、指标词典初稿、第一版验收标准。

第 2 章：电商数仓建模

核心问题：怎样的数据结构才能让 Agent 稳定分析？

学习内容：业务过程、粒度、事实表、维度表、主题汇总和质量测试。

动手产物：ODS、DIM、DWD、DWS 模型 SQL 和模型说明书。

第 3 章：指标语义层

核心问题：如何让“销售额”“转化率”不再由模型临时解释？

学习内容：指标表达式、来源表、时间字段、可用维度、同义词和口径测试。

动手产物：metrics.yaml 和至少 6 个核心指标的基准查询。

第 4 章：规则型 Data Agent

核心问题：不用大模型，能否跑通从问题到结论的闭环？

学习内容：指标识别、维度识别、时间推理、分析模板和确定性解释。

动手产物：单指标、排名、趋势和渠道诊断四种分析路径。

第 5 章：结构化大模型规划器

核心问题：大模型如何参与分析，又不获得数据库控制权？

学习内容：Structured Outputs、模型适配器、Schema 校验、降级策略和成本边界。

动手产物：可切换的 auto/rules/llm 三种运行模式。

第 6 章：SQL 安全、执行与证据链

核心问题：如何证明 Agent 执行的是只读、可追踪查询？

学习内容：SQL AST、危险语句拦截、表白名单、结果限制、SQL 记录和 trace。

动手产物：安全校验器、查询服务和攻击用例测试。

第 7 章：多轮会话与安全下钻

核心问题：如何让“为什么”“具体是哪些商品”沿用正确上下文？

学习内容：会话状态、轮次快照、上下文计划、过滤条件白名单和 SQLite WAL。

动手产物：可重启恢复的会话 API 和三个下钻案例。

第 8 章：Web 分析工作台

核心问题：怎样把复杂分析链路呈现给非技术用户？

学习内容：会话导航、结论层级、结果可视化、SQL 抽屉、错误状态和移动端设计。

动手产物：可以实际提问和追问的同源 Web 工作台。

第 9 章：报告版本化

核心问题：怎样让一次分析结论在后续追问后仍然可复核？

学习内容：不可变快照、会话内版本号、数据库事务、历史渲染和 Markdown 导出。

动手产物：报告 API、报告库和报告删除流程。

第 10 章：评测、部署与商业交付

核心问题：怎样证明项目可用，并让购买者能够成功运行？

学习内容：标准问题集、数值评测、失败分类、Docker、安装排错、授权和支持边界。

动手产物：评测报告、Release 包、部署文档和销售交付清单。

5. 每章统一交付标准

每一章都必须同时具备：

1. 一个清晰的业务问题。
2. 一套可解释的设计原则。
3. 一张能独立阅读的图。
4. 与参考实现对应的代码入口。
5. 一个学习者必须完成的动手任务。
6. 一组可执行或可检查的验收标准。
7. 常见失败和排查方法。
8. 可以录制成视频的演示场景。

详细格式见 appendix/chapter-writing-standard.md。

6. 整体结课项目

结课时，学习者需要现场完成以下链路：

加载电商样例数据
-> 构建分层数仓
-> 验证核心指标
-> 用自然语言发起渠道诊断
-> 查看计划、趋势图和 SQL
-> 继续下钻具体商品
-> 保存报告快照
-> 运行自动评测

验收时不能只展示页面截图，还必须解释：

• 当前问题使用了哪个指标口径。
• 查询为什么选择这张 DWS 或 DWD 表。
• 大模型失败时系统如何降级。
• SQL 在执行前经过了哪些安全检查。
• 报告为什么能够保持历史数据不变。

7. 资料建设状态

这里的“待整理”不是没有实现，而是尚未达到可独立售卖教程的写作标准。