Files

1105 lines
61 KiB
YAML
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
openapi: 3.0.3
info:
title: go-sms API v1(阶段 2:账号与权限)
version: 1.5.0
description: |
阶段 2(Day 21-30)交付的账号与权限域全部端点。
统一响应 {code,msg,data}:code=ISC:000 成功;错误码三位制(ISC:4xx/5xx)。
认证:Authorization Bearer JWT(除 /auth/login);敏感路由另挂 Casbin 细粒度门禁。
servers:
- url: /api/v1
security:
- bearerAuth: []
tags:
- {name: auth, description: 认证(Day 24)}
- {name: accounts, description: 账号 CRUD 与配置(Day 21-23)}
- {name: hierarchy, description: 上级切换/标星/团队/实名(Day 28)}
- {name: recharge, description: 充值与余额(Day 26)}
- {name: warning, description: 余额预警(Day 27)}
- {name: permissions, description: 二级权限与导出(Day 25)}
- {name: audit, description: 审计查询(Day 29)}
- {name: channel, description: 通道 CRUD/测试工具/拦截配置(Day 31-36)}
- {name: billing, description: 充值订单审核/消耗日汇总(S2)}
- {name: settle, description: 下家/上家月结与阶梯价(S2)}
paths:
/auth/login:
post:
tags: [auth]
summary: 登录(公开;5 次失败锁 15 分钟)
security: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [username, password]
properties:
username: {type: string}
password: {type: string, minLength: 6}
responses:
"200": {description: "data: token/expires_in/username/role + user{account_id,username,roles[],permissions[]}(Day 31 前端契约)"}
"401": {description: 用户名或密码错误}
"429": {description: 连续错误锁定}
/auth/logout:
post: {tags: [auth], summary: 登出(令牌入黑名单), responses: {"200": {description: ok}}}
/auth/refresh:
post: {tags: [auth], summary: 刷新令牌(轮换,旧令牌失效), responses: {"200": {description: 新 token}}}
/accounts:
post:
tags: [accounts]
summary: 开户(业务位掩码+bcrypt+事务;自动绑定 Casbin 角色)
requestBody:
required: true
content:
application/json:
schema: {$ref: "#/components/schemas/CreateAccount"}
responses:
"200": {description: 账号已创建}
"400": {description: 参数/角色/掩码非法}
get:
tags: [accounts]
summary: 分页列表(标星置顶;username/protocol/status 过滤)
parameters:
- {name: page, in: query, schema: {type: integer, default: 1}}
- {name: page_size, in: query, schema: {type: integer, default: 20, maximum: 100}}
- {name: username, in: query, schema: {type: string}}
- {name: status, in: query, schema: {type: integer}}
- {name: protocol, in: query, schema: {type: string}}
- {name: starred, in: query, schema: {type: boolean}}
responses:
"200": {description: 分页结果}
/accounts/{id}:
parameters: [{name: id, in: path, required: true, schema: {type: integer, format: int64}}]
get: {tags: [accounts], summary: 详情(账号+业务配置), responses: {"200": {description: ok}, "404": {description: 不存在}}}
put:
tags: [accounts]
summary: 部分更新(real_name/role/parent_id/svc_team/remark;改角色自动重绑 Casbin)
requestBody: {content: {application/json: {schema: {type: object}}}}
responses: {"200": {description: ok}}
delete: {tags: [accounts], summary: 删除(守卫:有发送记录拒删;同步解绑 Casbin), responses: {"200": {description: ok}, "429": {description: 有发送记录不可删}}}
/accounts/{id}/status:
put:
tags: [accounts]
summary: 启用/禁用(禁用即存量 Token 失效)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
requestBody: {content: {application/json: {schema: {type: object, properties: {status: {type: integer, enum: [0, 1]}}}}}}
responses: {"200": {description: ok}}
/accounts/{id}/ip-bindings:
get: {tags: [accounts], summary: 查询 IP 白名单, parameters: [{name: id, in: path, required: true, schema: {type: integer}}], responses: {"200": {description: ips 数组}}}
put:
tags: [accounts]
summary: 设置 IP 白名单(JSON 数组/CIDR)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
requestBody: {content: {application/json: {schema: {type: object, required: [ips], properties: {ips: {type: array, items: {type: string}}}}}}}
responses: {"200": {description: ok}}
/accounts/{id}/protocol:
put:
tags: [accounts]
summary: 设置接入协议(A-2.1 四协议 http/cmpp/smpp/web)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
requestBody: {content: {application/json: {schema: {type: object, required: [business, protocol], properties: {business: {type: string}, protocol: {type: string, enum: [http, cmpp, smpp, web]}}}}}}
responses: {"200": {description: ok}, "404": {description: 业务线不存在}}
/accounts/{id}/audit-mode:
put:
tags: [accounts]
summary: 审核模式(0 免审/1 手动/2 自动审核——黑词命中拒/未命中过)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
requestBody: {content: {application/json: {schema: {type: object, required: [business, mode], properties: {business: {type: string}, mode: {type: integer, enum: [0, 1, 2]}}}}}}
responses: {"200": {description: ok}}
/accounts/{id}/business/{biz}/enable:
post: {tags: [accounts], summary: 开通业务线, parameters: [{name: id, in: path, required: true, schema: {type: integer}}, {name: biz, in: path, required: true, schema: {type: string}}], responses: {"200": {description: ok}}}
/accounts/{id}/business/{biz}/disable:
post: {tags: [accounts], summary: 关闭业务线(硬删配置行), parameters: [{name: id, in: path, required: true, schema: {type: integer}}, {name: biz, in: path, required: true, schema: {type: string}}], responses: {"200": {description: ok}}}
/accounts/{id}/business-status:
get: {tags: [accounts], summary: 业务线开关状态, parameters: [{name: id, in: path, required: true, schema: {type: integer}}], responses: {"200": {description: "map[business]bool"}}}
/accounts/{id}/parent:
post:
tags: [hierarchy]
summary: 切换上级(物化路径防环+子孙级联重写;account:write)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
requestBody: {content: {application/json: {schema: {type: object, required: [parent_id], properties: {parent_id: {type: integer}}}}}}
responses: {"200": {description: ok}, "400": {description: 成环}, "404": {description: 上级不存在}}
/accounts/{id}/star:
post:
tags: [hierarchy]
summary: 标星/取消(列表置顶;account:write)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
requestBody: {content: {application/json: {schema: {type: object, properties: {starred: {type: boolean}}}}}}
responses: {"200": {description: ok}}
/accounts/{id}/svc-team:
put:
tags: [hierarchy]
summary: 绑定服务团队(空串清除;account:write)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
requestBody: {content: {application/json: {schema: {type: object, properties: {svc_team: {type: string, maxLength: 64}}}}}}
responses: {"200": {description: ok}}
/accounts/{id}/realname:
get:
tags: [hierarchy]
summary: 实名信息(证件号脱敏;本人或 admin)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
responses: {"200": {description: real_name/id_card(脱敏)/status}}
post:
tags: [hierarchy]
summary: 提交实名资料(状态置 0 待审;已通过不可重提)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
requestBody: {content: {application/json: {schema: {type: object, required: [real_name, id_card], properties: {real_name: {type: string}, id_card: {type: string, minLength: 15}}}}}}
responses: {"200": {description: ok}, "400": {description: 已通过/参数非法}}
/accounts/{id}/realname/review:
post:
tags: [hierarchy]
summary: 实名审核(仅待审态;account:write)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
requestBody: {content: {application/json: {schema: {type: object, properties: {approve: {type: boolean}, reason: {type: string}}}}}}
responses: {"200": {description: status=1 通过/2 驳回}, "400": {description: 非待审态}}
/accounts/{id}/balance:
get:
tags: [recharge]
summary: 余额查询(余额/授信+近 20 条流水;非 admin 仅本人)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
responses: {"200": {description: ok}, "403": {description: 越权}, "404": {description: 不存在}}
/accounts/{id}/recharge:
post:
tags: [recharge]
summary: 单笔充值(事务:余额自增+流水;account:recharge 二级权限)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
requestBody: {content: {application/json: {schema: {type: object, required: [amount], properties: {amount: {type: integer, minimum: 1, maximum: 10000000000}, remark: {type: string}}}}}}
responses: {"200": {description: 返回新余额与流水号}, "403": {description: 无 recharge 权限}}
/accounts/recharge/batch:
post:
tags: [recharge]
summary: CSV 批量充值(username,amount[,remark];multipart file 或原文;行级结果)
requestBody:
content:
text/csv: {schema: {type: string}}
multipart/form-data: {schema: {type: object, properties: {file: {type: string, format: binary}}}}
responses:
"200": {description: total/success/failed/rows(行号+原因)}
"400": {description: 空 CSV/超 1000 行/坏格式}
/accounts/{id}/warning:
get:
tags: [warning]
summary: 预警配置(本人或 admin)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
responses: {"200": {description: config(未配置为 null)}}
put:
tags: [warning]
summary: 设置预警(阈值/冷却分钟/渠道/接收 webhook)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
requestBody: {content: {application/json: {schema: {type: object, required: [threshold], properties: {threshold: {type: number, exclusiveMinimum: 0}, cooldown_min: {type: integer, maximum: 1440}, notify_type: {type: string, enum: [wechat, dingtalk]}, notify_to: {type: string}}}}}}
responses: {"200": {description: ok}}
delete:
tags: [warning]
summary: 停用预警(保留参数)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
responses: {"200": {description: ok}}
/accounts/export:
get:
tags: [permissions]
summary: 全量账号 CSV 导出(BOM;上限 1 万行;account:export 二级权限)
responses:
"200": {description: text/csv}
"403": {description: 无 export 权限}
/accounts/{id}/permissions:
get:
tags: [permissions]
summary: 二级权限列表
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
responses: {"200": {description: permissions 数组}}
/accounts/{id}/permissions/{perm}/grant:
post:
tags: [permissions]
summary: 授予二级权限(recharge/proxy_send/export/send;account:write)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}, {name: perm, in: path, required: true, schema: {type: string}}]
responses: {"200": {description: ok}, "400": {description: 非法标记}}
/accounts/{id}/permissions/{perm}/revoke:
post:
tags: [permissions]
summary: 撤销二级权限(account:write)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}, {name: perm, in: path, required: true, schema: {type: string}}]
responses: {"200": {description: ok}}
/audit/logs:
get:
tags: [audit]
summary: 操作日志查询(system:read;操作人/账号/模块/动作/IP/时间范围)
parameters:
- {name: page, in: query, schema: {type: integer}}
- {name: page_size, in: query, schema: {type: integer}}
- {name: operator, in: query, schema: {type: string}}
- {name: account_id, in: query, schema: {type: integer}}
- {name: module, in: query, schema: {type: string}}
- {name: action, in: query, schema: {type: string}}
- {name: ip, in: query, schema: {type: string}}
- {name: start, in: query, schema: {type: string, example: "2026-09-01"}}
- {name: end, in: query, schema: {type: string}}
responses: {"200": {description: total+list}, "403": {description: 无 system:read}}
/audit/logins:
get:
tags: [audit]
summary: 登录审计查询(system:read;username/ip/only_failed/时间范围)
parameters:
- {name: page, in: query, schema: {type: integer}}
- {name: username, in: query, schema: {type: string}}
- {name: ip, in: query, schema: {type: string}}
- {name: only_failed, in: query, schema: {type: string, enum: ["0", "1"]}}
responses: {"200": {description: total+list}}
/channels:
post:
tags: [channel]
summary: 创建通道(channel:write;Day 31 扩展协议接入+运营属性 16 字段)
requestBody:
content:
application/json:
schema:
type: object
required: [name, code, protocol, host]
properties:
name: {type: string, maxLength: 64}
code: {type: string, description: 通道号/接入码,全局唯一}
protocol: {type: string, enum: [cmpp, http, sgip, smpp]}
host: {type: string}
port: {type: integer, minimum: 1, maximum: 65535}
username: {type: string}
password: {type: string}
sp_id: {type: string, maxLength: 6, description: 企业代码(CMPP SourceAddr ≤6B/SGIP CorpID)}
protocol_version: {type: integer, description: "cmpp:20(3.0 未实现拒绝) sgip:12 smpp:34;缺省按协议填充"}
heartbeat_interval: {type: integer, description: 心跳周期秒,0 取默认 30}
reconnect_max: {type: integer, description: 重连退避上限秒,0 取默认 30}
service_id: {type: string, description: 服务代码,空用 TEST}
carrier: {type: string, description: "运营商逗号分隔: cmcc,cucc,ctcc"}
billing_length: {type: integer, description: 计费长度字/条,0 取默认 70}
payment_type: {type: string, enum: ["", prepay_monthly, postpaid_monthly, prepay_realtime]}
billing_mode: {type: string, enum: ["", success_unknown, success, all]}
price: {type: number, description: 通道价格元/条}
category: {type: string}
mo_forward_channel_id: {type: integer, description: 上行组合通道,0 不转发}
number_rule: {type: integer, enum: [0, 1, 2, 3]}
code_truncate: {type: integer, description: 通道号截断位数 0~20}
ext_params: {type: string}
service_remark: {type: string}
responses: {"200": {description: 创建成功}, "400": {description: 校验失败(协议/sp_id≤6B/CMPP3.0/白名单)}}
get:
tags: [channel]
summary: 通道列表(name/protocol/status 过滤,分页)
parameters:
- {name: page, in: query, schema: {type: integer}}
- {name: page_size, in: query, schema: {type: integer}}
- {name: name, in: query, schema: {type: string}}
- {name: protocol, in: query, schema: {type: string}}
- {name: status, in: query, schema: {type: integer, enum: [0, 1]}}
responses: {"200": {description: total+list}}
/channels/{id}:
get:
tags: [channel]
summary: 通道详情(含 Day 31 扩展字段)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
responses: {"200": {description: 通道}, "404": {description: 不存在}}
put:
tags: [channel]
summary: 更新通道(channel:write;白名单字段;code/protocol/status 不可改;sp_id≤6B/CMPP3.0 纵深防御)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
requestBody: {content: {application/json: {schema: {type: object}}}}
responses: {"200": {description: 更新成功}, "400": {description: 越权字段/校验失败}, "404": {description: 不存在}}
delete:
tags: [channel]
summary: 删除通道(channel:write;须先停用且不被通道组引用)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
responses: {"200": {description: 删除成功}, "400": {description: 启用中/被组引用}, "404": {description: 不存在}}
/channels/{id}/status:
put:
tags: [channel]
summary: 启停通道(channel:write)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
requestBody: {content: {application/json: {schema: {type: object, required: [status], properties: {status: {type: integer, enum: [0, 1]}}}}}}
responses: {"200": {description: 成功}, "400": {description: 状态非法}}
/channels/{id}/test:
post:
tags: [channel]
summary: 通道测试工具(channel:write;真实发送返回上游 MsgID;CMPP 用 sp_id 映射 SourceAddr)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
requestBody: {content: {application/json: {schema: {type: object, required: [mobile, content], properties: {mobile: {type: string}, content: {type: string}}}}}}
responses: {"200": {description: message_id+protocol+elapsed_ms}, "400": {description: 停用/CMPP3.0}}
/channels/{id}/intercept:
get:
tags: [channel]
summary: 拦截配置查询(夜发/日限/屏蔽地区/黑关键字)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
responses: {"200": {description: intercept}}
put:
tags: [channel]
summary: 拦截配置设置(channel:write;night_limit>0 即 22:00-08:00 禁发)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
responses: {"200": {description: 成功}, "400": {description: 校验失败}}
/channels/{id}/prices:
post:
tags: [channel]
summary: 写入价格时间线(channel:write;Day 38 分时成本价)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
requestBody:
content:
application/json:
schema:
type: object
required: [price]
properties:
price: {type: number, minimum: 0, description: 元/条}
effective_at: {type: string, format: date-time, description: RFC3339;空=立即生效}
responses: {"200": {description: id+price+effective_at}, "400": {description: 价格为负/时间格式}, "404": {description: 通道不存在}}
get:
tags: [channel]
summary: 价格时间线(生效时间升序)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
responses: {"200": {description: total+list}}
/channels/{id}/prices/current:
get:
tags: [channel]
summary: 当前时间点单价(EffectiveAt<=now 最新一条;无时间线回退通道实体 price)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
responses: {"200": {description: channel_id+price}}
/channels/{id}/prices/{pid}:
delete:
tags: [channel]
summary: 删除价格时间线记录(channel:write;须归属该通道)
parameters:
- {name: id, in: path, required: true, schema: {type: integer}}
- {name: pid, in: path, required: true, schema: {type: integer}}
responses: {"200": {description: 删除成功}, "404": {description: 记录不存在}}
/channels/{id}/link-status:
get:
tags: [channel]
summary: 常驻链路状态(未建链返回 running=false;启用中 cmpp 通道展示池连接/健康数)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
responses: {"200": {description: channel_id/running/total/healthy/started_at}, "404": {description: 通道不存在}}
/channels/{id}/receipts:
get:
tags: [channel]
summary: 最近回执/上行(内存环形≤100条倒序;状态报告含 stat,上行含 src/content;重启清空,持久化待 Day 51)
parameters:
- {name: id, in: path, required: true, schema: {type: integer}}
- {name: limit, in: query, required: false, schema: {type: integer, default: 50, maximum: 100}}
responses: {"200": {description: channel_id+total+list}, "404": {description: 通道不存在}}
/send/estimate:
post:
tags: [message]
summary: 发送预估(Day 41;D17 群发工作台实时条数——号码归一去重+长度拆分同源 SmsLength;template_id>0 时服务端取模板渲染)
requestBody: {content: {application/json: {schema: {type: object, required: [mobiles], properties: {task_no: {type: string}, account_id: {type: integer}, send_type: {type: integer, enum: [1, 2, 3, 4], default: 1}, template_id: {type: integer}, mobiles: {type: array, items: {type: string}, maxItems: 10000}, content: {type: string, maxLength: 1000}, variables: {type: object, additionalProperties: {type: string}}, sign: {type: string, maxLength: 32, description: "可选;不传时内容须自带签名(如【公司名】);计费=sign+content 合并口径"}, send_at: {type: string, description: "YYYY-MM-DD HH:mm(定时必填)"}, extend: {type: string}}}}}}
responses: {"200": {description: "Estimate: valid_count/chars/segments/total_fee(=valid_count×segments;Day41 验收:chars/segments 为 签名+正文 合并口径,原样拼接零包装)"}, "400": {description: "号码/内容/变量/签名拒绝路径(ISC:400+中文 msg;长度上限 1000 亦按合并口径)"}, "404": {description: "template_id 不存在"}}
/send/precheck:
post:
tags: [message]
summary: 发送预检(Day 42;D18 个性短信提交前逐号过拦截器链 DryRun——黑名单三级/频次滑窗/签名/退订/地区;频次只读不占配额,拦截不落库;提交主链 Day 46 复用同链非 DryRun 且命中落 send_block_log)
requestBody: {content: {application/json: {schema: {type: object, required: [mobiles], properties: {task_no: {type: string}, account_id: {type: integer}, send_type: {type: integer, enum: [1, 2, 3, 4], default: 1}, template_id: {type: integer}, mobiles: {type: array, items: {type: string}, maxItems: 10000}, content: {type: string, maxLength: 1000}, variables: {type: object, additionalProperties: {type: string}}, sign: {type: string, maxLength: 32}, send_at: {type: string}, extend: {type: string}}}}}}
responses:
"200":
description: "PrecheckResp: total/passed/blocked[]({mobile,interceptor: blacklist|frequency|sign|unsubscribe|region,code,msg})"
content:
application/json:
schema:
type: object
properties:
code: {type: string, example: "ISC:000"}
data:
type: object
properties:
total: {type: integer}
passed: {type: integer}
blocked:
type: array
items:
type: object
properties:
mobile: {type: string}
interceptor: {type: string, enum: [blacklist, frequency, sign, unsubscribe, region]}
code: {type: string, example: "ISC:006"}
msg: {type: string}
"400": {description: "基础校验拒绝(号码/内容/变量/模板未过审;ISC:400)"}
"404": {description: "template_id 不存在"}
/send/submit:
post:
tags: [message]
summary: 发送提交受理(Day 43 修复循环;最小提交链——校验→计费→余额只读校验(ISC:007)→事务落 message_task+message_detail 雪花ID→审核分流;task_no 幂等(重复 ISC:400);限流/冻结扣费/真实下发 Day45/46)
requestBody: {content: {application/json: {schema: {type: object, required: [mobiles], properties: {task_no: {type: string, description: "幂等键;缺省服务端生成 T+时间戳+随机"}, account_id: {type: integer, description: "缺省取 JWT 本人"}, send_type: {type: integer, enum: [1, 2, 3, 4], default: 1}, template_id: {type: integer}, mobiles: {type: array, items: {type: string}, maxItems: 10000}, content: {type: string, maxLength: 1000}, variables: {type: object, additionalProperties: {type: string}}, sign: {type: string, maxLength: 32}, send_at: {type: string, description: "YYYY-MM-DD HH:mm(send_type=3 必填且须未来)"}, extend: {type: string}}}}}}
responses:
"200":
description: "SubmitResp: task_no/task_id/audit_status(0待审/1过/2拒/3免审)/audit_hint/valid_count/segments/total_fee/schedule_at(定时)"
content:
application/json:
schema:
type: object
properties:
code: {type: string, example: "ISC:000"}
data:
type: object
properties:
task_no: {type: string}
task_id: {type: integer}
audit_status: {type: integer, enum: [0, 1, 2, 3]}
audit_hint: {type: string}
valid_count: {type: integer}
segments: {type: integer}
total_fee: {type: integer}
schedule_at: {type: string, description: RFC3339}
"400": {description: "参数/号码/内容/定时时刻过去/任务号重复(ISC:400)"}
"402": {description: "余额不足(ISC:007;口径 Balance<TotalFee 条数,不冻结)"}
"404": {description: "template_id/账号不存在"}
/audits/messages:
get:
tags: [message]
summary: 待审消息列表(Day 43;审核中心——audit_status 过滤 0待/1过/2拒/3免/4超时,默认 0 待审,-1 全部)
parameters:
- {name: page, in: query, required: false, schema: {type: integer, default: 1}}
- {name: page_size, in: query, required: false, schema: {type: integer, default: 20, maximum: 100}}
- {name: account_id, in: query, required: false, schema: {type: integer}}
- {name: audit_status, in: query, required: false, schema: {type: integer, default: 0, enum: [-1, 0, 1, 2, 3, 4]}}
- {name: status, in: query, required: false, schema: {type: integer, default: -1}}
responses: {"200": {description: "total+list(message_task:task_no/content/sign/mobile_count/audit_status/created_at)"}}
/audits/messages/counts:
get:
tags: [message]
summary: 审核态计数(Day 45/D21 审核中心 Tab 徽标;GROUP BY audit_status)
responses: {"200": {description: "total+by_status(map: 审核态→数量,0待/1过/2拒/3免/4超时)"}}
/audits/messages/batch-review:
post:
tags: [message]
summary: 批量审核(Day 45/D21;逐条原子翻转,已审跳过幂等;拒绝原因必填;单批≤100)
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [ids, pass]
properties:
ids: {type: array, items: {type: integer}, maxItems: 100}
pass: {type: boolean}
reason: {type: string, maxLength: 255}
responses: {"200": {description: "ok(成功流转数)+total(提交数)"}}
/audits/messages/{id}/approve:
post:
tags: [message]
summary: 审核通过(audit:write;原子翻转——仅 audit_status=0 可流转,审核人取 JWT 用户名)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
requestBody: {content: {application/json: {schema: {type: object, properties: {reason: {type: string}}}}}}
responses: {"200": {description: "task+record(AuditRecord 留痕)"}, "409": {description: "非待审状态(ISC:037)"}}
/audits/messages/{id}/reject:
post:
tags: [message]
summary: 审核拒绝(audit:write;reason 必填;原子翻转同上)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
requestBody: {content: {application/json: {schema: {type: object, required: [reason], properties: {reason: {type: string}}}}}}
responses: {"200": {description: "task+record"}, "400": {description: "拒绝原因必填(ISC:400)"}, "409": {description: "非待审状态(ISC:037)"}}
/send/tasks:
get:
tags: [message]
summary: 发送任务列表(D19;状态/审核态/类型/账号过滤分页——定时任务列表数据源)
parameters:
- {name: page, in: query, required: false, schema: {type: integer, default: 1}}
- {name: page_size, in: query, required: false, schema: {type: integer, default: 20, maximum: 100}}
- {name: account_id, in: query, required: false, schema: {type: integer}}
- {name: status, in: query, required: false, schema: {type: integer, default: -1, enum: [-1, 0, 1, 2, 3]}}
- {name: audit_status, in: query, required: false, schema: {type: integer, default: -1}}
- {name: send_type, in: query, required: false, schema: {type: integer}}
responses: {"200": {description: "total+list(message_task 全字段;send_type=3 为定时)"}}
/send/tasks/{id}/cancel:
post:
tags: [message]
summary: 取消任务(D19;仅 status=0 待发可取消→3;幂等拒绝)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
responses: {"200": {description: "取消后任务"}, "409": {description: "仅待发任务可取消(ISC:038)"}}
/send/tasks/{id}/reschedule:
put:
tags: [message]
summary: 定时任务改期(D19;仅 send_type=3 且待发;send_at 须未来时刻)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
requestBody: {content: {application/json: {schema: {type: object, required: [send_at], properties: {send_at: {type: string, example: "2026-09-12 10:00"}}}}}}
responses: {"200": {description: "改期后任务(schedule_at 已更新)"}, "400": {description: "时刻格式/过去时刻(ISC:400)"}, "409": {description: "仅定时待发任务可改期(ISC:038)"}}
/templates:
get:
tags: [message]
summary: 模板列表(Day 41;status 过滤 0待审/1通过/-1拒绝,指针语义缺省=全量)
parameters:
- {name: page, in: query, required: false, schema: {type: integer, default: 1}}
- {name: page_size, in: query, required: false, schema: {type: integer, default: 20, maximum: 100}}
- {name: account_id, in: query, required: false, schema: {type: integer}}
- {name: status, in: query, required: false, schema: {type: integer, enum: [-1, 0, 1]}}
- {name: name, in: query, required: false, schema: {type: string}}
responses: {"200": {description: "total+list(id/name/content/variables/status/audit_at/reason)"}}
post:
tags: [message]
summary: 新建模板(message:write;变量≤10,新建即待审,Variables 自动提取)
requestBody: {content: {application/json: {schema: {type: object, required: [account_id, name, content], properties: {account_id: {type: integer}, name: {type: string}, content: {type: string, maxLength: 500}}}}}}
responses: {"200": {description: 创建后的实体(status=0 待审)}, "400": {description: 内容空/超长/变量超限}}
/templates/{id}:
get:
tags: [message]
summary: 模板详情
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
responses: {"200": {description: 实体}, "404": {description: 不存在}}
put:
tags: [message]
summary: 编辑模板(message:write;内容变更自动回待审并清空过审时间)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
requestBody: {content: {application/json: {schema: {type: object, properties: {name: {type: string}, content: {type: string, maxLength: 500}}}}}}
responses: {"200": {description: "{id}"}, "400": {description: 无可更新字段/内容校验失败}}
delete:
tags: [message]
summary: 删除模板(message:write;通过态须先拒审)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
responses: {"200": {description: "{id}"}, "400": {description: 通过态不可删}}
/templates/{id}/review:
put:
tags: [message]
summary: 审核模板(message:write;Day 43 审核服务接入前的模板态审核端点)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
requestBody: {content: {application/json: {schema: {type: object, required: [pass], properties: {pass: {type: boolean}, reason: {type: string}}}}}}
responses: {"200": {description: "{id}"}, "404": {description: 不存在}}
/templates/batch-review:
put:
tags: [message]
summary: 批量审核模板(Day 44/D20;事务内逐条原子翻转 WHERE status=0,已审跳过,返回成功数)
requestBody: {content: {application/json: {schema: {type: object, required: [ids, pass], properties: {ids: {type: array, items: {type: integer}, maxItems: 100}, pass: {type: boolean}, reason: {type: string}}}}}}
responses: {"200": {description: "{ok,total}(ok=成功翻转数,已审条目不计)"}, "400": {description: ids 空/超 100}}
/files/numbers/import:
post:
tags: [message]
summary: 号码文件导入(Day 44;multipart file=TXT/CSV/XLSX≤10MB→解析第一列→归一校验去重→MinIO 落对象,返回计数/预览50/对象键)
requestBody:
content:
multipart/form-data:
schema:
type: object
required: [file]
properties:
file: {type: string, format: binary, description: "号码文件(.txt 每行一号/.csv 第一列/.xlsx 首 sheet 第一列;首行表头自动识别)"}
account_id: {type: integer, description: 缺省取 JWT 账号}
responses:
"200": {description: "{total,valid,duplicated,invalid,header_skipped,preview[],object_key}"}
"400": {description: 格式不支持/空文件/全非法/超 10000 上限}
/channels/monitor:
get:
tags: [channel]
summary: 通道实时监控快照(Day 40 · A-3.13;60s 滑窗 submit_ps/deliver_ps/fail_rate/latency_p50_ms+链路 running/healthy,与 WS 帧同构)
responses: {"200": {description: "ChannelSnapshot[]: channel_id/name/protocol/status/running/total/healthy/submit_ps/deliver_ps/fail_rate/latency_p50_ms/updated_at"}}
/channels/upstreams:
get:
tags: [channel]
summary: 上家(通道方)列表(Day 41 清债③;FE-1 UpstreamList 既有对接)
parameters:
- {name: page, in: query, required: false, schema: {type: integer, default: 1}}
- {name: page_size, in: query, required: false, schema: {type: integer, default: 20, maximum: 100}}
- {name: name, in: query, required: false, schema: {type: string}}
- {name: status, in: query, required: false, schema: {type: integer, enum: [0, 1]}}
responses: {"200": {description: total+list(id/name/contact/phone/category/status/remark)}}
post:
tags: [channel]
summary: 新建上家(channel:write;name 必填唯一)
requestBody: {content: {application/json: {schema: {type: object, required: [name], properties: {name: {type: string}, contact: {type: string}, phone: {type: string}, category: {type: string}, status: {type: integer, enum: [0, 1], default: 1}, remark: {type: string}}}}}}
responses: {"200": {description: 创建后的实体}, "400": {description: name 缺失/重名}}
/channels/upstreams/{id}:
put:
tags: [channel]
summary: 更新上家(channel:write;白名单 name/contact/phone/category/status/remark)
parameters:
- {name: id, in: path, required: true, schema: {type: integer}}
requestBody: {content: {application/json: {schema: {type: object, properties: {name: {type: string}, contact: {type: string}, phone: {type: string}, category: {type: string}, status: {type: integer, enum: [0, 1]}, remark: {type: string}}}}}}
responses: {"200": {description: "{id}"}, "400": {description: 无可更新字段/重名}}
delete:
tags: [channel]
summary: 删除上家(channel:write;被通道引用则拒绝)
parameters:
- {name: id, in: path, required: true, schema: {type: integer}}
responses: {"200": {description: "{id}"}, "400": {description: 被通道引用,须先解除关联}}
/channels/monitor/ws:
get:
tags: [channel]
summary: 通道实时监控 WebSocket(Day 40 · A-3.13;每 2s 推送全通道快照数组,实时通讯曲线刷新;单 Hub 广播,写失败自动摘除)
responses: {"101": {description: "升级成功后每 2s 一帧 ChannelSnapshot[] JSON"}, "400": {description: 非 WebSocket 握手}}
/channels/{id}/logs:
get:
tags: [channel]
summary: 通道日志(Day 40 · A-3.14;连接事件逐条+提交/回执窗口聚合行,kind 过滤;kind=connect|disconnect|stop|submit|submit_fail|deliver|deliver_fail|deliver_mo|alert)
parameters:
- {name: id, in: path, required: true, schema: {type: integer}}
- {name: kind, in: query, required: false, schema: {type: string}}
- {name: page, in: query, required: false, schema: {type: integer, default: 1}}
- {name: page_size, in: query, required: false, schema: {type: integer, default: 20, maximum: 100}}
responses: {"200": {description: channel_id+total+list(kind/level/msg_id/detail/count/fail_count/latency_ms)}, "404": {description: 通道不存在}}
/route-rules:
post:
tags: [channel]
summary: 创建导流规则(channel:write;按账号/内容关键字指定通道,优先于四步路由)
requestBody:
content:
application/json:
schema:
type: object
required: [channel_id, rule_type]
properties:
account_id: {type: integer, description: "账号维度;0=全局(keyword 规则允许)"}
channel_id: {type: integer}
rule_type: {type: string, enum: [keyword, account]}
rule_config: {type: string, description: keyword 类型的匹配字(内容包含)}
priority: {type: integer, description: 大者优先}
responses: {"200": {description: 规则}, "400": {description: 类型/参数/通道校验失败}}
get:
tags: [channel]
summary: 导流规则列表(优先级倒序)
responses: {"200": {description: total+list}}
/route-rules/{id}:
put:
tags: [channel]
summary: 更新导流规则(channel:write;白名单 priority/status/rule_config)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
requestBody: {content: {application/json: {schema: {type: object}}}}
responses: {"200": {description: 成功}, "400": {description: 越权字段}, "404": {description: 不存在}}
delete:
tags: [channel]
summary: 删除导流规则(channel:write;软删)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
responses: {"200": {description: 删除成功}, "404": {description: 不存在}}
/sms/api/sendMessageMass:
post:
tags: [openapi]
summary: 外部群发提交(Day 46;SMS_HTTP_1.6 协议,MD5 验签,无 JWT;双桶限流)
description: |
独立协议域(不走 /api/v1 JWT)。鉴权:sign=MD5(userName+timestamp+MD5(secret)),
timestamp 秒级 ±5min 窗口。中间件链:全局 IP 桶→验签(401)→账号桶(speed_limit)。
响应码表:0 成功/1 用户名空/2 鉴权失败/3 禁用/4 未开通/5 缺参/6 号码空/7 超万/
8 内容空/9 扩展码超长/10 callData 超长/12 定时不合法/16 时间戳失效/99 其他。
security: []
requestBody:
content:
application/json:
schema:
type: object
required: [userName, timestamp, sign, phoneList]
properties:
userName: {type: string}
timestamp: {type: string, description: 秒级 Unix 时间戳}
sign: {type: string, description: MD5(userName+timestamp+MD5(secret))}
phoneList: {type: array, items: {type: string}, maxItems: 10000}
content: {type: string}
templateId: {type: string, description: 模板 ID(content 为空时使用,须已过审)}
signName: {type: string}
sendTime: {type: string, description: "yyyy-MM-dd HH:mm:ss;空=立即;≤15 天"}
extCode: {type: string, maxLength: 32}
callData: {type: string, maxLength: 64, description: 回执推送原样带回}
responses:
"200": {description: "code=0:{code,message,msgId,smsCount,taskNo}"}
"401": {description: "code=1/2/3/4/16 鉴权类失败"}
"429": {description: 限流(全局 IP 桶或账号桶)}
/sms/api/sendMessageOne:
post:
tags: [openapi]
summary: 外部个性提交(Day 46;phoneList/contentList 等长逐号配对,单次≤1000)
security: []
requestBody:
content:
application/json:
schema:
type: object
required: [userName, timestamp, sign, phoneList, contentList]
properties:
userName: {type: string}
timestamp: {type: string}
sign: {type: string}
phoneList: {type: array, items: {type: string}, maxItems: 1000}
contentList: {type: array, items: {type: string}, maxItems: 1000}
signName: {type: string}
sendTime: {type: string}
extCode: {type: string, maxLength: 32}
callData: {type: string, maxLength: 64}
responses:
"200": {description: "code=0:{code,message,msgId,smsCount,taskNo};14=数量不匹配/15=超限"}
"401": {description: 鉴权类失败}
"429": {description: 限流}
/send/tasks/{id}/details:
get:
tags: [send]
summary: 任务明细分页(Day 46/D22 结果反馈页;status/error_code 过滤;含 ext_code/call_data)
parameters:
- {name: id, in: path, required: true, schema: {type: integer}}
- {name: page, in: query, schema: {type: integer, default: 1}}
- {name: page_size, in: query, schema: {type: integer, default: 50, maximum: 200}}
- {name: status, in: query, schema: {type: integer, description: "-1=全部"}}
- {name: error_code, in: query, schema: {type: string}}
responses: {"200": {description: total+list}}
/accounts/{id}/api-config:
get:
tags: [account]
summary: 查看外部 API 配置(Day 46;Day 62 增 CMPP 密码/接入配额/交付块)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
responses:
"200":
description: "report_url/uplink_url/speed_limit/ext_code/secret_issued/secret_fingerprint;Day 62:cmpp_password(库值即密码,CMPP/SMPP/HTTP 客户端直接填它)/cmpp_max_conns(0=系统默认)/cmpp_speed/cmpp_*_effective(生效值)/cmpp_access{port,version,default_max_conns,default_speed}"
"404": {description: 短信线不存在}
put:
tags: [account]
summary: 更新外部 API 配置(Day 46;account:write;reset_secret 重发密钥仅返回一次;Day 62 增 CMPP 配额/自定义密钥)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
requestBody:
content:
application/json:
schema:
type: object
properties:
report_url: {type: string}
uplink_url: {type: string}
speed_limit: {type: integer, description: "条/秒;0=不修改"}
ext_code: {type: string, maxLength: 32}
reset_secret: {type: boolean, description: true=重新生成 32hex 密钥}
custom_secret: {type: string, minLength: 6, maxLength: 64, description: "Day 62:自定义密码(优先于 reset_secret;原样入库零转换,CMPP/SMPP/HTTP 客户端均直接填它)"}
cmpp_max_conns: {type: integer, description: "Day 62:每账号最大 CMPP 连接数(0=不修改;-1=恢复系统默认;1~1024=设置)"}
cmpp_speed: {type: integer, description: "Day 62:单链提交限速 条/s(0=不修改;-1=恢复系统默认;1~100000=设置)"}
responses: {"200": {description: "secret(=库值原文,重发/自定义时返回);cmpp_password(库值即密码)"}}
# ---- S2 结算域(契约草案 2026-11-14;表设计裁决 docs/review/s2-settle-table-review.md;
# 金额口径=元,条数口径=条;R1=出账时刻按日成功条数×生效单价推导,明细 Fee 不金额化) ----
/billing/orders:
get:
tags: [billing]
summary: 充值订单分页(account_id/pay_status 过滤;admin/ops)
parameters:
- {name: page, in: query, schema: {type: integer, default: 1}}
- {name: page_size, in: query, schema: {type: integer, default: 20, maximum: 100}}
- {name: account_id, in: query, schema: {type: integer, format: int64}}
- {name: pay_status, in: query, schema: {type: integer, enum: [0, 1, 2], description: "0待确认 1已到账 2失败"}}
responses: {"200": {description: total+list}}
post:
tags: [billing]
summary: 创建充值订单(pay_status=0 待确认,不动余额;复用 account:recharge 二级权限;count=到账条数,amount=元记账)
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [account_id, count]
properties:
account_id: {type: integer, format: int64}
count: {type: integer, format: int64, description: 到账条数(>0;确认后余额自增此值)}
amount: {type: number, description: 金额(元;记账与账单展示,不参与余额)}
pay_type: {type: string}
remark: {type: string}
responses: {"200": {description: 订单(含 order_no)}, "400": {description: 参数非法}}
/billing/orders/{id}/confirm:
post:
tags: [billing]
summary: 付款审核确认(0→1;事务=状态 CAS+余额原子自增 count+流水 ref_id=order_no;并发/重复确认被 CAS 拒)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
responses: {"200": {description: 新余额}, "409": {description: "状态非 0(ISC:039)"}}
/billing/orders/{id}/reject:
post:
tags: [billing]
summary: 驳回(0→2;不涉余额)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
responses: {"200": {description: ok}, "409": {description: "状态非 0(ISC:039)"}}
/billing/consume:
get:
tags: [billing]
summary: 消耗日汇总查询(账号×业务×天;admin/ops 全量,customer 仅自己;默认近 7 天)
parameters:
- {name: account_id, in: query, schema: {type: integer, format: int64}}
- {name: business, in: query, schema: {type: string}}
- {name: date_from, in: query, schema: {type: string, format: date}}
- {name: date_to, in: query, schema: {type: string, format: date}}
- {name: page, in: query, schema: {type: integer, default: 1}}
- {name: page_size, in: query, schema: {type: integer, default: 20, maximum: 100}}
responses: {"200": {description: "list{account_id,business,stat_date,submit/success/fail/unknown_count,fee_total(单位=条)"}}
/settle/customer:
get:
tags: [settle]
summary: 下家月结单分页(period/account_id/status 过滤;admin/ops 全量,customer 仅自己)
parameters:
- {name: page, in: query, schema: {type: integer, default: 1}}
- {name: page_size, in: query, schema: {type: integer, default: 20, maximum: 100}}
- {name: period, in: query, schema: {type: string, description: 账期 YYYY-MM}}
- {name: account_id, in: query, schema: {type: integer, format: int64}}
- {name: status, in: query, schema: {type: integer, enum: [0, 1, 2], description: "0草稿 1已确认 2已结账"}}
responses: {"200": {description: total+list}}
/settle/customer/generate:
post:
tags: [settle]
summary: 生成/重算下家账期结算单(settle:write;幂等 uk(account,period);status=2 拒重算;金额=Σ日成功条数×生效单价,阶梯档覆写)
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [period]
properties:
period: {type: string, description: 账期 YYYY-MM}
account_id: {type: integer, format: int64, description: 缺省=全账号逐个生成}
responses: {"200": {description: 生成/重算统计}, "409": {description: 含已结账单}}
/settle/customer/{id}:
get:
tags: [settle]
summary: 结算单详情(单头+按天明细,取自 billing_consume_log;customer 仅自己)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
responses: {"200": {description: "单头+days[]"}, "404": {description: 不存在}}
/settle/customer/{id}/confirm:
post:
tags: [settle]
summary: 确认结算单(0草稿→1已确认;人工核对锁账,拒绝静默重算;settle:write)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
responses: {"200": {description: ok}, "409": {description: 状态非 0}}
/settle/customer/{id}/settle:
post:
tags: [settle]
summary: 结账(1→2;写 settle_record(direction=1);终态拒重算;settle:write)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
requestBody:
content:
application/json:
schema:
type: object
properties:
pay_type: {type: string}
remark: {type: string}
responses: {"200": {description: ok}, "409": {description: 状态非 1}}
/settle/customer/{id}/export:
get:
tags: [settle]
summary: 结算单 XLSX 导出(单头+按天明细)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
responses: {"200": {description: application/octet-stream}}
/settle/upstream:
get:
tags: [settle]
summary: 上家月结单分页(period/upstream_id/status 过滤;admin/ops)
parameters:
- {name: page, in: query, schema: {type: integer, default: 1}}
- {name: page_size, in: query, schema: {type: integer, default: 20, maximum: 100}}
- {name: period, in: query, schema: {type: string}}
- {name: upstream_id, in: query, schema: {type: integer, format: int64}}
- {name: status, in: query, schema: {type: integer, enum: [0, 1, 2]}}
responses: {"200": {description: total+list}}
/settle/upstream/generate:
post:
tags: [settle]
summary: 生成/重算上家账期结算单(settle:write;按 channel.upstream_id 归并;计费口径随通道 billing_mode=success/success_unknown/all)
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [period]
properties:
period: {type: string, description: 账期 YYYY-MM}
upstream_id: {type: integer, format: int64, description: 缺省=全上家逐个生成}
responses: {"200": {description: 生成/重算统计}, "409": {description: 含已结账单}}
/settle/upstream/{id}:
get:
tags: [settle]
summary: 上家结算单详情(单头+按通道×天明细,取自 stats_channel_daily)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
responses: {"200": {description: "单头+channels[]days[]"}, "404": {description: 不存在}}
/settle/upstream/{id}/settle:
post:
tags: [settle]
summary: 结账(1→2;写 settle_record(direction=2);settle:write)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
requestBody:
content:
application/json:
schema:
type: object
properties:
pay_type: {type: string}
remark: {type: string}
responses: {"200": {description: ok}, "409": {description: 状态非 1}}
/settle/upstream/{id}/export:
get:
tags: [settle]
summary: 上家结算单 XLSX 导出(单头+通道×天明细)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
responses: {"200": {description: application/octet-stream}}
/settle/ladder:
get:
tags: [settle]
summary: 阶梯价档位列表(owner_type/owner_id 过滤;settle:write 可写,read 全角色)
parameters:
- {name: owner_type, in: query, schema: {type: string, enum: [account, upstream]}}
- {name: owner_id, in: query, schema: {type: integer, format: int64}}
responses: {"200": {description: 档位列表(按 tier_from 升序)}}
post:
tags: [settle]
summary: 新增档位(owner×tier_from 唯一;0=首档下限;settle:write)
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [owner_type, owner_id, tier_from, price]
properties:
owner_type: {type: string, enum: [account, upstream]}
owner_id: {type: integer, format: int64}
tier_from: {type: integer, format: int64, description: 档位下限(含,条/月)}
price: {type: number, description: 该档单价(元/条)}
responses: {"200": {description: ok}, "400": {description: 档位重叠/参数非法}}
/settle/ladder/{id}:
put:
tags: [settle]
summary: 修改档位(price/tier_from;settle:write)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
requestBody:
content:
application/json:
schema: {type: object, properties: {tier_from: {type: integer, format: int64}, price: {type: number}}}
responses: {"200": {description: ok}}
delete:
tags: [settle]
summary: 删除档位(settle:write)
parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
responses: {"200": {description: ok}}
/stats/biz:
get:
tags: [stats]
summary: 业务类型分布(Issue#6 Dashboard donut;近 N 自然日,1~30 缺省 7)
parameters:
- {name: days, in: query, schema: {type: integer, default: 7, minimum: 1, maximum: 30}}
responses:
"200": {description: '{days,by_business:[{key:sms|video,count}],by_send_type:[{key:batch|personal|timer|file|other,count}]}'}
/stats/realtime:
get:
tags: [stats]
summary: 实时提交速率(Issue#6 Dashboard KPI;60s 窗口均值,覆盖索引 COUNT)
responses:
"200": {description: '{ts,window_s:60,global_submit_ps,top_accounts:[{account_id,name,submit_ps}]Top5(客户口径仅自己)}'}
/ops/system/overview:
get:
tags: [ops]
summary: 系统健康总览(Issue#6 Dashboard 系统健康卡;admin/ops,gateway 视角五子系统)
responses:
"200": {description: '{uptime_s,subsystems:[{name:gateway|consumer|mysql|redis|kafka,status:up|degraded|down|unknown,detail,latency_ms}]}'}
/stats/profit/users:
get:
tags: [settle]
summary: 用户利润分析(平台角色)——revenue=Σ日成功×用户时间线价(阶梯不进分析);cost=通道成本按成功条数占比分摊;rebate=直线下级结算额×其 rebate_rate(R4 单级,历史不重算);profit=revenue-cost+rebate;parent_id=子树过滤(Path)
parameters:
- {name: date_from, in: query, schema: {type: string, format: date}}
- {name: date_to, in: query, schema: {type: string, format: date}}
- {name: parent_id, in: query, schema: {type: integer, format: int64, description: 以该账号为根的子树(缺省=全平台)}}
- {name: page, in: query, schema: {type: integer, default: 1}}
- {name: page_size, in: query, schema: {type: integer, default: 20, maximum: 100}}
responses: {"200": {description: "{list[...],total,summary{total_revenue,total_cost,total_rebate,platform_profit}}(元)"}}
/stats/profit/channels:
get:
tags: [settle]
summary: 通道利润分析(平台角色)——cost=Σ日成功×通道时间线价;revenue=全平台用户收入×通道成功占比分摊(无账号×通道交叉粒度事实源);profit=revenue-cost;date_from/date_to/channel_id
parameters:
- {name: date_from, in: query, schema: {type: string, format: date}}
- {name: date_to, in: query, schema: {type: string, format: date}}
- {name: channel_id, in: query, schema: {type: integer, format: int64}}
- {name: page, in: query, schema: {type: integer, default: 1}}
- {name: page_size, in: query, schema: {type: integer, default: 20, maximum: 100}}
responses: {"200": {description: "list{channel_id,name,upstream_id,success_count,revenue,cost,profit}(元)"}}
/ops/settle/aggregate:
post:
tags: [settle]
summary: 手动触发消耗日汇总回补(date 缺省=昨日;幂等 UPSERT;运维口径,admin)
requestBody:
content:
application/json:
schema: {type: object, properties: {date: {type: string, format: date, description: 可回补历史日期(明细热窗内)}}}
responses: {"200": {description: "落账行数(账号/通道两表)"}}
/ops/callback:
get:
tags: [callback]
summary: 回调推送任务列表(S4·C1;死信可查;status 0待推送/1已送达/2死信,ops)
parameters:
- {name: status, in: query, schema: {type: integer, enum: [0, 1, 2]}, description: 缺省=全部}
- {name: type, in: query, schema: {type: integer, enum: [1, 2]}, description: "1回执终态 2上行消息;缺省=全部"}
- {name: account_id, in: query, schema: {type: integer}}
- {name: page, in: query, schema: {type: integer, default: 1}}
- {name: page_size, in: query, schema: {type: integer, default: 20}}
responses:
"200":
description: "{total,list[],status_counts{pending,sent,dead}}"
/ops/callback/{id}/resend:
post:
tags: [callback]
summary: 死信重派(status 2→0/attempt 清零/立即投递;仅死信可派,幂等拒绝非死信,ops)
parameters:
- {name: id, in: path, required: true, schema: {type: integer}}
responses:
"200": {description: "{id,resent:true}"}
"404": {description: "任务不存在或非死信状态(ISC:404)"}
components:
securitySchemes:
bearerAuth: {type: http, scheme: bearer, bearerFormat: JWT}
schemas:
CreateAccount:
type: object
required: [username, password, role, business]
properties:
username: {type: string, minLength: 3, maxLength: 64}
password: {type: string, minLength: 6, maxLength: 64}
real_name: {type: string}
role: {type: string, enum: [admin, ops, service, group, customer]}
parent_id: {type: integer}
business: {type: integer, description: "业务位掩码:1 短信/2 国际/4 视频/8 CSP/16 空号/32 短链"}
credit_balance: {type: integer}
svc_team: {type: string}
remark: {type: string}
# x-isc-dict:ISC 错误码→中文 契约字典(Day 41 清债② codegen 源)。
# 与后端 internal/pkg/errors/codes.go 由 openapi_sync_test 双向锁定,改动任一侧须跑 go run ./tools/gen-dict 再生成。
x-isc-dict:
ISC:000: 成功
ISC:001: 网关错误
ISC:002: 账号被禁用
ISC:003: 签名被禁用
ISC:004: 签名非法
ISC:005: 通道非法
ISC:006: 黑名单
ISC:007: 欠费
ISC:009: 短信网关内部错误
ISC:010: 发送回执超时
ISC:011: 用户不在线
ISC:012: 用户停机
ISC:013: 没有路由,携号转网
ISC:014: 用户不在服务区
ISC:015: 端口下线
ISC:016: 等待5G消息终端响应超时
ISC:017: 消息编码非法
ISC:018: 用户未开通5G消息
ISC:019: 彩信下发成功,下载超时
ISC:020: 终端存储空间满
ISC:021: 回落彩信延迟获取
ISC:022: 不支持彩信
ISC:023: 码号局数据错误
ISC:024: 短信已下发,但是终端故障
ISC:025: 找不到归属运营商,可能是新号段
ISC:026: 无法识别彩信回执
ISC:027: 空号
ISC:029: 无通道路由
ISC:030: 通道拒绝
ISC:031: 内容不合规拦截
ISC:032: 发送限制
ISC:033: 超出账号设置的最大文本长度
ISC:034: 超出账号每天发送量限制
ISC:035: 超出账号授信额限制
ISC:036: 地区屏蔽
ISC:037: 审核状态冲突(非待审)
ISC:038: 任务状态冲突(不可取消/改期)
ISC:039: 订单状态冲突(非待确认)
ISC:040: 夜间频控
ISC:043: 5G消息拦截
ISC:400: 参数错误
ISC:401: 未认证
ISC:402: Token 已过期
ISC:403: 无权限
ISC:404: 资源不存在
ISC:405: 方法不允许
ISC:429: 请求过于频繁
ISC:500: 其他错误,需要人工核查
ISC:501: 数据库错误
ISC:502: 缓存错误
ISC:503: 消息队列错误
ISC:504: 服务暂不可用