Boonlive_RD_Web/Web_BAI_Manage_ApiServer
9
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 规范化PocketBase数据库文档与原生API访问

Browse Source 
- 将数据库文档拆分为按collection命名的标准文件，统一格式
- 补充tbl_company、tbl_system_dict等表的原生访问规则
- 新增users_tag、document_create等字段
- 优化用户资料更新接口，支持非必填字段
- 添加公司原生API测试脚本
- 归档本次变更至OpenSpec
This commit is contained in:
徐
2026-03-29 16:21:34 +08:00
parent 51a90260e4
commit e9fe1165e3
46 changed files with 3790 additions and 1108 deletions
Download Patch File Download Diff File Expand all files Collapse all files

144
pocket-base/spec/openapi-miniapp-company.yaml
View File

@@ -7,6 +7,8 @@ info:
本文档面向小程序端直接使用 PocketBase JS SDK / REST API 访问 `tbl_company`。
本文档统一以 PocketBase 原生记录主键 `id` 作为唯一识别键。
`company_id` 保留为普通业务字段，可用于展示、筛选和业务关联，但不再作为 CRUD 的唯一键。
当前线上 `tbl_company` 还包含 `company_owner_openid` 字段，用于保存公司所有者 openid，并带普通索引。
同时新增了国家、省、市、区的名称与编码字段，便于前端直接按行政区划存取。
license:
name: Proprietary
identifier: LicenseRef-Proprietary
@@ -29,7 +31,8 @@ paths:
支持三种常见模式：
1. 全表查询：不传 `filter`；
2. 精确查询：`filter=id="q1w2e3r4t5y6u7i"`；
3. 模糊查询：`filter=(company_name~"华住" || company_usci~"9131" || company_entity~"张三")`。
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'
@@ -64,12 +67,18 @@ paths:
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 精确查询
@@ -90,12 +99,18 @@ paths:
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: 过滤表达式或查询参数不合法
@@ -115,7 +130,8 @@ paths:
summary: 新增公司
description: >-
创建一条 `tbl_company` 记录。当前文档以 `id` 作为记录唯一识别键，
新建成功后由 PocketBase 自动生成 `id`；根据当前项目建表脚本，`company_id` 仍是必填业务字段，但不再作为 CRUD 唯一键。
新建成功后由 PocketBase 自动生成 `id`；`company_id` 也由数据库自动生成，
客户端创建时不需要传入，但仍可作为后续业务查询字段。
requestBody:
required: true
content:
@@ -125,18 +141,23 @@ paths:
examples:
default:
value:
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: 首次创建
responses:
'200':
@@ -198,6 +219,8 @@ paths:
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'
@@ -213,6 +236,7 @@ paths:
company_name: 宝镜科技（更新）
company_status: 有效
company_level: S
company_owner_openid: wx-openid-owner-002
company_remark: 已更新基础资料
responses:
'200':
@@ -349,12 +373,27 @@ components:
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: 邮编
@@ -367,44 +406,132 @@ components:
company_level:
type: string
description: 公司等级
company_owner_openid:
type: string
description: 公司所有者 openid
company_remark:
type: string
description: 备注
CompanyCreateRequest:
allOf:
- $ref: '#/components/schemas/CompanyBase'
- type: object
required: [company_id]
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:
@@ -418,8 +545,10 @@ components:
collectionName:
type: string
created:
description: "记录创建时间"
type: string
updated:
description: "记录更新时间"
type: string
- $ref: '#/components/schemas/CompanyBase'
CompanyListResponse:
@@ -445,5 +574,6 @@ components:
message:
type: string
data:
description: "业务响应数据"
type: object
additionalProperties: true