2.3 KiB
2.3 KiB
API 中心管理系统需求
1. 定位与使用者
API 中心管理系统用于治理平台向可燃气体站、生产合作方、配送合作方、设备厂商和经授权第三方开放的 API。它提供 API 产品、调用方、凭证、订阅、配额、文档和审计管理；不替代平台总后台对订单、设备、资金等业务事实的主数据管理。
2. API 产品管理
| 模块 | 功能 | 规则 |
|---|---|---|
| API 目录 | 设备查询、遥测订阅、订单同步、库存调拨、售后、内容等 API 产品 | 按业务域、版本、环境、受众、数据等级和 SLA 管理 |
| 生命周期 | 设计、评审、发布、灰度、废弃、下线 | OpenAPI/AsyncAPI 契约版本化；破坏性变更需弃用期和通知 |
| 应用接入 | 合作方组织、应用、回调地址、用途、负责人、资质审核 | 一应用一身份；生产环境需审核后开通 |
| 认证授权 | OAuth 2.1/OIDC、客户端凭证、mTLS、签名、密钥轮换和吊销 | 最小权限、短期令牌、密钥不可明文回显 |
| 流量治理 | 配额、限流、并发、IP/地域策略、熔断、重试、沙箱 | 按 API 产品和调用方策略执行；高风险写操作可二次签名 |
| 事件订阅 | Webhook、MQTT/消息主题、事件 Schema、投递重试和死信 | 消息签名、幂等事件 ID、订阅范围及回放权限受控 |
| 监控审计 | 调用量、成功率、延迟、错误、配额、敏感访问、导出 | 不记录完整密钥和敏感载荷；可关联 request_id 和审计事件 |
3. 对外接口安全红线
- 默认不开放远程开阀、强制解除安全限制、提现审核等高危能力；确需开放须独立 API 产品、最小范围、双重鉴权、审批和实时审计。
- 对外查询仅返回调用方业务所需字段，用户手机号、地址、定位、视频、资金信息按数据分类和授权协议最小化提供。
- Webhook 必须校验回调地址、签名、超时、重试和幂等；失败事件进入可追踪的死信队列。
4. 开发者体验与扩展
- 提供沙箱、模拟数据、在线文档、SDK、变更公告、调用日志、工单和状态页。
- 扩展 API 商店、套餐计费、合作方评分、数据共享审批、字段级脱敏模板和跨境数据合规检查。