feat: 添加 PocketBase MiniApp 公司 API 文档和文件字段迁移脚本
- 新增 openapi-miniapp-company.yaml 文件,定义 tbl_company 的基础 CRUD 接口文档,包括查询、创建、更新和删除公司记录的详细描述和示例。 - 新增 pocketbase.file-fields-to-attachments.js 脚本,用于迁移 PocketBase 中的文件字段到文本字段,并处理 tbl_attachments 集合的公开规则。
This commit is contained in:
65
openspec/specs/attachment-backed-media/spec.md
Normal file
65
openspec/specs/attachment-backed-media/spec.md
Normal file
@@ -0,0 +1,65 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user