任務時間到在同一筆上再跑一輪、掃描自己跑、掃到新的高風險多通知一個人

狀態：已上線／收尾（2026-10-14，全部卡 Done）｜收尾彙整：handoff/2026-10-14-FR-137-SUMMARY.md｜討論稿：discussion.md｜雛形：prototype/index.html

本文件描述上線的現況與決策理由。雛形三頁是設計階段的畫面，週期列文字與 Dialog 內容以 §6.7 為準。檔案路徑會隨程式漂移，查不到時以函式名重新定位。路徑慣例：BE 路徑相對 compliance-manager-be/；pkg/ 代表 ~/Projects/Jedicogy/module/jedi-python-package/；FE 路徑相對 compliance-manager-fe/。

稽核裡很多工作不是做一次就好——每月掃一次源碼弱點、每季填一次問卷、每年檢視一次程序書。本案讓任務帶一組週期設定：時間到了，系統在同一筆任務上再跑一輪並提醒執行人。對使用者來說一個週期任務就是一張卡，每一輪多一筆執行紀錄、多一批證據，都在同一筆任務裡。

掃描類任務更進一步：開了自動執行，時間到直接開掃，不用人按。檢測工具派給 agent，SBOM 原始碼掃描沿用上次上傳的源碼包。

CRA 要求製造商知悉高風險漏洞要及時處理，負責對外通報的人常常不是執行人。所以 SBOM 掃完時與這筆任務上一次成功的掃描比，新出現 high（含）以上的弱點時，多寄一封信給指定的人，每封留一筆紀錄，稽核時可拿來證明「知悉後有通知」。同一批老弱點不會每輪重寄。

資訊系統的版本支援期到期前 90／30／7 天提醒，走同一支排程與同一張紀錄表。

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','secondaryColor':'#EEF2F3','secondaryTextColor':'#14201F','tertiaryColor':'#FBFCFC','tertiaryTextColor':'#14201F','lineColor':'#4A5A5C','textColor':'#14201F','mainBkg':'#E2F0F1','nodeBorder':'#0E7C86','nodeTextColor':'#14201F','edgeLabelBackground':'#FBFCFC','titleColor':'#14201F','clusterBkg':'#FBFCFC','clusterBorder':'#E4EAEB','actorBkg':'#E2F0F1','actorTextColor':'#14201F','actorBorder':'#0E7C86','actorLineColor':'#C7D1D2','signalColor':'#4A5A5C','signalTextColor':'#14201F','labelBoxBkgColor':'#EEF2F3','labelBoxBorderColor':'#C7D1D2','labelTextColor':'#14201F','loopTextColor':'#14201F','noteBkgColor':'#F6EBD5','noteTextColor':'#14201F','noteBorderColor':'#9C6B12','activationBkgColor':'#EEF2F3','activationBorderColor':'#C7D1D2','sequenceNumberColor':'#FFFFFF'}}}%%
flowchart TD
    MF[資源庫 frequency] -.建專案時帶預設頻率.-> P[規劃頁任務週期設定<br/>頻率・間隔・下次啟動・自動執行・額外通知]
    P --> T{{每 5 分鐘 tick<br/>撈 next_due_at 已到的任務}}
    T --> S{輪次結案或<br/>專案結束？}
    S -- 是 --> Z[清空 next_due_at，不再啟動]
    S -- 否 --> U[條件式推進：next_due_at 往後推一格<br/>run_count＋1・last_run_at]
    U --> O[任務已完成就重開成進行中]
    O --> K{檢測工具任務且<br/>自動執行開著？}
    K -- 是 --> A[直呼派工入口開掃<br/>執行紀錄 created_user=system]
    K -- 否 --> M
    A --> M[寄信提醒執行人]
    A --> D2[SBOM：沿用上次源碼包排背景掃]
    D2 --> C[掃描完成回呼 on_scan_completed]
    C --> F{與同一筆任務上一次成功掃描比<br/>有新出現 high 以上？}
    F -- 否 --> X[不寄・不記]
    F -- 是 --> R[寄給額外通知對象<br/>＋寫通知紀錄]

