feat: 规范化PocketBase数据库文档与原生API访问
- 将数据库文档拆分为按collection命名的标准文件，统一格式 - 补充tbl_company、tbl_system_dict等表的原生访问规则 - 新增users_tag、document_create等字段 - 优化用户资料更新接口，支持非必填字段 - 添加公司原生API测试脚本 - 归档本次变更至OpenSpec
This commit is contained in:
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-03-29
|
||||
@@ -0,0 +1,56 @@
|
||||
## Overview
|
||||
|
||||
本次变更是一次“文档基线收敛 + OpenSpec 补记”。运行时 schema 已经完成修改，因此设计重点不是实现新逻辑，而是把现有真实状态沉淀成可检索、可归档、可继续维护的标准资料。
|
||||
|
||||
## Documentation Strategy
|
||||
|
||||
### Per-collection database docs
|
||||
|
||||
数据库结构文档统一拆成按 collection 命名的单文件：
|
||||
|
||||
- `pb_tbl_system_dict.md`
|
||||
- `pb_tbl_company.md`
|
||||
- `pb_tbl_attachments.md`
|
||||
- `pb_tbl_document.md`
|
||||
- `pb_tbl_document_operation_history.md`
|
||||
- `pb_tbl_auth_users.md`
|
||||
- `pb_tbl_auth_resources.md`
|
||||
- `pb_tbl_auth_roles.md`
|
||||
- `pb_tbl_auth_role_perms.md`
|
||||
- `pb_tbl_auth_user_overrides.md`
|
||||
- `pb_tbl_auth_row_scopes.md`
|
||||
|
||||
混合型老文档删除，避免一张表同时出现在多份说明中。
|
||||
|
||||
### Uniform format
|
||||
|
||||
每份文档统一包含以下章节：
|
||||
|
||||
1. 来源
|
||||
2. 类型
|
||||
3. 读写规则
|
||||
4. 表用途
|
||||
5. 字段清单
|
||||
6. 索引
|
||||
7. 补充约定
|
||||
|
||||
字段信息以线上实际 collection 回读为主，脚本为辅；这能规避脚本历史遗留误差。
|
||||
|
||||
## OpenSpec Recording Strategy
|
||||
|
||||
### pocketbase-native-data-access
|
||||
|
||||
记录当前项目允许直接走 PocketBase 原生 API / SDK 的边界：
|
||||
|
||||
- `tbl_company` 公开创建与公开列表 / 条件查询
|
||||
- `tbl_system_dict` 公开读
|
||||
- `tbl_document` 公开读
|
||||
|
||||
### pocketbase-schema-docs
|
||||
|
||||
记录数据库结构文档必须采用按表命名和统一格式的规范，避免未来继续出现零散说明。
|
||||
|
||||
## Validation
|
||||
|
||||
- 文档字段以线上 PocketBase collection 回读结果为准
|
||||
- OpenSpec 变更在归档前完成 `openspec validate`
|
||||
@@ -0,0 +1,29 @@
|
||||
## Why
|
||||
|
||||
近期项目连续完成了 PocketBase schema 扩展、原生公开查询、附件统一存储、文档字段扩展和用户字段扩展，但 `docs/` 中与数据库结构相关的文档仍然混合在少量总表文件里，命名和格式也不统一。与此同时，这批 schema 与原生数据访问能力还没有完整计入 OpenSpec，后续维护会出现“线上结构、脚本结构、文档结构、OpenSpec 记录”四套口径不一致的问题。
|
||||
|
||||
## What Changes
|
||||
|
||||
- 将 `docs/` 中数据库结构相关文档拆分为按 collection 命名的标准文件，统一采用 `pb_tbl_xxx.md` 命名。
|
||||
- 统一数据库文档格式，按“来源 / 类型 / 读写规则 / 表用途 / 字段清单 / 索引 / 补充约定”组织内容。
|
||||
- 补充此前未进入 OpenSpec 的 PocketBase 原生数据访问与 schema 更新记录，包括：
|
||||
- `tbl_company` 的公开创建 / 列表 / 条件查询约定
|
||||
- `tbl_system_dict` 与 `tbl_document` 的公开读规则
|
||||
- `company_owner_openid`、地区编码字段、`users_tag`、`document_file`、`document_create` 等新增字段
|
||||
- 归档本次规范化工作，作为后续数据库文档与原生 API 文档的基线。
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
- `pocketbase-native-data-access`: 记录原生 PocketBase 公开读写边界与标准查询方式。
|
||||
- `pocketbase-schema-docs`: 规定数据库结构文档的命名与组织方式。
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- None.
|
||||
|
||||
## Impact
|
||||
|
||||
- 受影响目录：`docs/`、`openspec/`
|
||||
- 不涉及新的运行时代码发布，但会影响后续 schema 变更和接口文档维护方式
|
||||
@@ -0,0 +1,34 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: PocketBase native company access SHALL expose a stable public create and query boundary
|
||||
|
||||
The system SHALL allow native PocketBase clients to create company records publicly and to query company records through standard PocketBase records APIs, while privileged mutations remain restricted to management users.
|
||||
|
||||
#### Scenario: Public client creates company record
|
||||
|
||||
- **WHEN** a client calls the native PocketBase create-record API for `tbl_company`
|
||||
- **THEN** the request SHALL succeed without requiring a management token
|
||||
|
||||
#### Scenario: Public client queries company list
|
||||
|
||||
- **WHEN** a client calls the native PocketBase list-records API for `tbl_company`
|
||||
- **THEN** the request SHALL return company records using standard PocketBase pagination parameters
|
||||
|
||||
#### Scenario: Management user updates company record
|
||||
|
||||
- **WHEN** a client attempts to update or delete `tbl_company`
|
||||
- **THEN** PocketBase SHALL allow the operation only for management users or administrators
|
||||
|
||||
### Requirement: Public dictionary and document reads SHALL be supported through native PocketBase APIs
|
||||
|
||||
The system SHALL allow native PocketBase clients to read `tbl_system_dict` and `tbl_document` records without requiring application hooks tokens, while write operations remain restricted.
|
||||
|
||||
#### Scenario: Public client reads dictionary records
|
||||
|
||||
- **WHEN** a client calls the native PocketBase records API for `tbl_system_dict`
|
||||
- **THEN** list and view operations SHALL be readable without authentication
|
||||
|
||||
#### Scenario: Public client reads document records
|
||||
|
||||
- **WHEN** a client calls the native PocketBase records API for `tbl_document`
|
||||
- **THEN** list and view operations SHALL be readable without authentication
|
||||
@@ -0,0 +1,29 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Database structure docs SHALL be maintained per PocketBase collection
|
||||
|
||||
The project SHALL document PocketBase schema structures in per-collection markdown files under `docs/`, and each file SHALL use the collection name in the filename.
|
||||
|
||||
#### Scenario: Collection doc is named by collection
|
||||
|
||||
- **WHEN** a PocketBase collection has a dedicated schema document
|
||||
- **THEN** the document filename SHALL follow the `pb_tbl_xxx.md` naming convention
|
||||
|
||||
#### Scenario: Mixed schema docs are replaced
|
||||
|
||||
- **WHEN** older documents combine multiple unrelated collection structures in one file
|
||||
- **THEN** the project SHALL replace them with per-collection docs to avoid conflicting schema descriptions
|
||||
|
||||
### Requirement: Database structure docs SHALL use a uniform format
|
||||
|
||||
Each PocketBase schema document SHALL use the same section structure so readers can quickly compare tables and verify field and index changes.
|
||||
|
||||
#### Scenario: Reader opens a schema document
|
||||
|
||||
- **WHEN** a reader opens any database structure document under `docs/`
|
||||
- **THEN** the document SHALL include source, collection type, access rule summary, purpose, field table, index table, and supplementary notes
|
||||
|
||||
#### Scenario: Schema docs reflect live collection state
|
||||
|
||||
- **WHEN** the project documents a collection structure
|
||||
- **THEN** the field list and rule summary SHALL be aligned with the current live PocketBase collection state whenever practical
|
||||
@@ -0,0 +1,19 @@
|
||||
## 1. 数据库文档整理
|
||||
|
||||
- [x] 1.1 盘点 `docs/` 中和数据库结构直接相关的文档。
|
||||
- [x] 1.2 将混合型结构文档拆分为按 collection 命名的标准文件。
|
||||
- [x] 1.3 统一所有数据库结构文档格式。
|
||||
- [x] 1.4 删除被替代的旧文档文件。
|
||||
|
||||
## 2. 基于线上结构回读修正文档
|
||||
|
||||
- [x] 2.1 回读线上 `tbl_system_dict`、`tbl_company`、`tbl_attachments`、`tbl_document`、`tbl_document_operation_history`。
|
||||
- [x] 2.2 回读线上 `tbl_auth_*` 系列 collection。
|
||||
- [x] 2.3 以线上结果修正字段、索引和权限描述。
|
||||
|
||||
## 3. OpenSpec 补记与归档
|
||||
|
||||
- [x] 3.1 为未计入 OpenSpec 的原生数据访问与 schema 文档规范补建 change。
|
||||
- [x] 3.2 为 `pocketbase-native-data-access` 编写 delta spec。
|
||||
- [x] 3.3 为 `pocketbase-schema-docs` 编写 delta spec。
|
||||
- [x] 3.4 校验并归档本次 change。
|
||||
38
openspec/specs/pocketbase-native-data-access/spec.md
Normal file
38
openspec/specs/pocketbase-native-data-access/spec.md
Normal file
@@ -0,0 +1,38 @@
|
||||
# pocketbase-native-data-access Specification
|
||||
|
||||
## Purpose
|
||||
TBD - created by archiving change normalize-pocketbase-schema-docs. Update Purpose after archive.
|
||||
## Requirements
|
||||
### Requirement: PocketBase native company access SHALL expose a stable public create and query boundary
|
||||
|
||||
The system SHALL allow native PocketBase clients to create company records publicly and to query company records through standard PocketBase records APIs, while privileged mutations remain restricted to management users.
|
||||
|
||||
#### Scenario: Public client creates company record
|
||||
|
||||
- **WHEN** a client calls the native PocketBase create-record API for `tbl_company`
|
||||
- **THEN** the request SHALL succeed without requiring a management token
|
||||
|
||||
#### Scenario: Public client queries company list
|
||||
|
||||
- **WHEN** a client calls the native PocketBase list-records API for `tbl_company`
|
||||
- **THEN** the request SHALL return company records using standard PocketBase pagination parameters
|
||||
|
||||
#### Scenario: Management user updates company record
|
||||
|
||||
- **WHEN** a client attempts to update or delete `tbl_company`
|
||||
- **THEN** PocketBase SHALL allow the operation only for management users or administrators
|
||||
|
||||
### Requirement: Public dictionary and document reads SHALL be supported through native PocketBase APIs
|
||||
|
||||
The system SHALL allow native PocketBase clients to read `tbl_system_dict` and `tbl_document` records without requiring application hooks tokens, while write operations remain restricted.
|
||||
|
||||
#### Scenario: Public client reads dictionary records
|
||||
|
||||
- **WHEN** a client calls the native PocketBase records API for `tbl_system_dict`
|
||||
- **THEN** list and view operations SHALL be readable without authentication
|
||||
|
||||
#### Scenario: Public client reads document records
|
||||
|
||||
- **WHEN** a client calls the native PocketBase records API for `tbl_document`
|
||||
- **THEN** list and view operations SHALL be readable without authentication
|
||||
|
||||
33
openspec/specs/pocketbase-schema-docs/spec.md
Normal file
33
openspec/specs/pocketbase-schema-docs/spec.md
Normal file
@@ -0,0 +1,33 @@
|
||||
# pocketbase-schema-docs Specification
|
||||
|
||||
## Purpose
|
||||
TBD - created by archiving change normalize-pocketbase-schema-docs. Update Purpose after archive.
|
||||
## Requirements
|
||||
### Requirement: Database structure docs SHALL be maintained per PocketBase collection
|
||||
|
||||
The project SHALL document PocketBase schema structures in per-collection markdown files under `docs/`, and each file SHALL use the collection name in the filename.
|
||||
|
||||
#### Scenario: Collection doc is named by collection
|
||||
|
||||
- **WHEN** a PocketBase collection has a dedicated schema document
|
||||
- **THEN** the document filename SHALL follow the `pb_tbl_xxx.md` naming convention
|
||||
|
||||
#### Scenario: Mixed schema docs are replaced
|
||||
|
||||
- **WHEN** older documents combine multiple unrelated collection structures in one file
|
||||
- **THEN** the project SHALL replace them with per-collection docs to avoid conflicting schema descriptions
|
||||
|
||||
### Requirement: Database structure docs SHALL use a uniform format
|
||||
|
||||
Each PocketBase schema document SHALL use the same section structure so readers can quickly compare tables and verify field and index changes.
|
||||
|
||||
#### Scenario: Reader opens a schema document
|
||||
|
||||
- **WHEN** a reader opens any database structure document under `docs/`
|
||||
- **THEN** the document SHALL include source, collection type, access rule summary, purpose, field table, index table, and supplementary notes
|
||||
|
||||
#### Scenario: Schema docs reflect live collection state
|
||||
|
||||
- **WHEN** the project documents a collection structure
|
||||
- **THEN** the field list and rule summary SHALL be aligned with the current live PocketBase collection state whenever practical
|
||||
|
||||
Reference in New Issue
Block a user