feat: 添加 PocketBase MiniApp 公司 API 文档和文件字段迁移脚本

- 新增 openapi-miniapp-company.yaml 文件，定义 tbl_company 的基础 CRUD 接口文档，包括查询、创建、更新和删除公司记录的详细描述和示例。 - 新增 pocketbase.file-fields-to-attachments.js 脚本，用于迁移 PocketBase 中的文件字段到文本字段，并处理 tbl_attachments 集合的公开规则。
2026-03-28 15:13:04 +08:00
parent eaf282ea24
commit 51a90260e4
50 changed files with 4250 additions and 113 deletions
--- a/docs/ARCHIVE.md
+++ b/docs/ARCHIVE.md
@@ -2,6 +2,110 @@

 ## 归档日期

+- 2026-03-28
+
+## 归档范围
+
+本次归档覆盖 PocketBase hooks 项目在附件统一存储、文档管理页增强、字典项图片、用户图片字段附件化、SDK 直连权限页、文档文件字段 `document_file`、大文件上传 body limit 修复、以及对应 OpenAPI / 表结构文档同步方面的工作，涉及：
+
+- 所有业务文件统一收敛到 `tbl_attachments`
+- 业务表只保存 `attachments_id`，并由 hooks 联表返回文件流链接
+- `tbl_document` 新增 `document_file`，与 `document_image`、`document_video` 一样支持多附件和 `|` 分隔存储
+- `manage/document-manage` 页面新增文件附件区、初始隐藏编辑区、保存后保持当前编辑态、局部状态提示、拖拽上传与全屏图片预览
+- `manage/dictionary-manage` 页面支持字典枚举项图片上传和全屏查看原图
+- `manage/sdk-permission-manage` 页面支持按角色配置 collection CRUD 直连权限，并优化为即时保存
+- 上传路由显式放宽 PocketBase custom route `bodyLimit`
+- 使用 `POCKETBASE_AUTH_TOKEN` 在线补齐 `tbl_document.document_file`
+- 新增 OpenSpec 归档目录 `openspec/changes/archive/2026-03-28-pocketbase-manage-media-and-sdk-permissions/`
+
+---
+
+## 一、附件集中存储
+
+### 1. 附件表作为唯一文件存储点
+
+- 仅 `tbl_attachments.attachments_link` 保留真实 `file` 字段
+- 其他业务表不再保存实际文件
+- 文档、字典、用户图片字段统一改为保存 `attachments_id`
+
+### 2. 附件回读策略
+
+hooks 查询时统一联查 `tbl_attachments`，并补充：
+
+- 文件流链接
+- 下载链接
+- 附件元数据对象
+
+适用对象包括：
+
+- 文档图片 / 视频 / 文件
+- 字典枚举项图片
+- 用户头像 / 身份图 / 资质图
+
+### 3. 附件访问控制
+
+- PocketBase 原生 `tbl_attachments` 已放开公开读取与下载
+- hooks 层原有 `ManagePlatform` 限制保持不变
+- 业务访问控制继续由保存附件 ID 的业务表承担
+
+---
+
+## 二、文档管理增强
+
+### 1. `tbl_document` 新增 `document_file`
+
+- 新字段：`document_file`
+- 类型：`text`
+- 用途：保存多个文件类 `attachments_id`
+- 存储格式：`id1|id2|id3`
+
+### 2. 文档管理页行为
+
+- 首次进入页面时只显示列表，不显示编辑区
+- 点击“新建模式”或“编辑”后才进入编辑区
+- 保存成功后保持当前文档编辑态，不再强制清空回到新建
+- 保存 / 报错信息同时显示在顶部与保存按钮下方
+- 图片、视频、文件三块附件区都支持拖拽上传
+
+### 3. 上传链路修复
+
+- 上传接口继续使用 `/pb/api/attachment/upload`
+- 为自定义路由显式增加更大的 `bodyLimit`
+- 解决了文件未超过数据库与网关限制但仍在 hooks 层被 413 拒绝的问题
+
+---
+
+## 三、SDK 直连权限管理
+
+### 1. 管理页能力
+
+- 新增 `/pb/manage/sdk-permission-manage`
+- 支持创建角色后按角色给 `tbl_auth_users` 用户授权
+- 支持逐 collection 配置 `list / view / create / update / delete`
+
+### 2. 页面交互约束
+
+- 页面不显示角色 ID，只显示角色名称
+- 勾选权限后立即保存
+- `public` 和 `custom` 规则不允许在页面里继续勾选改写
+- 支持集合级 `全选`
+- 当某集合下所有操作都不可编辑时，`全选` 自动禁用
+
+---
+
+## 四、OpenSpec 记录
+
+本次新增的 OpenSpec 记录包括：
+
+- `openspec/specs/attachment-backed-media/spec.md`
+- `openspec/specs/document-manage-console/spec.md`
+- `openspec/specs/sdk-collection-permissions/spec.md`
+- `openspec/changes/archive/2026-03-28-pocketbase-manage-media-and-sdk-permissions/`
+
+---
+
+## 归档日期
+
 - 2026-03-23

 ## 归档范围
