Boonlive_RD_Web/Web_BAI_Manage_ApiServer
9
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 规范化PocketBase数据库文档与原生API访问

Browse Source 
- 将数据库文档拆分为按collection命名的标准文件，统一格式
- 补充tbl_company、tbl_system_dict等表的原生访问规则
- 新增users_tag、document_create等字段
- 优化用户资料更新接口，支持非必填字段
- 添加公司原生API测试脚本
- 归档本次变更至OpenSpec
This commit is contained in:
徐
2026-03-29 16:21:34 +08:00
parent 51a90260e4
commit e9fe1165e3
46 changed files with 3790 additions and 1108 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
docs/api.md
View File

@@ -133,6 +133,7 @@
"users_type": "注册用户",
"users_name": "张三",
"users_phone": "13800138000",
"users_tag": "核心客户",
"users_phone_masked": "138****8000",
"users_picture": "ATT-1743123456789-abc123",
"users_picture_url": "https://bai-api.blv-oa.com/pb/api/files/pbc_xxx/recordId/avatar.png",
@@ -163,6 +164,8 @@
{
"users_name": "张三",
"users_phone_code": "2b7d9f2e3c4a5b6d7e8f",
"users_phone": "13800138000",
"users_tag": "核心客户",
"users_picture": "ATT-1743123456789-abc123",
"users_id_pic_a": "ATT-1743123456789-id-a",
"users_id_pic_b": "ATT-1743123456789-id-b",
@@ -174,9 +177,11 @@
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `users_name` | string | 是 | 用户姓名 |
| `users_phone_code` | string | 是 | 微信手机号获取凭证 code，后端将据此换取真实手机号 |
| `users_picture` | string | 是 | 用户头像附件的 `attachments_id` |
| `users_name` | string | 否 | 用户姓名；非空时才更新 |
| `users_phone_code` | string | 否 | 微信手机号获取凭证 code；若提供，服务端优先据此换取真实手机号 |
| `users_phone` | string | 否 | 直接写入的手机号；仅在未提供 `users_phone_code` 时生效 |
| `users_tag` | string | 否 | 用户标签；非空时才更新 |
| `users_picture` | string | 否 | 用户头像附件的 `attachments_id`；非空时才更新 |
| `users_id_pic_a` | string | 否 | 证件正面附件的 `attachments_id` |
| `users_id_pic_b` | string | 否 | 证件反面附件的 `attachments_id` |
| `users_title_picture` | string | 否 | 资质附件的 `attachments_id` |
@@ -186,8 +191,10 @@
- 从 `Authorization` 对应的 PocketBase auth record 读取当前用户 `openid`
- 校验 `Authorization`
- 不再从 body 读取 `users_wx_code`
- 使用 `users_phone_code` 调微信官方接口换取真实手机号
- 将真实手机号写入数据库字段 `users_phone`
- 所有字段均允许不传或传空
- 若传入 `users_phone_code`，优先调用微信接口换取真实手机号并写入 `users_phone`
- 若未传 `users_phone_code` 但传入 `users_phone`，则直接写入数据库字段 `users_phone`
- 未传或传空的字段不会清空数据库中的已有值；只有非空字段才会更新
- `users_picture`、`users_id_pic_a`、`users_id_pic_b`、`users_title_picture` 均按 `attachments_id` 存储，服务端查询用户信息时会自动补充对应文件流链接
- 若用户首次从“三项资料均为空”变为“三项资料均完整”，则将 `users_type` 从 `游客` 升级为 `注册用户`
- 返回更新后的完整用户信息
@@ -205,6 +212,7 @@
"users_type": "注册用户",
"users_name": "张三",
"users_phone": "13800138000",
"users_tag": "核心客户",
"users_phone_masked": "138****8000",
"users_picture": "ATT-1743123456789-abc123",
"users_picture_url": "https://bai-api.blv-oa.com/pb/api/files/pbc_xxx/recordId/avatar.png",

168
docs/api_response_field_notes.md Normal file
View File

@@ -0,0 +1,168 @@
# API 返回字段备注补充
这份文档用于补充 OpenAPI 返回示例里需要展示的“备注 | 类型”文案。
## 1. 用户返回结构 `UserInfo`
| 字段名 | 建议示例文案 |
| :--- | :--- |
| `pb_id` | `PocketBase记录主键 | string` |
| `users_convers_id` | `会话侧用户ID | string` |
| `users_id` | `用户业务ID | string` |
| `users_idtype` | `用户身份来源类型 | string` |
| `users_id_number` | `证件号 | string` |
| `users_type` | `用户类型 | string` |
| `users_name` | `用户姓名 | string` |
| `users_status` | `用户状态 | string` |
| `users_rank_level` | `等级 | number` |
| `users_auth_type` | `账户类型 | number` |
| `users_phone` | `手机号 | string` |
| `users_phone_masked` | `脱敏手机号 | string` |
| `users_level` | `用户等级 | string` |
| `users_tag` | `用户标签 | string` |
| `users_picture` | `用户头像附件ID | string` |
| `users_picture_url` | `用户头像文件流链接 | string` |
| `users_id_pic_a` | `证件正面附件ID | string` |
| `users_id_pic_a_url` | `证件正面文件流链接 | string` |
| `users_id_pic_b` | `证件反面附件ID | string` |
| `users_id_pic_b_url` | `证件反面文件流链接 | string` |
| `users_title_picture` | `资质附件ID | string` |
| `users_title_picture_url` | `资质文件流链接 | string` |
| `openid` | `全平台统一身份标识 | string` |
| `company_id` | `公司业务id | string` |
| `users_parent_id` | `上级用户业务id | string` |
| `users_promo_code` | `推广码 | string` |
| `usergroups_id` | `用户组业务id | string` |
| `created` | `创建时间 | string` |
| `updated` | `更新时间 | string` |
## 2. 公司返回结构 `CompanyInfo`
| 字段名 | 建议示例文案 |
| :--- | :--- |
| `pb_id` | `PocketBase记录主键 | string` |
| `company_id` | `公司业务id | string` |
| `company_name` | `公司名称 | string` |
| `company_type` | `公司类型 | string` |
| `company_entity` | `公司法人 | string` |
| `company_usci` | `统一社会信用代码 | string` |
| `company_nationality` | `国家名称 | string` |
| `company_nationality_code` | `国家编码 | string` |
| `company_province` | `省份名称 | string` |
| `company_province_code` | `省份编码 | string` |
| `company_city` | `城市名称 | string` |
| `company_city_code` | `城市编码 | string` |
| `company_district` | `区县名称 | string` |
| `company_district_code` | `区县编码 | string` |
| `company_postalcode` | `邮政编码 | string` |
| `company_add` | `公司地址 | string` |
| `company_status` | `公司状态 | string` |
| `company_level` | `公司等级 | string` |
| `company_owner_openid` | `公司所有者openid | string` |
| `company_remark` | `备注 | string` |
| `created` | `创建时间 | string` |
| `updated` | `更新时间 | string` |
## 3. 待你补充确认的字段
下面这些字段目前在已有 docs 中备注还不够稳定，如果你希望我继续把“所有接口返回示例”都改成这种风格，建议你先补充这几类字段的标准叫法：
- 系统类返回里各状态字段的最终业务叫法
你补完以后，我可以继续把剩余接口的返回示例全部统一成 `备注 | 类型` 风格。
## 3. 字典返回结构 `DictionaryRecord` / `DictionaryItem`
| 字段名 | 建议示例文案 |
| :--- | :--- |
| `pb_id` | `PocketBase记录主键 | string` |
| `system_dict_id` | `字典业务id | string` |
| `dict_name` | `词典名称 | string` |
| `dict_word_is_enabled` | `是否有效 | boolean` |
| `dict_word_parent_id` | `父级字典业务id | string` |
| `dict_word_remark` | `备注 | string` |
| `enum` | `枚举值 | string` |
| `description` | `枚举描述 | string` |
| `image` | `图片附件ID | string` |
| `imageUrl` | `图片文件流链接 | string` |
| `sortOrder` | `显示顺序 | integer` |
| `created` | `创建时间 | string` |
| `updated` | `更新时间 | string` |
## 4. 附件返回结构 `AttachmentRecord`
| 字段名 | 建议示例文案 |
| :--- | :--- |
| `pb_id` | `PocketBase记录主键 | string` |
| `attachments_id` | `附件业务id | string` |
| `attachments_link` | `PocketBase存储文件名 | string` |
| `attachments_url` | `附件文件流访问链接 | string` |
| `attachments_download_url` | `附件下载链接 | string` |
| `attachments_filename` | `原始文件名 | string` |
| `attachments_filetype` | `文件类型或MIME | string` |
| `attachments_size` | `附件大小 | number` |
| `attachments_owner` | `上传者业务id | string` |
| `attachments_md5` | `附件MD5码 | string` |
| `attachments_ocr` | `OCR识别结果 | string` |
| `attachments_status` | `附件状态 | string` |
| `attachments_remark` | `备注 | string` |
| `created` | `创建时间 | string` |
| `updated` | `更新时间 | string` |
## 5. 文档返回结构 `DocumentRecord`
| 字段名 | 建议示例文案 |
| :--- | :--- |
| `pb_id` | `PocketBase记录主键 | string` |
| `document_id` | `文档业务id | string` |
| `document_create` | `文档创建时间 | string` |
| `document_effect_date` | `文档生效日期 | string` |
| `document_expiry_date` | `文档到期日期 | string` |
| `document_type` | `文档类型 | string` |
| `document_title` | `文档标题 | string` |
| `document_subtitle` | `文档副标题 | string` |
| `document_summary` | `文档摘要 | string` |
| `document_content` | `正文内容 | string` |
| `document_image` | `图片附件ID串 | string` |
| `document_image_ids` | `图片附件ID列表 | array` |
| `document_image_urls` | `图片文件流链接列表 | array` |
| `document_image_url` | `第一张图片文件流链接 | string` |
| `document_video` | `视频附件ID串 | string` |
| `document_video_ids` | `视频附件ID列表 | array` |
| `document_video_urls` | `视频文件流链接列表 | array` |
| `document_video_url` | `第一个视频文件流链接 | string` |
| `document_file` | `文件附件ID串 | string` |
| `document_file_ids` | `文件附件ID列表 | array` |
| `document_file_urls` | `文件文件流链接列表 | array` |
| `document_file_url` | `第一个文件文件流链接 | string` |
| `document_owner` | `上传者openid | string` |
| `document_relation_model` | `关联机型标识 | string` |
| `document_keywords` | `关键词 | string` |
| `document_share_count` | `分享次数 | number` |
| `document_download_count` | `下载次数 | number` |
| `document_favorite_count` | `收藏次数 | number` |
| `document_status` | `文档状态 | string` |
| `document_embedding_status` | `文档嵌入状态 | string` |
| `document_embedding_error` | `文档错误原因 | string` |
| `document_embedding_lasttime` | `最后更新日期 | string` |
| `document_vector_version` | `向量版本号或模型名称 | string` |
| `document_product_categories` | `产品关联文档 | string` |
| `document_application_scenarios` | `筛选依据 | string` |
| `document_hotel_type` | `适用场景 | string` |
| `document_remark` | `备注 | string` |
| `created` | `创建时间 | string` |
| `updated` | `更新时间 | string` |
## 6. 文档历史返回结构 `DocumentHistoryRecord`
| 字段名 | 建议示例文案 |
| :--- | :--- |
| `pb_id` | `PocketBase记录主键 | string` |
| `doh_id` | `文档操作历史业务id | string` |
| `doh_document_id` | `关联文档业务id | string` |
| `doh_operation_type` | `操作类型 | string` |
| `doh_user_id` | `操作人业务id | string` |
| `doh_current_count` | `本次操作对应次数 | number` |
| `doh_remark` | `备注 | string` |
| `created` | `创建时间 | string` |
| `updated` | `更新时间 | string` |

95
docs/newpb.md
View File

@@ -1,95 +0,0 @@
针对你的复杂权限需求，建议采用 **“RBAC（基于角色的访问控制）+ ABAC（基于属性的访问控制）+ 个性化覆盖（Overrides）”** 的混合模式。这种结构能支持从“大颗粒度角色”到“极细颗粒度字段/行”的动态权限矩阵。
以下是为你设计的实施方案及关键表结构规划：
### 一、 核心表方案设计
为了实现“字段级”和“行级”的动态控制，我们需要将 **资源（Resource）**、**权限定义（Permission）**、**角色（Role）** 与 **用户（User）** 彻底解耦。
#### 1. 用户基础表：`tbl_auth_users`
作为全局身份锚点，记录用户的静态信息和动态属性（部门、等级）。
| 字段名 | 类型 | 说明 |
| :--- | :--- | :--- |
| **users_convers_id** | String | 会话/对话侧用户标识，允许为空 |
| **openid** | String (Unique) | **全局身份锚点**，微信唯一标识 |
| **users_name** | String | 姓名/昵称 |
| **org_id** | Int | 所属组织/部门 ID（影响行级权限的关键属性） |
| **users_rank_level** | Int | 职级/等级（影响动态权限矩阵的关键属性） |
| **users_status** | Int | 账户状态 (1: 正常, 0: 禁用) |
| **users_auth_type** | Int | 账户类型 (0: 微信小程序，1: 管理平台，2: 其他) |
---
#### 2. 资源定义表：`tbl_auth_resources`
定义系统中哪些表、哪些字段属于受控资源。
| 字段名 | 类型 | 说明 |
| :--- | :--- | :--- |
| **res_id** | Int (PK) | 资源 ID |
| **table_name** | String | 数据库表名 |
| **column_name** | String | 字段名（如果是表级权限，此项可为空或设为 '*'） |
| **res_type** | Enum | 资源类型：`TABLE`（行/全表）, `COLUMN`（字段级） |
---
#### 3. 角色与基础权限：`tbl_auth_roles` & `tbl_auth_role_perms`
实现通用的权限模板，方便批量管理。
* **`tbl_auth_roles`**: 角色表（如：财务经理、普通销售）。
* **`tbl_auth_role_perms`**: 角色权限关联表，定义该角色对某个资源的操作（读/写/无）。
---
#### 4. **核心：个性化权限覆盖表 `tbl_auth_user_overrides`**
这是满足你“某个用户对某个字段单独设置”需求的关键。
| 字段名 | 类型 | 说明 |
| :--- | :--- | :--- |
| **id** | BigInt (PK) | 自增 ID |
| **users_convers_id** | String | 用户会话标识（关联 `tbl_auth_users.users_convers_id`） |
| **res_id** | Int | 资源 ID（关联 `tbl_auth_resources`） |
| **access_level** | Int | 权限值 (0: 无权, 1: 只读, 2: 读写) |
| **priority** | Int | 优先级（当角色权限与个人设置冲突时，以此为准） |
---
#### 5. **核心：行级过滤策略表 `tbl_auth_row_scopes`**
实现“某个用户只能看自己部门/某几个项目”的动态逻辑。
| 字段名 | 类型 | 说明 |
| :--- | :--- | :--- |
| **id** | Int (PK) | 策略 ID |
| **target_type** | Enum | 目标：`USER` 或 `ROLE` |
| **target_id** | BigInt | 对应的 UserID 或 RoleID |
| **table_name** | String | 作用的表名 |
| **filter_sql** | String | 过滤逻辑。例如：`dept_id = {user.org_id}` 或 `creator_id = {user.users_convers_id}` |
---
### 二、 权限实施方案逻辑
你的权限矩阵页面将由以下逻辑驱动：
#### 1. 权限计算路径 (Effective Permissions)
当用户访问某个数据时，系统按照以下顺序合并权限：
1. **取基础属性**：获取用户的 `org_id` 和 `users_rank_level`。
2. **取角色权限**：获取该用户所属角色对应的资源权限列表。
3. **应用个性化覆盖**：查询 `tbl_auth_user_overrides`。如果该表中有记录，则**覆盖**（或叠加）角色权限。
4. **注入行级过滤**：如果是查询操作，解析 `tbl_auth_row_scopes` 中的 `filter_sql`，将 `{user.xxx}` 变量替换为当前用户的真实值。
#### 2. 动态更新机制
* **组织/等级变更**：当 `tbl_auth_users` 中的 `org_id` 或 `users_rank_level` 变化时，由于行级过滤表（`tbl_auth_row_scopes`）引用的是动态变量，**权限会自动生效**，无需重新授权。
* **缓存策略**：建议将计算后的“最终权限清单”缓存到 Redis。当用户在后台矩阵页面修改权限，或者发生组织架构调整时，通过 `wx_openid` **主动失效（Purge）** 该用户的 Redis 缓存。
#### 3. 字段级权限实现 (Field-Level)
在接口层（中间件），根据计算出的字段级权限清单（即用户对该 Table 下哪些 Column 有读权），动态过滤返回的 JSON 结构。
### 三、 总结：你需要几张表？
为了实现你描述的系统，最精简需要 **5 张表**：
1. **`tbl_auth_users`**：用户主体（含 OpenID、部门、等级）。
2. **`tbl_auth_resources`**：资源清单（表名、字段名）。
3. **`tbl_auth_roles`**：角色定义。
4. **`tbl_auth_role_perms`** / **`tbl_auth_user_overrides`**：权限映射（解决字段级和个人特权）。
5. **`tbl_auth_row_scopes`**：行级过滤表达式（解决多维数据隔离）。

37
docs/pb_auth_model.md Normal file
View File

@@ -0,0 +1,37 @@
# pb_auth_model
> 来源：`script/pocketbase.newpb.js`、当前 hooks 权限实现
> 说明：本文件描述权限模型设计与表间职责，不替代单表结构文档
## 模型目标
当前项目采用 `RBAC + ABAC + 用户覆盖` 的混合权限模型：
- `RBAC` 负责角色级默认权限
- `ABAC` 负责组织、等级、目标表等属性条件
- `用户覆盖` 负责单人例外授权
## 核心表职责
| 文档 | 作用 |
| :--- | :--- |
| [pb_tbl_auth_users.md](/e:/Project_Class/BAI/Web_BAI_Manage_ApiServer/docs/pb_tbl_auth_users.md) | 用户身份源与 PocketBase auth 主表 |
| [pb_tbl_auth_resources.md](/e:/Project_Class/BAI/Web_BAI_Manage_ApiServer/docs/pb_tbl_auth_resources.md) | 资源目录 |
| [pb_tbl_auth_roles.md](/e:/Project_Class/BAI/Web_BAI_Manage_ApiServer/docs/pb_tbl_auth_roles.md) | 角色定义 |
| [pb_tbl_auth_role_perms.md](/e:/Project_Class/BAI/Web_BAI_Manage_ApiServer/docs/pb_tbl_auth_role_perms.md) | 角色权限映射 |
| [pb_tbl_auth_user_overrides.md](/e:/Project_Class/BAI/Web_BAI_Manage_ApiServer/docs/pb_tbl_auth_user_overrides.md) | 单用户权限覆盖 |
| [pb_tbl_auth_row_scopes.md](/e:/Project_Class/BAI/Web_BAI_Manage_ApiServer/docs/pb_tbl_auth_row_scopes.md) | 行级过滤范围 |
## 权限计算路径
1. 从 `tbl_auth_users` 读取用户身份、组织、等级和角色。
2. 从 `tbl_auth_role_perms` 读取角色默认权限。
3. 从 `tbl_auth_user_overrides` 应用用户级覆盖。
4. 从 `tbl_auth_row_scopes` 组合行级过滤条件。
5. 将可原生表达的权限同步到 PocketBase collection rules；复杂业务权限仍由 hooks 判断。
## 当前实现约定
- 管理后台用户通过 `users_idtype = ManagePlatform` 与管理角色识别。
- hooks 页面 `/pb/manage/sdk-permission-manage` 负责维护角色与 collection CRUD 权限。
- 用户登录返回的是 PocketBase 原生可验证 token，可直接给 PocketBase SDK 使用。

106
docs/pb_document_tables.md
View File

@@ -1,106 +0,0 @@
# PocketBase 文档相关表结构
本方案新增 3 张 PocketBase `base collection`，统一采用业务 id 字段进行关联，不直接依赖 PocketBase 自动生成的 `id` 作为业务主键。
补充约定：
- `document_image`、`document_video`、`document_file` 只保存关联的 `attachments_id`，不直接存文件；当存在多个附件时，统一使用 `|` 分隔，例如：`ATT-001|ATT-002|ATT-003`。
- `document_type` 使用多选字符串持久化，但格式特殊：`system_dict_id@dict_word_enum|system_dict_id@dict_word_enum`；前端显示时用枚举值描述，存库时保留该组合值。
- `document_keywords`、`document_product_categories`、`document_application_scenarios`、`document_hotel_type` 统一使用竖线分隔字符串，例如：`分类A|分类B|分类C`。
- `document_status` 仅允许 `有效`、`过期` 两种值，并由系统根据生效日期与到期日期自动计算；当两者都为空时默认 `有效`。
- `document_owner` 的业务含义为“上传者openid”。
- `attachments_link` 是 PocketBase `file` 字段，保存附件本体；访问链接由 PocketBase 根据记录和文件名生成。
- `tbl_attachments` 的文件查看/下载权限应保持公开；真正的业务访问控制交由引用 `attachments_id` 的业务表和业务接口决定。
- 文档字段中，面向用户填写的字段里只有 `document_title`、`document_type` 设为必填，其余字段均允许为空。
---
## 1. `tbl_attachments` 附件表
**类型：** Base Collection
| 字段名 | 类型 | 备注 |
| :--- | :--- | :--- |
| attachments_id | text | 附件业务 id，唯一标识符 |
| attachments_link | file | 附件本体，单文件，不限制文件类型，数据库字段上限已放宽到约 4GB |
| attachments_filename | text | 原始文件名 |
| attachments_filetype | text | 文件类型/MIME |
| attachments_size | number | 附件大小 |
| attachments_owner | text | 上传者业务 id |
| attachments_md5 | text | 附件 MD5 码 |
| attachments_ocr | text | OCR 识别结果 |
| attachments_status | text | 附件状态 |
| attachments_remark | text | 备注 |
**索引规划：**
- `attachments_id` 唯一索引
- `attachments_owner` 普通索引
- `attachments_status` 普通索引
---
## 2. `tbl_document` 文档表
**类型：** Base Collection
| 字段名 | 类型 | 备注 |
| :--- | :--- | :--- |
| document_id | text | 文档业务 id，唯一标识符 |
| document_effect_date | date | 文档生效日期 |
| document_expiry_date | date | 文档到期日期 |
| document_type | text | 文档类型，必填；多选时按 `system_dict_id@dict_word_enum|...` 保存 |
| document_title | text | 文档标题，必填 |
| document_subtitle | text | 文档副标题 |
| document_summary | text | 文档摘要 |
| document_content | text | 正文内容，保存 Markdown 原文 |
| document_image | text | 关联多个 `attachments_id`，使用 `|` 分隔 |
| document_video | text | 关联多个 `attachments_id`，使用 `|` 分隔 |
| document_file | text | 关联多个 `attachments_id`，使用 `|` 分隔 |
| document_owner | text | 上传者openid |
| document_relation_model | text | 关联机型/模型标识 |
| document_keywords | text | 关键词，多选后用 `|` 分隔保存 |
| document_share_count | number | 分享次数 |
| document_download_count | number | 下载次数 |
| document_favorite_count | number | 收藏次数 |
| document_status | text | 文档状态，仅允许 `有效` 或 `过期`，由系统依据生效日期和到期日期自动更新 |
| document_embedding_status | text | 文档嵌入状态 |
| document_embedding_error | text | 文档错误原因 |
| document_embedding_lasttime | date | 最后更新日期 |
| document_vector_version | text | 向量版本号或模型名称 |
| document_product_categories | text | 产品关联文档，多选后从 `文档-产品关联文档` 字典保存为 `|` 分隔字符串 |
| document_application_scenarios | text | 筛选依据，多选后从 `文档-筛选依据` 字典保存为 `|` 分隔字符串 |
| document_hotel_type | text | 适用场景，多选后从 `文档-适用场景` 字典保存为 `|` 分隔字符串 |
| document_remark | text | 备注 |
**索引规划：**
- `document_id` 唯一索引
- `document_owner` 普通索引
- `document_type` 普通索引
- `document_status` 普通索引
- `document_embedding_status` 普通索引
- `document_effect_date` 普通索引
- `document_expiry_date` 普通索引
---
## 3. `tbl_document_operation_history` 文档操作历史表
**类型：** Base Collection
| 字段名 | 类型 | 备注 |
| :--- | :--- | :--- |
| doh_id | text | 文档操作历史业务 id，唯一标识符 |
| doh_document_id | text | 关联 `document_id` |
| doh_operation_type | text | 操作类型 |
| doh_user_id | text | 操作人业务 id |
| doh_current_count | number | 本次操作对应次数 |
| doh_remark | text | 备注 |
**索引规划：**
- `doh_id` 唯一索引
- `doh_document_id` 普通索引
- `doh_user_id` 普通索引
- `doh_operation_type` 普通索引

39
docs/pb_tbl_attachments.md Normal file
View File

@@ -0,0 +1,39 @@
# pb_tbl_attachments
> 来源：线上 PocketBase collection 回读、`script/pocketbase.documents.js`
> 类型：`base`
> 读写规则：公开可读；原生写权限与 hooks 管理权限仅管理员 / 管理角色允许
## 表用途
统一存储项目中的真实上传文件。业务表只保存 `attachments_id`，文件本体仅保存在本表 `attachments_link` 中。
## 字段清单
| 字段名 | 类型 | 必填 | 说明 |
| :--- | :--- | :---: | :--- |
| `id` | `text` | 是 | PocketBase 记录主键 |
| `attachments_id` | `text` | 是 | 附件业务 ID |
| `attachments_link` | `file` | 否 | 文件本体，数据库限制已放宽到约 4GB |
| `attachments_filename` | `text` | 否 | 原始文件名 |
| `attachments_filetype` | `text` | 否 | 文件类型 / MIME |
| `attachments_size` | `number` | 否 | 文件大小 |
| `attachments_owner` | `text` | 否 | 上传者业务标识 |
| `attachments_md5` | `text` | 否 | 文件 MD5 |
| `attachments_ocr` | `text` | 否 | OCR 识别结果 |
| `attachments_status` | `text` | 否 | 附件状态 |
| `attachments_remark` | `text` | 否 | 备注 |
## 索引
| 索引名 | 类型 | 说明 |
| :--- | :--- | :--- |
| `idx_tbl_attachments_attachments_id` | `UNIQUE INDEX` | 保证 `attachments_id` 唯一 |
| `idx_tbl_attachments_attachments_owner` | `INDEX` | 加速按上传者查询 |
| `idx_tbl_attachments_attachments_status` | `INDEX` | 加速按附件状态查询 |
## 补充约定
- 图片、视频、普通文件都统一走本表。
- 业务访问控制不放在本表，而由引用它的业务表与 hooks 接口控制。
- PocketBase 系统字段 `created`、`updated` 仍然存在，只是不在 collection 字段清单里单独声明。

28
docs/pb_tbl_auth_resources.md Normal file
View File

@@ -0,0 +1,28 @@
# pb_tbl_auth_resources
> 来源：线上 PocketBase collection 回读、`script/pocketbase.newpb.js`
> 类型：`base`
> 读写规则：仅管理员 / 管理角色允许
## 表用途
定义哪些表、哪些字段属于受控资源，是角色权限与用户覆盖权限的资源目录表。
## 字段清单
| 字段名 | 类型 | 必填 | 说明 |
| :--- | :--- | :---: | :--- |
| `id` | `text` | 是 | PocketBase 记录主键 |
| `res_id` | `text` | 是 | 资源业务 ID |
| `table_name` | `text` | 是 | 对应数据表名 |
| `column_name` | `text` | 否 | 对应字段名；表级权限时可为空 |
| `res_type` | `text` | 是 | 资源类型 |
## 索引
| 索引名 | 类型 | 说明 |
| :--- | :--- | :--- |
| `idx_tbl_auth_resources_res_id` | `UNIQUE INDEX` | 保证 `res_id` 唯一 |
| `idx_tbl_auth_resources_table_name` | `INDEX` | 加速按表名查询 |
| `idx_tbl_auth_resources_res_type` | `INDEX` | 加速按资源类型查询 |
| `idx_tbl_auth_resources_unique_res` | `UNIQUE INDEX` | 保证 `table_name + column_name + res_type` 唯一 |

29
docs/pb_tbl_auth_role_perms.md Normal file
View File

@@ -0,0 +1,29 @@
# pb_tbl_auth_role_perms
> 来源：线上 PocketBase collection 回读、`script/pocketbase.newpb.js`
> 类型：`base`
> 读写规则：仅管理员 / 管理角色允许
## 表用途
用于存储角色与资源之间的权限映射，是按角色下发 PocketBase SDK CRUD 权限的基础表。
## 字段清单
| 字段名 | 类型 | 必填 | 说明 |
| :--- | :--- | :---: | :--- |
| `id` | `text` | 是 | PocketBase 记录主键 |
| `role_perm_id` | `text` | 是 | 角色权限业务 ID |
| `role_id` | `text` | 是 | 角色业务 ID |
| `res_id` | `text` | 是 | 资源业务 ID |
| `access_level` | `number` | 是 | 权限级别 |
| `priority` | `number` | 否 | 优先级 |
## 索引
| 索引名 | 类型 | 说明 |
| :--- | :--- | :--- |
| `idx_tbl_auth_role_perms_role_perm_id` | `UNIQUE INDEX` | 保证 `role_perm_id` 唯一 |
| `idx_tbl_auth_role_perms_role_id` | `INDEX` | 加速按角色查询 |
| `idx_tbl_auth_role_perms_res_id` | `INDEX` | 加速按资源查询 |
| `idx_tbl_auth_role_perms_unique_map` | `UNIQUE INDEX` | 保证 `role_id + res_id` 唯一 |

28
docs/pb_tbl_auth_roles.md Normal file
View File

@@ -0,0 +1,28 @@
# pb_tbl_auth_roles
> 来源：线上 PocketBase collection 回读、`script/pocketbase.newpb.js`
> 类型：`base`
> 读写规则：仅管理员 / 管理角色允许
## 表用途
用于存储角色定义，供 SDK 直连权限管理页和用户授权流程使用。
## 字段清单
| 字段名 | 类型 | 必填 | 说明 |
| :--- | :--- | :---: | :--- |
| `id` | `text` | 是 | PocketBase 记录主键 |
| `role_id` | `text` | 是 | 角色业务 ID |
| `role_name` | `text` | 是 | 角色名称 |
| `role_code` | `text` | 否 | 角色编码 |
| `role_status` | `number` | 否 | 角色状态 |
| `role_remark` | `text` | 否 | 备注 |
## 索引
| 索引名 | 类型 | 说明 |
| :--- | :--- | :--- |
| `idx_tbl_auth_roles_role_id` | `UNIQUE INDEX` | 保证 `role_id` 唯一 |
| `idx_tbl_auth_roles_role_name` | `UNIQUE INDEX` | 保证 `role_name` 唯一 |
| `idx_tbl_auth_roles_role_code` | `UNIQUE INDEX` | 保证 `role_code` 唯一 |

29
docs/pb_tbl_auth_row_scopes.md Normal file
View File

@@ -0,0 +1,29 @@
# pb_tbl_auth_row_scopes
> 来源：线上 PocketBase collection 回读、`script/pocketbase.newpb.js`
> 类型：`base`
> 读写规则：仅管理员 / 管理角色允许
## 表用途
用于定义按用户或按角色生效的行级过滤范围，是 ABAC / 行级权限的核心表。
## 字段清单
| 字段名 | 类型 | 必填 | 说明 |
| :--- | :--- | :---: | :--- |
| `id` | `text` | 是 | PocketBase 记录主键 |
| `scope_id` | `text` | 是 | 范围业务 ID |
| `target_type` | `text` | 是 | 目标类型 |
| `target_id` | `text` | 是 | 目标 ID |
| `table_name` | `text` | 是 | 作用表名 |
| `filter_sql` | `editor` | 是 | 行级过滤表达式 |
## 索引
| 索引名 | 类型 | 说明 |
| :--- | :--- | :--- |
| `idx_tbl_auth_row_scopes_scope_id` | `UNIQUE INDEX` | 保证 `scope_id` 唯一 |
| `idx_tbl_auth_row_scopes_target_type` | `INDEX` | 加速按目标类型查询 |
| `idx_tbl_auth_row_scopes_target_id` | `INDEX` | 加速按目标 ID 查询 |
| `idx_tbl_auth_row_scopes_table_name` | `INDEX` | 加速按作用表查询 |

29
docs/pb_tbl_auth_user_overrides.md Normal file
View File

@@ -0,0 +1,29 @@
# pb_tbl_auth_user_overrides
> 来源：线上 PocketBase collection 回读、`script/pocketbase.newpb.js`
> 类型：`base`
> 读写规则：仅管理员 / 管理角色允许
## 表用途
用于给单个用户覆盖角色默认权限，实现细粒度例外授权。
## 字段清单
| 字段名 | 类型 | 必填 | 说明 |
| :--- | :--- | :---: | :--- |
| `id` | `text` | 是 | PocketBase 记录主键 |
| `override_id` | `text` | 是 | 覆盖权限业务 ID |
| `users_convers_id` | `text` | 是 | 目标用户会话 ID |
| `res_id` | `text` | 是 | 资源业务 ID |
| `access_level` | `number` | 是 | 权限级别 |
| `priority` | `number` | 否 | 优先级 |
## 索引
| 索引名 | 类型 | 说明 |
| :--- | :--- | :--- |
| `idx_tbl_auth_user_overrides_override_id` | `UNIQUE INDEX` | 保证 `override_id` 唯一 |
| `idx_tbl_auth_user_overrides_users_convers_id` | `INDEX` | 加速按用户查询 |
| `idx_tbl_auth_user_overrides_res_id` | `INDEX` | 加速按资源查询 |
| `idx_tbl_auth_user_overrides_unique_map` | `UNIQUE INDEX` | 保证 `users_convers_id + res_id` 唯一 |

66
docs/pb_tbl_auth_users.md Normal file
View File

@@ -0,0 +1,66 @@
# pb_tbl_auth_users
> 来源：线上 PocketBase collection 回读、`script/pocketbase.newpb.js`
> 类型：`auth`
> 读写规则：仅管理员 / 管理角色允许
## 表用途
作为项目统一身份源，承载微信用户与管理平台用户，并负责向 PocketBase 原生鉴权体系签发可被 SDK 识别的 token。
## 字段清单
| 字段名 | 类型 | 必填 | 说明 |
| :--- | :--- | :---: | :--- |
| `id` | `text` | 是 | PocketBase 记录主键 |
| `users_convers_id` | `text` | 否 | 会话侧用户 ID |
| `openid` | `text` | 是 | 全局身份锚点 |
| `org_id` | `number` | 否 | 组织 / 部门标识 |
| `users_rank_level` | `number` | 否 | 用户星级数值 |
| `users_status` | `text` | 否 | 用户状态 |
| `users_auth_type` | `number` | 否 | 账户类型 |
| `users_id` | `text` | 否 | 用户业务 ID |
| `users_name` | `text` | 否 | 用户姓名 / 昵称 |
| `users_idtype` | `text` | 否 | 身份来源类型或证件类型 |
| `users_id_number` | `text` | 否 | 证件号 |
| `users_phone` | `text` | 否 | 手机号 |
| `users_level` | `text` | 否 | 用户等级文本 |
| `users_type` | `text` | 否 | 用户类型 |
| `company_id` | `text` | 否 | 所属公司业务 ID |
| `users_parent_id` | `text` | 否 | 上级用户业务 ID |
| `users_promo_code` | `text` | 否 | 推广码 |
| `users_picture` | `text` | 否 | 头像附件 ID |
| `usergroups_id` | `text` | 否 | 用户组 / 角色 ID |
| `password` | `password` | 是 | PocketBase 认证密码 |
| `tokenKey` | `text` | 是 | PocketBase token 签发关键字段 |
| `email` | `email` | 是 | PocketBase 认证邮箱 |
| `emailVisibility` | `bool` | 否 | 邮箱是否公开 |
| `verified` | `bool` | 否 | 邮箱是否验证 |
| `users_title_picture` | `text` | 否 | 资质附件 ID |
| `users_id_pic_a` | `text` | 否 | 证件照正面附件 ID |
| `users_id_pic_b` | `text` | 否 | 证件照反面附件 ID |
| `users_tag` | `text` | 否 | 用户标签 |
## 索引
| 索引名 | 类型 | 说明 |
| :--- | :--- | :--- |
| `idx_tbl_auth_users_users_convers_id` | `UNIQUE INDEX` | 保证 `users_convers_id` 唯一 |
| `idx_tbl_auth_users_openid` | `UNIQUE INDEX` | 保证 `openid` 唯一 |
| `idx_tbl_auth_users_org_id` | `INDEX` | 加速按组织查询 |
| `idx_tbl_auth_users_users_rank_level` | `INDEX` | 加速按等级查询 |
| `idx_tbl_auth_users_users_status` | `INDEX` | 加速按状态查询 |
| `idx_tbl_auth_users_users_auth_type` | `INDEX` | 加速按账户类型查询 |
| `idx_tbl_auth_users_users_phone` | `INDEX` | 加速按手机号查询 |
| `idx_tbl_auth_users_company_id` | `INDEX` | 加速按公司查询 |
| `idx_tbl_auth_users_usergroups_id` | `INDEX` | 加速按用户组查询 |
| `idx_tbl_auth_users_users_parent_id` | `INDEX` | 加速按上级查询 |
| `idx_tokenKey_pbc_421601843` | `UNIQUE INDEX` | PocketBase auth 系统索引 |
| `idx_email_pbc_421601843` | `UNIQUE INDEX` | PocketBase auth 系统索引，保证邮箱唯一 |
## 补充约定
- 本表为 `auth` collection，除上述字段外还受 PocketBase 原生鉴权机制约束。
- 图片类字段统一只保存 `tbl_attachments.attachments_id`。
- 登录接口返回的 token 来源于本表 auth record 的原生签发能力，可直接给 PocketBase SDK 使用。
- PocketBase 系统字段 `created`、`updated` 仍然存在，只是不在 collection 字段清单里单独声明。

48
docs/pb_tbl_company.md Normal file
View File

@@ -0,0 +1,48 @@
# pb_tbl_company
> 来源：线上 PocketBase collection 回读、`script/pocketbase.js`
> 类型：`base`
> 读写规则：公开可创建、公开可列出；详情 / 更新 / 删除仅管理员或管理后台用户允许
## 表用途
用于存储公司主数据，并作为用户归属公司、微信端公司创建与原生 PocketBase 查询的基础表。
## 字段清单
| 字段名 | 类型 | 必填 | 说明 |
| :--- | :--- | :---: | :--- |
| `id` | `text` | 是 | PocketBase 记录主键 |
| `company_id` | `text` | 是 | 公司业务 ID，由数据库自动生成 |
| `company_name` | `text` | 否 | 公司名称 |
| `company_type` | `text` | 否 | 公司类型 |
| `company_entity` | `text` | 否 | 公司法人 |
| `company_usci` | `text` | 否 | 统一社会信用代码 |
| `company_nationality` | `text` | 否 | 国家名称 |
| `company_nationality_code` | `text` | 否 | 国家编码 |
| `company_province` | `text` | 否 | 省份名称 |
| `company_province_code` | `text` | 否 | 省份编码 |
| `company_city` | `text` | 否 | 城市名称 |
| `company_city_code` | `text` | 否 | 城市编码 |
| `company_district` | `text` | 否 | 区 / 县名称 |
| `company_district_code` | `text` | 否 | 区 / 县编码 |
| `company_postalcode` | `text` | 否 | 邮编 |
| `company_add` | `text` | 否 | 地址 |
| `company_status` | `text` | 否 | 公司状态 |
| `company_level` | `text` | 否 | 公司等级 |
| `company_owner_openid` | `text` | 否 | 公司所有者 openid |
| `company_remark` | `text` | 否 | 备注 |
## 索引
| 索引名 | 类型 | 说明 |
| :--- | :--- | :--- |
| `idx_company_id` | `UNIQUE INDEX` | 保证 `company_id` 唯一 |
| `idx_company_usci` | `INDEX` | 加速按统一社会信用代码查询 |
| `idx_company_owner_openid` | `INDEX` | 加速按公司所有者查询 |
## 补充约定
- 微信端原生 PocketBase 接口支持公开创建公司记录。
- `company_id` 已切换为数据库自动生成，客户端不再需要提交。
- PocketBase 系统字段 `created`、`updated` 仍然存在，只是不在 collection 字段清单里单独声明。

62
docs/pb_tbl_document.md Normal file
View File

@@ -0,0 +1,62 @@
# pb_tbl_document
> 来源：线上 PocketBase collection 回读、`script/pocketbase.documents.js`
> 类型：`base`
> 读写规则：公开可读；新增 / 修改 / 删除仅 `ManagePlatform` / 管理角色允许
## 表用途
用于存储文档主体信息，以及图片、视频、文件三类附件的关联关系。
## 字段清单
| 字段名 | 类型 | 必填 | 说明 |
| :--- | :--- | :---: | :--- |
| `id` | `text` | 是 | PocketBase 记录主键 |
| `document_id` | `text` | 是 | 文档业务 ID |
| `document_effect_date` | `date` | 否 | 文档生效日期 |
| `document_expiry_date` | `date` | 否 | 文档到期日期 |
| `document_type` | `text` | 是 | 文档类型，多选时按 `system_dict_id@dict_word_enum|...` 保存 |
| `document_title` | `text` | 是 | 文档标题 |
| `document_subtitle` | `text` | 否 | 文档副标题 |
| `document_summary` | `text` | 否 | 文档摘要 |
| `document_content` | `text` | 否 | 正文内容，保存 Markdown |
| `document_image` | `text` | 否 | 图片附件 ID 集合，底层以 `|` 分隔 |
| `document_video` | `text` | 否 | 视频附件 ID 集合，底层以 `|` 分隔 |
| `document_owner` | `text` | 否 | 上传者 openid |
| `document_relation_model` | `text` | 否 | 关联机型 / 模型标识 |
| `document_keywords` | `text` | 否 | 关键词，多选后以 `|` 分隔 |
| `document_share_count` | `number` | 否 | 分享次数 |
| `document_download_count` | `number` | 否 | 下载次数 |
| `document_favorite_count` | `number` | 否 | 收藏次数 |
| `document_status` | `text` | 否 | 文档状态，仅 `有效` / `过期` |
| `document_embedding_status` | `text` | 否 | 文档嵌入状态 |
| `document_embedding_error` | `text` | 否 | 文档嵌入错误原因 |
| `document_embedding_lasttime` | `date` | 否 | 最后一次嵌入更新时间 |
| `document_vector_version` | `text` | 否 | 向量版本号 / 模型名称 |
| `document_product_categories` | `text` | 否 | 产品关联文档，多选后以 `|` 分隔 |
| `document_application_scenarios` | `text` | 否 | 筛选依据，多选后以 `|` 分隔 |
| `document_hotel_type` | `text` | 否 | 适用场景，多选后以 `|` 分隔 |
| `document_remark` | `text` | 否 | 备注 |
| `document_file` | `text` | 否 | 普通文件附件 ID 集合，底层以 `|` 分隔 |
| `document_create` | `autodate` | 否 | 文档创建时间，由数据库自动生成 |
## 索引
| 索引名 | 类型 | 说明 |
| :--- | :--- | :--- |
| `idx_tbl_document_document_id` | `UNIQUE INDEX` | 保证 `document_id` 唯一 |
| `idx_tbl_document_document_create` | `INDEX` | 加速按创建时间倒序查询 |
| `idx_tbl_document_document_owner` | `INDEX` | 加速按上传者查询 |
| `idx_tbl_document_document_type` | `INDEX` | 加速按文档类型查询 |
| `idx_tbl_document_document_status` | `INDEX` | 加速按文档状态查询 |
| `idx_tbl_document_document_embedding_status` | `INDEX` | 加速按嵌入状态查询 |
| `idx_tbl_document_document_effect_date` | `INDEX` | 加速按生效日期查询 |
| `idx_tbl_document_document_expiry_date` | `INDEX` | 加速按到期日期查询 |
## 补充约定
- 三类附件字段都只保存 `attachments_id`，真实文件统一在 `tbl_attachments`。
- `document_create` 已作为原生 PocketBase 列表排序字段，推荐使用 `sort=-document_create`。
- 面向用户填写的字段里，仅 `document_title`、`document_type` 必填，其余允许为空。
- PocketBase 系统字段 `created`、`updated` 仍然存在，只是不在 collection 字段清单里单独声明。

35
docs/pb_tbl_document_operation_history.md Normal file
View File

@@ -0,0 +1,35 @@
# pb_tbl_document_operation_history
> 来源：线上 PocketBase collection 回读、`script/pocketbase.documents.js`
> 类型：`base`
> 读写规则：仅管理员 / 管理角色允许
## 表用途
用于记录文档的新增、修改、删除等操作历史。
## 字段清单
| 字段名 | 类型 | 必填 | 说明 |
| :--- | :--- | :---: | :--- |
| `id` | `text` | 是 | PocketBase 记录主键 |
| `doh_id` | `text` | 是 | 文档操作历史业务 ID |
| `doh_document_id` | `text` | 是 | 关联文档业务 ID |
| `doh_operation_type` | `text` | 否 | 操作类型 |
| `doh_user_id` | `text` | 否 | 操作人业务 ID |
| `doh_current_count` | `number` | 否 | 本次操作对应次数 |
| `doh_remark` | `text` | 否 | 备注 |
## 索引
| 索引名 | 类型 | 说明 |
| :--- | :--- | :--- |
| `idx_tbl_document_operation_history_doh_id` | `UNIQUE INDEX` | 保证 `doh_id` 唯一 |
| `idx_tbl_document_operation_history_doh_document_id` | `INDEX` | 加速按文档查询历史 |
| `idx_tbl_document_operation_history_doh_user_id` | `INDEX` | 加速按操作人查询 |
| `idx_tbl_document_operation_history_doh_operation_type` | `INDEX` | 加速按操作类型查询 |
## 补充约定
- 本表主要用于管理端审计与追溯，不对匿名用户开放。
- PocketBase 系统字段 `created`、`updated` 仍然存在，只是不在 collection 字段清单里单独声明。

38
docs/pb_tbl_system_dict.md Normal file
View File

@@ -0,0 +1,38 @@
# pb_tbl_system_dict
> 来源：线上 PocketBase collection 回读、`script/pocketbase.js`、`script/pocketbase.dictionary.js`
> 类型：`base`
> 读写规则：公开可读；仅 `ManagePlatform` / 管理角色可写
## 表用途
用于存储系统字典与枚举组。当前项目中，文档类型、关键词、产品关联文档、筛选依据、适用场景等前端多选项都来自本表。
## 字段清单
| 字段名 | 类型 | 必填 | 说明 |
| :--- | :--- | :---: | :--- |
| `id` | `text` | 是 | PocketBase 记录主键 |
| `system_dict_id` | `text` | 是 | 字典业务 ID |
| `dict_name` | `text` | 是 | 字典名称，当前按全局唯一维护 |
| `dict_word_enum` | `text` | 否 | 枚举值集合，底层以聚合字符串保存 |
| `dict_word_description` | `text` | 否 | 枚举描述集合，底层以聚合字符串保存 |
| `dict_word_is_enabled` | `bool` | 否 | 字典是否启用 |
| `dict_word_sort_order` | `text` | 否 | 枚举排序集合，底层以聚合字符串保存 |
| `dict_word_parent_id` | `text` | 否 | 父级字典业务 ID |
| `dict_word_remark` | `text` | 否 | 备注 |
| `dict_word_image` | `text` | 否 | 枚举图片附件 ID 集合，和枚举值一一对应 |
## 索引
| 索引名 | 类型 | 说明 |
| :--- | :--- | :--- |
| `idx_system_dict_id` | `UNIQUE INDEX` | 保证 `system_dict_id` 唯一 |
| `idx_dict_name` | `UNIQUE INDEX` | 保证 `dict_name` 唯一 |
| `idx_dict_word_parent_id` | `INDEX` | 加速父子字典查询 |
## 补充约定
- 业务返回时，hooks 会把聚合字段转换成 `items[]` 结构，每个元素包含 `enum`、`description`、`image`、`imageUrl`、`sortOrder`。
- 字典项图片本体统一存放在 `tbl_attachments`，本表只保存 `attachments_id`。
- PocketBase 系统字段 `created`、`updated` 仍然存在，只是不在 collection 字段清单里单独声明。

190
docs/tbl_auth_tables.md
View File

@@ -1,190 +0,0 @@
# tbl_auth 系列表结构说明
> 数据来源：`script/pocketbase.newpb.js`
>
> 说明：以下为当前脚本中定义的 `tbl_auth_` 系列 PocketBase 集合结构，不含 PocketBase `auth` 集合的系统内置字段，仅列出脚本中显式声明的自定义字段与索引。
---
## 1. `tbl_auth_users`
- 集合类型：`auth`
- 说明：认证用户主表，业务身份锚点为 `openid`
### 字段
| 字段名 | 类型 | 必填 | 备注 |
| :--- | :--- | :---: | :--- |
| `users_convers_id` | `text` | 否 | 会话/对话侧用户 ID |
| `openid` | `text` | 是 | 微信身份锚点，唯一索引 |
| `org_id` | `number` | 否 | 组织/部门 ID |
| `users_rank_level` | `number` | 否 | 等级 |
| `users_status` | `number` | 否 | 状态 |
| `users_auth_type` | `number` | 否 | 账户类型 |
| `users_id` | `text` | 否 | 自定义用户 ID |
| `users_name` | `text` | 否 | 用户姓名 |
| `users_idtype` | `text` | 否 | 证件类型 |
| `users_id_number` | `text` | 否 | 证件号 |
| `users_phone` | `text` | 否 | 手机号 |
| `users_level` | `text` | 否 | 用户等级 |
| `users_type` | `text` | 否 | 用户类型 |
| `users_status` | `text` | 否 | 用户状态 |
| `company_id` | `text` | 否 | 公司 ID |
| `users_parent_id` | `text` | 否 | 上级用户 ID |
| `users_promo_code` | `text` | 否 | 推广码 |
| `users_id_pic_a` | `text` | 否 | 保存 `tbl_attachments.attachments_id`，用于关联证件照正面 |
| `users_id_pic_b` | `text` | 否 | 保存 `tbl_attachments.attachments_id`，用于关联证件照反面 |
| `users_title_picture` | `text` | 否 | 保存 `tbl_attachments.attachments_id`，用于关联资质照片 |
| `users_picture` | `text` | 否 | 用户头像，保存 `tbl_attachments.attachments_id` |
| `usergroups_id` | `text` | 否 | 用户组 ID |
### 索引
| 索引名 | 类型 | 字段 |
| :--- | :--- | :--- |
| `idx_tbl_auth_users_users_convers_id` | UNIQUE INDEX | `users_convers_id` |
| `idx_tbl_auth_users_openid` | UNIQUE INDEX | `openid` |
| `idx_tbl_auth_users_org_id` | INDEX | `org_id` |
| `idx_tbl_auth_users_users_rank_level` | INDEX | `users_rank_level` |
| `idx_tbl_auth_users_users_status` | INDEX | `users_status` |
| `idx_tbl_auth_users_users_auth_type` | INDEX | `users_auth_type` |
| `idx_tbl_auth_users_users_phone` | INDEX | `users_phone` |
| `idx_tbl_auth_users_company_id` | INDEX | `company_id` |
| `idx_tbl_auth_users_usergroups_id` | INDEX | `usergroups_id` |
| `idx_tbl_auth_users_users_parent_id` | INDEX | `users_parent_id` |
---
## 2. `tbl_auth_resources`
- 集合类型：`base`
- 说明：受控资源定义表
### 字段
| 字段名 | 类型 | 必填 | 备注 |
| :--- | :--- | :---: | :--- |
| `res_id` | `text` | 是 | 资源 ID |
| `table_name` | `text` | 是 | 表名 |
| `column_name` | `text` | 否 | 字段名 |
| `res_type` | `text` | 是 | 资源类型 |
### 索引
| 索引名 | 类型 | 字段 |
| :--- | :--- | :--- |
| `idx_tbl_auth_resources_res_id` | UNIQUE INDEX | `res_id` |
| `idx_tbl_auth_resources_table_name` | INDEX | `table_name` |
| `idx_tbl_auth_resources_res_type` | INDEX | `res_type` |
| `idx_tbl_auth_resources_unique_res` | UNIQUE INDEX | `table_name, column_name, res_type` |
---
## 3. `tbl_auth_roles`
- 集合类型：`base`
- 说明：角色定义表
### 字段
| 字段名 | 类型 | 必填 | 备注 |
| :--- | :--- | :---: | :--- |
| `role_id` | `text` | 是 | 角色 ID |
| `role_name` | `text` | 是 | 角色名称 |
| `role_code` | `text` | 否 | 角色编码 |
| `role_status` | `number` | 否 | 角色状态 |
| `role_remark` | `text` | 否 | 备注 |
### 索引
| 索引名 | 类型 | 字段 |
| :--- | :--- | :--- |
| `idx_tbl_auth_roles_role_id` | UNIQUE INDEX | `role_id` |
| `idx_tbl_auth_roles_role_name` | UNIQUE INDEX | `role_name` |
| `idx_tbl_auth_roles_role_code` | UNIQUE INDEX | `role_code` |
---
## 4. `tbl_auth_role_perms`
- 集合类型：`base`
- 说明：角色权限映射表
### 字段
| 字段名 | 类型 | 必填 | 备注 |
| :--- | :--- | :---: | :--- |
| `role_perm_id` | `text` | 是 | 角色权限记录 ID |
| `role_id` | `text` | 是 | 角色 ID |
| `res_id` | `text` | 是 | 资源 ID |
| `access_level` | `number` | 是 | 权限级别 |
| `priority` | `number` | 否 | 优先级 |
### 索引
| 索引名 | 类型 | 字段 |
| :--- | :--- | :--- |
| `idx_tbl_auth_role_perms_role_perm_id` | UNIQUE INDEX | `role_perm_id` |
| `idx_tbl_auth_role_perms_role_id` | INDEX | `role_id` |
| `idx_tbl_auth_role_perms_res_id` | INDEX | `res_id` |
| `idx_tbl_auth_role_perms_unique_map` | UNIQUE INDEX | `role_id, res_id` |
---
## 5. `tbl_auth_user_overrides`
- 集合类型：`base`
- 说明：用户个性化权限覆盖表
### 字段
| 字段名 | 类型 | 必填 | 备注 |
| :--- | :--- | :---: | :--- |
| `override_id` | `text` | 是 | 覆盖记录 ID |
| `users_convers_id` | `text` | 是 | 用户会话标识 |
| `res_id` | `text` | 是 | 资源 ID |
| `access_level` | `number` | 是 | 权限级别 |
| `priority` | `number` | 否 | 优先级 |
### 索引
| 索引名 | 类型 | 字段 |
| :--- | :--- | :--- |
| `idx_tbl_auth_user_overrides_override_id` | UNIQUE INDEX | `override_id` |
| `idx_tbl_auth_user_overrides_users_convers_id` | INDEX | `users_convers_id` |
| `idx_tbl_auth_user_overrides_res_id` | INDEX | `res_id` |
| `idx_tbl_auth_user_overrides_unique_map` | UNIQUE INDEX | `users_convers_id, res_id` |
---
## 6. `tbl_auth_row_scopes`
- 集合类型：`base`
- 说明：行级权限范围表
### 字段
| 字段名 | 类型 | 必填 | 备注 |
| :--- | :--- | :---: | :--- |
| `scope_id` | `text` | 是 | 范围记录 ID |
| `target_type` | `text` | 是 | 目标类型 |
| `target_id` | `text` | 是 | 目标 ID |
| `table_name` | `text` | 是 | 作用表名 |
| `filter_sql` | `editor` | 是 | 行级过滤表达式 |
### 索引
| 索引名 | 类型 | 字段 |
| :--- | :--- | :--- |
| `idx_tbl_auth_row_scopes_scope_id` | UNIQUE INDEX | `scope_id` |
| `idx_tbl_auth_row_scopes_target_type` | INDEX | `target_type` |
| `idx_tbl_auth_row_scopes_target_id` | INDEX | `target_id` |
| `idx_tbl_auth_row_scopes_table_name` | INDEX | `table_name` |
---
## 备注
1. `tbl_auth_users` 是 `auth` 集合，除上表字段外，还会受 PocketBase auth 系统字段与认证配置影响。
2. 当前文档仅以 `script/pocketbase.newpb.js` 为准，不代表线上数据库已经 100% 同步成功。
3. 若你需要，我可以继续帮你再生成一份“更像数据库设计说明书”的版本，增加字段含义、业务用途、关联关系三列。