PartsInquiry/doc/openapi.yaml

openapi: 3.0.3
info:
  title: PartsInquiry API
  version: 0.1.0
  description: >-
    所有接口定义集中于此文件。每个 path 在 summary/description 中标注实现状态。
servers:
  - url: /
paths:
  /api/notices:
    get:
      summary: 公告列表（✅ Fully Implemented）
      description: 返回当前店铺可见的公告列表。后端与前端均已接入。
      parameters:
        - in: header
          name: X-Shop-Id
          required: false
          schema:
            type: integer
          description: 店铺ID，缺省为 1
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Notice'
  /api/metrics/overview:
    get:
      summary: 概览统计（❌ Partially Implemented）
      description: 返回今日/本月销售额、本月利润与库存商品数量。前端已接入，后端待实现。
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetricsOverview'
  /api/accounts:
    get:
      summary: 账户列表（❌ Partially Implemented）
      description: 前端账户选择页已接入，后端返回数组或 {list:[]} 皆可。
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                oneOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/Account'
                  - type: object
                    properties:
                      list:
                        type: array
                        items:
                          $ref: '#/components/schemas/Account'
  /api/suppliers:
    get:
      summary: 供应商搜索（❌ Partially Implemented）
      parameters:
        - in: query
          name: kw
          schema:
            type: string
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                oneOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/Supplier'
                  - type: object
                    properties:
                      list:
                        type: array
                        items:
                          $ref: '#/components/schemas/Supplier'
  /api/other-transactions:
    post:
      summary: 新建其他收入/支出（❌ Partially Implemented）
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOtherTransactionRequest'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    format: int64
  /api/products:
    get:
      summary: 商品搜索（❌ Partially Implemented）
      description: 前端已接入查询参数 kw/page/size，后端待实现或对齐。
      parameters:
        - in: query
          name: kw
          schema:
            type: string
        - in: query
          name: page
          schema:
            type: integer
            default: 1
        - in: query
          name: size
          schema:
            type: integer
            default: 50
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                oneOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/Product'
                  - type: object
                    properties:
                      list:
                        type: array
                        items:
                          $ref: '#/components/schemas/Product'
  /api/customers:
    get:
      summary: 客户搜索（❌ Partially Implemented）
      description: 前端已接入查询参数 kw/page/size，后端待实现或对齐。
      parameters:
        - in: query
          name: kw
          schema:
            type: string
        - in: query
          name: page
          schema:
            type: integer
            default: 1
        - in: query
          name: size
          schema:
            type: integer
            default: 50
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                oneOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/Customer'
                  - type: object
                    properties:
                      list:
                        type: array
                        items:
                          $ref: '#/components/schemas/Customer'
  /api/orders:
    post:
      summary: 新建单据（❌ Partially Implemented）
      description: 前端开单页已提交 payload，后端待实现。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    format: int64
                  orderNo:
                    type: string
components:
  schemas:
    Notice:
      type: object
      properties:
        id:
          type: integer
          format: int64
        shopId:
          type: integer
          format: int64
        userId:
          type: integer
          format: int64
        title:
          type: string
        content:
          type: string
        tag:
          type: string
        pinned:
          type: boolean
        startsAt:
          type: string
          format: date-time
    MetricsOverview:
      type: object
      properties:
        todaySales:
          type: string
          example: '1234.56'
        monthSales:
          type: string
          example: '23456.78'
        monthProfit:
          type: string
          example: '3456.78'
        stockCount:
          type: string
          example: '1200'
    Account:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        type:
          type: string
          enum: [cash, bank, alipay, wechat, other]
        balance:
          type: number
    Supplier:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        mobile:
          type: string
    CreateOtherTransactionRequest:
      type: object
      properties:
        type:
          type: string
          enum: [income, expense]
        category:
          type: string
        counterpartyId:
          type: integer
          format: int64
          nullable: true
        accountId:
          type: integer
          format: int64
        amount:
          type: number
        txTime:
          type: string
          format: date
        remark:
          type: string
        endsAt:
          type: string
          format: date-time
        status:
          type: string
          enum: [DRAFT, PUBLISHED, OFFLINE]
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    Product:
      type: object
      properties:
        id:
          type: integer
          format: int64
        code:
          type: string
        name:
          type: string
        price:
          type: number
        stock:
          type: number
    Customer:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        mobile:
          type: string
    CreateOrderRequest:
      type: object
      properties:
        type:
          type: string
          description: 'sale.out/sale.return/sale.collect/purchase/income/expense 等'
        orderTime:
          type: string
          format: date
        customerId:
          type: integer
          format: int64
          nullable: true
        items:
          type: array
          items:
            type: object
            properties:
              productId:
                type: integer
                format: int64
              quantity:
                type: number
              unitPrice:
                type: number
        amount:
          type: number