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

feat: 添加文档管理和登录页面功能，包含文档上传、列表展示及用户登录逻辑；新增数据库表结构初始化脚本

Browse Source
This commit is contained in:
徐
2026-03-27 10:27:44 +08:00
parent 836e660842
commit 9feb0bb3a0
23 changed files with 2483 additions and 104 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -6,7 +6,7 @@
## 范围
本次变更覆盖 `pocket-base/` 下 PocketBase hooks 项目的微信登录、平台注册/登录、资料更新、token 刷新、认证落库、错误可观测性、索引策略、字典管理、页面辅助操作、健康检查版本探针、OpenAPI 鉴权与统一响应规范。
本次变更覆盖 `pocket-base/` 下 PocketBase hooks 项目的微信登录、平台注册/登录、资料更新、token 刷新、认证落库、错误可观测性、索引策略、字典管理、附件管理、文档管理、文档操作历史、页面辅助操作、健康检查版本探针、OpenAPI 鉴权与统一响应规范。
---
@@ -144,6 +144,16 @@
- `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`
其中平台用户链路补充为：
@@ -209,16 +219,100 @@
- `dict_word_enum`、`dict_word_description`、`dict_word_sort_order` 已统一改为 JSON 字符串持久化，其中 `dict_word_sort_order` 已改为 `text` 类型。
- 查询时统一聚合为：`items: [{ enum, description, sortOrder }]`
### 附件管理接口
新增 `attachment` 分类接口，统一要求平台管理用户访问：
- `POST /api/attachment/list`
- 支持按 `attachments_id`、`attachments_filename` 模糊搜索
- 支持按 `attachments_status` 过滤
- 返回附件元数据以及 PocketBase 文件流链接 `attachments_url`
- `POST /api/attachment/detail`
- 按 `attachments_id` 查询单个附件
- 返回文件流链接与下载链接
- `POST /api/attachment/upload`
- 使用 `multipart/form-data`
- 文件字段固定为 `attachments_link`
- 上传成功后自动生成 `attachments_id`
- 自动写入 `attachments_owner = 当前用户 openid`
- `POST /api/attachment/delete`
- 按 `attachments_id` 真删除附件
- 若该附件已被 `tbl_document.document_image` 或 `document_video` 引用，则拒绝删除
说明：
- `tbl_attachments.attachments_link` 为 PocketBase `file` 字段，保存实际文件本体。
- 对外查询时会额外补充：
- `attachments_url`
- `attachments_download_url`
### 文档管理接口
新增 `document` 分类接口，统一要求平台管理用户访问：
- `POST /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_id` 查询单条文档
- 返回与附件表联动解析后的文件流链接
- `POST /api/document/create`
- 新增文档
- `document_id` 可不传，由服务端自动生成
- `document_image`、`document_video` 必须传入已存在的 `attachments_id`
- 成功后会写入一条文档操作历史，类型为 `create`
- `POST /api/document/update`
- 按 `document_id` 更新文档
- 若传入附件字段，则会校验对应 `attachments_id` 是否存在
- 成功后会写入一条文档操作历史，类型为 `update`
- `POST /api/document/delete`
- 按 `document_id` 真删除文档
- 删除前会写入一条文档操作历史，类型为 `delete`
说明：
- `document_image`、`document_video` 当前保存的是 `attachments_id`，不是 PocketBase 文件字段。
- 文档查询时通过 `attachments_id -> tbl_attachments` 反查实际文件，并返回可直接访问的数据流链接。
- `document_owner` 语义为“上传者 openid”。
### 文档操作历史接口
新增 `document-history` 分类接口，统一要求平台管理用户访问：
- `POST /api/document-history/list`
- 不传 `document_id` 时返回全部文档历史
- 传入 `document_id` 时仅返回该文档历史
- 结果按创建时间倒序排列
说明：
- 操作历史表为 `tbl_document_operation_history`
- 当前由文档新增、修改、删除接口自动写入
- 主要字段为：
- `doh_document_id`
- `doh_operation_type`
- `doh_user_id`
- `doh_current_count`
- `doh_remark`
---
## 七、页面与运维辅助能力新增
### 1. PocketBase 页面
新增页面：
当前页面入口：
- `/web`
- `/web/dictionary-manage`
- `/pb/manage`
- `/pb/manage/login`
- `/pb/manage/dictionary-manage`
- `/pb/manage/document-manage`
页面能力：
@@ -231,6 +325,22 @@
- 弹窗编辑枚举项
- 新增 / 删除字典
- 返回主页
- 文档管理页支持：
- 先上传附件到 `tbl_attachments`
- 再把返回的 `attachments_id` 写入 `tbl_document.document_image` / `document_video`
- 新增文档
- 查询文档列表
- 直接展示 PocketBase 文件流链接
- 删除文档
说明：
- 原页面 `page-b.js` 已替换为 `document-manage.js`
- 页面实际走的接口链路为：
- `/api/attachment/upload`
- `/api/document/create`
- `/api/document/list`
- `/api/document/delete`
### 2. 健康检查版本探针

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

