# GRC 專案使用 Table 盤點

本文件盤點 GRC 專案（compliance-manager）實際使用到的所有資料表，包含主專案自建表、jedi-* 套件表、以及跨模組 mapping 表。用於與 OSCAL 標準進行對照分析。

---

## 總覽

```
┌─────────────────────────────────────────────────────────────────────────┐
│                        GRC Project 使用表總覽                           │
├──────────────────┬──────────────────────────────────────────────────────┤
│ Schema           │ Tables                                              │
├──────────────────┼──────────────────────────────────────────────────────┤
│ compliance       │ 22 tables（專案核心 + 參與人員 + mapping）             │
│ oscal            │ 30+ tables（框架/目錄/Profile/SSP/AP/AR）+ 3 mapping │
│ public (default) │ 15+ tables（auth/workflow/module_frame/device/file） │
│ survey           │ 5 tables（問卷填答）                                  │
├──────────────────┼──────────────────────────────────────────────────────┤
│ 合計             │ ~70+ tables                                         │
└──────────────────┴──────────────────────────────────────────────────────┘
```

---

## 1. 專案核心表（compliance schema）

### 1.1 專案主表

| Table | 來源 | 說明 | 關鍵欄位 |
|-------|------|------|----------|
| `projects` | jedi-project | 專案主體 | `uid`, `name`, `description`, `start_date`, `end_date`, `status`(pending/in_progress/completed/suspended/archived), `tenant_id` |
| `project_extensions` | 主專案 | GRC 擴充（1:1） | PK=`project_id`→projects.id, `module_frame_id`(soft ref), `owner_id`(soft ref→users.id), `deleted_at`(soft delete) |

### 1.2 專案 Mapping 表

| Table | 說明 | FK 關係 | UQ |
|-------|------|---------|-----|
| `project_assessment_plan_mapping` | 專案 ↔ AP | `project_id`→projects, `assessment_plan_id`→oscal.assessment_plans | (project_id, assessment_plan_id) |
| `project_device_mapping` | 專案 ↔ 設備 | `project_id`→projects, `device_id`→devices | (project_id, device_id) |
| `project_org_unit_mapping` | 專案 ↔ 組織 | `project_id`→projects, `org_unit_id`→org_units | (project_id, org_unit_id) |
| `project_system_characteristic_mapping` | 專案 ↔ SSP 系統特性 | `project_id`→projects, `system_characteristic_id`→oscal.ssp_system_characteristics | (project_id, system_characteristic_id) |
| `project_information_systems` | 專案 ↔ 資訊系統 | `project_id`→projects, `information_system_id`→information_systems | (project_id, information_system_id) |

### 1.3 專案報告

| Table | 說明 | 關鍵欄位 |
|-------|------|----------|
| `project_summary_reports` | 專案報告 | `uid`, `project_id`→projects, `name`, `summary`, `is_delete` |
| `project_summary_report_histories` | 報告歷史 | `report_id`→project_summary_reports, `type`(U=update/R=restore), `name`, `summary` |

---

## 2. 參與人員表（compliance schema）

所有參與人員表共通欄位：`is_admin`(0/1), `role`(String), `created_at`, `updated_at`, `created_user`, `updated_user`，以及 `user_info` → `users` 的 viewonly relationship。

| Table | 複合 PK | 說明 |
|-------|---------|------|
| `project_participants` | (project_id, user_id) | 專案層級成員 |
| `process_participants` | (project_id, process_id, user_id) | 子流程（sub-workflow）成員 |
| `project_group_participants` | (project_id, group_id, user_id) | 控制項群組成員 |
| `project_control_participants` | (project_id, group_id, control_id, user_id) | 控制項層級指派 |
| `control_group_participants` | (project_id, group_id, user_id) | 控制項群組參與者 |
| `task_assignees` | (project_id, control_id, task_id, user_id) | 任務指派人員，額外欄位：`task_uid`, `task_template_id`, proxy `user_email` |

### View

| View | 說明 |
|------|------|
| `vw_user_job_queue` | My Jobs 視圖，Join 7+ 張表，PK=(job_id, user_id, control_id)，73 欄位涵蓋 AP task / project / group / control / job / workflow / user |

---

## 3. GRC Job 相關表（compliance schema）

### 3.1 Job 擴充

