企业官网建设流程全解析

• AI 应用
• 媒体生成
• 后端
• 前端

Economics Web 是 Pollinations 的私有经济运营界面，部署在economics.myceli.ai与economics.pollinations.ai两个自定义域名上，数据完全来自 enter.pollinations.ai/observability/ 中定义的 Economics Tinybird pipe 物化结果。本文完整拆解它的本地运行方式、.dev.vars与密钥配置、基于应用级会话的私有读取端点、fixtures 离线演示模式、数据契约（含 model 成本归并规则）以及 Runway 现金预测口径，并逐条对照 Worker 与前端源码，说明每个约束在代码中是如何落地的。

应用定位：三个操作视图组

应用把所有经济数据组织为三个操作视图（operating views），导航栏也按此分组：

从源码结构看，这套视图与数据的绑定关系由 App.tsx 中的VIEW_SOURCES映射（L88-L106）驱动：每个视图声明自己需要哪些数据源（如runway需要opTransactions、vendorLedger、stripeSales、userBalances、privateConfig），这正是下文"每个视图只加载所需端点"的实现基础。导航项定义见 App.tsx 中的INSIGHT_TABS、LEDGER_INSIGHT_TABS与TABS。

本地运行

启动命令

npm install npm run dev

开发服务器固定使用http://localhost:4180。该端口由 vite.config.ts 中server: { host: "localhost", port: 4180, strictPort: true }强制锁定（strictPort意味着端口被占用时直接报错而不是换端口）。

npm run dev会先触发predev钩子（见 package.json）：

"predev": "npm run build --prefix ../../../packages/ui && npm run decrypt-vars"

即先构建共享 UI 包@pollinations/ui，再运行decrypt-vars解密本地变量——这是本地开发能读到数据的必要前提。

.dev.vars与 OAuth 回调注册

本地.dev.vars需要两个关键变量：

POLLINATIONS_AUTH_BASE_URL=http://localhost:3000 TINYBIRD_POLLEN_PIPE=economics_pollen_usage_snapshot_api

• POLLINATIONS_AUTH_BASE_URL指向本地运行的 Enter 服务（端口 3000）。KPI、Economics 与 Observability 三个应用共享同一个登录页、provider 按钮和 admin-only OAuth 会话实现；“Sign out” 只清除当前应用的会话，且登录不要求任何 generation key 或 Pollen 权限。
• TINYBIRD_POLLEN_PIPE在本地必须指向 staging 快照端点economics_pollen_usage_snapshot_api，而不是生产 pipe。该 staging 端点的定义见 economics_pollen_usage_snapshot_api.pipe，其 DESCRIPTION 明确写着"供 staging 与本地 Economics 开发使用的最新已定稿生产 Pollen 快照"，并声明不含本地物化的 staging 用量、不会重复计数。

必须在本地 Economics OAuth client 上注册http://localhost:4180/auth/callback；生产环境的注册只接受 HTTPS 应用回调。

密钥配置：独立的签名密钥与只读 Token

应用要求两个专属凭据：

1. POLLINATIONS_AUTH_SESSION_SECRET—— 本应用自己的会话签名密钥，绝不能复用 KPI 的签名密钥；
2. TINYBIRD_ECONOMICS_READ_TOKEN—— 本应用自己的 Tinybird 只读 Token。

本地开发必须使用来自 operations/economics/secrets/web.dev.json 的staging reader，绝不允许使用生产 reader。这两个凭据在预置（provisioning）前需要单独审批；从该文件内容看，TINYBIRD_ECONOMICS_READ_TOKEN以ENC[AES256_GCM,...]形式被 sops 加密存储，配合 age 密钥管理。

npm run decrypt-vars脚本（package.json 中定义为sops exec-env ../secrets/web.dev.json 'node scripts/write-dev-vars.mjs'）的行为约定是：保留单独审批过的应用签名密钥，只加载staging reader，永远不读取生产 secret。实现见 write-dev-vars.mjs 及其测试 write-dev-vars.test.mjs。

部署顺序

生产部署必须严格按以下顺序执行：

1. 先部署 Enter 的 OAuth client 注册；
2. 再预置审批过的应用密钥；
3. 最后通过 GitHub Actions 构建并部署 Economics Worker。

