feat: add operator and business reference fields to tenant ledgers
- Added `operator_user_id`, `biz_ref_type`, and `biz_ref_id` fields to the TenantLedger model for enhanced auditing and traceability. - Updated the tenant ledgers query generation to include new fields. - Introduced new API endpoint for retrieving tenant ledger records with filtering options based on the new fields. - Enhanced Swagger documentation to reflect the new endpoint and its parameters. - Created DTOs for admin ledger filtering and item representation. - Implemented the admin ledger retrieval logic in the tenant service. - Added database migration scripts to introduce new fields and indexes for efficient querying.
This commit is contained in:
@@ -939,6 +939,125 @@ const docTemplate = `{
|
||||
}
|
||||
}
|
||||
},
|
||||
"/t/{tenantCode}/v1/admin/ledgers": {
|
||||
"get": {
|
||||
"consumes": [
|
||||
"application/json"
|
||||
],
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"Tenant"
|
||||
],
|
||||
"summary": "余额流水列表（租户管理/审计）",
|
||||
"parameters": [
|
||||
{
|
||||
"type": "string",
|
||||
"description": "Tenant Code",
|
||||
"name": "tenantCode",
|
||||
"in": "path",
|
||||
"required": true
|
||||
},
|
||||
{
|
||||
"type": "integer",
|
||||
"description": "BizRefID 按业务引用ID过滤（可选）。",
|
||||
"name": "biz_ref_id",
|
||||
"in": "query"
|
||||
},
|
||||
{
|
||||
"type": "string",
|
||||
"description": "BizRefType 按业务引用类型过滤（可选）。\n约定：当前业务写入为 \"order\"；未来可扩展为 refund/topup 等。",
|
||||
"name": "biz_ref_type",
|
||||
"in": "query"
|
||||
},
|
||||
{
|
||||
"type": "string",
|
||||
"description": "CreatedAtFrom 创建时间起（可选）。",
|
||||
"name": "created_at_from",
|
||||
"in": "query"
|
||||
},
|
||||
{
|
||||
"type": "string",
|
||||
"description": "CreatedAtTo 创建时间止（可选）。",
|
||||
"name": "created_at_to",
|
||||
"in": "query"
|
||||
},
|
||||
{
|
||||
"type": "integer",
|
||||
"description": "Limit is page size; only values in {10,20,50,100} are accepted (otherwise defaults to 10).",
|
||||
"name": "limit",
|
||||
"in": "query"
|
||||
},
|
||||
{
|
||||
"type": "integer",
|
||||
"description": "OperatorUserID 按操作者用户ID过滤（可选）。\n典型场景：后台检索“某个管理员发起的充值/退款”等敏感操作流水。",
|
||||
"name": "operator_user_id",
|
||||
"in": "query"
|
||||
},
|
||||
{
|
||||
"type": "integer",
|
||||
"description": "OrderID 按关联订单过滤（可选）。",
|
||||
"name": "order_id",
|
||||
"in": "query"
|
||||
},
|
||||
{
|
||||
"type": "integer",
|
||||
"description": "Page is 1-based page index; values \u003c= 0 are normalized to 1.",
|
||||
"name": "page",
|
||||
"in": "query"
|
||||
},
|
||||
{
|
||||
"enum": [
|
||||
"credit_topup",
|
||||
"debit_purchase",
|
||||
"credit_refund",
|
||||
"freeze",
|
||||
"unfreeze",
|
||||
"adjustment"
|
||||
],
|
||||
"type": "string",
|
||||
"x-enum-varnames": [
|
||||
"TenantLedgerTypeCreditTopup",
|
||||
"TenantLedgerTypeDebitPurchase",
|
||||
"TenantLedgerTypeCreditRefund",
|
||||
"TenantLedgerTypeFreeze",
|
||||
"TenantLedgerTypeUnfreeze",
|
||||
"TenantLedgerTypeAdjustment"
|
||||
],
|
||||
"description": "Type 按流水类型过滤（可选）。",
|
||||
"name": "type",
|
||||
"in": "query"
|
||||
},
|
||||
{
|
||||
"type": "integer",
|
||||
"description": "UserID 按余额账户归属用户ID过滤（可选）。\n典型场景：查看某个租户成员的资金变化全链路。",
|
||||
"name": "user_id",
|
||||
"in": "query"
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "OK",
|
||||
"schema": {
|
||||
"allOf": [
|
||||
{
|
||||
"$ref": "#/definitions/requests.Pager"
|
||||
},
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"items": {
|
||||
"$ref": "#/definitions/dto.AdminLedgerItem"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/t/{tenantCode}/v1/admin/media_assets": {
|
||||
"get": {
|
||||
"consumes": [
|
||||
@@ -3021,6 +3140,23 @@ const docTemplate = `{
|
||||
}
|
||||
}
|
||||
},
|
||||
"dto.AdminLedgerItem": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"ledger": {
|
||||
"description": "Ledger 流水记录（租户内隔离）。",
|
||||
"allOf": [
|
||||
{
|
||||
"$ref": "#/definitions/models.TenantLedger"
|
||||
}
|
||||
]
|
||||
},
|
||||
"type_description": {
|
||||
"description": "TypeDescription 流水类型中文说明（用于前端展示）。",
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"dto.AdminMediaAssetUploadCompleteForm": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
@@ -4181,10 +4317,11 @@ const docTemplate = `{
|
||||
},
|
||||
"snapshot": {
|
||||
"description": "订单快照：JSON；建议包含 content 标题/定价/折扣、请求来源等，避免改价影响历史展示",
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "integer"
|
||||
}
|
||||
"allOf": [
|
||||
{
|
||||
"$ref": "#/definitions/types.JSONType-fields_OrdersSnapshot"
|
||||
}
|
||||
]
|
||||
},
|
||||
"status": {
|
||||
"description": "订单状态：created/paid/refunding/refunded/canceled/failed；状态变更需与账本/权益保持一致",
|
||||
@@ -4251,10 +4388,11 @@ const docTemplate = `{
|
||||
},
|
||||
"snapshot": {
|
||||
"description": "内容快照：JSON；建议包含 title/price/discount 等，用于历史展示与审计",
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "integer"
|
||||
}
|
||||
"allOf": [
|
||||
{
|
||||
"$ref": "#/definitions/types.JSONType-fields_OrderItemsSnapshot"
|
||||
}
|
||||
]
|
||||
},
|
||||
"tenant_id": {
|
||||
"description": "租户ID：多租户隔离关键字段；必须与 orders.tenant_id 一致",
|
||||
@@ -4439,6 +4577,14 @@ const docTemplate = `{
|
||||
"description": "变更前可用余额：用于审计与对账回放",
|
||||
"type": "integer"
|
||||
},
|
||||
"biz_ref_id": {
|
||||
"description": "业务引用ID：与 biz_ref_type 配合使用（例如 orders.id）；用于对账与审计",
|
||||
"type": "integer"
|
||||
},
|
||||
"biz_ref_type": {
|
||||
"description": "业务引用类型：order/refund/topup/etc；与 biz_ref_id 组成可选的结构化幂等/追溯键",
|
||||
"type": "string"
|
||||
},
|
||||
"created_at": {
|
||||
"description": "创建时间：默认 now()",
|
||||
"type": "string"
|
||||
@@ -4459,6 +4605,10 @@ const docTemplate = `{
|
||||
"description": "幂等键：同一租户同一用户同一业务操作固定；用于防止重复落账（建议由业务层生成）",
|
||||
"type": "string"
|
||||
},
|
||||
"operator_user_id": {
|
||||
"description": "操作者用户ID：谁触发该流水（admin/buyer/system）；用于审计与追责；可为空（历史数据或无法识别时）",
|
||||
"type": "integer"
|
||||
},
|
||||
"order": {
|
||||
"$ref": "#/definitions/models.Order"
|
||||
},
|
||||
@@ -4609,6 +4759,12 @@ const docTemplate = `{
|
||||
"type": "integer"
|
||||
}
|
||||
}
|
||||
},
|
||||
"types.JSONType-fields_OrderItemsSnapshot": {
|
||||
"type": "object"
|
||||
},
|
||||
"types.JSONType-fields_OrdersSnapshot": {
|
||||
"type": "object"
|
||||
}
|
||||
},
|
||||
"securityDefinitions": {
|
||||
|
||||
@@ -933,6 +933,125 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"/t/{tenantCode}/v1/admin/ledgers": {
|
||||
"get": {
|
||||
"consumes": [
|
||||
"application/json"
|
||||
],
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"Tenant"
|
||||
],
|
||||
"summary": "余额流水列表（租户管理/审计）",
|
||||
"parameters": [
|
||||
{
|
||||
"type": "string",
|
||||
"description": "Tenant Code",
|
||||
"name": "tenantCode",
|
||||
"in": "path",
|
||||
"required": true
|
||||
},
|
||||
{
|
||||
"type": "integer",
|
||||
"description": "BizRefID 按业务引用ID过滤（可选）。",
|
||||
"name": "biz_ref_id",
|
||||
"in": "query"
|
||||
},
|
||||
{
|
||||
"type": "string",
|
||||
"description": "BizRefType 按业务引用类型过滤（可选）。\n约定：当前业务写入为 \"order\"；未来可扩展为 refund/topup 等。",
|
||||
"name": "biz_ref_type",
|
||||
"in": "query"
|
||||
},
|
||||
{
|
||||
"type": "string",
|
||||
"description": "CreatedAtFrom 创建时间起（可选）。",
|
||||
"name": "created_at_from",
|
||||
"in": "query"
|
||||
},
|
||||
{
|
||||
"type": "string",
|
||||
"description": "CreatedAtTo 创建时间止（可选）。",
|
||||
"name": "created_at_to",
|
||||
"in": "query"
|
||||
},
|
||||
{
|
||||
"type": "integer",
|
||||
"description": "Limit is page size; only values in {10,20,50,100} are accepted (otherwise defaults to 10).",
|
||||
"name": "limit",
|
||||
"in": "query"
|
||||
},
|
||||
{
|
||||
"type": "integer",
|
||||
"description": "OperatorUserID 按操作者用户ID过滤（可选）。\n典型场景：后台检索“某个管理员发起的充值/退款”等敏感操作流水。",
|
||||
"name": "operator_user_id",
|
||||
"in": "query"
|
||||
},
|
||||
{
|
||||
"type": "integer",
|
||||
"description": "OrderID 按关联订单过滤（可选）。",
|
||||
"name": "order_id",
|
||||
"in": "query"
|
||||
},
|
||||
{
|
||||
"type": "integer",
|
||||
"description": "Page is 1-based page index; values \u003c= 0 are normalized to 1.",
|
||||
"name": "page",
|
||||
"in": "query"
|
||||
},
|
||||
{
|
||||
"enum": [
|
||||
"credit_topup",
|
||||
"debit_purchase",
|
||||
"credit_refund",
|
||||
"freeze",
|
||||
"unfreeze",
|
||||
"adjustment"
|
||||
],
|
||||
"type": "string",
|
||||
"x-enum-varnames": [
|
||||
"TenantLedgerTypeCreditTopup",
|
||||
"TenantLedgerTypeDebitPurchase",
|
||||
"TenantLedgerTypeCreditRefund",
|
||||
"TenantLedgerTypeFreeze",
|
||||
"TenantLedgerTypeUnfreeze",
|
||||
"TenantLedgerTypeAdjustment"
|
||||
],
|
||||
"description": "Type 按流水类型过滤（可选）。",
|
||||
"name": "type",
|
||||
"in": "query"
|
||||
},
|
||||
{
|
||||
"type": "integer",
|
||||
"description": "UserID 按余额账户归属用户ID过滤（可选）。\n典型场景：查看某个租户成员的资金变化全链路。",
|
||||
"name": "user_id",
|
||||
"in": "query"
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "OK",
|
||||
"schema": {
|
||||
"allOf": [
|
||||
{
|
||||
"$ref": "#/definitions/requests.Pager"
|
||||
},
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"items": {
|
||||
"$ref": "#/definitions/dto.AdminLedgerItem"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/t/{tenantCode}/v1/admin/media_assets": {
|
||||
"get": {
|
||||
"consumes": [
|
||||
@@ -3015,6 +3134,23 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"dto.AdminLedgerItem": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"ledger": {
|
||||
"description": "Ledger 流水记录（租户内隔离）。",
|
||||
"allOf": [
|
||||
{
|
||||
"$ref": "#/definitions/models.TenantLedger"
|
||||
}
|
||||
]
|
||||
},
|
||||
"type_description": {
|
||||
"description": "TypeDescription 流水类型中文说明（用于前端展示）。",
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"dto.AdminMediaAssetUploadCompleteForm": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
@@ -4175,10 +4311,11 @@
|
||||
},
|
||||
"snapshot": {
|
||||
"description": "订单快照：JSON；建议包含 content 标题/定价/折扣、请求来源等，避免改价影响历史展示",
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "integer"
|
||||
}
|
||||
"allOf": [
|
||||
{
|
||||
"$ref": "#/definitions/types.JSONType-fields_OrdersSnapshot"
|
||||
}
|
||||
]
|
||||
},
|
||||
"status": {
|
||||
"description": "订单状态：created/paid/refunding/refunded/canceled/failed；状态变更需与账本/权益保持一致",
|
||||
@@ -4245,10 +4382,11 @@
|
||||
},
|
||||
"snapshot": {
|
||||
"description": "内容快照：JSON；建议包含 title/price/discount 等，用于历史展示与审计",
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "integer"
|
||||
}
|
||||
"allOf": [
|
||||
{
|
||||
"$ref": "#/definitions/types.JSONType-fields_OrderItemsSnapshot"
|
||||
}
|
||||
]
|
||||
},
|
||||
"tenant_id": {
|
||||
"description": "租户ID：多租户隔离关键字段；必须与 orders.tenant_id 一致",
|
||||
@@ -4433,6 +4571,14 @@
|
||||
"description": "变更前可用余额：用于审计与对账回放",
|
||||
"type": "integer"
|
||||
},
|
||||
"biz_ref_id": {
|
||||
"description": "业务引用ID：与 biz_ref_type 配合使用（例如 orders.id）；用于对账与审计",
|
||||
"type": "integer"
|
||||
},
|
||||
"biz_ref_type": {
|
||||
"description": "业务引用类型：order/refund/topup/etc；与 biz_ref_id 组成可选的结构化幂等/追溯键",
|
||||
"type": "string"
|
||||
},
|
||||
"created_at": {
|
||||
"description": "创建时间：默认 now()",
|
||||
"type": "string"
|
||||
@@ -4453,6 +4599,10 @@
|
||||
"description": "幂等键：同一租户同一用户同一业务操作固定；用于防止重复落账（建议由业务层生成）",
|
||||
"type": "string"
|
||||
},
|
||||
"operator_user_id": {
|
||||
"description": "操作者用户ID：谁触发该流水（admin/buyer/system）；用于审计与追责；可为空（历史数据或无法识别时）",
|
||||
"type": "integer"
|
||||
},
|
||||
"order": {
|
||||
"$ref": "#/definitions/models.Order"
|
||||
},
|
||||
@@ -4603,6 +4753,12 @@
|
||||
"type": "integer"
|
||||
}
|
||||
}
|
||||
},
|
||||
"types.JSONType-fields_OrderItemsSnapshot": {
|
||||
"type": "object"
|
||||
},
|
||||
"types.JSONType-fields_OrdersSnapshot": {
|
||||
"type": "object"
|
||||
}
|
||||
},
|
||||
"securityDefinitions": {
|
||||
|
||||
@@ -257,6 +257,16 @@ definitions:
|
||||
description: UserID 目标用户ID。
|
||||
type: integer
|
||||
type: object
|
||||
dto.AdminLedgerItem:
|
||||
properties:
|
||||
ledger:
|
||||
allOf:
|
||||
- $ref: '#/definitions/models.TenantLedger'
|
||||
description: Ledger 流水记录（租户内隔离）。
|
||||
type_description:
|
||||
description: TypeDescription 流水类型中文说明（用于前端展示）。
|
||||
type: string
|
||||
type: object
|
||||
dto.AdminMediaAssetUploadCompleteForm:
|
||||
properties:
|
||||
content_type:
|
||||
@@ -1054,10 +1064,9 @@ definitions:
|
||||
description: 退款完成时间：退款落账成功后写入
|
||||
type: string
|
||||
snapshot:
|
||||
allOf:
|
||||
- $ref: '#/definitions/types.JSONType-fields_OrdersSnapshot'
|
||||
description: 订单快照：JSON；建议包含 content 标题/定价/折扣、请求来源等，避免改价影响历史展示
|
||||
items:
|
||||
type: integer
|
||||
type: array
|
||||
status:
|
||||
allOf:
|
||||
- $ref: '#/definitions/consts.OrderStatus'
|
||||
@@ -1101,10 +1110,9 @@ definitions:
|
||||
description: 订单ID：关联 orders.id；用于聚合订单明细
|
||||
type: integer
|
||||
snapshot:
|
||||
allOf:
|
||||
- $ref: '#/definitions/types.JSONType-fields_OrderItemsSnapshot'
|
||||
description: 内容快照：JSON；建议包含 title/price/discount 等，用于历史展示与审计
|
||||
items:
|
||||
type: integer
|
||||
type: array
|
||||
tenant_id:
|
||||
description: 租户ID：多租户隔离关键字段；必须与 orders.tenant_id 一致
|
||||
type: integer
|
||||
@@ -1232,6 +1240,12 @@ definitions:
|
||||
balance_before:
|
||||
description: 变更前可用余额：用于审计与对账回放
|
||||
type: integer
|
||||
biz_ref_id:
|
||||
description: 业务引用ID：与 biz_ref_type 配合使用（例如 orders.id）；用于对账与审计
|
||||
type: integer
|
||||
biz_ref_type:
|
||||
description: 业务引用类型：order/refund/topup/etc；与 biz_ref_id 组成可选的结构化幂等/追溯键
|
||||
type: string
|
||||
created_at:
|
||||
description: 创建时间：默认 now()
|
||||
type: string
|
||||
@@ -1247,6 +1261,9 @@ definitions:
|
||||
idempotency_key:
|
||||
description: 幂等键：同一租户同一用户同一业务操作固定；用于防止重复落账（建议由业务层生成）
|
||||
type: string
|
||||
operator_user_id:
|
||||
description: 操作者用户ID：谁触发该流水（admin/buyer/system）；用于审计与追责；可为空（历史数据或无法识别时）
|
||||
type: integer
|
||||
order:
|
||||
$ref: '#/definitions/models.Order'
|
||||
order_id:
|
||||
@@ -1350,6 +1367,10 @@ definitions:
|
||||
paging).
|
||||
type: integer
|
||||
type: object
|
||||
types.JSONType-fields_OrderItemsSnapshot:
|
||||
type: object
|
||||
types.JSONType-fields_OrdersSnapshot:
|
||||
type: object
|
||||
externalDocs:
|
||||
description: OpenAPI
|
||||
url: https://swagger.io/resources/open-api/
|
||||
@@ -1967,6 +1988,92 @@ paths:
|
||||
summary: 拒绝加入申请（租户管理）
|
||||
tags:
|
||||
- Tenant
|
||||
/t/{tenantCode}/v1/admin/ledgers:
|
||||
get:
|
||||
consumes:
|
||||
- application/json
|
||||
parameters:
|
||||
- description: Tenant Code
|
||||
in: path
|
||||
name: tenantCode
|
||||
required: true
|
||||
type: string
|
||||
- description: BizRefID 按业务引用ID过滤（可选）。
|
||||
in: query
|
||||
name: biz_ref_id
|
||||
type: integer
|
||||
- description: |-
|
||||
BizRefType 按业务引用类型过滤（可选）。
|
||||
约定：当前业务写入为 "order"；未来可扩展为 refund/topup 等。
|
||||
in: query
|
||||
name: biz_ref_type
|
||||
type: string
|
||||
- description: CreatedAtFrom 创建时间起（可选）。
|
||||
in: query
|
||||
name: created_at_from
|
||||
type: string
|
||||
- description: CreatedAtTo 创建时间止（可选）。
|
||||
in: query
|
||||
name: created_at_to
|
||||
type: string
|
||||
- description: Limit is page size; only values in {10,20,50,100} are accepted
|
||||
(otherwise defaults to 10).
|
||||
in: query
|
||||
name: limit
|
||||
type: integer
|
||||
- description: |-
|
||||
OperatorUserID 按操作者用户ID过滤（可选）。
|
||||
典型场景：后台检索“某个管理员发起的充值/退款”等敏感操作流水。
|
||||
in: query
|
||||
name: operator_user_id
|
||||
type: integer
|
||||
- description: OrderID 按关联订单过滤（可选）。
|
||||
in: query
|
||||
name: order_id
|
||||
type: integer
|
||||
- description: Page is 1-based page index; values <= 0 are normalized to 1.
|
||||
in: query
|
||||
name: page
|
||||
type: integer
|
||||
- description: Type 按流水类型过滤（可选）。
|
||||
enum:
|
||||
- credit_topup
|
||||
- debit_purchase
|
||||
- credit_refund
|
||||
- freeze
|
||||
- unfreeze
|
||||
- adjustment
|
||||
in: query
|
||||
name: type
|
||||
type: string
|
||||
x-enum-varnames:
|
||||
- TenantLedgerTypeCreditTopup
|
||||
- TenantLedgerTypeDebitPurchase
|
||||
- TenantLedgerTypeCreditRefund
|
||||
- TenantLedgerTypeFreeze
|
||||
- TenantLedgerTypeUnfreeze
|
||||
- TenantLedgerTypeAdjustment
|
||||
- description: |-
|
||||
UserID 按余额账户归属用户ID过滤（可选）。
|
||||
典型场景：查看某个租户成员的资金变化全链路。
|
||||
in: query
|
||||
name: user_id
|
||||
type: integer
|
||||
produces:
|
||||
- application/json
|
||||
responses:
|
||||
"200":
|
||||
description: OK
|
||||
schema:
|
||||
allOf:
|
||||
- $ref: '#/definitions/requests.Pager'
|
||||
- properties:
|
||||
items:
|
||||
$ref: '#/definitions/dto.AdminLedgerItem'
|
||||
type: object
|
||||
summary: 余额流水列表（租户管理/审计）
|
||||
tags:
|
||||
- Tenant
|
||||
/t/{tenantCode}/v1/admin/media_assets:
|
||||
get:
|
||||
consumes:
|
||||
|
||||
Reference in New Issue
Block a user