OAC 平台文档

主题

API 草案：消息汇聚（平台侧）+ OA 门户（消费端）+ 事件中心 API 集成（网关侧） ​

这是接口形态建议，用于任务拆分与接口对齐；落地时需结合现有网关路由与服务命名。

1. 统一约定 ​

  • 认证：OAuth2 Bearer Token。
  • 外部应用接入：client_credentials。
  • OA 门户：用户态访问。
  • API 前缀：经网关统一暴露（示例）。

2. 事件中心（网关集成） ​

平台不实现事件中心底层引擎能力，仅在网关侧完成 API 聚合与鉴权接管。

  • ANY /event-center/**（示例）
    • 用途：转发到事件中心项目对应接口
    • 鉴权：客户端鉴权（client_credentials）
    • 说明：网关负责统一接入与权限控制，不在本项目内实现业务逻辑

事件中心鉴权模型：

  • 事件中心在处理业务 API 时，会调用统一认证中心的 check token 接口完成 token 有效性验证。

3. 消息汇聚（平台侧） ​

3.1 外部应用推送消息（入站） ​

POST /message-hub/messages

  • 用途：外部应用单向推送消息到平台
  • 鉴权：客户端鉴权（client_credentials）
  • 关键字段（示例）：
    • sourceAppId
    • targetUserIds（明确用户维度，MVP）
    • title / content
    • category
    • actions（可为空：跳转链接）
    • occurredAt

3.2 OA 门户查询消息（HTTP） ​

  • GET /message-hub/inbox?status=unread&cursor=&size=

    • 鉴权：用户态（OA 门户）
    • 返回：消息列表与未读统计（可分接口）

  • POST /message-hub/messages/{id}/read

    • 鉴权：用户态
    • 行为：幂等标记已读

4. OA 门户待办与已办 ​

OA 门户只保留两类待办视图：

  • 我的待办：待办汇聚接口查询 status=open
  • 我的已办：待办汇聚接口查询 status=cleared

5. WebSocket 推送（平台 → OA 门户） ​

GET /message-hub/ws（示例）

  • 用途：平台向 OA 门户推送新消息与未读变化
  • 鉴权：用户态（建议复用现有登录态/Token 校验）
  • 消息类型示例：
    • message.created
    • inbox.unread.changed

6. 应用列表与跳转（OA 门户页面对接） ​

OA 门户侧需要的接口形态：

  • GET /apps：获取用户可见应用列表
  • GET /apps/{appId}/jump：获取跳转地址或直接 302（具体以现有后端实现为准）

6.1 OA 门户后端服务（门户服务端，OA 门户 API 服务） ​

说明：OA 门户前端与管理端前端统一通过“门户服务端”获取聚合数据并完成权限校验；门户服务端再对接网关、消息汇聚服务与待办汇聚服务。

门户通用：

  • GET /portal/me：用户信息与权限概览（含是否具备管理权限）
  • GET /portal/home：首页聚合数据（未读消息数、待办数等）
  • GET /portal/apps：应用列表（可转发/聚合 /apps）
  • GET /portal/apps/{appId}/jump：跳转能力（可转发/聚合 /apps/{appId}/jump）

消息（用户态）：

  • GET /portal/messages?status=unread|read&cursor=&size=：消息列表
  • POST /portal/messages/{id}/read：标记已读

待办（用户态）：

  • GET /portal/todos?status=open|cleared&cursor=&size=：我的待办/我的已办

管理端（用户态 + 管理权限）：

  • GET /portal/admin/permissions：管理端数据范围与功能点权限
  • GET /portal/admin/todos?...：跨用户/部门待办查询与管理
  • GET /portal/admin/messages?...：跨用户/部门消息查询与管理
  • GET /portal/admin/cms/...：栏目/文章管理
  • POST /portal/admin/files/upload：图片/附件上传

7. 待办汇聚（平台侧，独立于消息体系） ​

说明：待办与消息属于两套接口体系。待办支持来源于事件中心的待办与外部系统自有待办，统一持久化到统一认证模块数据库（Mongo）。

7.1 外部系统发送待办（入站） ​

POST /todo-hub/todos

  • 用途：外部系统创建/更新待办（幂等）
  • 鉴权：客户端鉴权（client_credentials）
  • 请求字段建议：
    • todoId（幂等主键，推荐 UUID）
    • sourceSystem（来源系统标识）
    • sourceBizId（来源业务主键，可用于幂等辅助）
    • assigneeUserId（待办处理人）
    • initiatorUserId（发起人，可为空）
    • title / summary
    • actionUrl（处理跳转地址或路由信息）
    • actionAppId（目标应用，可为空）
    • dueAt（可为空）
    • payload（可为空，扩展字段）
    • eventCenterRef（可为空：兼容事件中心待办关联，如 instanceId/taskId）

7.2 OA 门户查询待办（HTTP） ​

GET /todo-hub/todos?status=open|cleared&cursor=&size=

  • 用途：OA 门户拉取“我的待办/我的已办”
  • 鉴权：用户态
  • 说明：平台统一从待办库返回结果，不通过事件中心聚合待办视图

7.3 待办消除（回调闭环） ​

POST /todo-hub/todos/{todoId}/clear

  • 用途：三方系统完成办理后回调，消除待办
  • 鉴权：客户端鉴权（client_credentials）
  • 请求字段建议：
    • result（done/cancel/invalid）
    • clearedAt（可为空，默认当前时间）
    • clearedBy（可为空：用户标识/系统标识）
    • reason（可为空）

7.4 待办取消/失效（发起方主动） ​

POST /todo-hub/todos/{todoId}/invalidate

  • 用途：发起方在业务撤销时主动消除待办
  • 鉴权：客户端鉴权

8. OA 门户管理端（高权限人群） ​

说明：管理端与 OA 门户共用同一前端工程，通过管理端路由（如 /admin/**）进入；后端复用“门户服务端”与平台底层能力。管理端以“用户态 + 管理权限”访问接口，并按部门/角色等维度做数据范围控制。

8.1 内容管理（栏目/文章） ​

  • GET /admin/cms/channels：栏目列表
  • POST /admin/cms/channels：新增栏目
  • PUT /admin/cms/channels/{id}：编辑栏目
  • POST /admin/cms/channels/{id}/enable：启用
  • POST /admin/cms/channels/{id}/disable：禁用

栏目字段建议：

  • name
  • type（news/notice）
  • sort
  • enabled
  • visibleFor（可见范围，可按后续权限模型落地）

文章（Article）

  • GET /admin/cms/articles?channelId=&type=&status=&q=&cursor=&size=：文章列表
  • POST /admin/cms/articles：新增文章（草稿）
  • PUT /admin/cms/articles/{id}：编辑文章
  • POST /admin/cms/articles/{id}/publish：发布
  • POST /admin/cms/articles/{id}/unpublish：下线
  • POST /admin/cms/articles/{id}/pin：置顶
  • POST /admin/cms/articles/{id}/unpin：取消置顶

文章字段建议：

  • title
  • summary
  • coverImageUrl（可为空）
  • contentHtml（富文本 HTML）
  • contentJson（可为空：编辑器结构化数据）
  • status（draft/published/offline）
  • pinned、pinnedAt
  • occurredAt（展示时间）

前台展示（OA 门户）

  • GET /cms/feeds?type=news&cursor=&size=：新闻列表
  • GET /cms/feeds?type=notice&cursor=&size=：公告列表
  • GET /cms/articles/{id}：文章详情

8.2 待办管理（跨用户/跨部门） ​

  • GET /admin/todo-hub/todos?userId=&deptId=&roleId=&sourceSystem=&status=open|cleared&cursor=&size=

    • 用途：按授权范围查询待办/已办
    • 鉴权：用户态 + 管理权限

  • POST /admin/todo-hub/todos/{todoId}/clear

    • 用途：按权限消除待办（完成/取消/失效）
    • 鉴权：用户态 + 管理权限

8.3 消息管理（跨用户/跨部门） ​

  • GET /admin/message-hub/inbox?userId=&deptId=&sourceAppId=&status=unread|read&cursor=&size=

    • 用途：按授权范围查询消息
    • 鉴权：用户态 + 管理权限

  • POST /admin/message-hub/messages/{id}/read

    • 用途：按权限修正已读状态
    • 鉴权：用户态 + 管理权限