openapi: 3.1.0
info:
  title: PocketBase MiniApp Company API
  version: 1.0.0
  summary: 小程序端通过 PocketBase JS SDK 直连 tbl_company 的基础 CRUD 文档
  description: >-
    本文档面向小程序端直接使用 PocketBase JS SDK / REST API 访问 `tbl_company`。
    本文档统一以 PocketBase 原生记录主键 `id` 作为唯一识别键。
    `company_id` 保留为普通业务字段，可用于展示、筛选和业务关联，但不再作为 CRUD 的唯一键。
  license:
    name: Proprietary
    identifier: LicenseRef-Proprietary
servers:
  - url: https://bai-api.blv-oa.com/pb
    description: 线上 PocketBase 服务
tags:
  - name: Company
    description: tbl_company 公司信息基础 CRUD
security:
  - pocketbaseAuth: []
paths:
  /api/collections/tbl_company/records:
    get:
      tags: [Company]
      operationId: listCompanyRecords
      summary: 查询公司列表
      description: >-
        使用 PocketBase 原生 records list/search 接口查询 `tbl_company`。
        支持三种常见模式：
        1. 全表查询：不传 `filter`；
        2. 精确查询：`filter=id="q1w2e3r4t5y6u7i"`；
        3. 模糊查询：`filter=(company_name~"华住" || company_usci~"9131" || company_entity~"张三")`。
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PerPage'
        - $ref: '#/components/parameters/Sort'
        - $ref: '#/components/parameters/Filter'
        - $ref: '#/components/parameters/Fields'
        - $ref: '#/components/parameters/SkipTotal'
      responses:
        '200':
          description: 查询成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyListResponse'
              examples:
                all:
                  summary: 全表查询
                  value:
                    page: 1
                    perPage: 30
                    totalItems: 2
                    totalPages: 1
                    items:
                      - id: q1w2e3r4t5y6u7i
                        collectionId: pbc_company_demo
                        collectionName: tbl_company
                        created: '2026-03-27 10:00:00.000Z'
                        updated: '2026-03-27 10:00:00.000Z'
                        company_id: C10001
                        company_name: 宝镜科技
                        company_type: 渠道商
                        company_entity: 张三
                        company_usci: '91310000123456789A'
                        company_nationality: 中国
                        company_province: 上海
                        company_city: 上海
                        company_postalcode: '200000'
                        company_add: 上海市浦东新区XX路1号
                        company_status: 有效
                        company_level: A
                        company_remark: ''
                exact:
                  summary: 按 id 精确查询
                  value:
                    page: 1
                    perPage: 1
                    totalItems: 1
                    totalPages: 1
                    items:
                      - id: q1w2e3r4t5y6u7i
                        collectionId: pbc_company_demo
                        collectionName: tbl_company
                        created: '2026-03-27 10:00:00.000Z'
                        updated: '2026-03-27 10:00:00.000Z'
                        company_id: C10001
                        company_name: 宝镜科技
                        company_type: 渠道商
                        company_entity: 张三
                        company_usci: '91310000123456789A'
                        company_nationality: 中国
                        company_province: 上海
                        company_city: 上海
                        company_postalcode: '200000'
                        company_add: 上海市浦东新区XX路1号
                        company_status: 有效
                        company_level: A
                        company_remark: ''
        '400':
          description: 过滤表达式或查询参数不合法
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PocketBaseError'
        '403':
          description: 当前调用方没有 list 权限
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PocketBaseError'
    post:
      tags: [Company]
      operationId: createCompanyRecord
      summary: 新增公司
      description: >-
        创建一条 `tbl_company` 记录。当前文档以 `id` 作为记录唯一识别键，
        新建成功后由 PocketBase 自动生成 `id`；根据当前项目建表脚本，`company_id` 仍是必填业务字段，但不再作为 CRUD 唯一键。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyCreateRequest'
            examples:
              default:
                value:
                  company_id: C10001
                  company_name: 宝镜科技
                  company_type: 渠道商
                  company_entity: 张三
                  company_usci: '91310000123456789A'
                  company_nationality: 中国
                  company_province: 上海
                  company_city: 上海
                  company_postalcode: '200000'
                  company_add: 上海市浦东新区XX路1号
                  company_status: 有效
                  company_level: A
                  company_remark: 首次创建
      responses:
        '200':
          description: 创建成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyRecord'
        '400':
          description: 校验失败，例如字段类型不合法或违反当前集合约束
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PocketBaseError'
        '403':
          description: 当前调用方没有 create 权限
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PocketBaseError'
        '404':
          description: 集合不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PocketBaseError'
  /api/collections/tbl_company/records/{recordId}:
    get:
      tags: [Company]
      operationId: getCompanyRecordByRecordId
      summary: 按 PocketBase 记录 id 查询公司
      description: >-
        这是 PocketBase 原生单条查询接口，路径参数必须传记录主键 `id`。
      parameters:
        - $ref: '#/components/parameters/RecordId'
        - $ref: '#/components/parameters/Fields'
      responses:
        '200':
          description: 查询成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyRecord'
        '403':
          description: 当前调用方没有 view 权限
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PocketBaseError'
        '404':
          description: 记录不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PocketBaseError'
    patch:
      tags: [Company]
      operationId: updateCompanyRecordByRecordId
      summary: 按 PocketBase 记录 id 更新公司
      description: >-
        这是 PocketBase 原生更新接口，路径参数统一使用记录主键 `id`。
      parameters:
        - $ref: '#/components/parameters/RecordId'
        - $ref: '#/components/parameters/Fields'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyUpdateRequest'
            examples:
              default:
                value:
                  company_name: 宝镜科技（更新）
                  company_status: 有效
                  company_level: S
                  company_remark: 已更新基础资料
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyRecord'
        '400':
          description: 更新参数不合法
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PocketBaseError'
        '403':
          description: 当前调用方没有 update 权限
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PocketBaseError'
        '404':
          description: 记录不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PocketBaseError'
    delete:
      tags: [Company]
      operationId: deleteCompanyRecordByRecordId
      summary: 按 PocketBase 记录 id 删除公司
      description: >-
        这是 PocketBase 原生删除接口，路径参数统一使用记录主键 `id`。
      parameters:
        - $ref: '#/components/parameters/RecordId'
      responses:
        '204':
          description: 删除成功
        '400':
          description: 删除失败，例如仍被必填 relation 引用
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PocketBaseError'
        '403':
          description: 当前调用方没有 delete 权限
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PocketBaseError'
        '404':
          description: 记录不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PocketBaseError'
