架构决策与风险
# 架构决策与风险
版本 v1.5，2026-10-22。返回总览。状态分“用户已确定”“方案建议”“实施前验证”，不把规划标记成实现完成。
# 1. 决策记录
| ADR | 决策 | 状态 | 原因及代价 |
|---|---|---|---|
| 001 | Go 后端 + Vben 5 重做前端，不兼容旧 API | 用户确定方向；新 API 为方案建议 | 可统一合同，代价是重做业务页面并另做存量迁移 |
| 002 | Go workspace 多模块，统一仓库发布 | 用户要求多模块；物理组织为方案建议 | 接近能力模块边界；需管理 module 版本、依赖图和独立构建 |
| 003 | 多模块组装 Go API/worker，流程运行时也使用 Go | 方案建议 | 保留本地业务事务与有限部署单元；并非每个模块一个微服务 |
| 004 | 七种业务数据库逐个适配/认证 | 用户确定 | 需要方言 SQL、类型和锁测试；不是添加 DSN 即完成 |
| 005 | Event/Redis/RabbitMQ/Kafka/RocketMQ 可选 | 用户确定 | 端口抽象基础语义，增强能力显式声明，需运维和合同矩阵 |
| 006 | RBAC + 数据范围 + 租户权限上限 + Redis 缓存 | 用户确定目标；计算规则为方案建议 | 导航/按钮/服务端一致，缓存不能掩盖撤销 |
| 007 | 受信 TenantScope 和受控全局 repository | 方案建议 | 透明封装减少重复，仍需覆盖 raw SQL/批量/关联的隔离测试 |
| 008 | 多 realm/client，OIDC 接入成熟 IdP | 用户确定 SSO/多终端目标；OIDC 为方案建议 | 不自写授权服务器，需统一身份提供方部署/接入与登出联测 |
| 009 | 纯 Go 通用工作流，现有库复用与缺口自研 | 用户明确不要 Java，功能对标 Flowable | core/approval/resource 分层，需承担持久化恢复与高级流程语义研发 |
| 010 | JSON 表单 + 统一流程模型 + bpmn-js/简易设计器 | 方案建议 | 符合 Vben 重做方向，在线设计器和引擎语义仍有开发成本 |
| 011 | access 内存 + HttpOnly refresh + 主库撤销 | 方案建议 | 需要调整 Vben store、回调和跨标签页协调；不是默认模板行为 |
| 012 | 默认 web-antd | 可调整建议 | 用户只确定 Vben 5，UI 库尚未明确；默认统一一种避免混用 |
| 013 | 全新业务库，存量平台数据另迁移 | 默认假设 | 避免继承旧实现细节；存量库迁移另立方案 |
| 014 | 在线独立表单内置 form-instance 资源与 adapter | 评审后补全的设计 | 不需要逐表单创建业务模块；提交快照、字段/附件授权与普通资源同样受控 |
| 015 | 定义/实例固定运行语义；持久化版本准入，新旧处理器并存，显式迁移 | 评审后补全的设计 | 退役/回滚同时保护可发起定义与活动引用；先关准入再排空，防止并发发起越过检查 |
| 016 | 信息系统按 二级等保 规划应用控制与交付物；测评与备案由使用单位负责 | 用户要求完善合规；条款映射为方案建议 | 国密/MFA/行业附加项不默认纳入 R1；差距见 二级等保合规要求 |
| 017 | R2 子树范围在完整树上限内按授权事务快照迭代展开 | 已实施，验证见 M5 | 当前树最多一万节点/64 层，复用既有防环与租户锁，不引入方言递归或 closure 维护窗口；代价是扩展范围请求读取完整树，超过上限明确拒绝。未来扩大组织容量须重新测量并调整存储方案 |
| 018 | 平台/租户基础设施独立；模板显式版本复制，无隐式回退 | 用户要求全部建议，v29双库本地验收通过 | 平台标准/默认模板与私有参数分离，代码枚举不开放编辑；已有租户副本不自动覆盖，部署/安全配置保持专用入口 | | 019 | 仅Cron计算日期，共享持久执行引擎，平台业务按租户独立拆分 | 用户后续明确仅保留Cron，v29双库本地验收通过 | 旧非Cron计划停用待配置；平台无零租户，父受理不锁所有目标，子运行当前能力/限额/重试/历史各自维护；需承担独立权限/存储/并发与升级验证 |
# 2. 实施前 PoC 闸口
| 闸口 | 验证内容 | 不通过时的处理 |
|---|---|---|
| 模块化 | 两个能力模块通过契约协作、独立构建和同库事务 | 调整依赖边界，禁止循环 import 或暴露内部仓库 |
| 数据库 | Oracle/DM 驱动安装、主键、分页、事务锁和迁移失败恢复 | 更换受支持驱动/runner、记录外部依赖；不能删掉用户目标后宣称通过 |
| SSO | 两个应用单点登录、身份绑定和统一登出 | 确定提供方能力和补偿，明确无法即时撤销的边界 |
| Go 工作流 | 持久化恢复、scope/join、定时器 fencing、OR 竞争、命令事务 | 评估现成组件；未满足则自研缺口，先正确性再设计器 |
| 通用资源 | PDF 固定版本与采购单共用一个流程 | ResourceAdapter/ACL/临时 grant/活动实例唯一占位全部验收 |
| 表单与设计器 | Vben/Ant Design Vue 集成、字段校验语义一致 | 调整渲染/设计方案，不混入不兼容 UI 库 |
| 缓存 | 权限变更提交后的新请求拒绝旧授权 | 修正主库版本校验、失效和回源策略 |
# 3. 关键风险
| 风险 | 影响 | 处理与可核实证据 |
|---|---|---|
| 目标范围接近平台产品而非单一后台 | 工期低估 | R1–R4 分期，不把 MVP 当完整交付 |
| Oracle/DM 客户端、授权或测试环境不可用 | 认证受阻 | M0 申请/确认环境与架构；未跑测试标记未认证 |
| 数据库兼容协议被误当行为相同 | 隐性生产缺陷 | MariaDB/TiDB 独立 profile，锁/事务/DDL 同套测试 |
| 模块只有目录拆分，没有依赖约束 | 后期循环依赖 | 各模块公开端口、内部实现，CI 检查依赖 DAG |
| 多用户身份被 userId 混用 | 会员访问后台或跨租户 | realm/client/audience 与类型化主体，负向验收 |
| Redis 缓存过期才撤销权限 | 撤销延迟/越权 | 主库版本校验 + 版本化缓存 + 失效事件 |
| SSO 只做登录，不做身份解绑和登出 | 会话残留 | issuer/sub/sid 绑定、本地撤销、提供方登出联测 |
| 自研引擎并发与恢复错误 | 丢 token、重复任务、流程卡死 | 状态机不变量、scope/activation、fencing、故障注入与跨库合同测试 |
| 发布改变旧实例的运行语义 | 长期流程升级后行为漂移或无法恢复 | 固定 engineVersion、兼容池清单、滚动/回滚闸口与跨版本恢复用例 |
| 空实例计数掩盖仍开放的旧定义或在途发起 | 退役/回滚后无法发起或产生无处理器实例 | 持久化 draining 入口、定义准入与受理同锁同事务、引用排空、零实例/并发启用与发起测试 |
| 文件换版或权限随任务泄漏 | 批准错误版本、泄露文档 | 固定资源版本、ACL 双检、授权回收和受控下载 |
| OR/AND 仅按完成数量判定 | 拒绝被当成同意 | 决策计数和拒绝路线显式建模，测试并发同意/拒绝 |
| 流程脚本/表达式开放过度 | 执行任意代码/访问内部服务 | 受控节点和 DSL、XML/图编译校验、禁止任意脚本 |
| 统一消息抽象掩盖后端差异 | 丢失、乱序和错误重试 | Capabilities、幂等和保序需求单独验证 |
| Vben 上游 main 继续变化 | 构建漂移 | 固定 SHA + lockfile，按发布节奏评估升级 |
| 等保范围蔓延（三员、MFA、国密、行业扩展、云责任） | R1 工期与测评预期失真 | ADR-016 边界；M1–M4 已含基线；超范围单估；备案材料如实列差距 |
# 4. 保留的范围边界
“SSO”默认指 OIDC 接入现有或随平台部署的身份提供方，多个应用共用其身份会话；不默认开发自有 OIDC 授权服务器或 SAML 协议实现。
“多终端”指认证与会话协议支持及测试客户端验收；具体手机 App、小程序和会员业务页面另行设计。
“多数据库”指部署可选择且有认证版本矩阵；不承诺同一事务横跨多家数据库。工作流持久化与业务库使用同一方言认证，不能只测普通 CRUD。
“Event”暂定义为进程内事件适配器。其裸模式不保证可靠投递；可靠本地消费由数据库 outbox worker 承担。这一解释若与用户所指 Event 产品不同，应替换对应 adapter，不改业务事件合同。
“动态表单/在线流程设计”需要交付可操作设计器、校验和版本管理，不是只增加几个执行节点。“会签/或签”语义在 07-workflow.md 明确，高级构件、迁移、DMN/CMMN 在矩阵中列明后续对标阶段。
# 5. 当前进度
已完成：需求落点、架构提案、前后端合同草案、核心模型、数据库/消息策略、纯 Go 通用工作流设计、里程碑和验收要求。已核实上游来源及版本信息。
M0 已交付 Go 1.27.3 多模块、Vben 空壳/真实健康 API、迁移/bootstrap、合同和 CI；MySQL/PostgreSQL 已完成工程与工作流 PoC，Oracle/SQL Server 仅完成探针构建，达梦已在开发实例完成独立 adapter 的行为 PoC，默认 API 与迁移仍未装配。Dex 本地密码候选未满足双应用免重复登录和统一登出，已淘汰，不作为默认 IdP。登录业务、完整工作流、七库/五消息认证和性能验证尚未完成。详见 M0 实施与验收。
# 6. 最新约束与范围解释
用户将工作流要求更新为：不使用 Java；功能对标 Flowable；文件/文档与业务流程共用；组件不足时自行实现。此要求替代早期 Flowable bridge 方案。现有库初筛不等于已验证完整替代，详见工作流候选比较与分期功能矩阵。
全部自研服务和默认本地部署不要求 JVM。此前用户列出的 Kafka/RocketMQ 保留为外部协议适配目标；这不代表把它们的 broker 服务端重写为 Go。默认消息 profile 使用 Event/Redis，可选 RabbitMQ。若要求连外部基础设施也彻底无 Java，则相应 broker 需由独立的无 JVM 兼容实现通过同套协议认证，不能假定 Kafka/RocketMQ 原生 broker 满足此约束。
SSO 仍通过 OIDC 接口实现，自带 IdP 候选需验证不新增 JVM；不默认部署 Keycloak。文件/文档的具体编辑器、在线 Office 协作、OCR、电子签章不由通用审批引擎自动提供，按实际业务另接资源动作，文件审批本身在 R3 范围内。