# ASDM DDL 上下文分析文档

## 1. 数据库概览

| 项目 | 值 |
|------|-----|
| 数据库类型 | MySQL 8.x (InnoDB) |
| 字符集 | utf8mb4 / utf8mb4_unicode_ci |
| 表总数 | 60 |
| 外键关系数 | 15 |
| 业务领域数 | 7 |

### 表清单

| # | 表名 | 用途 | 行数估算 |
|---|------|------|----------|
| 1 | adapter_registries | 适配器注册表，存储已注册适配器的域能力声明与元数据 | 小 |
| 2 | agentorbit_configs | AgentOrbit 连接配置 | 小 |
| 3 | agentorbit_instances | AgentOrbit 数字分身实例 | 中 |
| 4 | asdm_file_entries | 归档文件条目元数据 | 中 |
| 5 | asdm_file_objects | 文件对象元数据（S3 存储） | 中 |
| 6 | asdm_file_versions | 文件版本元数据 | 中 |
| 7 | asset_categories | 资源分类表（toolset/spec/mcp_repo/skill） | 小 |
| 8 | asset_collections | 资产集合元数据 | 小 |
| 9 | asset_command_scenario | 命令-场景关联（toolset/spec） | 小 |
| 10 | asset_registry_info | 资源注册信息中心表 | 中 |
| 11 | asset_repositories | 资产 Git 仓库配置 | 小 |
| 12 | asset_tags | 资源标签 | 小 |
| 13 | bank_users | 银行系统用户账户（IAM） | 中 |
| 14 | business_file_mappings | 业务实体与文件服务 UUID 映射 | 中 |
| 15 | config_settings | 系统配置（层级 scope） | 小 |
| 16 | context_item_webhook_config | 上下文条目 Webhook 配置 | 小 |
| 17 | context_sync_task | 上下文同步任务 | 中 |
| 18 | context_webhook_sync_request | Webhook 触发的同步请求 | 中 |
| 19 | feature_flag_allowlist | 功能开关用户白名单 | 小 |
| 20 | feature_flags | 服务端功能开关配置 | 小 |
| 21 | flyway_schema_history | Flyway 迁移历史 | 中 |
| 22 | global_repositories | 组织级全局仓库/流水线配置 | 小 |
| 23 | integration_audit_logs | 集成适配器审计日志 | 中 |
| 24 | integration_configs | 集成适配器配置（ADO/GitHub/Jira） | 小 |
| 25 | integration_pat_mapping | PAT 与集成映射 | 小 |
| 26 | invitations | 用户邀请记录 | 中 |
| 27 | library_context_item_database | 上下文条目数据库 DDL 定义 | 小 |
| 28 | library_context_item_file_upload_entries | 上下文条目文件上传明细 | 中 |
| 29 | library_context_item_file_uploads | 上下文条目文件上传历史 | 中 |
| 30 | library_context_items | 上下文空间条目 | 中 |
| 31 | library_context_results | 上下文空间同步结果 | 大 |
| 32 | library_context_sync_history | 上下文空间同步历史 | 大 |
| 33 | library_contexts | 上下文空间定义 | 中 |
| 34 | mcp_routes | MCP 路由注册表 | 小 |
| 35 | notifications | 用户通知 | 大 |
| 36 | one_time_task_control | 一次性任务执行控制 | 小 |
| 37 | org_create_quota_rules | 组织创建配额规则 | 小 |
| 38 | org_create_usage | 组织创建使用量追踪 | 小 |
| 39 | personal_access_tokens | 用户个人访问令牌 | 中 |
| 40 | pipeline_servers | 流水线服务端配置（Jenkins/GitHub Actions） | 小 |
| 41 | project_collections | 组织/项目集合定义 | 小 |
| 42 | project_repositories | 项目仓库绑定 | 小 |
| 43 | projects | 项目定义 | 中 |
| 44 | reporting_events | 事件上报（会话/工具调用/资源安装） | 大 |
| 45 | repository_project_mappings | 代码库与外部工具项目映射 | 小 |
| 46 | roles | 角色定义 | 小 |
| 47 | super_admin_operation_audit_logs | 超管操作审计日志 | 中 |
| 48 | super_admin_operator_whitelist | 超管操作员白名单 | 小 |
| 49 | sys_url_config | 系统 URL 配置 | 小 |
| 50 | sys_url_mapping | URL 路由映射 | 小 |
| 51 | user_managed_resource_types | 用户可管理资源类型定义 | 小 |
| 52 | user_mappings | 用户身份映射（SSO/IAM） | 小 |
| 53 | user_rule_mappings | 用户-角色映射 | 中 |
| 54 | users | 核心用户表 | 中 |
| 55 | users_sso_pre | 预 SSO 用户注册记录 | 小 |
| 56 | workspace_artifacts | 工作空间执行制品 | 中 |
| 57 | workspace_relations | 工作空间关系映射 | 中 |
| 58 | workspace_resource_links | 工作空间资源链接（快照） | 中 |
| 59 | workspace_run_history | 工作空间运行历史 | 大 |
| 60 | workspaces | 工作空间定义 | 中 |

---

## 2. 实体关系图