components:
  securitySchemes:
    pocketbaseAuth:
      type: apiKey
      in: header
      name: Authorization
      description: PocketBase 认证 token。使用 JS SDK 时通常由 `pb.authStore` 自动附带。
  parameters:
    Page:
      name: page
      in: query
      description: 页码，默认 1
      schema:
        type: integer
        minimum: 1
        default: 1
    PerPage:
      name: perPage
      in: query
      description: 每页返回条数，默认 30
      schema:
        type: integer
        minimum: 1
        default: 30
    Sort:
      name: sort
      in: query
      description: 排序字段，例如 `-created,+company_name`
      schema:
        type: string
    Filter:
      name: filter
      in: query
      description: >-
        PocketBase 过滤表达式。
        精确查询示例：`id="q1w2e3r4t5y6u7i"`；
        模糊查询示例：`(company_name~"宝镜" || company_usci~"9131" || company_entity~"张三")`
      schema:
        type: string
    Fields:
      name: fields
      in: query
      description: 逗号分隔的返回字段列表，例如 `id,company_id,company_name`
      schema:
        type: string
    SkipTotal:
      name: skipTotal
      in: query
      description: 是否跳过 totalItems/totalPages 统计
      schema:
        type: boolean
        default: false
    RecordId:
      name: recordId
      in: path
      required: true
      description: PocketBase 记录主键 id
      schema:
        type: string
  schemas:
    CompanyBase:
      type: object
      properties:
        company_id:
          type: string
          description: 公司业务编号字段，不再作为 CRUD 唯一键
        company_name:
          type: string
          description: 公司名称
        company_type:
          type: string
          description: 公司类型
        company_entity:
          type: string
          description: 公司法人
        company_usci:
          type: string
          description: 统一社会信用代码
        company_nationality:
          type: string
          description: 国家
        company_province:
          type: string
          description: 省份
        company_city:
          type: string
          description: 城市
        company_postalcode:
          type: string
          description: 邮编
        company_add:
          type: string
          description: 地址
        company_status:
          type: string
          description: 公司状态
        company_level:
          type: string
          description: 公司等级
        company_remark:
          type: string
          description: 备注
    CompanyCreateRequest:
      allOf:
        - $ref: '#/components/schemas/CompanyBase'
        - type: object
          required: [company_id]
    CompanyUpdateRequest:
      type: object
      description: >-
        更新时可只传需要修改的字段；记录定位统一依赖路径参数 `id`。
      properties:
        company_id:
          type: string
        company_name:
          type: string
        company_type:
          type: string
        company_entity:
          type: string
        company_usci:
          type: string
        company_nationality:
          type: string
        company_province:
          type: string
        company_city:
          type: string
        company_postalcode:
          type: string
        company_add:
          type: string
        company_status:
          type: string
        company_level:
          type: string
        company_remark:
          type: string
    CompanyRecord:
      allOf:
        - type: object
          properties:
            id:
              type: string
              description: PocketBase 记录主键 id
            collectionId:
              type: string
            collectionName:
              type: string
            created:
              type: string
            updated:
              type: string
        - $ref: '#/components/schemas/CompanyBase'
    CompanyListResponse:
      type: object
      properties:
        page:
          type: integer
        perPage:
          type: integer
        totalItems:
          type: integer
        totalPages:
          type: integer
        items:
          type: array
          items:
            $ref: '#/components/schemas/CompanyRecord'
    PocketBaseError:
      type: object
      properties:
        status:
          type: integer
        message:
          type: string
        data:
          type: object
          additionalProperties: true