V0｜企业数据与工程基础

实现状态：已完成。V0-S01～V0-S07 全部 27 个任务通过验收。

这一期学会什么：一套可重复的数据环境，是后续所有质量结论的地基。

为什么有这一期

先建立真实、可复现、能暴露 NL2SQL 难题的数据环境。进入条件：无；先阅读项目总纲与本计划约定。

本期链路

text

总纲 → 业务模型 → 迁移 → 生成器 → 元数据采集 → 索引基础 → Gold 题库 → 管理页

跟读顺序

先解释 Sales、Store、Product 怎样连接，选一张事实表写清一行的含义。
阅读配置与迁移，再跟数据生成器的 seed、时钟和批量写入过程。
对照采集器与控制库模型，区分技术字段与人工说明。
跟一个 Celery 同步任务，观察失败、重试和发布版本。
手算三个 Gold 样例，核对生成器与比较器的行为。

必做学习实验

用两条订单明细和三条退款记录暴露 Join 放大；删除或改名一个字段后重做元数据同步；验证百万级数据生成有实际行数与资源记录。

记录输入、预测、实际输出、代码入口和失败原因；实验通过后再勾选相应任务。只有文档或 fake 运行不能替代真实集成与质量验收。

规模与验收门槛

7 个域、56 张表、约 700 个字段；已生成 200 万级数据；120 道初始题。轻量数据仅用于开发自测，不替代阶段验收。

设计取舍

第一天接入四类基础设施增加本地资源负担，但符合总纲且能从一开始学习索引和控制面边界。tiny 数据降低日常反馈成本，阶段规模验收仍用 scale。凭据引用（env: / vault:）从第一天就分离连接串和代码，防止密码进入版本控制。

两分钟复述骨架

"我先建立固定 seed 的零售数据和 Gold 题库，使以后每个优化都能在同一数据快照上比较。控制库管元数据与版本，业务库管事实，两个索引是可重建副本。元数据中心用凭据引用保证密码不进代码，增量同步保留人工注释。Benchmark v1 分三个互不重叠的集合，测试集锁定禁止作为 few-shot 示例。"

目前已经能用真实经历补充前半段：两个 PostgreSQL 分离控制面和业务数据，OpenSearch 停止时 readiness 返回 503、liveness 保持 200；固定 seed 的 scale 快照含 100 万订单明细，两次运行校验和一致。Gold 题库 120 道覆盖单表/Join/同比/权限/拒绝题，数据集泄漏检查全部通过。

当前代码导读

