OAC 平台文档

主题

总体架构：平台底层能力与 OA 门户 ​

1. 总体目标 ​

  • OA 门户作为统一认证后的默认落地应用，复用应急厅底座进行前端改造，覆盖多端响应式与核心业务页面。
  • 平台侧提供两套独立的底层能力：
    • 消息汇聚：外部应用单向推送消息到平台，OA 门户通过 HTTP 查询与 WebSocket 实时接收。
    • 待办汇聚：外部应用/事件中心生成待办并统一入库，OA 门户通过 HTTP 查询待办，处理后由三方回调消除，形成闭环。
  • 事件中心由独立项目提供，平台网关只做 API 集成与客户端鉴权接管。

2. 系统边界 ​

2.1 统一认证平台（底层能力） ​

  • 统一认证与授权：OAuth2/OIDC（已具备）。
  • 统一网关：路由、鉴权、接入方统一入口。
  • 消息汇聚服务：
    • 入站：外部应用 push 消息（客户端鉴权）
    • 存储：用户 inbox、未读统计
    • 查询：OA 门户 HTTP 拉取消息与未读
    • 推送：WebSocket 向 OA 门户推送新消息与未读变化
  • 待办汇聚服务：
    • 入站：
      • 外部系统自有待办：通过客户端鉴权推送待办
      • 事件中心待办：兼容事件中心生成的待办形态
    • 存储：统一认证模块数据库（Mongo），以用户维度聚合
    • 查询：OA 门户拉取我的待办/我的已办
    • 操作：待办发送、消除（完成/取消/失效）接口；三方系统回调消除
    • 跳转：待办处理按钮跳转到三方系统办理页
  • 事件中心 API 集成：
    • 网关路由聚合事件中心项目接口
    • 接管接入方鉴权逻辑（客户端鉴权）
    • 事件中心调用统一认证中心的 check token 完成鉴权验证

2.2 OA 门户（前端） ​

  • 复用应急厅底座，前端改造覆盖：
    • 全端响应式（Web/App 壳/Windows 壳）
    • 应用列表与跳转
    • 消息中心（列表、提醒、已读）
    • 待办（我的待办/我的已办）
    • 我的信息（资料、权限、岗位/角色、部门、账号安全）
    • 新闻公告
  • OA 门户作为单一消费端：
    • 首屏通过 HTTP 获取消息与未读
    • 长连接通过 WebSocket 实时获取新消息
    • 待办通过 HTTP 拉取“我的待办/我的已办”；点击处理跳转三方系统；待三方回调后待办统一消除

2.3 OA 门户管理端（前端路由） ​

  • 与 OA 门户同一前端工程，通过管理端路由（如 /admin/**）进入，面向高权限人群。
  • 首页用户名下拉菜单根据是否具备管理权限显示“管理后台”入口。
  • 复用 OA 门户后端服务（门户服务端）与平台底层能力，在授权范围内统一管理：
    • 待办（跨用户/跨部门）
    • 消息（跨用户/跨部门）
    • 新闻公告与内容
  • 权限模型：按部门/角色等维度限制数据范围与操作权限，并记录审计日志。

3. 关键数据流 ​

3.1 应用跳转 ​

  1. 用户完成统一认证
  2. 浏览器/壳进入 OA 门户首页
  3. OA 门户拉取用户可见应用列表
  4. 用户点击应用，调用平台提供的跳转能力并进入目标系统

3.2 消息汇聚与消费 ​

  1. 外部应用通过 client_credentials 获取 token
  2. 外部应用调用平台“消息入站 API”推送消息
  3. 平台落库并更新未读统计
  4. 平台通过 WebSocket 向 OA 门户推送新消息事件
  5. OA 门户收到推送后更新角标/列表；用户可标记已读

3.3 待办汇聚与业务闭环 ​

  1. 外部系统或事件中心产生待办
  2. 外部系统通过客户端鉴权调用平台“待办发送 API”写入待办（兼容事件中心待办结构）
  3. 平台将待办持久化到统一认证模块数据库（Mongo），并为目标用户生成 inbox 记录
  4. OA 门户通过 HTTP 拉取待办列表（我的待办/我的已办），待办列表来自平台待办库
  5. 用户点击待办“处理”按钮跳转三方系统办理页
  6. 三方系统完成办理后回调平台“待办消除 API”更新待办状态
  7. OA 门户再次拉取或收到刷新提示后，待办在统一视图中被消除

3.4 事件中心 API 接入 ​

  1. 外部应用通过客户端鉴权调用网关
  2. 网关校验客户端权限
  3. 网关转发至事件中心项目 API

4. 技术要点（行业最佳实践） ​

  • WebSocket：
    • 心跳与断线重连
    • 鉴权与会话续期
    • 消息幂等与客户端去重（以 messageId 为主键）
  • 消息模型：
    • 明确 sourceAppId、targetUserId(s)、occurredAt、messageId（幂等）
    • 索引：targetUserId + occurredAt、targetUserId + readStatus、sourceAppId + occurredAt
  • 网关鉴权：
    • 事件中心 API 与消息入站 API 统一使用客户端鉴权
    • OA 门户对消息查询与已读使用用户态鉴权
  • 待办模型与状态：
    • 明确 todoId（幂等主键）、sourceSystem、sourceBizId、assigneeUserId、initiatorUserId、status（open/cleared）
    • 兼容事件中心待办：保留 eventCenterRef 或 workflowInstanceId/taskId 等关联字段
    • 消除口径统一：完成/取消/失效均以“消除”体现，并记录 clearedAt/clearedBy/reason