↑ 需求首頁 ⌂ 需求中心

FR-142 交接現況（STATE）

這份是 living 檔：每棒就地 Edit，只描述「此刻」。歷史脈絡看同資料夾的 FR-142-LOG.md。

項目 值
最後更新 2026-10-17 傍晚（第四棒首腦交接：稽核作業頁改依專案分組＋頁籤三項＋分頁全站標準，CM-2850 已完成待複測；服務已全部重啟；下一棒＝FR-145 完成後的全面測試）
branch 三 repo 都在主工作樹 feature/FR-139；worktree 與本地分支 feature/FR-142 已刪（2026-10-16）
母案卡 CM-2818 https://app.notion.com/p/FR-142-AO-Excel-3fb346da4cd0819c8d6dcb40beb8185f
本棒角色 首腦（分析決策／開卡／派工／驗收），不自己實作。工作形態＝決策者在 DEV 手測 → 回報問題 → 首腦查根因開修正卡 → runner 修 → 首腦復核
Notion 回寫規範 docs/claude/notion-issue-tracker.md、派工卡骨架 docs/claude/notion-card-templates.md
接手前必讀 §0 讀序

🧭 原始需求 / WHY

  • 要解決的問題：現在的稽核結果頁（RoundAuditReviewView.vue）是「一個控制項一個判定」，稽核人員實際是逐條評估目標查核；判定值域、風險、佐證、報告都對不上 OSCAL AR 標準，匯出不合規（finding 的 status 塞了 product_state、risk 的 severity 塞錯位置、finding↔︎risk 連結表與 JSONB 不同步）。亞航要的稽核報告是「第 7 章稽核結果文字＋附件逐評估目標結果表」，現在產不出來。
  • 目標模型：判定以評估目標為單位（符合／不符合／不適用／未判定），控制項結論不存、由評估目標即時推（D5）；風險就地填在評估目標；佐證＝該評估目標對到的任務佐證一張平清單，預設全採用；稽核報告頁籤只寫第 7 章，預覽才組完整報告；Excel 沿用 FR-141 四頁往後加 K～Q 欄；結案整份鎖定、佐證凍結；資料全照 OSCAL v1.2.2 落點。十二項決策 D1～D12 全部在 design.md 決策定案表，不重開。
  • 需求演變：雛形六輪（風險總覽頁籤拿掉、逐項填寫按鈕拿掉、報告預覽併進 overlay、佐證清單不分任務且任務討論不採用）。工作環境中途改兩次：主工作樹 → worktree → 專用庫（見 §2）。
  • 本棒位置：實作八棒全部首腦復核過、三 repo 已推上 origin/feature/FR-139（2026-10-17）。棒 8 是 10-17 新加的「稽核作業」頁（原「我的稽核」，改表格＋改名）。下一棒＝決策者親自在 DEV 手測八棒，首腦接手「測試→修正」循環。

§0 接手讀序

0.1 🔒 先懂需求 gate

  1. 本檔 🧭 WHY
  2. docs/features/FR-142-2610-audit-result-ao-worksheet-and-report/design.md：分工概述、決策 D1～D12、「現況接入點」、「拆分表」四節全讀
  3. 八張子卡各自的「✅ 首腦復核」段（python scripts/notion_case.py get CM-28xx，卡號見 §1 表；CM-2836 卡尾有三段規格修正＋改名＋配色，以最後為準）——每段末行是該棒的複測步驟與首腦沒實測的打折處，決策者回報的 bug 先對這裡看是不是已知打折

0.2 現況與待辦

  1. 本檔 §1、§3、§4
  2. FR-142-LOG.md 最後三個 block（第三棒：決策者裁示、稽核作業頁、配色）