```mermaid
erDiagram
    users ||--o{ invitations : "inviter/invitee"
    users ||--o{ notifications : "recipient/sender"
    users ||--o{ personal_access_tokens : "owner"
    users ||--o{ feature_flag_allowlist : "whitelist"
    users ||--o{ integration_pat_mapping : "user"
    users ||--o{ user_rule_mappings : "user"
    users ||--o{ user_mappings : "user"
    users ||--o{ agentorbit_instances : "owner"
    users ||--o{ org_create_usage : "user"
    users ||--o{ users_sso_pre : "provisioned"
    users ||--o{ library_contexts : "owner"

    user_mappings }o--|| bank_users : "bank_user"
    user_mappings }o--|| users : "user"

    user_rule_mappings ||--o{ user_managed_resource_types : "mapping"

    roles ||--o{ user_rule_mappings : "rule_id"

    project_collections ||--o{ projects : "collection"
    project_collections ||--o{ library_contexts : "collection"
    project_collections ||--o{ workspaces : "collection"
    project_collections ||--o{ asset_collections : "collection"

    projects ||--o{ project_repositories : "project"
    projects ||--o{ library_contexts : "project"
    projects ||--o{ workspaces : "project"
    projects ||--o{ integration_configs : "project"
    projects ||--o{ config_settings : "project scope"

    workspaces ||--o{ workspace_artifacts : "workspace"
    workspaces ||--o{ workspace_run_history : "workspace"
    workspaces ||--o{ workspace_resource_links : "workspace"
    workspaces ||--o{ workspace_relations : "workspace"
    workspaces }o--|| project_repositories : "repo"

    workspace_run_history ||--o{ workspace_artifacts : "run"

    library_contexts ||--o{ library_context_items : "context"
    library_contexts ||--o{ library_context_sync_history : "context"
    library_contexts ||--o{ library_context_results : "context"
    library_contexts ||--o{ workspace_resource_links : "context link"

    library_context_items ||--o{ library_context_item_database : "item"
    library_context_items ||--o{ library_context_item_file_uploads : "item"
    library_context_items ||--o{ context_item_webhook_config : "item"
    library_context_items ||--o{ library_context_sync_history : "item"
    library_context_items ||--o{ library_context_results : "item"

    library_context_item_file_uploads ||--o{ library_context_item_file_upload_entries : "upload"
    library_context_item_file_uploads }o--o| business_file_mappings : "file mapping"

    library_context_results }o--o| business_file_mappings : "file mapping"

    asdm_file_objects ||--o{ asdm_file_versions : "object"
    asdm_file_versions ||--o{ asdm_file_entries : "version"

    asset_registry_info ||--o{ asset_tags : "registry"
    asset_registry_info ||--o{ asset_command_scenario : "registry"

    agentorbit_configs ||--o{ agentorbit_instances : "config"

    integration_configs ||--o{ integration_audit_logs : "integration"
    integration_configs ||--o{ repository_project_mappings : "config"

    sys_url_config ||--o{ sys_url_mapping : "config"

    business_file_mappings ||--o{ business_file_mappings : "parent (self-ref)"

    feature_flags ||--o{ feature_flag_allowlist : "flag_key"

    global_repositories ||--o{ library_context_sync_history : "server_id"
```

---

## 3. 实体定义

### 3.1 用户与身份领域

#### users
```typescript
interface User {
  id: bigint;               // 主键，自增
  email: string;            // 唯一邮箱（登录标识）
  password: string;         // 密码哈希
  first_name: string | null;
  last_name: string | null;
  username: string | null;  // 身份源展示姓名
  status: number;           // 1=active, 0=inactive, 2=locked
  created_at: datetime;
  updated_at: datetime;
  register_source: string;  // LOCAL | ADMIN_PROVISIONED | BANK_SSO
  login_page_allowed: number; // 1=允许密码登录, 0=禁止
}
```

#### bank_users
```typescript
interface BankUser {
  id: bigint;
  iam_login_no: string;     // IAM 登录号（唯一）
  email: string;            // 邮箱（唯一）
  username: string;         // 姓名
  first_name: string | null;
  last_name: string | null;
  status: string;           // ACTIVE
  created_at: datetime;
  updated_at: datetime;
}
```

#### user_mappings
```typescript
interface UserMapping {
  id: bigint;
  user_id: bigint;          // FK users.id（唯一）
  bank_user_id: bigint;     // FK bank_users.id（唯一）
  mapping_status: string;   // BOUND
  created_at: datetime;
  updated_at: datetime;
}
```

#### users_sso_pre
```typescript
interface UserSsoPre {
  id: bigint;
  user_id: bigint;          // FK users.id
  iam_login_no: string;     // IAM 登录号
  email: string;
  username: string | null;
  status: number;           // 0=PENDING, 1=BOUND
  created_by: bigint;       // FK users.id
  bound_at: datetime | null;
  created_at: datetime;
  updated_at: datetime;
}
```

#### roles
```typescript
interface Role {
  id: bigint;
  name: string;             // 角色标识（唯一，如 super-admin）
  display_name: string;
  description: string | null;
  status: string;           // active/inactive
  created_at: datetime;
  updated_at: datetime;
}
```

#### user_rule_mappings
```typescript
interface UserRuleMapping {
  id: bigint;
  user_id: bigint;          // FK users.id
  collection_id: string;    // 组织 ID 或 *
  project_id: string;       // 项目 ID 或 *
  rule_id: bigint;          // 角色 ID（roles.id）
  rule_name: string;        // 角色标识
}
```

#### user_managed_resource_types
```typescript
interface UserManagedResourceType {
  id: bigint;
  mapping_id: bigint;       // FK user_rule_mappings.id
  resource_type: string;    // CONTEXT|TOOLSET|SPEC|SKILL|WORKSPACE
  created_at: timestamp;
}
```

