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;口径 Balance0;确认后余额自增此值)} 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: 服务暂不可用