FR-047 全站已知坑處理 — 現況交接（2026-07-07）

FR-047 spec 手冊逐頁 code-read 期間，把每頁掃到的邊界情況 / 缺口 / 技術債記進各頁 §12「已知坑」（當時政策：只記錄不修）。全站累積後，散在 67 頁 + 8 個 _overview，難以總覽。終驗收尾時 user 要求彙整成一份總表，好做「總整理、分類分析、看怎麼解決」。

於是產出 docs/analysis/2026-07-07-spec-known-pits-inventory.md：508 條坑，每條標 群/頁#N id、頁功能、第一版 keyword 粗分類、可修性啟發式徽章。

本棒的任務＝把這 508 條「處理掉」——但「處理」不等於「全修」。§12 混了三種東西：

1. 可修的 bug / 缺口（安全守門缺失、真 bug、死碼）→ 要修，排優先級；
2. 刻意設計、只是提醒（full-replace 全量覆寫、best-effort 不阻塞、owner 只在 BE 保護、date-only 時區慣例）→ 多半 no-action（維持現狀，確認 spec 已講清楚）；
3. 文件 / schema 澄清 → 多數已在終驗修掉。

所以「怎麼解決」＝先跟 user 把每條定調（①/②/③），把①挑出來排序 + 規劃。這是跨模組決策，不是機械全補。

本棒在大圖的位置：坑清單處理的第 0 步——理解現況、跟 user 定分類與範圍、從 SEC 開始。

先做「授權守門（SEC）」（見下方 SEC 段），再依 user 意願接續其餘類別。每一類都先跟 user 討論再動手，不要自作主張把整份 508 條一次分完 / 開修。

分類表（清單檔內，primary 單標，sum=508）：

註：分類是 keyword 第一版粗分，會犯錯（primary 單標犧牲細節、204 條沒被 keyword 抓到）。真正定調待人工。可修徽章（🔧/📗/❓）也是啟發式，逐條要人看。

共同 root pattern：大量「寫入 / 狀態轉換」API 端點只有 @jwt_required()，沒有 BE 角色 / 能力守門，全靠 FE 隱藏入口或 canEdit 擋——任何已登入者知道 path + uid、繞過 FE 就能執行本該限 manager / auditor / admin 的操作。違反 CLAUDE.md「寫入 API 必須有角色權限檢查（manager / auditor）」「權限檢查在 service 層透過 domain service」。

• 抓 SEC 段：grep -nE "\SEC`" docs/analysis/2026-07-07-spec-known-pits-inventory.md`（每條下一行是內文）。
• 67 條裡三種性質、不能盲補：
  1. 真守門缺口（絕大多數）；
  2. 刻意不做角色檢查（例 evidence/cloud-integrations#4 trigger_init_project_folders docstring 明載「避免 is_admin 誤擋專案 manager」）；
  3. RLS / 跨租戶可見性類（user-log#4 api_logs 無 tenant_id、不受 RLS）。
• 最嚴重：system-admin/user-log#1——GET /log/api-logs/export 的 @jwt_required() 被註解掉（SEC-001），未登入者知道 URL 即可下載全部 api_logs，已有 regression test。這條幾乎確定要優先修。
• 很多端點在 jedi-auth 套件內（user/role/tenant）——動套件前依 CLAUDE.md「外部套件異動規範」先提醒 user 決策。

user 說：「先不用分析，你只要跟他說現況就好，我會跟他討論狀況。」 所以整份清單（含 SEC）：

• 不要自己把坑分桶定調、排優先級、寫解法計畫。
• 要：讀懂現況（本檔 + 坑清單 + CLAUDE.md 權限/DDD 規範），然後跟 user 討論怎麼切（先攻哪類？一次全補還是逐群？統一 decorator 還是逐 service？哪些判 no-action？）。

1. 本棒要處理的範圍是什麼？→（整份 508 條坑清單，不只 SEC；SEC 是 user 指定的第一個桶）
2. 「處理」是不是「全修」？→（不是。逐條定調 ①可修 / ②刻意設計只告知 / ③文件澄清；只有①要修）
3. 你被授權做到哪？→（讀現況 + 跟 user 討論分類與範圍；不是直接開修任何一條）
4. SEC 的共同 root pattern？角色檢查放哪層、什麼 error code？→（寫入端點僅 @jwt_required；service 層透過 domain service；GRC_403xxx）
5. 你在哪個 branch？→（fix/v1.8.0-bugs，不切）

• 不切 branch（已在 fix/v1.8.0-bugs）；push 永遠等 user 明示；commit 顯式 git add 檔名、禁 -am。
• 權限檢查放 service 層（透過 domain service 查 participant / role），route 層不碰 DB；error code 走 GRC_403xxx（如 GRC_403002 / GRC_NOT_MANAGER；平台層 GRC_NOT_PLATFORM_ADMIN / 403060）。
• 改 jedi-auth 等套件前先提醒 user 決策；dev 走 poetry path dependency、path 改動不 commit。
• 改 BE service code 必提醒 user 重啟（無 hot reload）；BE 行為異常先自己看 log/app.log。
• 不甩 caveat：坑內文標的「刻意不檢查 / RLS 類 / 只記錄不修 / 設計如此」要當真，別一律當缺口。
• spec = code 真相：修掉某條坑後，對應頁面 §12 該條的敘述要更新（走 writing-feature-specs skill，收尾時做、等 user 令）。

量產期已在 Notion「[GuidantAI] Issue 任務清單」開過幾條 SEC / bug case（notion-search 搜「守門 / 僅 JWT / 無角色 / 密碼政策 / TOTP / GITLAB / MAIL_SEND_FAILED」）。要 spin 成 case 前先搜、有相符就 update 別重開。座標見 docs/claude/notion-issue-tracker.md；作業人員 Claude 做的填「小弟」。

• 未 push：e7fc9230（坑清單）+ 本交接 commit 還在本地（origin/main 停在 f707bf1d）。要 push 到 main、還是留在 fix/v1.8.0-bugs 隨處理工作一起走，等 user 定。
• POC rsync 未完成：spec 手冊 html 站待部署到 jedi@192.168.50.189:/var/www/html/docs/specs/v1.8.0/，但該目錄 root:root、jedi 需 sudo 密碼——待 user 一次性 sudo chown -R jedi:jedi 後才能 rsync。
• is_template drift：背景 task task_c5e7ff0b（BE code cleanup，樣板 SSP 靠 template_ssp_id 非 is_template 欄），與本棒無關。

請接手 FR-047 全站已知坑處理。先讀 docs/features/FR-047-2607-feature-spec-handbook/handoff/2026-07-07-known-pits-remediation-handoff.md
全文 + 坑清單 docs/analysis/2026-07-07-spec-known-pits-inventory.md（尤其檔頭性質提醒 + 分類表）+ CLAUDE.md 權限/DDD 規範，
答完冷接自檢 5 題。branch 是 fix/v1.8.0-bugs、不要切。第一個處理的桶是「授權守門(SEC)」。
【重要】先讀現況、別自己分類或開修——分類方式與解法我會跟你討論後才定。讀完跟我對話。