Fago：架构与实施方案
# Fago：架构与实施方案
版本：v1.9 · 日期：2026-11-09 · 状态：M0–M5 本地工程与自动化验收完成，其中 M1/M2 另有用户人工确认。M6 工作流已进行到 schema v52，含表单与流程设计、受控 BPMN 和文档版本，R3 未结项。无生产环境，未执行生产部署。见M5最终验收。
# 已确定的方向
用户确定：先完成完整架构和分期方案；后端使用 Go，前端基于 Vben Admin 5 (opens new window) 重做。本文替代此前“复用旧 Vue 3 管理端并兼容旧 API”的草案。
建议定位为企业后台开发平台：按系统管理、基础设施和业务模块划分，前后端采用新合同。目标能力按用户补充扩展为：多模块、多数据库、多消息后端、多用户多终端与 SSO、Redis 权限缓存、透明租户封装及纯 Go 通用工作流（对标 Flowable 的业务能力，文件/文档与业务流程共用）。全部自研服务使用 Go，工作流不引入 Java/JVM；可选外部消息/身份服务按协议对接，默认本地部署无需 JVM，详见架构决策的范围解释。默认新建业务库；存量平台数据和旧引擎实例迁移单独设计。
# 阅读入口
在线文档按读者要完成的事分册。日常从手册进入；下表之后仍是规划与验收记录，对应站点里的「规划备查」。
| 手册 | 从这里进入 |
|---|---|
| 快速开始 | 简介 |
| 后端手册 | 配置与环境 |
| 前端手册 | 本地启动 |
| 文档 | 回答的问题 |
|---|---|
| 02 总体架构 | 技术栈、模块边界、代码结构、事务、任务、部署和运维 |
| 03 身份、权限与租户 | 如何登录、授权、隔离数据，以及如何撤销访问 |
| 04 前端与 API 合同 | Vben 如何接入 Go，路由、DTO、错误、分页如何统一 |
| 05 核心数据模型 | 核心实体、约束、索引、软删除和迁移策略 |
| 06 数据库与消息适配 | 七种数据库和五种消息后端如何接入与认证 |
| 07 纯 Go 通用工作流 | 组件评估、引擎自研、文件/文档与业务流程统一、功能对标矩阵 |
| 08 分期与验收 | 做哪些功能、按什么顺序、投入区间和完成标准 |
| 09 架构决策与风险 | 为什么这样选、哪些是假设、何时需要重新决策 |
| 10 来源与基线 | 哪些事实已经核实，参考版本和官方链接 |
| 11 M0 实施与验收 | 工程底座交付范围、验证命令与未认证项 |
| 13 M1 身份与导航 | 已实施闭环、自动化证据与用户人工验收确认 |
| 14 配置与数据安全 | 环境 YAML、JSON 内容加密、脱敏模块与验证证据 |
| 15 M2 系统管理实施 | 部门岗位的迁移、事务、接口、页面及后续工作 |
| 12 二级等保合规要求 | 等保二级控制映射、应用基线、部署配套与验收清单 |
# 架构结论
| 领域 | 默认设计 | 状态 |
|---|---|---|
| 后端 | Go + Gin + GORM，Go workspace 多模块；按部署需要组装 API/worker | 建议采用 |
| 前端 | Vben Admin 5 + Vue 3 + TypeScript，默认 web-antd | Vben 5 已确定；Ant Design Vue 为建议 |
| 数据 | MySQL / Oracle / PostgreSQL / SQL Server / MariaDB / DM / TiDB；方言迁移与隔离 | 用户确定目标 |
| 会话 | 不透明 access token + HttpOnly 刷新 cookie，可服务端撤销 | 建议采用 |
| Redis | 限流、版本化权限/菜单缓存；权威状态在业务主库 | 建议采用 |
| 权限 | 后端动态菜单 + 按钮权限码 + 服务端数据范围 + Redis 缓存 | 用户确定目标 |
| 身份 | 多用户类型、多终端策略、OIDC SSO | 用户确定目标 |
| 消息 | Event / Redis / RabbitMQ / Kafka / RocketMQ，可靠投递封装 | 用户确定目标 |
| 部署 | 同域反向代理；前端静态文件 + Go API/worker + 可选数据库 + Redis | 建议采用 |
| 后台任务 | 同代码仓库、独立 worker 进程，数据库 outbox/任务表 | 第二阶段引入 |
| 文件 | 对象存储适配层；S3 兼容桶，或单机受控磁盘目录 | 已实现。多副本共享盘未认证 |
| 工作流 | 纯 Go workflow-core + workflow-approval + workflow-resource；优先评估复用，不足部分自研 | 用户确定纯 Go、功能对标与通用资源 |
上表是总体目标；已交付部分以各里程碑及M5最终验收为准。Go 1.27.3、Gin 1.12.0 和 GORM 1.31.1 已锁定；其他数据库、消息后端、SSO 与完整工作流仍按各阶段认证，不能由工程初始化推断支持范围。
# 功能地图
| 层次 | 模块 | 优先级与边界 |
|---|---|---|
| 平台底座 | 配置、日志、错误、数据库、迁移、审计、健康检查 | P0 基础工程 |
| 系统管理 | 登录、会话、用户、部门、岗位、角色、菜单、数据权限 | P0 首个闭环 |
| SaaS | 平台账号、租户、套餐、能力开关、到期和停用 | P0 租户闭环 |
| 通用能力 | 字典、参数、文件、通知模板、任务、操作日志、代码生成 | P1 平台能力 |
| 用户业务 | 多用户类型、多终端、SSO；会员业务另扩展 | 身份能力必做，业务按需 |
| 审批 | 纯 Go 引擎、动态表单、在线设计、会签/或签、任务分配、文件审批 | P2 必须交付的目标能力 |
| 商业业务 | 支付、商城、CRM、ERP、MES、WMS、财务等 | P3 选择具体业务实施 |
| 扩展业务 | AI、IoT、IM、报表 | P3 独立评估，不估算为普通 CRUD |
首个正式版本 R1 = P0 中的后台和租户闭环。R2 = P1 通用平台能力及 SSO。R3 完成纯 Go 通用工作流与文件审批；R4 完成全部数据库/消息后端认证；后续按业务场景扩展。“完整架构”意味着扩展边界和路线明确，不意味着全量业务已经定义到字段级。
# 实施顺序
- M0 合同和工程底座：确认 API 样例、版本基线、工程和 CI。
- M1 身份和导航：登录、刷新、登出、本人信息、菜单和权限码。
- M2 系统管理：用户、部门、岗位、角色、授权、数据范围。
- M3 SaaS 和平台管理：平台身份、租户套餐、停用与到期、隔离验收。
- M4 R1 发布：安全与权限回归、压测、备份恢复、部署演练。
- M5 R2 能力扩展：字典、配置、文件、通知、任务、代码生成、多终端与 SSO。
- M6 R3 工作流：纯 Go 引擎、表单/流程设计、审批和任务分配、文件/文档与业务资源绑定。
- M7 R4 兼容认证：完成七种业务数据库、五种消息后端及工作流持久化的一致性回归。
- M8 业务扩展：先选一个真实业务验证扩展方式，再扩展其他领域。
租户字段和上下文从 M0 就存在；M3 完成的是平台管理功能，不是到那时才补数据隔离。详细依赖、工作包和验收见 路线图。
# 首期完成的业务场景
平台运营创建租户并指定套餐 → 初始化该租户管理员 → 管理员创建部门、岗位、用户与角色 → 分配菜单、按钮权限和数据范围 → 普通用户登录并只看到获授权页面与数据 → 调整权限后服务端立即按新规则校验 → 租户停用后会话不可继续访问。
这个场景需由真实 Vben 页面和持久化 API 完成。演示账号、静态菜单和内存 CRUD 不能替代验收。
# 前提和估算口径
默认面向中小型企业后台，初始不要求跨地域、多活、物理分库或十万级实时连接。R1 默认单租户归属账号、中文界面、Web 密码登录。多用户身份和 client 模型从 R1 存在，完整多终端策略及 SSO 在 R2 验收。国际化结构保留，短信、MFA 和具体 App 业务另排。
默认 UI 库选 Ant Design Vue，理由是统一采用 Vben 的 web-antd 应用作为开发模板。合规默认按信息系统 二级等保 规划应用与交付物（见 二级等保合规要求）；定级、备案与测评由使用单位负责，项目不预先宣称已通过测评。业务组织规模、并发、存量数据迁移、更细的工作流语义和部署环境尚未给出，因此工期和容量均是规划假设，不是交付承诺。路线图现按 AI 工作日核算：1 AI 工作日为 8 小时有效设计、编码、测试与交付时间，外部等待单列；M0 已交付后的 R1 规划为 6–12 AI 工作日，R1–R4 剩余合计 28–52 AI 工作日，均含一次约 20% 风险余量。此为首轮估算，完成 M1 后按实际耗时校准，详见 分期与验收。
# 下一步的具体工作
M0–M5本地工程已完成。M6纯Go通用工作流已在仓库中推进到 schema v52，仍按路线图逐构件验收，R3 未结项。生产SSO部署、目标数据库/消息完整认证仍须后续验证。
# 工作流能力的承诺边界
本方案以 Flowable 作为能力参照，首批交付动态表单、在线设计、会签/或签、候选策略、可靠任务、历史和通用资源审批；复杂 BPMN、规则/案例管理等对标项逐批补齐。尚未实现的功能明确列为待开发，不能把自研 v1 描述为已经与 Flowable 完全等价。详见工作流的功能矩阵与验收套件。
M0 的实际运行、验证命令和未认证范围见 实施与验收。