@@ -9,7 +9,7 @@ info:
请在 Apifox 环境中统一设置全局 Header：`Authorization: Bearer {{token}}`。
version: 1.0.0
servers:
- url: https://bai-api.blv-oa.com/pb
- url: https://bai-api.blv-oa.com
description: 生产环境
- url: http://localhost:8090
description: PocketBase 本地环境
@@ -22,6 +22,12 @@ tags:
description: 面向平台用户的认证接口；平台用户会生成 GUID 并写入统一 `openid` 字段。
- name: 字典管理
description: 面向 ManagePlatform 用户的系统字典维护接口。
- name: 附件管理
description: 面向 ManagePlatform 用户的附件上传、查询与删除接口。
- name: 文档管理
description: 面向 ManagePlatform 用户的文档新增、查询、修改、删除接口；查询时会自动返回关联附件的 PocketBase 文件流链接。
- name: 文档历史
description: 面向 ManagePlatform 用户的文档操作历史查询接口。
components:
schemas:
ApiResponse:
@@ -358,8 +364,286 @@ components:
dict_name:
type: string
example: 用户状态
AttachmentRecord:
type: object
properties:
pb_id:
type: string
attachments_id:
type: string
attachments_link:
type: string
description: PocketBase 实际存储的文件名
attachments_url:
type: string
description: 附件文件流访问链接
attachments_download_url:
type: string
description: 附件下载链接
attachments_filename:
type: string
attachments_filetype:
type: string
attachments_size:
type: number
attachments_owner:
type: string
attachments_md5:
type: string
attachments_ocr:
type: string
attachments_status:
type: string
attachments_remark:
type: string
created:
type: string
updated:
type: string
AttachmentListRequest:
type: object
properties:
keyword:
type: string
description: 对 `attachments_id`、`attachments_filename` 的模糊搜索关键字
example: 手册
status:
type: string
description: 按附件状态过滤
example: active
AttachmentDetailRequest:
type: object
required: [attachments_id]
properties:
attachments_id:
type: string
example: ATT-1743037200000-abc123
AttachmentUploadRequest:
type: object
required: [attachments_link]
properties:
attachments_link:
type: string
format: binary
description: 要上传到 `tbl_attachments` 的单个文件
attachments_filename:
type: string
description: 原始文件名；不传时可由前端直接使用文件名
attachments_filetype:
type: string
description: 文件 MIME 类型
attachments_size:
type: number
description: 文件大小
attachments_md5:
type: string
attachments_ocr:
type: string
attachments_status:
type: string
example: active
attachments_remark:
type: string
DocumentRecord:
type: object
properties:
pb_id:
type: string
document_id:
type: string
document_effect_date:
type: string
document_expiry_date:
type: string
document_type:
type: string
document_title:
type: string
document_subtitle:
type: string
document_summary:
type: string
document_content:
type: string
document_image:
type: string
description: 关联的 `attachments_id`
document_image_url:
type: string
description: 根据 `document_image -> tbl_attachments` 自动解析出的图片文件流链接
document_image_attachment:
allOf:
- $ref: '#/components/schemas/AttachmentRecord'
nullable: true
document_video:
type: string
description: 关联的 `attachments_id`
document_video_url:
type: string
description: 根据 `document_video -> tbl_attachments` 自动解析出的视频文件流链接
document_video_attachment:
allOf:
- $ref: '#/components/schemas/AttachmentRecord'
nullable: true
document_owner:
type: string
description: 上传者 openid
document_relation_model:
type: string
document_keywords:
type: string
description: 多值字段，使用 `|` 分隔
document_share_count:
type: number
document_download_count:
type: number
document_favorite_count:
type: number
document_status:
type: string
document_embedding_status:
type: string
document_embedding_error:
type: string
document_embedding_lasttime:
type: string
document_vector_version:
type: string
document_product_categories:
type: string
description: 多值字段，使用 `|` 分隔
document_application_scenarios:
type: string
description: 多值字段，使用 `|` 分隔
document_hotel_type:
type: string
description: 多值字段，使用 `|` 分隔
document_remark:
type: string
created:
type: string
updated:
type: string
DocumentListRequest:
type: object
properties:
keyword:
type: string
description: 对 `document_id`、`document_title`、`document_subtitle`、`document_summary`、`document_keywords` 的模糊搜索关键字
example: 安装
status:
type: string
example: active
document_type:
type: string
example: 说明书
DocumentDetailRequest:
type: object
required: [document_id]
properties:
document_id:
type: string
example: DOC-1743037200000-abc123
DocumentMutationRequest:
type: object
properties:
document_id:
type: string
description: 创建时可不传，由服务端自动生成；更新时必填
example: DOC-1743037200000-abc123
document_effect_date:
type: string
description: 支持 `YYYY-MM-DD` 或 PocketBase 可识别日期时间字符串
example: 2026-03-27
document_expiry_date:
type: string
description: 支持 `YYYY-MM-DD` 或 PocketBase 可识别日期时间字符串
example: 2027-03-27
document_type:
type: string
document_title:
type: string
document_subtitle:
type: string
document_summary:
type: string
document_content:
type: string
document_image:
type: string
description: 图片附件的 `attachments_id`
document_video:
type: string
description: 视频附件的 `attachments_id`
document_relation_model:
type: string
document_keywords:
type: string
description: 多值字段，使用 `|` 分隔
document_share_count:
type: number
document_download_count:
type: number
document_favorite_count:
type: number
document_status:
type: string
document_embedding_status:
type: string
document_embedding_error:
type: string
document_embedding_lasttime:
type: string
document_vector_version:
type: string
document_product_categories:
type: string
description: 多值字段，使用 `|` 分隔
document_application_scenarios:
type: string
description: 多值字段，使用 `|` 分隔
document_hotel_type:
type: string
description: 多值字段，使用 `|` 分隔
document_remark:
type: string
DocumentDeleteRequest:
type: object
required: [document_id]
properties:
document_id:
type: string
example: DOC-1743037200000-abc123
DocumentHistoryRecord:
type: object
properties:
pb_id:
type: string
doh_id:
type: string
doh_document_id:
type: string
doh_operation_type:
type: string
doh_user_id:
type: string
doh_current_count:
type: number
doh_remark:
type: string
created:
type: string
updated:
type: string
DocumentHistoryListRequest:
type: object
properties:
document_id:
type: string
description: 可选；传入时仅查询指定文档的操作历史
example: DOC-1743037200000-abc123
paths:
/api/system/test-helloworld:
/pb/api/system/test-helloworld:
post:
tags: [系统]
summary: HelloWorld 测试接口
@@ -375,7 +659,7 @@ paths:
properties:
data:
$ref: '#/components/schemas/HelloWorldData'
/api/system/health:
/pb/api/system/health:
post:
tags: [系统]
summary: 健康检查
@@ -391,7 +675,7 @@ paths:
properties:
data:
$ref: '#/components/schemas/HealthData'
/api/system/users-count:
/pb/api/system/users-count:
post:
tags: [系统]
summary: 查询用户总数
@@ -408,7 +692,7 @@ paths:
properties:
data:
$ref: '#/components/schemas/UsersCountData'
/api/system/refresh-token:
/pb/api/system/refresh-token:
post:
tags: [系统]
summary: 刷新系统认证 token
@@ -451,7 +735,7 @@ paths:
description: 请求体必须为 application/json
'429':
description: 重复请求过于频繁
/api/wechat/login:
/pb/api/wechat/login:
post:
tags: [微信认证]
summary: 微信登录/注册合一
@@ -483,7 +767,7 @@ paths:
description: 重复请求过于频繁
'500':
description: 保存 auth 用户失败或服务端内部错误
/api/platform/register:
/pb/api/platform/register:
post:
tags: [平台认证]
summary: 平台用户注册
@@ -513,7 +797,7 @@ paths:
description: 请求体必须为 application/json
'429':
description: 重复请求过于频繁
/api/platform/login:
/pb/api/platform/login:
post:
tags: [平台认证]
summary: 平台用户登录
@@ -575,7 +859,7 @@ paths:
description: 请求体必须为 application/json
'429':
description: 重复请求过于频繁
/api/wechat/profile:
/pb/api/wechat/profile:
post:
tags: [微信认证]
summary: 更新微信用户资料
@@ -604,7 +888,7 @@ paths:
description: token 无效或当前 auth record 缺少统一身份字段 openid
'400':
description: 参数错误、手机号已被注册或资料更新失败
/api/dictionary/list:
/pb/api/dictionary/list:
post:
tags: [字典管理]
summary: 查询字典列表
@@ -640,7 +924,7 @@ paths:
description: 非 ManagePlatform 用户无权访问
'415':
description: 请求体必须为 application/json
/api/dictionary/detail:
/pb/api/dictionary/detail:
post:
tags: [字典管理]
summary: 查询指定字典
@@ -675,7 +959,7 @@ paths:
description: 未找到对应字典
'415':
description: 请求体必须为 application/json
/api/dictionary/create:
/pb/api/dictionary/create:
post:
tags: [字典管理]
summary: 新增字典
@@ -711,7 +995,7 @@ paths:
description: 请求体必须为 application/json
'429':
description: 重复请求过于频繁
/api/dictionary/update:
/pb/api/dictionary/update:
post:
tags: [字典管理]
summary: 修改字典
@@ -748,7 +1032,7 @@ paths:
description: 请求体必须为 application/json
'429':
description: 重复请求过于频繁
/api/dictionary/delete:
/pb/api/dictionary/delete:
post:
tags: [字典管理]
summary: 删除字典
@@ -788,3 +1072,370 @@ paths:
description: 请求体必须为 application/json
'429':
description: 重复请求过于频繁
/pb/api/attachment/list:
post:
tags: [附件管理]
summary: 查询附件列表
description: |
仅允许 `ManagePlatform` 用户访问。
支持按 `attachments_id`、`attachments_filename` 模糊搜索，并可按 `attachments_status` 过滤。
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/AttachmentListRequest'
responses:
'200':
description: 查询成功
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ApiResponse'
- type: object
properties:
data:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/AttachmentRecord'
'401':
description: token 无效或已过期
'403':
description: 非 ManagePlatform 用户无权访问
'415':
description: 请求体必须为 application/json
/pb/api/attachment/detail:
post:
tags: [附件管理]
summary: 查询附件详情
description: |
仅允许 `ManagePlatform` 用户访问。
按 `attachments_id` 查询单条附件，并返回 PocketBase 文件流链接与下载链接。
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AttachmentDetailRequest'
responses:
'200':
description: 查询成功
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ApiResponse'
- type: object
properties:
data:
$ref: '#/components/schemas/AttachmentRecord'
'400':
description: 参数错误
'401':
description: token 无效或已过期
'403':
description: 非 ManagePlatform 用户无权访问
'404':
description: 未找到对应附件
'415':
description: 请求体必须为 application/json
/pb/api/attachment/upload:
post:
tags: [附件管理]
summary: 上传附件
description: |
仅允许 `ManagePlatform` 用户访问。
使用 `multipart/form-data` 上传单个文件到 `tbl_attachments`，服务端会自动生成 `attachments_id`，
并返回可直接访问的 PocketBase 文件流链接。
requestBody:
required: true
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/AttachmentUploadRequest'
responses:
'200':
description: 上传成功
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ApiResponse'
- type: object
properties:
data:
$ref: '#/components/schemas/AttachmentRecord'
'400':
description: 参数错误、缺少文件或附件保存失败
'401':
description: token 无效或已过期
'403':
description: 非 ManagePlatform 用户无权访问
/pb/api/attachment/delete:
post:
tags: [附件管理]
summary: 删除附件
description: |
仅允许 `ManagePlatform` 用户访问。
按 `attachments_id` 真删除附件；若附件已被 `tbl_document.document_image` 或 `document_video` 引用，则拒绝删除。
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AttachmentDetailRequest'
responses:
'200':
description: 删除成功
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ApiResponse'
- type: object
properties:
data:
type: object
properties:
attachments_id:
type: string
'400':
description: 参数错误、附件已被文档引用或删除失败
'401':
description: token 无效或已过期
'403':
description: 非 ManagePlatform 用户无权访问
'404':
description: 未找到待删除附件
'415':
description: 请求体必须为 application/json
'429':
description: 重复请求过于频繁
/pb/api/document/list:
post:
tags: [文档管理]
summary: 查询文档列表
description: |
仅允许 `ManagePlatform` 用户访问。
支持按标题、摘要、关键词等字段模糊搜索，并可按 `document_status`、`document_type` 过滤。
返回结果会自动根据 `document_image`、`document_video` 关联 `tbl_attachments`，
额外补充 `document_image_url`、`document_video_url` 以及对应附件对象。
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentListRequest'
responses:
'200':
description: 查询成功
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ApiResponse'
- type: object
properties:
data:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/DocumentRecord'
'401':
description: token 无效或已过期
'403':
description: 非 ManagePlatform 用户无权访问
'415':
description: 请求体必须为 application/json
/pb/api/document/detail:
post:
tags: [文档管理]
summary: 查询文档详情
description: |
仅允许 `ManagePlatform` 用户访问。
按 `document_id` 查询单条文档，并返回与附件表联动解析后的文件流链接。
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentDetailRequest'
responses:
'200':
description: 查询成功
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ApiResponse'
- type: object
properties:
data:
$ref: '#/components/schemas/DocumentRecord'
'400':
description: 参数错误
'401':
description: token 无效或已过期
'403':
description: 非 ManagePlatform 用户无权访问
'404':
description: 未找到对应文档
'415':
description: 请求体必须为 application/json
/pb/api/document/create:
post:
tags: [文档管理]
summary: 新增文档
description: |
仅允许 `ManagePlatform` 用户访问。
`document_id` 可选；未传时服务端自动生成。
`document_image`、`document_video` 需传入已存在于 `tbl_attachments` 的 `attachments_id`。
成功后会同步写入一条 `tbl_document_operation_history`，操作类型为 `create`。
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentMutationRequest'
responses:
'200':
description: 新增成功
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ApiResponse'
- type: object
properties:
data:
$ref: '#/components/schemas/DocumentRecord'
'400':
description: 参数错误、附件不存在或文档创建失败
'401':
description: token 无效或已过期
'403':
description: 非 ManagePlatform 用户无权访问
'415':
description: 请求体必须为 application/json
'429':
description: 重复请求过于频繁
/pb/api/document/update:
post:
tags: [文档管理]
summary: 修改文档
description: |
仅允许 `ManagePlatform` 用户访问。
按 `document_id` 定位现有文档并更新；若传入 `document_image`、`document_video`，则必须是已存在的 `attachments_id`。
成功后会同步写入一条 `tbl_document_operation_history`，操作类型为 `update`。
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentMutationRequest'
responses:
'200':
description: 修改成功
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ApiResponse'
- type: object
properties:
data:
$ref: '#/components/schemas/DocumentRecord'
'400':
description: 参数错误、附件不存在或修改失败
'401':
description: token 无效或已过期
'403':
description: 非 ManagePlatform 用户无权访问
'404':
description: 未找到待修改文档
'415':
description: 请求体必须为 application/json
'429':
description: 重复请求过于频繁
/pb/api/document/delete:
post:
tags: [文档管理]
summary: 删除文档
description: |
仅允许 `ManagePlatform` 用户访问。
按 `document_id` 真删除文档，并在删除前同步写入一条 `tbl_document_operation_history`，操作类型为 `delete`。
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentDeleteRequest'
responses:
'200':
description: 删除成功
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ApiResponse'
- type: object
properties:
data:
type: object
properties:
document_id:
type: string
'400':
description: 参数错误或删除失败
'401':
description: token 无效或已过期
'403':
description: 非 ManagePlatform 用户无权访问
'404':
description: 未找到待删除文档
'415':
description: 请求体必须为 application/json
'429':
description: 重复请求过于频繁
/pb/api/document-history/list:
post:
tags: [文档历史]
summary: 查询文档操作历史
description: |
仅允许 `ManagePlatform` 用户访问。
若 body 传入 `document_id`，则仅查询该文档的历史；否则返回全部文档操作历史，按创建时间倒序排列。
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentHistoryListRequest'
responses:
'200':
description: 查询成功
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ApiResponse'
- type: object
properties:
data:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/DocumentHistoryRecord'
'401':
description: token 无效或已过期
'403':
description: 非 ManagePlatform 用户无权访问
'415':
description: 请求体必须为 application/json