| Table | 說明 | 關鍵欄位 |
|-------|------|----------|
| `job_execution_comments` | Job 留言/討論 | `job_execution_id`→job_executions, `author_id`→users, `content`, `author_name`(snapshot) |
| `job_execution_devices` | Job ↔ 設備 | `job_execution_id`→job_executions, `device_id`→devices |
| `job_execution_org_units` | Job ↔ 部門 | `job_execution_id`→job_executions, `org_unit_id`→org_units |
| `job_execution_surveys` | Job ↔ 問卷 | `job_execution_id`→job_executions, `survey_id`→surveys |
| `job_execution_device_mapping` | Job ↔ Device（含專案維度） | `project_id`→projects, `workflow_execution_id`→wf, `job_execution_id`→job, `device_id`→devices |
| `review_marks` | 控制項/AO 審核標記 | `project_id`, `group_id`, `control_id`, `ao_id`(NULL=控制項級), `user_id`, `reviewed_at` |

### 3.2 Job 證據

| Table | Schema | 說明 | 關鍵欄位 |
|-------|--------|------|----------|
| `job_evidences` | compliance | Job 執行證據 | PK=`uid`, `main_workflow_execution_id`→wf, `workflow_execution_id`→wf, `job_execution_id`→job, `file_id`→upload_files, `evidence_type`, `ref_id`, `content_hash`, `reference_url`, `description` |

---

## 4. 問卷填答表（survey schema）

| Table | 說明 | 關鍵欄位 |
|-------|------|----------|
| `task_surveys` | 任務問卷（bridge job↔survey） | `uid`, `main_project_id`(wf), `process_id`(wf), `task_id`(job), `survey_id`→surveys, `device_id`→devices, `department_id`→org_units, `status`(0~9), `approval_required`, `is_delete`, `job_evidence_id` |
| `question_answers` | 問題答案 | `task_survey_id`, `survey_id`, `page_id`, `question_id`(soft ref), `score`, `answer`(JSONB), `ext_answer`(JSONB), `feedback`(JSONB), `ext_feedback`(JSONB) |
| `question_answer_histories` | 答案歷史 | `task_survey_id`, `type`(U/R) |
| `question_answer_history_details` | 歷史明細 | `history_id`→qa_histories, `question_id`→survey_questions, 答案 JSONB 快照 |
| `task_survey_ref_items` | 任務問卷參考項目 | PK=(task_survey_id, item_type, item_id) |

---

## 5. 跨模組 Mapping 表（oscal schema，主專案自建）

| Table | 說明 | FK 關係 |
|-------|------|---------|
| `assessment_plan_task_workflow_mapping` | AP Task ↔ WorkflowTemplate | `assessment_plan_task_id`→ap_tasks, `workflow_template_id`→wf_templates |
| `assessment_plan_task_workflow_execution_mapping` | AP Task ↔ WorkflowExecution | `assessment_plan_task_id`→ap_tasks, `workflow_execution_id`→wf_executions |
| `profile_assessment_workflow_mapping` | ProfileControl ↔ Assessment ↔ WfTemplate（三方） | `profile_control_id`→profile_controls, `catalog_control_assessment_id`→catalog_ctrl_assessments, `workflow_template_id`→wf_templates |
| `workflow_execution_control_mapping` | WorkflowExecution ↔ OSCAL 控制項 | `workflow_execution_id`→wf_executions, `version_id`→oscal_framework_versions, `control_id`(String) |

---

## 6. Module Frame（public schema）

| Table | 說明 | 關鍵欄位 |
|-------|------|----------|
| `module_frames` | 合規資源庫模板 | `uid`, `name`, `group`, `template_uid`, `frequency`, `version`, `enable`, `description`, `provider`, `oscal_framework_version_uid`(soft ref), `oscal_profile_uid`(soft ref), `tenant_id`, `org_unit_id` |
| `module_frames_trans` | 模板 i18n 翻譯 | `module_frame_id`→module_frames, `language_code`, `name`, `group`, `description` |

---

## 7. jedi-* 套件表（專案直接使用）

### 7.1 Auth（jedi-auth, public schema）

| Table | 專案使用方式 |
|-------|-------------|
| `users` | 解析 owner_uid → owner_id、參與人員 user_info、任務指派 |
| `tenants` | RLS 隔離、專案所屬租戶 |
| `org_units` | 組織單位：部門指派、project_org_unit_mapping |
| `roles` | 角色查詢（participant role） |
| `user_roles` | 判斷 is_admin |
| `user_tenants` | 多租戶關聯 |
| `user_org_units` | 組織關聯 |

### 7.2 Workflow Engine（jedi-flow-engine, public schema）

