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": {
|
||||
|
||||
Reference in New Issue
Block a user