0.3 需要細節才開

  • 雛形 prototype/index.html、prototype/my-audits.html（稽核作業頁）——決策者說「畫面跟雛形不一樣」時對照用。開法：BE 根目錄 python3 -m http.server 8765，開 http://localhost:8765/docs/features/FR-142-2610-audit-result-ao-worksheet-and-report/prototype/<檔>
  • 稽核作業頁座標：FE src/views/project/MyAuditsView.vue；BE infra/readmodel/audit/auditor_dashboard_query.py、app/readmodel/service/auditor_dashboard_{service,summary,people,risk}.py；套件 jedi-compliance-audit api/serializers/auditor_dashboard.py
  • 新頁程式座標：FE src/views/project/RoundAuditResultView.vue＋src/components/grc/ar-result/＋src/composables/useAr*.js；BE app/flow_control/service/ar_objective_app_service.py（讀寫）、ar_objective_writer.py（存一條）、ar_close_service.py（結案）、ar_workbook_*（Excel）、ar_report_export_service.py＋ar_docx_generator.py（報告）；DI di_containers/ar_result/；套件 jedi-oscal-v2 app/service/ar/ar_objective_observation_service.py／ar_attestation_service.py、jedi-compliance-audit app/service/ar_import/aggregation.py（D5 唯一規則）／ar_result_scope.py／pass_scope_rule.py

0.4 ✅ 冷接自檢

  1. 為什麼判定要從控制項層改到評估目標層？控制項結論去哪了？
  2. 「未判定」在 OSCAL 怎麼存？（答：不建 finding）「不適用」呢？
  3. 決策者說「舊的稽核次打開變唯讀、不能改」——這是 bug 嗎？（答：D4，舊稽核次控制項層判定只能看；新頁 legacy: true）
  4. 決策者說「結案時系統說還有未判定但我明明都判了」——先查哪裡？（答：reviewed_controls.control-objective-selections 的 AO 清單 vs assessment_findings.target_id，結案守門自己算差集，不讀 stats["pending"]）
  5. 修正卡要開在哪個 branch、用哪個庫？（答：主工作樹 feature/FR-139、DEV；worktree 與專用庫都沒了。同 repo 兩張修正卡平行派要各開 worktree 或序列派，見 §4 第 5 點）

§1 當前狀態（2026-10-17 傍晚盤點）

項目 值
BE feature/FR-139 HEAD 為本交接 commit，領先 origin 約 70 個 commit 未 push（本案第四棒的文件 commit＋其他 session 的 FR-143／144／145 commit 混在一起）。未 commit 的 pyproject.toml／poetry.lock、FR-133／144／145 文件都不是本案的
FE feature/FR-139 領先 origin 約 29 個 commit 未 push。本案第四棒六個：72708440（棒 9 分組）、88e5f5d5（麵包屑 from）、60baaf42（空表藏鈕）、73369176（頁籤三項）、081ee5b5（文字已完成）、2c79a437（分頁改表格內建）；其餘是 FR-143／144／145
套件 feature/FR-139 本案沒再動；領先 origin 1 個（FR-143 的）。未發版、未推 Nexus（主工作樹 venv 以 editable 吃這棵樹）
test repo feature/FR-139，本案未動
DEV guidant_ai_dev 013＋seed 已套並登記（2026-10-16）。可見稽核次只有 3 筆（2 待覆核＋1 覆核輪矯正中），沒有「稽核中」的新稽核次——測新流程要先從 FR-140 開一個
正式服務 2026-10-17 16:37 首腦全部重啟：BE API 8000、BE worker（RUN_MODE=worker）、FE vite 5180，都在主工作樹、系統 Python。BE 跑到當時 HEAD 30650bdd0。之後若 BE 有新 commit 要再重啟
測試基線 BE 守衛＋FR-142 測試 124 passed（10-17）；test_migration_stamp_policy.py 7 passed

Notion 卡（子卡全部停在「修正待驗證」等決策者複測；母卡 CM-2818 Not started，等收尾令才收 Done）：

