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