openapi: 3.0.3
info:
  title: 柏悦费用项目 API
  version: 1.0.0
  description: 平台费用项目主数据；业务结果统一通过响应体 code 返回。
security:
  - bearerAuth: []
paths:
  /api/platform/v1/fee-items:
    get:
      summary: 查询费用项目
      description: 需要 firstleg:fee-item:view 权限；费用项目属于平台公共主数据。
      parameters:
        - {name: category, in: query, schema: {type: string, maxLength: 64}}
        - {name: tradeScope, in: query, schema: {type: string, enum: [DOMESTIC, INTERNATIONAL]}}
        - {name: keyword, in: query, schema: {type: string, maxLength: 128}}
        - {name: status, in: query, schema: {type: string, enum: [ACTIVE, DISABLED]}}
        - {name: page, in: query, schema: {type: integer, minimum: 1, default: 1}}
        - {name: size, in: query, schema: {type: integer, minimum: 1, maximum: 200, default: 20}}
      responses:
        '200':
          description: 成功或业务失败
          content:
            application/json:
              schema: {$ref: '#/components/schemas/FeeItemPageApiResponse'}
        '403': {description: 无权限}
    post:
      summary: 新增费用项目
      description: 需要 firstleg:fee-item:create 权限；feeCode 可省略，服务端生成唯一人工编码；传入时统一转为大写并在平台公共范围内保持唯一。
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/FeeItemSaveRequest'}
      responses:
        '200':
          description: 成功或业务失败
          content:
            application/json:
              schema: {$ref: '#/components/schemas/FeeItemApiResponse'}
        '403': {description: 无权限}
  /api/platform/v1/fee-items/{id}:
    get:
      summary: 查询费用项目详情
      description: 需要 firstleg:fee-item:view 权限。
      parameters: [{$ref: '#/components/parameters/Id'}]
      responses:
        '200':
          description: 成功或业务失败
          content:
            application/json:
              schema: {$ref: '#/components/schemas/FeeItemApiResponse'}
        '403': {description: 无权限}
    put:
      summary: 编辑费用项目
      description: 需要 firstleg:fee-item:edit 权限；省略 feeCode 时保留原编码，传入时统一转为大写并校验平台公共范围内唯一性。
      parameters: [{$ref: '#/components/parameters/Id'}]
      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/FeeItemSaveRequest'}}}}
      responses:
        '200':
          description: 成功或业务失败
          content:
            application/json:
              schema: {$ref: '#/components/schemas/FeeItemApiResponse'}
        '403': {description: 无权限}
    delete:
      summary: 删除费用项目
      description: 需要 firstleg:fee-item:delete 权限；已被费用明细引用的项目只能停用。
      parameters: [{$ref: '#/components/parameters/Id'}]
      responses:
        '200':
          description: 成功或业务失败
          content:
            application/json:
              schema: {$ref: '#/components/schemas/VoidApiResponse'}
        '403': {description: 无权限}
  /api/platform/v1/fee-items/{id}/status:
    patch:
      summary: 启用或停用费用项目
      description: 需要 firstleg:fee-item:edit 权限。
      parameters: [{$ref: '#/components/parameters/Id'}]
      requestBody: {required: true, content: {application/json: {schema: {type: object, required: [status], properties: {status: {type: string, enum: [ACTIVE, DISABLED]}}}}}}
      responses:
        '200':
          description: 成功或业务失败
          content:
            application/json:
              schema: {$ref: '#/components/schemas/VoidApiResponse'}
        '403': {description: 无权限}
components:
  securitySchemes:
    bearerAuth: {type: http, scheme: bearer}
  parameters:
    Id: {name: id, in: path, required: true, schema: {type: integer, format: int64, minimum: 1}}
  schemas:
    FeeItemSaveRequest:
      type: object
      required: [category, tradeScope, feeTypeName, pickupPayable, pickupReceivable, warehousePayable, warehouseReceivable, allocationFee]
      properties:
        category: {type: string, maxLength: 64}
        tradeScope: {type: string, enum: [DOMESTIC, INTERNATIONAL]}
        feeCode: {type: string, maxLength: 50, pattern: '^[A-Za-z0-9_-]+$'}
        feeTypeName: {type: string, maxLength: 128}
        pickupPayable: {type: boolean}
        pickupReceivable: {type: boolean}
        warehousePayable: {type: boolean}
        warehouseReceivable: {type: boolean}
        allocationFee: {type: boolean}
        description: {type: string, maxLength: 500}
    FeeItemResource:
      type: object
      required: [id, category, tradeScope, feeCode, feeTypeName, pickupPayable, pickupReceivable, warehousePayable, warehouseReceivable, allocationFee, status]
      properties:
        id: {type: integer, format: int64}
        category: {type: string}
        tradeScope: {type: string, enum: [DOMESTIC, INTERNATIONAL]}
        feeCode: {type: string}
        feeTypeName: {type: string}
        pickupPayable: {type: boolean}
        pickupReceivable: {type: boolean}
        warehousePayable: {type: boolean}
        warehouseReceivable: {type: boolean}
        allocationFee: {type: boolean}
        description: {type: string, nullable: true}
        status: {type: string, enum: [ACTIVE, DISABLED]}
        createdBy: {type: integer, format: int64, nullable: true}
        createdByName: {type: string, nullable: true}
        updatedBy: {type: integer, format: int64, nullable: true}
        updatedByName: {type: string, nullable: true}
        createdAt: {type: string, format: date-time}
        updatedAt: {type: string, format: date-time}
        deleted: {type: boolean, nullable: true}
        version: {type: integer, nullable: true}
    FeeItemPage:
      type: object
      required: [records, page, size, total, pages]
      properties:
        records:
          type: array
          items: {$ref: '#/components/schemas/FeeItemResource'}
        page: {type: integer, format: int64}
        size: {type: integer, format: int64}
        total: {type: integer, format: int64}
        pages: {type: integer, format: int64}
    FeeItemApiResponse:
      type: object
      required: [code, message, timestamp]
      properties:
        code: {type: string}
        message: {type: string}
        data: {$ref: '#/components/schemas/FeeItemResource'}
        requestId: {type: string, nullable: true}
        traceId: {type: string, nullable: true}
        timestamp: {type: string, format: date-time}
    FeeItemPageApiResponse:
      type: object
      required: [code, message, timestamp]
      properties:
        code: {type: string}
        message: {type: string}
        data: {$ref: '#/components/schemas/FeeItemPage'}
        requestId: {type: string, nullable: true}
        traceId: {type: string, nullable: true}
        timestamp: {type: string, format: date-time}
    VoidApiResponse:
      type: object
      required: [code, message, timestamp]
      properties:
        code: {type: string}
        message: {type: string}
        data: {nullable: true}
        requestId: {type: string, nullable: true}
        traceId: {type: string, nullable: true}
        timestamp: {type: string, format: date-time}