生产环境的静态配置见 wrangler.toml：Worker 名为myceli-economics，入口 worker/index.ts，绑定两个自定义域名，[vars]中预置POLLINATIONS_OAUTH_CLIENT_ID、TINYBIRD_INGEST_URL（欧洲区 Tinybird 网关）以及生产值TINYBIRD_POLLEN_PIPE = "economics_pollen_usage_api"。注意本地与生产正是通过这一变量切换 Pollen 数据源（详见下文）。

私有读取端点与会话安全模型

README 中有一段密度很高的安全约定，逐条对应到源码：

此外还有三条运行时行为约定：

• 权限复查窗口：受保护请求在 60 秒 cookie 窗口内只重新校验一次当前 admin 状态（向 Enter 复核）。被降权、封禁或 Token 被吊销后，下一次检查即拒绝访问——即权限回收最多延迟一个复查窗口，不需要强制踢出会话。
• Enter 临时故障不丢会话：复查时 Enter 短暂不可用会返回 503，但不清除现有会话，避免上游抖动造成全员掉线。
• pipe 白名单：worker/economics.ts 中READ_PIPES是硬编码白名单（7 个 pipe），未知 pipe 返回 404；TINYBIRD_ECONOMICS_READ_TOKEN缺失返回 503；对economics_pollen_usage_api做上游映射时，若TINYBIRD_POLLEN_PIPE既不是生产值也不是 staging 快照值，返回 503 并提示"必须选择 production 或 staging Pollen 端点"（L26-L42）。Worker 以 Bearer Token 请求{TINYBIRD_INGEST_URL}/v0/pipes/{pipe}.json，上游非成功状态统一转 502，凭据只存在于 Worker 环境，从不进入浏览器 bundle。

前端侧，tb.ts 的fetchPipe始终以credentials: "same-origin"请求同源/api/economics/pipes/:pipe，并对响应做行级契约校验（validatePipeRows，定义于 pipeContracts.ts）。

Fixtures 模式

http://localhost:4180/?fixtures=1

在 admin 登录之后，?fixtures=1会渲染内置样例数据，不请求任何实时账本数据。实现上：

• tb.ts 的fixturesMode()检测 URL 是否含fixtures参数；
• fetchPipe在 fixtures 模式下改为从 fixtures.ts 的FIXTURES记录中取数，并对 fixtures 数据执行与真实数据相同的validatePipeRows契约校验，保证演示路径与生产路径走同一套数据形状；
• fixtures.ts 中明确注释：所有金额都是刻意取整的虚构值，绝不能把真实账本数字写进 fixtures——因为 fixtures 会打包进公开 bundle，在认证之前就已存在。

导航栏底部出现fixtures徽标（App.tsx）用于提示当前处于演示数据状态。

数据契约

Pipe 清单与 Staging/生产切换

应用从 enter.pollinations.ai/observability/endpoints/ 读取 Economics pipes：

"生产读实时物化、本地开发读已验证的 staging 副本"通过TINYBIRD_POLLEN_PIPE环境变量实现：生产取economics_pollen_usage_api，staging/本地取 economics_pollen_usage_snapshot_api.pipe，二者共用operations_read只读 Token 体系。

收入与分成口径

• Revenue Share使用去重后的事件物化（deduplicated event materialization），使经济视图与其压缩源账本共享同一条计算路径；
• 创作者用户名与当前 Paid/Quest 余额来自每日 D1 用户快照，只有聚合余额到达 Runway API；
• Stripe P&L 收入来自复核过的账户余额活动：Pollen 与 Ko-fi 毛销售、退款、冲正分列；处理费计入 Operations 费用；Wise 打款只是现金 movements，不参与 P&L。

Inference 模型成本归并规则

Inference 模型成本将 provider 账本标签关联到 Pollen 模型时，只允许通过精确 Pollen id 或 operations/economics/provider-registry.json 中经复核的modelLabels表（该文件同时含canonicalModelRenames等模型改名映射）。归并的硬约束是：

• Pollen id 保持拆分——今天的 registry 别名永不把它们合并；
• provider 在同一行账单上计费的多个 Pollen id 形成一个分组行（grouped row）；
• 未关联上的成本保持可见，表现为 needs mapping 或 missing breakdown 行，绝不摊派到各模型上。

前端对 Pollen 行的聚合逻辑见 tb.ts 的canonicalPollenRows（按month|vendor|model|currency合并、过滤全零行）。

采集与修正约定（append-only 修正、tombstone 标记等）定义在仓库根目录的 SKILL.md；补充口径可参考父级 operations/economics/README.md：银行与 vendor 账本的修正是追加式的（复用稳定entry_id+ 更新recorded_at），vendor 墓碑用显式source=tombstone标记、在原始账本中保留但由 effective 端点隐藏。

