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 
- 修改登录路由为 `/pb/api/wechat/login`，新增局部 try/catch 以保留业务状态码并返回统一结构 `{ code, msg, data }`。
- 更新所有相关 API 路由前缀为 `/pb`，包括系统、平台、字典、附件和文档接口。
- 新增文档接口支持多个附件 ID，更新 OpenAPI 文档以反映这些变化。
- 在数据库模式中添加对字典名称的唯一索引，确保全局唯一性。
- 更新文档字段，设置 `document_title` 和 `document_type` 为必填项，并在验证过程中检查字段的必填属性。
This commit is contained in:
徐
2026-03-27 13:55:06 +08:00
parent 9feb0bb3a0
commit c43aae783f
9 changed files with 749 additions and 206 deletions
Download Patch File Download Diff File Expand all files Collapse all files

133
pocket-base/spec/changes.2026-03-23-pocketbase-hooks-auth-hardening.md
View File

@@ -81,7 +81,7 @@
### 1. 登录路由显式错误响应
`POST /api/wechat/login` 新增局部 try/catch：
`POST /pb/api/wechat/login` 新增局部 try/catch：
- 保留业务状态码
- 返回 `{ code, msg, data }`
@@ -132,39 +132,39 @@
当前 active PocketBase hooks 契约如下：
- `POST /api/system/test-helloworld`
- `POST /api/system/health`
- `POST /api/system/refresh-token`
- `POST /api/platform/register`
- `POST /api/platform/login`
- `POST /api/wechat/login`
- `POST /api/wechat/profile`
- `POST /api/dictionary/list`
- `POST /api/dictionary/detail`
- `POST /api/dictionary/create`
- `POST /api/dictionary/update`
- `POST /api/dictionary/delete`
- `POST /api/attachment/list`
- `POST /api/attachment/detail`
- `POST /api/attachment/upload`
- `POST /api/attachment/delete`
- `POST /api/document/list`
- `POST /api/document/detail`
- `POST /api/document/create`
- `POST /api/document/update`
- `POST /api/document/delete`
- `POST /api/document-history/list`
- `POST /pb/api/system/test-helloworld`
- `POST /pb/api/system/health`
- `POST /pb/api/system/refresh-token`
- `POST /pb/api/platform/register`
- `POST /pb/api/platform/login`
- `POST /pb/api/wechat/login`
- `POST /pb/api/wechat/profile`
- `POST /pb/api/dictionary/list`
- `POST /pb/api/dictionary/detail`
- `POST /pb/api/dictionary/create`
- `POST /pb/api/dictionary/update`
- `POST /pb/api/dictionary/delete`
- `POST /pb/api/attachment/list`
- `POST /pb/api/attachment/detail`
- `POST /pb/api/attachment/upload`
- `POST /pb/api/attachment/delete`
- `POST /pb/api/document/list`
- `POST /pb/api/document/detail`
- `POST /pb/api/document/create`
- `POST /pb/api/document/update`
- `POST /pb/api/document/delete`
- `POST /pb/api/document-history/list`
其中平台用户链路补充为：
### `POST /api/platform/register`
### `POST /pb/api/platform/register`
- body 必填：`users_name`、`users_phone`、`password`、`passwordConfirm`、`users_picture`
- 自动生成 GUID 并写入统一身份字段 `openid`
- 写入 `users_idtype = ManagePlatform`
- 成功时返回统一结构：`code`、`msg`、`data`，并在顶层额外返回 `token`
### `POST /api/platform/login`
### `POST /pb/api/platform/login`
- body 必填：`login_account`、`password`
- 仅允许 `users_idtype = ManagePlatform`
@@ -174,7 +174,7 @@
其中：
### `POST /api/wechat/login`
### `POST /pb/api/wechat/login`
- body 必填：`users_wx_code`
- 自动以微信 code 换取微信侧 `openid` 并写入统一身份字段
@@ -182,13 +182,13 @@
- 写入 `users_idtype = WeChat`
- 成功时返回统一结构：`code`、`msg`、`data`，并在顶层额外返回 `token`
### `POST /api/wechat/profile`
### `POST /pb/api/wechat/profile`
- 需 `Authorization`
- 基于当前 auth record 的 `openid` 定位用户
- 服务端用 `users_phone_code` 换取手机号后保存
### `POST /api/system/refresh-token`
### `POST /pb/api/system/refresh-token`
- body 可选：`users_wx_code`（允许为空）
- `Authorization` 可选：
@@ -202,16 +202,16 @@
新增 `dictionary` 分类接口，统一要求平台管理用户访问：
- `POST /api/dictionary/list`
- `POST /pb/api/dictionary/list`
- 支持按 `dict_name` 模糊搜索
- 返回字典全量信息，并将 `dict_word_enum`、`dict_word_description`、`dict_word_sort_order` 组装为 `items`
- `POST /api/dictionary/detail`
- `POST /pb/api/dictionary/detail`
- 按 `dict_name` 查询单条字典
- `POST /api/dictionary/create`
- `POST /pb/api/dictionary/create`
- 新增字典，`system_dict_id` 自动生成，`dict_name` 唯一
- `POST /api/dictionary/update`
- `POST /pb/api/dictionary/update`
- 按 `original_dict_name` / `dict_name` 更新字典
- `POST /api/dictionary/delete`
- `POST /pb/api/dictionary/delete`
- 按 `dict_name` 真删除字典
说明：
@@ -223,21 +223,21 @@
新增 `attachment` 分类接口，统一要求平台管理用户访问：
- `POST /api/attachment/list`
- `POST /pb/api/attachment/list`
- 支持按 `attachments_id`、`attachments_filename` 模糊搜索
- 支持按 `attachments_status` 过滤
- 返回附件元数据以及 PocketBase 文件流链接 `attachments_url`
- `POST /api/attachment/detail`
- `POST /pb/api/attachment/detail`
- 按 `attachments_id` 查询单个附件
- 返回文件流链接与下载链接
- `POST /api/attachment/upload`
- `POST /pb/api/attachment/upload`
- 使用 `multipart/form-data`
- 文件字段固定为 `attachments_link`
- 上传成功后自动生成 `attachments_id`
- 自动写入 `attachments_owner = 当前用户 openid`
- `POST /api/attachment/delete`
- `POST /pb/api/attachment/delete`
- 按 `attachments_id` 真删除附件
- 若该附件已被 `tbl_document.document_image` 或 `document_video` 引用，则拒绝删除
- 若该附件已被 `tbl_document.document_image` 或 `document_video` 中的任一附件列表引用，则拒绝删除
说明：
@@ -250,42 +250,44 @@
新增 `document` 分类接口，统一要求平台管理用户访问：
- `POST /api/document/list`
- `POST /pb/api/document/list`
- 支持按 `document_id`、`document_title`、`document_subtitle`、`document_summary`、`document_keywords` 模糊搜索
- 支持按 `document_status`、`document_type` 过滤
- 返回时会自动联查 `tbl_attachments`
- 额外补充：
- `document_image_url`
- `document_video_url`
- `document_image_attachment`
- `document_video_attachment`
- `POST /api/document/detail`
- `document_image_urls`
- `document_video_urls`
- `document_image_attachments`
- `document_video_attachments`
- `POST /pb/api/document/detail`
- 按 `document_id` 查询单条文档
- 返回与附件表联动解析后的文件流链接
- `POST /api/document/create`
- 返回与附件表联动解析后的多文件流链接
- `POST /pb/api/document/create`
- 新增文档
- `document_id` 可不传，由服务端自动生成
- `document_image`、`document_video` 必须传入已存在的 `attachments_id`
- `document_title`、`document_type` 为必填；其余字段均允许为空
- `document_image`、`document_video` 支持传入多个已存在的 `attachments_id`
- 成功后会写入一条文档操作历史，类型为 `create`
- `POST /api/document/update`
- `POST /pb/api/document/update`
- 按 `document_id` 更新文档
- 若传入附件字段，则会校验对应 `attachments_id` 是否存在
- `document_title`、`document_type` 为必填；其余字段均允许为空
- 若传入附件字段，则会校验多个 `attachments_id` 是否都存在
- 成功后会写入一条文档操作历史，类型为 `update`
- `POST /api/document/delete`
- `POST /pb/api/document/delete`
- 按 `document_id` 真删除文档
- 删除前会写入一条文档操作历史，类型为 `delete`
说明：
- `document_image`、`document_video` 当前保存的是 `attachments_id`，不是 PocketBase 文件字段。
- 文档查询时通过 `attachments_id -> tbl_attachments` 反查实际文件，并返回可直接访问的数据流链接。
- `document_image`、`document_video` 当前保存的是多个 `attachments_id`，底层以 `|` 分隔文本持久化，不是 PocketBase 文件字段。
- 文档查询时通过 `attachments_id -> tbl_attachments` 反查实际文件，并返回可直接访问的数据流链接数组。
- `document_owner` 语义为“上传者 openid”。
### 文档操作历史接口
新增 `document-history` 分类接口，统一要求平台管理用户访问：
- `POST /api/document-history/list`
- `POST /pb/api/document-history/list`
- 不传 `document_id` 时返回全部文档历史
- 传入 `document_id` 时仅返回该文档历史
- 结果按创建时间倒序排列
@@ -327,8 +329,11 @@
- 返回主页
- 文档管理页支持：
- 先上传附件到 `tbl_attachments`
- 再把返回的 `attachments_id` 写入 `tbl_document.document_image` / `document_video`
- 再把返回的多个 `attachments_id` 写入 `tbl_document.document_image` / `document_video`
- 图片和视频都支持多选上传
- 新增文档
- 编辑已有文档并回显多图片、多视频
- 从文档中移除附件并在保存后删除对应附件记录
- 查询文档列表
- 直接展示 PocketBase 文件流链接
- 删除文档
@@ -337,14 +342,16 @@
- 原页面 `page-b.js` 已替换为 `document-manage.js`
- 页面实际走的接口链路为：
- `/api/attachment/upload`
- `/api/document/create`
- `/api/document/list`
- `/api/document/delete`
- `/pb/api/attachment/upload`
- `/pb/api/document/create`
- `/pb/api/document/update`
- `/pb/api/attachment/delete`
- `/pb/api/document/list`
- `/pb/api/document/delete`
### 2. 健康检查版本探针
`POST /api/system/health` 新增：
`POST /pb/api/system/health` 新增：
- `data.version`
@@ -419,9 +426,9 @@ OpenAPI 文档中已取消 `bearerAuth` 鉴权组件与接口级重复 `Authoriz
建议归档后的发布核验顺序：
1. `POST /api/system/health`：确认 `data.version`
2. `POST /api/platform/login`：确认返回统一结构与顶层 `token`
3. `POST /api/dictionary/list`：确认鉴权与字典接口可用
1. `POST /pb/api/system/health`：确认 `data.version`
2. `POST /pb/api/platform/login`：确认返回统一结构与顶层 `token`
3. `POST /pb/api/dictionary/list`：确认鉴权与字典接口可用
---
@@ -429,3 +436,5 @@ OpenAPI 文档中已取消 `bearerAuth` 鉴权组件与接口级重复 `Authoriz
- 已将本轮字典管理、PocketBase 页面、统一响应、平台登录兼容修复、健康检查版本探针、OpenAPI/Apifox 鉴权策略调整并入本变更记录。
- 本记录可作为当前 PocketBase hooks 阶段性归档基线继续维护。

