平台概览
状态
本文说明当前代码实现的接入规则，不代表各环境已发布或可用。实际接入前请确认目标环境的发布状态与配置；文档站可访问不等于 API / MCP 服务已就绪。
使用 MCP 前先确认
不是所有管理员或员工都能使用
MCP 是付费增值服务，以下条件必须同时满足：
- 使用当前租户超级管理员（SUPERADMIN）账号，普通管理员或员工不适用。
- 当前租户已启用，主套餐状态为 ACTIVE。
- 同一租户持有有效的 MCP 订阅权益。主套餐未包含 MCP 时须另行购买，不能仅凭“已有主套餐”判断可用。
先确认当前套餐是否明确包含 MCP；未包含时到主站 服务订阅 → 增值市场（/service-subscription?tab=market）购买，再通过支持完整 OAuth 流程的 MCP 客户端授权。登录、勾选 scope 或取得令牌本身不等于开通 MCP。
MCP 客户端接入说明具体步骤，认证与授权说明身份判定及权益失效时机。
这项 MCP 订阅要求不扩展到 REST /v1/api/invoke；REST 仍受凭证、身份及权限校验约束。
请求链路
开放 API 调用使用独立域名，不经主站网关；浏览器登录、授权同意和凭证管理仍在主站完成：
调用方
│ https://open.risemap.cn/{v1|oauth|.well-known}/...
▼
负载均衡 / 边缘 nginx 按【域名】转发
│
▼
开放平台入口 nginx 按【路径】分流
├─ /v1/openapp/**、/v1/oauth/grant/** ──▶ 拒绝（404，管理接口不对外）
├─ 其余 /v1/**、/oauth/**、/.well-known/** ──▶ 开放 API 服务
│ │ 内部调用
│ ▼
│ 各业务微服务
└─ 其余 ──▶ 本文档站
/v1/openapp/** 与 /v1/oauth/grant/** 属于主站登录态的管理接口，只能经主站网关访问，不应把主站登录令牌发到开放域名。
与主站的两点差异：
- 鉴权在开放平台自身完成：调用方持平台签发的凭证（OAuth 令牌 / AppKey），每个凭证绑定一名员工，实际能力 = 授权范围 ∩ 该员工本人权限，详见认证与授权
- 调用业务微服务走内部通道，不经主站网关
统一响应格式
REST 业务接口（如 /v1/api/invoke）通过鉴权后统一返回：
{ "code": 200, "message": "success", "data": {} }
code=200 为成功，非 200 时 message 为错误描述，完整清单见错误码。
OAuth 协议端点（/oauth/**、/.well-known/**）按 RFC 返回裸 JSON，不套此格式。
MCP /v1/mcp 使用 JSON-RPC / 工具结果；鉴权与权益拒绝可能直接返回 HTTP 401 / 403 / 503，不能按业务响应格式判断。
环境
| 环境 | 域名 | 接入前确认 |
|---|---|---|
| 生产 | open.risemap.cn | 按该环境发布记录确认 |
| 预发 | open-rel.risemap.cn | 按该环境发布记录确认 |
| 开发 | open-dev.risemap.cn | 确认联调服务及配置 |
从哪里开始
- AI 客户端接入（当前租户超级管理员）：MCP 客户端接入——MCP 为付费服务，需租户启用、主套餐 ACTIVE 和同租户有效 MCP 权益；先确认或购买权益，再由兼容客户端完成 OAuth 授权
- 服务器对接（集成商）：快速接入——AppKey + 统一直通入口
SDK 与更多语言示例在开放接口成规模后提供。