内容	当前记录
已验收任务及证据	V0-S01～V0-S07 全 27 项；见 `plan/evidence/` 目录
API 入口	`server/api/app.py:create_app` 注册 health、datasource、metadata 路由
依赖检查	`server/health.py:DependencyChecker` 并发检查两个 PostgreSQL、Redis、OpenSearch、Milvus
配置边界	`server/config.py:Settings` 校验必填项、URL 与双库隔离，`safe_summary` 只输出脱敏摘要
业务目录	`datasets/schema/catalog.py` 是声明式源；`scripts/build_schema_catalog.py` 生成 JSON 字典和域关系图
业务迁移	`datasets/migrations.py` 校验并执行 `datasets/business_migrations/001_nova_retail_schema.sql`
数据生成	`datasets/generator/model.py` 负责确定性批次，`database.py` 负责事务写入、校验与快照记录
指标口径	`semantic_models/drafts/core_metrics.yaml` 保存 10 个仅用于 V0 测试数据的草案
数据源登记	`server/datasource/models.py` ORM；`server/datasource/router.py` CRUD + 连接测试 + 触发同步
凭据引用	`server/datasource/credentials.py` 解析 `env:` / `vault:`，拒绝明文
元数据采集	`server/datasource/inspector.py` 从源库反射 information_schema；敏感列跳过样例值采集
增量同步	`server/datasource/sync.py` 保留 manual_* 字段，消失对象标记 is_deleted=True
Celery 任务	`server/tasks/metadata_sync.py` 重试计数 + 幂等键；`server/tasks/index_build.py` 发布前核对数量
控制库迁移	`migrations/versions/398bf9ebf135_v0_s04_.py`（S04）、`6bdae843a9d5_v0_s05_.py`（S05）
文档 ID 规则	`server/search/document_id.py` 稳定 ID，OpenSearch 和 Milvus 共用
OpenSearch	`server/search/opensearch_schema.py` strict mapping，中英文混合分析器
Milvus	`server/search/milvus_schema.py` BGE-M3 1024 维，HNSW + IP 度量
Embedding 抽象	`server/llm/embedding.py` EmbeddingProvider 协议，BGEM3 + Fake 双实现
索引状态	`server/search/index_status.py` IndexBatch + PublishedIndexVersion；发布后才切换指针
Redis 缓存	`server/search/cache.py` 命名空间规则；SCAN 批量失效；TTL 分级（Schema 24h / Query 5min）
Benchmark v1	`benchmarks/v1/train.yaml`（60）+ `tune.yaml`（30）+ `test.yaml`（30，锁定）
比较器	`server/evaluation/comparator.py` 有序/无序/NULL/空结果/拒绝题；Decimal 精确比较
Gold 执行器	`server/evaluation/gold_executor.py` 只读身份，statement_timeout 防大查询
管理界面	`apps/admin/app/` 数据源列表/详情/同步触发；元数据表格/详情；业务域导航
正常与失败场景	全依赖 ready 为 200；停止 OpenSearch 后 live 为 200、ready 为 503，恢复后回到 200
实测指标与环境	Apple Silicon / Docker 7.65 GiB；全服务热启动 22 秒，健康后约 1.38 GiB
规模实测	200,000 订单、1,000,000 订单明细、总计 1,422,172 行；22.47 秒、328 MB

已实现调用关系

text

GET /health/ready
  → FastAPI create_app
  → DependencyChecker.check_all（并发）
  ├─ control PostgreSQL
  ├─ business PostgreSQL（atlas_reader）
  ├─ Redis
  ├─ OpenSearch
  └─ Milvus TCP
  → 全部 up: 200 ready；任一 down: 503 not_ready

数据源注册链路：
POST /api/v1/datasources              → DataSource ORM
POST /api/v1/datasources/{slug}/sync  → MetadataSyncJob + Celery 派发
  → server/tasks/metadata_sync.py
  → inspector.collect_tables（源库）
  → sync.run_metadata_sync（写控制库，幂等）
  → datasource.status / job.status

索引构建链路：
server/tasks/index_build.py
  → 控制库 TableMetadata + ColumnMetadata
  → EmbeddingProvider.embed_batch（BGE-M3 或 Fake）
  → OpenSearch bulk 写入（schema 索引）
  → Milvus REST 写入（向量）
  → 核对文档数
  → PublishedIndexVersion 更新（发布指针）

datasets/schema/catalog.py
  → validate_catalog
  → scripts/build_schema_catalog.py
  ├─ datasets/dictionary/catalog.json
  └─ datasets/dictionary/domain-relationship.md

scripts/seed_data.py
  → reset 安全校验
  → fixture_rows + iter_order_batches
  → PostgreSQL COPY 批量写入
  → 金额 / 状态 / 外键 / 库存 / 边界校验
  → atlas_internal.dataset_run

健康接口返回依赖类别和延迟，不返回底层异常文本。这既方便运维定位，也避免把密码、主机名或驱动错误泄露给调用者。

生成器把确定性规则与数据库写入分开：前者可以快速单测，后者在真实 PostgreSQL 上验证事务、约束和 COPY。业务 owner 只用于迁移与数据生成，应用查询继续使用 atlas_reader。

凭据引用（credential_ref = "env:VAR_NAME"）把连接串保存在环境变量，控制库响应体永远不回显密码。管理界面的 Token 通过 x-admin-token 请求头传递，V4 阶段替换为真实 RBAC。

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

为什么有这一期 ​

本期链路 ​

跟读顺序 ​

必做学习实验 ​

规模与验收门槛 ​

设计取舍 ​

两分钟复述骨架 ​

当前代码导读 ​

已实现调用关系 ​

延伸阅读 ​