1062 lines
59 KiB
YAML
1062 lines
59 KiB
YAML
openapi: 3.0.3
|
||
info:
|
||
title: go-sms API v1(阶段 2:账号与权限)
|
||
version: 1.3.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/profit/users:
|
||
get:
|
||
tags: [settle]
|
||
summary: 用户利润分析(含下级树聚合:revenue=Σ结算额,cost=其流量通道成本分摊,rebate=返点支出;历史归属不随换上级重算)
|
||
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{account_id,revenue,cost,rebate,profit}(元)"}}
|
||
/stats/profit/channels:
|
||
get:
|
||
tags: [settle]
|
||
summary: 通道利润分析(收入=Σ日成功条数×用户价,成本=Σ×通道价;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,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: "落账行数(账号/通道两表)"}}
|
||
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: 服务暂不可用
|