整案一句話：任務上多一組週期設定；每 5 分鐘排程把到期的任務在原地重開、推進下次啟動時間並提醒執行人或直接開掃；SBOM 掃完比對同一筆任務上一次成功掃描，新出現 high 以上就寄給額外通知對象並記一筆。

上一輪還沒做完、下一次啟動時間又到了：照樣推進並提醒，任務維持進行中，不會疊出第二筆。

6.1 資料模型

① compliance.job_executions 週期欄（jedi-flow-engine ORM／entity／mapper 三處帶欄；主線 migration 2026-10-12-fr137-job-recurrence.sql 與 2026-10-13-fr137-job-recurrence-same-task.sql，出貨基線已含最終結構）：

CREATE INDEX IF NOT EXISTS ix_job_executions_next_due_at
    ON compliance.job_executions (next_due_at) WHERE next_due_at IS NOT NULL;

寫入驗證（job_recurrence_validator.py）：recur_unit 必為 task_frequency 的 enable key；recur_interval ≥ 1；開重複時 next_due_at 必填；auto_execute／alert_recipients 只接受檢測工具任務，其他型別送來回 400；alert_recipients 每筆 type 限 participant（前端送 user_uid，必為本專案參與者，存成 user_id）或 party_role（role_id 必在 ssp_party_role menu）。錯誤碼 GRC_400141～GRC_400145（common/code/flow_control_error_code.py，GRC_TASK_RECUR_*）。

② 表 compliance.task_alert_notifications（主線 migration 2026-10-12-fr137-task-alert-notifications.sql、2026-10-13-fr137-task-alert-notifications-object.sql）：

唯一索引 uq_task_alert_notifications_object_recipient (object_type, COALESCE(scan_uid, object_uid), COALESCE(stage, ''), recipient_email)（D11、D15）；CHECK object_type IN ('scan_alert','support_end') AND (scan_uid IS NOT NULL OR object_uid IS NOT NULL)。RLS 比照 compliance.source_scans：ENABLE＋FORCE、一條 FOR ALL policy、GRANT cm_app 含 sequence。

③ 內頁登記（2026-10-12-fr137-alert-notifications-route.sql）：public.ui_routes 加 project-alert-notifications（/project/projects/:id/alert-notifications，pid 掛 project-auditor-overview，不上側欄），進入門檻 ALL grc.project.read。🔴 name 必須與 FE 路由 name 一字不差，沒登記就誰都進不去。

④ public.system_menus 頻率 seed（phase=seed，ON CONFLICT ("group", key) DO NOTHING；2026-10-12-fr137-task-frequency-menu.sql、2026-10-13-fr137-task-frequency-hourly.sql）：

i18n 標籤走 lang.task_frequency.<key>（FE options.json，zh-tw／en）。資源庫的 none 不進 menu：任務上「不重複」由週期開關表示。

6.2 到期排程

core/scheduler.py 的 task_recurrence_tick：cron 每 5 分鐘（minute="*/5"，UTC），max_instances=1, coalesce=True，寫法照既有 @_job_scoped＋app.app_context()＋system_context。邏輯本體在 TaskRecurrenceAppService.run_once()，支援期提醒（§6.8）接在同一支 tick 尾端。

每輪：

1. 撈到期（system_context）：next_due_at <= now() 的 USER 任務，每輪上限 500 筆。先套停止條件（D19）：沒有所屬專案、輪次 closed、專案 completed／archived 的，直接清空 next_due_at 並記 info log。其餘依租戶分組。
2. 逐租戶進 tenant_context，每筆各包一個 SAVEPOINT（單筆失敗不擋同批，失敗時 next_due_at 不動，下一輪再試）：
   • 算下次啟動：從本次的 next_due_at 依 recur_unit×recur_interval 往後推（不從 now() 算，排程延遲不會讓週期漂移）；推完仍 ≤ now() 就繼續推到未來，停擺多格也只跑一輪。月以上單位以「原點＋第 k 格」計算，31 號遇小月取月底，下個大月仍回到 31 號。
   • 條件式推進：UPDATE ... SET next_due_at = 新值, run_count = run_count + 1, last_run_at = now() WHERE id = :id AND next_due_at = :舊值；更新 0 列＝另一副本已推過，本副本跳過。
   • 重開：任務狀態是 COMPLETED 就改回 PROCESSING、清 end_time；所屬流程實例已完成一併改回 PROCESSING。
