# ASDM DDL 上下文分析文档

> 基于 asdm_admin 与 asdm_telemetry 数据库的完整 DDL 结构分析。
>
> 分析日期：2026-07-20
>
> DDL 来源：`pre-context/crystal/ddl.sql`（完整 schema dump）及 Flyway 迁移文件（V1.0.0 ~ V2.1.56）

---

## 目录

- [1. 数据库概览](#1-数据库概览)
- [2. 实体关系图 (ER)](#2-实体关系图-er)
- [3. 业务领域分析](#3-业务领域分析)
- [4. 实体定义](#4-实体定义)
  - [4.1 认证与用户管理](#41-认证与用户管理)
  - [4.2 组织与项目管理](#42-组织与项目管理)
  - [4.3 工作空间与执行](#43-工作空间与执行)
  - [4.4 知识库上下文](#44-知识库上下文)
  - [4.5 流水线与 CI/CD](#45-流水线与-cicd)
  - [4.6 资产注册](#46-资产注册)
  - [4.7 文件服务](#47-文件服务)
  - [4.8 数字分身 (AgentOrbit)](#48-数字分身-agentorbit)
  - [4.9 集成与适配器](#49-集成与适配器)
  - [4.10 系统配置与辅助](#410-系统配置与辅助)
- [5. 数据验证规则](#5-数据验证规则)
- [6. 数据访问模式](#6-数据访问模式)

---

## 1. 数据库概览

### 1.1 数据库类型与版本

| 项目 | 说明 |
|------|------|
| 数据库引擎 | MySQL 8.x (InnoDB) |
| 字符集 | utf8mb4 / utf8mb4_unicode_ci |
| 迁移工具 | Flyway（版本化迁移 V1.0.0 ~ V2.1.56） |
| 数据库数量 | 2 个：`asdm_admin`（主库）、`asdm_telemetry`（遥测库） |

### 1.2 表统计

**asdm_admin 数据库**：共 **52** 张业务表（不含 `flyway_schema_history`），按领域分布如下：

| 业务领域 | 表数量 | 说明 |
|----------|--------|------|
| 认证与用户管理 | 10 | 用户、角色、权限映射、SSO、PAT、审计、配额 |
| 组织与项目管理 | 3 | 组织（集合）、项目、仓库配置 |
| 工作空间与执行 | 6 | 工作空间、关系、运行历史、资源链接、制品 |
| 知识库上下文 | 10 | 上下文空间、条目、同步历史、结果、分析、Webhook、数据库条目、文件上传 |
| 流水线与 CI/CD | 2 | Pipeline 服务器、全局仓库 |
| 资产注册 | 7 | 资产注册信息、集合、仓库、分类、标签、命令场景、共享范围 |
| 文件服务 | 4 | 文件对象、版本、条目、业务文件映射 |
| 数字分身 (AgentOrbit) | 4 | 配置、实例、组织设置、用户覆盖 |
| 集成与适配器 | 5 | 适配器注册、集成配置、PAT映射、项目映射、审计日志 |
| 系统配置与辅助 | 11 | 配置设置、功能开关、白名单、URL配置、通知、邀请、事件上报、一次性任务等 |

**asdm_telemetry 数据库**：5 张表（`telemetry_events`、`telemetry_metrics_hourly`、`telemetry_metrics_daily`、`shedlock`、`telemetry_flush_dead_letters`）

### 1.3 关系统计

- 外键约束总数：**17** 个（含自引用）
- 核心关系链：`users → project_collections → projects → workspaces / library_contexts`
- 自引用关系：`business_file_mappings.parent_mapping_id → business_file_mappings.id`、`project_collections.parent_id → project_collections.id`

---

## 2. 实体关系图 (ER)

```mermaid
erDiagram
    users {
        BIGINT_unsigned id PK "主键"
        VARCHAR_255 email UK "登录邮箱"
        VARCHAR_255 password "加密密码"
        VARCHAR_100 first_name "名"
        VARCHAR_100 last_name "姓"
        VARCHAR_255 username "身份源展示姓名"
        TINYINT status "1=active,0=inactive,2=locked"
        VARCHAR_32 register_source "LOCAL/ADMIN_PROVISIONED/BANK_SSO"
        TINYINT_1 login_page_allowed "是否允许登录页登录"
    }

    roles {
        BIGINT_unsigned id PK "主键"
        VARCHAR_64 name UK "角色标识如super-admin"
        VARCHAR_128 display_name "展示名"
        VARCHAR_255 description "描述"
        VARCHAR_32 status "active/inactive"
    }

    user_rule_mappings {
        BIGINT_unsigned id PK "主键"
        BIGINT_unsigned user_id FK "用户ID"
        VARCHAR_50 collection_id "集合ID,*表示全部"
        VARCHAR_50 project_id "项目ID,*表示全部"
        BIGINT_unsigned rule_id FK "规则ID"
        VARCHAR_64 rule_name "规则名称"
    }

    user_managed_resource_types {
        BIGINT id PK "主键"
        BIGINT_unsigned mapping_id FK "权限映射ID"
        VARCHAR_32 resource_type "CONTEXT/TOOLSET/SPEC/SKILL/WORKSPACE"
    }

    project_collections {
        INT_unsigned id PK "主键"
        CHAR_36 guid UK "全局唯一标识"
        VARCHAR_100 collection_uid UK "集合唯一标识(slug)"
        VARCHAR_255 name "集合名称"
        TEXT description "描述"
        VARCHAR_20 status "Active/Inactive/Removed"
    }

    projects {
        BIGINT id PK "主键"
        CHAR_36 guid UK "全局唯一标识"
        VARCHAR_128 project_uid UK "项目唯一标识(slug)"
        BIGINT collection_id FK "所属集合ID"
        VARCHAR_255 name "项目名称"
        VARCHAR_32 status "Active/Pending/Completed"
        DATE start_date "开始日期"
        DATE end_date "结束日期"
    }

    project_repositories {
        BIGINT id PK "主键"
        BIGINT project_id FK "所属项目ID"
        VARCHAR_32 repository_source_type "gitlab/github/custom"
        VARCHAR_512 base_url "仓库BaseURL"
        VARCHAR_512 git_push_base_url "GitPushBaseURL"
        VARCHAR_20 repository_auth_type "none/token"
        VARCHAR_255 repository_name "仓库名称"
        VARCHAR_128 default_branch "默认分支"
        VARCHAR_20 status "Active/Deactive"
    }

    workspaces {
        BIGINT id PK "主键"
        CHAR_36 guid UK "工作空间GUID"
        VARCHAR_255 name "工作空间名称"
        TEXT description "描述"
        BIGINT collection_id FK "集合ID"
        BIGINT project_id FK "项目ID"
        BIGINT owner_id FK "拥有者用户ID"
        VARCHAR_20 type "CODE/NORMAL"
        BIGINT project_repository_id FK "仓库配置ID"
        VARCHAR_32 status "Active/Archived"
    }

    workspace_relations {
        BIGINT workspace_id PK_FK "工作空间ID"
        VARCHAR_20 kind "关联类型:toolset/context/spec"
        VARCHAR_64 ref_id PK "关联ID"
    }

    workspace_resource_links {
        BIGINT id PK "主键"
        BIGINT workspace_id FK "工作空间ID"
        VARCHAR_20 resource_kind "CONTEXT/TOOLSET/SPEC"
        BIGINT library_context_id FK "上下文ID(CONTEXT时)"
        VARCHAR_255 resource_id "资源ID(快照)"
        VARCHAR_255 resource_guid "资源GUID(快照)"
        VARCHAR_255 resource_name "资源名称(快照)"
    }

    workspace_run_history {
        BIGINT id PK "主键"
        VARCHAR_255 guid UK "运行GUID"
        VARCHAR_255 workspace_id "工作空间ID"
        TEXT prompt_text "提示文本"
        VARCHAR_1024 repo_url "仓库URL"
        VARCHAR_255 branch "分支"
        BIGINT run_id "WorkflowRunID"
        VARCHAR_32 status "Success/Failed/Running/Queued"
        BIGINT server_id FK "Pipeline服务器ID"
    }

    workspace_artifacts {
        BIGINT id PK "主键"
        CHAR_36 guid UK "GUID"
        BIGINT workspace_id FK "工作空间ID"
        BIGINT run_history_id FK "运行历史ID"
        VARCHAR_512 storage_name "制品存储名称"
        VARCHAR_50 artifact_type "output/log/report/archive/other"
        TINYINT source_type "1=WORKSPACE/2=AGENTORBIT"
        VARCHAR_20 status "Active/Archived/Deleted"
    }

    library_contexts {
        BIGINT id PK "主键"
        CHAR_36 guid UK "上下文GUID"
        VARCHAR_255 name "上下文名称"
        TEXT description "描述"
        BIGINT collection_id FK "集合ID"
        BIGINT project_id FK "项目ID"
        BIGINT owner_id FK "拥有者ID"
        VARCHAR_32 status "Active/Archived"
        TINYINT_1 auto_sync_enabled "是否自动同步"
        TINYINT delete_flag "逻辑删除标记"
    }

    library_context_items {
        BIGINT id PK "主键"
        CHAR_36 guid UK "条目GUID"
        BIGINT context_id FK "上下文ID"
        VARCHAR_255 name "条目名称"
        VARCHAR_50 type "codebase/document/database/url/file_upload"
        VARCHAR_255 uri "条目URI"
        VARCHAR_255 branch "分支名"
        BIGINT project_repository_id FK "仓库配置ID"
        VARCHAR_50 sync_status "NotStarted/InProgress/Success/Failed"
        VARCHAR_20 status "Active/Deactive"
    }

    library_context_sync_history {
        BIGINT id PK "主键"
        CHAR_36 guid UK "同步GUID"
        BIGINT context_id FK "上下文ID"
        BIGINT context_item_id FK "条目ID"
        VARCHAR_255 repo_name "仓库名"
        VARCHAR_1024 repo_url "仓库URL"
        VARCHAR_128 branch "分支"
        VARCHAR_32 status "Success/Failed"
        BIGINT server_id FK "Pipeline服务器ID"
        VARCHAR_16 trigger_source "MANUAL/WEBHOOK"
    }

    library_context_results {
        BIGINT id PK "主键"
        CHAR_36 guid UK "结果GUID"
        BIGINT context_id FK "上下文ID"
        BIGINT context_item_id FK "条目ID"
        BIGINT sync_history_id FK "同步历史ID"
        VARCHAR_255 artifact_name "产物名称"
        LONGTEXT file_content "文件内容"
    }

    library_context_analysis {
        BIGINT id PK "主键"
        CHAR_36 guid UK "分析GUID"
        BIGINT context_id FK "上下文ID"
        LONGTEXT overall_md "overall.md内容"
    }

    config_settings {
        INT_unsigned id PK "主键"
        CHAR_36 guid UK "GUID"
        VARCHAR_255 name "配置名称"
        VARCHAR_100 uname UK "唯一标识"
        VARCHAR_20 level "server/collection/project/user"
        INT_unsigned collection_id "集合ID"
        INT_unsigned project_id "项目ID"
        INT_unsigned user_id "用户ID"
        JSON value "配置值JSON"
    }

    pipeline_servers {
        BIGINT id PK "主键"
        VARCHAR_255 name "服务器名称"
        VARCHAR_100 uname UK "唯一标识"
        VARCHAR_32 server_type "github/jenkins"
        VARCHAR_32 repository_source_type "仓库源类型"
        VARCHAR_20 status "Active/Deactive"
    }

    global_repositories {
        BIGINT id PK "主键"
        VARCHAR_100 uname UK "唯一标识"
        VARCHAR_20 setting_type "server/pipeline"
        VARCHAR_32 pipeline_type "二级类型"
        VARCHAR_32 server_type "github/jenkins"
        VARCHAR_20 status "Active/Deactive/Removed"
    }

    personal_access_tokens {
        BIGINT_unsigned id PK "主键"
        BIGINT_unsigned user_id FK "用户ID"
        VARCHAR_64 name "令牌名称"
        VARCHAR_16 token_prefix "令牌前缀"
        VARCHAR_255 token_hash "令牌哈希"
        VARCHAR_16 hash_algo "BCRYPT"
        DATETIME expires_at "过期时间"
        DATETIME revoked_at "撤销时间"
    }

    invitations {
        BIGINT_unsigned id PK "主键"
        BIGINT_unsigned inviter_user_id FK "邀请人ID"
        BIGINT_unsigned invitee_user_id FK "被邀请人ID"
        VARCHAR_16 invitation_type "ORG/PROJECT"
        VARCHAR_50 collection_id "组织集合ID"
        VARCHAR_32 status "PENDING/ACCEPTED/REJECTED/EXPIRED"
        JSON role_mappings_json "授予的角色映射"
    }

    notifications {
        BIGINT_unsigned id PK "主键"
        BIGINT_unsigned recipient_user_id FK "接收人ID"
        BIGINT_unsigned sender_user_id FK "发送人ID"
        VARCHAR_32 type "INVITATION/GENERAL"
        VARCHAR_500 title "标题"
        TINYINT_1 is_read "是否已读"
    }

    reporting_events {
        BIGINT id PK "主键"
        VARCHAR_32 event "事件名称"
        VARCHAR_128 batch_id "批次标识"
        TEXT events "事件明细JSON"
    }

    agentorbit_configs {
        BIGINT_unsigned id PK "主键"
        CHAR_36 guid UK "GUID"
        VARCHAR_255 name "配置名称"
        VARCHAR_512 server_url "服务器URL"
        VARCHAR_32 auth_mode "client-key/none"
        TINYINT_1 is_active "1-活跃,0-停用"
    }

    agentorbit_instances {
        BIGINT_unsigned id PK "主键"
        CHAR_36 guid UK "GUID"
        BIGINT_unsigned user_id FK "用户ID"
        VARCHAR_255 instance_id "外部实例ID"
        VARCHAR_32 deployment_type "remote/local/embedded"
        BIGINT_unsigned agentorbit_config_id FK "配置ID"
        VARCHAR_32 type "personal/workspace"
    }

    asset_registry_info {
        BIGINT id PK "主键"
        VARCHAR_10 registry_level "server/project"
        VARCHAR_100 config_type "toolset/spec/mcp/skill"
        VARCHAR_64 guid "全局唯一标识"
        VARCHAR_255 name "注册名称"
    }

    asdm_file_objects {
        BIGINT id PK "主键"
        VARCHAR_64 file_id UK "文件唯一标识"
        VARCHAR_255 bucket "S3桶名"
        VARCHAR_512 name "原始文件名"
        VARCHAR_32 status "ACTIVE/DELETED/ARCHIVED"
    }

    asdm_file_versions {
        BIGINT id PK "主键"
        BIGINT file_object_id FK "文件对象ID"
        INT version_no "版本号"
        VARCHAR_32 status "ACTIVE/DELETED"
    }

    asdm_file_entries {
        BIGINT id PK "主键"
        BIGINT file_version_id FK "文件版本ID"
        VARCHAR_2048 entry_path "归档内相对路径"
    }

    business_file_mappings {
        BIGINT id PK "主键"
        CHAR_36 guid UK "映射UUID"
        VARCHAR_50 business_type "业务类型"
        VARCHAR_255 business_id "业务实体标识"
        VARCHAR_32 file_uuid "文件服务UUID"
        VARCHAR_20 blob_kind "FILE/ARCHIVE/ENTRY"
        BIGINT parent_mapping_id FK "父映射ID(自引用)"
    }

    users ||--o{ user_rule_mappings : "has"
    roles ||--o{ user_rule_mappings : "has"
    user_rule_mappings ||--o{ user_managed_resource_types : "has"
    users ||--o{ personal_access_tokens : "has"
    users ||--o{ invitations : "inviter"
    users ||--o{ invitations : "invitee"
    users ||--o{ notifications : "recipient"
    users ||--o{ notifications : "sender"
    users ||--o{ workspaces : "owns"
    users ||--o{ library_contexts : "owns"
    users ||--o{ agentorbit_instances : "has"
    users ||--o{ feature_flag_allowlist : "in"
    users ||--o{ org_create_usage : "uses"
    project_collections ||--o{ projects : "contains"
    projects ||--o{ project_repositories : "has"
    projects ||--o{ workspaces : "has"
    projects ||--o{ library_contexts : "has"
    workspaces ||--o{ workspace_relations : "has"
    workspaces ||--o{ workspace_resource_links : "has"
    workspaces ||--o{ workspace_run_history : "has"
    workspaces ||--o{ workspace_artifacts : "has"
    workspaces }o--|| project_repositories : "uses"
    library_contexts ||--o{ library_context_items : "contains"
    library_contexts ||--o{ library_context_analysis : "analyzes"
    library_context_items ||--o{ library_context_sync_history : "generates"
    library_context_items ||--o{ context_item_webhook_config : "has"
    library_context_sync_history ||--o{ library_context_results : "produces"
    pipeline_servers ||--o{ library_context_sync_history : "executes"
    agentorbit_configs ||--o{ agentorbit_instances : "configures"
    asdm_file_objects ||--o{ asdm_file_versions : "versions"
    asdm_file_versions ||--o{ asdm_file_entries : "entries"
    business_file_mappings }o--o| business_file_mappings : "parent"
    config_settings }o--o| project_collections : "collection_scope"
    integration_configs ||--o{ integration_audit_logs : "audits"
    integration_configs ||--o{ repository_project_mappings : "maps"
    sys_url_config ||--o{ sys_url_mapping : "maps"
```

---

## 3. 业务领域分析

### 3.1 领域识别

基于表关系和命名模式，识别出以下 **8** 个核心业务领域：

| 领域 | 核心表 | 说明 |
|------|--------|------|
| **认证与用户** | `users`, `roles`, `user_rule_mappings`, `personal_access_tokens`, `bank_users`, `user_mappings`, `users_sso_pre`, `super_admin_*`, `org_create_*` | 用户身份、RBAC权限、SSO、超管审计 |
| **组织与项目** | `project_collections`, `projects`, `project_repositories` | 多级组织层级、项目管理、仓库配置 |
| **工作空间** | `workspaces`, `workspace_relations`, `workspace_resource_links`, `workspace_run_history`, `workspace_artifacts` | 开发工作空间、执行与制品 |
| **知识库上下文** | `library_contexts`, `library_context_items`, `library_context_sync_history`, `library_context_results`, `library_context_analysis`, `context_item_webhook_config`, `context_sync_task`, `library_context_item_database`, `library_context_item_file_uploads`, `library_context_item_file_upload_entries` | 上下文空间、条目同步、自动分析 |
| **流水线与CI/CD** | `pipeline_servers`, `global_repositories` | GitHub Actions / Jenkins 流水线配置 |
| **资产注册** | `asset_registry_info`, `asset_collections`, `asset_repositories`, `asset_categories`, `asset_tags`, `asset_command_scenario` | Toolset/Spec/MCP/Skill 注册与分类 |
| **文件服务** | `asdm_file_objects`, `asdm_file_versions`, `asdm_file_entries`, `business_file_mappings` | MinIO/S3 文件存储与业务映射 |
| **数字分身** | `agentorbit_configs`, `agentorbit_instances`, `collection_agent_configs`, `organization_agent_twin_*` | AgentOrbit 数字分身管理 |
| **集成与适配器** | `adapter_registries`, `integration_configs`, `integration_pat_mapping`, `integration_audit_logs`, `repository_project_mappings` | Azure DevOps 等外部集成 |
| **系统配置** | `config_settings`, `feature_flags`, `feature_flag_allowlist`, `sys_url_config`, `sys_url_mapping`, `one_time_task_control`, `invitations`, `notifications`, `reporting_events`, `mcp_routes` | 全局配置、开关、URL路由、通知 |

### 3.2 领域关系图

```mermaid
graph TB
    subgraph "用户层"
        AUTH[认证与用户]
    end

    subgraph "组织层"
        ORG[组织与项目]
    end

    subgraph "资源层"
        WS[工作空间]
        LC[知识库上下文]
        ASSET[资产注册]
        FILE[文件服务]
    end

    subgraph "执行层"
        PIPE[流水线CI/CD]
        AGENT[数字分身]
    end

    subgraph "集成层"
        INT[集成与适配器]
    end

    subgraph "系统层"
        CFG[系统配置]
    end

    AUTH --> ORG
    AUTH --> WS
    AUTH --> LC
    AUTH --> AGENT
    ORG --> WS
    ORG --> LC
    ORG --> ASSET
    ORG --> AGENT
    ORG --> INT
    WS --> PIPE
    WS --> FILE
    WS --> AGENT
    LC --> PIPE
    LC --> FILE
    ASSET --> FILE
    INT --> PIPE
    CFG --> AUTH
    CFG --> ORG
    CFG --> WS
    CFG --> ASSET
```

---

## 4. 实体定义

### 4.1 认证与用户管理

#### users

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT UNSIGNED` | PK, AUTO_INCREMENT | 主键 |
| `email` | `VARCHAR(255)` | NOT NULL, UNIQUE | 登录邮箱 |
| `password` | `VARCHAR(255)` | NOT NULL | 加密密码 |
| `first_name` | `VARCHAR(100)` | NULL | 名 |
| `last_name` | `VARCHAR(100)` | NULL | 姓 |
| `username` | `VARCHAR(255)` | NULL | 身份源展示姓名（可含中文） |
| `status` | `TINYINT` | NOT NULL, DEFAULT 1 | 1=active, 0=inactive, 2=locked |
| `register_source` | `VARCHAR(32)` | NOT NULL, DEFAULT 'LOCAL' | LOCAL / ADMIN_PROVISIONED / BANK_SSO |
| `login_page_allowed` | `TINYINT(1)` | NOT NULL, DEFAULT 1 | 是否允许登录页密码登录 |

```typescript
interface User {
  id: number;
  email: string;
  password: string;
  firstName?: string;
  lastName?: string;
  username?: string;
  status: 1 | 0 | 2;
  registerSource: "LOCAL" | "ADMIN_PROVISIONED" | "BANK_SSO";
  loginPageAllowed: boolean;
  createdAt: string;
  updatedAt: string;
}
```

#### roles

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT UNSIGNED` | PK, AUTO_INCREMENT | 主键 |
| `name` | `VARCHAR(64)` | NOT NULL, UNIQUE | 角色标识（如 `super-admin`, `org-admin`, `project-admin`, `user`） |
| `display_name` | `VARCHAR(128)` | NOT NULL | 展示名称 |
| `description` | `VARCHAR(255)` | NULL | 描述 |
| `status` | `VARCHAR(32)` | NOT NULL, DEFAULT 'active' | active / inactive |
| `created_at` | `DATETIME` | NOT NULL, DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| `updated_at` | `DATETIME` | NOT NULL, DEFAULT CURRENT_TIMESTAMP ON UPDATE | 更新时间 |

#### user_rule_mappings

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT UNSIGNED` | PK, AUTO_INCREMENT | 主键 |
| `user_id` | `BIGINT UNSIGNED` | NOT NULL | 用户 ID (FK users.id) |
| `collection_id` | `VARCHAR(50)` | NOT NULL | 集合 ID，`*` 表示全部 |
| `project_id` | `VARCHAR(50)` | NOT NULL | 项目 ID，`*` 表示全部 |
| `rule_id` | `BIGINT UNSIGNED` | NOT NULL | 规则 ID (通常 roles.id) |
| `rule_name` | `VARCHAR(64)` | NOT NULL | 规则标识（如 `super-admin`） |

**唯一约束**：`uk_user_rule_mappings_unique(user_id, collection_id, project_id, rule_id)`、`uk_user_collection_project(user_id, collection_id, project_id)`

#### user_managed_resource_types

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT` | PK, AUTO_INCREMENT | 主键 |
| `mapping_id` | `BIGINT UNSIGNED` | NOT NULL, FK, UNIQUE(per+resource_type) | 权限映射 ID |
| `resource_type` | `VARCHAR(32)` | NOT NULL | CONTEXT / TOOLSET / SPEC / SKILL / WORKSPACE |

**外键**：`mapping_id → user_rule_mappings.id (ON DELETE CASCADE)`

#### personal_access_tokens

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT UNSIGNED` | PK, AUTO_INCREMENT | 主键 |
| `user_id` | `BIGINT UNSIGNED` | NOT NULL, FK | 用户 ID |
| `name` | `VARCHAR(64)` | NOT NULL | 令牌名称 |
| `token_prefix` | `VARCHAR(16)` | NOT NULL | 令牌前缀（如 `asdm_`） |
| `token_hash` | `VARCHAR(255)` | NOT NULL | 令牌哈希 |
| `hash_algo` | `VARCHAR(16)` | NOT NULL, DEFAULT 'BCRYPT' | 哈希算法 |
| `expires_at` | `DATETIME` | NOT NULL | 过期时间 |
| `revoked_at` | `DATETIME` | NULL | 撤销时间 |
| `rotated_at` | `DATETIME` | NULL | 轮换时间 |

#### bank_users

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT UNSIGNED` | PK, AUTO_INCREMENT | 主键 |
| `iam_login_no` | `VARCHAR(128)` | NOT NULL, UNIQUE | IAM 登录号 |
| `email` | `VARCHAR(255)` | NOT NULL, UNIQUE | 邮箱 |
| `username` | `VARCHAR(100)` | NOT NULL | 用户名（来自上游 data.name） |
| `first_name` | `VARCHAR(100)` | NULL | 名 |
| `last_name` | `VARCHAR(100)` | NULL | 姓 |
| `status` | `VARCHAR(32)` | NOT NULL, DEFAULT 'ACTIVE' | ACTIVE / INACTIVE |

#### user_mappings

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT UNSIGNED` | PK, AUTO_INCREMENT | 主键 |
| `user_id` | `BIGINT UNSIGNED` | NOT NULL, UNIQUE | ASDM 用户 ID |
| `bank_user_id` | `BIGINT UNSIGNED` | NOT NULL, UNIQUE | 银行 SSO 用户 ID |
| `mapping_status` | `VARCHAR(16)` | NOT NULL, DEFAULT 'BOUND' | BOUND / UNBOUND |

#### users_sso_pre

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT UNSIGNED` | PK, AUTO_INCREMENT | 主键 |
| `user_id` | `BIGINT UNSIGNED` | NOT NULL | 已预创建用户 ID |
| `iam_login_no` | `VARCHAR(128)` | NOT NULL | IAM 登录号 |
| `email` | `VARCHAR(255)` | NOT NULL | SSO 用户邮箱 |
| `username` | `VARCHAR(255)` | NULL | 首次登录时设置的用户名 |
| `status` | `TINYINT` | NOT NULL, DEFAULT 0 | 0=PENDING, 1=BOUND |
| `created_by` | `BIGINT UNSIGNED` | NOT NULL | 创建人用户 ID |
| `bound_at` | `DATETIME` | NULL | SSO 用户首次绑定登录时间 |

**唯一约束**：`uk_users_sso_pre_iam_email(iam_login_no, email)`

#### super_admin_operation_audit_logs

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT UNSIGNED` | PK, AUTO_INCREMENT | 主键 |
| `operation_type` | `VARCHAR(50)` | NOT NULL | CREATE/PROMOTE/DEMOTE/RESET_PASSWORD/ENABLE/DISABLE/WHITELIST_* |
| `operator_user_id` | `BIGINT UNSIGNED` | NULL | 操作者用户 ID |
| `target_user_id` | `BIGINT UNSIGNED` | NULL | 目标用户 ID |
| `request_payload` | `JSON` | NULL | 请求体（脱敏） |
| `result_status` | `VARCHAR(20)` | NOT NULL | SUCCESS / FAILED / REJECTED |
| `error_code` | `VARCHAR(100)` | NULL | 错误码 |
| `error_message` | `VARCHAR(1000)` | NULL | 错误信息 |
| `client_ip` | `VARCHAR(64)` | NULL | 客户端 IP |
| `user_agent` | `VARCHAR(500)` | NULL | 用户代理 |
| `created_at` | `DATETIME` | NOT NULL, DEFAULT CURRENT_TIMESTAMP | 创建时间 |

#### super_admin_operator_whitelist

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT UNSIGNED` | PK, AUTO_INCREMENT | 主键 |
| `operator_user_id` | `BIGINT UNSIGNED` | NOT NULL, UNIQUE | 授权操作员用户 ID |
| `operator_email_snapshot` | `VARCHAR(255)` | NULL | 操作员邮箱快照 |
| `status` | `VARCHAR(20)` | NOT NULL, DEFAULT 'active' | active / inactive |
| `remark` | `VARCHAR(500)` | NULL | 备注 |

#### org_create_quota_rules

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT UNSIGNED` | PK, AUTO_INCREMENT | 主键 |
| `subject_type` | `VARCHAR(32)` | NOT NULL | 主体类型（固定 USER_TYPE） |
| `subject_key` | `VARCHAR(64)` | NOT NULL | SUPER_ADMIN / NON_SUPER_ADMIN |
| `quota_limit` | `INT` | NOT NULL | 创建上限（-1 表示无限制） |

**唯一约束**：`uk_org_create_quota_rules_subject(subject_type, subject_key)`

#### org_create_usage

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT UNSIGNED` | PK, AUTO_INCREMENT | 主键 |
| `user_id` | `BIGINT UNSIGNED` | NOT NULL, UNIQUE | 用户 ID |
| `used_count` | `INT` | NOT NULL, DEFAULT 0 | 已创建组织数 |
| `closed_organization_count` | `INT` | NOT NULL, DEFAULT 0 | 已关闭组织数 |
| `last_used_at` | `DATETIME` | NULL | 最后使用时间 |
| `last_collection_id` | `BIGINT UNSIGNED` | NULL | 最后创建的集合 ID |

---

### 4.2 组织与项目管理

#### project_collections

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `INT UNSIGNED` | PK, AUTO_INCREMENT | 主键 |
| `guid` | `CHAR(36)` | NOT NULL, UNIQUE | 全局唯一标识 |
| `collection_uid` | `VARCHAR(100)` | NOT NULL, UNIQUE | 集合唯一标识（slug，如 `core-banking`） |
| `name` | `VARCHAR(255)` | NOT NULL | 集合名称 |
| `description` | `TEXT` | NULL | 描述 |
| `status` | `VARCHAR(20)` | NOT NULL, DEFAULT 'active' | Active / Inactive / Removed |
| `date_created` | `DATETIME` | NOT NULL | 创建时间 |
| `created_by` | `VARCHAR(100)` | NOT NULL | 创建人 |
| `date_updated` | `DATETIME` | NOT NULL | 更新时间 |
| `updated_by` | `VARCHAR(100)` | NOT NULL | 更新人 |

```typescript
interface ProjectCollection {
  id: number;
  guid: string;
  collectionUid: string;
  name: string;
  description?: string;
  status: "Active" | "Inactive" | "Removed";
  dateCreated: string;
  createdBy: string;
  dateUpdated: string;
  updatedBy: string;
}
```

#### projects

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT` | PK, AUTO_INCREMENT | 主键 |
| `guid` | `CHAR(36)` | NOT NULL, UNIQUE | 全局唯一标识 |
| `project_uid` | `VARCHAR(128)` | NOT NULL, UNIQUE | 项目唯一标识（slug） |
| `collection_id` | `BIGINT` | NOT NULL | 所属集合 ID |
| `name` | `VARCHAR(255)` | NOT NULL | 项目名称 |
| `status` | `VARCHAR(32)` | NOT NULL, DEFAULT 'Pending' | Active / Pending / Completed |
| `start_date` | `DATE` | NULL | 开始日期 |
| `end_date` | `DATE` | NULL | 结束日期 |

#### project_repositories

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT` | PK, AUTO_INCREMENT | 主键 |
| `project_id` | `BIGINT` | NOT NULL | 所属项目 ID |
| `repository_source_type` | `VARCHAR(32)` | NOT NULL, DEFAULT 'gitlab' | gitlab / github / custom |
| `base_url` | `VARCHAR(512)` | NULL | 仓库源 Base URL |
| `git_push_base_url` | `VARCHAR(512)` | NULL | Git push Base URL（custom 专用） |
| `token` | `VARCHAR(512)` | NULL | 访问 Token |
| `repository_auth_type` | `VARCHAR(20)` | NOT NULL, DEFAULT 'token' | none / token |
| `repository_name` | `VARCHAR(255)` | NULL | 仓库名称或路径 |
| `default_branch` | `VARCHAR(128)` | NULL | 默认分支 |
| `status` | `VARCHAR(20)` | NOT NULL, DEFAULT 'Active' | Active / Deactive |

---

### 4.3 工作空间与执行

#### workspaces

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT` | PK, AUTO_INCREMENT | 主键 |
| `guid` | `CHAR(36)` | NOT NULL, UNIQUE | 工作空间 GUID |
| `name` | `VARCHAR(255)` | NOT NULL | 工作空间名称 |
| `description` | `TEXT` | NULL | 描述 |
| `collection_id` | `BIGINT` | NOT NULL | 集合 ID |
| `project_id` | `BIGINT` | NOT NULL | 项目 ID |
| `owner_id` | `BIGINT` | NOT NULL | 拥有者用户 ID |
| `type` | `VARCHAR(20)` | NOT NULL, DEFAULT 'CODE' | CODE / NORMAL |
| `project_repository_id` | `BIGINT` | NULL, FK | 仓库配置 ID |
| `status` | `VARCHAR(32)` | NOT NULL, DEFAULT 'Active' | Active / Archived |

**外键**：`project_repository_id → project_repositories.id (ON DELETE RESTRICT)`

```typescript
interface Workspace {
  id: number;
  guid: string;
  name: string;
  description?: string;
  collectionId: number;
  projectId: number;
  ownerId: number;
  type: "CODE" | "NORMAL";
  projectRepositoryId?: number;
  status: "Active" | "Archived";
  createdAt: string;
  createdBy: string;
}
```

#### workspace_relations

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `workspace_id` | `BIGINT` | PK (复合), FK | 工作空间 ID |
| `kind` | `VARCHAR(20)` | PK (复合) | toolset / context / spec |
| `ref_id` | `VARCHAR(64)` | PK (复合) | 关联 ID |

#### workspace_resource_links

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT` | PK, AUTO_INCREMENT | 主键 |
| `workspace_id` | `BIGINT` | NOT NULL, FK | 工作空间 ID |
| `resource_kind` | `VARCHAR(20)` | NOT NULL | CONTEXT / TOOLSET / SPEC / SKILLS |
| `library_context_id` | `BIGINT` | NULL, FK | 上下文 ID（仅 CONTEXT 时） |
| `resource_id` | `VARCHAR(255)` | NULL | 资源 ID（快照） |
| `resource_guid` | `VARCHAR(255)` | NULL | 资源 GUID（快照） |
| `resource_name` | `VARCHAR(255)` | NULL | 资源名称（快照） |
| `resource_description` | `TEXT` | NULL | 资源描述（快照） |
| `resource_version` | `VARCHAR(128)` | NULL | 资源版本（快照） |

**CHECK 约束**：`chk_wrl_shape` — 当 `resource_kind='CONTEXT'` 时 `library_context_id` 必须非空；当 `resource_kind` 为 TOOLSET/SPEC/SKILLS 时 `resource_id` 必须非空且 `library_context_id` 为 NULL。

#### workspace_run_history

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT` | PK, AUTO_INCREMENT | 主键 |
| `guid` | `VARCHAR(255)` | NOT NULL, UNIQUE | 运行 GUID |
| `workspace_id` | `VARCHAR(255)` | NOT NULL | 工作空间 ID |
| `prompt_text` | `TEXT` | NULL | 提示文本 |
| `repo_url` | `VARCHAR(1024)` | NOT NULL | 仓库 URL |
| `branch` | `VARCHAR(255)` | NOT NULL | 分支 |
| `run_id` | `BIGINT` | NULL | Workflow Run ID |
| `workflow_status` | `VARCHAR(50)` | NULL | queued / in_progress / completed |
| `workflow_conclusion` | `VARCHAR(50)` | NULL | success / failure / cancelled / skipped |
| `status` | `VARCHAR(50)` | NOT NULL | Success / Failed / Running / Queued |
| `server_id` | `BIGINT` | NULL | Pipeline 服务器 ID |

#### workspace_artifacts

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT` | PK, AUTO_INCREMENT | 主键 |
| `guid` | `CHAR(36)` | NOT NULL, UNIQUE | GUID |
| `workspace_id` | `BIGINT` | NOT NULL, FK | 工作空间 ID |
| `run_history_id` | `BIGINT` | NULL, FK | 运行历史 ID |
| `storage_name` | `VARCHAR(512)` | NOT NULL | 制品存储名称 |
| `relative_path` | `VARCHAR(1024)` | NOT NULL | 制品相对路径 |
| `artifact_type` | `VARCHAR(50)` | NOT NULL, DEFAULT 'output' | output / log / report / archive / other |
| `source_type` | `TINYINT` | NOT NULL, DEFAULT 1 | 1=WORKSPACE / 2=AGENTORBIT |
| `file_size_bytes` | `BIGINT` | NULL | 文件大小 |
| `status` | `VARCHAR(20)` | NOT NULL, DEFAULT 'Active' | Active / Archived / Deleted |

---

### 4.4 知识库上下文

#### library_contexts

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT` | PK, AUTO_INCREMENT | 主键 |
| `guid` | `CHAR(36)` | NOT NULL, UNIQUE | 上下文 GUID |
| `name` | `VARCHAR(255)` | NOT NULL | 上下文名称 |
| `description` | `TEXT` | NULL | 描述 |
| `collection_id` | `BIGINT` | NOT NULL | 集合 ID |
| `project_id` | `BIGINT` | NOT NULL | 项目 ID |
| `owner_id` | `BIGINT` | NOT NULL | 拥有者用户 ID |
| `status` | `VARCHAR(32)` | NOT NULL, DEFAULT 'Active' | Active / Archived |
| `auto_sync_enabled` | `TINYINT(1)` | NOT NULL, DEFAULT 0 | 是否自动同步 |
| `project_repository_id` | `BIGINT` | NULL | 项目仓库配置 ID |
| `delete_flag` | `TINYINT` | NOT NULL, DEFAULT 0 | 逻辑删除标记 |

#### library_context_items

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT` | PK, AUTO_INCREMENT | 主键 |
| `guid` | `CHAR(36)` | NOT NULL, UNIQUE | 条目 GUID |
| `context_id` | `BIGINT` | NOT NULL | 所属上下文 ID |
| `name` | `VARCHAR(255)` | NOT NULL | 条目名称 |
| `type` | `VARCHAR(50)` | NOT NULL | codebase / document / database / url / file_upload |
| `uri` | `VARCHAR(255)` | NULL | 条目 URI |
| `branch` | `VARCHAR(255)` | NULL | 分支名 |
| `project_repository_id` | `BIGINT` | NULL | 仓库配置 ID |
| `promote_file_path` | `VARCHAR(1024)` | NULL | promote 文件路径 |
| `toolset_id` | `VARCHAR(128)` | NULL | 所选工具集 ID |
| `toolset_command` | `VARCHAR(256)` | NULL | 工具集命令 |
| `connection_uri` | `VARCHAR(1024)` | NULL | 数据库连接 URI（type=database） |
| `webhook_enabled` | `TINYINT` | NOT NULL, DEFAULT 0 | Webhook 是否启用 |
| `status` | `VARCHAR(20)` | NOT NULL, DEFAULT 'Active' | Active / Deactive |
| `sync_status` | `VARCHAR(50)` | NOT NULL | NotStarted / InProgress / Success / Failed |

#### library_context_sync_history

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT` | PK, AUTO_INCREMENT | 主键 |
| `guid` | `CHAR(36)` | NOT NULL, UNIQUE | 同步 GUID |
| `context_id` | `BIGINT` | NOT NULL | 上下文 ID |
| `context_item_id` | `BIGINT` | NOT NULL | 条目 ID |
| `repo_name` | `VARCHAR(255)` | NOT NULL | 仓库显示名 |
| `repo_url` | `VARCHAR(1024)` | NOT NULL | 仓库 URL |
| `branch` | `VARCHAR(128)` | NOT NULL | 分支名 |
| `trigger_source` | `VARCHAR(16)` | NOT NULL, DEFAULT 'MANUAL' | MANUAL / WEBHOOK |
| `webhook_config_id` | `BIGINT` | NULL | Webhook 配置 ID |
| `commit_sha_before` | `VARCHAR(40)` | NULL | 合并前 Commit SHA |
| `commit_sha_after` | `VARCHAR(40)` | NULL | 合并后 Commit SHA |
| `status` | `VARCHAR(32)` | NOT NULL | Success / Failed |
| `duration` | `BIGINT` | NULL | 耗时（秒） |

#### library_context_results

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT` | PK, AUTO_INCREMENT | 主键 |
| `guid` | `CHAR(36)` | NOT NULL, UNIQUE | 结果 GUID |
| `context_id` | `BIGINT` | NOT NULL | 上下文 ID |
| `context_item_id` | `BIGINT` | NOT NULL | 条目 ID |
| `sync_history_id` | `BIGINT` | NOT NULL | 同步历史 ID |
| `artifact_name` | `VARCHAR(255)` | NOT NULL | 产物名称 |
| `file_name` | `VARCHAR(512)` | NULL | 文件名 |
| `file_content` | `LONGTEXT` | NULL | 文件内容 |
| `file_mapping_id` | `BIGINT` | NULL, FK | 文件服务映射 ID |

#### library_context_analysis

> 来源：Flyway V2.1.47 `library_context_analysis.sql`

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT` | PK, AUTO_INCREMENT | 主键 |
| `guid` | `CHAR(36)` | NOT NULL, UNIQUE | 分析 GUID |
| `context_id` | `BIGINT` | NOT NULL | 上下文 ID |
| `overall_md` | `LONGTEXT` | NULL | overall.md 自动分析内容 |
| `created_at` | `DATETIME` | NOT NULL | 创建时间 |
| `created_by` | `VARCHAR(128)` | NOT NULL | 创建人 |

#### context_item_webhook_config

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT` | PK, AUTO_INCREMENT | 主键 |
| `context_item_id` | `BIGINT` | NOT NULL, UNIQUE | 条目 ID（一对一） |
| `collection_id` | `BIGINT` | NOT NULL | 集合 ID（冗余快查） |
| `project_id` | `BIGINT` | NOT NULL | 项目 ID（冗余快查） |
| `platform` | `VARCHAR(32)` | NULL | 平台标识（CODING / GITHUB） |
| `repository_url` | `VARCHAR(512)` | NULL | 仓库 URL |
| `branch` | `VARCHAR(128)` | NULL | 目标分支 |
| `enabled` | `TINYINT` | NOT NULL, DEFAULT 0 | 是否启用 |

#### library_context_item_database

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT` | PK, AUTO_INCREMENT | 主键 |
| `guid` | `CHAR(36)` | NOT NULL, UNIQUE | GUID |
| `context_id` | `BIGINT` | NOT NULL | 上下文 ID |
| `context_item_id` | `BIGINT` | NOT NULL | 条目 ID |
| `table_schema` | `VARCHAR(255)` | NOT NULL | 数据库/Schema 名称 |
| `table_name` | `VARCHAR(255)` | NOT NULL | 表名 |
| `ddl` | `TEXT` | NOT NULL | CREATE TABLE DDL 语句 |
| `status` | `VARCHAR(20)` | NOT NULL, DEFAULT 'Active' | 状态 |

#### library_context_item_file_uploads

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT` | PK, AUTO_INCREMENT | 主键 |
| `guid` | `CHAR(36)` | NOT NULL, UNIQUE | GUID |
| `context_id` | `BIGINT` | NOT NULL | 上下文 ID |
| `context_item_id` | `BIGINT` | NOT NULL | 条目 ID |
| `original_filename` | `VARCHAR(512)` | NOT NULL | 原始文件名 |
| `stored_filename` | `VARCHAR(512)` | NOT NULL | 存储文件名 |
| `md5` | `CHAR(32)` | NOT NULL | 文件内容 MD5 |
| `is_archive` | `TINYINT(1)` | NOT NULL, DEFAULT 0 | 是否归档解压 |
| `file_mapping_id` | `BIGINT` | NULL, FK | 文件服务映射 ID |

**唯一约束**：`uk_lci_fu_item_md5(context_item_id, md5)` — 同一条目不允许重复上传相同文件。

---

### 4.5 流水线与 CI/CD

#### pipeline_servers

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT` | PK, AUTO_INCREMENT | 主键 |
| `name` | `VARCHAR(255)` | NOT NULL | 服务器名称 |
| `uname` | `VARCHAR(100)` | NOT NULL, UNIQUE | 唯一标识 |
| `server_type` | `VARCHAR(32)` | NULL | github / jenkins |
| `repository_source_type` | `VARCHAR(32)` | NOT NULL, DEFAULT 'github' | 仓库源类型 |
| `base_url` | `VARCHAR(512)` | NULL | Base URL |
| `repository_auth_type` | `VARCHAR(20)` | NOT NULL, DEFAULT 'token' | none / token |
| `token` | `VARCHAR(512)` | NULL | 访问 Token |
| `repository_name` | `VARCHAR(255)` | NOT NULL | 仓库名 |
| `workflow_id` | `VARCHAR(255)` | NULL | Workflow ID |
| `default_branch` | `VARCHAR(128)` | NULL | 默认分支 |
| `jenkins_git_*` | 多个字段 | NULL | Jenkins 专用 Git 配置系列 |
| `jenkins_context_sync_jenkinsfile` | `VARCHAR(255)` | NULL | 上下文同步 Jenkinsfile |
| `jenkins_workspace_execution_jenkinsfile` | `VARCHAR(255)` | NULL | 工作区执行 Jenkinsfile |
| `asdm_api_pat` | `VARCHAR(512)` | NULL | ASDM API PAT |
| `status` | `VARCHAR(20)` | NOT NULL, DEFAULT 'Active' | 状态 |

#### global_repositories

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT` | PK, AUTO_INCREMENT | 主键 |
| `name` | `VARCHAR(255)` | NOT NULL | 展示名称 |
| `uname` | `VARCHAR(100)` | NOT NULL, UNIQUE | 唯一标识 |
| `setting_type` | `VARCHAR(20)` | NOT NULL, DEFAULT 'server' | server / pipeline |
| `pipeline_type` | `VARCHAR(32)` | NULL | 二级类型 |
| `server_type` | `VARCHAR(32)` | NULL | github / jenkins |
| `repository_source_type` | `VARCHAR(32)` | NOT NULL, DEFAULT 'github' | gitlab / github / custom |
| `base_url` | `VARCHAR(512)` | NULL | Base URL |
| `token` | `VARCHAR(512)` | NULL | Token |
| `repository_name` | `VARCHAR(255)` | NOT NULL | 仓库名 |
| `status` | `VARCHAR(20)` | NOT NULL, DEFAULT 'Active' | 状态 |

---

### 4.6 资产注册

#### asset_registry_info

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT` | PK, AUTO_INCREMENT | 主键 |
| `registry_level` | `VARCHAR(10)` | NOT NULL | server / project |
| `registry_id` | `VARCHAR(255)` | NOT NULL | 注册 ID |
| `config_type` | `VARCHAR(100)` | NOT NULL | toolset / spec / mcp / skill |
| `affiliated_organization` | `VARCHAR(255)` | NULL | 所属组织 GUID |
| `affiliated_project` | `VARCHAR(255)` | NULL | 所属项目 GUID |
| `guid` | `VARCHAR(64)` | NULL | 全局唯一标识 |
| `name` | `VARCHAR(255)` | NOT NULL | 注册名称 |
| `description` | `TEXT` | NULL | 描述 |
| `version` | `VARCHAR(50)` | NULL | 版本 |
| `download_url` | `VARCHAR(500)` | NULL | 下载地址 |
| `path` | `VARCHAR(255)` | NULL | 路径 |
| `entry_point` | `VARCHAR(500)` | NULL | 入口点 |
| `readme_md_content` | `LONGTEXT` | NULL | README.md 内容 |
| `commands` | `VARCHAR(500)` | NULL | 安装命令 |
| `scenario` | `VARCHAR(255)` | NULL | 场景 |
| `is_share` | `TINYINT` | DEFAULT 0 | 是否共享 |
| `category` | `VARCHAR(100)` | NULL | 分类名称 |

#### asset_categories

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT` | PK, AUTO_INCREMENT | 主键 |
| `collection_uid` | `VARCHAR(64)` | NOT NULL | 组织 UID |
| `config_type` | `VARCHAR(20)` | NOT NULL | toolset / spec / mcp_repo / skill |
| `name` | `VARCHAR(100)` | NOT NULL | 分类名称 |
| `sort_order` | `INT` | NOT NULL, DEFAULT 0 | 排序号 |
| `is_system` | `TINYINT` | NOT NULL, DEFAULT 0 | 是否系统内置 |

**唯一约束**：`uk_collection_type_name(collection_uid, config_type, name)`

#### asset_tags

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT` | PK, AUTO_INCREMENT | 主键 |
| `asset_registry_id` | `BIGINT` | NOT NULL, FK | 资源注册表 ID |
| `tag_name` | `VARCHAR(20)` | NOT NULL | 标签名称 |

**唯一约束**：`uk_asset_tag(asset_registry_id, tag_name)`
**外键**：`asset_registry_id → asset_registry_info.id (ON DELETE CASCADE)`

#### asset_command_scenario

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT` | PK, AUTO_INCREMENT | 主键 |
| `config_type` | `VARCHAR(100)` | NOT NULL | 配置类型 |
| `registry_id` | `BIGINT` | NOT NULL | asset_registry_info ID |
| `command` | `VARCHAR(255)` | NOT NULL | 命令标识符 |
| `scenario` | `VARCHAR(255)` | NOT NULL | 场景描述 |
| `md_content` | `TEXT` | NULL | Markdown 内容 |

#### asset_share_scope

> 来源：Flyway V2.1.31

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT` | PK | 主键 |
| `asset_guid` | `VARCHAR(64)` | NOT NULL | 资源 GUID |
| `scope_type` | `VARCHAR(20)` | NOT NULL | 组织/项目级别 |
| `scope_id` | `VARCHAR(255)` | NOT NULL | 组织/项目 ID |

---

### 4.7 文件服务

#### asdm_file_objects

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT` | PK, AUTO_INCREMENT | 主键 |
| `file_id` | `VARCHAR(64)` | NOT NULL, UNIQUE | 文件唯一标识（UUID 无 dash） |
| `bucket` | `VARCHAR(255)` | NOT NULL, DEFAULT 'asdm-files' | S3 桶名 |
| `storage_prefix` | `VARCHAR(255)` | NOT NULL, DEFAULT '' | S3 业务目录前缀 |
| `name` | `VARCHAR(512)` | NOT NULL | 原始文件名 |
| `content_type` | `VARCHAR(255)` | NULL | MIME 类型 |
| `size` | `BIGINT` | NOT NULL, DEFAULT 0 | 总文件大小 |
| `is_directory` | `TINYINT(1)` | NOT NULL, DEFAULT 0 | 是否目录型（归档展开） |
| `status` | `VARCHAR(32)` | NOT NULL, DEFAULT 'ACTIVE' | ACTIVE / DELETED / ARCHIVED |
| `deleted_at` | `DATETIME` | NULL | 软删除时间 |

```typescript
interface AsdmFileObject {
  id: number;
  fileId: string;
  bucket: string;
  storagePrefix: string;
  name: string;
  contentType?: string;
  size: number;
  isDirectory: boolean;
  status: "ACTIVE" | "DELETED" | "ARCHIVED";
  createdAt: string;
  deletedAt?: string;
}
```

#### asdm_file_versions

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT` | PK, AUTO_INCREMENT | 主键 |
| `file_object_id` | `BIGINT` | NOT NULL, FK | 文件对象 ID |
| `version_no` | `INT` | NOT NULL, DEFAULT 1 | 版本号（从1开始） |
| `s3_key_prefix` | `VARCHAR(1024)` | NOT NULL | S3 key 前缀 |
| `size` | `BIGINT` | NOT NULL, DEFAULT 0 | 版本总大小 |
| `file_count` | `INT` | NOT NULL, DEFAULT 1 | 文件条目数 |

**唯一约束**：`uk_file_version(file_object_id, version_no)`
**外键**：`file_object_id → asdm_file_objects.id (ON DELETE CASCADE)`

#### asdm_file_entries

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT` | PK, AUTO_INCREMENT | 主键 |
| `file_version_id` | `BIGINT` | NOT NULL, FK | 文件版本 ID |
| `entry_id` | `VARCHAR(64)` | NOT NULL, UNIQUE | 条目 ID |
| `entry_path` | `VARCHAR(2048)` | NOT NULL | 归档内相对路径 |
| `s3_key` | `VARCHAR(2048)` | NOT NULL | S3 对象 Key |
| `content_type` | `VARCHAR(255)` | NULL | MIME 类型 |
| `size` | `BIGINT` | NOT NULL, DEFAULT 0 | 条目文件大小 |

**外键**：`file_version_id → asdm_file_versions.id (ON DELETE CASCADE)`

#### business_file_mappings

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT` | PK, AUTO_INCREMENT | 主键 |
| `guid` | `CHAR(36)` | NOT NULL, UNIQUE | 映射 UUID |
| `business_type` | `VARCHAR(50)` | NOT NULL | 业务类型 |
| `business_id` | `VARCHAR(255)` | NOT NULL | 业务实体标识 |
| `bucket` | `VARCHAR(100)` | NOT NULL | S3 桶名 |
| `storage_prefix` | `VARCHAR(255)` | NOT NULL, DEFAULT '' | S3 目录前缀 |
| `file_uuid` | `VARCHAR(32)` | NOT NULL | 文件服务 UUID |
| `blob_kind` | `VARCHAR(20)` | NOT NULL | FILE / ARCHIVE / ENTRY |
| `parent_mapping_id` | `BIGINT` | NULL, FK (自引用) | 父映射 ID（ENTRY → ARCHIVE） |
| `original_filename` | `VARCHAR(500)` | NULL | 原始文件名 |
| `file_size_bytes` | `BIGINT` | NULL | 文件字节数 |
| `status` | `VARCHAR(20)` | NOT NULL, DEFAULT 'ACTIVE' | ACTIVE / DELETED |
| `extra_metadata` | `JSON` | NULL | 扩展元数据 |

**外键**：`parent_mapping_id → business_file_mappings.id (ON DELETE SET NULL)` — 自引用，ENTRY 类型指向 ARCHIVE 容器。

---

### 4.8 数字分身 (AgentOrbit)

#### agentorbit_configs

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT UNSIGNED` | PK, AUTO_INCREMENT | 主键 |
| `guid` | `CHAR(36)` | NOT NULL, UNIQUE | GUID |
| `name` | `VARCHAR(255)` | NOT NULL, UNIQUE | 配置名称 |
| `server_url` | `VARCHAR(512)` | NOT NULL | AgentOrbit Server URL |
| `auth_mode` | `VARCHAR(32)` | NOT NULL, DEFAULT 'client-key' | client-key / none |
| `client_key` | `VARCHAR(256)` | NULL | 客户端 Key（加密存储） |
| `infrastructure_image_id` | `VARCHAR(256)` | NULL | 基础设施镜像配置 ID |
| `is_active` | `TINYINT(1)` | NOT NULL, DEFAULT 1 | 活跃/停用 |

#### agentorbit_instances

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT UNSIGNED` | PK, AUTO_INCREMENT | 主键 |
| `guid` | `CHAR(36)` | NOT NULL, UNIQUE | GUID |
| `user_id` | `BIGINT UNSIGNED` | NOT NULL | 用户 ID |
| `instance_id` | `VARCHAR(255)` | NOT NULL, UNIQUE | 外部实例 ID |
| `instance_name` | `VARCHAR(255)` | NOT NULL | 实例显示名称 |
| `is_default` | `TINYINT(1)` | NOT NULL, DEFAULT 0 | 是否默认实例 |
| `status` | `VARCHAR(32)` | NOT NULL, DEFAULT 'active' | active / stopped / error |
| `deployment_type` | `VARCHAR(32)` | NOT NULL, DEFAULT 'remote' | remote / local / embedded |
| `agentorbit_config_id` | `BIGINT UNSIGNED` | NULL, FK | 配置 ID |
| `workspace_id` | `BIGINT` | NULL | 关联工作空间 ID |
| `type` | `VARCHAR(32)` | NULL | personal / workspace |
| `config_snapshot` | `JSON` | NULL | 创建时配置快照 |

**外键**：`agentorbit_config_id → agentorbit_configs.id (ON DELETE SET NULL)`

---

### 4.9 集成与适配器

#### adapter_registries

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT` | PK, AUTO_INCREMENT | 主键 |
| `adapter_type` | `VARCHAR(50)` | NOT NULL, UNIQUE | 适配器类型（azure-devops, github, jira） |
| `service_name` | `VARCHAR(100)` | NOT NULL | 服务名称 |
| `base_url` | `VARCHAR(512)` | NOT NULL | 基础 URL |
| `health_endpoint` | `VARCHAR(100)` | NOT NULL, DEFAULT '/health' | 健康检查端点 |
| `status` | `VARCHAR(20)` | NOT NULL, DEFAULT 'active' | active / inactive / error |
| `health_status` | `VARCHAR(20)` | NULL | healthy / unhealthy |
| `domain_capabilities_json` | `JSON` | NULL | 能力声明 |
| `adapter_metadata_json` | `JSON` | NULL | 适配器元数据 |

#### integration_configs

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT` | PK, AUTO_INCREMENT | 主键 |
| `guid` | `VARCHAR(36)` | NOT NULL, UNIQUE | GUID |
| `name` | `VARCHAR(255)` | NOT NULL | 配置名称 |
| `adapter_type` | `VARCHAR(50)` | NOT NULL | 适配器类型 |
| `project_id` | `BIGINT` | NOT NULL | 所属项目 ID |
| `config_json` | `JSON` | NOT NULL | 适配器配置参数 |
| `status` | `VARCHAR(20)` | NOT NULL, DEFAULT 'active' | active / inactive / error |
| `last_connected_at` | `DATETIME` | NULL | 上次连接成功时间 |
| `last_error` | `VARCHAR(2048)` | NULL | 上次错误信息 |

#### integration_pat_mapping

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT` | PK, AUTO_INCREMENT | 主键 |
| `guid` | `VARCHAR(36)` | NOT NULL, UNIQUE | GUID |
| `user_id` | `BIGINT` | NOT NULL | ASDM 用户 ID |
| `asdm_pat_id` | `BIGINT` | NULL | ASDM PAT ID |
| `adapter_type` | `VARCHAR(50)` | NOT NULL | 适配器类型 |
| `external_pat` | `VARCHAR(512)` | NULL | 外部集成 PAT |
| `status` | `VARCHAR(20)` | NOT NULL, DEFAULT 'active' | active / inactive |

**唯一约束**：`uk_integration_pat_mapping_user_adapter(user_id, adapter_type)`

#### repository_project_mappings

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT` | PK, AUTO_INCREMENT | 主键 |
| `guid` | `VARCHAR(36)` | NOT NULL, UNIQUE | GUID |
| `integration_config_id` | `BIGINT` | NOT NULL | 集成配置 ID |
| `repository_id` | `BIGINT` | NOT NULL | ASDM 代码库 ID |
| `external_project_id` | `VARCHAR(255)` | NOT NULL | 外部项目标识 |

---

### 4.10 系统配置与辅助

#### config_settings

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `INT UNSIGNED` | PK, AUTO_INCREMENT | 主键 |
| `guid` | `CHAR(36)` | NOT NULL, UNIQUE | GUID |
| `name` | `VARCHAR(255)` | NOT NULL | 配置名称 |
| `uname` | `VARCHAR(100)` | NOT NULL, UNIQUE | 唯一标识 |
| `level` | `VARCHAR(20)` | NOT NULL | server / collection / project / user |
| `collection_id` | `INT UNSIGNED` | NULL | 集合 ID |
| `project_id` | `INT UNSIGNED` | NULL | 项目 ID |
| `user_id` | `INT UNSIGNED` | NULL | 用户 ID |
| `value` | `JSON` | NOT NULL | 配置值 JSON |
| `operator_scope` | `VARCHAR(32)` | NOT NULL, DEFAULT 'all-admin' | all-admin / whitelist-admin |

```typescript
interface ConfigSetting {
  id: number;
  guid: string;
  name: string;
  uname: string;
  level: "server" | "collection" | "project" | "user";
  collectionId?: number;
  projectId?: number;
  userId?: number;
  value: Record<string, unknown>;
  operatorScope: "all-admin" | "whitelist-admin";
}
```

#### feature_flags

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT UNSIGNED` | PK, AUTO_INCREMENT | 主键 |
| `flag_key` | `VARCHAR(100)` | NOT NULL, UNIQUE | 开关唯一标识 |
| `flag_value` | `VARCHAR(16)` | NOT NULL, DEFAULT '0' | 0=开放, 1=部分开放, 2=关闭 |
| `description` | `VARCHAR(255)` | NULL | 开关说明 |

#### feature_flag_allowlist

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT UNSIGNED` | PK, AUTO_INCREMENT | 主键 |
| `flag_key` | `VARCHAR(100)` | NOT NULL | 开关标识 |
| `user_id` | `BIGINT UNSIGNED` | NOT NULL, FK | 用户 ID |

**唯一约束**：`uk_flag_key_user_id(flag_key, user_id)`
**外键**：`user_id → users.id (ON DELETE CASCADE)`

#### invitations

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT UNSIGNED` | PK, AUTO_INCREMENT | 主键 |
| `inviter_user_id` | `BIGINT UNSIGNED` | NOT NULL, FK | 邀请人 ID |
| `invitee_user_id` | `BIGINT UNSIGNED` | NOT NULL, FK | 被邀请人 ID |
| `invitation_type` | `VARCHAR(16)` | NOT NULL | ORG / PROJECT |
| `collection_id` | `VARCHAR(50)` | NOT NULL | 组织集合 ID |
| `project_id` | `VARCHAR(50)` | NULL | 项目 ID（ORG 类型为 NULL） |
| `status` | `VARCHAR(32)` | NOT NULL, DEFAULT 'PENDING' | PENDING/ACCEPTED/REJECTED/CANCELLED/EXPIRED/INVALIDATED |
| `role_mappings_json` | `JSON` | NOT NULL | 授予的角色映射 |
| `batch_id` | `VARCHAR(64)` | NULL | 批量创建 ID |
| `invitation_source` | `VARCHAR(16)` | NOT NULL | ORG / PROJECT |

#### notifications

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT UNSIGNED` | PK, AUTO_INCREMENT | 主键 |
| `recipient_user_id` | `BIGINT UNSIGNED` | NOT NULL, FK | 接收人 ID |
| `sender_user_id` | `BIGINT UNSIGNED` | NULL, FK | 发送人 ID |
| `type` | `VARCHAR(32)` | NOT NULL, DEFAULT 'GENERAL' | INVITATION / GENERAL |
| `title` | `VARCHAR(500)` | NOT NULL | 标题 |
| `content` | `TEXT` | NOT NULL | 内容 |
| `is_read` | `TINYINT(1)` | NOT NULL, DEFAULT 0 | 是否已读 |
| `metadata` | `JSON` | NULL | 结构化元数据 |

#### reporting_events

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT` | PK, AUTO_INCREMENT | 主键 |
| `event` | `VARCHAR(32)` | NOT NULL | 事件名称（固定 REPORT_DATA） |
| `batch_id` | `VARCHAR(128)` | NOT NULL | 批次标识 |
| `event_count` | `INT` | NOT NULL | 事件数量 |
| `events` | `TEXT` | NOT NULL | 事件明细 JSON |
| `active_workspace_id` | `VARCHAR(128)` | NULL | 当前激活工作空间 ID |

#### sys_url_config

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT UNSIGNED` | PK, AUTO_INCREMENT | 主键 |
| `domain` | `VARCHAR(255)` | NOT NULL | 域名地址 |
| `api_path` | `VARCHAR(255)` | NOT NULL, DEFAULT '' | API 路径段 |
| `description` | `VARCHAR(255)` | NULL | 配置说明 |

**唯一约束**：`uk_domain_api_path(domain, api_path)`

#### sys_url_mapping

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT UNSIGNED` | PK, AUTO_INCREMENT | 主键 |
| `method_name` | `VARCHAR(100)` | NOT NULL | 方法标识（前端函数名） |
| `config_id` | `BIGINT UNSIGNED` | NOT NULL, FK | 关联配置 ID |

**外键**：`config_id → sys_url_config.id (ON DELETE RESTRICT)`

#### mcp_routes

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT` | PK, AUTO_INCREMENT | 主键 |
| `mcp_server_id` | `VARCHAR(64)` | NOT NULL, UNIQUE | MCP Server 标识符 |
| `instance_guid` | `VARCHAR(36)` | NOT NULL, UNIQUE | 实例 GUID |
| `target_url` | `VARCHAR(256)` | NOT NULL | 转发目标地址 |
| `name` | `VARCHAR(100)` | NULL | 显示名称 |
| `enabled` | `TINYINT` | NOT NULL, DEFAULT 1 | 是否启用 |

#### one_time_task_control

| 列名 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | `BIGINT` | PK, AUTO_INCREMENT | 主键 |
| `task_code` | `VARCHAR(128)` | NOT NULL, UNIQUE | 任务代码 |
| `task_name` | `VARCHAR(255)` | NOT NULL | 任务名称 |
| `status` | `VARCHAR(32)` | NOT NULL | 任务状态 |

---

## 5. 数据验证规则

### 5.1 字段级约束

#### 数据类型约束

| 类型 | 用途 | 典型列 |
|------|------|--------|
| `BIGINT UNSIGNED` | 主键、外键 | 所有 `id`、`user_id`、`*_id` |
| `CHAR(36)` | GUID | `guid` 列（UUID v4 格式） |
| `VARCHAR(255)` | 名称、URL | `name`、`email`、`base_url` |
| `VARCHAR(64)` | 角色标识、令牌前缀 | `rule_name`、`token_prefix` |
| `VARCHAR(32)` | 状态、枚举类型 | `status`、`type`、`level` |
| `VARCHAR(512)` | 长文本 URL、Token | `server_url`、`base_url`、`token` |
| `TEXT` / `LONGTEXT` | 描述、内容 | `description`、`file_content`、`overall_md` |
| `JSON` | 结构化数据 | `value`(config_settings)、`role_mappings_json`、`config_snapshot` |
| `TINYINT` / `TINYINT(1)` | 标记、布尔值 | `status`(users)、`is_default`、`is_share`、`is_read` |
| `INT` | 数量 | `used_count`、`version_no`、`file_count`、`quota_limit` |
| `DATETIME` | 时间戳 | `created_at`、`updated_at`、`expires_at` |

#### 唯一约束汇总

| 表 | 约束 | 说明 |
|----|------|------|
| `users` | `uk_users_email` | 邮箱全局唯一 |
| `roles` | `uk_roles_name` | 角色标识全局唯一 |
| `project_collections` | `uk_*_guid` + `uk_*_collection_uid` | GUID 和 slug 双唯一 |
| `projects` | `uk_*_guid` + `uk_*_project_uid` | GUID 和 slug 双唯一 |
| `bank_users` | `uk_*_iam_login_no` + `uk_*_email` | IAM 号和邮箱双唯一 |
| `user_mappings` | `uk_*_user_id` + `uk_*_bank_user_id` | 双向唯一映射 |
| `personal_access_tokens` | `idx_pat_user_status_page` | 复合索引覆盖令牌查询 |
| `library_context_item_file_uploads` | `uk_lci_fu_item_md5` | 同一条目不允许重复上传相同文件 |
| `asset_tags` | `uk_asset_tag` | 同一资源不允许重复标签 |
| `integration_pat_mapping` | `uk_integration_pat_mapping_user_adapter` | 每用户每适配器唯一 PAT 映射 |
| `mcp_routes` | `uk_mcp_routes_mcpsid` + `uk_mcp_routes_guid` | Server ID 和 GUID 双唯一 |

#### NOT NULL 关键约束

- `users.email`、`users.password` — 登录必需
- `project_collections.name`、`projects.name` — 名称必需
- `library_contexts.collection_id`、`library_contexts.project_id` — 必须归属组织/项目
- `config_settings.uname`、`config_settings.level`、`config_settings.value` — 配置必需
- `invitations.role_mappings_json` — 邀请必须携带角色映射

### 5.2 表级约束

#### CHECK 约束

| 表 | 约束名 | 规则 |
|----|--------|------|
| `workspace_resource_links` | `chk_wrl_shape` | CONTEXT 类型必须有 `library_context_id`；TOOLSET/SPEC/SKILLS 类型必须有 `resource_id` 且 `library_context_id` 为 NULL |

#### 外键关系汇总

| 子表 | 外键列 | 父表 | 父列 | ON DELETE |
|------|--------|------|------|-----------|
| `user_rule_mappings` | `user_id` | `users` | `id` | - |
| `personal_access_tokens` | `user_id` | `users` | `id` | - |
| `invitations` | `invitee_user_id` | `users` | `id` | - |
| `invitations` | `inviter_user_id` | `users` | `id` | - |
| `notifications` | `recipient_user_id` | `users` | `id` | - |
| `notifications` | `sender_user_id` | `users` | `id` | SET NULL |
| `feature_flag_allowlist` | `user_id` | `users` | `id` | CASCADE |
| `agentorbit_instances` | `agentorbit_config_id` | `agentorbit_configs` | `id` | SET NULL |
| `workspace_resource_links` | `workspace_id` | `workspaces` | `id` | CASCADE |
| `workspace_resource_links` | `library_context_id` | `library_contexts` | `id` | RESTRICT |
| `workspace_artifacts` | `workspace_id` | `workspaces` | `id` | CASCADE |
| `workspace_artifacts` | `run_history_id` | `workspace_run_history` | `id` | SET NULL |
| `workspaces` | `project_repository_id` | `project_repositories` | `id` | RESTRICT |
| `asdm_file_versions` | `file_object_id` | `asdm_file_objects` | `id` | CASCADE |
| `asdm_file_entries` | `file_version_id` | `asdm_file_versions` | `id` | CASCADE |
| `business_file_mappings` | `parent_mapping_id` | `business_file_mappings` | `id` | SET NULL (自引用) |
| `library_context_results` | `file_mapping_id` | `business_file_mappings` | `id` | SET NULL |
| `asset_tags` | `asset_registry_id` | `asset_registry_info` | `id` | CASCADE |
| `user_managed_resource_types` | `mapping_id` | `user_rule_mappings` | `id` | CASCADE |
| `sys_url_mapping` | `config_id` | `sys_url_config` | `id` | RESTRICT |

---

## 6. 数据访问模式

### 6.1 常见查询模式

#### 用户认证与权限

| 查询模式 | 涉及表 | 关键索引 |
|----------|--------|----------|
| 按邮箱查找用户 | `users` | `uk_users_email` |
| 查询用户角色与权限 | `users → user_rule_mappings → roles` | `ix_user_rule_mappings_user_id` |
| 查询用户可管理的资源类型 | `user_rule_mappings → user_managed_resource_types` | `uk_mapping_resource` |
| 查询用户 PAT 列表 | `personal_access_tokens` | `idx_pat_user_status_page` |
| SSO 用户映射查询 | `bank_users → user_mappings → users` | `uk_user_mappings_*` |

#### 组织项目层级

| 查询模式 | 涉及表 | 关键索引 |
|----------|--------|----------|
| 按集合查找项目 | `project_collections → projects` | `idx_projects_collection_id` |
| 查询项目仓库配置 | `projects → project_repositories` | `idx_project_repositories_project_id` |
| 组织配额检查 | `org_create_quota_rules + org_create_usage` | `uk_org_create_quota_rules_subject`, `uk_org_create_usage_user_id` |

#### 知识库上下文

| 查询模式 | 涉及表 | 关键索引 |
|----------|--------|----------|
| 按项目查找上下文 | `library_contexts` | `idx_library_contexts_project_id` |
| 查询上下文条目及类型 | `library_contexts → library_context_items` | `idx_library_context_items_context_id` |
| 查询同步历史 | `library_context_items → library_context_sync_history` | `idx_lcsh_context_item_id_triggered_at` |
| 查询同步结果 | `library_context_sync_history → library_context_results` | `idx_lcr_sync_history_id` |
| 查询上下文分析 | `library_contexts → library_context_analysis` | - |

#### 工作空间执行

| 查询模式 | 涉及表 | 关键索引 |
|----------|--------|----------|
| 查询工作空间资源链接 | `workspaces → workspace_resource_links` | `idx_wrl_workspace` |
| 查询运行历史 | `workspace_run_history` | `idx_run_history_workspace_id` |
| 查询制品文件 | `workspace_artifacts` | `idx_workspace_artifacts_workspace_id` |

#### 集成查询

| 查询模式 | 涉及表 | 关键索引 |
|----------|--------|----------|
| 按项目查找集成配置 | `integration_configs` | `idx_integration_configs_project_id` |
| 查询用户集成 PAT | `integration_pat_mapping` | `uk_integration_pat_mapping_user_adapter` |

### 6.2 性能考虑

#### 索引覆盖分析

| 表 | 覆盖索引 | 用途 |
|----|----------|------|
| `personal_access_tokens` | `(user_id, revoked_at, expires_at, created_at)` | 令牌列表分页查询 |
| `invitations` | `(invitee_user_id, status)` | 被邀请人邀请列表 |
| `invitations` | `(collection_id, project_id, invitee_user_id, status)` | 组织/项目内邀请查询 |
| `notifications` | `(recipient_user_id, is_read, created_at)` | 未读通知查询 |
| `library_context_sync_history` | `(context_id, triggered_at)` | 上下文同步历史分页 |
| `library_context_sync_history` | `(status, triggered_at)` | 同步状态筛选分页 |
| `reporting_events` | `(active_workspace_id, event_timestamp)` | 工作空间事件时间序列 |

#### 潜在缺失索引

| 表 | 建议索引 | 原因 |
|----|----------|------|
| `library_context_analysis` | `(context_id)` | 高频查询上下文分析结果 |
| `library_context_item_database` | `(context_item_id, status)` | 按条目查询数据库 DDL |
| `asset_registry_info` | `(registry_level, registry_id, config_type)` | 按级别+类型复合查询 |
| `business_file_mappings` | `(business_type, business_id, status)` | 业务文件映射状态筛选 |
| `integration_audit_logs` | `(integration_id, date_created)` | 集成审计日志分页（已有单列索引，建议复合） |

#### 查询性能建议

1. **`config_settings` 四级配置继承**：查询时应按 `level` → `collection_id` → `project_id` → `user_id` 逐级覆盖，现有索引 `ix_config_settings_*` 已覆盖单列查询，但建议应用层合并逻辑避免 N+1 查询。

2. **`library_context_results.file_content` 使用 LONGTEXT**：大文件内容存储在数据库中可能导致查询性能下降。已有 `file_mapping_id` 外键指向 `business_file_mappings`，建议优先通过文件服务读取大内容，而非直接查询 `file_content` 列。

3. **`workspace_resource_links` CHECK 约束**：`chk_wrl_shape` 约束确保 CONTEXT 与 TOOLSET/SPEC/SKILLS 的数据完整性，但 CHECK 约束在 MySQL 8.x 中对批量插入有性能影响，需注意批量操作场景。

4. **`business_file_mappings` 自引用外键**：`parent_mapping_id → id` 的自引用关系支持 ENTRY → ARCHIVE 的层级映射，查询归档内容时需递归或 JOIN，建议限制层级深度（当前设计为两层）。

---

*本 DDL 上下文分析文档使 AI 模型能够全面理解 ASDM 数据库模式，支持更好的代码生成和数据感知开发。*