卡 做什麼 狀態
CM-2819 討論稿／雛形／Excel 範例 Done
CM-2823 1a 套件 AR 改 OSCAL 形狀（套件 acdb197b、BE 38f90c51a、migration 013） 修正待驗證，首腦復核過，手測併 1b
CM-2824 1b 評估目標層判定範圍、佐證兩筆、第 7 章存取、aggregate_verdict／summarize 一支（套件 4a310d97） 修正待驗證，首腦復核過（突變＋專用庫核 7 條 AO）；發現 finalize_assessment 的 pending 守門對新稽核次失效 → 已補進 CM-2825
CM-2825 2 BE API（51101df83：新容器 di_containers/ar_result/、七個端點、結案走 stage advance） 修正待驗證，首腦復核過（真資料一條龍含凍結 4 筆、POA&M）
CM-2827 4 Excel K～Q、檔名比對、預覽（BE d00fecb1f、FE c597bbe4） 修正待驗證，首腦復核過（匯出實檔＋匯入確認寫入真資料）
CM-2829 6 pass_scope_rule.py 改評估目標層、seed system_menus（套件 7c9840a6、BE e243300f1） 修正待驗證，首腦復核過；縮範圍端到端併棒 2
CM-2826 3 FE 新頁（FE a7a64fe3：新頁＋17 元件＋6 composable；退役三支超標舊檔） 修正待驗證，首腦復核過（瀏覽器深淺色實開；匯入／結案／現場上傳 FE 操作留決策者）
CM-2828 5 報告 docx／pdf／zip（BE 0145d2f25、ac17ad2d3；接棒 4 export 入口、report_head() 抽共用） 修正待驗證，首腦復核過（docx 結構／pdf 方向／AP 匯出回歸；Word 實開留決策者）
CM-2833 7 「我的稽核」清單與首頁小卡改讀評估目標層（BE aa2ba2214、FE 1c86875e、套件 serializer bd73429b） 修正待驗證，首腦復核過（實打 my/list 舊稽核次相容；新稽核次路徑待複測）
CM-2836 8 「我的稽核」頁改成表格並改名「稽核作業」：一格一值（頂多一行小字），加稽核人員（稽核計畫名單）、稽核次、待覆核、風險高中低三欄；搜尋／排序／分頁。雛形 prototype/my-audits.html，卡尾三段規格修正以最後為準（BE eee4ac782、FE a4a86f0a、套件 cfe0ce4a） 修正待驗證，首腦復核過（實打端點＋headless 實開中英文、搜尋、排序；稽核中的稽核次 DEV 沒有，截止日小字未實見）
CM-2850 9 「稽核作業」頁改依專案分組展開：一專案一列顯示「目前這一次」，點開子列是每一次稽核；單次專案不展開；排序分頁以專案為單位。只改 FE。雛形 prototype/my-audits-grouped.html（決策者 2026-10-17 裁直接取代平列版） 修正待驗證，首腦復核過（FE 72708440＋麵包屑補 from 88e5f5d5；真資料實開；預設展開／分頁只在假資料驗過）。空表藏鈕（FE 60baaf42）；頁籤改「待處理／已完成／全部」、預設待處理（FE 73369176＋文字 081ee5b5，決策者裁）；分頁改用表格內建、與全站清單頁同一套（FE 2c79a437）。首腦前次說「子列開到該輪目前那次」是誤判（已更正）：子列一筆＝一輪、各自 round_uid，點哪輪開哪輪沒問題。真正的設計邊界是清單一輪一列，同一輪多次稽核只顯示目前那次、舊的進結果頁切換器看；要不要改一次一列待裁

1b 新增的套件檔：jedi-oscal-v2 app/service/ar/ar_objective_observation_service.py、ar_attestation_service.py；jedi-compliance-audit app/service/ar_result_scope.py、ar_import/aggregation.py（aggregate_verdict(states, has_risk)、control_verdicts、summarize）。

