問卷填寫 / 預覽（Survey Fill / Preview）

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

事實基準：2026-07-05 從 FE（views/survey-v2/SurveyPreview.vue、composables/useSurveySocket.js）/ BE（api/task_survey、app/task_survey）code 掃出；表結構取自 db_schema.json（survey schema）；error code 對 common/code/error_code.py

1. 功能描述

本頁是問卷消費端：同一個 SurveyPreview.vue 依 route.query.mode 服務五種模式，涵蓋兩條 route——

• 預覽 /survey/preview/:id（作者端）：唯讀渲染問卷結構，不落資料、不查權限、不連 socket（由設計器/管理頁的預覽鈕開啟）。
• 填寫 /survey/fill?taskSurveyUid=…&mode=fill（消費端）：稽核任務執行者對綁定的問卷快照作答；載入 task_survey + 既有答案 + 權限，連 socket 即時協作，答案持久化。另有 review（審核人給分 / 回饋）、view / history（唯讀檢視 / 看歷史版本）子模式。

填寫的是綁定任務時的問卷快照（is_snapshot=1），非 live 範本（見 _overview §4）。

主要使用者：預覽 = 問卷作者；填寫 = 任務執行者（受稽方）；審核 = 任務指派的審核人（is_approver）。

角色速覽（消費端角色，見 _overview §5）：

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

UC（§2）已展開本頁所有具實質後端寫入邏輯的功能：7-11（狀態機 checkpoint，UC-SVF-01）、8（單題 patch，UC-SVF-04）、12（協作，UC-SVF-02）、13（歷史還原，UC-SVF-03）。純顯示 / 導覽類（1 模式分流、2 題目渲染、3 選項補充、5 進度導覽、6 頁面切換）見 §5 / §10；檔案上傳（4）、討論串（14）、答案 Excel 匯入 / 範本（15）屬常規 CRUD / 任務層，細節見 §6.1 / GAI-SD-02；preview 模式無作答 / 持久化。

2. Use Case

角色速覽（消費端角色，見 _overview §5）：

canEdit / canVerify 由 POST /task-assignees 載入指派名單後判定。流程圖視覺慣例：菱形 = 判斷、橘底 = 例外、紅框 = 錯誤（標 error code）、綠框 = 成功終點、虛線 = 可選路徑。

UC-SVF-01 填答 → 送審 → 審核 → 結案

UC-SVF-02 多人即時協作

UC-SVF-03 歷史版本檢視 / 還原

UC-SVF-04 單題即時暫存（patch，不改狀態 / 不寫歷史）

3. 權限矩陣

⚠️ 可否編輯 / 審核的判定在 FE（canEdit / canVerify 由前端算），BE 端點僅 @jwt_required()、不重新驗證角色與狀態合法性——繞過 FE 可送任意 status。收進 §12。

4. 狀態機與前置條件

消費端填答狀態機（task_surveys.status，TaskSurveyStatusCode）：

轉換：0/1→2（送審，需 approval_required）、1→9（免審核結案）、2→3（退回補充）、3→2（重送審）、2→9（審核通過結案）。轉換合法性只在 FE 動作鈕條件把關，BE checkpoint 直接寫入送入的 status（§12）。

5. UI 設計

📸 實際畫面截圖待補（一律亮色模式拍攝；截圖另有專責 session）。預計補到 assets/img/： ① fill 整頁（左進度 + 中題目）fill-overview.png ② 各題型渲染（單選 + 補充 / 檔案上傳 / 連結）fill-question-types.png ③ 審核區（評分 + 回饋）fill-review-section.png ④ 歷史側欄 / 討論側欄 fill-sidebars.png ⑤ preview 模式唯讀 preview-readonly.png

版面骨架與區塊職責（頂列狀態＋動作、左進度導覽、中題目作答、歷史／討論側欄；彩色區塊可點跳對應小節錨點，API 僅標代表性）：

模式分流：

狀態呈現：頂列動作鈕依 status + 角色動態顯示；題目依 type 分支渲染（唯讀 vs 可編輯由 canEdit / disabled 控）；連結題唯讀時 sanitizeHref 擋 javascript: / data:；線上使用者頭像來自 socket presence。有 socket（fill 模式即時協作）。

6. API 規格

