企业官网建设流程全解析

Helix Foundry 是一个运行在你自己电脑上的本地优先（local-first）数据工作区，基于 HelixDB 与 DuckDB 构建。它的数据版本化设计由三大支柱组成：每次导入都生成一个不可变的 Parquet 快照、源库 Schema 变化会被拦截进入审查队列、任意历史快照可随时只读回溯。对于需要回答"上周三那天这张表到底长什么样"的团队，这套机制提供了可追溯的数据底座。

为什么数据版本化值得认真对待

数据源每天都在变：字段悄悄改名、新增列、行数忽多忽少。如果工作区直接"就地更新"，就会出现两类问题：

• 分析结果不可复现——昨天跑出来的报表，今天重算数字就变了；
• Schema 变更静默破坏下游——AI 生成的 SQL、管道（Pipeline）基于旧结构，字段一改全部报错。

Helix Foundry 的解法是"快照 + 状态机"：数据文件只新增、不修改；结构变化不自动生效，必须人工确认。下面逐条拆解。

设计一：每次刷新 = 一个新的不可变 Parquet 版本

每当一个数据源（PostgreSQL、MySQL、Stripe、S3、上传文件等）完成一次导入，工作区都会为该数据集创建一条新的version 资源，对应磁盘上一个独立的 Parquet 文件：

datasets/<workspace>/<version-id>.parquet

关键行为（实现在 datasets.ts）：

每个版本都自带一份profile（行数、每列空值率、主键唯一性、重复行数、内容指纹），这是后续漂移检测与质量告警的依据。官方文档明确写道："Parquet versions and staged artifacts are immutable"（见 OPERATIONS.md）——版本文件一旦落盘就不会被改写或删除，这是全部追溯能力的物理基础。

一个值得注意的细节：指纹相同的"空刷新"不会污染版本历史。代码中的注释解释了原因——否则每张表的定时刷新（默认 5 分钟一次）都会堆积成百上千份完全相同的副本，还会把进行中的发布流程误判为"输入已变更"而中止。

设计二：Schema 漂移审查——三态快照状态机

当检测到新快照的列结构（列名 + 类型的组合）与现有 profile 不一致时，代码会判定为schema drift（见 datasets.ts#L52-L96），数据集随即进入三态模型：

current（当前）── 所有查询、视图、指标都使用它 pending（待审查）── 新结构快照，等待人工确认 historical（历史）── 之前被替换下来的所有版本

在这个状态下，体验上有几个保护点：

1. 现有视图不受影响。页面上会弹出提示："The source schema changed — Your existing views still use the previous snapshot."，并提供Accept new snapshot按钮，由编辑者显式点击后（accept-version 路由），pending 版本才被提升为 current。

2. 审查不只是看列名。系统会自动比对前后两次 profile，生成质量发现（finding），包括：

   • xxx 列失去唯一性或出现空值（主键退化）
   • xxx 列空值率上升
   • 行数前后对比（before / after）与重复行数（duplicateRows）

   这些证据会随 finding 一起持久化，形成一份"变更说明书"。

3. AI 发布流程同步感知。如果某个待发布提案验证之后，其输入快照发生了漂移，发布时会出现警告要求重新测试（见 GUIDE.md 的 Publishing and rollback 一节），防止 AI 基于过期结构写入生产定义。

对数据源侧的变更捕获，Helix Foundry 优先使用 PostgreSQL 逻辑复制或 MySQL binlog，不可用时回落到定时快照刷新；无论哪条路径，结构变化都统一走这条审查通道（见 GUIDE.md 的 Sync and change capture）。

设计三：历史追溯——只读回看任意一个时间点

数据集的versions数组按时间倒序记录全部版本。在Data页面打开任一数据集，顶部有一个Snapshot下拉框，列出Current、Needs review以及最近 30 个历史版本（更早的版本以计数形式显示，见 data.tsx）。选中任一历史版本即可：

• 只读预览任意一页的行数据（offset/limit 分页，单次最多 500 行）；
• 查看该版本的 profile（行数、列结构、时间戳），即使是一个空快照也会展示其带类型的 schema；
• 获得精确的版本引用（{ datasetId, version }），回答中引用哪个快照一目了然。

预览走的是 APIPOST /datasets/:id/versions/:version/preview，由独立的 DuckDB 执行器进程加载对应 Parquet 文件执行（只读、无网络、无凭据），核心实现在 previewDatasetVersion。TypeScript SDK 暴露了同等方法：previewDatasetVersion(datasetId, versionId, offset, limit)（参考 API.md）。

追溯能力还延伸到导出：GET /datasets/:id/export下载的 Parquet / CSV 基于当前活动快照，响应头会附上x-foundry-version，文件与版本号天然配对，归档到外部工具时依然可复核来源。

这套设计给工程师的三点启示

1. "不可变文件 + 可变指针"是版本化的最小骨架。Helix Foundry 把复杂度控制在元数据层：Parquet 文件只增不改，数据集资源上仅维护activeVersion/pendingVersion/versions三个字段，状态迁移（current → historical）就是指针移动，天然支持任意次回看。
2. 指纹去重让"不变"不产生成本。定时刷新的场景下，内容指纹相同的快照被直接丢弃（datasets.ts#L56-L82），存储与版本历史都不会被无意义地拉长——这是很多数据管道容易忽略的优化。
3. 审查门（review gate）应携带证据，而非仅一个开关。漂移 finding 自动附带列级质量对比和行数前后值，让"要不要接受"成为一个有数据支撑的决策，而不是凭感觉点按钮。

小结

对于希望"数据可复现、变更可审查、历史可回看"的本地数据工作区，Helix Foundry 的这套 不可变 Parquet 快照 + Schema 漂移审查 + 版本追溯 组合，提供了一个结构清晰、边界明确的参考实现。更多功能细节可查阅 docs/GUIDE.md 与 docs/OPERATIONS.md。