§2 已定裁示（不要重新討論）

  • D1～D12 全部定案（2026-10-16，design.md 決策表）。
  • 實作期用 worktree＋專用庫的裁示已結束（2026-10-16 合併後 worktree／專用庫都刪）；修正階段一律主工作樹 feature/FR-139＋DEV。
  • 首腦自己寫討論稿／雛形／design／開卡／探脈，不開 subagent；只有實作卡開 case 給新 session（決策者 2026-10-16，已入 CLAUDE.md）。
  • UI 絕對禁令：任何卡片不准左側粗色邊框（決策者 2026-10-16，已入 CLAUDE.md 與設計系統 skill）。
  • 舊稽核次不遷移、POA&M 改版另開 FR、任務討論不當佐證。

§3 下一步

🔴 下一個動作：FR-145 完成後決策者開始全面測試。 接手首腦讀完盤點完即停，等決策者丟問題。CM-2850（稽核作業頁）已做完、首腦復核過、待決策者複測。

稽核作業頁此刻長相（決策者 2026-10-17 逐項裁過，不重開）：一專案一列、點開子列是每一次稽核；頁籤「待處理（預設，＝稽核中）／已完成（矯正中、待覆核、已結案）／全部」；分頁用表格內建、與待辦任務頁同一套（每頁 10／25／50，以專案計不算子列）；點進結果頁帶 ?from=audit-manage，麵包屑回稽核作業。

全面測試時順手看：稽核作業頁分頁是表格內建，改善計畫／稽核計畫／結案報告三頁是 FR-145 抽的共用外掛元件 GroupedListPaginator，兩種寫法；文字已對齊，並排看長相是否一致，不一致回報給 FR-145 首腦（決策者裁：別人的頁不動）。

決策者會怎麼測（各卡「✅ 首腦復核」段末行＋棒 3 卡「手測清單」）：從 FR-140 流程開一個新內稽稽核次推到「稽核」站 → 新頁左樹／評估目標頁／判定／風險／佐證 → Excel 匯出改格匯入 → 第 7 章＋帶入不符合＋預覽 → 結案（被擋→補完→成功→POA&M）→ 匯出 Word／PDF／ZIP → 左側選單「稽核作業」看清單數字。首腦沒在瀏覽器實測過的：匯入 Excel 預覽畫面、結案那一下、現場上傳（棒 3）；稽核作業頁的截止日小字、分頁、本人加粗（棒 8，DEV 無稽核中資料）。這幾個最可能出問題。

收到問題後的固定動作：

  1. 先對 §4 與各卡「首腦復核」段的打折處，判「已知非本案／已知打折／新 bug」。
  2. 新 bug：首腦自己查根因（log log/app.log、DEV 唯讀查詢、開檔），不開 subagent；查到後開修正卡（docs/claude/notion-card-templates.md 修正卡骨架，母卡 CM-2818 子卡，卡號接 CM-2833 之後），印派工 prompt 等令。小到一行的改法首腦可直接修並 commit（CLAUDE.md 碎片 case 不寫新測試，跑守衛即可），但要在卡上留紀錄。
  3. runner 修完回寫 → 首腦復核（實打端點／開瀏覽器）→ 回貼任務總表。
  4. 修正卡同 repo 平行要各開 worktree 或序列派（§4 第 5 點）。

全部複測過後才做的（等令）：收尾（writing-feature-specs 更新 SPEC、使用手冊——docs/user-manual/lifecycle-and-use-cases.md 的「我的稽核任務」三處改「稽核作業」、母卡 Done、analysis）、e2e 文件（test repo site-regression/docs/test-cases/audit-execution/my-audits.md／audit-risk.md 描述舊頁；site-regression 自 10-09 起不是發版 gate，不必跑）、套件發版（jedi-oscal-v2 有 migration 013、jedi-compliance-audit 有 serializer 改動，進版時要 bump）。

出貨基線（已核，2026-10-17）：013 是套件 migration（build 期 flatten_pkg_migrations.sh 自動攤平）、seed 是 phase=seed，都不需重產 02-schema.sql。seed 原本漏登主線 scripts/sql/manifest.tsv，已補（BE 729ade180，test_migration_stamp_policy.py 7 passed）。

⚠️ 本節是建議清單，不是執行授權。接手方讀完盤點完即停，等決策者發令。