Envelope：成功 {"status": true, "data": …}、失敗 {"error_code": "…", "msg": "…"}。消費端走 api.task_survey 模組（/task-survey*、/project-survey/*）。

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

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

[GET] /project-survey/answers/{uid} — 載入答案

回一個 map：key = question_uid，value = 該題答案物件（取最新，DISTINCT ON 去重）。value 物件欄位：

task_survey 不存在擋 TASK_SURVEY_404001。出處：app/task_survey/service/question_answer_service.py::get_answer_list_by_task_survey_uid:47。

[POST] /project-survey/answers/{uid}/patch — 單題暫存

Request：

{
  "patches": [
    {
      "question_uid": "string",
      "answer": {
        "answer": "string",       // 選填
        "ext_answer": "string",   // 選填
        "feedback": "string",     // 選填
        "ext_feedback": "string", // 選填
        "score": 0                // 選填
      }
    }
  ]
}

單題 upsert，不寫歷史、不改狀態（socket update 也走此邏輯）。題目不存在擋 TASK_SURVEY_404006。出處：question_answer_service.py::patch_task_survey_answer:313、serializer api/task_survey/serializers/question_answer_patch.py。

[POST] /project-survey/answers/{uid}/checkpoint — 批次 + 狀態

Request：

{
  "status": "string",
  "patches": []  // 同上（見上一個 endpoint 的 patches 結構）
}

交易內：① 套用 patch ② 為每題補空列（score=0 / answer=null，確保「所有題都有列」利於乾淨還原）③ 更新 task_survey.status ④ 每題寫 question_answer_histories + _details ⑤ status 變更時通知指派人。分數 null → 0 正規化。出處：question_answer_service.py::checkpoint_task_survey_answer:167、serializer api/task_survey/serializers/question_answer_checkpoint.py。

[POST] /project-survey/history/revert — 還原

Request：

{
  "task_survey_uid": "string",
  "history_uid": "string"
}

把該版明細套回當前答案（現存題才套），寫一筆新歷史 type=R，socket 廣播 reload。歷史主檔 / 明細查無擋 TASK_SURVEY_404003 / 404004。出處：app/task_survey/service/question_answer_history_service.py::revert_question_answer_from_history:44。

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

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

DDD 提醒：消費端在主專案自有 DDD 分層（非 jedi-survey）；answer / history 走 domain service → repo。checkpoint 以 @transaction 包住多表寫入（答案 + 歷史 + 明細 + status）。

9. DB

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

9.2 ER 圖（本頁讀寫範圍）

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

survey.task_surveys — 任務對應問卷（17 欄）

survey.question_answers — 答案（15 欄）

survey.question_answer_histories — 答案版本主檔

uid / task_survey_id / type（U=更新 / R=還原）/ 審計欄位。明細在 question_answer_history_details（history_id + 每題 question_id / score / answer / feedback …）。

10. 頁面邏輯與資料對應

模式分流：mode = route.query.mode || 'preview'。preview 只 getSurveyById(id) 唯讀；fill / review / view / history 載入 task_survey + answers + task-assignees（判 canEdit/canVerify）+ socket。

題型渲染 ↔︎ 答案（answers[questionId] = {answer, ext_answer, feedback, ext_feedback, score}）：

持久化：作答變更 → markDirty + debounce → 單題 patch（socket update 同路徑）；頂列動作 → checkpoint（帶目標 status，寫歷史）。

錯誤對應：TASK_SURVEY_404001（任務問卷不存在）、TASK_SURVEY_404006（題目不存在）、TASK_SURVEY_404003/404004（歷史主檔 / 明細不存在）、TASK_SURVEY_400002（legacy PUT 缺 status/answers）→ toast。

11. 背景行為與外部依賴

12. 邊界情況與已知坑

1. 狀態轉換合法性只在 FE：checkpoint 直接寫入送入的 status，BE 不驗證 0→9、2→1 等是否合法——繞過 FE 動作鈕可送任意狀態。改狀態機時需補 BE 守門。
2. canEdit / canVerify 在 FE 算：可否作答 / 審核由前端依 task-assignees 判定，BE 端點僅 @jwt_required() 不重驗——與作者端一致的守門缺口。
3. checkpoint 補齊空列：每次 checkpoint 為所有題補空列（score=0 / answer=null），確保還原乾淨；統計 / 匯出時「有列 ≠ 有作答」，需以 answer 是否為 null 判斷實際填答。
4. 分數 null→0 不對稱：FE 未評分送 null，BE 正規化為 0；「0 分」與「未評分」在 DB 無法區分，報表勿把 0 當已評分。
5. socket dirty-aware 只在 joined 快照：join 時的 DB 快照合併會保護本地未存答案；但 updated 廣播是權威、直接覆蓋——兩人同時改同題，後到的廣播覆蓋前者，靠編輯鎖（lock/unlock）降低衝突而非強一致。
6. 填的是快照非 live 範本：task_survey.survey_id 指向綁定當下的快照（is_snapshot=1）；作者事後改範本 / 改版不影響進行中的填答（見 _overview §4）。
7. preview 模式無持久化：預覽路徑不載 task_survey、不落資料——別把 preview 當「試填」，作答不會存。
8. 還原寫新歷史（type=R）：還原不是刪除後續版本，而是把舊版套回並記一筆 R 歷史；版本鏈只增不減。

13. 開發與驗證

• 跑起來：BE python main_socketio.py（port 8000，socket 需經 eventlet，log 在 log/app.log）；FE 在 compliance-manager-fe/ 起 Vite dev server。BE 改 service code 後必須重啟（無 hot reload）
• 測試帳號：dev 環境登入帳號密碼見 .env / 部署文件
• 導航路徑：預覽 = 設計器 / 管理頁「預覽」鈕（/survey/preview/:id）；填寫 = 專案任務抽屜「填寫問卷」新分頁開 /survey/fill?taskSurveyUid=…&mode=fill
• 前置資料：填寫需先有綁定問卷的稽核任務（規劃頁 job_type=survey 綁問卷 → 產生 task_survey 快照，見 project-task-edit.md §6.2）；多人協作需兩個帳號同開同 taskSurveyUid
• E2E：compliance-manager-test/ repo（Cucumber + Playwright）；以 問卷填寫 / survey fill 搜尋 feature 檔
• 相關文件：範本設計見 問卷設計器、任務綁定與快照見 project-task-edit.md §6.2 / §12、資料模型見 功能群總覽；DB / API 全量見 GAI-SD-02/03