稽核計畫直達入口：設計定案

🔴 這份是設計決策，不是現況。 內文停在 2026-10-17 定稿當時，實作改動不回頭改寫這裡。

狀態：設計定案，待開卡派工｜討論稿：discussion.md｜雛形：prototype/my-audit-plans.html

檔案路徑與行號以 2026-10-17 為準，查不到時以函式名重新定位。路徑慣例：BE 路徑相對 compliance-manager-be/；FE 路徑相對 compliance-manager-fe/；三個 repo 都在 feature/FR-139。

名詞：稽核次＝compliance.audit_round_passes 一筆，一輪裡每做一次稽核一筆、各自一份稽核計畫；稽核計畫（AP）＝FR-141 的計畫概要＋查核項目規劃；評估目標（AO）＝控制項底下的檢查項目，鍵是 part_id；填寫站＝流程範本「稽核計畫填寫」站，稽核次狀態 audit_planning，對應 job 的 template_job_id 是 UserTask_ap_authoring／UserTask_internal_ap_authoring／UserTask_external_ap_authoring；參與者＝compliance.project_participants。

整案一句話：左側選單多一項「稽核計畫」，點進去一張表格列跟我有關的每一份稽核計畫，點列直達 FR-141 的填寫頁。

依賴：1 → 2。卡 1 可先用 Swagger 驗完資料再開卡 2。

