問卷管理頁（Survey Manage）

功能群：問卷｜資料模型與雙生命週期先讀 功能群總覽

事實基準：2026-07-05 從 FE（views/survey-v2/SurveyManage.vue 等）/ BE（api/survey、jedi-survey 套件）code 掃出；表結構取自 db_schema.json（survey schema）；error code 對 jedi_survey/common/enum/error_code.py 與 common/code/grc_error_code.py

1. 功能描述

問卷管理頁是作者端問卷範本的入口與總覽：左側資料夾樹分類、主區以卡片或表格列出問卷，提供建立 / 複製 / 另存新版 / 發布 / 移動 / 刪除 / 批量匯入。點問卷進問卷設計器編輯題目結構；問卷發布後才能被專案規劃頁的稽核任務選用（綁定時取快照，見 _overview §4）。

主要使用者：問卷範本作者（以選單能力控管，非專案層角色，見 _overview §5）。清單僅顯示範本（is_snapshot=0），看不到消費端快照。

角色速覽（作者端以選單能力控管，非專案 manager/auditor，見 _overview §5）：

1.1 功能總覽（本頁全部功能）

UC（§2）已展開本頁所有具實質後端邏輯的功能：瀏覽 / 搜尋 / 篩選（1/5/6/7）、建立 / 複製 / 另存新版 / 發布（9/12/14）、刪除問卷 / 資料夾（15/16/2 刪除路徑）、批量匯入（17）、資料夾建立 / 更名 + 問卷移動（2 建立更名 / 13）。純顯示 / 導覽類（4 統計腳、8 檢視切換）見 §5 / §10；進設計器 / 預覽（10/11）另屬所屬頁面 spec，於此只交叉連結不重複。

2. Use Case

角色速覽（作者端以選單能力控管，非專案 manager/auditor，見 _overview §5）：

流程圖視覺慣例：菱形 = 判斷、橘底 = 例外 / 擋下、紅框 = 錯誤（標 error code）、綠框 = 成功終點、虛線 = 可選路徑。

UC-SVM-01 瀏覽 / 搜尋 / 篩選問卷

UC-SVM-02 建立 / 複製 / 另存新版 / 發布

UC-SVM-03 刪除問卷 / 資料夾

UC-SVM-04 批量匯入問卷（Excel 三 sheet）

UC-SVM-05 資料夾建立 / 更名 + 問卷移動

3. 權限矩陣

作者端角色基調見 _overview §5。本頁實際檢查點（FE 判定與 BE 強制分欄並列）：

⚠️ 已知安全缺口（維護時注意）：作者端問卷 / 資料夾的寫入與刪除只有 JWT、無角色守門——任何登入者只要能到此頁就能改 / 刪任一問卷。清單另附的 GRC_SURVEY_HAS_ANSWERS 守門只保護規劃頁任務移除問卷的路徑（app/grc/service/job_service.py:374），不保護本頁刪除。收進 §12。

4. 狀態機與前置條件

本頁的問卷狀態是作者端發布生命週期（surveys.release，見 _overview §3）；消費端填答狀態機不在此頁。

5. UI 設計

📸 實際畫面截圖待補（一律亮色模式拍攝；截圖另有專責 session）。預計補到 assets/img/： ① 整頁（左資料夾樹 + grid 卡片）manage-overview.png ② 卡片三點選單（編輯 / 預覽 / 複製 / 移動 / 刪除）manage-card-menu.png ③ 建立問卷 dialog manage-create-dialog.png ④ BatchImportDialog manage-import-dialog.png

版面骨架與區塊職責（工具列、左資料夾樹＋統計腳選夾 → 右問卷清單分頁，建立／匯入 dialog；彩色區塊可點跳對應小節錨點，API 僅標代表性）：

狀態呈現：grid 卡片頂色條依狀態（發布 / 草稿 / 範本）；grid / table 由 viewMode 切換；勾選列出現時工具列才顯示批次刪除；卡片 menu 的「刪除」對 hasAnswer=true 的問卷 toast 阻止。切資料夾時多次 fetchSurveys 以遞增 reqId 只保留最新回應（useSurveyApi.js:103-124）。無 socket（作者端管理頁不即時協作；即時協作只在填寫頁）。

6. API 規格

Envelope：成功 {"status": true, "data": …, "meta": …}（清單帶分頁 meta）、失敗 {"error_code": "…", "msg": "…"}。

6.1 總清單（本頁呼叫的全部 endpoint）

6.2 核心 endpoint（欄位對照 serializer / service，出處標段末）

[POST] /surveys — 分頁清單

Request：

{
  "pager": {
    "page": 0,
    "page_size": 0,
    "with_total": true
  },
  "sort": [
    {
      "field": "string",
      "order": "string"
    }
  ],
  "filters": {
    "is_delete": 0  // 其他 filter 條件
  }
}

BE 強制 is_snapshot=0（只回範本）。

Response data（陣列，每項 = 問卷 DTO）核心欄位：

出處：api/survey/routes/survey_route.py:54-96（SurveysRoute + has_answer enrich）、DTO jedi_survey SurveyEntity。

[POST] /survey ・ [PUT] /survey/{uid} — 建立 / 更新

Request（建立）：

release_at 於 route 層 datetime.strptime(...[:10]) 只取日期。出處：api/survey/routes/survey_route.py:99-141、jedi_survey/app/service/survey.py::add_survey。

[POST] /survey/{uid}/clone — 深度複製

Request：

{
  "name": "string",
  "folder_uid": "string"  // 選填
}

深度複製 pages / questions / _trans 翻譯，新問卷 group_id = 新 survey.id（獨立版本序列）。同名擋 SURVEY_409002（問卷已存在）。出處：app/survey/service/survey_clone_service.py。

