572 lines
19 KiB
YAML
572 lines
19 KiB
YAML
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 的唯一键。
|
||
当前线上 `tbl_company` 还包含 `company_owner_openid` 字段，用于保存公司所有者 openid，并带普通索引。
|
||
同时新增了国家、省、市、区的名称与编码字段，便于前端直接按行政区划存取。
|
||
license:
|
||
name: Proprietary
|
||
identifier: LicenseRef-Proprietary
|
||
servers:
|
||
- url: https://bai-api.blv-oa.com/pb
|
||
description: 线上 PocketBase 服务
|
||
tags:
|
||
- name: Company
|
||
description: tbl_company 公司信息基础 CRUD
|
||
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~"张三")`；
|
||
4. 按 `company_id` 查询单条：`filter=company_id="WX-COMPANY-10001"&perPage=1&page=1`。
|
||
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_nationality_code: CN
|
||
company_province: 上海
|
||
company_province_code: '310000'
|
||
company_city: 上海
|
||
company_city_code: '310100'
|
||
company_district: 浦东新区
|
||
company_district_code: '310115'
|
||
company_postalcode: '200000'
|
||
company_add: 上海市浦东新区XX路1号
|
||
company_status: 有效
|
||
company_level: A
|
||
company_owner_openid: wx-openid-owner-001
|
||
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_nationality_code: CN
|
||
company_province: 上海
|
||
company_province_code: '310000'
|
||
company_city: 上海
|
||
company_city_code: '310100'
|
||
company_district: 浦东新区
|
||
company_district_code: '310115'
|
||
company_postalcode: '200000'
|
||
company_add: 上海市浦东新区XX路1号
|
||
company_status: 有效
|
||
company_level: A
|
||
company_owner_openid: wx-openid-owner-001
|
||
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` 也由数据库自动生成，
|
||
客户端创建时不需要传入，但仍可作为后续业务查询字段。
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/CompanyCreateRequest'
|
||
examples:
|
||
default:
|
||
value:
|
||
company_name: 宝镜科技
|
||
company_type: 渠道商
|
||
company_entity: 张三
|
||
company_usci: '91310000123456789A'
|
||
company_nationality: 中国
|
||
company_nationality_code: CN
|
||
company_province: 上海
|
||
company_province_code: '310000'
|
||
company_city: 上海
|
||
company_city_code: '310100'
|
||
company_district: 浦东新区
|
||
company_district_code: '310115'
|
||
company_postalcode: '200000'
|
||
company_add: 上海市浦东新区XX路1号
|
||
company_status: 有效
|
||
company_level: A
|
||
company_owner_openid: wx-openid-owner-001
|
||
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`。
|
||
如果业务侧只有 `company_id`，标准流程是先调用 list 接口
|
||
`filter=company_id="..."&perPage=1&page=1` 查出对应记录，再用返回的 `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_owner_openid: wx-openid-owner-002
|
||
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:
|
||
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_nationality_code:
|
||
type: string
|
||
description: 国家编码
|
||
company_province:
|
||
type: string
|
||
description: 省份
|
||
company_province_code:
|
||
type: string
|
||
description: 省份编码
|
||
company_city:
|
||
type: string
|
||
description: 城市
|
||
company_city_code:
|
||
type: string
|
||
description: 城市编码
|
||
company_district:
|
||
type: string
|
||
description: 区/县
|
||
company_district_code:
|
||
type: string
|
||
description: 区/县编码
|
||
company_postalcode:
|
||
type: string
|
||
description: 邮编
|
||
company_add:
|
||
type: string
|
||
description: 地址
|
||
company_status:
|
||
type: string
|
||
description: 公司状态
|
||
company_level:
|
||
type: string
|
||
description: 公司等级
|
||
company_owner_openid:
|
||
type: string
|
||
description: 公司所有者 openid
|
||
company_remark:
|
||
type: string
|
||
description: 备注
|
||
CompanyCreateRequest:
|
||
type: object
|
||
description: 创建时不需要传 `company_id`，由数据库自动生成。
|
||
properties:
|
||
company_name:
|
||
description: "公司名称"
|
||
type: string
|
||
company_type:
|
||
description: "公司类型"
|
||
type: string
|
||
company_entity:
|
||
description: "公司法人"
|
||
type: string
|
||
company_usci:
|
||
description: "统一社会信用代码"
|
||
type: string
|
||
company_nationality:
|
||
description: "国家名称"
|
||
type: string
|
||
company_nationality_code:
|
||
description: "国家编码"
|
||
type: string
|
||
company_province:
|
||
description: "省份名称"
|
||
type: string
|
||
company_province_code:
|
||
description: "省份编码"
|
||
type: string
|
||
company_city:
|
||
description: "城市名称"
|
||
type: string
|
||
company_city_code:
|
||
description: "城市编码"
|
||
type: string
|
||
company_district:
|
||
description: "区 / 县名称"
|
||
type: string
|
||
company_district_code:
|
||
description: "区 / 县编码"
|
||
type: string
|
||
company_postalcode:
|
||
description: "邮编"
|
||
type: string
|
||
company_add:
|
||
description: "地址"
|
||
type: string
|
||
company_status:
|
||
description: "公司状态"
|
||
type: string
|
||
company_level:
|
||
description: "公司等级"
|
||
type: string
|
||
company_owner_openid:
|
||
description: "公司所有者 openid"
|
||
type: string
|
||
company_remark:
|
||
description: "备注"
|
||
type: string
|
||
additionalProperties: false
|
||
CompanyUpdateRequest:
|
||
type: object
|
||
description: >-
|
||
更新时可只传需要修改的字段；记录定位统一依赖路径参数 `id`。
|
||
properties:
|
||
company_id:
|
||
description: "所属公司业务 ID"
|
||
type: string
|
||
company_name:
|
||
description: "公司名称"
|
||
type: string
|
||
company_type:
|
||
description: "公司类型"
|
||
type: string
|
||
company_entity:
|
||
description: "公司法人"
|
||
type: string
|
||
company_usci:
|
||
description: "统一社会信用代码"
|
||
type: string
|
||
company_nationality:
|
||
description: "国家名称"
|
||
type: string
|
||
company_nationality_code:
|
||
description: "国家编码"
|
||
type: string
|
||
company_province:
|
||
description: "省份名称"
|
||
type: string
|
||
company_province_code:
|
||
description: "省份编码"
|
||
type: string
|
||
company_city:
|
||
description: "城市名称"
|
||
type: string
|
||
company_city_code:
|
||
description: "城市编码"
|
||
type: string
|
||
company_district:
|
||
description: "区 / 县名称"
|
||
type: string
|
||
company_district_code:
|
||
description: "区 / 县编码"
|
||
type: string
|
||
company_postalcode:
|
||
description: "邮编"
|
||
type: string
|
||
company_add:
|
||
description: "地址"
|
||
type: string
|
||
company_status:
|
||
description: "公司状态"
|
||
type: string
|
||
company_level:
|
||
description: "公司等级"
|
||
type: string
|
||
company_owner_openid:
|
||
description: "公司所有者 openid"
|
||
type: string
|
||
company_remark:
|
||
description: "备注"
|
||
type: string
|
||
CompanyRecord:
|
||
allOf:
|
||
- type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: PocketBase 记录主键 id
|
||
collectionId:
|
||
type: string
|
||
collectionName:
|
||
type: string
|
||
created:
|
||
description: "记录创建时间"
|
||
type: string
|
||
updated:
|
||
description: "记录更新时间"
|
||
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:
|
||
description: "业务响应数据"
|
||
type: object
|
||
additionalProperties: true
|