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

| 項目 | 內容 |
|------|------|
| 緣由 | 508 條「已知坑」逐桶處理 arc。SEC/SCHEMA/DEAD/其他/ECODE 已收口，**剩 UX / STATE / REPLACE 三桶**待處理。本棒交接給下一棒續做。 |
| branch | **`fix/v1.8.0-bugs`**（不要切；不對就停下問 user）|
| **唯一進度真相** | 🔴 **`docs/analysis/2026-07-07-known-pits-remediation-tracker.md`** —— **只有這一份追蹤表**。一切定調/銷帳/桶狀態看它、寫它。**絕對不要另建第二份清單/checklist**（上一棒交接曾出現兩份追蹤表造成混亂，已刪除，勿重蹈）。|
| 收口 SUMMARY | `docs/features/FR-047-2607-feature-spec-handbook/handoff/2026-07-08-known-pits-remediation-SUMMARY.md`（已完成部分的彙整）|
| 母清單 | `docs/analysis/2026-07-07-spec-known-pits-inventory.md`（508 條原文，**只讀不改分類**）|
| 預估 | 剩 3 桶約 113 條，但照塌縮率實際動手估 **一二十個決策點**（~85% 是告知類 no-action）|

---

## 🧭 這個 arc 在解決什麼（WHY，先讀再動手）

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 修。**

---

## §0 接手讀序（按順序，讀完才動手）

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 明示）

---

## §1 現況：508 條桶層總帳（細節看 tracker 進度總覽）

| 桶 | 狀態 |
|----|------|
| ① SEC (75) | ✅ 收口（→ FR-048）|
| ② SCHEMA (60) | ✅ 收口（DDL 5 項 DEV+STG 已套；升級 2 條已修；告知類 no-action）|
| ④ ECODE (39) | ✅ 收口（真缺陷 7 條已修+發版；告知類 no-action）|
| ⑦ DEAD (30) | ✅ 收口（死碼刪、v1 鏈退役、C 族改桶；B 族 topt_secret 待定調）|
| ⑧ 其他 (204) | ✅ 三次複核（~175 no-action、25 歸桶、1 誤報）|
| **③ UX (47)** | ⬜ **待抽桶** |
| **⑤ STATE (33)** | ⬜ **待抽桶** |
| **⑥ REPLACE (33)** | ⬜ **待抽桶** |

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

---

## §2 前棒教訓（別重蹈）

- **絕不建第二份追蹤表**：上棒出現兩份 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 一次再放生。

---

## §3 接一個桶的 SOP（五步，每桶照做）

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`）：
```bash
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 族改桶）。

---

## §4 零星 loose ends（未修 / 未定調，桶外）

在 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 顯示 / 框架下載前科件 + 負向案。

---

## §5 檔案座標

- **進度/定調**：`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/`

---

## §6 Pre-flight（開工前必跑）

```bash
cd ~/Projects/Billows/Audit-Manager/compliance-manager-be
git branch --show-current          # 應為 fix/v1.8.0-bugs，不是就停下問 user
git status --short | grep -v '^??'  # working tree 應乾淨（?? untracked 的 docx/zip 是 user 的別動）
git rev-list --count @{u}..HEAD     # 領先 upstream 數（本 branch 已 push 到 origin/fix/v1.8.0-bugs）
lsof -i :8000 | grep LISTEN         # BE 是否在跑（BE 由 user 起）
```

---

## §7 已完成的不要重做（verify 已收桶）

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

---

## §8 行為規範（本 arc 適用）

- **不切 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；不晶晶體。

---

## §9 收尾流程（每桶定調完 / fix 完）

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

---

## §10 不在本期 scope（別順手做，會 scope creep）

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

---

## §11 本 arc commits（對照用）

- **主 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。

---

## §12 給下個 session 的超短 prompt

```
接手 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 合併→寫追蹤表→跟我定調」，別自己開修。
```