3. 開掃與提醒：開了自動執行的檢測工具任務先開掃（§6.4），再以 force_locale("zh_Hant_TW") 呼叫 notify_user_todo_job 寄信提醒執行人。開掃失敗不影響寄信，寄信失敗不影響已推進的任務。

next_due_at 在畫面以 Asia/Taipei 顯示、存 UTC（D10），可選到時分。

6.3 為什麼不複製任務

週期任務始終是同一筆：不複製任務、不在流程圖掛新節點、問卷不建新快照。使用者眼中一個週期任務就是一張卡，每一輪的成果是「多一筆執行紀錄、多一批證據」，都在同一筆任務的抽屜裡、依時間排序（證據最新在上）；第幾輪由 run_count 表示。複製的做法會長出使用者不認得的任務，還要另外處理複製鏈、唯一鍵、指派／部門／設備／檢測綁定的逐項複製，任一處沒對齊就靜默停掉週期。

6.4 掃描自動執行

TaskAutoExecuteService.start(job, tenant_id)，caller 已在交易內且已進 tenant_context：

1. 任務不是 PROCESSING 就不開掃、記 warning——還在排隊（上游未完成）的任務不硬轉進行中，那會跳過流程順序。已完成的任務已由 §6.2 先重開。
2. SAVEPOINT 內呼叫 detection_orchestration.start_execution(job_uid, "system", tenant_id)。檢測工具建 agent_tasks；SBOM 走伺服器端派工，沿用綁定上上次上傳的源碼包排背景掃描。
3. 執行紀錄的 created_user = "system"，抽屜據此標「自動執行」。結果與證據進同一筆任務。

為什麼不走平台啟動掛鉤：掛鉤挑任務時刻意排除 upload 模式（防首次無檔 400 迴圈），SBOM 正是 upload 模式，走掛鉤永遠派不出去；且掛鉤只派「沒有執行紀錄」的任務，週期任務第二輪起一定有紀錄。直呼派工入口兩個問題都沒有。

派工失敗（例如從未上傳過源碼包）只記 warning，執行人仍收到提醒信，可從抽屜手動執行；Dialog 在檢測工具任務沒有源碼包時提示「需先手動執行一次」。

6.5 門檻通知

套件端（jedi-source-scan 0.1.1）：

• plugin/contract.py 的 SourceScanAdapters 有選填 on_scan_completed: Optional[Callable[[str], None]]（參數＝scan_uid）。
• SbomScanJob 在掃描完成並轉回檢測結果之後呼叫；回呼失敗只記 logger.exception，不會把已完成的掃描改成失敗。
• plugin/scan_alert_diff.py 的 new_findings(previous_scan_uid, scan_uid) 給宿主用：previous_scan_uid 為空＝首掃，這次全部算新出現。

BE 端：core/plugins/source_scan.py 的 build_adapters 註冊 on_scan_completed，轉交 ScanAlertAppService.handle(scan_uid)（worker 行程、以建單者身分、RLS 照常）：

1. 由掃描找到任務；掃描不是 done、任務沒有 alert_recipients 或沒有所屬專案就結束。
2. 找上一次：同一筆任務底下、狀態 done、不是本次、完成時間早於本次的掃描中最近一筆；沒有＝首掃（D17）。
3. 取新出現：new_findings(上一次, 這一次) 濾 severity in ("CRITICAL", "HIGH")。為空就結束——不寄、不記。
4. 解析收件人（§6.6），去重後逐人：先搶紀錄列（唯一索引），搶到才寄；搶不到跳過。
5. 寄信：send_mail_notification(..., is_html=True)；回 True 記 sent，回 False 或丟例外記 failed、error 寫原因。不重試、不自動補寄。

不用 summary.delta：summary.delta 以掃描對象（target_uid）找上一次，任務發起的掃描不建掃描對象，target_uid 為空、delta 永遠是空的；照它判斷會每次都當首掃、整批老弱點每輪重寄，違反 D8。

