# attachment-backed-media Specification

## Purpose
定义 PocketBase hooks 项目中“真实文件只存于 `tbl_attachments`，业务表仅保存附件 ID，并由 hooks 回读文件流链接与元数据”的统一附件模型。
## Requirements
### Requirement: Business records SHALL reference attachments by ID

The system SHALL store business media references as `tbl_attachments.attachments_id` values, and `tbl_attachments.attachments_link` SHALL remain the only business file field that stores actual uploaded file data.

#### Scenario: Document media is stored by attachment ID

- **WHEN** a document is created or updated with images, videos, or files
- **THEN** the document record SHALL store attachment IDs in `document_image`, `document_video`, and `document_file` instead of raw file payloads

#### Scenario: Dictionary item images are stored by attachment ID

- **WHEN** a dictionary item image is uploaded from the dictionary management page
- **THEN** the dictionary record SHALL persist the returned `attachments_id` in the aggregated dictionary image field

#### Scenario: User image fields are stored by attachment ID

- **WHEN** user profile-related image fields are written through hooks
- **THEN** `users_picture`, `users_id_pic_a`, `users_id_pic_b`, and `users_title_picture` SHALL store attachment IDs only

### Requirement: Hooks SHALL resolve attachment metadata for referenced media

The system SHALL resolve attachment-backed fields to include file stream URLs and attachment metadata when hooks return documents, dictionaries, or user records.

#### Scenario: Document query returns attachment-backed links

- **WHEN** a document list or detail request is handled
- **THEN** the response SHALL include attachment-backed URL and metadata fields for images, videos, and files derived from the stored attachment IDs

#### Scenario: Dictionary query returns item image links

- **WHEN** a dictionary list or detail request is handled
- **THEN** each dictionary item with an image SHALL include the stored attachment ID, a resolved file URL, and the corresponding attachment metadata

#### Scenario: User query returns image URLs

- **WHEN** a user-facing hooks response contains attachment-backed image fields
- **THEN** the response SHALL include resolved `..._url` and `..._attachment` fields for those image references

### Requirement: Attachment access SHALL separate read visibility from write control

The system SHALL allow public read access to attachment records and file streams at the PocketBase collection level, while write access SHALL continue to be controlled by hooks and existing `ManagePlatform` restrictions.

#### Scenario: Attachment records are publicly readable

- **WHEN** a client reads `tbl_attachments` through PocketBase list or view access
- **THEN** the collection SHALL allow reading attachment metadata and downloading the linked file stream

#### Scenario: Hooks upload endpoint remains managed

- **WHEN** a client calls the hooks attachment management endpoints
- **THEN** the existing `ManagePlatform` restrictions for hooks-controlled upload and management flows SHALL remain in effect

### Requirement: Attachment upload SHALL support large multipart requests

The hooks attachment upload route SHALL explicitly configure a larger PocketBase custom-route body limit so that large files can pass through the hooks layer without being rejected by the default request size limit.

#### Scenario: Large upload is accepted by custom route

- **WHEN** a client uploads a file larger than the default PocketBase custom-route body threshold to `/pb/api/attachment/upload`
- **THEN** the route SHALL accept the multipart request as long as it remains within the configured hooks and infrastructure limits