diff --git a/docs/admin-openapi.yaml b/docs/admin-openapi.yaml index 24d07b7..16c3889 100644 --- a/docs/admin-openapi.yaml +++ b/docs/admin-openapi.yaml @@ -520,8 +520,9 @@ components: DtoAssetPackageResponse: properties: activated_at: - description: 激活时间 + description: 激活时间（待生效套餐为空） format: date-time + nullable: true type: string created_at: description: 创建时间 @@ -534,8 +535,9 @@ components: description: 已用真流量(MB) type: integer expires_at: - description: 到期时间 + description: 到期时间（待生效套餐为空） format: date-time + nullable: true type: string master_usage_id: description: 主套餐ID（加油包时有值） @@ -759,6 +761,105 @@ components: description: 虚拟号 type: string type: object + DtoAssetWalletResponse: + properties: + available_balance: + description: 可用余额 = balance - frozen_balance（分） + type: integer + balance: + description: 总余额（分） + type: integer + created_at: + description: 创建时间（RFC3339） + format: date-time + type: string + currency: + description: 币种，目前固定 CNY + type: string + frozen_balance: + description: 冻结余额（分） + type: integer + resource_id: + description: 对应卡或设备的数据库ID + minimum: 0 + type: integer + resource_type: + description: 资源类型：iot_card 或 device + type: string + status: + description: 钱包状态：1-正常 2-冻结 3-关闭 + type: integer + status_text: + description: 状态文本 + type: string + updated_at: + description: 更新时间（RFC3339） + format: date-time + type: string + wallet_id: + description: 钱包数据库ID + minimum: 0 + type: integer + type: object + DtoAssetWalletTransactionItem: + properties: + amount: + description: 变动金额（分），充值为正数，扣款/退款为负数 + type: integer + balance_after: + description: 变动后余额（分） + type: integer + balance_before: + description: 变动前余额（分） + type: integer + created_at: + description: 流水创建时间（RFC3339） + format: date-time + type: string + id: + description: 流水记录ID + minimum: 0 + type: integer + reference_no: + description: 关联业务编号：充值单号（CRCH…）或订单号（ORD…）（可空） + nullable: true + type: string + reference_type: + description: 关联业务类型：recharge 或 order（可空） + nullable: true + type: string + remark: + description: 备注（可空） + nullable: true + type: string + transaction_type: + description: 交易类型：recharge/deduct/refund + type: string + transaction_type_text: + description: 交易类型文本：充值/扣款/退款 + type: string + type: object + DtoAssetWalletTransactionListResponse: + properties: + list: + description: 流水列表 + items: + $ref: '#/components/schemas/DtoAssetWalletTransactionItem' + nullable: true + type: array + page: + description: 当前页码 + type: integer + page_size: + description: 每页数量 + type: integer + total: + description: 总记录数 + type: integer + total_pages: + description: 总页数 + type: integer + type: object DtoAssignPermissionsParams: properties: perm_ids: @@ -3365,6 +3466,9 @@ components: virtual_data_mb: description: 虚流量额度(MB) type: integer + virtual_ratio: + description: 虚流量比例(real_data_mb/virtual_data_mb)，启用虚流量时计算，否则为1.0 + type: number type: object DtoPackageSeriesPageResult: properties: @@ -7141,6 +7245,191 @@ paths: summary: 刷新资产状态 tags: - 资产管理 + /api/admin/assets/{asset_type}/{id}/wallet: + get: + description: 查询指定卡或设备的钱包余额概况。企业账号禁止调用。 + parameters: + - description: 资产类型：card 或 device + in: path + name: asset_type + required: true + schema: + description: 资产类型：card 或 device + type: string + - description: 资产ID + in: path + name: id + required: true + schema: + description: 资产ID + minimum: 0 + type: integer + responses: + "200": + content: + application/json: + schema: + properties: + code: + description: 响应码 + example: 0 + type: integer + data: + $ref: '#/components/schemas/DtoAssetWalletResponse' + msg: + description: 响应消息 + example: success + type: string + timestamp: + description: 时间戳 + format: date-time + type: string + required: + - code + - msg + - data + - timestamp + type: object + description: 成功 + "400": + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + description: 请求参数错误 + "401": + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + description: 未认证或认证已过期 + "403": + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + description: 无权访问 + "500": + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + description: 服务器内部错误 + security: + - BearerAuth: [] + summary: 资产钱包概况 + tags: + - 资产管理 + /api/admin/assets/{asset_type}/{id}/wallet/transactions: + get: + description: 分页查询指定资产的钱包收支流水，含充值/扣款来源编号。企业账号禁止调用。 + parameters: + - description: 页码，默认1 + in: query + name: page + schema: + description: 页码，默认1 + type: integer + - description: 每页数量，默认20，最大100 + in: query + name: page_size + schema: + description: 每页数量，默认20，最大100 + type: integer + - description: 交易类型过滤：recharge/deduct/refund + in: query + name: transaction_type + schema: + description: 交易类型过滤：recharge/deduct/refund + nullable: true + type: string + - description: 开始时间（RFC3339） + in: query + name: start_time + schema: + description: 开始时间（RFC3339） + format: date-time + nullable: true + type: string + - description: 结束时间（RFC3339） + in: query + name: end_time + schema: + description: 结束时间（RFC3339） + format: date-time + nullable: true + type: string + - description: 资产类型：card 或 device + in: path + name: asset_type + required: true + schema: + description: 资产类型：card 或 device + type: string + - description: 资产ID + in: path + name: id + required: true + schema: + description: 资产ID + minimum: 0 + type: integer + responses: + "200": + content: + application/json: + schema: + properties: + code: + description: 响应码 + example: 0 + type: integer + data: + $ref: '#/components/schemas/DtoAssetWalletTransactionListResponse' + msg: + description: 响应消息 + example: success + type: string + timestamp: + description: 时间戳 + format: date-time + type: string + required: + - code + - msg + - data + - timestamp + type: object + description: 成功 + "400": + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + description: 请求参数错误 + "401": + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + description: 未认证或认证已过期 + "403": + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + description: 无权访问 + "500": + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + description: 服务器内部错误 + security: + - BearerAuth: [] + summary: 资产钱包流水列表 + tags: + - 资产管理 /api/admin/assets/card/{iccid}/start: post: description: 手动复机单张卡（通过ICCID）。受设备保护期约束。