#### invitations
```typescript
interface Invitation {
  id: bigint;
  inviter_user_id: bigint;  // FK users.id
  invitee_user_id: bigint;  // FK users.id
  invitation_type: string;  // ORG | PROJECT
  collection_id: string;
  project_id: string | null;
  status: string;           // PENDING/ACCEPTED/REJECTED/CANCELLED/EXPIRED/INVALIDATED
  invalidated_reason: string | null;
  created_at: datetime;
  updated_at: datetime;
  expires_at: datetime | null;
  role_mappings_json: object;
  batch_id: string | null;
  processed_at: datetime | null;
  cancelled_by: bigint | null;
  cancelled_at: datetime | null;
  last_reminded_at: datetime | null;
  reminder_count: number;
  invitation_source: string; // ORG | PROJECT
}
```

#### personal_access_tokens
```typescript
interface PersonalAccessToken {
  id: bigint;
  user_id: bigint;          // FK users.id
  name: string;
  token_prefix: string;
  token_hash: string;
  hash_algo: string;        // BCRYPT
  expires_at: datetime;
  revoked_at: datetime | null;
  rotated_at: datetime | null;
  created_at: datetime;
  updated_at: datetime;
}
```

#### notifications
```typescript
interface Notification {
  id: bigint;
  recipient_user_id: bigint; // FK users.id
  sender_user_id: bigint | null; // FK users.id, NULL=系统通知
  type: string;            // INVITATION | GENERAL
  title: string;
  content: string;
  related_invitation_id: bigint | null;
  is_read: number;          // 0=未读, 1=已读
  metadata: object | null;
  created_at: datetime;
  updated_at: datetime;
  expires_at: datetime | null;
}
```

#### org_create_quota_rules
```typescript
interface OrgCreateQuotaRule {
  id: bigint;
  subject_type: string;     // USER_TYPE
  subject_key: string;      // SUPER_ADMIN | NON_SUPER_ADMIN
  quota_limit: number;      // -1=不限
  created_at: datetime;
  updated_at: datetime;
}
```

#### org_create_usage
```typescript
interface OrgCreateUsage {
  id: bigint;
  user_id: bigint;          // 唯一
  used_count: number;
  last_used_at: datetime | null;
  last_collection_id: bigint | null;
  closed_organization_count: number;
  created_at: datetime;
  updated_at: datetime;
}
```

### 3.2 组织与项目领域

#### project_collections
```typescript
interface ProjectCollection {
  id: number;
  guid: string;             // UUID（唯一）
  collection_uid: string;   // 路由 UID（唯一，如 core-banking）
  name: string;
  description: string | null;
  date_created: datetime;
  created_by: string;
  date_updated: datetime;
  updated_by: string;
  status: string;           // active / inactive
}
```

#### projects
```typescript
interface Project {
  id: bigint;
  guid: string;             // UUID（唯一）
  project_uid: string;      // slug（唯一）
  collection_id: bigint;    // 所属集合 ID
  name: string;
  status: string;           // Active / Pending / Completed
  start_date: date | null;
  end_date: date | null;
  date_created: datetime;
  created_by: string | null;
  date_updated: datetime;
  updated_by: string | null;
}
```

#### project_repositories
```typescript
interface ProjectRepository {
  id: bigint;
  project_id: bigint;
  repository_source_type: string; // gitlab | github | custom
  base_url: string | null;
  git_push_base_url: string | null;
  token: string | null;
  repository_auth_type: string;   // none | token
  repository_name: string | null;
  default_branch: string | null;
  status: string;           // Active / Deactive
  date_created: datetime;
  created_by: string | null;
  date_updated: datetime;
  updated_by: string | null;
}
```

### 3.3 工作空间领域

#### workspaces
```typescript
interface Workspace {
  id: bigint;
  guid: string;             // UUID（唯一）
  name: string;
  description: string | null;
  collection_id: bigint;
  project_id: bigint;
  owner_id: bigint;
  type: string;             // CODE | NORMAL
  project_repository_id: bigint | null; // FK project_repositories.id
  status: string;           // Active / Archived
  created_at: datetime;
  created_by: string;
  updated_at: datetime | null;
  updated_by: string | null;
}
```

#### workspace_relations
```typescript
interface WorkspaceRelation {
  workspace_id: bigint;     // PK 复合
  kind: string;             // toolset | context | spec
  ref_id: string;           // 关联 ID
}
```

#### workspace_resource_links
```typescript
interface WorkspaceResourceLink {
  id: bigint;
  workspace_id: bigint;     // FK workspaces.id
  resource_kind: string;    // CONTEXT | TOOLSET | SPEC
  library_context_id: bigint | null; // 仅 CONTEXT
  resource_id: string | null;
  resource_guid: string | null;
  resource_name: string | null;
  resource_description: string | null;
  resource_version: string | null;
  resource_entry_point: string | null;
  resource_date_created: string | null;
  resource_date_updated: string | null;
  resource_created_by: string | null;
  resource_updated_by: string | null;
}
```

