FR-047 全站已知坑處理 — 交接（剩餘桶，2026-07-08）

FR-047 spec 手冊全站 67 頁的 §12「邊界情況與已知坑」被彙整成 508 條清單。關鍵認知：這 508 條不是 508 個待辦——§12 是寫給工程師的「邊界情況告知」，混了三種東西：

1. 可修 bug / 缺口（安全守門、真 bug、死碼）
2. 刻意設計、只是提醒（full-replace、best-effort、date-only 時區慣例）—— 知道就好，不是要改
3. 文件/schema 澄清

arc 的目標＝逐桶把「①可修」挑出來修，②③ 一律 no-action（維持現狀）。 前 5 桶實證：真正動手的遠少於總數（SCHEMA 60 條真動手 5 個 DDL、其他 204 條 ~25、ECODE 25 條真缺陷 7 條）。下一棒的三桶同理——大部分會是 no-action，別把每條當 bug 修。

1. 🔒 本文件全讀（懂 WHY + 現況 + SOP）
2. 🔒 docs/analysis/2026-07-07-known-pits-remediation-tracker.md 全讀（唯一進度真相；看已收桶的定調模式、剩桶的預收歸位條目）
3. 2026-07-08-known-pits-remediation-SUMMARY.md（已完成彙整、loose ends、部署狀態）
4. CLAUDE.md 權限/DDD/DB transaction/error code/jedi 套件異動/DROP 前四查規範
5. 母清單 2026-07-07-spec-known-pits-inventory.md（要抽桶時查原文，只讀）

冷接自檢（答不出回去讀，別碰 code）：

1. 508 條的核心認知是什麼？→（§12 是邊界告知非待辦，~85% no-action，只挑①可修）
2. 進度真相在哪一份文件？可以另開清單嗎？→（唯一 tracker，絕不另開第二份）
3. 接一個桶的 SOP 五步是什麼？→（見 §3）
4. 動手前對每條坑要先做什麼？→（live 驗證真實碼/DB，spec 文字常過時誤報）
5. 你在哪個 branch？發版/merge 能自己做嗎？→（fix/v1.8.0-bugs，發版/push/merge 全等 user 明示）

已收的 5 桶不要重做。 三桶各有「從其他桶歸位進來」的預收條目，寫在 tracker 各桶段落 + §其他二次歸類「可行動清單」——抽桶時把該桶的歸位條目一起納入。

• 絕不建第二份追蹤表：上棒出現兩份 checklist（docs/features/FR-047.../known-pits-remediation-tracker.md vs docs/analysis/...）造成混亂，已刪前者。只用 docs/analysis/ 那份。
• 動手/升級前一律 live 驗證：spec 文字常過時。本 arc 抓到多條誤報——system_owner comment 早修好、info-system#4 route 早回 404、tenant-manage#5 marshal apply=False 不影響 response。先 grep 真碼 / 查 DB 再定調。
• 改套件 ≠ 授權發版：發版（bump + 推 Nexus）不可逆，一律等 user 明示。本 arc 執行 session 曾自行 bump 超前。
• 不甩 caveat：坑內文標「刻意不檢查 / 設計如此 / RLS 類」要當真——盲改會打爆（FR-048 那批 2 次盲加 auth 打爆下載的前科）。
• 告知類收攏成族群索引 no-action，別逐條；但 spec 自斷言「無害」的條目快速 confirm 一次再放生。

1. 抽桶：跑下方腳本把該桶條目 + 內文全撈出來。
2. 逐條讀內文分性質：真缺陷 / 設計告知 no-action / 同 root pattern 重複 / 屬別桶。每條可行動的先 live 驗證（grep 真碼、查 DB）。
3. 同 root pattern 合併談：例如 REPLACE「送 [] 清空」跨多頁、STATE「SSP 寫入無 phase guard ×N 頁」、UX「date-only 時區 ×10+」——合併後塌縮成幾個決策點。
4. 寫進 tracker（唯一那份）：開 §UX / §STATE / §REPLACE 段，逐族定調（比照已收桶的寫法）。
5. 跟 user 討論定調 → 才動手。絕不自己開修——本 arc 全程「先定調、user 拍板、才派工」。

抽桶腳本（把 UX 換成 STATE / REPLACE）：

cd ~/Projects/Billows/Audit-Manager/compliance-manager-be
python3 - <<'PY'
import re
lines=open("docs/analysis/2026-07-07-spec-known-pits-inventory.md",encoding="utf-8").read().split("\n")
n=0
for i,l in enumerate(lines):
    m=re.match(r'- \*\*\[([^\]]+)\]\*\*\s+(\S+)\s+(.*)$', l)
    if m and m.group(3).strip().startswith("`UX`"):
        n+=1
        b=next((lines[j].strip() for j in range(i+1,len(lines)) if lines[j].strip()),"")
        print(f'{n:2d}. [{m.group(1)}] {re.sub(r"[*`]","",b)[:100]}')
print(f"\nTOTAL = {n}")
PY

三桶各自的預收方向（詳細內文抽桶後才有；這裡只給定位）：

• UX (47)：date-only 時區 ×多頁（同 root）、i18n 漏譯、toast、分頁、即時刷新。歸入：user-profile#1（TOTP 未驗證就啟用會自鎖）、device#5/department#5（status 欄無 UI）。跨 FE repo（~/Projects/Billows/Audit-Manager/compliance-manager-fe/）。
• STATE (33)：前置檢查不對稱、可繞過、凍結時機。大宗＝「SSP 寫入無 phase guard ×6 頁」（先對 FR-048 端點授權矩陣查哪些已被收，可能塌縮剩幾條）。歸入：import-docx#3（phase guard）、問卷填答狀態機 2ffec。
• REPLACE (33)：full-replace 送 [] 清空、非單一交易、FK 級聯、硬/軟刪。歸入：user-import#2（批次非單一交易）、role-manage#2/user-form#3（全量取代漏帶=刪授權）、department-manage#7（刪部門 FK 未查證）、issue-integrate-config#1（DEAD C 族改桶）。