信件：主旨與內文 msgid 在 config/translations/ zh_Hant_TW，排程與背景 job 沒有 request，以 force_locale("zh_Hant_TW") 取字串（D10）。內文列：專案、任務名、新出現 CRITICAL／HIGH 筆數、前五筆弱點編號與套件、掃描結果頁連結。使用者輸入的字串一律 html.escape。

6.6 收件人解析

app/task_alert/service/scan_alert_recipients.py：

排程與回呼裡沒有登入者，Party 走 domain service，不呼叫帶 require_participant 守門的 app service。同一信箱（不分大小寫）只寄一封。沒有任何可用信箱就記 warning 結束，不寫紀錄。

6.7 畫面

規劃頁（卡 ①）：

• AoTaskForm.vue「任務類型」下方一行引用 TaskRecurrenceSummary.vue：有週期時顯示 ↻ 每月 · 第 N 輪 · 下次啟動 2026-11-01 09:00 · 自動執行 · 高風險額外通知 2 個對象　[設定]，沒設時顯示「不重複　[＋ 設定週期]」。
• TaskRecurrenceDialog.vue：重複開關、頻率（讀 task_frequency）、間隔、下次啟動時間（可選到時分）；檢測工具任務多「自動執行」與「掃到新出現的 high（含）以上時，額外通知」（專案參與人員／系統責任角色，可多筆）；一般與問卷任務底部提示「到了啟動時間，這筆任務會重新開啟並通知指派人員」。沒有歷次列表。
• 「確定」只回寫表單 state，存檔走表單既有「儲存」；BE 在既有 update job 端點收 recurrence 物件。
• AoTaskSection.vue 頁籤列：有週期的任務名稱後加 ↻。
• 建專案時資源庫 frequency 不是 none 就寫 recur_unit，next_due_at 留空（只預選頻率），專案管理者在 Dialog 填下次啟動後才生效。

任務抽屜（卡 ②③）：

• JobRecurrenceRows.vue：檢測工具任務放在檢測設定區、與工具／掃描模式／完成模式同一個 grid；一般與問卷任務放在描述與指南之後。週期列：每小時 · 第 N 輪 · 下次啟動 …（N＝run_count＋1）；停掉後 已停止重複 · 第 N 輪。檢測工具任務另列自動執行（是／否）與高風險額外通知對象。
• 執行紀錄：created_user == "system" 的那筆標「自動執行」，提示「到了啟動時間系統自動開始，沿用上次上傳的源碼包」。
• 證據清單最新在上。

通知紀錄（卡 ④⑤）：

• ProjectAuditorOverview.vue 頁首「通知紀錄」一顆（所有參與者可見）。
• ProjectAlertNotificationsView.vue，路由 name project-alert-notifications，有返回鍵；上方三個計數（全部、已寄出、寄送失敗），有失敗時提示郵件伺服器未啟用、失敗的不會自動補寄；篩選：結果、期間。
• 表格欄：時間、掃描（任務名＋源碼包名＋「首次掃描」或「vs 上一次」；支援期列顯示「支援期提醒・<系統名> <版本>・剩 N 天」）、新出現 high 以上（CRITICAL n／HIGH n）、收件人（名稱＋信箱）、結果。
• 端點 POST /api/1.0/project/<project_uid>/alert-notifications（分頁，守門：專案參與者），回傳補任務名、掃描源碼包名、支援期列的系統名與版本。

6.8 支援期提醒

• 排程：task_recurrence_tick 尾端呼叫 SupportEndReminderService.run_once()。撈 support_end_date - today(Asia/Taipei) 等於 90、30、7 天的版本；tick 一天跑很多次，同一天同一階段靠唯一索引只寄一次。
• 收件人（infra/readmodel/detection/support_end_query.py）：版本 → 資訊系統 uid → oscal.ssp_inventory_items.props 的 ref-id＝該 uid → SSP → compliance.projects.living_ssp_id → 專案，濾框架 CRA_2024、未刪除、狀態不是 completed／archived → 該專案參與者中 role＝manager 的 email。沒掛任何 CRA 專案的版本不寄。
• 紀錄：寫入 task_alert_notifications，object_type='support_end'、object_uid＝版本 uid、stage＝d90／d30／d7、project_id＝收件人所屬專案；先搶列才寄，寫紀錄時逐專案切 tenant_context。
• 不做：通報三階段期限提醒（D16）。