#### workspace_run_history
```typescript
interface WorkspaceRunHistory {
  id: bigint;
  guid: string;             // 唯一
  workspace_id: string;
  prompt_text: string | null;
  repo_url: string;
  branch: string;
  triggered_at: timestamp;
  triggered_by: string | null;
  run_id: bigint | null;
  workflow_url: string | null;
  workflow_status: string | null;   // queued/in_progress/completed
  workflow_conclusion: string | null; // success/failure/cancelled/skipped
  status: string;
  error_message: string | null;
  completed_at: timestamp | null;
  duration: number | null;
  verbose: number;
  output_format: string | null;
  pr_url: string | null;
  server_id: bigint | null; // FK pipeline_servers.id
}
```

#### workspace_artifacts
```typescript
interface WorkspaceArtifact {
  id: bigint;
  guid: string;
  workspace_id: bigint;     // FK workspaces.id
  run_history_id: bigint | null; // FK workspace_run_history.id
  storage_name: string;
  relative_path: string;
  artifact_type: string;    // output/log/report/archive/other
  source_type: number;      // 1=WORKSPACE, 2=AGENTORBIT
  file_size_bytes: bigint | null;
  mime_type: string | null;
  file_entries: string | null; // JSON 数组
  total_file_size_bytes: bigint | null;
  status: string;           // Active/Archived/Deleted
  created_at: datetime;
  created_by: string;
  business_file_mapping_id: bigint | null; // FK business_file_mappings.id
}
```

### 3.4 上下文库领域

#### library_contexts
```typescript
interface LibraryContext {
  id: bigint;
  guid: string;             // UUID（唯一）
  name: string;
  description: string | null;
  collection_id: bigint;
  project_id: bigint;
  owner_id: bigint;
  status: string;           // Active / Archived
  auto_sync_enabled: number; // 0/1
  project_repository_id: bigint | null;
  created_at: datetime;
  created_by: string;
  updated_at: datetime;
  updated_by: string;
  delete_flag: number;      // 0=未删除, 1=已删除
}
```

#### library_context_items
```typescript
interface LibraryContextItem {
  id: bigint;
  guid: string;
  context_id: bigint;
  name: string;
  type: string;             // codebase | database | file 等
  uri: string | null;
  branch: string | null;
  project_repository_id: bigint | null;
  promote_file_path: string | null;
  toolset_id: string | null;
  toolset_command: string | null;
  update_toolset_id: string | null;
  update_toolset_command: string | null;
  webhook_enabled: number;
  connection_uri: string | null; // type=database
  status: string;           // Active / Deactive
  sync_status: string;
  synced_at: datetime | null;
  synced_by: string | null;
  created_at: datetime;
  created_by: string;
  updated_at: datetime;
  updated_by: string;
}
```

#### library_context_item_database
```typescript
interface LibraryContextItemDatabase {
  id: bigint;
  guid: string;
  context_id: bigint;
  context_item_id: bigint;
  table_schema: string;
  table_name: string;
  ddl: string;              // CREATE TABLE DDL
  status: string;           // Active
  created_at: datetime;
  created_by: string;
  updated_at: datetime;
  updated_by: string;
}
```

#### library_context_item_file_uploads
```typescript
interface LibraryContextItemFileUpload {
  id: bigint;
  guid: string;
  context_id: bigint;
  context_item_id: bigint;
  original_filename: string;
  stored_filename: string;
  relative_path: string;
  public_uri: string;
  file_mapping_id: bigint | null; // FK business_file_mappings.id
  md5: string;
  is_archive: number;       // 0/1
  archive_type: string | null;   // zip/tar/tgz
  extracted_root_relative_path: string | null;
  file_count: bigint | null;
  total_file_size_bytes: bigint | null;
  content_type: string | null;
  file_size_bytes: bigint | null;
  uploaded_by: string;
  uploaded_at: datetime;
}
```

#### library_context_item_file_upload_entries
```typescript
interface LibraryContextItemFileUploadEntry {
  id: bigint;
  upload_id: bigint;
  relative_path: string;
  file_name: string;
  public_uri: string;
  file_size_bytes: bigint | null;
  md5: string | null;
  created_at: datetime;
}
```

#### library_context_sync_history
```typescript
interface LibraryContextSyncHistory {
  id: bigint;
  guid: string;
  context_id: bigint;
  context_item_id: bigint;
  repo_name: string;
  repo_url: string;
  branch: string;
  triggered_at: datetime;
  triggered_by: string;
  run_id: bigint | null;
  server_id: bigint | null; // FK global_repositories.id
  workflow_url: string | null;
  workflow_status: string | null;
  workflow_conclusion: string | null;
  status: string;           // Success / Failed
  trigger_source: string;   // MANUAL | WEBHOOK
  webhook_config_id: bigint | null;
  commit_sha_before: string | null;
  commit_sha_after: string | null;
  version_before: string | null;
  version_after: string | null;
  error_message: string | null;
  completed_at: datetime | null;
  duration: bigint | null;
}
```

#### library_context_results
```typescript
interface LibraryContextResult {
  id: bigint;
  guid: string;
  context_id: bigint;
  context_item_id: bigint;
  sync_history_id: bigint;
  artifact_name: string;
  file_name: string | null;
  file_content: string | null;
  file_mapping_id: bigint | null; // FK business_file_mappings.id
  created_at: datetime;
  created_by: string;
}
```

#### context_item_webhook_config
```typescript
interface ContextItemWebhookConfig {
  id: bigint;
  context_item_id: bigint;  // 唯一，一对一
  collection_id: bigint;
  project_id: bigint;
  context_id: bigint;
  platform: string | null;  // CODING | GITHUB 等
  repository_url: string | null;
  branch: string | null;
  enabled: number;          // 0/1
  created_at: datetime;
  updated_at: datetime;
  created_by: string;
  updated_by: string;
}
```

