XuJiacheng
51a90260e4
- 新增 openapi-miniapp-company.yaml 文件，定义 tbl_company 的基础 CRUD 接口文档，包括查询、创建、更新和删除公司记录的详细描述和示例。 - 新增 pocketbase.file-fields-to-attachments.js 脚本，用于迁移 PocketBase 中的文件字段到文本字段，并处理 tbl_attachments 集合的公开规则。
450 lines
14 KiB
YAML
450 lines
14 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 的唯一键。
|
||
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
|