html/docs
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

优化

Browse Source
This commit is contained in:
ouyangxq
2026-08-11 10:45:57 +08:00
parent f5a0c81286
commit 6041a6d976
4 changed files with 123 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files
财务管理/openapi/finance-f1-manual-v1.yaml
+77 -29
View File
@@ -6,18 +6,31 @@ info:
servers:
- url: /api
paths:
/platform/finance/v1/customers/{tenantId}/terms:
get:
summary: 查询客户账期
x-permission: platform:finance:customer-terms:view
security: [{platformFinance: []}]
parameters: [{$ref: '#/components/parameters/TenantId'}]
responses: {'200': {$ref: '#/components/responses/SuccessObject'}, '403': {$ref: '#/components/responses/BusinessError'}}
put:
summary: 保存客户账期
x-permission: platform:finance:customer-terms:update
security: [{platformFinance: []}]
parameters: [{$ref: '#/components/parameters/TenantId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/CustomerTermsRequest'}}}}
responses: {'200': {$ref: '#/components/responses/SuccessObject'}, '403': {$ref: '#/components/responses/BusinessError'}}
/platform/finance/v1/bills:
get:
summary: 查询平台账单
x-permission: platform:finance:bill:view
security: [{platformFinance: []}]
parameters:
- {$ref: '#/components/parameters/CustomerId'}
- {name: status, in: query, schema: {$ref: '#/components/schemas/BillStatus'}}
- {name: page, in: query, schema: {type: integer, minimum: 1, default: 1}}
- {name: pageSize, in: query, schema: {type: integer, minimum: 1, maximum: 100, default: 20}}
responses: {'200': {$ref: '#/components/responses/SuccessPage'}}
- {$ref: '#/components/parameters/RequiredCustomerId'}
responses: {'200': {$ref: '#/components/responses/SuccessList'}}
post:
summary: 创建账单草稿
x-permission: platform:finance:bill:create
security: [{platformFinance: []}]
parameters: [{$ref: '#/components/parameters/IdempotencyKey'}]
requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/CreateBillRequest'}}}}
@@ -25,11 +38,13 @@ paths:
/platform/finance/v1/bills/{billId}:
get:
summary: 查询平台账单详情
x-permission: platform:finance:bill:view
security: [{platformFinance: []}]
parameters: [{$ref: '#/components/parameters/BillId'}]
responses: {'200': {$ref: '#/components/responses/SuccessBill'}}
put:
summary: 更新账单草稿
x-permission: platform:finance:bill:update
security: [{platformFinance: []}]
parameters: [{$ref: '#/components/parameters/BillId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/UpdateBillRequest'}}}}
@@ -37,6 +52,7 @@ paths:
/platform/finance/v1/bills/{billId}/issue:
post:
summary: 出账并冻结账单
x-permission: platform:finance:bill:issue
security: [{platformFinance: []}]
parameters: [{$ref: '#/components/parameters/BillId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/VersionRequest'}}}}
@@ -44,6 +60,7 @@ paths:
/platform/finance/v1/bills/{billId}/adjust:
post:
summary: 出账后调整并生成新版本
x-permission: platform:finance:bill:adjust
security: [{platformFinance: []}]
parameters: [{$ref: '#/components/parameters/BillId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/AdjustBillRequest'}}}}
@@ -51,6 +68,7 @@ paths:
/platform/finance/v1/bills/{billId}/void:
post:
summary: 作废账单
x-permission: platform:finance:bill:void
security: [{platformFinance: []}]
parameters: [{$ref: '#/components/parameters/BillId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/ReasonRequest'}}}}
@@ -58,73 +76,92 @@ paths:
/platform/finance/v1/receipts:
post:
summary: 人工登记收款并分配账单
x-permission: platform:finance:receipt:create
security: [{platformFinance: []}]
parameters: [{$ref: '#/components/parameters/IdempotencyKey'}]
requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/CreateReceiptRequest'}}}}
responses: {'200': {$ref: '#/components/responses/SuccessReceipt'}}
get:
summary: 查询收款记录
x-permission: platform:finance:receipt:view
security: [{platformFinance: []}]
responses: {'200': {$ref: '#/components/responses/SuccessPage'}}
parameters: [{$ref: '#/components/parameters/OptionalCustomerId'}]
responses: {'200': {$ref: '#/components/responses/SuccessList'}}
/platform/finance/v1/cost-entries:
post:
summary: 人工登记单票或整柜成本
x-permission: platform:finance:cost:create
security: [{platformFinance: []}]
parameters: [{$ref: '#/components/parameters/IdempotencyKey'}]
requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/CreateCostRequest'}}}}
responses: {'200': {$ref: '#/components/responses/SuccessCost'}}
get:
summary: 查询成本记录
x-permission: platform:finance:cost:view
security: [{platformFinance: []}]
responses: {'200': {$ref: '#/components/responses/SuccessPage'}}
parameters: [{$ref: '#/components/parameters/OptionalCustomerId'}]
responses: {'200': {$ref: '#/components/responses/SuccessList'}}
/client/finance/v1/bills:
get:
summary: 客户只读查询账单
x-permission: merchant:finance:statement:list
security: [{customerFinanceRead: []}]
responses: {'200': {$ref: '#/components/responses/SuccessPage'}, '403': {$ref: '#/components/responses/BusinessError'}}
responses: {'200': {$ref: '#/components/responses/SuccessList'}, '403': {$ref: '#/components/responses/BusinessError'}}
/client/finance/v1/bills/{billId}:
get:
summary: 客户只读查看账单详情
x-permission: merchant:finance:statement:view
security: [{customerFinanceRead: []}]
parameters: [{$ref: '#/components/parameters/BillId'}]
responses: {'200': {$ref: '#/components/responses/SuccessBill'}, '403': {$ref: '#/components/responses/BusinessError'}}
/client/finance/v1/receipts:
get:
summary: 客户只读查询收款记录
x-permission: merchant:finance:statement:view
security: [{customerFinanceRead: []}]
responses: {'200': {$ref: '#/components/responses/SuccessPage'}, '403': {$ref: '#/components/responses/BusinessError'}}
responses: {'200': {$ref: '#/components/responses/SuccessList'}, '403': {$ref: '#/components/responses/BusinessError'}}
components:
securitySchemes:
platformFinance: {type: http, scheme: bearer}
customerFinanceRead: {type: http, scheme: bearer}
parameters:
BillId: {name: billId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
CustomerId: {name: customerId, in: query, required: false, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
TenantId: {name: tenantId, in: path, required: true, description: 后端兼容字段，对应产品中的客户 ID, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
RequiredCustomerId: {name: customerId, in: query, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
OptionalCustomerId: {name: customerId, in: query, required: false, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
IdempotencyKey: {name: Idempotency-Key, in: header, required: true, schema: {type: string, maxLength: 128}}
schemas:
CustomerTermsRequest:
type: object
required: [creditDays]
properties:
customerName: {type: string, maxLength: 200, description: 客户名称快照；未传时由服务端按客户主数据补齐}
creditDays: {type: integer, minimum: 0, maximum: 3650, default: 30, description: 自然日账期}
CreateBillRequest:
type: object
required: [customerId, billDate, lines]
properties:
customerId: {type: string}
customerId: {type: string, pattern: '^[1-9][0-9]*$'}
billDate: {type: string, format: date}
lines: {type: array, minItems: 1, items: {$ref: '#/components/schemas/BillLineInput'}}
UpdateBillRequest:
allOf:
- {$ref: '#/components/schemas/CreateBillRequest'}
- type: object
required: [expectedVersion]
properties: {expectedVersion: {type: integer, minimum: 0}}
type: object
required: [customerId, billDate, expectedVersion, lines]
properties:
customerId: {type: string, pattern: '^[1-9][0-9]*$'}
billDate: {type: string, format: date}
expectedVersion: {type: integer, minimum: 0}
lines: {type: array, minItems: 1, items: {$ref: '#/components/schemas/BillLineInput'}}
BillLineInput:
type: object
required: [sourceFeeId, sourceFeeVersion, amount]
properties:
sourceFeeId: {type: string}
sourceFeeId: {type: string, pattern: '^[1-9][0-9]*$'}
sourceFeeVersion: {type: integer, minimum: 1}
orderId: {type: string}
inboundId: {type: string}
orderId: {type: string, pattern: '^[1-9][0-9]*$'}
inboundId: {type: string, pattern: '^[1-9][0-9]*$'}
feeItemName: {type: string}
amount: {type: number, format: double, minimum: 0}
amount: {type: number, minimum: 0, multipleOf: 0.000001}
VersionRequest:
type: object
required: [expectedVersion]
@@ -145,9 +182,9 @@ components:
type: object
required: [customerId, receivedDate, amount, paymentMethod, voucherFileIds, allocations]
properties:
customerId: {type: string}
customerId: {type: string, pattern: '^[1-9][0-9]*$'}
receivedDate: {type: string, format: date}
amount: {type: number, format: double, minimum: 0, exclusiveMinimum: true}
amount: {type: number, minimum: 0, exclusiveMinimum: true, multipleOf: 0.000001}
currency: {type: string, enum: [CNY], default: CNY}
paymentMethod: {type: string, enum: [BANK_TRANSFER, CASH, OTHER]}
voucherFileIds: {type: array, minItems: 1, items: {type: string}}
@@ -168,17 +205,19 @@ components:
type: object
required: [billId, amount]
properties:
billId: {type: string}
amount: {type: number, format: double, minimum: 0, exclusiveMinimum: true}
billId: {type: string, pattern: '^[1-9][0-9]*$'}
amount: {type: number, minimum: 0, exclusiveMinimum: true, multipleOf: 0.000001}
CreateCostRequest:
type: object
required: [costType, amount, expenseName, voucherFileIds]
description: SINGLE_ORDER 必须提供 orderId；CONTAINER_SHARED 必须提供 containerId，并按柜内有效票体积分摊。
required: [customerId, costType, amount, expenseName, voucherFileIds]
properties:
customerId: {type: string, pattern: '^[1-9][0-9]*$'}
costType: {type: string, enum: [SINGLE_ORDER, CONTAINER_SHARED]}
orderId: {type: string}
containerId: {type: string}
orderId: {type: string, pattern: '^[1-9][0-9]*$'}
containerId: {type: string, pattern: '^[1-9][0-9]*$'}
expenseName: {type: string, minLength: 1, maxLength: 100}
amount: {type: number, format: double, minimum: 0, exclusiveMinimum: true}
amount: {type: number, minimum: 0, exclusiveMinimum: true, multipleOf: 0.000001}
currency: {type: string, enum: [CNY], default: CNY}
voucherFileIds: {type: array, minItems: 1, items: {type: string}}
remark: {type: string, maxLength: 500}
@@ -191,6 +230,14 @@ components:
message: {type: string}
data: {type: object, additionalProperties: true}
requestId: {type: string}
ApiListEnvelope:
type: object
required: [code, message, data]
properties:
code: {type: string, example: '200'}
message: {type: string}
data: {type: array, items: {type: object, additionalProperties: true}}
requestId: {type: string}
ErrorEnvelope:
type: object
required: [code, message]
@@ -199,5 +246,6 @@ components:
SuccessBill: {description: Bill result, content: {application/json: {schema: {$ref: '#/components/schemas/ApiEnvelope'}}}}
SuccessReceipt: {description: Receipt result, content: {application/json: {schema: {$ref: '#/components/schemas/ApiEnvelope'}}}}
SuccessCost: {description: Cost result, content: {application/json: {schema: {$ref: '#/components/schemas/ApiEnvelope'}}}}
SuccessPage: {description: Paged result, content: {application/json: {schema: {$ref: '#/components/schemas/ApiEnvelope'}}}}
SuccessObject: {description: Object result, content: {application/json: {schema: {$ref: '#/components/schemas/ApiEnvelope'}}}}
SuccessList: {description: Non-paged list result, content: {application/json: {schema: {$ref: '#/components/schemas/ApiListEnvelope'}}}}
BusinessError: {description: Business error, content: {application/json: {schema: {$ref: '#/components/schemas/ErrorEnvelope'}}}}