Ivan's Blog
项目实践

KaisouMail

KaisouMail 是 Cloudflare temporary email platform，基于 Email Routing、Workers、D1、R2，以及 React + shadcn/ui control plane。README.md 和 README.zh-CN.md 同时存在，说明文档需要中英双语入口；公开 docs site 与 Storybook 也是产品交付面，而不只是开发辅助。

  • Progressive web app
  • README content contract
  • shadcn/ui

目录

技术栈

运行与交付

CI 工作流
  • ci-main.yml
  • ci-pr.yml
  • deploy-main.yml
  • docs-pages.yml
  • label-gate.yml
  • notify-release-failure.yml
  • release.yml
能力标记
  • bun_lock
  • github_actions
  • package_json
JSON

Purpose

KaisouMail 是 Cloudflare temporary email platform，基于 Email Routing、Workers、D1、R2，以及 React + shadcn/ui control plane。README.md 和 README.zh-CN.md 同时存在，说明文档需要中英双语入口；公开 docs site 与 Storybook 也是产品交付面，而不只是开发辅助。

Taxonomy

  • Tags: Progressive web app, README content contract, shadcn/ui

Repository map

  • apps/api-worker/ 承载 Cloudflare Worker/API 层；apps/web/ 承载 React control plane。
  • packages/shared/ 保存跨 Worker/Web 的共享类型或逻辑。
  • apps/web/public/site.webmanifest 与 apps/web/public/*.png 定义 install metadata、theme color、maskable icons 和 app identity。
  • docs-site/ 使用 Rspress 发布公开文档，并链接 /storybook.html 与 /zh/storybook.html。
  • apps/web/.storybook、apps/web/package.json 和大量 *.stories.tsx 证明 Storybook 是公开组件/页面 QA surface。

Runtime and delivery

根 package.json 是 Bun workspace，check、typecheck、test、build、build-storybook 会跨 root、shared、api-worker、web、docs-site 运行。Cloudflare 部署由 deploy-main.yml 和 app 内 wrangler/config 负责；Playwright e2e 在 apps/web/playwright.config.ts 与 test:e2e 中体现。当前显式 PWA 证据集中在 apps/web/index.html 和 apps/web/public/site.webmanifest：这个 control plane 已经维护 display: standalone、scope: /、theme_color、maskable icons 与 apple-touch-icon，说明安装面是有意维护的；但当前 snapshot 还没有把 service worker/offline/update lifecycle 写成同等级 contract。

Architecture notes

架构由 Cloudflare 控制面分层：Email Routing 收邮件，Workers 处理 API/控制逻辑，D1 存 mailbox/domain/API key 等元数据，R2 存邮件对象，React UI 暴露 mailbox、domains、API keys、identity/passkeys 等操作。直接域名绑定、apex-only 约束和 zone cleanup 在 README 中是重要产品规则。

证据锚点：README.md。

Workflow and quality gates

.github/workflows/ci-main.yml、ci-pr.yml、deploy-main.yml、docs-pages.yml、label-gate.yml、release.yml、notify-release-failure.yml 拆分 PR、main、deploy、docs 和 release alert。因为 Cloudflare 资源是真实外部系统，release/deploy 失败通知比普通前端站更重要。

.github/workflows/ci-pr.yml 把 edited metadata 重验与普通 candidate 放入可取消的 per-PR concurrency group；重验不能取消当前 head 的 gate 是 GitHub Actions scheduling 的独立约束，不能混入 Cloudflare deploy 或 release 规则。

Reusable decisions

  • 公开 docs 和 Storybook 作为产品 surface 一起发布，适合控制台类项目。
  • 根 workspace 脚本聚合所有 package gate，避免只检查 Web 忽略 Worker。
  • 双语 README + docs-site 导航符合中文优先、英文可读的受众。
  • 若要把控制台作为 installable Web app 交付，最好像当前仓库这样把 site.webmanifest、apple-touch-icon 和 maskable icons 一起纳入品牌资产生成链，而不是手工散落维护。
  • README 的产品入口与安装身份应分开维护：README.md / README.zh-CN.md 负责产品说明，site.webmanifest 和生成的 icon 资产负责 install surface；不能把 maskable 或 Apple touch 外壳直接当作 README Logo contract。

Risks and open questions

  • Cloudflare zone discovery/direct bind/delete 是高风险操作，项目记忆要保留 apex-only 与 cleanup 语义。
  • Storybook 是公开资产，破坏路径会影响 docs-site。
  • D1/R2/Email Routing 权限和环境变量需要部署证据，不应只看本地 build。
  • 当前 install metadata 已经存在，但 service worker / offline / update UX 没有同等强度的公开证据；后续若对外宣称“PWA 可离线使用”，需要先补齐这部分 contract。

Evidence index

  • README.md
  • README.zh-CN.md
  • package.json
  • apps/web/package.json
  • apps/web/index.html
  • apps/web/public/site.webmanifest
  • apps/web/.storybook/
  • apps/web/playwright.config.ts
  • scripts/generate-brand-assets.py
  • docs-site/package.json
  • docs-site/docs/zh/deployment-environment.md
  • .github/workflows/ci-main.yml
  • .github/workflows/deploy-main.yml
  • .github/workflows/docs-pages.yml
  • .github/workflows/notify-release-failure.yml

相关内容