#### context_sync_task
```typescript
interface ContextSyncTask {
  id: bigint;
  guid: string;
  context_item_id: bigint;
  status: string;           // PENDING
  trigger_source: string | null;
  trigger_payload: string | null;
  created_at: timestamp;
}
```

#### context_webhook_sync_request
```typescript
interface ContextWebhookSyncRequest {
  id: bigint;
  guid: string;
  context_id: bigint;
  delivery_id: string | null;
  event: string | null;
  scope: string;            // CONTEXT
  raw_payload: string | null;
  status: string;           // RECEIVED
  total_matched: number;
  created_at: timestamp;
}
```

### 3.5 资产管理领域

#### asset_registry_info
```typescript
interface AssetRegistryInfo {
  id: bigint;
  registry_level: string;   // server | project
  registry_id: string;
  config_type: string;      // toolset | spec | mcp | skill
  affiliated_organization: string | null;
  affiliated_project: string | null;
  guid: string | null;
  name: string;
  description: string | null;
  version: string | null;
  download_url: string | null;
  path: string | null;
  entry_point: string | null;
  readme_md_content: string | null;
  commands: string | null;
  scenario: string | null;
  is_share: number;         // 0/1
  category: string | null;  // FK asset_categories.name
  date_created: datetime | null;
  date_updated: datetime | null;
  created_by: string | null;
  updated_by: string | null;
}
```

#### asset_categories
```typescript
interface AssetCategory {
  id: bigint;
  collection_uid: string;   // 组织 UID
  config_type: string;      // toolset/spec/mcp_repo/skill
  name: string;
  sort_order: number;
  is_system: number;        // 0/1
  date_created: datetime;
  date_updated: datetime;
}
```

#### asset_tags
```typescript
interface AssetTag {
  id: bigint;
  asset_registry_id: bigint; // FK asset_registry_info.id
  tag_name: string;
  created_by: string | null;
  date_created: datetime;
}
```

#### asset_command_scenario
```typescript
interface AssetCommandScenario {
  id: bigint;
  config_type: string;
  registry_id: bigint;      // FK asset_registry_info.id
  command: string;
  scenario: string;
  md_content: string | null;
  date_created: datetime | null;
  date_updated: datetime | null;
  created_by: string | null;
  updated_by: string | null;
}
```

#### asset_collections
```typescript
interface AssetCollection {
  id: bigint;
  repository_id: bigint;
  collection_uid: string | null;
  project_uid: string | null;
  date_created: datetime;
  created_by: string;
  date_updated: datetime;
  updated_by: string;
  status: string;           // active/inactive
}
```

#### asset_repositories
```typescript
interface AssetRepository {
  id: bigint;
  asset_level: string;      // org | project
  config_type: string;      // toolset_repo | spec_repo
  repository_source_type: string; // gitlab / github
  base_url: string | null;
  repository_auth_method: string; // public | private
  token: string | null;
  repository_name: string | null;
  default_branch: string | null;
  status: string;           // Active / Deactive
  date_created: datetime;
  created_by: string | null;
  date_updated: datetime;
  updated_by: string | null;
}
```

### 3.6 文件服务领域

#### asdm_file_objects
```typescript
interface AsdmFileObject {
  id: bigint;
  file_id: string;          // UUID（唯一）
  bucket: string;           // S3 bucket
  storage_prefix: string;
  name: string;             // 原始文件名
  content_type: string | null;
  size: bigint;
  is_directory: number;     // 0/1
  status: string;           // ACTIVE/DELETED/ARCHIVED
  created_at: datetime;
  updated_at: datetime;
  deleted_at: datetime | null;
}
```

#### asdm_file_versions
```typescript
interface AsdmFileVersion {
  id: bigint;
  file_object_id: bigint;   // FK asdm_file_objects.id
  version_no: number;       // 从 1 开始
  s3_key_prefix: string;
  size: bigint;
  file_count: number;
  status: string;           // ACTIVE/DELETED
  created_at: datetime;
}
```

#### asdm_file_entries
```typescript
interface AsdmFileEntry {
  id: bigint;
  file_version_id: bigint;  // FK asdm_file_versions.id
  entry_id: string;         // 唯一
  entry_path: string;
  s3_key: string;
  content_type: string | null;
  size: bigint;
  created_at: datetime;
}
```

#### business_file_mappings
```typescript
interface BusinessFileMapping {
  id: bigint;
  guid: string;             // UUID（唯一）
  business_type: string;
  business_id: string;
  bucket: string;
  storage_prefix: string;
  file_uuid: string;
  blob_kind: string;        // FILE/ARCHIVE/ENTRY
  parent_mapping_id: bigint | null; // 自引用 FK
  original_filename: string | null;
  file_size_bytes: bigint | null;
  content_type: string | null;
  status: string;           // ACTIVE/DELETED
  extra_metadata: object | null;
  created_at: datetime;
  created_by: string | null;
  updated_at: datetime;
  updated_by: string | null;
}
```

### 3.7 集成与系统领域

#### adapter_registries
```typescript
interface AdapterRegistry {
  id: bigint;
  adapter_type: string;     // 唯一（如 azure-devops, github, jira）
  service_name: string;
  base_url: string;
  health_endpoint: string;
  status: string;           // active/inactive/error
  health_status: string | null; // healthy/unhealthy
  last_health_check: datetime | null;
  domain_capabilities_json: object | null;
  adapter_metadata_json: object | null;
  date_registered: datetime;
  date_updated: datetime;
}
```

