Web_BAI_Manage_ApiServer/openspec/specs/attachment-backed-media/spec.md

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