[PUT] /survey/{uid}/release ・ [DELETE] .../release — 發布 / 取消

PUT body {release_target} → release=1 + release_at；DELETE → release=0。出處：api/survey/routes/survey_route.py::SurveyReleaseRoute。

[DELETE] /survey/{uid} — 軟刪除

無 body。BE 僅驗證存在後 is_delete=1，不檢查 has_answer（FE 才擋）。出處：api/survey/routes/survey_route.py:145-149 → jedi_survey/app/service/survey.py::delete_survey:197。

資料夾 CRUD

POST /survey-folder {name, description}；PUT /survey-folder/{uid} {name, description}（同名擋 SURVEY_409007）；DELETE /survey-folder/{uid} 無條件軟刪除（不檢查含問卷）。審計欄位 enrich created_user_name / updated_user_name。出處：api/survey/routes/survey_folder_route.py、jedi_survey/app/service/survey_folder.py。

[POST] /survey/excel-import — 批量匯入

FormData：

缺欄擋 TASK_SURVEY_400001（Excel 必含 No / Question 欄——共用匯入驗證）。出處：api/survey/routes/survey_route.py::SurveyExcelImportRoute。

7. 前端檔案地圖（compliance-manager-fe/）

8. 後端檔案地圖（本頁核心鏈路）

DDD 提醒：問卷 domain / repo 在 jedi_survey 外部套件；主專案 route 只做 HTTP 邊界 + audit 欄位 enrich。作者端 route 全部僅 @jwt_required()，未加角色守門（見 §3 缺口）——新增寫入端點時勿比照，應補角色檢查。

9. DB

9.1 資料表總清單（本頁讀寫的全部表）

9.2 ER 圖（本頁讀寫範圍）

9.3 核心表欄位（取自 DEV DB dump，含 DB comment）

survey.surveys — 問卷主檔（20 欄）

survey.survey_folders — 資料夾（樹）

翻譯表 survey.surveys_trans / survey_folders_trans

surveys_trans：survey_id / name / description / release_target / language_code；survey_folders_trans：survey_folder_id / name / description / language_code。寫入含翻譯欄位要傳 locale（見 _overview §6.3 / docs/claude/translatable-fields.md）。

10. 頁面邏輯與資料對應

載入時序：見 §2 UC-SVM-01（資料夾與清單並行，reqId 防亂序）。

關鍵欄位對應（API ↔︎ 畫面）：

儲存流程：建立 dialog → POST /survey → 成功導向設計器；複製 / 移動 / 發布 / 刪除確認後呼叫對應 endpoint → 重查清單。批量匯入成功後重載 folders + surveys。

錯誤對應：BE error envelope → toast。常見碼：SURVEY_404002（問卷不存在）、SURVEY_409002（複製同名）、SURVEY_409007（資料夾同名）、TASK_SURVEY_400001（匯入 Excel 缺 No/Question 欄）。

11. 背景行為與外部依賴

12. 邊界情況與已知坑

1. 作者端寫入無角色守門（安全缺口）：問卷 / 資料夾的建立 / 更新 / 刪除 route 只有 @jwt_required()，無 manager / 能力層強制——任何能到此頁者皆可改 / 刪任一問卷。修法應在 route 或 app service 補角色 / 能力檢查。
2. 刪除問卷 BE 無答案守門：DELETE /survey/{uid} 只軟刪除，不檢查 has_answer；守門只在 FE（survey.hasAnswer 擋）。GRC_SURVEY_HAS_ANSWERS（GRC_409033）只保護規劃頁任務移除問卷的路徑（job_service.py:374），與本頁刪除無關。繞過 FE 直接呼叫可刪掉已有填答資料的範本。
3. 刪資料夾不檢查是否含問卷：delete_folder 無條件軟刪除；夾內問卷 folder_id 仍指向已軟刪除的資料夾（孤兒）。清單以資料夾 is_delete=0 過濾，被孤立問卷可能在樹上找不到入口。
4. 範本 vs 快照同表：survey.surveys 同時放範本列（is_snapshot=0）與消費端快照列（is_snapshot=1）；管理頁一律 is_snapshot=0，別在此頁查 / 改到快照。
5. 版本語意：「另存新版」= 保留舊版 + 同 group_id 新 version_no 列；「複製」= 全新 group_id（獨立序列）。兩者都不影響已綁定任務的快照（快照綁定當下已脫鉤）。
6. 切資料夾亂序：fetchSurveys 以遞增 reqId 保證只有最新請求寫入 state（useSurveyApi.js:103-124）；慢回的舊請求丟棄——維護分頁 / 篩選邏輯時勿破壞此保護。
7. 可翻譯欄位：改 name / description / release_target 未傳 locale 只更新主表；讀取走 failover 優先翻譯表 → 前端可能看不到主表變更（見 docs/claude/translatable-fields.md）。

13. 開發與驗證

• 跑起來：BE python main_socketio.py（port 8000，log 在 log/app.log）；FE 在 compliance-manager-fe/ 起 Vite dev server。BE 改 service code 後必須重啟（無 hot reload）
• 測試帳號：dev 環境登入帳號密碼見 .env / 部署文件
• 導航路徑：登入 → 側邊選單「問卷」→ 問卷管理（/survey/manage）
• 前置資料：至少一個資料夾才能建問卷；「從樣板複製」需有 is_sample=1 的範本
• E2E：compliance-manager-test/ repo（Cucumber + Playwright）；以 問卷 / survey 搜尋 feature 檔
• 相關文件：題目編輯見 問卷設計器、填答 / 預覽見 問卷填寫 / 預覽、任務綁定見 project-task-edit.md §6.2；DB / API 全量見 GAI-SD-02/03