#### integration_configs
```typescript
interface IntegrationConfig {
  id: bigint;
  guid: string;
  name: string;
  adapter_type: string;     // azure-devops/github/jira 等
  project_id: bigint;
  config_json: object;      // 适配器配置参数
  status: string;           // active/inactive/error
  last_connected_at: datetime | null;
  last_error: string | null;
  date_created: datetime;
  created_by: string | null;
  date_updated: datetime;
  updated_by: string | null;
}
```

#### integration_audit_logs
```typescript
interface IntegrationAuditLog {
  id: bigint;
  adapter_type: string | null;
  date_created: datetime;
  error_message: string | null;
  executed_by: string | null;
  integration_id: bigint;
  operation_details: object | null;
  operation_type: string;
  success: boolean;
}
```

#### integration_pat_mapping
```typescript
interface IntegrationPatMapping {
  id: bigint;
  guid: string;
  user_id: bigint;
  asdm_pat_id: bigint | null; // FK personal_access_tokens.id
  adapter_type: string;
  external_pat: string | null;
  status: string;           // active/inactive
  date_created: datetime;
  created_by: string | null;
  date_updated: datetime;
  updated_by: string | null;
}
```

#### repository_project_mappings
```typescript
interface RepositoryProjectMapping {
  id: bigint;
  guid: string;
  integration_config_id: bigint;
  repository_id: bigint;
  external_project_id: string;
  external_project_name: string | null;
  date_created: datetime;
  created_by: string | null;
  date_updated: datetime;
  updated_by: string | null;
}
```

#### pipeline_servers
```typescript
interface PipelineServer {
  id: bigint;
  name: string;
  uname: string;            // 唯一
  server_type: string | null; // github/jenkins
  repository_source_type: string;
  base_url: string | null;
  repository_auth_type: string;
  token: string | null;
  repository_name: string;
  workflow_id: string | null;
  default_branch: string | null;
  // Jenkins 子仓库配置字段...
  jenkins_git_repository_source_type: string | null;
  jenkins_git_base_url: string | null;
  jenkins_git_repository_auth_type: string | null;
  jenkins_git_token: string | null;
  jenkins_git_repository_name: string | null;
  jenkins_git_default_branch: string | null;
  jenkins_context_sync_jenkinsfile: string | null;
  jenkins_workspace_execution_jenkinsfile: string | null;
  status: string;
  asdm_api_pat: string | null;
  date_created: datetime;
  created_by: string | null;
  date_updated: datetime;
  updated_by: string | null;
}
```

#### global_repositories
```typescript
interface GlobalRepository {
  id: bigint;
  name: string;
  uname: string;            // 唯一
  setting_type: string;     // server | pipeline
  pipeline_type: string | null;
  server_type: string | null; // github/jenkins
  repository_source_type: string;
  base_url: string | null;
  repository_auth_type: string;
  token: string | null;
  repository_name: string;
  workflow_id: string | null;
  default_branch: string | null;
  status: string;
  date_created: datetime;
  created_by: string | null;
  date_updated: datetime;
  updated_by: string | null;
}
```

#### config_settings
```typescript
interface ConfigSetting {
  id: number;
  guid: string;
  name: string;
  uname: string;            // 唯一
  level: string;            // server/collection/project/user
  collection_id: number | null;
  project_id: number | null;
  user_id: number | null;
  value: object;            // JSON 配置
  operator_scope: string;   // all-admin | whitelist-admin
}
```

#### feature_flags
```typescript
interface FeatureFlag {
  id: bigint;
  flag_key: string;         // 唯一
  flag_value: string;       // 0=开放, 1=部分开放, 2=关闭
  description: string | null;
  created_by: string | null;
  updated_by: string | null;
  date_created: datetime;
  date_updated: datetime;
}
```

#### feature_flag_allowlist
```typescript
interface FeatureFlagAllowlist {
  id: bigint;
  flag_key: string;
  user_id: bigint;          // FK users.id
  created_at: datetime;
  created_by: string | null;
}
```

#### mcp_routes
```typescript
interface McpRoute {
  id: bigint;
  mcp_server_id: string;    // 唯一
  instance_guid: string;    // UUID（唯一）
  target_url: string;
  name: string | null;
  enabled: number;          // 0/1
  created_at: datetime;
  updated_at: datetime | null;
}
```

#### agentorbit_configs
```typescript
interface AgentorbitConfig {
  id: bigint;
  guid: string;
  name: string;             // 唯一
  server_url: string;
  auth_mode: string;        // client-key | none
  client_key: string | null;
  client_id: string | null;
  infrastructure_image_id: string | null;
  is_active: number;        // 0/1
  created_at: datetime;
  updated_at: datetime;
}
```

#### agentorbit_instances
```typescript
interface AgentorbitInstance {
  id: bigint;
  guid: string;
  user_id: bigint;          // FK users.id
  instance_id: string;      // 唯一
  instance_name: string;
  is_default: number;       // 0/1
  status: string;           // active/stopped/error
  deployment_type: string;  // remote/local/embedded
  agentorbit_config_id: bigint | null; // FK agentorbit_configs.id
  workspace_id: bigint | null;
  type: string | null;      // personal/workspace
  config_snapshot: object | null;
  created_at: datetime;
  updated_at: datetime;
}
```

