Cloudflare 全栈 V1 闭环架构文档¶

突发事件应急演练评估数字化平台 · 第一版（全量闭环）¶

项目	内容
文档版本	v1.0
对应需求	`docs/PRD-应急演练评估数字化平台.md`（P0 为主，V1 含部分 P1）
UI 参考	`docs/UI-竞品参考与设计原则.md`
目标	第一版业务闭环全部可在 Cloudflare 上交付（可行），并明确边界与外挂点

1. 结论：第一版闭环「全用 CF」是否可行？¶

可行。 对当前 PRD 定义的 V1 范围（多租户 SaaS、项目/模板/现场/评分/报告/整改/审计、文件与异步报告、RBAC），Cloudflare 开发者平台具备完整闭环所需能力：

能力域	Cloudflare 组件	说明
前端	Pages（React/Vue/Svelte 等）	管理端 + 客户门户；与 API 同账号统一部署
API / BFF	Workers	统一鉴权、租户隔离、业务路由、R2 签名 URL
关系数据	D1	租户、用户、项目、模板版本、指标值、报告版本、审计
对象存储	R2	证据附件、导出 docx/pdf、静态资源包
异步任务	Queues + Consumer Worker	报告生成、通知、Webhook、批量导出
长事务/重试编排（建议）	Workflows	多步骤报告流水线（生成 → 转 PDF → 写回版本）
定时	Cron Triggers	逾期扫描、提醒、清理临时文件
边缘缓存/配置	KV（可选）	会话票据黑名单、功能开关、幂等键、限流计数
实时协作（可选 V1.1）	Durable Objects	同一场次多人编辑锁、在线状态
身份与零信任（可选）	Cloudflare Access	内部管理员、私有化客户 SSO 接入
安全与流量	WAF / Bot / Rate Limiting	API 防护与爬虫控制

需要在架构上「外挂或非 CF」的部分（边界清晰即可，不阻碍 V1 闭环）

场景	建议	原因
复杂 Word 排版引擎	Worker 内嵌 docx 模板引擎（如 docxtemplater 类方案）或独立微服务（容器）	极端复杂版式、字体嵌入、OLE 等可能超出 Worker 包体与 CPU 习惯用法
重视频转码	外链专用转码服务或客户本地	Workers 不适合长时转码
强 OLAP/BI	定期导出到外部数仓（Snowflake/BQ 等）或仅导出 CSV	D1 为 OLTP 向，非分析型数仓
短信/邮件	第三方 API（SendGrid、阿里云短信等）由 Queue 消费者调用	云厂商无关

总结：V1 闭环的 主路径 100% 可放在 Cloudflare；重计算与强分析走「异步 + 外挂」即可，不影响「可部署、可验收」的第一版目标。

2. 业务闭环（V1）在平台上的映射¶

对应 PRD 的端到端流程：

租户/用户/权限(Access 或自建 JWT)
        ↓
Pages 前端（工作台…系统设置）
        ↓
Workers API（租户解析 + RBAC + 业务校验）
        ↓
D1 事务写入（项目/场次/指标/评分/问题/整改/审计）
        ↓
R2 存证据与报告二进制
        ↓
Queues → Consumer（报告生成 / PDF / 通知 / Webhook）
        ↓
D1 更新报告版本与项目状态 + 审计日志

3. 逻辑架构（V1）¶

                    ┌─────────────────┐
                    │ Cloudflare DNS  │
                    └────────┬────────┘
                             │
              ┌──────────────┴──────────────┐
              │                             │
              v                             v
      ┌───────────────┐             ┌───────────────┐
      │ Pages (Web)   │   HTTPS     │ Workers API   │
      │ 管理端/客户门户 │ ──────────► │ + Auth 中间件 │
      └───────────────┘             └───────┬───────┘
                                            │
              ┌─────────────────────────────┼─────────────────────────────┐
              │                             │                             │
              v                             v                             v
      ┌───────────────┐             ┌───────────────┐             ┌───────────────┐
      │ D1 (OLTP)     │             │ R2 (Objects)  │             │ KV (可选)     │
      │ 多租户数据     │             │ 附件/报告       │             │ 开关/限流/幂等 │
      └───────────────┘             └───────────────┘             └───────────────┘
                                            │
                                            v
                                    ┌───────────────┐
                                    │ Queues        │
                                    │ jobs.*        │
                                    └───────┬───────┘
                                            │
                                            v
                                    ┌───────────────┐
                                    │ Consumer      │
                                    │ Worker        │
                                    └───────────────┘

Cron（可选并行画出）：Workers scheduled → 扫描 remediation_tasks 逾期 → 写通知队列表或发 Webhook。

4. 应用拆分建议（单体 Worker + 模块化路由）¶

V1 推荐 单仓库、单 API Worker（降低运维面），内部按模块拆文件：

