附录 C · 仓库地图¶
本地图帮助开发者快速定位 TTD monorepo 中的文件与模块。
根目录¶
the-ttd/
├── backend/ # Python 后端：FastAPI + LangGraph Agentic BI 编排
├── web/ # 前端：Next.js 16 + React 19 + Zustand + shadcn/ui
├── semantic-plane/ # 语义治理层：YAML 元数据资产 + JSON Schema + CI 校验
├── data-plane/ # 数据执行层：PostgreSQL(AGE+pgvector) + pg_mooncake + MinIO
├── deploy/ # 部署编排：docker-compose + Docker Swarm(HAProxy)
├── scripts/ # 根级 CI 校验工具（YAML/SQL/跨层引用/版本号）
├── docs/ # MkDocs Material 文档（本站点）
├── .github/ # GitHub Actions workflows
├── pyproject.toml # uv workspace 根配置（backend, data-plane 成员）
├── Taskfile.yml # 统一任务编排（be/dp/sp/web/deploy 命名空间）
├── .env.example # 共享环境变量（全部 TTD_ 前缀）
├── mkdocs.yml # 文档站点配置
└── uv.lock # Python 依赖锁文件
backend/ — 后端核心¶
backend/
├── app/
│ ├── main.py # FastAPI 入口 + lifespan + instance registration
│ ├── config.py # Pydantic Settings（TTD_* 环境变量）
│ ├── deps.py # FastAPI 依赖注入 + distributed lock
│ ├── errors.py # 异常层次 + 错误 sanitization
│ ├── schemas.py # API 请求/响应 Pydantic models
│ ├── agents/
│ │ ├── builder.py # build_supervisor_graph() 图构建（第 4 章）
│ │ ├── state.py # AgenticBIState TypedDict（第 4 章）
│ │ ├── supervisor.py # Supervisor 节点
│ │ ├── embedding.py # Embedding 工具函数
│ │ ├── sub_agents/ # 所有 Sub-agent（第 4 章）
│ │ │ ├── query_understanding.py
│ │ │ ├── router.py # 7 路由决策
│ │ │ ├── planner.py # Plan-and-Execute
│ │ │ ├── data_retrieval.py
│ │ │ ├── sql_generation.py # SQL 生成（第 6 章）
│ │ │ ├── guardrails.py # 五层护栏（第 6 章）
│ │ │ ├── visualization.py
│ │ │ ├── insights.py
│ │ │ ├── analytical.py # ML 分析（第 8 章）
│ │ │ ├── schema_explorer.py
│ │ │ ├── sql_explainer.py
│ │ │ ├── knowledge_qa.py
│ │ │ ├── followup.py
│ │ │ └── suggest_followup.py
│ │ ├── evaluators/ # 三级评估器（第 15 章）
│ │ └── semantic_plane/ # 语义层导入管道（第 9 章）
│ ├── semantic/ # 语义查询规划器（第 6 章）
│ │ ├── query_contract.py
│ │ ├── router.py # KMB Steiner 树
│ │ ├── rewrite.py # 三大代数重写
│ │ ├── sql_compiler.py # SQLGlot 编译
│ │ └── planner_node.py
│ ├── skills/ # AI 技能（第 5/8 章）
│ │ ├── rag.py # R/V/G/D 四引擎检索（61KB，最核心）
│ │ ├── reranker.py # 重排序
│ │ ├── corrective_retrieval.py # 补偿检索
│ │ ├── graph_rag.py # NL2Cypher
│ │ ├── sql_executor.py # 数据面执行器
│ │ ├── sql_column_validator.py # AST 列校验
│ │ ├── visualization.py # 可视化推荐
│ │ ├── chart_templates/ # 35+ 图表模板
│ │ ├── metadata_cache.py
│ │ ├── context_compactor.py
│ │ ├── query_decomposer.py
│ │ └── governance.py
│ ├── tools/ # 工具（第 8 章）
│ │ ├── ml/ # 6 个 ML 工具
│ │ └── interpreter/ # 代码沙箱
│ ├── memory/ # 四层记忆（第 7 章）
│ │ ├── facade.py # 统一入口
│ │ ├── formation.py # 记忆形成
│ │ ├── long_term.py # 长期记忆
│ │ ├── short_term.py # 短期记忆
│ │ ├── sql_cache.py # SQL 语义缓存
│ │ ├── dynamic_few_shot.py # 动态 few-shot
│ │ └── term_mapping.py
│ ├── models/ # 多模型注册表（第 4 章）
│ │ └── registry.py
│ ├── prompt/ # Prompt 管理（第 6 章）
│ │ ├── assembler.py # Prompt 组装
│ │ └── manager.py
│ ├── security/ # 安全（第 14 章）
│ │ ├── auth.py # JWKS 验签
│ │ ├── guard.py # Content Safety
│ │ └── policy.py # 权限过滤
│ ├── observability/ # 可观测性（第 14 章）
│ │ ├── facade.py # 统一网关
│ │ ├── langfuse_adapter.py
│ │ ├── automq_exporter.py
│ │ ├── events.py
│ │ └── spans.py
│ ├── audit/ # 审计日志
│ ├── session/ # 会话管理
│ ├── runtime/ # Agent Runtime Pool
│ │ ├── registry.py # 实例注册 + heartbeat
│ │ └── lifecycle.py # Graceful shutdown
│ ├── api/ # FastAPI 端点（第 11 章）
│ │ ├── chats.py # Chat BI API
│ │ ├── stream.py # SSE 流式
│ │ ├── admin/ # 20+ Admin 端点
│ │ └── ...
│ ├── db/ # SQLAlchemy ORM
│ │ └── models.py # 39KB，所有表模型
│ ├── repositories/ # 数据访问层
│ └── services/ # 业务逻辑层
├── alembic/ # 数据库迁移（11 个版本）
├── tests/ # 测试
├── Dockerfile
├── docker-compose.yml
├── Taskfile.yml
└── pyproject.toml
web/ — 前端¶
web/
├── app/
│ ├── (auth)/ # 登录/注册
│ ├── (chat)/chat/ # 对话主界面 + admin/
│ └── api/ # auth/[...all], token, v1/[...path] 反代
├── components/
│ ├── chat/ # 流式消息、思考步骤
│ ├── results/ # 结果表、图表、下钻、ML/知识/图面板
│ ├── query/ # 查询组件
│ ├── admin/ # 管理后台组件
│ ├── landing/ # 落地页
│ └── ui/ # 62 个 shadcn 组件
├── stores/ # Zustand（chat/query-workspace/session-detail/ui-preferences）
├── hooks/ # use-chat-stream, use-models, use-few-shots, use-evaluation...
├── lib/
│ ├── auth.ts # Better Auth 配置
│ ├── api/
│ │ ├── generated/ # openapi-ts 生成客户端
│ │ ├── sse-schema.ts # SSE 事件 Zod schema
│ │ ├── query-stream.ts
│ │ └── chat-stream.ts
│ └── chart-templates/ # 前端图表模板
└── package.json
semantic-plane/ — 语义治理资产¶
semantic-plane/
├── domains/ # Layer 1: table_asset（含 metrics/ 子目录）
├── terms/ # Layer 1+2: business_term
├── term_relationships/ # Layer 2: 术语关系
├── few_shots/ # Layer 1: few-shot 示例
├── join_rules/ # Layer 1: JOIN 规则
├── business_rules/ # Layer 3
├── business_contexts/ # Layer 3
└── schemas/ # 8 个 JSON Schema
data-plane/ — 数据执行环境¶
data-plane/
├── docker-compose.yml # PG Supernode + pg_mooncake + MinIO + AutoMQ
├── sql/
│ ├── 001_create_schema.sql # semlayer schema + pgvector + AGE
│ └── 100_hm_create_schema.sql # H&M gold 表
└── scripts/
├── load_hm_data.py # 加载 H&M 数据
└── publish_semantic_plane.py # 发布 YAML 到 S3
deploy/ — 部署编排¶
deploy/
├── docker-compose.yml # 本地全栈
└── swarm/
├── docker-compose.swarm.yml # Swarm HA
└── haproxy.cfg # 一致性哈希配置
scripts/ — CI 校验工具¶
scripts/
├── validate_all_yaml.py # JSON Schema 校验
├── validate_sql_definitions.py # metric SQL 语法
├── validate_cross_layer_refs.py # 跨层引用
├── check_version_bump.py # 版本号检查
├── build_changeset.py # 增量 changeset
├── build_full_changeset.py # 全量 changeset
└── analyze_metadata_diff.py # 变更影响分析
按角色推荐阅读顺序¶
| 角色 | 阅读顺序 |
|---|---|
| 后端开发 | agents/builder.py → state.py → sub_agents/router.py → skills/rag.py → semantic/ |
| 前端开发 | web/app/(chat)/ → stores/chat-store.ts → lib/api/sse-schema.ts → components/results/ |
| 数据治理 | semantic-plane/ → scripts/validate_*.py → backend/app/agents/semantic_plane/ |
| 运维 | data-plane/docker-compose.yml → deploy/swarm/ → backend/app/runtime/ → backend/app/observability/ |