feat: add HTTP API and complete client workflows
This commit is contained in:
hectorzhao
@@ -420,8 +420,9 @@
|
||||
### 5.8 客户端签名管理
|
||||
|
||||
- 支持新增、编辑、提交审核、上传证明材料。
|
||||
- 支持维护引流信息。
|
||||
- 支持查看通道报备状态。
|
||||
- “签名与引流信息”采用签名父级、引流信息子级的可展开工作台，提供真实后端统计、签名/应用/状态筛选、审核状态、已交资料数、驳回修改说明及新增、修改、删除操作。
|
||||
- 签名审核通过后支持维护短信中使用的网站、应用页面等引流信息；新增或修改后进入真实审核流程，客户端只展示“待提交、资料审核中、审核通过、需修改”等客户可理解的状态。
|
||||
- 客户端页面和 `/client` API 均不得暴露内部通道、通道组、路由规则、运营商报备汇总、报备任务及内部资料要求快照。动态审核字段接口只返回字段名称、类型、必填规则等客户填报所需信息；通道级报备状态仅限运营端查看。
|
||||
|
||||
### 5.9 客户端账户计费
|
||||
|
||||
@@ -457,6 +458,7 @@
|
||||
- 企业短信模板列表必须采用自适应布局，在常用桌面及平板视口下无需水平滚动即可看到编辑、删除等操作。
|
||||
- 运营端“企业模板管理”以响应式列表行展示模板、归属、内容、状态和更新时间；预览、编辑、删除操作在常用视口内始终可见，不得依赖水平滚动。
|
||||
- 运营端“企业签名管理”的移动、联通、电信报备状态必须将状态文字与通过数/总数允许分行展示；报备详情、报备状态、编辑、删除四个操作按钮在空间不足时按每行两个排列，不得将按钮文字挤成单字换行。
|
||||
- 运营端企业签名的状态颜色必须按统一业务语义展示：全部目标通道通过为绿色、部分通过为蓝色、审核中/报备中/资料待补充为橙色、审核或报备失败为红色、未提交/未报备/不适用为灰色；卡片总体色先遵循签名审核状态，再汇总真实通道报备状态，不能把“报备中”和“部分通过”混成同一种颜色。
|
||||
|
||||
### 5.12 运营端审核
|
||||
|
||||
@@ -507,7 +509,7 @@
|
||||
- 企业黑名单：企业应用级号码拦截，同一企业不同短信应用的黑名单互不影响。
|
||||
- 全局黑名单：平台维度号码拦截。
|
||||
- 敏感词管理：发送前和审核时命中提示或拦截。
|
||||
- 手机号段库：用于运营商识别和路由；列表使用服务端游标分页和服务端搜索，不查询或展示全库总条数。
|
||||
- 手机号段库：用于运营商识别和路由；号段与运营商区分规则使用真实服务端分页、搜索和总数。通用 Tab 位于页面标题下、搜索条件上；每个 Tab 只显示本类统计数字，不同时展示另一类统计。
|
||||
- 引流信息字段库：用于签名/报备资料结构化采集。
|
||||
- 企业应用级黑名单、全局黑名单、敏感词管理必须提供搜索、添加、启停/删除功能；所有操作调用真实后端 API，写入系统日志。
|
||||
- 企业黑名单必须绑定到具体短信应用，支持按企业、应用、手机号、入库原因、状态搜索；发送预览、风控和发送链路只能拦截当前应用的 active 黑名单号码，不得把同企业其他应用的黑名单串用；全局黑名单支持按手机号、原因、状态搜索；敏感词支持按词、分类/级别、状态搜索。
|
||||
@@ -1435,6 +1437,7 @@
|
||||
- 单次登录绝对时长为 12 小时，无论是否持续操作均不得自动续期；到期必须使用账号、密码和图形验证码完整登录。修改密码、禁用/删除用户、角色变化和管理员强制下线必须通过 `sessionVersion` 和 Redis 会话立即撤销现有会话。
|
||||
- 用户、权限、企业状态、应用密钥、通道配置、路由、报备状态和资金调整等敏感操作要求最近 30 分钟内验证过当前密码。超时后由后端返回 `RECENT_AUTHENTICATION_REQUIRED`，前端验证当前密码后自动重试原操作；不能只依赖前端弹窗判断。
|
||||
- 主动退出、空闲锁定、密码解锁、敏感操作再认证和会话创建均需写真实系统日志；多标签页使用浏览器消息同步锁定、解锁和退出。普通网络错误、400、403 业务拒绝或 5xx 不得被误判为自动退出。
|
||||
- 在同一浏览器已有运营端或客户端会话时，另一个入口的账号、密码、角色或验证码登录失败只属于本次登录尝试，不得清理、广播退出或跳转已有会话；只有现有会话自身的 401 失效响应才触发退出处理。
|
||||
|
||||
### 2. 用户类型和企业关联
|
||||
|
||||
@@ -1487,3 +1490,28 @@
|
||||
4. 创建批次时按每条资料所属企业应用的当前生效路由规则展开所有通道；一个签名走多个通道时，必须为每个通道创建或重置独立报备任务并生成一份该通道的 `.xlsx`。无生效路由、通道未配置字段或缺少通道必填资料时，该资料继续保留在待报备池，任务进入“资料待补充”，不得伪装为已完成。
|
||||
5. 通道“配置签名报备字段”和“配置引流信息字段”弹窗使用字段池，按资料类型分别配置。每列包含标准字段、通道导出表头、列顺序、必填、说明、列宽、文本转换、缺省值以及图片宽高；导出表头和列顺序必须严格使用通道配置，不受导入表格原始名称和顺序影响。
|
||||
6. 通道导出文件必须为 WPS/Excel 可打开的 `.xlsx`，图片直接内嵌到对应单元格区域，而不是仅写 MinIO URL 或本地路径。批次保留所选材料版本快照、通道文件、行号和通道任务关联，可从最近批次直接下载每个通道文件。
|
||||
## HTTP 客户接口第一版
|
||||
|
||||
### 管理端企业应用配置
|
||||
|
||||
- CMPP 与 HTTP 是两套可独立开通的接入能力，不再把 HTTP 作为 `interfaceType` 的互斥选项。运营端在企业应用“接口配置”中维护 HTTP 总开关，以及单条发送、短信状态查询、回执 Webhook、上行 Webhook、上行查询、客户端凭据自助管理等子能力。
|
||||
- HTTP 配置独立维护 IP/CIDR 白名单、应用级 QPS、签名时间容差、最多有效凭据数、上行保留/查询范围/分页上限、Webhook 超时和最多尝试次数、生产 HTTPS 约束、客户手工重投权限。
|
||||
- 回执和上行分别配置 `cmpp/http/both/none` 投递模式。Gateway 产生的回执或上行必须先写入现有真实短信记录，再按模式投递；HTTP 回调不得取代或伪造 Gateway、回执匹配和上行认领链路。
|
||||
- HTTP 访问密钥和 Webhook 签名密钥使用 `HTTP_API_MASTER_KEY` 派生的 AES-256-GCM 密钥加密保存。Secret 只在创建或轮换当次返回，后续运营端和客户端仅显示末四位；允许同时保留多个有效凭据以完成无停机轮换。
|
||||
|
||||
### 客户接口与安全约束
|
||||
|
||||
- 第一版提供 `POST /api/openapi/v1/sms/messages` 单条发送、`GET /api/openapi/v1/sms/messages/{messageId}` 状态查询、`GET /api/openapi/v1/sms/uplinks` 上行游标查询和 `GET /api/openapi/v1/sms/uplinks/{uplinkId}` 上行详情。
|
||||
- 身份只由 `X-App-Key` 对应凭据确定，不接受请求体中的企业或应用身份。签名原文为 `METHOD + "\n" + PATH + "\n" + X-Timestamp + "\n" + X-Nonce + "\n" + SHA256(rawBody)`，使用 Secret 执行 HMAC-SHA256。
|
||||
- 时间戳默认允许正负 5 分钟；签名成功后使用 Redis `SET NX EX` 防 nonce 重放，并按应用在 Redis 执行秒级 QPS 限制。IP 白名单与 CMPP 白名单相互独立。
|
||||
- 单发必须提供 8～128 位 `Idempotency-Key`。PostgreSQL 对 `(applicationId, idempotencyKey)` 建唯一约束并保存请求体哈希和响应快照：相同内容重放原响应，不同内容返回 409；`clientMessageId` 在应用内唯一。
|
||||
- 单发复用现有 `SendChainService`，必须经过真实企业/应用、签名、模板、风控、余额、计费、通道路由和 Redis 队列链路；接收成功返回 202，不代表运营商提交或终端到达成功。
|
||||
- 上行查询只返回已匹配或人工认领到当前应用的记录，默认最近 24 小时，单次范围和分页上限由应用配置控制；未匹配和歧义上行不得泄露给任一客户。
|
||||
- 客户错误使用 `application/problem+json` 和稳定业务码。客户 Swagger 只包含四个 `/openapi/v1` 接口，不得包含 admin、client 管理或 gateway 内部接口。
|
||||
|
||||
### HTTP Webhook 与客户端页面
|
||||
|
||||
- 状态回执和上行回调分别配置 HTTPS URL 与独立事件类型，共享该端点的签名密钥；每个事件生成唯一 `eventId`。回调请求用 `TIMESTAMP + "\n" + rawBody` 执行 HMAC-SHA256，客户必须按 `eventId` 幂等。
|
||||
- Webhook 禁止重定向，并在保存和每次投递前解析域名，拒绝环回、私网、链路本地、共享地址和元数据地址。2xx 成功；网络错误、408、429、5xx 可按立即、1 分钟、5 分钟、15 分钟、1 小时、6 小时、24 小时重试；其他 4xx 直接终结。
|
||||
- PostgreSQL 分别保存 Webhook 事件、投递状态和每次尝试摘要；客户和运营人员可查询，授权后可手工重投。首次投递与重试均由 BullMQ 执行，不得使用浏览器定时器或 localStorage 冒充。
|
||||
- 客户端“短信基础配置”新增“接口对接”，包含接口概览、访问凭据、回调配置、接口文档、调用与回调记录五个页签；企业应用卡片显示 HTTP 开通状态并跳转。客户端上行列表改为真实服务端条件查询，不再先拉全量数据后仅在浏览器过滤。
|
||||
|
||||
Reference in New Issue
Block a user