S2-D1 结算域表设计评审+迁移 v20+契约草案: 六项裁决定稿(docs/review/s2-settle-table-review.md)——R1 出账时刻计价(用户拍板:明细 Fee 保持片数/send 域零改动,金额=Σ日成功条数×生效单价,时间线+阶梯 D4 price.go 单点推导)/R2 消耗事实源统一 billing_consume_log+stats_channel_daily,stats_user_daily 废弃/R3 充值双通道(即时+BillingOrder 审核)/R4 rebate_rate 单级返点历史不重算/R5 settle_ladder 阶梯表/R6 条/元口径单点换算;v20_settle_domain(billing_consume_log +unknown_count/updated_at,account_user +rebate_rate,DROP stats_user_daily,settle_ladder 建表,casbin 补 ops settle:write/customer settle:read;显式 ALTER+HasColumn 守卫/空库 HasTable 守卫三路径收敛,零新增索引复用 v16);实体同步 All() 39 个;openapi v1.3.0 +20 结算端点(js-yaml 84 paths 过);迁移测试末七窗口 v14..v20 两遍幂等+五项 v20 断言;门禁全绿:vet 0/-race 38 包零 FAIL/lint 0/集成 AutoMigrate 39 表+Casbin PASS;dev 库实跑 v19→v20+information_schema 五项核验过;验收单 s2-d1.md+CHANGELOG+memory-bank 回填
This commit is contained in:
+236
-1
@@ -1,7 +1,7 @@
|
||||
openapi: 3.0.3
|
||||
info:
|
||||
title: go-sms API v1(阶段 2:账号与权限)
|
||||
version: 1.2.0
|
||||
version: 1.3.0
|
||||
description: |
|
||||
阶段 2(Day 21-30)交付的账号与权限域全部端点。
|
||||
统一响应 {code,msg,data}:code=ISC:000 成功;错误码三位制(ISC:4xx/5xx)。
|
||||
@@ -19,6 +19,8 @@ tags:
|
||||
- {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:
|
||||
@@ -751,6 +753,239 @@ paths:
|
||||
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(已确认/已驳回)}}
|
||||
/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}}
|
||||
/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}
|
||||
|
||||
Reference in New Issue
Block a user