另：2026-10-13-fn-purge-projects.sql（維運函式 compliance.purge_projects(ids, dry_run)，硬刪專案整棵資料樹，預設試算）在本 FR 期間加入，隨同一批進出貨基線。

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','secondaryColor':'#EEF2F3','secondaryTextColor':'#14201F','tertiaryColor':'#FBFCFC','tertiaryTextColor':'#14201F','lineColor':'#4A5A5C','textColor':'#14201F','mainBkg':'#E2F0F1','nodeBorder':'#0E7C86','nodeTextColor':'#14201F','edgeLabelBackground':'#FBFCFC','titleColor':'#14201F','clusterBkg':'#FBFCFC','clusterBorder':'#E4EAEB','actorBkg':'#E2F0F1','actorTextColor':'#14201F','actorBorder':'#0E7C86','actorLineColor':'#C7D1D2','signalColor':'#4A5A5C','signalTextColor':'#14201F','labelBoxBkgColor':'#EEF2F3','labelBoxBorderColor':'#C7D1D2','labelTextColor':'#14201F','loopTextColor':'#14201F','noteBkgColor':'#F6EBD5','noteTextColor':'#14201F','noteBorderColor':'#9C6B12','activationBkgColor':'#EEF2F3','activationBorderColor':'#C7D1D2','sequenceNumberColor':'#FFFFFF'}}}%%
flowchart LR
    C1[① 週期設定畫面] --> C2[② 到期處理<br/>＋提醒執行人]
    C2 --> C3[③ 掃描自動執行]
    C1 --> C4[④ 門檻通知＋紀錄]
    C2 --> C5[⑤ 支援期提醒]
    C4 --> C5

用一個有 SBOM 原始碼掃描任務的 CRA 專案（SSP 已填「漏洞通報聯絡人」Party 與信箱），郵件設定已啟用，批次跑完再一次回報：

1. 規劃頁開該任務 →「設定」→ 開重複、每月、間隔 1、下次啟動填明天 09:00、開自動執行、額外通知加「通報聯絡人」角色與一位參與者 → 確定、儲存；重整後摘要列（↻ 每月 · 第 1 輪 · 下次啟動 …）與 Dialog 都還在；頁籤有 ↻。
2. 開始執行任務後，手動執行一次掃描（首掃）→ 兩位收件人各收到一封門檻信；專案概覽頁頂端「通知紀錄」→ 兩列「首次掃描」。
3. 把該任務 next_due_at 改成過去時間 → 5 分鐘內：同一筆任務（沒有新任務出現）回到進行中、執行人收到提醒信、抽屜週期列變「第 2 輪」、下次啟動往後推一個月、執行紀錄多一筆「自動執行」且沿用上次源碼包。
4. 該輪用同一份源碼包掃完 → 不寄、通知紀錄頁沒有多列。
5. 抽屜上傳一份多帶一個新 HIGH 的源碼包、按重新執行 → 兩人各收一封、通知紀錄頁多兩列，顯示「vs 上一次」與 HIGH 1。
6. 同一份源碼包再重掃一次 → 不寄、不多列。
7. 證據與執行紀錄全在同一筆任務，最新在上。
8. 把該輪次結案後，再把 next_due_at 改成過去 → 5 分鐘後任務沒有被重開，下次啟動已清空、週期列顯示「已停止重複」（D19）。
9. 某資訊系統建一個 30 天後到期的版本、掛進該 CRA 專案 SSP 盤點 → 5 分鐘內專案 manager 收到一封、紀錄頁多一列「支援期提醒・剩 30 天」；之後的 tick 不重寄。
10. CMMC 專案的規劃頁、任務抽屜、專案概覽頁，除了任務表單多一行「不重複　[＋ 設定週期]」與頁首多一顆「通知紀錄」，其餘不變。