1171 lines
49 KiB
YAML
1171 lines
49 KiB
YAML
|
openapi: 3.0.3
|
|||
|
|
info:
|
|||
|
|
title: Finance Phase 1 Five-page Acceptance API
|
|||
|
|
version: 1.0.0-draft
|
|||
|
|
description: >-
|
|||
|
|
一期领导验收 5 页目标契约：客户账户、客户应收应付、客户对账单、结算单应收、
|
|||
|
|
结算单应付。只支持 CNY。费用分析、利润表、钱包、预收和充值不属于本契约。
|
|||
|
|
每个 operation 通过 x-implementation-status 标记当前 Java 实现事实；NOT_IMPLEMENTED
|
|||
|
|
仅代表目标契约尚未落地，不得生成按钮或模拟成功入口。
|
|||
|
|
servers:
|
|||
|
|
- url: /api
|
|||
|
|
x-product-scope:
|
|||
|
|
included:
|
|||
|
|
- CUSTOMER_ACCOUNT_DERIVED_VIEW
|
|||
|
|
- CUSTOMER_ARAP_FEE_SOURCE_POOL
|
|||
|
|
- CUSTOMER_RECONCILIATION_STATEMENT
|
|||
|
|
- RECEIVABLE_SETTLEMENT
|
|||
|
|
- PAYABLE_SETTLEMENT
|
|||
|
|
excluded:
|
|||
|
|
- WALLET
|
|||
|
|
- PREPAYMENT
|
|||
|
|
- MANUAL_RECHARGE
|
|||
|
|
- COST_ANALYSIS
|
|||
|
|
- PROFIT_REPORT
|
|||
|
|
- FOREIGN_CURRENCY
|
|||
|
|
- EXCHANGE_RATE
|
|||
|
|
x-source-gate:
|
|||
|
|
eligible: APPROVED + PUBLISHED + settlementIncluded=true + ACTIVE + CNY
|
|||
|
|
currentStatus: Finance 已显式校验非作废事件 PUBLISHED、APPROVED、参与结算、CNY、amount>0、客户/版本/方向/来源归属；Inbox 幂等及 fin_fee_source 写入/替代/作废均已验证。
|
|||
|
|
x-current-verification:
|
|||
|
|
checkedAt: '2026-08-11'
|
|||
|
|
source: 当前 baiyue-firstleg 工作树中的 Controller、DTO、Service、Client 和现有 Surefire 报告。
|
|||
|
|
testStatus: Finance 35/35、Firstleg 549/549（2 skip）、File 114/114、Gateway 26/26、IAM 163/163、Phase3/PDA SQL 12/12、Order SQL 3/3，均 BUILD SUCCESS；来源消费专项 10/10。
|
|||
|
|
paths:
|
|||
|
|
/internal/finance/v1/fee-source-events:
|
|||
|
|
post:
|
|||
|
|
servers:
|
|||
|
|
- url: /
|
|||
|
|
operationId: consumeFirstlegFeeSourceEvent
|
|||
|
|
summary: 消费 Firstleg 不可变费用来源事件
|
|||
|
|
description: >-
|
|||
|
|
使用内部服务令牌鉴权；按 eventId 和完整事件请求哈希幂等消费，回查 Firstleg
|
|||
|
|
入库或柜子费用快照，校验客户、版本、审核、参与结算、CNY、方向和来源类型后，
|
|||
|
|
写入 fin_inbox_event 与 fin_fee_source。调整新增版本并替代旧 AVAILABLE 版本，作废只改状态不删除历史。
|
|||
|
|
x-implementation-status: IMPLEMENTED
|
|||
|
|
x-test-evidence: FinanceFeeSourceEventServiceTest 10/10、InternalFinanceFeeSourceControllerTest 2/2、Finance 全量 35/35 BUILD SUCCESS；Firstleg 相关事件/Relay/快照定向测试 17/17
|
|||
|
|
x-authentication: X-Internal-Service-Token
|
|||
|
|
x-error-codes:
|
|||
|
|
- FIN-EVT-001
|
|||
|
|
- FIN-EVT-002
|
|||
|
|
- FIN-EVT-003
|
|||
|
|
- FIN-EVT-004
|
|||
|
|
- FIN-EVT-005
|
|||
|
|
- FIN-EVT-006
|
|||
|
|
- FIN-EVT-007
|
|||
|
|
- FIN-EVT-008
|
|||
|
|
- FIN-EVT-009
|
|||
|
|
- FIN-EVT-010
|
|||
|
|
- FIN-EVT-011
|
|||
|
|
- FIN-EVT-012
|
|||
|
|
- FIN-EVT-013
|
|||
|
|
- FIN-EVT-014
|
|||
|
|
- FIN-EVT-015
|
|||
|
|
- FIN-EVT-401
|
|||
|
|
parameters:
|
|||
|
|
- $ref: '#/components/parameters/InternalServiceToken'
|
|||
|
|
requestBody:
|
|||
|
|
required: true
|
|||
|
|
content:
|
|||
|
|
application/json:
|
|||
|
|
schema: {$ref: '#/components/schemas/FinanceFeeSourceEvent'}
|
|||
|
|
responses:
|
|||
|
|
'200':
|
|||
|
|
description: 成功消费、同参重放结果或稳定业务错误。
|
|||
|
|
content:
|
|||
|
|
application/json:
|
|||
|
|
schema:
|
|||
|
|
oneOf:
|
|||
|
|
- $ref: '#/components/schemas/FeeSourceEventResultEnvelope'
|
|||
|
|
- $ref: '#/components/schemas/ErrorEnvelope'
|
|||
|
|
/platform/finance/v1/accounts:
|
|||
|
|
get:
|
|||
|
|
operationId: listDerivedCustomerAccounts
|
|||
|
|
summary: 查询客户财务账户派生汇总
|
|||
|
|
description: 只读聚合，不返回钱包余额，不提供充值或余额调整动作。
|
|||
|
|
x-implementation-status: NOT_IMPLEMENTED
|
|||
|
|
x-permission: platform:finance:account:view
|
|||
|
|
parameters:
|
|||
|
|
- $ref: '#/components/parameters/Page'
|
|||
|
|
- $ref: '#/components/parameters/PageSize'
|
|||
|
|
- name: keyword
|
|||
|
|
in: query
|
|||
|
|
schema: {type: string}
|
|||
|
|
- name: status
|
|||
|
|
in: query
|
|||
|
|
schema: {type: string, enum: [ACTIVE, DISABLED]}
|
|||
|
|
responses:
|
|||
|
|
'200': {$ref: '#/components/responses/AccountPageResponse'}
|
|||
|
|
/platform/finance/v1/customer-accounts/{customerId}:
|
|||
|
|
get:
|
|||
|
|
operationId: getDerivedCustomerAccount
|
|||
|
|
summary: 查询客户财务账户详情
|
|||
|
|
x-implementation-status: IMPLEMENTED
|
|||
|
|
x-test-evidence: FinanceReadApiBehaviorTest 3/3 通过；fivePlatformPageMethodsUseTypedQueryFacade 覆盖该委托
|
|||
|
|
x-permission: platform:finance:bill:view
|
|||
|
|
parameters:
|
|||
|
|
- $ref: '#/components/parameters/CustomerId'
|
|||
|
|
responses:
|
|||
|
|
'200': {$ref: '#/components/responses/CustomerAccountReadResponse'}
|
|||
|
|
'404': {$ref: '#/components/responses/BusinessError'}
|
|||
|
|
/platform/finance/v1/accounts/{customerId}/ledger:
|
|||
|
|
get:
|
|||
|
|
operationId: listDerivedCustomerAccountLedger
|
|||
|
|
summary: 查询客户财务派生流水
|
|||
|
|
x-implementation-status: NOT_IMPLEMENTED
|
|||
|
|
x-permission: platform:finance:account:view
|
|||
|
|
parameters:
|
|||
|
|
- $ref: '#/components/parameters/CustomerId'
|
|||
|
|
- $ref: '#/components/parameters/Page'
|
|||
|
|
- $ref: '#/components/parameters/PageSize'
|
|||
|
|
- name: businessType
|
|||
|
|
in: query
|
|||
|
|
schema: {$ref: '#/components/schemas/LedgerBusinessType'}
|
|||
|
|
- name: startDate
|
|||
|
|
in: query
|
|||
|
|
schema: {type: string, format: date}
|
|||
|
|
- name: endDate
|
|||
|
|
in: query
|
|||
|
|
schema: {type: string, format: date}
|
|||
|
|
responses:
|
|||
|
|
'200': {$ref: '#/components/responses/LedgerPageResponse'}
|
|||
|
|
/platform/finance/v1/fee-pool:
|
|||
|
|
get:
|
|||
|
|
operationId: listFinanceFeeSources
|
|||
|
|
summary: 查询客户应收应付费用来源池
|
|||
|
|
x-implementation-status: IMPLEMENTED
|
|||
|
|
x-test-evidence: FinanceReadApiBehaviorTest 3/3、FinanceFeePoolDirectionBehaviorTest 2/2 通过
|
|||
|
|
x-permission: platform:finance:bill:view
|
|||
|
|
parameters:
|
|||
|
|
- name: customerId
|
|||
|
|
in: query
|
|||
|
|
required: true
|
|||
|
|
schema: {$ref: '#/components/schemas/Id'}
|
|||
|
|
- name: direction
|
|||
|
|
in: query
|
|||
|
|
schema: {$ref: '#/components/schemas/FeeDirection'}
|
|||
|
|
responses:
|
|||
|
|
'200': {$ref: '#/components/responses/FeePoolReadResponse'}
|
|||
|
|
/platform/finance/v1/fee-sources/{feeSourceId}:
|
|||
|
|
get:
|
|||
|
|
operationId: getFinanceFeeSource
|
|||
|
|
summary: 查询费用来源详情、业务关联和操作记录
|
|||
|
|
x-implementation-status: NOT_IMPLEMENTED
|
|||
|
|
x-permission: platform:finance:fee-source:view
|
|||
|
|
parameters:
|
|||
|
|
- $ref: '#/components/parameters/FeeSourceId'
|
|||
|
|
responses:
|
|||
|
|
'200': {$ref: '#/components/responses/FeeSourceDetailResponse'}
|
|||
|
|
'404': {$ref: '#/components/responses/BusinessError'}
|
|||
|
|
/platform/finance/v1/fee-sources/{feeSourceId}/review:
|
|||
|
|
post:
|
|||
|
|
operationId: reviewFinanceFeeSource
|
|||
|
|
summary: 审核费用来源
|
|||
|
|
x-implementation-status: NOT_IMPLEMENTED
|
|||
|
|
x-permission: platform:finance:fee-source:review
|
|||
|
|
parameters:
|
|||
|
|
- $ref: '#/components/parameters/FeeSourceId'
|
|||
|
|
- $ref: '#/components/parameters/IdempotencyKey'
|
|||
|
|
requestBody:
|
|||
|
|
required: true
|
|||
|
|
content:
|
|||
|
|
application/json:
|
|||
|
|
schema: {$ref: '#/components/schemas/ReviewRequest'}
|
|||
|
|
responses:
|
|||
|
|
'200': {$ref: '#/components/responses/FeeSourceDetailResponse'}
|
|||
|
|
'409': {$ref: '#/components/responses/BusinessError'}
|
|||
|
|
/platform/finance/v1/fee-sources/{feeSourceId}/settlement-inclusion:
|
|||
|
|
put:
|
|||
|
|
operationId: updateFeeSourceSettlementInclusion
|
|||
|
|
summary: 设置参与结算或禁止结算
|
|||
|
|
x-implementation-status: NOT_IMPLEMENTED
|
|||
|
|
x-permission: platform:finance:fee-source:settlement
|
|||
|
|
parameters:
|
|||
|
|
- $ref: '#/components/parameters/FeeSourceId'
|
|||
|
|
- $ref: '#/components/parameters/IdempotencyKey'
|
|||
|
|
requestBody:
|
|||
|
|
required: true
|
|||
|
|
content:
|
|||
|
|
application/json:
|
|||
|
|
schema: {$ref: '#/components/schemas/SettlementInclusionRequest'}
|
|||
|
|
responses:
|
|||
|
|
'200': {$ref: '#/components/responses/FeeSourceDetailResponse'}
|
|||
|
|
'409': {$ref: '#/components/responses/BusinessError'}
|
|||
|
|
/platform/finance/v1/statements:
|
|||
|
|
get:
|
|||
|
|
operationId: listReconciliationStatements
|
|||
|
|
summary: 查询客户对账单
|
|||
|
|
x-implementation-status: IMPLEMENTED
|
|||
|
|
x-test-evidence: FinanceReadApiBehaviorTest 3/3 通过；fivePlatformPageMethodsUseTypedQueryFacade 覆盖该委托
|
|||
|
|
x-permission: platform:finance:bill:view
|
|||
|
|
parameters:
|
|||
|
|
- name: customerId
|
|||
|
|
in: query
|
|||
|
|
required: true
|
|||
|
|
schema: {$ref: '#/components/schemas/Id'}
|
|||
|
|
responses:
|
|||
|
|
'200': {$ref: '#/components/responses/StatementListReadResponse'}
|
|||
|
|
post:
|
|||
|
|
operationId: createReconciliationStatement
|
|||
|
|
summary: 按截止时间或勾选来源生成客户对账单草稿
|
|||
|
|
x-implementation-status: NOT_IMPLEMENTED
|
|||
|
|
x-permission: platform:finance:reconciliation:create
|
|||
|
|
parameters:
|
|||
|
|
- $ref: '#/components/parameters/IdempotencyKey'
|
|||
|
|
requestBody:
|
|||
|
|
required: true
|
|||
|
|
content:
|
|||
|
|
application/json:
|
|||
|
|
schema: {$ref: '#/components/schemas/CreateReconciliationRequest'}
|
|||
|
|
responses:
|
|||
|
|
'200': {$ref: '#/components/responses/ReconciliationDetailResponse'}
|
|||
|
|
'409': {$ref: '#/components/responses/BusinessError'}
|
|||
|
|
/platform/finance/v1/bills/{billId}:
|
|||
|
|
get:
|
|||
|
|
operationId: getReconciliationStatement
|
|||
|
|
summary: 查询客户对账单详情、费用明细和支付历史
|
|||
|
|
x-implementation-status: IMPLEMENTED
|
|||
|
|
x-test-evidence: FinanceReadApiBehaviorTest 3/3 通过；客户详情隔离与固定 DTO 行为有直接覆盖
|
|||
|
|
x-permission: platform:finance:bill:view
|
|||
|
|
parameters:
|
|||
|
|
- $ref: '#/components/parameters/BillId'
|
|||
|
|
responses:
|
|||
|
|
'200': {$ref: '#/components/responses/StatementDetailReadResponse'}
|
|||
|
|
'404': {$ref: '#/components/responses/BusinessError'}
|
|||
|
|
/platform/finance/v1/reconciliation-statements/{statementId}/actions:
|
|||
|
|
post:
|
|||
|
|
operationId: actionReconciliationStatement
|
|||
|
|
summary: 提交审核、通过、拒绝或作废客户对账单
|
|||
|
|
x-implementation-status: NOT_IMPLEMENTED
|
|||
|
|
x-permission: platform:finance:reconciliation:review
|
|||
|
|
parameters:
|
|||
|
|
- $ref: '#/components/parameters/StatementId'
|
|||
|
|
- $ref: '#/components/parameters/IdempotencyKey'
|
|||
|
|
requestBody:
|
|||
|
|
required: true
|
|||
|
|
content:
|
|||
|
|
application/json:
|
|||
|
|
schema: {$ref: '#/components/schemas/DocumentActionRequest'}
|
|||
|
|
responses:
|
|||
|
|
'200': {$ref: '#/components/responses/ReconciliationDetailResponse'}
|
|||
|
|
'409': {$ref: '#/components/responses/BusinessError'}
|
|||
|
|
/platform/finance/v1/receivable-settlements:
|
|||
|
|
get:
|
|||
|
|
operationId: listReceivableSettlements
|
|||
|
|
summary: 查询结算单应收
|
|||
|
|
x-implementation-status: IMPLEMENTED
|
|||
|
|
x-test-evidence: FinanceReadApiBehaviorTest 3/3 通过；fivePlatformPageMethodsUseTypedQueryFacade 覆盖该委托
|
|||
|
|
x-permission: platform:finance:bill:view
|
|||
|
|
parameters:
|
|||
|
|
- name: customerId
|
|||
|
|
in: query
|
|||
|
|
required: true
|
|||
|
|
schema: {$ref: '#/components/schemas/Id'}
|
|||
|
|
responses:
|
|||
|
|
'200': {$ref: '#/components/responses/ReceivableSettlementListReadResponse'}
|
|||
|
|
post:
|
|||
|
|
operationId: createReceivableSettlement
|
|||
|
|
summary: 从审核通过的客户对账单生成应收结算单
|
|||
|
|
x-implementation-status: NOT_IMPLEMENTED
|
|||
|
|
x-permission: platform:finance:settlement-ar:create
|
|||
|
|
parameters:
|
|||
|
|
- $ref: '#/components/parameters/IdempotencyKey'
|
|||
|
|
requestBody:
|
|||
|
|
required: true
|
|||
|
|
content:
|
|||
|
|
application/json:
|
|||
|
|
schema: {$ref: '#/components/schemas/CreateReceivableSettlementRequest'}
|
|||
|
|
responses:
|
|||
|
|
'200': {$ref: '#/components/responses/SettlementDetailResponse'}
|
|||
|
|
'409': {$ref: '#/components/responses/BusinessError'}
|
|||
|
|
/platform/finance/v1/payable-settlements:
|
|||
|
|
get:
|
|||
|
|
operationId: listPayableSettlements
|
|||
|
|
summary: 查询结算单应付
|
|||
|
|
x-implementation-status: IMPLEMENTED
|
|||
|
|
x-test-evidence: FinanceReadApiBehaviorTest 3/3 通过；fivePlatformPageMethodsUseTypedQueryFacade 覆盖该委托
|
|||
|
|
x-permission: platform:finance:cost:view
|
|||
|
|
parameters:
|
|||
|
|
- name: customerId
|
|||
|
|
in: query
|
|||
|
|
required: true
|
|||
|
|
schema: {$ref: '#/components/schemas/Id'}
|
|||
|
|
responses:
|
|||
|
|
'200': {$ref: '#/components/responses/PayableSettlementListReadResponse'}
|
|||
|
|
post:
|
|||
|
|
operationId: createPayableSettlement
|
|||
|
|
summary: 从审核通过且参与结算的应付来源生成应付结算单
|
|||
|
|
x-implementation-status: NOT_IMPLEMENTED
|
|||
|
|
x-permission: platform:finance:settlement-ap:create
|
|||
|
|
parameters:
|
|||
|
|
- $ref: '#/components/parameters/IdempotencyKey'
|
|||
|
|
requestBody:
|
|||
|
|
required: true
|
|||
|
|
content:
|
|||
|
|
application/json:
|
|||
|
|
schema: {$ref: '#/components/schemas/CreatePayableSettlementRequest'}
|
|||
|
|
responses:
|
|||
|
|
'200': {$ref: '#/components/responses/SettlementDetailResponse'}
|
|||
|
|
'409': {$ref: '#/components/responses/BusinessError'}
|
|||
|
|
/platform/finance/v1/receipts:
|
|||
|
|
get:
|
|||
|
|
operationId: listPlatformReceipts
|
|||
|
|
summary: 平台按客户查询人工收款记录
|
|||
|
|
x-implementation-status: IMPLEMENTED
|
|||
|
|
x-test-evidence: FinanceReadApiBehaviorTest 3/3 通过；PlatformReceipt 固定 DTO 与客户范围委托已验证
|
|||
|
|
x-permission: platform:finance:receipt:view
|
|||
|
|
parameters:
|
|||
|
|
- name: customerId
|
|||
|
|
in: query
|
|||
|
|
required: true
|
|||
|
|
schema: {$ref: '#/components/schemas/Id'}
|
|||
|
|
responses:
|
|||
|
|
'200': {$ref: '#/components/responses/PlatformReceiptListReadResponse'}
|
|||
|
|
post:
|
|||
|
|
operationId: createReceiptWithAllocations
|
|||
|
|
summary: 人工登记一笔收款并分配到一张或多张应收结算单
|
|||
|
|
description: >-
|
|||
|
|
收款总额必须等于 allocations 金额之和；所有结算单必须属于同一客户且为 CNY，
|
|||
|
|
每笔分配不得超过对应未收余额。示例：收款 300 元可分配到 3 张结算单各 100 元，
|
|||
|
|
共用同一组收款凭证图片。File 校验失败或不可用时必须 fail-closed，不得落库。
|
|||
|
|
x-implementation-status: IMPLEMENTED
|
|||
|
|
x-test-evidence: FinanceServiceValidationTest 10/10、PlatformFinanceControllerBehaviorTest 2/2 通过；覆盖多账单分配和凭证 fail-closed
|
|||
|
|
x-permission: platform:finance:receipt:create
|
|||
|
|
parameters:
|
|||
|
|
- $ref: '#/components/parameters/IdempotencyKey'
|
|||
|
|
requestBody:
|
|||
|
|
required: true
|
|||
|
|
content:
|
|||
|
|
application/json:
|
|||
|
|
schema: {$ref: '#/components/schemas/CreateReceiptRequest'}
|
|||
|
|
responses:
|
|||
|
|
'200': {$ref: '#/components/responses/ResourceResultResponse'}
|
|||
|
|
'409': {$ref: '#/components/responses/BusinessError'}
|
|||
|
|
/client/finance/v1/receipts:
|
|||
|
|
get:
|
|||
|
|
operationId: listClientVisibleReceipts
|
|||
|
|
summary: 客户只读查询已确认收款和账单分配
|
|||
|
|
description: 使用登录客户身份隔离，不接收 customerId；不返回凭证、操作人、内部备注或 tenantId。
|
|||
|
|
x-implementation-status: IMPLEMENTED
|
|||
|
|
x-test-evidence: FinanceReadApiBehaviorTest 3/3 通过；ClientReceipt 脱敏序列化和登录客户隔离有直接覆盖
|
|||
|
|
x-permission: merchant:finance:statement:view
|
|||
|
|
responses:
|
|||
|
|
'200': {$ref: '#/components/responses/ClientReceiptListReadResponse'}
|
|||
|
|
/platform/finance/v1/settlements/{settlementId}:
|
|||
|
|
get:
|
|||
|
|
operationId: getSettlement
|
|||
|
|
summary: 查询应收或应付结算单详情
|
|||
|
|
x-implementation-status: NOT_IMPLEMENTED
|
|||
|
|
x-permission-any-of:
|
|||
|
|
- platform:finance:settlement-ar:view
|
|||
|
|
- platform:finance:settlement-ap:view
|
|||
|
|
parameters:
|
|||
|
|
- $ref: '#/components/parameters/SettlementId'
|
|||
|
|
responses:
|
|||
|
|
'200': {$ref: '#/components/responses/SettlementDetailResponse'}
|
|||
|
|
'404': {$ref: '#/components/responses/BusinessError'}
|
|||
|
|
/platform/finance/v1/settlements/{settlementId}/transactions:
|
|||
|
|
post:
|
|||
|
|
operationId: createSettlementPayment
|
|||
|
|
summary: 人工登记应付结算单付款并上传凭证
|
|||
|
|
x-implementation-status: NOT_IMPLEMENTED
|
|||
|
|
x-permission: platform:finance:payment:create
|
|||
|
|
parameters:
|
|||
|
|
- $ref: '#/components/parameters/SettlementId'
|
|||
|
|
- $ref: '#/components/parameters/IdempotencyKey'
|
|||
|
|
requestBody:
|
|||
|
|
required: true
|
|||
|
|
content:
|
|||
|
|
application/json:
|
|||
|
|
schema: {$ref: '#/components/schemas/CreateSettlementPaymentRequest'}
|
|||
|
|
responses:
|
|||
|
|
'200': {$ref: '#/components/responses/SettlementDetailResponse'}
|
|||
|
|
'409': {$ref: '#/components/responses/BusinessError'}
|
|||
|
|
components:
|
|||
|
|
parameters:
|
|||
|
|
InternalServiceToken:
|
|||
|
|
name: X-Internal-Service-Token
|
|||
|
|
in: header
|
|||
|
|
required: true
|
|||
|
|
schema: {type: string, minLength: 1}
|
|||
|
|
CustomerId:
|
|||
|
|
name: customerId
|
|||
|
|
in: path
|
|||
|
|
required: true
|
|||
|
|
schema: {$ref: '#/components/schemas/Id'}
|
|||
|
|
FeeSourceId:
|
|||
|
|
name: feeSourceId
|
|||
|
|
in: path
|
|||
|
|
required: true
|
|||
|
|
schema: {$ref: '#/components/schemas/Id'}
|
|||
|
|
StatementId:
|
|||
|
|
name: statementId
|
|||
|
|
in: path
|
|||
|
|
required: true
|
|||
|
|
schema: {$ref: '#/components/schemas/Id'}
|
|||
|
|
BillId:
|
|||
|
|
name: billId
|
|||
|
|
in: path
|
|||
|
|
required: true
|
|||
|
|
schema: {$ref: '#/components/schemas/Id'}
|
|||
|
|
SettlementId:
|
|||
|
|
name: settlementId
|
|||
|
|
in: path
|
|||
|
|
required: true
|
|||
|
|
schema: {$ref: '#/components/schemas/Id'}
|
|||
|
|
Page:
|
|||
|
|
name: page
|
|||
|
|
in: query
|
|||
|
|
required: false
|
|||
|
|
schema: {type: integer, minimum: 1, default: 1}
|
|||
|
|
PageSize:
|
|||
|
|
name: pageSize
|
|||
|
|
in: query
|
|||
|
|
required: false
|
|||
|
|
schema: {type: integer, minimum: 1, maximum: 200, default: 20}
|
|||
|
|
IdempotencyKey:
|
|||
|
|
name: Idempotency-Key
|
|||
|
|
in: header
|
|||
|
|
required: true
|
|||
|
|
schema: {type: string, minLength: 1, maxLength: 128}
|
|||
|
|
description: 完整规范化 method/path/customer/body 哈希；同参重放，异参冲突。
|
|||
|
|
schemas:
|
|||
|
|
Id:
|
|||
|
|
type: string
|
|||
|
|
pattern: '^[1-9][0-9]*$'
|
|||
|
|
FinanceFeeSourceEvent:
|
|||
|
|
type: object
|
|||
|
|
required: [eventId, eventType, eventVersion, producer, occurredAt, tenantId, aggregateType, aggregateId, sequence, idempotencyKey, payloadHash, payload]
|
|||
|
|
properties:
|
|||
|
|
eventId: {type: string, minLength: 1}
|
|||
|
|
eventType:
|
|||
|
|
type: string
|
|||
|
|
enum: [FIRSTLEG_FEE_PUBLISHED, FIRSTLEG_FEE_ADJUSTED, FIRSTLEG_FEE_VOIDED]
|
|||
|
|
eventVersion: {type: integer, minimum: 1}
|
|||
|
|
producer: {type: string, enum: [firstleg-service]}
|
|||
|
|
occurredAt: {type: string, format: date-time}
|
|||
|
|
tenantId: {$ref: '#/components/schemas/Id'}
|
|||
|
|
aggregateType: {type: string, enum: [INBOUND, CONTAINER]}
|
|||
|
|
aggregateId: {$ref: '#/components/schemas/Id'}
|
|||
|
|
sequence: {type: integer, minimum: 1}
|
|||
|
|
idempotencyKey: {type: string, minLength: 1}
|
|||
|
|
payloadHash: {type: string, pattern: '^[a-f0-9]{64}$'}
|
|||
|
|
payload: {$ref: '#/components/schemas/FinanceFeeSourceEventPayload'}
|
|||
|
|
FinanceFeeSourceEventPayload:
|
|||
|
|
type: object
|
|||
|
|
required: [feeId, feeVersion]
|
|||
|
|
properties:
|
|||
|
|
inboundId: {$ref: '#/components/schemas/Id'}
|
|||
|
|
containerId: {$ref: '#/components/schemas/Id'}
|
|||
|
|
feeId: {$ref: '#/components/schemas/Id'}
|
|||
|
|
feeVersion: {type: integer, minimum: 1}
|
|||
|
|
oneOf:
|
|||
|
|
- required: [inboundId]
|
|||
|
|
not: {required: [containerId]}
|
|||
|
|
- required: [containerId]
|
|||
|
|
not: {required: [inboundId]}
|
|||
|
|
FeeSourceEventResult:
|
|||
|
|
type: object
|
|||
|
|
required: [feeSourceId]
|
|||
|
|
properties:
|
|||
|
|
feeSourceId: {type: integer, format: int64, minimum: 1}
|
|||
|
|
Money:
|
|||
|
|
type: string
|
|||
|
|
pattern: '^(0|[1-9][0-9]*)(\.[0-9]{1,6})?$'
|
|||
|
|
FeeDirection:
|
|||
|
|
type: string
|
|||
|
|
enum: [RECEIVABLE, PAYABLE]
|
|||
|
|
FeeSourceType:
|
|||
|
|
type: string
|
|||
|
|
enum: [INBOUND_FEE, CONTAINER_FEE]
|
|||
|
|
ReviewStatus:
|
|||
|
|
type: string
|
|||
|
|
enum: [PENDING, APPROVED, REJECTED]
|
|||
|
|
ReconciliationStatus:
|
|||
|
|
type: string
|
|||
|
|
enum: [DRAFT, PENDING_REVIEW, APPROVED, REJECTED, VOIDED]
|
|||
|
|
SettlementStatus:
|
|||
|
|
type: string
|
|||
|
|
enum: [DRAFT, PENDING_REVIEW, ISSUED, PARTIALLY_PAID, PAID, REJECTED, VOIDED]
|
|||
|
|
PaymentStatus:
|
|||
|
|
type: string
|
|||
|
|
enum: [UNPAID, PARTIALLY_PAID, PAID, OVERDUE]
|
|||
|
|
LedgerBusinessType:
|
|||
|
|
type: string
|
|||
|
|
enum: [FEE_INCLUDED, FEE_EXCLUDED, RECONCILIATION_CREATED, SETTLEMENT_ISSUED, RECEIPT, PAYMENT, ADJUSTMENT, VOID]
|
|||
|
|
TraceMeta:
|
|||
|
|
type: object
|
|||
|
|
required: [requestId, traceId, timestamp]
|
|||
|
|
properties:
|
|||
|
|
requestId: {type: string, minLength: 1}
|
|||
|
|
traceId: {type: string, minLength: 1}
|
|||
|
|
timestamp: {type: string, format: date-time}
|
|||
|
|
PageMeta:
|
|||
|
|
type: object
|
|||
|
|
required: [page, pageSize, total]
|
|||
|
|
properties:
|
|||
|
|
page: {type: integer, minimum: 1}
|
|||
|
|
pageSize: {type: integer, minimum: 1}
|
|||
|
|
total: {type: integer, format: int64, minimum: 0}
|
|||
|
|
AccountSummary:
|
|||
|
|
type: object
|
|||
|
|
required: [customerId, customerCode, customerName, outstandingReceivable, pendingBilling, receivedInPeriod, outstandingPayable, status, lastChangedAt]
|
|||
|
|
properties:
|
|||
|
|
customerId: {$ref: '#/components/schemas/Id'}
|
|||
|
|
customerCode: {type: string}
|
|||
|
|
customerName: {type: string}
|
|||
|
|
contactName: {type: string}
|
|||
|
|
contactPhone: {type: string}
|
|||
|
|
outstandingReceivable: {$ref: '#/components/schemas/Money'}
|
|||
|
|
pendingBilling: {$ref: '#/components/schemas/Money'}
|
|||
|
|
receivedInPeriod: {$ref: '#/components/schemas/Money'}
|
|||
|
|
outstandingPayable: {$ref: '#/components/schemas/Money'}
|
|||
|
|
status: {type: string, enum: [ACTIVE, DISABLED]}
|
|||
|
|
lastChangedAt: {type: string, format: date-time}
|
|||
|
|
AccountDetail:
|
|||
|
|
allOf:
|
|||
|
|
- $ref: '#/components/schemas/AccountSummary'
|
|||
|
|
- type: object
|
|||
|
|
properties:
|
|||
|
|
email: {type: string}
|
|||
|
|
creditDays: {type: integer, minimum: 0}
|
|||
|
|
CustomerAccountRead:
|
|||
|
|
type: object
|
|||
|
|
required: [customerId, currency, accountMode, totalReceivable, totalReceived, outstandingAmount, entries]
|
|||
|
|
properties:
|
|||
|
|
customerId: {$ref: '#/components/schemas/Id'}
|
|||
|
|
currency: {type: string, enum: [CNY]}
|
|||
|
|
accountMode: {type: string, enum: [MANUAL_RECEIVABLE_LEDGER]}
|
|||
|
|
totalReceivable: {$ref: '#/components/schemas/Money'}
|
|||
|
|
totalReceived: {$ref: '#/components/schemas/Money'}
|
|||
|
|
outstandingAmount: {$ref: '#/components/schemas/Money'}
|
|||
|
|
entries:
|
|||
|
|
type: array
|
|||
|
|
items: {$ref: '#/components/schemas/AccountEntryRead'}
|
|||
|
|
AccountEntryRead:
|
|||
|
|
type: object
|
|||
|
|
required: [entryType, resourceId, resourceNo, occurredAt, debitAmount, creditAmount, currency, status]
|
|||
|
|
properties:
|
|||
|
|
entryType: {type: string, enum: [RECEIVABLE, RECEIPT]}
|
|||
|
|
resourceId: {$ref: '#/components/schemas/Id'}
|
|||
|
|
resourceNo: {type: string}
|
|||
|
|
occurredAt: {type: string, format: date-time}
|
|||
|
|
debitAmount: {$ref: '#/components/schemas/Money'}
|
|||
|
|
creditAmount: {$ref: '#/components/schemas/Money'}
|
|||
|
|
currency: {type: string, enum: [CNY]}
|
|||
|
|
status: {type: string}
|
|||
|
|
LedgerEntry:
|
|||
|
|
type: object
|
|||
|
|
required: [ledgerId, occurredAt, businessType, documentType, documentId, receivableChange, payableChange, outstandingReceivableAfter, operatorName]
|
|||
|
|
properties:
|
|||
|
|
ledgerId: {$ref: '#/components/schemas/Id'}
|
|||
|
|
occurredAt: {type: string, format: date-time}
|
|||
|
|
businessType: {$ref: '#/components/schemas/LedgerBusinessType'}
|
|||
|
|
documentType: {type: string}
|
|||
|
|
documentId: {$ref: '#/components/schemas/Id'}
|
|||
|
|
documentNo: {type: string}
|
|||
|
|
receivableChange: {$ref: '#/components/schemas/Money'}
|
|||
|
|
payableChange: {$ref: '#/components/schemas/Money'}
|
|||
|
|
outstandingReceivableAfter: {$ref: '#/components/schemas/Money'}
|
|||
|
|
operatorName: {type: string}
|
|||
|
|
remark: {type: string}
|
|||
|
|
FeeSource:
|
|||
|
|
type: object
|
|||
|
|
required: [feeSourceId, sourceType, sourceFeeId, sourceVersion, direction, customerId, businessDate, feeItemName, amount, currency, reviewStatus, settlementIncluded, sourceStatus, statementGenerated]
|
|||
|
|
properties:
|
|||
|
|
feeSourceId: {$ref: '#/components/schemas/Id'}
|
|||
|
|
sourceType: {$ref: '#/components/schemas/FeeSourceType'}
|
|||
|
|
sourceFeeId: {$ref: '#/components/schemas/Id'}
|
|||
|
|
sourceVersion: {type: integer, minimum: 1}
|
|||
|
|
direction: {$ref: '#/components/schemas/FeeDirection'}
|
|||
|
|
customerId: {$ref: '#/components/schemas/Id'}
|
|||
|
|
customerName: {type: string}
|
|||
|
|
supplierId: {$ref: '#/components/schemas/Id'}
|
|||
|
|
supplierName: {type: string}
|
|||
|
|
inboundId: {$ref: '#/components/schemas/Id'}
|
|||
|
|
inboundCode: {type: string}
|
|||
|
|
containerId: {$ref: '#/components/schemas/Id'}
|
|||
|
|
containerNo: {type: string}
|
|||
|
|
businessDate: {type: string, format: date}
|
|||
|
|
feeItemName: {type: string}
|
|||
|
|
quantity: {$ref: '#/components/schemas/Money'}
|
|||
|
|
unitPrice: {$ref: '#/components/schemas/Money'}
|
|||
|
|
amount: {$ref: '#/components/schemas/Money'}
|
|||
|
|
currency: {type: string, enum: [CNY]}
|
|||
|
|
reviewStatus: {$ref: '#/components/schemas/ReviewStatus'}
|
|||
|
|
settlementIncluded: {type: boolean}
|
|||
|
|
sourceStatus: {type: string, enum: [AVAILABLE, LOCKED, BILLED, VOIDED, SUPERSEDED]}
|
|||
|
|
statementGenerated: {type: boolean}
|
|||
|
|
FeeSourceDetail:
|
|||
|
|
allOf:
|
|||
|
|
- $ref: '#/components/schemas/FeeSource'
|
|||
|
|
- type: object
|
|||
|
|
properties:
|
|||
|
|
reviewReason: {type: string}
|
|||
|
|
settlementReason: {type: string}
|
|||
|
|
sourceHash: {type: string}
|
|||
|
|
operationLogs:
|
|||
|
|
type: array
|
|||
|
|
items: {$ref: '#/components/schemas/OperationLog'}
|
|||
|
|
FeePoolItemRead:
|
|||
|
|
type: object
|
|||
|
|
required: [poolItemId, direction, sourceType, sourceId, sourceVersion, feeItemName, amount, currency, status, createdAt]
|
|||
|
|
properties:
|
|||
|
|
poolItemId: {type: string}
|
|||
|
|
direction: {$ref: '#/components/schemas/FeeDirection'}
|
|||
|
|
sourceType: {type: string, enum: [FIRSTLEG_FEE, MANUAL_COST]}
|
|||
|
|
sourceId: {$ref: '#/components/schemas/Id'}
|
|||
|
|
sourceVersion: {type: integer, minimum: 1}
|
|||
|
|
orderId: {$ref: '#/components/schemas/Id'}
|
|||
|
|
inboundId: {$ref: '#/components/schemas/Id'}
|
|||
|
|
containerId: {$ref: '#/components/schemas/Id'}
|
|||
|
|
feeItemName: {type: string}
|
|||
|
|
amount: {$ref: '#/components/schemas/Money'}
|
|||
|
|
currency: {type: string, enum: [CNY]}
|
|||
|
|
status: {type: string}
|
|||
|
|
createdAt: {type: string, format: date-time}
|
|||
|
|
OperationLog:
|
|||
|
|
type: object
|
|||
|
|
required: [occurredAt, action, operatorName, result]
|
|||
|
|
properties:
|
|||
|
|
occurredAt: {type: string, format: date-time}
|
|||
|
|
action: {type: string}
|
|||
|
|
operatorName: {type: string}
|
|||
|
|
result: {type: string}
|
|||
|
|
remark: {type: string}
|
|||
|
|
ReviewRequest:
|
|||
|
|
type: object
|
|||
|
|
required: [action, expectedVersion]
|
|||
|
|
properties:
|
|||
|
|
action: {type: string, enum: [APPROVE, REJECT]}
|
|||
|
|
reason: {type: string, maxLength: 500}
|
|||
|
|
expectedVersion: {type: integer, minimum: 0}
|
|||
|
|
SettlementInclusionRequest:
|
|||
|
|
type: object
|
|||
|
|
required: [included, reason, expectedVersion]
|
|||
|
|
properties:
|
|||
|
|
included: {type: boolean}
|
|||
|
|
reason: {type: string, minLength: 1, maxLength: 500}
|
|||
|
|
expectedVersion: {type: integer, minimum: 0}
|
|||
|
|
ReconciliationSummary:
|
|||
|
|
type: object
|
|||
|
|
required: [statementId, statementNo, customerId, customerName, periodStart, periodEnd, creditDays, currency, totalReceivable, receivedAmount, outstandingAmount, settled, status, version, createdAt, updatedAt]
|
|||
|
|
properties:
|
|||
|
|
statementId: {$ref: '#/components/schemas/Id'}
|
|||
|
|
statementNo: {type: string}
|
|||
|
|
customerId: {$ref: '#/components/schemas/Id'}
|
|||
|
|
customerName: {type: string}
|
|||
|
|
periodStart: {type: string, format: date}
|
|||
|
|
periodEnd: {type: string, format: date}
|
|||
|
|
creditDays: {type: integer, minimum: 0}
|
|||
|
|
currency: {type: string, enum: [CNY]}
|
|||
|
|
totalReceivable: {$ref: '#/components/schemas/Money'}
|
|||
|
|
receivedAmount: {$ref: '#/components/schemas/Money'}
|
|||
|
|
outstandingAmount: {$ref: '#/components/schemas/Money'}
|
|||
|
|
lastReceiptAt: {type: string, format: date-time}
|
|||
|
|
settled: {type: boolean}
|
|||
|
|
status: {$ref: '#/components/schemas/ReconciliationStatus'}
|
|||
|
|
version: {type: integer, minimum: 0}
|
|||
|
|
createdAt: {type: string, format: date-time}
|
|||
|
|
updatedAt: {type: string, format: date-time}
|
|||
|
|
ReconciliationDetail:
|
|||
|
|
allOf:
|
|||
|
|
- $ref: '#/components/schemas/ReconciliationSummary'
|
|||
|
|
- type: object
|
|||
|
|
required: [lines, paymentHistory]
|
|||
|
|
properties:
|
|||
|
|
remark: {type: string}
|
|||
|
|
lines:
|
|||
|
|
type: array
|
|||
|
|
items: {$ref: '#/components/schemas/FeeSource'}
|
|||
|
|
paymentHistory:
|
|||
|
|
type: array
|
|||
|
|
items: {$ref: '#/components/schemas/SettlementTransaction'}
|
|||
|
|
StatementRead:
|
|||
|
|
type: object
|
|||
|
|
required: [id, customerId, billNo, billDate, dueDate, totalAmount, receivedAmount, outstandingAmount, currency, status, version]
|
|||
|
|
properties:
|
|||
|
|
id: {$ref: '#/components/schemas/Id'}
|
|||
|
|
customerId: {$ref: '#/components/schemas/Id'}
|
|||
|
|
billNo: {type: string}
|
|||
|
|
customerName: {type: string}
|
|||
|
|
billDate: {type: string, format: date}
|
|||
|
|
dueDate: {type: string, format: date}
|
|||
|
|
totalAmount: {$ref: '#/components/schemas/Money'}
|
|||
|
|
receivedAmount: {$ref: '#/components/schemas/Money'}
|
|||
|
|
outstandingAmount: {$ref: '#/components/schemas/Money'}
|
|||
|
|
currency: {type: string, enum: [CNY]}
|
|||
|
|
status: {type: string, enum: [DRAFT, ISSUED, PARTIALLY_PAID, PAID, VOIDED]}
|
|||
|
|
version: {type: integer, minimum: 0}
|
|||
|
|
StatementLineRead:
|
|||
|
|
type: object
|
|||
|
|
required: [id, sourceType, sourceId, sourceVersion, feeItemName, amount, currency]
|
|||
|
|
properties:
|
|||
|
|
id: {$ref: '#/components/schemas/Id'}
|
|||
|
|
sourceType: {type: string}
|
|||
|
|
sourceId: {$ref: '#/components/schemas/Id'}
|
|||
|
|
sourceVersion: {type: integer, minimum: 1}
|
|||
|
|
orderId: {$ref: '#/components/schemas/Id'}
|
|||
|
|
inboundId: {$ref: '#/components/schemas/Id'}
|
|||
|
|
feeItemCode: {type: string}
|
|||
|
|
feeItemName: {type: string}
|
|||
|
|
amount: {$ref: '#/components/schemas/Money'}
|
|||
|
|
currency: {type: string, enum: [CNY]}
|
|||
|
|
StatementDetailRead:
|
|||
|
|
type: object
|
|||
|
|
required: [statement, lines]
|
|||
|
|
properties:
|
|||
|
|
statement: {$ref: '#/components/schemas/StatementRead'}
|
|||
|
|
lines:
|
|||
|
|
type: array
|
|||
|
|
items: {$ref: '#/components/schemas/StatementLineRead'}
|
|||
|
|
ReceivableSettlementRead:
|
|||
|
|
type: object
|
|||
|
|
required: [id, customerId, settlementNo, billDate, dueDate, receivableAmount, receivedAmount, outstandingAmount, currency, status, version]
|
|||
|
|
properties:
|
|||
|
|
id: {$ref: '#/components/schemas/Id'}
|
|||
|
|
customerId: {$ref: '#/components/schemas/Id'}
|
|||
|
|
settlementNo: {type: string}
|
|||
|
|
billDate: {type: string, format: date}
|
|||
|
|
dueDate: {type: string, format: date}
|
|||
|
|
receivableAmount: {$ref: '#/components/schemas/Money'}
|
|||
|
|
receivedAmount: {$ref: '#/components/schemas/Money'}
|
|||
|
|
outstandingAmount: {$ref: '#/components/schemas/Money'}
|
|||
|
|
currency: {type: string, enum: [CNY]}
|
|||
|
|
status: {type: string}
|
|||
|
|
version: {type: integer, minimum: 0}
|
|||
|
|
PayableSettlementRead:
|
|||
|
|
type: object
|
|||
|
|
required: [id, customerId, settlementNo, costType, feeItemName, payableAmount, paidAmount, outstandingAmount, currency, status, createdAt, version]
|
|||
|
|
properties:
|
|||
|
|
id: {$ref: '#/components/schemas/Id'}
|
|||
|
|
customerId: {$ref: '#/components/schemas/Id'}
|
|||
|
|
settlementNo: {type: string}
|
|||
|
|
costType: {type: string, enum: [SINGLE_ORDER, CONTAINER_SHARED]}
|
|||
|
|
orderId: {$ref: '#/components/schemas/Id'}
|
|||
|
|
inboundId: {$ref: '#/components/schemas/Id'}
|
|||
|
|
containerId: {$ref: '#/components/schemas/Id'}
|
|||
|
|
supplierName: {type: string}
|
|||
|
|
feeItemName: {type: string}
|
|||
|
|
payableAmount: {$ref: '#/components/schemas/Money'}
|
|||
|
|
paidAmount: {$ref: '#/components/schemas/Money'}
|
|||
|
|
outstandingAmount: {$ref: '#/components/schemas/Money'}
|
|||
|
|
currency: {type: string, enum: [CNY]}
|
|||
|
|
status: {type: string}
|
|||
|
|
createdAt: {type: string, format: date-time}
|
|||
|
|
version: {type: integer, minimum: 0}
|
|||
|
|
CreateReconciliationRequest:
|
|||
|
|
type: object
|
|||
|
|
required: [customerId, generationMode, periodStart, periodEnd]
|
|||
|
|
properties:
|
|||
|
|
customerId: {$ref: '#/components/schemas/Id'}
|
|||
|
|
generationMode: {type: string, enum: [BY_CUTOFF, SELECTED]}
|
|||
|
|
feeSourceIds:
|
|||
|
|
type: array
|
|||
|
|
uniqueItems: true
|
|||
|
|
items: {$ref: '#/components/schemas/Id'}
|
|||
|
|
periodStart: {type: string, format: date}
|
|||
|
|
periodEnd: {type: string, format: date}
|
|||
|
|
remark: {type: string, maxLength: 500}
|
|||
|
|
DocumentActionRequest:
|
|||
|
|
type: object
|
|||
|
|
required: [action, reason, expectedVersion]
|
|||
|
|
properties:
|
|||
|
|
action: {type: string, enum: [SUBMIT, APPROVE, REJECT, VOID]}
|
|||
|
|
reason: {type: string, minLength: 1, maxLength: 500}
|
|||
|
|
expectedVersion: {type: integer, minimum: 0}
|
|||
|
|
SettlementSummary:
|
|||
|
|
type: object
|
|||
|
|
required: [settlementId, settlementNo, direction, currency, totalAmount, paidAmount, outstandingAmount, generatedDate, dueDate, paymentStatus, status, version]
|
|||
|
|
properties:
|
|||
|
|
settlementId: {$ref: '#/components/schemas/Id'}
|
|||
|
|
settlementNo: {type: string}
|
|||
|
|
direction: {$ref: '#/components/schemas/FeeDirection'}
|
|||
|
|
customerId: {$ref: '#/components/schemas/Id'}
|
|||
|
|
customerName: {type: string}
|
|||
|
|
supplierId: {$ref: '#/components/schemas/Id'}
|
|||
|
|
supplierName: {type: string}
|
|||
|
|
reconciliationStatementId: {$ref: '#/components/schemas/Id'}
|
|||
|
|
businessPeriod: {type: string}
|
|||
|
|
currency: {type: string, enum: [CNY]}
|
|||
|
|
totalAmount: {$ref: '#/components/schemas/Money'}
|
|||
|
|
paidAmount: {$ref: '#/components/schemas/Money'}
|
|||
|
|
outstandingAmount: {$ref: '#/components/schemas/Money'}
|
|||
|
|
generatedDate: {type: string, format: date}
|
|||
|
|
dueDate: {type: string, format: date}
|
|||
|
|
paymentStatus: {$ref: '#/components/schemas/PaymentStatus'}
|
|||
|
|
status: {$ref: '#/components/schemas/SettlementStatus'}
|
|||
|
|
version: {type: integer, minimum: 0}
|
|||
|
|
SettlementDetail:
|
|||
|
|
allOf:
|
|||
|
|
- $ref: '#/components/schemas/SettlementSummary'
|
|||
|
|
- type: object
|
|||
|
|
required: [lines, transactions]
|
|||
|
|
properties:
|
|||
|
|
lines:
|
|||
|
|
type: array
|
|||
|
|
items: {$ref: '#/components/schemas/FeeSource'}
|
|||
|
|
transactions:
|
|||
|
|
type: array
|
|||
|
|
items: {$ref: '#/components/schemas/SettlementTransaction'}
|
|||
|
|
CreateReceivableSettlementRequest:
|
|||
|
|
type: object
|
|||
|
|
required: [reconciliationStatementId]
|
|||
|
|
properties:
|
|||
|
|
reconciliationStatementId: {$ref: '#/components/schemas/Id'}
|
|||
|
|
CreatePayableSettlementRequest:
|
|||
|
|
type: object
|
|||
|
|
required: [supplierId, feeSourceIds, dueDate]
|
|||
|
|
properties:
|
|||
|
|
supplierId: {$ref: '#/components/schemas/Id'}
|
|||
|
|
feeSourceIds:
|
|||
|
|
type: array
|
|||
|
|
minItems: 1
|
|||
|
|
uniqueItems: true
|
|||
|
|
items: {$ref: '#/components/schemas/Id'}
|
|||
|
|
dueDate: {type: string, format: date}
|
|||
|
|
SettlementTransaction:
|
|||
|
|
type: object
|
|||
|
|
required: [transactionId, transactionType, transactionDate, amount, method, createdBy, createdAt]
|
|||
|
|
properties:
|
|||
|
|
transactionId: {$ref: '#/components/schemas/Id'}
|
|||
|
|
transactionType: {type: string, enum: [RECEIPT, PAYMENT]}
|
|||
|
|
transactionDate: {type: string, format: date}
|
|||
|
|
amount: {$ref: '#/components/schemas/Money'}
|
|||
|
|
method: {type: string, enum: [BANK_TRANSFER, CASH, OTHER]}
|
|||
|
|
referenceNo: {type: string}
|
|||
|
|
createdBy: {$ref: '#/components/schemas/Id'}
|
|||
|
|
createdAt: {type: string, format: date-time}
|
|||
|
|
remark: {type: string}
|
|||
|
|
ReceiptAllocationRequest:
|
|||
|
|
type: object
|
|||
|
|
required: [settlementId, amount]
|
|||
|
|
properties:
|
|||
|
|
settlementId: {$ref: '#/components/schemas/Id'}
|
|||
|
|
amount: {$ref: '#/components/schemas/Money'}
|
|||
|
|
CreateReceiptRequest:
|
|||
|
|
type: object
|
|||
|
|
required: [customerId, receivedDate, amount, paymentMethod, voucherFileIds, allocations]
|
|||
|
|
properties:
|
|||
|
|
customerId: {$ref: '#/components/schemas/Id'}
|
|||
|
|
receivedDate: {type: string, format: date}
|
|||
|
|
amount: {$ref: '#/components/schemas/Money'}
|
|||
|
|
currency: {type: string, enum: [CNY], default: CNY}
|
|||
|
|
paymentMethod: {type: string, enum: [BANK_TRANSFER, CASH, OTHER]}
|
|||
|
|
voucherFileIds:
|
|||
|
|
type: array
|
|||
|
|
minItems: 1
|
|||
|
|
uniqueItems: true
|
|||
|
|
items: {$ref: '#/components/schemas/Id'}
|
|||
|
|
allocations:
|
|||
|
|
type: array
|
|||
|
|
minItems: 1
|
|||
|
|
items: {$ref: '#/components/schemas/ReceiptAllocationRequest'}
|
|||
|
|
remark: {type: string, maxLength: 500}
|
|||
|
|
ClientReceiptRead:
|
|||
|
|
type: object
|
|||
|
|
required: [id, receiptNo, receivedAmount, receivedAt, paymentMethod, currency, status, allocations]
|
|||
|
|
properties:
|
|||
|
|
id: {$ref: '#/components/schemas/Id'}
|
|||
|
|
receiptNo: {type: string}
|
|||
|
|
receivedAmount: {$ref: '#/components/schemas/Money'}
|
|||
|
|
receivedAt: {type: string, format: date-time}
|
|||
|
|
paymentMethod: {type: string, enum: [BANK_TRANSFER, CASH, OTHER]}
|
|||
|
|
currency: {type: string, enum: [CNY]}
|
|||
|
|
status: {type: string, enum: [CONFIRMED]}
|
|||
|
|
allocations:
|
|||
|
|
type: array
|
|||
|
|
items: {$ref: '#/components/schemas/ClientReceiptAllocationRead'}
|
|||
|
|
PlatformReceiptRead:
|
|||
|
|
type: object
|
|||
|
|
required: [id, customerId, receiptNo, receivedAmount, receivedAt, paymentMethod, voucherFileIds, currency, status, version, allocations]
|
|||
|
|
properties:
|
|||
|
|
id: {$ref: '#/components/schemas/Id'}
|
|||
|
|
customerId: {$ref: '#/components/schemas/Id'}
|
|||
|
|
receiptNo: {type: string}
|
|||
|
|
receivedAmount: {$ref: '#/components/schemas/Money'}
|
|||
|
|
receivedAt: {type: string, format: date-time}
|
|||
|
|
paymentMethod: {type: string, enum: [BANK_TRANSFER, CASH, OTHER]}
|
|||
|
|
voucherNo: {type: string}
|
|||
|
|
voucherFileIds:
|
|||
|
|
type: array
|
|||
|
|
items: {type: string}
|
|||
|
|
currency: {type: string, enum: [CNY]}
|
|||
|
|
status: {type: string}
|
|||
|
|
remark: {type: string}
|
|||
|
|
version: {type: integer, minimum: 0}
|
|||
|
|
allocations:
|
|||
|
|
type: array
|
|||
|
|
items: {$ref: '#/components/schemas/ClientReceiptAllocationRead'}
|
|||
|
|
ClientReceiptAllocationRead:
|
|||
|
|
type: object
|
|||
|
|
required: [billId, billNo, appliedAmount]
|
|||
|
|
properties:
|
|||
|
|
billId: {$ref: '#/components/schemas/Id'}
|
|||
|
|
billNo: {type: string}
|
|||
|
|
appliedAmount: {$ref: '#/components/schemas/Money'}
|
|||
|
|
ResourceResult:
|
|||
|
|
type: object
|
|||
|
|
required: [id, resourceNo, status]
|
|||
|
|
properties:
|
|||
|
|
id: {$ref: '#/components/schemas/Id'}
|
|||
|
|
resourceNo: {type: string}
|
|||
|
|
status: {type: string}
|
|||
|
|
version: {type: integer, minimum: 0}
|
|||
|
|
CreateSettlementPaymentRequest:
|
|||
|
|
type: object
|
|||
|
|
required: [transactionDate, amount, method, voucherFileIds]
|
|||
|
|
properties:
|
|||
|
|
transactionDate: {type: string, format: date}
|
|||
|
|
amount: {$ref: '#/components/schemas/Money'}
|
|||
|
|
method: {type: string, enum: [BANK_TRANSFER, CASH, OTHER]}
|
|||
|
|
referenceNo: {type: string}
|
|||
|
|
voucherFileIds:
|
|||
|
|
type: array
|
|||
|
|
minItems: 1
|
|||
|
|
uniqueItems: true
|
|||
|
|
items: {$ref: '#/components/schemas/Id'}
|
|||
|
|
remark: {type: string, maxLength: 500}
|
|||
|
|
ErrorEnvelope:
|
|||
|
|
allOf:
|
|||
|
|
- $ref: '#/components/schemas/TraceMeta'
|
|||
|
|
- type: object
|
|||
|
|
required: [code, message]
|
|||
|
|
properties:
|
|||
|
|
code: {type: string}
|
|||
|
|
message: {type: string}
|
|||
|
|
FeeSourceEventResultEnvelope:
|
|||
|
|
allOf:
|
|||
|
|
- $ref: '#/components/schemas/TraceMeta'
|
|||
|
|
- type: object
|
|||
|
|
required: [code, message, data]
|
|||
|
|
properties:
|
|||
|
|
code: {type: string, example: '200'}
|
|||
|
|
message: {type: string}
|
|||
|
|
data: {$ref: '#/components/schemas/FeeSourceEventResult'}
|
|||
|
|
AccountPageEnvelope:
|
|||
|
|
allOf:
|
|||
|
|
- $ref: '#/components/schemas/TraceMeta'
|
|||
|
|
- type: object
|
|||
|
|
required: [code, message, data, page]
|
|||
|
|
properties:
|
|||
|
|
code: {type: string, example: '200'}
|
|||
|
|
message: {type: string}
|
|||
|
|
data: {type: array, items: {$ref: '#/components/schemas/AccountSummary'}}
|
|||
|
|
page: {$ref: '#/components/schemas/PageMeta'}
|
|||
|
|
AccountDetailEnvelope:
|
|||
|
|
allOf:
|
|||
|
|
- $ref: '#/components/schemas/TraceMeta'
|
|||
|
|
- type: object
|
|||
|
|
required: [code, message, data]
|
|||
|
|
properties:
|
|||
|
|
code: {type: string, example: '200'}
|
|||
|
|
message: {type: string}
|
|||
|
|
data: {$ref: '#/components/schemas/AccountDetail'}
|
|||
|
|
LedgerPageEnvelope:
|
|||
|
|
allOf:
|
|||
|
|
- $ref: '#/components/schemas/TraceMeta'
|
|||
|
|
- type: object
|
|||
|
|
required: [code, message, data, page]
|
|||
|
|
properties:
|
|||
|
|
code: {type: string, example: '200'}
|
|||
|
|
message: {type: string}
|
|||
|
|
data: {type: array, items: {$ref: '#/components/schemas/LedgerEntry'}}
|
|||
|
|
page: {$ref: '#/components/schemas/PageMeta'}
|
|||
|
|
FeeSourcePageEnvelope:
|
|||
|
|
allOf:
|
|||
|
|
- $ref: '#/components/schemas/TraceMeta'
|
|||
|
|
- type: object
|
|||
|
|
required: [code, message, data, page]
|
|||
|
|
properties:
|
|||
|
|
code: {type: string, example: '200'}
|
|||
|
|
message: {type: string}
|
|||
|
|
data: {type: array, items: {$ref: '#/components/schemas/FeeSource'}}
|
|||
|
|
page: {$ref: '#/components/schemas/PageMeta'}
|
|||
|
|
FeeSourceDetailEnvelope:
|
|||
|
|
allOf:
|
|||
|
|
- $ref: '#/components/schemas/TraceMeta'
|
|||
|
|
- type: object
|
|||
|
|
required: [code, message, data]
|
|||
|
|
properties:
|
|||
|
|
code: {type: string, example: '200'}
|
|||
|
|
message: {type: string}
|
|||
|
|
data: {$ref: '#/components/schemas/FeeSourceDetail'}
|
|||
|
|
ReconciliationPageEnvelope:
|
|||
|
|
allOf:
|
|||
|
|
- $ref: '#/components/schemas/TraceMeta'
|
|||
|
|
- type: object
|
|||
|
|
required: [code, message, data, page]
|
|||
|
|
properties:
|
|||
|
|
code: {type: string, example: '200'}
|
|||
|
|
message: {type: string}
|
|||
|
|
data: {type: array, items: {$ref: '#/components/schemas/ReconciliationSummary'}}
|
|||
|
|
page: {$ref: '#/components/schemas/PageMeta'}
|
|||
|
|
ReconciliationDetailEnvelope:
|
|||
|
|
allOf:
|
|||
|
|
- $ref: '#/components/schemas/TraceMeta'
|
|||
|
|
- type: object
|
|||
|
|
required: [code, message, data]
|
|||
|
|
properties:
|
|||
|
|
code: {type: string, example: '200'}
|
|||
|
|
message: {type: string}
|
|||
|
|
data: {$ref: '#/components/schemas/ReconciliationDetail'}
|
|||
|
|
SettlementPageEnvelope:
|
|||
|
|
allOf:
|
|||
|
|
- $ref: '#/components/schemas/TraceMeta'
|
|||
|
|
- type: object
|
|||
|
|
required: [code, message, data, page]
|
|||
|
|
properties:
|
|||
|
|
code: {type: string, example: '200'}
|
|||
|
|
message: {type: string}
|
|||
|
|
data: {type: array, items: {$ref: '#/components/schemas/SettlementSummary'}}
|
|||
|
|
page: {$ref: '#/components/schemas/PageMeta'}
|
|||
|
|
SettlementDetailEnvelope:
|
|||
|
|
allOf:
|
|||
|
|
- $ref: '#/components/schemas/TraceMeta'
|
|||
|
|
- type: object
|
|||
|
|
required: [code, message, data]
|
|||
|
|
properties:
|
|||
|
|
code: {type: string, example: '200'}
|
|||
|
|
message: {type: string}
|
|||
|
|
data: {$ref: '#/components/schemas/SettlementDetail'}
|
|||
|
|
CustomerAccountReadEnvelope:
|
|||
|
|
allOf:
|
|||
|
|
- $ref: '#/components/schemas/TraceMeta'
|
|||
|
|
- type: object
|
|||
|
|
required: [code, message, data]
|
|||
|
|
properties:
|
|||
|
|
code: {type: string, example: '200'}
|
|||
|
|
message: {type: string}
|
|||
|
|
data: {$ref: '#/components/schemas/CustomerAccountRead'}
|
|||
|
|
FeePoolReadEnvelope:
|
|||
|
|
allOf:
|
|||
|
|
- $ref: '#/components/schemas/TraceMeta'
|
|||
|
|
- type: object
|
|||
|
|
required: [code, message, data]
|
|||
|
|
properties:
|
|||
|
|
code: {type: string, example: '200'}
|
|||
|
|
message: {type: string}
|
|||
|
|
data: {type: array, items: {$ref: '#/components/schemas/FeePoolItemRead'}}
|
|||
|
|
StatementListReadEnvelope:
|
|||
|
|
allOf:
|
|||
|
|
- $ref: '#/components/schemas/TraceMeta'
|
|||
|
|
- type: object
|
|||
|
|
required: [code, message, data]
|
|||
|
|
properties:
|
|||
|
|
code: {type: string, example: '200'}
|
|||
|
|
message: {type: string}
|
|||
|
|
data: {type: array, items: {$ref: '#/components/schemas/StatementRead'}}
|
|||
|
|
StatementDetailReadEnvelope:
|
|||
|
|
allOf:
|
|||
|
|
- $ref: '#/components/schemas/TraceMeta'
|
|||
|
|
- type: object
|
|||
|
|
required: [code, message, data]
|
|||
|
|
properties:
|
|||
|
|
code: {type: string, example: '200'}
|
|||
|
|
message: {type: string}
|
|||
|
|
data: {$ref: '#/components/schemas/StatementDetailRead'}
|
|||
|
|
ReceivableSettlementListReadEnvelope:
|
|||
|
|
allOf:
|
|||
|
|
- $ref: '#/components/schemas/TraceMeta'
|
|||
|
|
- type: object
|
|||
|
|
required: [code, message, data]
|
|||
|
|
properties:
|
|||
|
|
code: {type: string, example: '200'}
|
|||
|
|
message: {type: string}
|
|||
|
|
data: {type: array, items: {$ref: '#/components/schemas/ReceivableSettlementRead'}}
|
|||
|
|
PayableSettlementListReadEnvelope:
|
|||
|
|
allOf:
|
|||
|
|
- $ref: '#/components/schemas/TraceMeta'
|
|||
|
|
- type: object
|
|||
|
|
required: [code, message, data]
|
|||
|
|
properties:
|
|||
|
|
code: {type: string, example: '200'}
|
|||
|
|
message: {type: string}
|
|||
|
|
data: {type: array, items: {$ref: '#/components/schemas/PayableSettlementRead'}}
|
|||
|
|
ClientReceiptListReadEnvelope:
|
|||
|
|
allOf:
|
|||
|
|
- $ref: '#/components/schemas/TraceMeta'
|
|||
|
|
- type: object
|
|||
|
|
required: [code, message, data]
|
|||
|
|
properties:
|
|||
|
|
code: {type: string, example: '200'}
|
|||
|
|
message: {type: string}
|
|||
|
|
data: {type: array, items: {$ref: '#/components/schemas/ClientReceiptRead'}}
|
|||
|
|
PlatformReceiptListReadEnvelope:
|
|||
|
|
allOf:
|
|||
|
|
- $ref: '#/components/schemas/TraceMeta'
|
|||
|
|
- type: object
|
|||
|
|
required: [code, message, data]
|
|||
|
|
properties:
|
|||
|
|
code: {type: string, example: '200'}
|
|||
|
|
message: {type: string}
|
|||
|
|
data: {type: array, items: {$ref: '#/components/schemas/PlatformReceiptRead'}}
|
|||
|
|
ResourceResultEnvelope:
|
|||
|
|
allOf:
|
|||
|
|
- $ref: '#/components/schemas/TraceMeta'
|
|||
|
|
- type: object
|
|||
|
|
required: [code, message, data]
|
|||
|
|
properties:
|
|||
|
|
code: {type: string, example: '200'}
|
|||
|
|
message: {type: string}
|
|||
|
|
data: {$ref: '#/components/schemas/ResourceResult'}
|
|||
|
|
responses:
|
|||
|
|
AccountPageResponse:
|
|||
|
|
description: 客户账户派生汇总分页。
|
|||
|
|
content: {application/json: {schema: {$ref: '#/components/schemas/AccountPageEnvelope'}}}
|
|||
|
|
AccountDetailResponse:
|
|||
|
|
description: 客户账户派生详情。
|
|||
|
|
content: {application/json: {schema: {$ref: '#/components/schemas/AccountDetailEnvelope'}}}
|
|||
|
|
LedgerPageResponse:
|
|||
|
|
description: 客户财务派生流水分页。
|
|||
|
|
content: {application/json: {schema: {$ref: '#/components/schemas/LedgerPageEnvelope'}}}
|
|||
|
|
FeeSourcePageResponse:
|
|||
|
|
description: 费用来源分页。
|
|||
|
|
content: {application/json: {schema: {$ref: '#/components/schemas/FeeSourcePageEnvelope'}}}
|
|||
|
|
FeeSourceDetailResponse:
|
|||
|
|
description: 费用来源详情。
|
|||
|
|
content: {application/json: {schema: {$ref: '#/components/schemas/FeeSourceDetailEnvelope'}}}
|
|||
|
|
ReconciliationPageResponse:
|
|||
|
|
description: 客户对账单分页。
|
|||
|
|
content: {application/json: {schema: {$ref: '#/components/schemas/ReconciliationPageEnvelope'}}}
|
|||
|
|
ReconciliationDetailResponse:
|
|||
|
|
description: 客户对账单详情。
|
|||
|
|
content: {application/json: {schema: {$ref: '#/components/schemas/ReconciliationDetailEnvelope'}}}
|
|||
|
|
SettlementPageResponse:
|
|||
|
|
description: 结算单分页。
|
|||
|
|
content: {application/json: {schema: {$ref: '#/components/schemas/SettlementPageEnvelope'}}}
|
|||
|
|
SettlementDetailResponse:
|
|||
|
|
description: 结算单详情。
|
|||
|
|
content: {application/json: {schema: {$ref: '#/components/schemas/SettlementDetailEnvelope'}}}
|
|||
|
|
CustomerAccountReadResponse:
|
|||
|
|
description: 当前固定 DTO 客户账户及流水。
|
|||
|
|
content: {application/json: {schema: {$ref: '#/components/schemas/CustomerAccountReadEnvelope'}}}
|
|||
|
|
FeePoolReadResponse:
|
|||
|
|
description: 当前固定 DTO 客户应收应付费用池。
|
|||
|
|
content: {application/json: {schema: {$ref: '#/components/schemas/FeePoolReadEnvelope'}}}
|
|||
|
|
StatementListReadResponse:
|
|||
|
|
description: 当前固定 DTO 客户对账单列表。
|
|||
|
|
content: {application/json: {schema: {$ref: '#/components/schemas/StatementListReadEnvelope'}}}
|
|||
|
|
StatementDetailReadResponse:
|
|||
|
|
description: 当前固定 DTO 客户对账单详情。
|
|||
|
|
content: {application/json: {schema: {$ref: '#/components/schemas/StatementDetailReadEnvelope'}}}
|
|||
|
|
ReceivableSettlementListReadResponse:
|
|||
|
|
description: 当前固定 DTO 应收结算单列表。
|
|||
|
|
content: {application/json: {schema: {$ref: '#/components/schemas/ReceivableSettlementListReadEnvelope'}}}
|
|||
|
|
PayableSettlementListReadResponse:
|
|||
|
|
description: 当前固定 DTO 应付结算单列表。
|
|||
|
|
content: {application/json: {schema: {$ref: '#/components/schemas/PayableSettlementListReadEnvelope'}}}
|
|||
|
|
ClientReceiptListReadResponse:
|
|||
|
|
description: 客户专用收款 DTO 列表，不含凭证和内部字段。
|
|||
|
|
content: {application/json: {schema: {$ref: '#/components/schemas/ClientReceiptListReadEnvelope'}}}
|
|||
|
|
PlatformReceiptListReadResponse:
|
|||
|
|
description: 平台专用收款 DTO 列表，包含凭证引用和账单分配。
|
|||
|
|
content: {application/json: {schema: {$ref: '#/components/schemas/PlatformReceiptListReadEnvelope'}}}
|
|||
|
|
ResourceResultResponse:
|
|||
|
|
description: 写操作资源结果。
|
|||
|
|
content: {application/json: {schema: {$ref: '#/components/schemas/ResourceResultEnvelope'}}}
|
|||
|
|
BusinessError:
|
|||
|
|
description: 稳定业务错误。
|
|||
|
|
content: {application/json: {schema: {$ref: '#/components/schemas/ErrorEnvelope'}}}
|