| Table | 專案使用方式 |
|-------|-------------|
| `workflow_templates` | BPMN 模板：Module Frame 建立時 clone、專案啟動時再 clone（定版） |
| `workflow_templates_trans` | 模板 i18n |
| `workflow_executions` | 工作流實例：專案啟動時每個 AP task 建立一個 sub-workflow |
| `job_executions` | 任務實例：`type=USER` 的 job 即 GRC Job，擴充 `task_type`、`guide` 欄位 |
| `element_variables` | 任務變數：存放 devices、comment 等 runtime 資料（JSONB） |

> 主專案 extend_existing 擴充 `workflow_executions`，加入 participant 關聯與 sub_workflows 統計。

### 7.3 OSCAL（jedi-oscal, oscal schema）

| Table Group | Tables | 專案使用方式 |
|-------------|--------|-------------|
| **Framework** | `oscal_frameworks`, `oscal_framework_versions` | Module Frame 綁定框架版本 |
| **Catalog** | `catalogs`, `catalog_groups`, `catalog_controls`, `catalog_control_parts`, `catalog_control_parameters`, `catalog_control_assessments` | 控制項全集：Profile 從中選取子集 |
| **Profile** | `profiles`, `profile_controls` | Module Frame 的控制項選取 |
| **SSP** | `system_security_plans`, `ssp_system_characteristics`, `ssp_system_implementations`, `ssp_control_implementations` | 專案啟動時建立 SSP + 系統特性快照 |
| **AP** | `assessment_plans`, `assessment_plan_groups`, `assessment_plan_controls`, `assessment_plan_tasks`, `assessment_task_control` | 專案核心：控制項群組→控制項→評估物件，狀態追蹤 |
| **AR** | `assessment_results`, `assessment_result_datas`, `assessment_result_controls`, `assessment_result_evidences`, `assessment_result_findings` | 評估結果：判定/證據/發現 |
| **Base** | `oscal_documents`, `oscal_metadatas`, `oscal_props`, `oscal_remarks`, `oscal_roles`, `oscal_parties`, `oscal_locations`, `oscal_links`, `oscal_responsible_parties` | OSCAL 共用元件 |
| **Mapping** | `oscal_control_mapping` | 跨框架控制項對應 |

### 7.4 Device（jedi-device, public schema）

| Table | 專案使用方式 |
|-------|-------------|
| `devices` | 設備管理：`uid`, `name`, `ip`, `os`, `hostname`, `device_type`, `manufacture`, `status`(1=正常/0=異常), `purpose`, `tenant_id` |

### 7.5 Information System（主專案 jedi_information_system, compliance schema）

| Table | 專案使用方式 |
|-------|-------------|
| `information_systems` | 資訊系統（受稽系統）：`uid`, `name`, `abbreviation`, `description`, `security_sensitivity_level`(low/moderate/high), `system_status`(operational/under-development/disposition), `system_owner`(soft ref→users.id), `is_active` |
| `project_information_systems` | 專案 ↔ 資訊系統 mapping |

### 7.6 Survey（jedi-survey, public schema）

| Table | 專案使用方式 |
|-------|-------------|
| `surveys` | 問卷主體：含 `is_snapshot`(0/1)、`source_survey_id` 支援快照 |
| `survey_folders` | 問卷分類資料夾，快照會建在 `__snapshots__<project_uid>` folder |
| `survey_pages` | 問卷頁面（樹狀 pid） |
| `survey_questions` | 問卷題目（樹狀 pid），`options`/`tags`/`references`(JSONB) |
| `survey_discussions` | 問卷討論 |
| `surveys_trans` / `survey_pages_trans` / `survey_questions_trans` / `survey_folders_trans` | i18n 翻譯表 |

### 7.7 File Upload（jedi-file-upload, public schema）

| Table | 專案使用方式 |
|-------|-------------|
| `upload_files` | 檔案上傳：`uid`, `file_name`, `file_ext`, `save_file_name`, `size`, `mimetype`, `path`, `storage_type`, `ref_id`, `checksum`。被 `job_evidences.file_id` 參照 |

### 7.8 其他（public schema）

| Table | 說明 |
|-------|------|
| `subtask_status_histories` | 子任務狀態歷史：`task_id`, `ref_id`, `type`(device), `status` |
| `feedback_issues` | 回饋議題：`issue_uid`, `gitlab_issue_uid`, `github_issue_uid` |
| `bulletins` / `bulletin_org_units` | 公告（extend_existing 加 TenantScopedMixin） |

---

## 8. 專案生命週期 × Table 對照

### 8.1 Module Frame 建立（POST /module-frame）