routes/tenants.ts routes/projects.ts routes/templates.ts …
middleware/auth.ts middleware/tenant.ts
services/reportPipeline.ts
db/queries/*

当 API 体量或团队并行度上升时，再拆为 多个 Worker + Service Bindings（P2）。

前端：Pages 独立项目，VITE_API_BASE 指向 api.example.com 或同域反向代理。

5. 多租户与数据隔离¶

5.1 模型¶

所有业务表含 tenant_id（UUID 或 bigint）。
API 层：JWT 声明 tenant_id + user_id + roles；每条查询强制 WHERE tenant_id = ?。
禁止仅靠前端隐藏菜单做隔离。

5.2 超级管理员¶

platform_admin 角色单独表或声明；仅允许运维域名 + IP allowlist + Access 双因素。

6. 身份认证（两种可选路径）¶

方案	适用	说明
A. 自建 JWT + Refresh（D1）	客户门户、评估员移动端	全在 Workers 内实现；Refresh 轮转、设备列表可选
B. Cloudflare Access + 应用内角色	内部员工、强管控客户	入口 SSO；业务 RBAC 仍在 D1

V1 可优先 方案 A（最少外部依赖），政府客户后续加 方案 B。

7. 核心数据域（D1 表分组建议）¶

以下为逻辑分组，实施时拆为多张迁移文件。

租户与用户：tenants、users、roles、user_roles、sessions（若不用外置 IdP）
组织与客户：customers（客户单位）、customer_contacts
项目与场次：projects、project_members、sessions
模板：template_definitions、template_versions、template_items（指标树）、template_report_mappings
现场与评分：observations、metric_values、score_snapshots、score_adjustments（人工调整留痕）
问题与整改：issues、remediation_tasks、remediation_evidence
报告：report_versions（元数据）、R2 object_key、签收字段
审计：audit_logs（不可变追加）

索引原则：tenant_id 与高频筛选字段组合索引；参考 D1 Best Practices。

8. 文件与报告流水线（R2 + Queues [+ Workflows]）¶

8.1 上传¶

小文件：直传 Worker multipart → R2。
大文件：Worker 签发 R2 预签名上传（短 TTL），前端直传 R2，完成后回调 Worker 写入 attachments 元数据。

8.2 报告生成（建议 V1 就上 Workflows，若团队更熟可先用 Queue 单消费者）¶

阶段

report.requested → 写 report_versions(status=pending)
拉取 score_snapshot + issues + 模板映射 → 生成 docx（或先生成 HTML 再转 PDF）
上传 R2 → 更新 report_versions(status=ready, r2_key=…)
写审计、可选发邮件/Webhook

失败：重试 + DLQ（Queues 能力），人工在后台「重试生成」。

9. API 与安全基线¶

HTTPS 全站；HSTS；Cookie Secure/HttpOnly（若用 Cookie 会话）。
RBAC：路由级 + 资源级（项目成员表）。
限流：按 tenant_id + IP + 路由（登录、导出）分级。
输入校验：Zod 或等价方案。
审计：导出、报告发布、签收、权限变更、评分人工调整必记。

10. 观测与运维¶

Workers Logs / Metrics（错误率、P95、队列积压深度）。
业务埋点表或结构化日志：report_generate_ms、queue_lag_ms。
告警：队列 DLQ 增长、报告失败率、5xx 突增。

11. 环境与发布¶

dev / staging / prod：独立 D1、R2 bucket（或前缀隔离）、Queues、Secrets。
CI：lint + test + wrangler deploy --env staging。
生产发布：人工审批 + 冒烟（登录、建项目、现场提交、出报告、签收、整改关闭）。

12. 与当前 `mvp/` 工程的关系¶

现有 mvp/ 为 技术骨架验证（D1/R2/Queues 跑通）。
V1 建议在 mvp/ 同级新建 apps/web（Pages）与 apps/api（Workers）或按 monorepo 重组，迁移策略：保留绑定模式，扩展路由与表结构。
wrangler.jsonc 按环境拆分 env.production / env.staging。

13. V1 里程碑（建议）¶

阶段	内容
M1	多租户 + 用户 RBAC + 项目/场次 + 审计
M2	模板中心（版本快照）+ 现场录入 + 附件 R2
M3	自动评分 + 调整留痕 + 报告队列流水线
M4	报告版本 + 签收 + 整改看板 + 通知
M5	统计简版 + 压测 + 安全加固 + 上线检查单

14. 官方文档索引（实施时对照）¶

Workers：https://developers.cloudflare.com/workers/
Pages Framework：https://developers.cloudflare.com/pages/framework-guides/
D1：https://developers.cloudflare.com/d1/best-practices/
R2：https://developers.cloudflare.com/r2/how-r2-works/
Queues：https://developers.cloudflare.com/queues/
Workflows：https://developers.cloudflare.com/workflows/

15. 修订记录¶

版本	日期	说明
v1.0	2026-04-21	初版：V1 全量闭环 CF 可行性 + 架构定稿