优化

2026-08-11 09:25:45 +08:00
parent 87a17e6694
commit f5a0c81286
9 changed files with 482 additions and 66 deletions
@@ -0,0 +1,203 @@
+openapi: 3.0.3
+info:
+  title: Finance F1 Manual AR API
+  version: 1.0.0
+  description: 首期人工账单、收款和成本接口；仅 CNY，平台财务可写，客户只读。
+servers:
+  - url: /api
+paths:
+  /platform/finance/v1/bills:
+    get:
+      summary: 查询平台账单
+      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'}}
+    post:
+      summary: 创建账单草稿
+      security: [{platformFinance: []}]
+      parameters: [{$ref: '#/components/parameters/IdempotencyKey'}]
+      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/CreateBillRequest'}}}}
+      responses: {'200': {$ref: '#/components/responses/SuccessBill'}, '403': {$ref: '#/components/responses/BusinessError'}}
+  /platform/finance/v1/bills/{billId}:
+    get:
+      summary: 查询平台账单详情
+      security: [{platformFinance: []}]
+      parameters: [{$ref: '#/components/parameters/BillId'}]
+      responses: {'200': {$ref: '#/components/responses/SuccessBill'}}
+    put:
+      summary: 更新账单草稿
+      security: [{platformFinance: []}]
+      parameters: [{$ref: '#/components/parameters/BillId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
+      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/UpdateBillRequest'}}}}
+      responses: {'200': {$ref: '#/components/responses/SuccessBill'}}
+  /platform/finance/v1/bills/{billId}/issue:
+    post:
+      summary: 出账并冻结账单
+      security: [{platformFinance: []}]
+      parameters: [{$ref: '#/components/parameters/BillId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
+      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/VersionRequest'}}}}
+      responses: {'200': {$ref: '#/components/responses/SuccessBill'}}
+  /platform/finance/v1/bills/{billId}/adjust:
+    post:
+      summary: 出账后调整并生成新版本
+      security: [{platformFinance: []}]
+      parameters: [{$ref: '#/components/parameters/BillId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
+      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/AdjustBillRequest'}}}}
+      responses: {'200': {$ref: '#/components/responses/SuccessBill'}}
+  /platform/finance/v1/bills/{billId}/void:
+    post:
+      summary: 作废账单
+      security: [{platformFinance: []}]
+      parameters: [{$ref: '#/components/parameters/BillId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
+      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/ReasonRequest'}}}}
+      responses: {'200': {$ref: '#/components/responses/SuccessBill'}}
+  /platform/finance/v1/receipts:
+    post:
+      summary: 人工登记收款并分配账单
+      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: 查询收款记录
+      security: [{platformFinance: []}]
+      responses: {'200': {$ref: '#/components/responses/SuccessPage'}}
+  /platform/finance/v1/cost-entries:
+    post:
+      summary: 人工登记单票或整柜成本
+      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: 查询成本记录
+      security: [{platformFinance: []}]
+      responses: {'200': {$ref: '#/components/responses/SuccessPage'}}
+  /client/finance/v1/bills:
+    get:
+      summary: 客户只读查询账单
+      security: [{customerFinanceRead: []}]
+      responses: {'200': {$ref: '#/components/responses/SuccessPage'}, '403': {$ref: '#/components/responses/BusinessError'}}
+  /client/finance/v1/bills/{billId}:
+    get:
+      summary: 客户只读查看账单详情
+      security: [{customerFinanceRead: []}]
+      parameters: [{$ref: '#/components/parameters/BillId'}]
+      responses: {'200': {$ref: '#/components/responses/SuccessBill'}, '403': {$ref: '#/components/responses/BusinessError'}}
+  /client/finance/v1/receipts:
+    get:
+      summary: 客户只读查询收款记录
+      security: [{customerFinanceRead: []}]
+      responses: {'200': {$ref: '#/components/responses/SuccessPage'}, '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]*$'}}
+    IdempotencyKey: {name: Idempotency-Key, in: header, required: true, schema: {type: string, maxLength: 128}}
+  schemas:
+    CreateBillRequest:
+      type: object
+      required: [customerId, billDate, lines]
+      properties:
+        customerId: {type: string}
+        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}}
+    BillLineInput:
+      type: object
+      required: [sourceFeeId, sourceFeeVersion, amount]
+      properties:
+        sourceFeeId: {type: string}
+        sourceFeeVersion: {type: integer, minimum: 1}
+        orderId: {type: string}
+        inboundId: {type: string}
+        feeItemName: {type: string}
+        amount: {type: number, format: double, minimum: 0}
+    VersionRequest:
+      type: object
+      required: [expectedVersion]
+      properties: {expectedVersion: {type: integer, minimum: 0}}
+    ReasonRequest:
+      type: object
+      required: [expectedVersion, reason]
+      properties:
+        expectedVersion: {type: integer, minimum: 0}
+        reason: {type: string, minLength: 1, maxLength: 500}
+    AdjustBillRequest:
+      allOf:
+        - {$ref: '#/components/schemas/ReasonRequest'}
+        - type: object
+          required: [lines]
+          properties: {lines: {type: array, minItems: 1, items: {$ref: '#/components/schemas/BillLineInput'}}}
+    CreateReceiptRequest:
+      type: object
+      required: [customerId, receivedDate, amount, paymentMethod, voucherFileIds, allocations]
+      properties:
+        customerId: {type: string}
+        receivedDate: {type: string, format: date}
+        amount: {type: number, format: double, minimum: 0, exclusiveMinimum: true}
+        currency: {type: string, enum: [CNY], default: CNY}
+        paymentMethod: {type: string, enum: [BANK_TRANSFER, CASH, OTHER]}
+        voucherFileIds: {type: array, minItems: 1, items: {type: string}}
+        remark: {type: string, maxLength: 500}
+        allocations: {type: array, minItems: 1, items: {$ref: '#/components/schemas/ReceiptAllocationInput'}}
+      example:
+        customerId: '10001'
+        receivedDate: '2026-08-11'
+        amount: 300
+        currency: CNY
+        paymentMethod: BANK_TRANSFER
+        voucherFileIds: ['90001']
+        allocations:
+          - {billId: '81001', amount: 100}
+          - {billId: '81002', amount: 100}
+          - {billId: '81003', amount: 100}
+    ReceiptAllocationInput:
+      type: object
+      required: [billId, amount]
+      properties:
+        billId: {type: string}
+        amount: {type: number, format: double, minimum: 0, exclusiveMinimum: true}
+    CreateCostRequest:
+      type: object
+      required: [costType, amount, expenseName, voucherFileIds]
+      properties:
+        costType: {type: string, enum: [SINGLE_ORDER, CONTAINER_SHARED]}
+        orderId: {type: string}
+        containerId: {type: string}
+        expenseName: {type: string, minLength: 1, maxLength: 100}
+        amount: {type: number, format: double, minimum: 0, exclusiveMinimum: true}
+        currency: {type: string, enum: [CNY], default: CNY}
+        voucherFileIds: {type: array, minItems: 1, items: {type: string}}
+        remark: {type: string, maxLength: 500}
+    BillStatus: {type: string, enum: [DRAFT, ISSUED, PARTIALLY_PAID, PAID, VOIDED]}
+    ApiEnvelope:
+      type: object
+      required: [code, message, data]
+      properties:
+        code: {type: string, example: '200'}
+        message: {type: string}
+        data: {type: object, additionalProperties: true}
+        requestId: {type: string}
+    ErrorEnvelope:
+      type: object
+      required: [code, message]
+      properties: {code: {type: string}, message: {type: string}, requestId: {type: string}}
+  responses:
+    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'}}}}
+    BusinessError: {description: Business error, content: {application/json: {schema: {$ref: '#/components/schemas/ErrorEnvelope'}}}}