68
pocket-base/spec/openapi.yaml
View File

@@ -467,20 +467,48 @@ components:
type: string
document_image:
type: string
description: 关联的 `attachments_id`
description: 关联多个 `attachments_id`，底层使用 `|` 分隔保存
document_image_ids:
type: array
description: `document_image` 解析后的附件 id 列表
items:
type: string
document_image_urls:
type: array
description: 根据 `document_image -> tbl_attachments` 自动解析出的图片文件流链接列表
items:
type: string
document_image_url:
type: string
description: 根据 `document_image -> tbl_attachments` 自动解析出的图片文件流链接
description: 兼容字段，返回第一张图片的文件流链接
document_image_attachments:
type: array
items:
$ref: '#/components/schemas/AttachmentRecord'
document_image_attachment:
allOf:
- $ref: '#/components/schemas/AttachmentRecord'
nullable: true
document_video:
type: string
description: 关联的 `attachments_id`
description: 关联多个 `attachments_id`，底层使用 `|` 分隔保存
document_video_ids:
type: array
description: `document_video` 解析后的附件 id 列表
items:
type: string
document_video_urls:
type: array
description: 根据 `document_video -> tbl_attachments` 自动解析出的视频文件流链接列表
items:
type: string
document_video_url:
type: string
description: 根据 `document_video -> tbl_attachments` 自动解析出的视频文件流链接
description: 兼容字段，返回第一个视频的文件流链接
document_video_attachments:
type: array
items:
$ref: '#/components/schemas/AttachmentRecord'
document_video_attachment:
allOf:
- $ref: '#/components/schemas/AttachmentRecord'
@@ -546,6 +574,7 @@ components:
example: DOC-1743037200000-abc123
DocumentMutationRequest:
type: object
required: [document_title, document_type]
properties:
document_id:
type: string
@@ -570,11 +599,21 @@ components:
document_content:
type: string
document_image:
type: string
description: 图片附件的 `attachments_id`
oneOf:
- type: string
description: 多个图片附件 id 使用 `|` 分隔
- type: array
items:
type: string
description: 图片附件 id 列表；支持数组或 `|` 分隔字符串
document_video:
type: string
description: 视频附件的 `attachments_id`
oneOf:
- type: string
description: 多个视频附件 id 使用 `|` 分隔
- type: array
items:
type: string
description: 视频附件 id 列表；支持数组或 `|` 分隔字符串
document_relation_model:
type: string
document_keywords:
@@ -1222,8 +1261,8 @@ paths:
description: |
仅允许 `ManagePlatform` 用户访问。
支持按标题、摘要、关键词等字段模糊搜索，并可按 `document_status`、`document_type` 过滤。
返回结果会自动根据 `document_image`、`document_video` 关联 `tbl_attachments`，
额外补充 `document_image_url`、`document_video_url` 以及对应附件对象。
返回结果会自动根据 `document_image`、`document_video` 中的多个 `attachments_id` 关联 `tbl_attachments`，
额外补充 `document_image_urls`、`document_video_urls` 以及对应附件对象数组。
requestBody:
required: false
content:
@@ -1259,7 +1298,7 @@ paths:
summary: 查询文档详情
description: |
仅允许 `ManagePlatform` 用户访问。
按 `document_id` 查询单条文档，并返回与附件表联动解析后的文件流链接。
按 `document_id` 查询单条文档，并返回与附件表联动解析后的多文件流链接。
requestBody:
required: true
content:
@@ -1295,7 +1334,8 @@ paths:
description: |
仅允许 `ManagePlatform` 用户访问。
`document_id` 可选；未传时服务端自动生成。
`document_image`、`document_video` 需传入已存在于 `tbl_attachments` 的 `attachments_id`。
`document_title`、`document_type` 为必填；其余字段均允许为空。
`document_image`、`document_video` 支持传入多个已存在于 `tbl_attachments` 的 `attachments_id`。
成功后会同步写入一条 `tbl_document_operation_history`，操作类型为 `create`。
requestBody:
required: true
@@ -1331,7 +1371,9 @@ paths:
summary: 修改文档
description: |
仅允许 `ManagePlatform` 用户访问。
按 `document_id` 定位现有文档并更新；若传入 `document_image`、`document_video`，则必须是已存在的 `attachments_id`。
按 `document_id` 定位现有文档并更新。
`document_title`、`document_type` 为必填；其余字段均允许为空。
若传入 `document_image`、`document_video`，则支持多个 `attachments_id`，并会逐一校验是否存在。
成功后会同步写入一条 `tbl_document_operation_history`，操作类型为 `update`。
requestBody:
required: true