平台能力集成

约 1427 字大约 5 分钟

2026-10-16

应用已经能独立运行后，再接入平台的访问入口、应用菜单、权限与调度。部署、注册和授权分别验收。

五种不同的注册

对象	在哪里实现	如何确认
应用业务 HTTP handler	自己的后端	直接调用自己的业务 API
平台代理路由	平台允许的 RouteManage RPC 或管理员配置	通过平台地址访问实际业务接口
Web 页面路由	自己的前端	页面跳转、直达与刷新
应用和菜单	平台应用/菜单管理	实际成员的应用与菜单列表
定时任务	平台 timed + 应用消费者	触发消息到达且产生业务结果

菜单不会自动生成页面，声明 API 权限也不会自动创建代理；接口存在、菜单可见与成员有权访问是三项检查。

注册应用与菜单

平台管理员分配稳定的数字应用 ID，确认客户端/管理端、Web/移动端与入口地址。
使用当前合同的应用和菜单管理接口，先查询再创建或更新，不重复生成 ID。
父菜单先创建，子菜单使用实际父 ID；路径与页面一致，组件标识匹配宿主映射。
为目标企业开通应用，再配置成员角色、菜单与动作权限。
使用真实成员查询自己的应用和菜单列表，验证无权成员的拒绝结果。

应用 HTTP 接口使用 /api/v1/system/app/info/ 前缀，操作为 create、get-one、update、get-list；菜单使用 /api/v1/system/app/menu/ 前缀，操作为 create、get-list、update。需要幂等批量导入时，AppMenuBatchImport 属于 Core RPC，不存在可凭空拼出的 HTTP /batch-import。

前端构建的数字 AppID、菜单所属应用和后端应用上下文保持一致。它不同于微信小程序厂商 AppID。

注册平台代理路由

先让自己的服务在平台网络中可达，再通过批准的服务身份调用公开 RouteManage 合同。下面展示注册逻辑，gRPC 连接及可信上下文由服务认证配置提供：

package registration

import (
    "context"
    "encoding/json"
    "github.com/unitedrhino/ur-kit/sdks/go/pb/core/service/syssvr/pb/sys"
    "google.golang.org/grpc"
)

// RegisterRoutes 登记本服务完整路由清单，upstream 是平台可达的应用地址。
func RegisterRoutes(ctx context.Context, connection grpc.ClientConnInterface, upstream string) error {
    config, err := json.Marshal(map[string]string{
        "code": "my-app-api", "location": "/api/v1/my-app/:suffix", "proxyPass": upstream,
    })
    if err != nil { return err }
    _, err = sys.NewRouteManageClient(connection).RouteInfoBatchUpsert(ctx, &sys.RouteInfoBatchUpsertReq{
        ServiceCode: "my-app",
        List: []*sys.RouteInfo{{Name: "my-app-api", Location: "/api/v1/my-app/:suffix", Proxy: string(config)}},
    })
    return err
}

该 RPC 按 serviceCode 上报本服务完整清单，会清理本次未上报的旧路由。不能复用别的服务标识，也不能把一个局部变更当作全量。HTTP 路由查询/更新接口不能替代这个创建流程；无 RPC 权限时由平台管理员配置支持的代理来源。

页面与权限

Web 在自己的 src/router/routes/modules/ 注册生产路由，懒加载 views 中的页面，再创建匹配菜单。验证成员可见性、无权 URL、详情直达、企业切换和 SPA 静态基路径。

应用后端仍须验证身份与资源动作，不能因为入口来自平台代理就信任请求内的角色或内部身份头。注册结果核对可使用 ur 的现有平台 API 能力，未开放的 RPC 仍由服务实现。

定时任务与消费者

采用自己的稳定 groupCode 和任务 code，先初始化业务消费者。
创建任务组和任务；RPC 使用 TaskGroupCreate、TaskInfoCreate，管理 HTTP 入口为 /api/v1/system/job/task/group/create 与 /api/v1/system/job/task/info/create。
Cron 类型使用 type=1、cronExpr 与 JSON 字符串 params；延时类型按合同提供毫秒 executeAt。
订阅实际主题 server.timed.<groupCode>.<taskCode>，解析平台触发信封，再执行业务。
测试立即触发、重复触发、停用、重启恢复和权限失效，处理器按业务做幂等。

仅在数据库中创建任务不会自动执行代码，params.topic 也不会改写真实调度主题。任务管理、RPC、NATS 权限需分别取得，不伪造 root 元数据。

接入 Hook 扩展点

先确认平台已经实现所需的 code + subCode 扩展点，以及其请求、返回值与失败语义。仅创建一个新的能力编码，不会自动给平台增加触发逻辑。

在自己的后端提供平台可达的 HTTP POST 回调地址。
经管理员授权，使用 /api/v1/system/hook/server/create 注册服务，配置 endpoint、authType、timeoutSec、maxRetry 和 failPolicy。
使用 /api/v1/system/hook/capability/create 将 serverID 与约定的 code、subCode 关联；先查询已有记录，再创建或更新。
触发对应平台业务，核对回调内容、返回结果、超时和重试；有副作用的处理按 X-Hook-Request-Id 和业务键幂等。

平台请求包含 method（code.subCode）、data 和可选 userCtx；标准响应为 {"code":200,"msg":"","data":{}}，其中 data 按具体扩展点约定返回。

使用 HMAC 时，authConfig.secret 在运行环境配置；回调方读取秒级 X-Hook-Timestamp，以原始请求体计算 HMAC-SHA256(secret, timestamp + "." + body) 的十六进制摘要，与 X-Hook-Signature 的 hmac-sha256=<摘要> 常量时间比较，并校验时间窗口。验签后再使用请求上下文，不能直接信任外部提交的 userCtx。独立应用按公开 HTTP 合同实现回调，不导入平台私有 Hook 包。

合同字段见固定版本 OpenAPI，路由、菜单和任务的完整初始化顺序见注册指南。

更新日志

2026/10/16 20:08

查看所有更新日志

b1437-docs(应用开发): 补齐WS通知及平台能力接入导航于 2026/10/16
1a4a7-docs(开发指南): 重建平台与应用开发路线于 2026/10/16

后端专题

实时通信

业务能力