```
寫入：
  module_frames                              ← 建立模板
  module_frames_trans                        ← i18n
  profiles + profile_controls                ← 建立 Profile（選取控制項子集）
  workflow_templates                         ← 建立 BPMN 主/子流程模板
  profile_assessment_workflow_mapping        ← 綁定 assessment → workflow_template

讀取：
  oscal_framework_versions → oscal_frameworks  ← 驗證框架版本
  catalogs → catalog_groups → catalog_controls ← 取得控制項
  catalog_control_assessments                  ← 取得評估項目
```

### 8.2 專案啟動（POST /oscal/projects/start）

```
寫入（單一 @transaction，依序）：
  1. system_security_plans                   ← 建立空 SSP（若無現有）
  2. assessment_plans                        ← 建立 AP（status=ACTIVE）
  3. assessment_results                      ← 建立 AR
  4. projects                                ← 建立 Project（jedi-project）
  5. project_extensions                      ← GRC 擴充
  6. project_assessment_plan_mapping         ← 綁定 Project ↔ AP
  7. assessment_plan_groups                  ← 從 Catalog clone 群組
     assessment_plan_controls                ← 從 Catalog clone 控制項
     assessment_plan_tasks                   ← 從 Catalog clone 評估物件
     assessment_task_control                 ← Task ↔ Control 關聯
  8. workflow_templates (clone)              ← 每個 AP task clone 定版模板
     assessment_plan_task_workflow_mapping   ← AP task ↔ 定版 template
     workflow_executions                     ← 每個 AP task 建立 sub-workflow
     job_executions                          ← workflow 自動產生 job
     assessment_plan_task_workflow_execution_mapping ← AP task ↔ wf_execution
  9. ssp_system_characteristics              ← 受稽系統快照到 SSP
     project_system_characteristic_mapping   ← Project ↔ SSP 系統特性
     project_information_systems             ← Project ↔ 資訊系統
  10. project_participants                   ← 建立者 + 額外參與者
  11. project_device_mapping                 ← 專案設備

讀取：
  profiles → profile_controls → catalog_controls ← Profile Resolution
  catalog_control_assessments                    ← 評估項目
  module_frames                                  ← 反查 module_frame_id
  information_systems                            ← 受稽系統資料
  users                                          ← 解析 owner_uid
```

### 8.3 專案執行（GRC 日常操作）

```
控制項群組列表：
  讀取：assessment_plan_groups, assessment_plan_controls, assessment_plan_tasks
       project_group_participants, review_marks, job_executions

控制項列表：
  讀取：assessment_plan_controls, assessment_plan_tasks
       project_control_participants, task_assignees, review_marks

評估物件（AO）列表：
  讀取：assessment_plan_tasks
       assessment_plan_task_workflow_execution_mapping → workflow_executions → job_executions

Job 管理（CRUD）：
  讀寫：job_executions (name, description, task_type, guide)
       task_assignees (指派人員)
       job_execution_org_units (部門)
       job_execution_surveys (問卷)
       job_execution_devices (設備)
       task_surveys (問卷 × 設備 笛卡兒積)
       job_evidences (證據)
       element_variables (devices 等 runtime 變數)
       surveys (快照 is_snapshot=1)

Job 留言：
  讀寫：job_execution_comments

問卷填答：
  讀寫：task_surveys, question_answers
       question_answer_histories, question_answer_history_details
       task_survey_ref_items

審核標記：
  讀寫：review_marks

Dashboard：
  讀取：projects, assessment_plans, assessment_plan_groups
       assessment_plan_controls, assessment_plan_tasks, job_executions
       project_participants
```

### 8.4 專案刪除

```
刪除（依序）：
  project_assessment_plan_mapping
  project_system_characteristic_mapping
  project_device_mapping
  task_assignees
  control_group_participants
  project_control_participants
  project_group_participants
  project_participants
  projects (soft delete)
```

---

## 9. Table 分類統計

### 按功能分類

