31 lines
2.8 KiB
Markdown
31 lines
2.8 KiB
Markdown
# 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 必须校验回调地址、签名、超时、重试和幂等；失败事件进入可追踪的死信队列。
|
|
- 邀请注册 API 仅允许校验短链接、查询脱敏转化统计或经授权建立服务关系；不得返回邀请码明文、用户账户凭证、完整地址或组织管理员信息。
|
|
- 配送轨迹 API 默认只提供订单履约状态、预计到达和用户可见的简化轨迹。精确坐标、轨迹回放、服务人员非履约位置、签名和现场视频属于受限数据，须独立产品、审批、短期授权和用途审计。
|
|
|
|
## 4. 开发者体验与扩展
|
|
|
|
- 提供沙箱、模拟数据、在线文档、SDK、变更公告、调用日志、工单和状态页。
|
|
- 扩展 API 商店、套餐计费、合作方评分、数据共享审批、字段级脱敏模板和跨境数据合规检查。
|