66 lines
3.7 KiB
Markdown
66 lines
3.7 KiB
Markdown
|
# 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
|