--- a/docs/api.md
+++ b/docs/api.md
@@ -5,8 +5,8 @@
 本文档描述当前项目中**已经真实实现**并可直接调用的后端接口。
 当前接口统一特征如下：

- 基础路径（生产）：`https://bai-api.blv-oa.com/api`
- 基础路径（本地）：`http://localhost:3000/api`
+- 基础路径（生产）：`https://bai-api.blv-oa.com/pb/api`
+- 基础路径（本地）：`http://localhost:8090/pb/api`
 - 响应格式：JSON
 - 业务响应结构统一为：`code`、`msg`、`data`
 - 当前公开接口统一使用 **POST** 方法
@@ -134,7 +134,8 @@
      "users_name": "张三",
      "users_phone": "13800138000",
      "users_phone_masked": "138****8000",
-      "users_picture": "https://example.com/avatar.png",
+      "users_picture": "ATT-1743123456789-abc123",
+      "users_picture_url": "https://bai-api.blv-oa.com/pb/api/files/pbc_xxx/recordId/avatar.png",
      "openid": "oAbCdEfGh123456789",
      "company_id": "C10001",
      "company": null,
@@ -162,7 +163,10 @@
 {
  "users_name": "张三",
  "users_phone_code": "2b7d9f2e3c4a5b6d7e8f",
-  "users_picture": "https://example.com/avatar.png"
+  "users_picture": "ATT-1743123456789-abc123",
+  "users_id_pic_a": "ATT-1743123456789-id-a",
+  "users_id_pic_b": "ATT-1743123456789-id-b",
+  "users_title_picture": "ATT-1743123456789-title"
 }
 ```

@@ -172,7 +176,10 @@
 |---|---|---|---|
 | `users_name` | string | 是 | 用户姓名 |
 | `users_phone_code` | string | 是 | 微信手机号获取凭证 code，后端将据此换取真实手机号 |
-| `users_picture` | string | 是 | 用户头像 URL |
+| `users_picture` | string | 是 | 用户头像附件的 `attachments_id` |
+| `users_id_pic_a` | string | 否 | 证件正面附件的 `attachments_id` |
+| `users_id_pic_b` | string | 否 | 证件反面附件的 `attachments_id` |
+| `users_title_picture` | string | 否 | 资质附件的 `attachments_id` |

 ### 处理逻辑

@@ -181,6 +188,7 @@
 - 不再从 body 读取 `users_wx_code`
 - 使用 `users_phone_code` 调微信官方接口换取真实手机号
 - 将真实手机号写入数据库字段 `users_phone`
+- `users_picture`、`users_id_pic_a`、`users_id_pic_b`、`users_title_picture` 均按 `attachments_id` 存储，服务端查询用户信息时会自动补充对应文件流链接
 - 若用户首次从“三项资料均为空”变为“三项资料均完整”，则将 `users_type` 从 `游客` 升级为 `注册用户`
 - 返回更新后的完整用户信息

@@ -198,7 +206,14 @@
      "users_name": "张三",
      "users_phone": "13800138000",
      "users_phone_masked": "138****8000",
-      "users_picture": "https://example.com/avatar.png",
+      "users_picture": "ATT-1743123456789-abc123",
+      "users_picture_url": "https://bai-api.blv-oa.com/pb/api/files/pbc_xxx/recordId/avatar.png",
+      "users_id_pic_a": "ATT-1743123456789-id-a",
+      "users_id_pic_a_url": "https://bai-api.blv-oa.com/pb/api/files/pbc_xxx/recordId/id-a.png",
+      "users_id_pic_b": "ATT-1743123456789-id-b",
+      "users_id_pic_b_url": "https://bai-api.blv-oa.com/pb/api/files/pbc_xxx/recordId/id-b.png",
+      "users_title_picture": "ATT-1743123456789-title",
+      "users_title_picture_url": "https://bai-api.blv-oa.com/pb/api/files/pbc_xxx/recordId/title.png",
      "openid": "oAbCdEfGh123456789",
      "company_id": "",
      "company": null,
--- a/docs/pb_document_tables.md
+++ b/docs/pb_document_tables.md
@@ -4,12 +4,13 @@

 补充约定：

- `document_image`、`document_video` 只保存关联的 `attachments_id`，不直接存文件；当存在多个附件时，统一使用 `|` 分隔，例如：`ATT-001|ATT-002|ATT-003`。
+- `document_image`、`document_video`、`document_file` 只保存关联的 `attachments_id`，不直接存文件；当存在多个附件时，统一使用 `|` 分隔，例如：`ATT-001|ATT-002|ATT-003`。
 - `document_type` 使用多选字符串持久化，但格式特殊：`system_dict_id@dict_word_enum|system_dict_id@dict_word_enum`；前端显示时用枚举值描述，存库时保留该组合值。
 - `document_keywords`、`document_product_categories`、`document_application_scenarios`、`document_hotel_type` 统一使用竖线分隔字符串，例如：`分类A|分类B|分类C`。
 - `document_status` 仅允许 `有效`、`过期` 两种值，并由系统根据生效日期与到期日期自动计算；当两者都为空时默认 `有效`。
 - `document_owner` 的业务含义为“上传者openid”。
 - `attachments_link` 是 PocketBase `file` 字段，保存附件本体；访问链接由 PocketBase 根据记录和文件名生成。
+- `tbl_attachments` 的文件查看/下载权限应保持公开；真正的业务访问控制交由引用 `attachments_id` 的业务表和业务接口决定。
 - 文档字段中，面向用户填写的字段里只有 `document_title`、`document_type` 设为必填，其余字段均允许为空。

 ---
@@ -55,6 +56,7 @@
 | document_content | text | 正文内容，保存 Markdown 原文 |
 | document_image | text | 关联多个 `attachments_id`，使用 `|` 分隔 |
 | document_video | text | 关联多个 `attachments_id`，使用 `|` 分隔 |
+| document_file | text | 关联多个 `attachments_id`，使用 `|` 分隔 |
 | document_owner | text | 上传者openid |
 | document_relation_model | text | 关联机型/模型标识 |
 | document_keywords | text | 关键词，多选后用 `|` 分隔保存 |
--- a/docs/tbl_auth_tables.md
+++ b/docs/tbl_auth_tables.md
@@ -32,10 +32,10 @@
 | `company_id` | `text` | 否 | 公司 ID |
 | `users_parent_id` | `text` | 否 | 上级用户 ID |
 | `users_promo_code` | `text` | 否 | 推广码 |
-| `users_id_pic_a` | `file` | 否 | 证件照正面，`maxSelect: 1`，允许 `jpeg/png/webp` |
-| `users_id_pic_b` | `file` | 否 | 证件照反面，`maxSelect: 1`，允许 `jpeg/png/webp` |
-| `users_title_picture` | `file` | 否 | 资质照片，`maxSelect: 1`，允许 `jpeg/png/webp` |
-| `users_picture` | `text` | 否 | 用户头像 |
+| `users_id_pic_a` | `text` | 否 | 保存 `tbl_attachments.attachments_id`，用于关联证件照正面 |
+| `users_id_pic_b` | `text` | 否 | 保存 `tbl_attachments.attachments_id`，用于关联证件照反面 |
+| `users_title_picture` | `text` | 否 | 保存 `tbl_attachments.attachments_id`，用于关联资质照片 |
+| `users_picture` | `text` | 否 | 用户头像，保存 `tbl_attachments.attachments_id` |
 | `usergroups_id` | `text` | 否 | 用户组 ID |

 ### 索引
@@ -187,4 +187,4 @@

 1. `tbl_auth_users` 是 `auth` 集合，除上表字段外，还会受 PocketBase auth 系统字段与认证配置影响。
 2. 当前文档仅以 `script/pocketbase.newpb.js` 为准，不代表线上数据库已经 100% 同步成功。
-3. 若你需要，我可以继续帮你再生成一份“更像数据库设计说明书”的版本，增加字段含义、业务用途、关联关系三列。
+3. 若你需要，我可以继续帮你再生成一份“更像数据库设计说明书”的版本，增加字段含义、业务用途、关联关系三列。