john
4e21ca937a
Deploy Documentation / deploy (push) Has been cancelled
Canary / Prepare Version (push) Has been cancelled
Canary / build-cli (push) Has been cancelled
Canary / Upload Install Script (push) Has been cancelled
Canary / bundle-desktop (push) Has been cancelled
Canary / bundle-desktop-intel (push) Has been cancelled
Canary / bundle-desktop-linux (push) Has been cancelled
Canary / bundle-desktop-windows (push) Has been cancelled
Canary / bundle-desktop-windows-cuda (push) Has been cancelled
Canary / Release (push) Has been cancelled
Unused Dependencies / machete (push) Has been cancelled
CI / changes (push) Has been cancelled
CI / Check Rust Code Format (push) Has been cancelled
CI / Build and Test Rust Project (push) Has been cancelled
CI / Build Rust Project on Windows (push) Has been cancelled
CI / Check MSRV (push) Has been cancelled
CI / Lint Rust Code (push) Has been cancelled
CI / Check Generated Schemas are Up-to-Date (push) Has been cancelled
CI / Test and Lint Electron Desktop App (push) Has been cancelled
CI / H5 Plaza Tests and Build (push) Has been cancelled
Live Provider Tests / check-fork (push) Has been cancelled
Live Provider Tests / changes (push) Has been cancelled
Live Provider Tests / Build Binary (push) Has been cancelled
Live Provider Tests / Smoke Tests (push) Has been cancelled
Live Provider Tests / Smoke Tests (Code Execution) (push) Has been cancelled
Live Provider Tests / Compaction Tests (push) Has been cancelled
Live Provider Tests / goose server HTTP integration tests (push) Has been cancelled
Publish Ask AI Bot Docker Image / docker (push) Has been cancelled
Publish Docker Image / docker (push) Has been cancelled
Scorecard supply-chain security / Scorecard analysis (push) Has been cancelled
Fork goose with custom MCP widgets, platform extensions (aider, git, web, search), MindSpace H5 backend/frontend, Plaza/Ops UIs, and deploy scripts for tkmind.cn. Co-authored-by: Cursor <cursoragent@cursor.com>
467 lines
9.9 KiB
Markdown
467 lines
9.9 KiB
Markdown
---
|
||
sidebar_position: 6
|
||
title: Data Model and State Machines
|
||
sidebar_label: Data Model
|
||
description: MindSpace tables, constraints, indexes, lifecycle states, and consistency rules
|
||
---
|
||
|
||
# 数据模型与状态机
|
||
|
||
## 通用约定
|
||
|
||
- 主键使用 UUID、ULID 或其他不可枚举标识。
|
||
- 时间使用 UTC 保存，客户端按用户时区展示。
|
||
- 所有业务表包含 `created_at` 和 `updated_at`。
|
||
- 需要软删除的表包含 `deleted_at`。
|
||
- JSON 仅用于扩展详情，不代替可查询的核心字段。
|
||
- 密码、token 和敏感值只保存哈希或加密值。
|
||
- 所有多租户查询必须包含 `user_id` 或通过明确 join 校验所有权。
|
||
|
||
## 1. users
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| id | 用户主键 |
|
||
| username | 登录名，唯一 |
|
||
| slug | 主页 slug，唯一或全局保留 |
|
||
| email | 邮箱，规范化后唯一 |
|
||
| phone | 可选，加密保存 |
|
||
| password_hash | 强密码哈希 |
|
||
| avatar_asset_id | 头像资产 |
|
||
| plan_type | free/growth/pro/enterprise |
|
||
| status | pending/active/frozen/disabled/deleted |
|
||
| email_verified_at | 邮箱验证时间 |
|
||
| last_login_at | 最近登录 |
|
||
|
||
索引：
|
||
|
||
- unique username
|
||
- unique slug
|
||
- unique normalized email
|
||
- status
|
||
|
||
## 2. user_spaces
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| id | Space ID |
|
||
| user_id | 所有者，首期一对一唯一 |
|
||
| space_name | 展示名 |
|
||
| quota_bytes | 总容量 |
|
||
| used_bytes | 已确认占用 |
|
||
| reserved_bytes | 上传中预留 |
|
||
| status | active/locked/deleted |
|
||
| storage_namespace | 内部存储命名空间 |
|
||
|
||
约束：
|
||
|
||
- `used_bytes >= 0`
|
||
- `reserved_bytes >= 0`
|
||
- `used_bytes + reserved_bytes <= quota_bytes`，管理员超配场景需显式处理。
|
||
|
||
## 3. space_categories
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| id | 分类 ID |
|
||
| user_id | 所有者 |
|
||
| space_id | 所属空间 |
|
||
| category_code | oa/private/public/draft/archive |
|
||
| category_name | 展示名 |
|
||
| visibility_policy | 默认可见性 |
|
||
| ai_access_policy | Agent 默认策略 |
|
||
| publish_policy | 发布策略 |
|
||
| is_system | 是否内置分类 |
|
||
| sort_order | 排序 |
|
||
|
||
唯一约束：`space_id + category_code`。
|
||
|
||
## 4. assets
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| id | 资产 ID |
|
||
| user_id | 所有者 |
|
||
| space_id | 所属空间 |
|
||
| category_id | 逻辑分类 |
|
||
| parent_id | 可选逻辑父目录 |
|
||
| asset_type | file/folder/image/html/markdown/pdf/excel/word/ppt/page_bundle |
|
||
| mime_type | 服务端检测值 |
|
||
| original_filename | 原始文件名 |
|
||
| display_name | 展示名 |
|
||
| logical_path | 逻辑路径，不用于物理访问 |
|
||
| current_version_id | 当前版本 |
|
||
| size_bytes | 当前版本大小 |
|
||
| checksum | 当前版本校验值 |
|
||
| risk_level | 最新风险等级 |
|
||
| visibility | private/internal/public_candidate |
|
||
| status | uploaded/processing/ready/quarantined/archived/deleted |
|
||
| source_type | upload/chat/agent/template/generated |
|
||
|
||
索引：
|
||
|
||
- `user_id + category_id + updated_at`
|
||
- `user_id + parent_id`
|
||
- checksum，可用于用户内去重
|
||
- status
|
||
|
||
## 5. asset_versions
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| id | 版本 ID |
|
||
| asset_id | 资产 |
|
||
| version_no | 递增版本号 |
|
||
| storage_key | 内部对象 key |
|
||
| size_bytes | 版本大小 |
|
||
| checksum | 内容校验值 |
|
||
| mime_type | 该版本类型 |
|
||
| created_by | 用户或系统主体 |
|
||
| change_note | 变更说明 |
|
||
| scan_status | pending/passed/warned/blocked |
|
||
|
||
唯一约束：`asset_id + version_no`。
|
||
|
||
版本删除需要先检查页面、发布和审计引用。
|
||
|
||
## 6. page_records
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| id | Page ID |
|
||
| user_id | 所有者 |
|
||
| space_id | 所属空间 |
|
||
| source_session_id | 来源会话 |
|
||
| source_message_id | 来源消息 |
|
||
| source_asset_id | 来源资产 |
|
||
| title | 标题 |
|
||
| summary | 摘要 |
|
||
| cover_image_asset_id | 封面 |
|
||
| page_type | 页面类型 |
|
||
| template_id | 模板 |
|
||
| draft_content_ref | 草稿内容引用 |
|
||
| current_version_id | 最新保存版本 |
|
||
| current_publish_id | 当前发布记录 |
|
||
| status | 页面状态 |
|
||
| visibility | 私有展示策略 |
|
||
|
||
## 7. page_versions
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| id | 页面版本 |
|
||
| page_id | Page ID |
|
||
| version_no | 递增版本 |
|
||
| content_asset_id | 页面内容资产 |
|
||
| bundle_asset_id | 构建后的页面包 |
|
||
| source_snapshot_json | 来源摘要和追溯信息 |
|
||
| security_scan_id | 对应扫描 |
|
||
| created_by | 创建主体 |
|
||
| change_note | 版本说明 |
|
||
| immutable | 发布版本必须为 true |
|
||
|
||
## 8. publish_records
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| id | 发布 ID |
|
||
| user_id | 所有者 |
|
||
| page_id | 页面 |
|
||
| page_version_id | 不可变版本 |
|
||
| publish_type | page/share |
|
||
| url_slug | 长期页面 slug |
|
||
| public_url | 可派生或缓存 |
|
||
| access_mode | public/password/private_link/time_limited/login_required/owner_only |
|
||
| password_hash | 密码模式 |
|
||
| token_hash | 分享 token 哈希 |
|
||
| token_prefix | 支持运维定位的短前缀 |
|
||
| expires_at | 过期时间 |
|
||
| published_at | 发布时间 |
|
||
| offline_at | 下线时间 |
|
||
| status | draft/online/expired/offline/blocked |
|
||
| view_count | 聚合浏览量 |
|
||
| security_scan_id | 发布扫描 |
|
||
|
||
唯一约束：
|
||
|
||
- 在线长期页：`user_id + url_slug`
|
||
- token hash 唯一
|
||
|
||
## 9. publication_events
|
||
|
||
用于保存发布历史，而不是覆盖旧记录：
|
||
|
||
- id
|
||
- publish_id
|
||
- event_type
|
||
- actor_id
|
||
- old_page_version_id
|
||
- new_page_version_id
|
||
- access_mode
|
||
- detail_json
|
||
- created_at
|
||
|
||
事件包括 `published`、`republished`、`settings_changed`、`expired`、`offlined`、`blocked`。
|
||
|
||
## 10. security_scans
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| id | 扫描 ID |
|
||
| user_id | 所有者 |
|
||
| target_type | asset/page_version/publication_bundle |
|
||
| target_id | 目标 |
|
||
| scanner_version | 扫描器和规则版本 |
|
||
| status | queued/running/passed/warned/blocked/failed |
|
||
| risk_level | none/low/medium/high/critical |
|
||
| findings_count | 命中数量 |
|
||
| summary_json | 分类统计 |
|
||
| started_at | 开始 |
|
||
| completed_at | 完成 |
|
||
|
||
## 11. security_findings
|
||
|
||
- id
|
||
- scan_id
|
||
- finding_type
|
||
- severity
|
||
- location_json
|
||
- masked_sample
|
||
- recommended_action
|
||
- resolution
|
||
- resolved_by
|
||
- resolved_at
|
||
|
||
`masked_sample` 不能保存完整敏感原文。
|
||
|
||
## 12. desensitization_rules
|
||
|
||
- id
|
||
- owner_type：system/user/organization
|
||
- owner_id
|
||
- scope
|
||
- rule_name
|
||
- rule_type
|
||
- pattern_encrypted
|
||
- replacement
|
||
- strategy
|
||
- enabled
|
||
- priority
|
||
- version
|
||
- created_at
|
||
- updated_at
|
||
|
||
规则类型：
|
||
|
||
- phone
|
||
- email
|
||
- id_card
|
||
- bank_card
|
||
- address
|
||
- person_name
|
||
- company_name
|
||
- amount
|
||
- contract_number
|
||
- medical_record_number
|
||
- student_number
|
||
- employee_number
|
||
- custom_regex
|
||
|
||
## 13. desensitization_runs
|
||
|
||
- id
|
||
- user_id
|
||
- source_asset_id
|
||
- source_version_id
|
||
- output_asset_id
|
||
- output_version_id
|
||
- scan_id_before
|
||
- scan_id_after
|
||
- applied_rules_json
|
||
- status
|
||
- confirmed_by
|
||
- created_at
|
||
|
||
## 14. audit_logs
|
||
|
||
- id
|
||
- actor_type
|
||
- actor_id
|
||
- user_id
|
||
- action
|
||
- target_type
|
||
- target_id
|
||
- request_id
|
||
- ip_hash 或按合规策略保存 IP
|
||
- user_agent_summary
|
||
- risk_level
|
||
- result
|
||
- detail_json
|
||
- created_at
|
||
|
||
动作至少包括：
|
||
|
||
- upload_file
|
||
- delete_file
|
||
- read_private_file
|
||
- download_file
|
||
- agent_access
|
||
- generate_page
|
||
- publish_page
|
||
- republish_page
|
||
- offline_page
|
||
- share_link_created
|
||
- share_link_accessed
|
||
- desensitize_content
|
||
- admin_freeze_user
|
||
- admin_offline_publication
|
||
|
||
## 15. agent_jobs
|
||
|
||
- id
|
||
- user_id
|
||
- session_id
|
||
- job_type
|
||
- instruction
|
||
- permission_scope
|
||
- output_category_id
|
||
- status
|
||
- idempotency_key
|
||
- progress
|
||
- result_page_id
|
||
- result_asset_id
|
||
- error_code
|
||
- error_message
|
||
- queued_at
|
||
- started_at
|
||
- completed_at
|
||
- expires_at
|
||
|
||
## 16. agent_job_assets
|
||
|
||
- id
|
||
- job_id
|
||
- asset_id
|
||
- asset_version_id
|
||
- permission：read/write/create_derivative
|
||
- created_at
|
||
|
||
Agent 不通过目录授权读取所有资产。
|
||
|
||
## 17. upload_sessions
|
||
|
||
- id
|
||
- user_id
|
||
- space_id
|
||
- category_id
|
||
- filename
|
||
- expected_size
|
||
- reserved_bytes
|
||
- temporary_storage_key
|
||
- status
|
||
- expires_at
|
||
- checksum
|
||
- created_at
|
||
- completed_at
|
||
|
||
## 18. templates
|
||
|
||
- id
|
||
- owner_type
|
||
- owner_id
|
||
- name
|
||
- category
|
||
- page_type
|
||
- description
|
||
- cover_asset_id
|
||
- manifest_json
|
||
- input_schema_json
|
||
- version
|
||
- status
|
||
- health_disclaimer
|
||
- created_at
|
||
- updated_at
|
||
|
||
## 19. usage_records
|
||
|
||
- id
|
||
- user_id
|
||
- metric_type
|
||
- quantity
|
||
- period_key
|
||
- source_type
|
||
- source_id
|
||
- created_at
|
||
|
||
指标包括存储、AI 次数、公开页面数和页面访问量。
|
||
|
||
## 20. page_view_events
|
||
|
||
- id
|
||
- publish_id
|
||
- occurred_at
|
||
- visitor_hash
|
||
- session_hash
|
||
- referrer_domain
|
||
- device_type
|
||
- country_code
|
||
- is_bot
|
||
|
||
原始事件按保留策略清理，聚合结果长期保存。
|
||
|
||
## 资产状态机
|
||
|
||
```text
|
||
uploaded -> processing -> ready
|
||
\-> quarantined
|
||
ready -> archived -> ready
|
||
ready -> deleted
|
||
quarantined -> processing
|
||
quarantined -> deleted
|
||
```
|
||
|
||
## 页面状态机
|
||
|
||
```text
|
||
draft -> processing -> reviewing
|
||
reviewing -> risk_found
|
||
reviewing -> ready
|
||
risk_found -> draft
|
||
ready -> published
|
||
published -> draft # 继续编辑产生新草稿
|
||
published -> protected
|
||
published/protected -> expired
|
||
published/protected -> offline
|
||
offline -> published # 必须重新检查并产生事件
|
||
any non-deleted -> deleted # 发布中的页面先下线
|
||
```
|
||
|
||
数据库中可以拆分 `status` 与 `access_mode`，避免把 protected 同时当状态和访问模式。
|
||
|
||
## Agent job 状态机
|
||
|
||
```text
|
||
queued -> running -> succeeded
|
||
queued -> cancelled
|
||
running -> cancelled
|
||
running -> failed -> queued # 允许重试
|
||
running -> timed_out
|
||
```
|
||
|
||
## 并发控制
|
||
|
||
- 页面保存携带 `version` 或 `updated_at` 做乐观锁。
|
||
- 重新发布锁定 Page 或 Publication，避免两个版本同时切换。
|
||
- 配额使用数据库原子更新。
|
||
- 幂等请求复用原结果，不重复扣费或创建资产。
|
||
- 删除资产前校验引用关系，并在事务中更新配额。
|
||
|
||
## 数据保留
|
||
|
||
- 软删除资产进入回收期，回收期内仍计入或不计入配额必须产品化配置。
|
||
- 分享 token 下线后保留哈希用于审计，不可恢复原 token。
|
||
- 审计日志保留期不得低于平台安全要求。
|
||
- 原始访问事件按隐私策略短期保留。
|
||
- 已发布版本应保留到发布记录和审计保留期结束。
|
||
|