§4 待辦與風險

  • FR-145 帶上（2026-10-17 留言）：重寫 audit-execution/my-audits.md（稽核作業頁）時一併寫進 FR-145.1 的「稽核報告」欄——已結案或矯正中的列有「下載報告」下拉（Word／PDF／Excel，Excel 依有無已送出改善計畫給改善計畫工作表或稽核結果工作表），稽核中印「結案後開放」；端點 GET /audit-round/<round_uid>/pass/<pass_uid>/report?format=docx|pdf|xlsx（412 GRC_412068 未結案、400 GRC_400174 格式）、POST /audit-round/report-status；Word 附件後多一節「改善計畫」三態。見 FR-145 design.md D1／D2。
  1. 【決策者 2026-10-17 裁：不處理，之後會清一次資料庫】 套件 finalize_assessment 第 808 行的 stats["pending"] 守門對新稽核次永遠 0——棒 2 的 ar_close_service 自己算未判定（AO 清單減已有 finding），結案守門實打驗過會擋；但舊端點 POST …/close-round（AuditRoundCloseRoute，走套件 finalize_assessment）若有人直接打，新稽核次會不經守門就結案。FE 已改走新 …/ar/close，舊端點留給舊稽核次。
  2. 主工作樹 pyproject.toml 有別人的套件 path 改動（三支 jedi-* 指到主套件樹的 editable），是其他 session 的開發期設定，不是本案的，別 add。
  3. 登入 DEV 用 test repo .env.e2e 的 TEST_ADMIN_USERNAME／TEST_PASSWORD；memory reference_dev_login.md 的明文密碼已過期、本棒改成只指路。
  4. 【已解，2026-10-17 核】 套件 jedi-task-platform 58836164（FR-140.14）已補 ProjectParticipantEntity.audit_scope，8000 重啟後 log 無此錯。原記錄：FR-140 推進站的進站通知噴 AttributeError（首腦復核棒 2 時實踩，非本案）：app/flow_engine/service/stage_entered_recipients.py:34 讀 ProjectParticipantEntity.audit_scope，實體沒有這個屬性；只在通知層被 try 住，推進本身成功。
  5. 同一 BE worktree 平行兩棒會撞 git index（棒 2／4 實踩：棒 4 git add 覆蓋棒 2 已 stage 的 fixtures_frozen_error_codes.py，夾進 13 行重複鍵，棒 4 在下一個 commit 清掉）。之後同 repo 的平行棒要各開 worktree，或序列派。 棒 3（FE）與棒 5（BE）不同 repo，可平行。
  6. DEV 既有稽核次全部是舊版（控制項層）：新頁打開顯示唯讀橫幅、我的稽核清單走 scope_level=control 相容路徑，是 D4 預期不是 bug。要測新流程必須從 FR-140 開新稽核次。
  7. FR-140 推進站的前置條件 round_prep_tasks_done 目前一律放行（TODO 註明），planning_readiness 只是 warning；首腦復核時用 force: true 推進。決策者從畫面推進若被擋，是 FR-140 的事不是本案。
  8. 報告標題「第 N 次」來自 audit_round_passes.nature_seq，不是 round_no：同一輪可有多個 pass，看到「第 2 次」但輪次是第 1 輪不是 bug（本棒實踩）。
  9. 【已修，2026-10-17，FE bcaaa4f5】 淺色主題橘色太接近紅色：--color-orange 改 amber-600 #d97706，新增 --color-yellow／--color-blue 兩個 token（雙主題）；全站用橘色的地方淺色下一起變亮。決策者令首腦直接調。
  10. 稽核作業頁「本人加粗」用暱稱比對：計畫名單的 party 沒綁帳號、登入資訊沒有數字 user id。同名會誤判；決策者若覺得要準，需在登入資訊帶 user id（另開卡）。

§5 Pre-flight（必跑，唯讀）