#### super_admin_operation_audit_logs
```typescript
interface SuperAdminOperationAuditLog {
  id: bigint;
  operation_type: string;   // CREATE/PROMOTE/DEMOTE/RESET_PASSWORD/ENABLE/DISABLE/WHITELIST_GRANT/WHITELIST_REVOKE
  operator_user_id: bigint | null;
  target_user_id: bigint | null;
  request_payload: object | null;
  result_status: string;    // SUCCESS/FAILED/REJECTED
  error_code: string | null;
  error_message: string | null;
  client_ip: string | null;
  user_agent: string | null;
  created_at: datetime;
}
```

#### super_admin_operator_whitelist
```typescript
interface SuperAdminOperatorWhitelist {
  id: bigint;
  operator_user_id: bigint; // 唯一
  operator_email_snapshot: string | null;
  status: string;           // active/inactive
  remark: string | null;
  created_at: datetime;
  created_by: string;
  updated_at: datetime;
  updated_by: string | null;
}
```

#### sys_url_config
```typescript
interface SysUrlConfig {
  id: bigint;
  domain: string;           // 唯一复合（domain+api_path）
  api_path: string;
  description: string | null;
  created_by: string | null;
  updated_by: string | null;
  date_created: datetime;
  date_updated: datetime;
}
```

#### sys_url_mapping
```typescript
interface SysUrlMapping {
  id: bigint;
  method_name: string;      // 唯一复合（method_name+config_id）
  config_id: bigint;        // FK sys_url_config.id
  description: string | null;
  created_by: string | null;
  updated_by: string | null;
  date_created: datetime;
  date_updated: datetime;
}
```

#### reporting_events
```typescript
interface ReportingEvent {
  id: bigint;
  event: string;            // REPORT_DATA
  batch_id: string;
  event_count: number;
  events: string;           // JSON 数组
  active_workspace_id: string | null;
  event_timestamp: datetime;
  created_at: datetime;
}
```

#### flyway_schema_history
```typescript
interface FlywaySchemaHistory {
  installed_rank: number;
  version: string | null;
  description: string;
  type: string;
  script: string;
  checksum: number | null;
  installed_by: string;
  installed_on: timestamp;
  execution_time: number;
  success: number;
}
```

#### one_time_task_control
```typescript
interface OneTimeTaskControl {
  id: bigint;
  task_code: string;        // 唯一
  task_name: string;
  status: string;
  updated_at: timestamp;
}
```

---

## 4. 业务领域分析

### 4.1 领域识别

| 领域 | 核心表 | 描述 |
|------|--------|------|
| **用户与身份** | users, bank_users, user_mappings, users_sso_pre, roles, user_rule_mappings, user_managed_resource_types, invitations, personal_access_tokens, notifications, org_create_quota_rules, org_create_usage | 用户注册、SSO 映射、角色权限、邀请、通知 |
| **组织与项目** | project_collections, projects, project_repositories, asset_collections | 组织集合、项目生命周期、仓库绑定 |
| **工作空间** | workspaces, workspace_relations, workspace_resource_links, workspace_run_history, workspace_artifacts, agentorbit_configs, agentorbit_instances | 工作空间管理、运行历史、制品、数字分身 |
| **上下文库** | library_contexts, library_context_items, library_context_item_database, library_context_item_file_uploads, library_context_item_file_upload_entries, library_context_sync_history, library_context_results, context_item_webhook_config, context_sync_task, context_webhook_sync_request | 上下文空间、条目、同步、Webhook |
| **资产管理** | asset_registry_info, asset_categories, asset_tags, asset_command_scenario, asset_repositories | 工具集/规范/MCP/技能注册、分类、标签 |
| **文件服务** | asdm_file_objects, asdm_file_versions, asdm_file_entries, business_file_mappings | S3 文件对象、版本、条目、业务映射 |
| **集成与系统** | adapter_registries, integration_configs, integration_audit_logs, integration_pat_mapping, repository_project_mappings, pipeline_servers, global_repositories, config_settings, feature_flags, feature_flag_allowlist, mcp_routes, sys_url_config, sys_url_mapping, super_admin_operation_audit_logs, super_admin_operator_whitelist, reporting_events, flyway_schema_history, one_time_task_control | 适配器注册、集成配置、审计、流水线、URL、功能开关 |

### 4.2 领域关系

```mermaid
graph LR
    U[用户与身份] --> O[组织与项目]
    U --> W[工作空间]
    U --> C[上下文库]
    O --> W
    O --> C
    O --> A[资产管理]
    W --> C
    W --> F[文件服务]
    C --> F
    C --> I[集成与系统]
    A --> I
    W --> I
```

**关键依赖链**：
- 用户是所有领域的核心依赖方，通过 `owner_id` / `user_id` / `created_by` 关联
- 组织集合（project_collections）是项目和工作空间的父级容器
- 上下文库依赖项目和组织，同时依赖文件服务存储同步结果
- 工作空间依赖上下文库提供代码上下文，依赖流水线执行任务
- 集成配置连接外部工具（ADO/GitHub/Jira），为上下文同步和代码库映射提供服务

---

## 5. 数据验证规则

### 5.1 字段级约束

