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
|
||||
60
openspec/specs/document-manage-console/spec.md
Normal file
60
openspec/specs/document-manage-console/spec.md
Normal file
@@ -0,0 +1,60 @@
|
||||
# document-manage-console Specification
|
||||
|
||||
## Purpose
|
||||
定义 `/pb/manage/document-manage` 的编辑、上传、反馈与附件管理体验，确保文档管理页在图片、视频、文件三类附件下保持一致交互。
|
||||
## Requirements
|
||||
### Requirement: Document management SHALL support three attachment categories
|
||||
|
||||
The document management console SHALL provide separate upload and editing areas for image attachments, video attachments, and generic file attachments, and the three categories SHALL all persist attachment IDs to the document record.
|
||||
|
||||
#### Scenario: User uploads generic files to a document
|
||||
|
||||
- **WHEN** a management user adds files in the file attachment area and saves the document
|
||||
- **THEN** the saved document SHALL persist those attachment IDs in `document_file`
|
||||
|
||||
#### Scenario: Existing attachments are editable by category
|
||||
|
||||
- **WHEN** a management user opens a document in edit mode
|
||||
- **THEN** the page SHALL show existing images, videos, and files in their corresponding sections and allow removing them from the document
|
||||
|
||||
### Requirement: Document editor visibility and state SHALL follow editing intent
|
||||
|
||||
The document management page SHALL load with the document list only, keep the editor hidden until the user enters create or edit mode, and SHALL remain in the current editing context after upload or save operations.
|
||||
|
||||
#### Scenario: Page loads without editor
|
||||
|
||||
- **WHEN** the user first opens `/pb/manage/document-manage`
|
||||
- **THEN** the page SHALL show the document list and SHALL NOT show the editor section until create or edit mode is entered
|
||||
|
||||
#### Scenario: Save keeps current editing context
|
||||
|
||||
- **WHEN** the user successfully creates or updates a document
|
||||
- **THEN** the page SHALL stay on the current document editing context instead of clearing the form and forcing a return to blank create mode
|
||||
|
||||
#### Scenario: Upload does not reset editor mode
|
||||
|
||||
- **WHEN** the user uploads attachments while editing a document
|
||||
- **THEN** the page SHALL keep the current editor state and SHALL NOT implicitly switch modes
|
||||
|
||||
### Requirement: Document management SHALL provide immediate user feedback
|
||||
|
||||
The document management console SHALL show operation feedback both in the global page status area and near the save actions so that users receive confirmation or error context without scrolling.
|
||||
|
||||
#### Scenario: Local save feedback is visible
|
||||
|
||||
- **WHEN** a save or upload request succeeds or fails
|
||||
- **THEN** the page SHALL show the status message below the save controls in addition to the top-level message area
|
||||
|
||||
#### Scenario: Long-running requests show blocking feedback
|
||||
|
||||
- **WHEN** the page is waiting for a long-running upload, save, delete, or query response
|
||||
- **THEN** it SHALL show a full-screen loading mask so the user can tell the action is in progress
|
||||
|
||||
### Requirement: Document and dictionary images SHALL support full-screen preview
|
||||
|
||||
Image previews rendered in the management pages SHALL support opening the original image in a full-screen preview overlay.
|
||||
|
||||
#### Scenario: User previews an image
|
||||
|
||||
- **WHEN** the user clicks an image preview in document or dictionary management
|
||||
- **THEN** the page SHALL open a full-screen overlay showing the original image and SHALL allow closing it with explicit controls
|
||||
60
openspec/specs/sdk-collection-permissions/spec.md
Normal file
60
openspec/specs/sdk-collection-permissions/spec.md
Normal file
@@ -0,0 +1,60 @@
|
||||
# sdk-collection-permissions Specification
|
||||
|
||||
## Purpose
|
||||
定义面向 `ManagePlatform` 用户的 SDK 直连权限配置能力，使角色绑定与 collection CRUD 授权能够通过 hooks 页面完成并映射到 PocketBase rules。
|
||||
## Requirements
|
||||
### Requirement: Role-based SDK direct access SHALL be configurable from hooks pages
|
||||
|
||||
The system SHALL provide a hooks-mounted management page that allows `ManagePlatform` users to assign roles to auth users and configure PocketBase SDK direct-access CRUD permissions by role and collection.
|
||||
|
||||
#### Scenario: Role is assigned to an auth user
|
||||
|
||||
- **WHEN** a management user selects a role for an auth user and saves the assignment
|
||||
- **THEN** the system SHALL persist the role mapping used by the SDK direct-access permission model
|
||||
|
||||
#### Scenario: Collection operation is granted by role
|
||||
|
||||
- **WHEN** a management user authorizes a role for a collection operation such as list, view, create, update, or delete
|
||||
- **THEN** the corresponding PocketBase collection access rule SHALL be updated for that role
|
||||
|
||||
### Requirement: Role identity SHALL be name-based in the management UI
|
||||
|
||||
The hooks permission page SHALL hide internal role IDs from the UI and present role assignments and selectors by role name only.
|
||||
|
||||
#### Scenario: Current role display hides role ID
|
||||
|
||||
- **WHEN** a management user views the role assignment page
|
||||
- **THEN** current role labels and selectors SHALL show the role name without exposing the internal role ID
|
||||
|
||||
### Requirement: Permission editing SHALL be immediate and constrained by rule type
|
||||
|
||||
The permission page SHALL save authorization changes immediately after a checkbox toggle, SHALL render CRUD labels in Chinese, and SHALL prevent editing for operations already governed by public or custom rules.
|
||||
|
||||
#### Scenario: Authorization change auto-saves
|
||||
|
||||
- **WHEN** a management user toggles an editable permission checkbox
|
||||
- **THEN** the change SHALL be persisted immediately without requiring a separate save button
|
||||
|
||||
#### Scenario: Public operation is read-only
|
||||
|
||||
- **WHEN** a collection operation is already publicly accessible
|
||||
- **THEN** the page SHALL show a brief `可公开访问` notice and SHALL NOT render an editable authorization checkbox for that operation
|
||||
|
||||
#### Scenario: Custom operation is read-only
|
||||
|
||||
- **WHEN** a collection operation is governed by a custom rule
|
||||
- **THEN** the page SHALL show `当前操作使用 custom 规则，禁止修改` and SHALL NOT render an editable authorization checkbox for that operation
|
||||
|
||||
### Requirement: Collection-level bulk selection SHALL respect editable operations only
|
||||
|
||||
The permission page SHALL provide a collection-level select-all control that applies only to editable operations, and the control SHALL be disabled when the collection has no editable operations.
|
||||
|
||||
#### Scenario: Collection select-all grants editable operations
|
||||
|
||||
- **WHEN** a management user enables the collection-level select-all control
|
||||
- **THEN** all editable CRUD operations for the current role on that collection SHALL be granted and auto-saved
|
||||
|
||||
#### Scenario: Collection select-all is disabled when nothing is editable
|
||||
|
||||
- **WHEN** every operation in a collection is either public, custom, or otherwise not editable
|
||||
- **THEN** the collection-level select-all control SHALL be disabled
|
||||
Reference in New Issue
Block a user