cd ~/Projects/Billows/Audit-Manager/compliance-manager-be && git branch --show-current && git status --short && git log --oneline -3 && git rev-list --left-right --count @{u}...HEAD   # 交接時 0 0
cd ~/Projects/Billows/Audit-Manager/compliance-manager-fe && git branch --show-current && git status --short && git log --oneline -2
cd ~/Projects/Jedicogy/module/jedi-python-package && git branch --show-current && git status --short && git log --oneline -2
git -C ~/Projects/Billows/Audit-Manager/compliance-manager-be worktree list   # 應只有主工作樹一列
lsof -nP -iTCP:8000 -sTCP:LISTEN; lsof -nP -iTCP:5180 -sTCP:LISTEN            # 正式前後端
cd ~/Projects/Billows/Audit-Manager/compliance-manager-be && grep -o 'release=[^)]*' log/app.log | tail -1   # 8000 跑的 commit
psql -h localhost -p 5432 -U cmmgr -d guidant_ai_dev -c "SELECT filename FROM public.schema_migrations WHERE filename LIKE '%013-ar%' OR filename LIKE '%fr142%'"   # 應兩列；密碼看 .env DB_PASSWORD
psql -h localhost -p 5432 -U cmmgr -d guidant_ai_dev -c "SELECT target_status_state, count(*) FROM oscal.assessment_findings GROUP BY 1"   # 不應有 pending
for c in CM-2823 CM-2824 CM-2825 CM-2826 CM-2827 CM-2828 CM-2829 CM-2833 CM-2836; do python scripts/notion_case.py get $c | grep -m1 '^狀態'; done   # 都應是修正待驗證（決策者測完會改）

§6 環境座標

項目 值
BE／FE／套件 主工作樹 feature/FR-139（BE 8000、FE 5180），worktree 已刪
DEV guidant_ai_dev（localhost:5432），013＋seed 已套（2026-10-16），8000 已重啟到合併後程式
專用庫 guidant_ai_fr142 已 DROP（2026-10-16，決策者令）；複測一律在 DEV 從 FR-140 流程開新稽核次
套件測試 主工作樹 .env 即可（conftest 預設讀主工作樹 .env，JEDI_TEST_ENV 不必再帶）

§7 行為規範提醒

  • 不切 branch、push 等決策者令、顯式 git add <檔>；主工作樹未 commit 的 pyproject.toml／FR-133 SUMMARY 不是本案的。
  • 🔴 絕不在決策者桌面開視窗：不用 open -a／open <url>、不用 chrome-devtools／Playwright／claude-in-chrome MCP 開頁。交雛形只給網址讓決策者自己點。
  • 要在真頁面驗、又不讓密碼進對話：用 test repo node_modules/playwright 寫腳本（預設 headless，不傳 headless: false），從 .env.e2e 讀帳密登入 5180、截圖到 scratchpad 自己看。登入頁是 /login，登入後要等 .layout-menu 出現再走 SPA 內導航。
  • 改 BE service 後必 kill -9 重啟 8000 再讓決策者看（共用 8000，runner 常說「沒重啟」）。
  • 決策者回報的 bug 先 tail log/app.log 找 Traceback，再問細節。
  • 派工＝先有 Notion 卡（CM 號＋URL 進 prompt）；prompt 薄、細節進卡；runner 做完 commit＋回寫不等令。
  • 首腦不開 subagent 寫文件；突變測試後清 __pycache__。
  • 新 error code 先 grep 主工作樹 common/code/ 最大號。

§8 不在本期 scope

POA&M 改版、CRA 系統資料當證據、舊稽核次遷移、assessment-log、證據分類器。

§9 給 fresh session 的短 prompt

接手 FR-142（稽核結果逐評估目標判定重做）首腦，進入「決策者測試→修正」階段。先讀 docs/features/FR-142-2610-audit-result-ao-worksheet-and-report/handoff/FR-142-STATE.md 照 §0 讀序讀完、答 §0.4 自檢，跑 §5 pre-flight（唯讀）。
讀取與盤點完成後不做任何事——不派工、不跑測試、不改檔，回報「自檢答案／現況盤點／待辦已就緒」後等我丟測試問題再開始作業。