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:
2026-11-14 09:56:54 +08:00
parent 24f7b3dd02
commit 5159e3c634
12 changed files with 481 additions and 46 deletions
+236 -1
View File
@@ -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}