## Context

当前 PocketBase hooks 项目已经不再是单一的微信登录接口集合，而是同时承担管理端页面、附件上传、文档管理、字典管理和 PocketBase SDK 直连权限配置。最近一轮需求把“所有业务文件集中存入 `tbl_attachments`”和“管理用户可直接为角色配置 collection CRUD 权限”两个方向一起落地，涉及数据库字段、路由 body limit、返回模型、页面交互和线上 schema 变更。

## Goals / Non-Goals

**Goals:**

- 用 OpenSpec 为已完成能力建立正式归档，明确能力边界。
- 记录“仅 `tbl_attachments` 保存真实文件，其他表只保存附件 ID”的统一模型。
- 记录文档管理页的三类附件与保存体验要求。
- 记录 SDK 权限页的角色驱动授权模型和 UI 约束。

**Non-Goals:**

- 不替代现有 OpenAPI 文档。
- 不重新设计 PocketBase 的 `_superusers` 体系。
- 不把所有复杂业务权限都迁移成 PocketBase 原生 rules 以外的自定义表达式语言。

## Decisions

### 1. 业务文件统一收敛到 `tbl_attachments`

除 `tbl_attachments.attachments_link` 外，不再保留其他业务 `file` 字段。文档、字典、用户资料等业务记录统一保存 `attachments_id`，读取时再由 hooks 反查附件元数据与文件流链接。

这样做的原因：

- 避免多个业务表重复持有文件字段，降低 schema 演化成本。
- 统一附件上传、回读、删除引用校验逻辑。
- 让 PocketBase SDK 与 hooks API 在附件访问上共享同一套标识。

### 2. 多附件字段统一使用 `|` 分隔的文本存储

`document_image`、`document_video`、`document_file` 等多附件字段继续使用 `text`，并以 `|` 分隔多个 `attachments_id`。hooks service 负责序列化、反序列化和联查回读。

这样做的原因：

- 与项目现有字典聚合字段设计风格一致。
- 避免为每类附件单独引入子表或 relation migration。
- 在 PocketBase JSVM hooks 环境里实现最简单直接。

### 3. 大文件上传继续走 hooks 自定义路由，但显式放宽 body limit

上传接口仍使用 `/pb/api/attachment/upload`，并通过 PocketBase custom route 的 `$apis.bodyLimit(...)` 放宽请求体限制。数据库字段 `attachments_link.maxSize` 已解除额外限制，上传链路重点落在自定义路由与网关配置协同。

这样做的原因：

- 保持现有 `ManagePlatform` 鉴权、业务字段补充和返回结构不变。
- 避免直接开放 `tbl_attachments.createRule` 给 SDK 原生写入。

### 4. SDK 直连权限按“角色 -> 集合 -> CRUD”建模

权限页以角色为中心展示每个 collection 的 `list/view/create/update/delete` 五类直连权限，并直接映射到 PocketBase collection rules。页面不显示角色 ID，只显示角色名称；勾选后立即保存；公开和 custom 规则不提供可编辑勾选框。

这样做的原因：

- 用户理解成本比“直接编辑 rule 字符串”更低。
- 保持 `ManagePlatform` 用户通过 hooks 页面管理，而不是要求他们成为 `_superusers`。

## Risks / Trade-offs

- `[PocketBase rule 冲突]` → 如果 collection 已经使用复杂 custom rule，权限页只做只读提示，不强行覆盖。
- `[大文件上传依赖基础设施]` → 即使 hooks 已放宽 body limit，仍需同步保证 Nginx / 反代允许更大请求体。
- `[文本分隔字段的一致性]` → 所有写入都必须经由 service 统一序列化，避免手工写入脏值。
- `[附件公开读取]` → `tbl_attachments` 公开 list/view 使文件流可直接访问，因此真正的业务访问控制必须由保存附件 ID 的业务表承担。

## Migration Plan

1. 通过 schema 脚本和 `POCKETBASE_AUTH_TOKEN` 为 `tbl_document` 增加 `document_file` 字段。
2. 部署更新后的 hooks 路由、service 与管理页面。
3. 校验文档管理页三类附件上传、编辑与回显。
4. 校验 SDK 权限页角色分配、即时保存和 collection rules 同步。
5. 归档到 OpenSpec 与项目既有归档文档。

## Open Questions

- 暂无新的未决问题；当前能力范围已经按现有实现归档。