| 分類 | 表數量 | 表列表 |
|------|--------|--------|
| **專案核心** | 2 | projects, project_extensions |
| **專案 Mapping** | 5 | project_assessment_plan_mapping, project_device_mapping, project_org_unit_mapping, project_system_characteristic_mapping, project_information_systems |
| **參與人員** | 6 + 1 view | project_participants, process_participants, project_group_participants, project_control_participants, control_group_participants, task_assignees + vw_user_job_queue |
| **GRC Job 擴充** | 6 | job_execution_comments, job_execution_devices, job_execution_org_units, job_execution_surveys, job_execution_device_mapping, review_marks |
| **Job 證據** | 1 | job_evidences |
| **問卷填答** | 5 | task_surveys, question_answers, question_answer_histories, question_answer_history_details, task_survey_ref_items |
| **跨模組 Mapping** | 4 | ap_task_workflow_mapping, ap_task_workflow_execution_mapping, profile_assessment_workflow_mapping, workflow_execution_control_mapping |
| **Module Frame** | 2 | module_frames, module_frames_trans |
| **專案報告** | 2 | project_summary_reports, project_summary_report_histories |
| **OSCAL 核心** | 30+ | 見 oscal-table.md |
| **Workflow** | 5 | workflow_templates, workflow_templates_trans, workflow_executions, job_executions, element_variables |
| **Auth** | 7+ | users, tenants, org_units, roles, user_roles, user_tenants, user_org_units |
| **資訊系統** | 2 | information_systems, project_information_systems |
| **設備** | 1 | devices |
| **問卷管理** | 9+ | surveys, survey_folders, survey_pages, survey_questions, survey_discussions + 4 trans 表 |
| **檔案** | 1 | upload_files |
| **其他** | 3 | subtask_status_histories, feedback_issues, bulletins |

### 按 Schema 分類

| Schema | 主專案自建 | jedi-* 套件 | 合計 |
|--------|-----------|-------------|------|
| `compliance` | 22 | 2 (projects, information_systems) | ~24 |
| `oscal` | 4 (mapping) | 30+ | ~34 |
| `public` | 5 | 25+ | ~30 |
| `survey` | 5 | 0 | 5 |
| **合計** | **36** | **57+** | **~93** |

### 按資料來源分類

| 來源 | 說明 | 表數量 |
|------|------|--------|
| 主專案獨立建置 | 不在任何 jedi-* 套件中 | ~36 |
| jedi-oscal | OSCAL 核心 | ~30 |
| jedi-flow-engine | 工作流引擎 | ~5 |
| jedi-auth | 認證授權 | ~10 |
| jedi-survey | 問卷管理 | ~9 |
| jedi-project | 專案基礎 | ~1 |
| jedi-device | 設備管理 | ~1 |
| jedi-file-upload | 檔案上傳 | ~1 |

---

## 10. 與 OSCAL 對照要點

以下整理目前專案中「非 OSCAL 標準但功能重疊」的表，供後續與 OSCAL SSP/AP/AR 對照：

| 專案表（非 OSCAL） | 對應 OSCAL 概念 | 差異說明 |
|-------------------|----------------|----------|
| `information_systems` | SSP `system-characteristics` | 獨立管理，專案啟動時快照到 `ssp_system_characteristics` |
| `devices` | SSP `system-implementation.components` (type=hardware) | 獨立設備管理，未對應到 OSCAL component 結構 |
| `project_device_mapping` | SSP `system-implementation.components[]` | 多對多關聯，OSCAL 是 SSP 內嵌 |
| `project_org_unit_mapping` | SSP `system-implementation.users[].authorized-privileges` | 組織參與，OSCAL 用 responsible-parties |
| `project_participants` | AP `assessment-subjects` + SSP `responsible-parties` | 6 層參與人員結構，OSCAL 較扁平 |
| `task_assignees` | AP `tasks[].responsible-roles` | 任務指派，OSCAL 用 role-based |
| `job_evidences` | AR `observations[].relevant-evidence` | 證據管理，OSCAL 有更結構化的 observation 模型 |
| `task_surveys` | AP `tasks[].activities[].steps[]` | 問卷填答 = 評估執行步驟，OSCAL 無問卷概念 |
| `question_answers` | AR `observations[]` | 問卷答案 ≈ 觀測紀錄，但結構不同 |
| `review_marks` | AR `attestations[]` | 審核標記 ≈ 證實，OSCAL 有 responsible-parties |
| `job_execution_comments` | AR `observations[].remarks` | Job 留言 ≈ 觀測備註 |
| `project_summary_reports` | AR `results[].remarks` / POA&M | 專案報告，可對應 AR 摘要或 POA&M |
| `subtask_status_histories` | 無直接對應 | OSCAL 不追蹤子任務級狀態變更 |
| `workflow_templates` / `workflow_executions` | AP `tasks[]` | BPMN 工作流 ≈ OSCAL 評估任務，但執行模型完全不同 |
| `element_variables` | 無直接對應 | Runtime 變數，OSCAL 不涉及執行層 |
| `module_frames` | Profile + AP template | 合規模板 = OSCAL Profile + 預設 AP 結構的打包 |