在 tracker §各段有記，摘要如下——這些是 arc 尾巴，不急，user 排：

• otp-resend type/mfa_type 未修：api/auth/routes/otp_route.py:148 讀 kwargs.get("mfa_type") 但 serializer MfaResendRequest 宣告 type → TOTP 使用者靜默走 email。標了「→BUG/ECODE」但沒派工。Notion case 61db 維持 Not started。
• AUTH_401009 文件漂移：ECODE#4 改碼後舊碼殘在 8 檔（docs/reference/error_code.json、docs/system-design/scripts/data/_all_error_codes.json、specs 的 auth/forget-password + system-admin/user-profile 的 md/html/dot）→ 應 AUTH_401009→AUTH_400003。純文件 spec-sync。
• spec §12 更正：tenant-manage#5 誤報、storage-config#5 無害澄清（走 writing-feature-specs skill）。
• DEAD B 族 topt_secret drop：DEV 查乾淨（0 資料零引用），待 STG/POC 確認 + user 拍板（跟 POC 一起等）。
• locale 對稱輕量驗證：可翻譯欄位 update 路徑是否都有傳 locale（SCHEMA ⑤ 列的待辦，非 bump）。
• FR-048 e2e ×2（test repo）：QR 顯示 / 框架下載前科件 + 負向案。

• 進度/定調：docs/analysis/2026-07-07-known-pits-remediation-tracker.md（唯一）
• 508 母清單：docs/analysis/2026-07-07-spec-known-pits-inventory.md（只讀）
• 收口彙整：docs/features/FR-047-2607-feature-spec-handbook/handoff/2026-07-08-known-pits-remediation-SUMMARY.md
• FR-048 端點授權矩陣（STATE 桶查 phase guard 用）：docs/features/FR-048-2607-unified-auth-guard/endpoint-authz-matrix.md
• FE repo（UX 桶）：~/Projects/Billows/Audit-Manager/compliance-manager-fe/（改前讀其 CLAUDE.md）
• jedi 套件（若某坑在套件層）：~/Projects/Jedicogy/module/jedi-python-package/

已收的 5 桶 fix 都已 landed + 部分手測 + jedi 套件已發版（Nexus pin）。不要回頭追已修的坑。若懷疑某條狀態，查 tracker 那一列（不是重新調查）。已修清單見 SUMMARY §3。

• 不切 branch（已在 fix/v1.8.0-bugs）；push / 發版 / merge to main / 主專案進版 全等 user 明示，不自動做。commit 顯式 git add 檔名、禁 -am。
• 絕不建第二份追蹤表（見 §2）。定調一律寫 docs/analysis/ 那份。
• 每條可行動坑先 live 驗證再定調（spec 常過時誤報）。
• 權限檢查放 service 層（透過 domain service）；動 jedi-* 套件前 path dep 開發、發版等明示。
• 改 BE service code 提醒 user 重啟（無 hot reload）；BE 異常先自己看 log/app.log。
• 不甩坑內 caveat（刻意不檢查/設計如此/RLS 類要當真）。
• 收尾（spec/SUMMARY/Notion/memory）等 user 明確下令，plan approve ≠ 自動收尾。
• 跨 FE repo 先讀 FE CLAUDE.md；不晶晶體。

• 桶定調完 → 寫 tracker 對應 §段（不另開檔）→ 跟 user 討論。
• fix 完 → 給 user 一句話 status + 手測 checklist，停，等 user 下令才做 SUMMARY / Notion / spec / memory。
• 走 closing-and-handoff skill 的收尾 SOP。

• 不做主專案進版 / merge to main——arc 沒完（還 3 桶），branch 繼續累積，等 user 決定。
• 不重推發版 / 不 push——已發版/已 push 的別動；新 commit 的 push 等 user 明示。
• 不套 POC migration——user 明確按住（先等等）。
• 不重做已收 5 桶。
• 零星 loose ends（§4）非本期主線——user 點才做。

• 主 repo compliance-manager-be：已 push 到 origin/fix/v1.8.0-bugs（領先 origin/main ~93，待未來 merge）。含 FR-048 全批 + BUG 池 + SCHEMA(DDL+升級) + ECODE(#1/#2) + DEAD + 追蹤表/SUMMARY。
• jedi monorepo：5 套件已發版 Nexus（system-menu 0.0.9/auth 0.1.24/information-system 0.0.3/survey 0.0.24/device 0.0.12），主 pyproject 已 pin 新版。
• FE compliance-manager-fe：FR-048 4b 79c0133、DEAD 死碼刪 7afeb49、ECODE#4 i18n b7a9929。
• 詳見 SUMMARY §3。

接手 FR-047 已知坑 arc 剩餘桶（UX/STATE/REPLACE）。先讀交接文件全文：
docs/features/FR-047-2607-feature-spec-handbook/handoff/2026-07-08-known-pits-remaining-buckets-handoff.md
再讀唯一追蹤表 docs/analysis/2026-07-07-known-pits-remediation-tracker.md（進度真相，絕不另開第二份清單）。
答完交接檔 §0 冷接自檢 5 題再動手。branch fix/v1.8.0-bugs 不切、push/發版/merge 等我明示。
接哪桶等我指定：照 §3 SOP「抽桶→逐條 live 驗分性質→同 root 合併→寫追蹤表→跟我定調」，別自己開修。