视图级加载与故障隔离

• 每个视图只加载其声明的端点——VIEW_SOURCES（App.tsx）→loadAll只请求wanted集合内的数据源（tb.ts），注释明确写着"无关视图不会等待它不消费的昂贵或不可用端点"；
• 无关端点失败不阻塞其他视图；
• 刷新时保留所选视图与报表月份：App.tsx 将view与month参数写入 URL（history.replaceState），刷新后从 URL 恢复。

前端隔离与部署校验

• 登录壳是公开的，但 provider registry 证据（审查记录）被隔离在/private/bundle chunk 中，仅在 admin 认证后下发，且响应头为private, no-store。构建层面，vite.config.ts 用manualChunks把provider-registry.json单独切块并输出到private/[name]-[hash].js；运行时 worker/index.ts 对/private/*请求先做会话认证、再覆盖缓存头后从 assets 取文件；wrangler.toml 的run_worker_first也包含/private/*。
• 真实账本数据与预测假设全部走受保护的读取端点，前端从不直连 Tinybird；
• 部署前校验 Tinybird 契约：check-tinybird-contract.mjs（及测试 check-tinybird-contract.test.mjs）在携带审批过的生产 secret 上传 Worker 之前验证数据契约；secret 同步本身同样需要审批。

Runway 现金预测口径

Runway 视图的计算规则是本文档中最具会计约束力的部分：

1. 现金重构：从economics_bank_ledger中一行对账单支撑的期初余额（opening-balance row）加后续银行 movements 逐月重构现金，不依赖任何第二套余额账本；
2. 月份状态：已关月全部为 actuals；开放月将"截至目前的实际现金"与"计算出的全月计划"并排展示，月末现金只应用其未花费/未收到的剩余部分；
3. 预测规则来源：来自认证后的economics_private_config_api，不存在任何存储型的 OP Forecast 账本——预测是纯派生计算（父级 README 亦强调 Runway 数学上派生自银行账本、vendor 账本、核对过的余额与 forecastTerms.ts 中的复核规则）；
4. 用量型预测：消耗每个账户核对过的预付/credit 余额与每个资金批次（funding lot）验证过的到期时间；"忽略到期"作为范围受限的用户审批假设保留时，必须在界面上与已验证条款可见地区分开；
5. 显式缺口：未知的 credit 条款、不完整的 Stripe 覆盖、未匹配的期初 postpaid 账单都作为显式 gap 呈现，而不是被悄悄消化；
6. Wise 快照仅作验证：当前 Wise 余额快照只用于核对，不作为第二余额账本存储；
7. 收入与费用锚定 Stripe，现金锚定 Wise：P&L 收入与 Stripe 费用使用 Stripe 活动而非 Wise 打款时点；"Cash change"与"Cash balance"仍以 Wise 为锚，两侧由 processor 结算时差（settlement timing）桥接；
8. 未使用的 Paid 与 Quest Pollen：作为"不可兑现的未来用量敞口"（non-cashable future usage exposure）单独呈现，不从现金跑道中扣减。

前端对这些口径的逐条解释在 App.tsx 的viewInfoContent("runway")悬停说明中：灰字数字代表 credit 支付部分（不进任何加总）、未对账项（未付账单、预付余额、Stripe 浮存金）被刻意排除在表格外等。

小结

Economics Web 的设计要点可归纳为四条工程原则，均可在仓库中逐条验证：

• 凭据隔离：应用级签名密钥、staging-only reader、Worker 侧 Token，本地与生产通过TINYBIRD_POLLEN_PIPE显式切换且受 Worker 白名单校验（worker/economics.ts）；
• 最小加载：视图声明式依赖数据源，端点失败互相隔离（tb.ts +VIEW_SOURCES）；
• 证据隔离：公开登录壳 +/private/切块 + 会话认证 + no-store（vite.config.ts、worker/index.ts）;
• 口径透明：Runway 纯派生、成本未归并即保持可见、预测假设与已验证条款分离，缺口一律显式呈现。

本地验证路径为：npm run dev启动（localhost:4180）→ 配置.dev.vars与 OAuth 回调 →?fixtures=1走演示数据，或经 admin 登录读取 staging 副本；生产构建由npm run deploy（vite build+wrangler deploy）配合 Tinybird 契约校验脚本完成。

• AI 应用
• 媒体生成
• 后端
• 前端