集成总览
你想把业务接到 rust_svc 上，或把 rust_svc 的能力嵌进你的系统——从这里开始。
四种集成姿态
| 姿态 | 入口 | 说明 |
|---|---|---|
| 调 API 的应用 | 北向 REST API | 90% 的场景：登录拿 JWT，调 /api/v1/* |
| 机器对机器 | 认证与令牌 的 AppToken | 服务账号：签发 AppToken → 换 15min App JWT |
| 实时订阅 | WebSocket | :8082 一次性 JWT + topic 订阅协议（注意数据面桥接边界） |
| 扩展平台 | 插件 SDK | authenticate/authorize/execute_step 等五个扩展点（宿主接线状态诚实标注） |
内部 gRPC 契约（grpc-api）主要供平台自身与深度集成方使用； 错误语义统一见错误模型。
集成检查清单
- 拿到平台地址（单机
http://host:8080；云化经 ingress host）； - 管理员执行
--bootstrap建租户与管理账号（或由平台方提供）； - 为你的应用建 AppToken（
POST /api/v1/apps→POST /api/v1/tokens）， 机器流量走POST /api/v1/auth/token换短时 JWT； - 若要写数据：先建实体（或使用既有实体），再向 IAM 申请 policy/access-rule 授权（默认拒绝，见第一次调用）；
- 处理
problem+json错误面（错误模型）， 按code分段路由你的告警与重试策略； - 需要空间/瓦片能力：见 GIS 概念与 OpenAPI 的 layers/tiles/tags 域；
- 关注配额与限流的 429 语义（软限流四级），实现退避重试。
契约事实源
| 面 | 事实源 | 校验 |
|---|---|---|
| REST | api/openapi/v1/openapi.yaml（OpenAPI 3.0.3，224 paths，手工冻结） | 运行时 /openapi.yaml、Swagger /docs；redocly 解析校验 |
| gRPC | api/proto/**（7 域） | CI buf lint + buf breaking |
| 错误码 | crates/platform-core/src/error.rs 分段表 | 错误码参考 |
北向未接线的面（避免误期待）
/api/v1/authz/*（授权管理北向面）当前 404/1004——授权管理经 internal 面 或控制台；OIDC/LDAP 联合认证未实现。