schema-e2e-validation

架构 E2E 验证

自我演进技能：此技能会在使用过程中不断改进。如果指令有误、参数发生漂移，或需要采用变通方案，请立即修复此文件，不要延后。仅针对真实且可复现的问题进行更新。

何时使用此技能

在以下情况下使用此技能：

• 提交前验证架构变更
• 验证 YAML 架构是否与线上 ClickHouse Cloud 匹配
• 重新生成 Python 类型、DDL 或文档
• 运行完整的架构工作流验证

前置条件

Docker 运行时（必需）

Earthly 需要 Docker。运行前请启动 Colima：

colima start

检查是否正在运行：

docker ps  # Should not error

Doppler 访问权限（用于验证目标）

运行 +test-schema-validate 和 +test-schema-e2e 时需要：

doppler configure set token <token_from_1password>
doppler setup --project gapless-network-data --config prd

Earthly 安装

brew install earthly

---

快捷命令

仅生成（无需密钥）

cd ~/eon/gapless-network-data
colima start  # If not already running
earthly +test-schema-generate

完整 E2E 验证（需要 Doppler）

cd ~/eon/gapless-network-data
colima start  # If not already running
./scripts/earthly-with-doppler.sh +test-schema-e2e

所有无需密钥的目标

cd ~/eon/gapless-network-data
earthly +all

---

产物

运行 +test-schema-generate 或 +test-schema-e2e 后，检查 ./earthly-artifacts/：

路径	内容
types/blocks.py	Pydantic + TypedDict 模型
types/__init__.py	包初始化
ddl/ethereum_mainnet.sql	ClickHouse DDL
docs/ethereum_mainnet.md	Markdown 文档

对于 E2E，产物位于 e2e/types/、e2e/ddl/ 和 e2e/docs/ 下。

---

Earthfile 目标参考

目标	密钥	用途
+deps	否	安装 uv + 依赖项
+build	否	复制源文件
+test-unit	否	运行 pytest
+test-schema-generate	否	生成类型/DDL/文档
+test-schema-validate	是	对照 ClickHouse 验证
+test-schema-e2e	是	完整工作流 + 产物
+all	否	运行所有无需密钥的目标

---

故障排除

“could not determine buildkit address - is Docker or Podman running?”

原因：Docker/Colima 未运行

修复方法：

colima start
# Wait for "done" message, then retry
earthly +test-schema-generate

“unable to parse --secret-file argument”

原因：标志名称错误，或密钥文件格式不正确

修复方法：正确的标志是 --secret-file-path（不是 --secret-file）。包装脚本会处理此问题，但如果手动运行：

# WRONG
earthly --secret-file=/path/to/secrets +target

# CORRECT
earthly --secret-file-path=/path/to/secrets +target

另外，请确保密钥文件中的值没有用引号括起来：

# WRONG format
CLICKHOUSE_HOST="host.cloud"

# CORRECT format
CLICKHOUSE_HOST=host.cloud

“OSError: Readme file does not exist: README.md”

原因：hatchling 构建后端要求容器中存在 README.md

修复方法：确保 Earthfile 在 deps 目标中复制 README.md：

deps:
    COPY pyproject.toml uv.lock README.md ./  # README.md required!

验证期间出现“missing secret”

原因：未配置 Doppler，或未传递密钥

修复方法：

# Verify Doppler has the secrets
doppler secrets --project gapless-network-data --config prd | grep CLICKHOUSE

# Use the wrapper script (handles secret injection)
./scripts/earthly-with-doppler.sh +test-schema-validate

缓存问题

强制在不使用缓存的情况下重新构建：

earthly --no-cache +test-schema-e2e

---

实现细节

Doppler 密钥注入

包装脚本 scripts/earthly-with-doppler.sh：

1. 从 Doppler 下载密钥
2. 筛选 CLICKHOUSE_* 变量
3. 去除引号（Doppler 输出 KEY="value"，而 Earthly 需要 KEY=value）
4. 通过 --secret-file-path 标志传递
5. 退出时清理临时文件

必需密钥

密钥	用途
CLICKHOUSE_HOST_READONLY	ClickHouse Cloud 主机
CLICKHOUSE_USER_READONLY	只读用户
CLICKHOUSE_PASSWORD_READONLY	只读密码

---

相关文件

文件	用途
~/eon/gapless-network-data/Earthfile	主构建文件
~/eon/gapless-network-data/scripts/earthly-with-doppler.sh	密钥注入封装脚本
~/eon/gapless-network-data/schema/clickhouse/ethereum_mainnet.yaml	SSoT 架构
~/eon/gapless-network-data/docs/adr/2025-12-03-earthly-schema-e2e.md	ADR

---

验证历史

• 2025-12-03：已创建，并通过针对 ClickHouse Cloud 的完整 E2E 运行完成验证
• 经验总结：
  • 使用 --secret-file-path，而不是 --secret-file（Earthly v0.8.16）
  • Doppler --format env 会输出引号，必须用 sed 's/"//g' 将其去掉
  • 必须复制 README.md，才能使用 hatchling 构建后端
  • 运行 Earthly 前必须启动 Colima

---

设计权威

此技能用于验证架构，但不负责设计架构。有关架构设计指导（ORDER BY、压缩、分区），请先调用 quality-tools:clickhouse-architect。

相关技能

技能	用途
quality-tools:clickhouse-architect	验证前进行架构设计
devops-tools:clickhouse-cloud-management	E2E 测试的云凭据
devops-tools:clickhouse-pydantic-config	客户端配置

执行后复盘

此技能完成后，请在结束前检查：

1. 命令是否成功？ — 如果没有，请修复导致失败的指令或错误表。
2. 参数或输出是否发生变化？ — 如果底层工具的接口发生变化，请相应更新 Usage 示例和 Parameters 表。
3. 是否需要变通方案？ — 如果你不得不临时调整（使用不同标志、增加额外步骤），请更新此 SKILL.md，避免下次调用时遇到相同问题。

仅当问题真实且可复现时才更新，不要基于猜测更新。