| 约束类型 | 示例 | 说明 |
|----------|------|------|
| **唯一性** | users.email, adapter_registries.adapter_type, project_collections.collection_uid, workspaces.guid | 确保实体标识不重复 |
| **NOT NULL** | users.email/password, integration_configs.project_id/config_json, workspaces.collection_id/project_id/owner_id | 核心业务字段不可为空 |
| **长度限制** | varchar(50): adapter_type; varchar(255): name; varchar(512): base_url/repo_url; varchar(2048): last_error | 按业务语义分级长度 |
| **默认值** | status 默认 'active'/1; health_endpoint 默认 '/health'; is_share 默认 0; version_no 默认 1 | 业务默认状态 |
| **JSON 字段** | integration_configs.config_json, config_settings.value, business_file_mappings.extra_metadata, feature_flags.role_mappings_json | 结构化数据存储 |

### 5.2 表级约束

| 约束 | 涉及表 | 说明 |
|------|--------|------|
| **复合唯一键** | uk_collection_type_name(collection_uid,config_type,name), uk_user_rule_mappings_unique(user_id,collection_id,project_id,rule_id), uk_file_version(file_object_id,version_no) | 多维度唯一约束 |
| **外键关系** | fk_agentorbit_instances_config → agentorbit_configs, fk_file_version_object → asdm_file_objects, fk_file_entry_version → asdm_file_versions, fk_asset_tags_registry → asset_registry_info, fk_invitations_invitee → users, fk_notifications_recipient → users, fk_pat_user → users, fk_wa_workspace → workspaces, fk_wrl_workspace → workspaces, fk_url_mapping_config → sys_url_config, fk_umrt_mapping → user_rule_mappings, fk_wrl_library_context → library_contexts, fk_bfm_parent_mapping → business_file_mappings(self), fk_workspaces_project_repository → project_repositories | 实体间引用完整性 |
| **CHECK 约束** | chk_wrl_shape on workspace_resource_links | CONTEXT 类型必须有 library_context_id，TOOLSET/SPEC 类型必须有 resource_id 且 library_context_id 为 null |
| **自引用** | business_file_mappings.parent_mapping_id → business_file_mappings.id | 归档条目指向父归档容器 |
| **级联删除** | ON DELETE CASCADE: asset_tags→asset_registry_info, asdm_file_versions→asdm_file_objects, asdm_file_entries→asdm_file_versions, feature_flag_allowlist→users, workspace_artifacts→workspaces, user_managed_resource_types→user_rule_mappings | 主表删除时自动清理子表 |
| **SET NULL** | ON DELETE SET NULL: agentorbit_instances.agentorbit_config_id, notifications.sender_user_id, workspace_artifacts.run_history_id, library_context_item_file_uploads.file_mapping_id, business_file_mappings.parent_mapping_id | 主表删除时置空引用 |

---

## 6. 数据访问模式

### 6.1 常见查询模式

| 查询场景 | 主要表 | 关键索引 |
|----------|--------|----------|
| 用户登录验证 | users | uk_users_email |
| 用户角色权限 | user_rule_mappings + roles | ix_user_rule_mappings_user_id, ix_user_rule_mappings_collection_id, ix_user_rule_mappings_project_id |
| 邀请管理 | invitations | idx_invitations_invitee_status, idx_invitations_inviter_status |
| 通知列表 | notifications | idx_notifications_recipient_read_created |
| 项目列表 | projects | idx_projects_collection_id |
| 工作空间列表 | workspaces | idx_workspaces_collection_id, idx_workspaces_project_id, idx_workspaces_owner_id |
| 上下文条目同步 | library_context_sync_history | idx_lcsh_context_id_triggered_at, idx_lcsh_context_item_id_triggered_at |
| 上下文结果查找 | library_context_results | idx_lcr_sync_history_id_file_name |
| 集成配置查找 | integration_configs | idx_integration_configs_project_id, idx_integration_configs_adapter_type |
| 功能开关判定 | feature_flags + feature_flag_allowlist | uk_feature_flags_flag_key, uk_flag_key_user_id |
| 文件对象查找 | asdm_file_objects | uk_file_id, idx_status |
| 资源注册查询 | asset_registry_info | idx_asset_registry_project_config_type |
| 超管审计日志 | super_admin_operation_audit_logs | idx_sa_audit_operation_created, idx_sa_audit_target |
| 事件上报查询 | reporting_events | idx_reporting_events_workspace_timestamp |
| PAT 认证 | personal_access_tokens | idx_pat_user_status_page |
| Webhook 同步 | context_webhook_sync_request | idx_context_webhook_sync_request_context_id |

### 6.2 性能考虑

| 项目 | 建议 |
|------|------|
| **library_context_results** | 高增长表，sync_history_id + file_name 复合索引已覆盖主要查询路径；考虑按 context_id 分区 |
| **notifications** | recipient + is_read + created_at 复合索引覆盖未读通知查询；需关注过期清理 |
| **reporting_events** | 批量写入场景，event_timestamp 索引支持时间范围查询；考虑定期归档 |
| **workspace_run_history** | 按 workspace_id + triggered_at 查询为主；已有 status/workflow_status 索引 |
| **library_context_sync_history** | context_item_id + triggered_at 复合索引覆盖同步历史查询 |
| **super_admin_operation_audit_logs** | operation_type + created_at 索引支持按操作类型和时间范围审计 |
| **business_file_mappings** | business_type + business_id 复合索引支持按业务实体查找文件；parent_mapping_id 支持归档层级查询 |
| **missing FK indexes** | integration_configs.project_id 有索引但 project_repositories.project_id 仅单列索引，高并发场景可考虑优化 |