%%{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[卡 1 清單端點＋選單登記] --> C2[卡 2 清單頁＋徽章]
    C2 -.點列.-> P[FR-141 稽核計畫頁（不動）]

① 清單查詢（卡 1）

檔：infra/readmodel/audit/audit_plan_list_query.py（新）。照 auditor_dashboard_query.py：@property session、raw SQL、.mappings() 只在函式內讀、回 list[dict]＋total＋status_counts。

主查詢（一句 SQL，分頁與排序在 SQL 做）：

WITH mine AS (                                  -- 我在哪些專案、什麼角色
  SELECT project_id, array_agg(role) AS roles
    FROM compliance.project_participants
   WHERE user_id = :uid AND role IN ('auditor','manager','reviewer')
   GROUP BY project_id
), base AS (
  SELECT ps.id AS pass_id, ps.uid AS pass_uid, ps.pass_no, ps.audit_nature, ps.nature_seq,
         ps.status, ps.assessment_plan_id, ps.updated_at AS pass_updated_at,
         r.uid AS round_uid, r.round_no, (r.current_pass_id = ps.id) AS is_current,
         r.workflow_execution_uid,
         p.uid AS project_uid, p.name AS project_name, p.framework_name,   -- 框架欄依專案表實際欄位
         m.roles AS my_roles
    FROM compliance.audit_round_passes ps
    JOIN compliance.project_audit_rounds r ON r.id = ps.round_id
    JOIN compliance.projects p ON p.id = r.project_id AND p.deleted_at IS NULL
    JOIN mine m ON m.project_id = r.project_id
   WHERE ps.status = ANY(:visible_statuses)                 -- D2 白名單
)
SELECT b.*,
       -- 進度
       (SELECT count(*) FROM oscal.ap_assessment_activities a
         WHERE a.assessment_plan_id = b.assessment_plan_id
           AND EXISTS (SELECT 1 FROM jsonb_array_elements(a.steps) s, jsonb_array_elements(s->'props') pr
                        WHERE pr->>'name' = 'method' AND coalesce(pr->>'value','') <> '')) AS filled_ao,
       (SELECT count(*) FROM oscal.ap_reviewed_controls rc,
               jsonb_array_elements(rc.control_objective_selections) s,
               jsonb_array_elements(s->'include-objectives') o
         WHERE rc.assessment_plan_id = b.assessment_plan_id) AS total_ao,
       -- 稽核日期
       (SELECT t.timing->'within-date-range'->>'start' FROM oscal.ap_tasks t WHERE t.assessment_plan_id = b.assessment_plan_id LIMIT 1) AS audit_start,
       (SELECT t.timing->'within-date-range'->>'end'   FROM oscal.ap_tasks t WHERE t.assessment_plan_id = b.assessment_plan_id LIMIT 1) AS audit_end,
       -- 填寫期限：該輪 workflow 下、填寫站那張 job
       (SELECT j.due_at FROM compliance.job_executions j
          JOIN compliance.workflow_executions w ON w.id = j.workflow_execution_id
         WHERE w.uid = b.workflow_execution_uid
           AND j.template_job_id IN ('UserTask_ap_authoring','UserTask_internal_ap_authoring','UserTask_external_ap_authoring')
         ORDER BY j.id DESC LIMIT 1) AS plan_due
  FROM base b
 WHERE (:kw IS NULL OR b.project_name ILIKE :kw OR b.framework_name ILIKE :kw
        OR (:kw_nature IS NOT NULL AND b.audit_nature = :kw_nature)
        OR EXISTS (稽核人員名單 ILIKE :kw) OR EXISTS (manager nickname ILIKE :kw))
   AND (:status IS NULL OR b.status = :status)
 ORDER BY <排序> LIMIT :size OFFSET :offset;

稽核人員與專案經理名單用第二、三句批次查（WHERE assessment_plan_id = ANY(:ap_ids)、WHERE project_id = ANY(:project_ids) AND role='manager'）再在 Python 組回每列，不在主查詢 string_agg（名單要保留順序與「是不是我」）。

status_counts：同一個 base＋搜尋條件、不套 :status，GROUP BY status。

預設排序：CASE status WHEN 'audit_planning' THEN 0 … END, plan_due NULLS LAST, pass_updated_at DESC。可排欄：project（name）、pass（round_no, nature, nature_seq）、status、progress（filled_ao/total_ao）、due、audit（audit_start）、manager、updated。

搜尋詞對稽核性質：「外稽」「外部」→ external；「內稽」「內部」→ internal；在 app service 層翻成 :kw_nature。

② App service 與端點（卡 1）

• app/readmodel/service/audit_plan_list_service.py（新）：@transaction list_my_audit_plans(user_id, status, keyword, page, size, sort) 回 {"items":[…], "total", "status_counts"}；@transaction count_my_pending(user_id) 只數 audit_planning 且非 reviewer-only。專案經理 nickname 走 common/util/audit_nickname.py 的既有 enrich。
• DI：di_containers/flow_control/flow_control_containers.py 加 Factory（照 auditor_dashboard_service 那段）。
• Route：api/project/routes/audit_plan_list_route.py（新，主專案，不進套件）。POST /audit-plans/my/list、GET /audit-plans/my/count。守門 @jwt_required ＋ @require_license("audit") ＋ @capability_required("grc.audit.read")（與「我的稽核」同，從 common.authz 取）。
• Schema：api/project/serializers/audit_plan_list.py（新）。Request 繼承 RequestMetaSchema＋filters{status, keyword}；Response 繼承 EnvelopeSchema，data 是 item 陣列，meta 多一個 status_counts: {audit_planning, auditing, remediation, pending_reverify, closed}。

每列欄位：

③ 選單登記（卡 1）

scripts/sql/2026-10-xx-fr144-audit-plan-list-route.sql，主線 phase=seed，照 2026-10-15-fr139-version-history-routes.sql 四段：① ui_routes INSERT（WHERE NOT EXISTS name='audit-plan-list'；root 0、pid 42、name audit-plan-list、url /project/audit-plans、icon pi pi-list（primeicons 6.0.1 沒有 pi-list-check）、sort 25、is_menu true、description 「稽核計畫清單（登入者相關的每一份）」）；② route_capabilities 綁 grc.audit.read ALL；③ DO 區塊驗「存在、pid=42、恰一顆 ALL」；④ schema_migrations 登記。只套 DEV；寫完回報「出貨基線待重產」。

④ 清單頁（卡 2）

• 路由：/project/audit-plans，name audit-plan-list，component @/views/project/AuditPlanListView.vue，meta breadcrumb label audit-plan-list。
• api 常數：AUDIT_PLANS_MY_LIST: getUrl('/audit-plans/my/list')、AUDIT_PLANS_MY_COUNT: getUrl('/audit-plans/my/count')。
• i18n：src/config/locales/i18n/{zh-tw,en}/menu.json 加 audit-plan-list（「稽核計畫」／"Audit Plans"）與描述；新檔 audit-plan-list.json 放頁內字串（分段鈕、欄名、空狀態「當你被列為某份稽核計畫的稽核人員，或你管理的專案進到稽核計畫填寫站時，會出現在這裡」、按鈕 tooltip）。
• 頁面照雛形：SelectButton 或 Button 群當分段鈕（帶 meta.status_counts）、IconField 搜尋框（300ms debounce）、PrimeVue DataTable lazy 模式（:lazy="true" @page @sort 打後端），欄位與格式照雛形「一格一件事」；整列 @row-click 導頁；最右 icon-only Button 必配 v-tooltip.top；loading 配 :loading。
• 導頁：router.push({name:'project-ap-authoring-round', params:{id: project_uid, roundUid: round_uid}, query: is_current ? {} : {pass: pass_uid}})；needs_assign → {name:'project-planning-round', params:{id, roundUid}}。
• 徽章：AppMenuItem.vue 支援 item 可選 badgeCount；選單載入時與從本頁離開時打 count 端點一次；FR-143 改善計畫入口沿用同機制。

1. 選單：顧問帳號登入，左側「待辦任務」底下出現「稽核計畫 N」，N＝待填寫筆數；viewer-only 帳號看不到此項。
2. 清單內容：DEV 建一個專案，走到填寫站（內稽第 1 次），清單出現一列「第 1 輪 · 內稽第 1 次」待填寫 0%；在 FR-141 頁填三條 AO 的方法後回清單，百分比變為 3／總數；填計畫概要的稽核日期後，稽核日期欄兩行顯示。
3. 多稽核次：同專案走到內稽第 2 次，清單多一列「內稽第 2 次」，第 1 次那列變「稽核中」或「已結案」、只有檢視。
4. 外稽未指派：走到外稽填寫站且未指派稽核人員；PM 帳號看到該列「未指派」＋「去指派」跳專案規劃頁；只是 auditor 的帳號看不到該列。
5. 覆核者：reviewer 帳號看得到列、只有「檢視」、按下去 FR-141 頁唯讀。
6. 分段鈕與搜尋：切「已結案」筆數與列數一致；搜「外稽」只剩外部稽核；搜人名只剩該人參與的；清空回全部。
7. 排序與分頁：點「填寫期限」升、降、取消三態；每頁 20，第二頁有資料；排序切換後分頁回第 1 頁。
8. 點列導頁：目前稽核次的列導到 FR-141 頁可編輯；已結束那次的列導過去是唯讀且麵包屑顯示該次。
9. D2：規劃中的輪次不在清單。
10. 期限：填寫站 job 有 due_at 的列，待填寫時顯示「逾期 N 天」或「剩 N 天」；鎖定後不標。