# DESIGN.md 修訂紀錄（節錄）

`DESIGN.md` 是憲法；每一次修訂在此留一列，新的在上面。
規矩見 DESIGN.md §13：實作與文件衝突時，要嘛修實作，要嘛在此留下修訂紀錄後修文件，
不得放任兩者長期不一致。

> 去個資版：原檔二十多列，這裡取有代表性的幾列；機構改代號、數字拿掉。看的重點是「動機」欄——幾乎每一列都是踩坑之後的修法。

| 日期 | 修訂 | 動機 |
|---|---|---|
| <日期> | **DESIGN.md 瘦身，移除暫態內容**：修訂紀錄由 §13 移到本檔（§13 只留原則與指路）；刪除「里程碑」表與其執行紀錄註記（均已完成或由常態流程取代）；刪除「待使用者確認的項目」——已解的內容都在 `config/` 與 STATUS.md，未解項搬到 STATUS.md「未完成」 | 使用者指示：DESIGN.md 是憲法，憲法裡不寫里程碑與待辦事項這類暫態內容，還有效的歸 STATUS.md；修訂紀錄不常用，另立一檔、DESIGN.md 指路即可 |
| <日期> | **§10「備份」補自動化條款**：每週自動、一機構一年份一包、覆蓋前留舊版到雲端 `archive/`（程式永不刪，清理由使用者手動） | 備份原本手動、整機構一包：只要新增一檔就整包重傳，無法週週自動跑；且自動化後「本機出事→自動備份蓋掉好備份」成為新風險，需要覆蓋前留檔＋人工清理的保險 |
| <日期> | **§7.2 新增規矩 9「報表層可整層拋棄重建，判斷一律在 config」**；**§10 目錄樹改成與實際檔案一致**（早期規劃的幾個模組從未建立）；**§11 CLI 只列實際存在的子指令**，設計時列過而未做的另段註明由什麼承接 | 專案健檢：DESIGN 與實作有多處長期不一致（§13 自己說不准這樣）——CLI 列了十幾個不存在的指令、`logs/` 從未建立。同一輪使用者說明他對兩層的態度：「analysis 可以接受、資料庫不能被污染，有問題想重來可以把 analysis 整個打掉」——但要成立必須先把程式裡寫死的日期、帳戶分組搬進 config（鐵則 2），否則打掉 analysis 會連使用者的決定一起丟掉 |
| <日期> | **§7.2 新增規矩 8「報表口徑 ≠ 帳本口徑」**：使用者基於約定不想算進報表的帳戶／幣別／標的，宣告在 `config/report_scope.json`、只有 `analysis/` 讀；帳本一切照舊，不得動 `account.is_own` 或 `include_in_portfolio`；排除金額必須印在報表上 | 使用者說明某帳戶「是我的，但依家人約定報告一律排除，資料庫狀態不變」——既不是所有權變更，也不是帳本有錯，原有的兩個旗標都不對，需要第三個概念 |
| <日期> | **§10 新增 `docs/data-shape.md`**：由 DB 自動生成的資料形狀速查。樣本欄一律**印格式不印值**（數字換成 9、文字只留字數）——第一版用欄位名黑名單判斷該不該遮，實測整批漏出帳號與金額，因為它們「看起來是數字」就被放行；黑名單永遠列不完，所以反過來做。測試守這條線 | 使用者要求量測「產生報告為什麼慢」。實測報表本身只要 0.3 秒，慢的是每次都得重新摸清楚資料長什麼樣（十幾輪試探性 SQL）與 159 秒的全套測試。自動生成的速查解決前者，且因為是從 DB 生成，parser 改了重跑就對 |
| <日期> | **§3.5 房產估值落地＋§10 新增 `data/aside/` 旁置區**：沒有取得成本也沒有現金流的 `real_estate` 帳戶會是一個沒有 lineage 的數字，違反鐵則 4，此時只建估值不建帳戶，報表層直接讀該 L1 檔；估值要標 `confidence`，由貸款金額回推者一律 `low`，且**必須在報表上說明「估值 − 貸款」不是獨立資訊** | 使用者提供房產估值並要求記入資產；同時要求一個「不刪掉、但不能進檔案庫」的位置放他自己的手工統計表——原本三個位置都不對：`data/raw/` 進去就成了證據、`data/inbox/` 是待歸檔、`config/` 要進 Git。另外 agent 連續數次沒去 `data/inbox/` 找使用者已經放好的檔案，使用者要求把行為規則寫進文件（同步寫入 AGENTS.md） |
| <日期> | **銀行C 全盤覆盤（使用者下令「別相信現況、親自抽查所有原始文件」）**：新增三個來源與 parser；既有 parser 升版修「某段落靜默 0 列」；新增**統計表加總 gate**（庫存 0 列而統計有數字＝整份拒收，同型靜默漏段從此必炸）；授權修訂：通知書的贖回一律不入現金（印的是申請額），贖回現金以對帳單實際入款為權威 | 覆盤實測：信箱幾百個候選檔中四類從未使用，對帳單七個段落被靜默丟棄。「數字自洽但少資料／解讀錯」正是驗證抓不到的兩類病；修法是讓文件自印的統計表當守門員，並把「段落標題在、列數為 0」一律視為 parser 壞掉而非資料不存在 |
| <日期> | §6.4 分類規則由紙上規格變成實作：compose 在連結全部做完之後，把仍然 unknown 的真外部進出依 `config/rules/categorize.json` 決定性安上名分。verify 新增 `categorized_event_criteria` 硬 gate：逐筆回頭用 L1 規則重判，規則改了而帳沒重建就 fail。順序鐵律：**先連結後分類** | 實作時抓到兩個教訓：(1) 單邊處理過的鏡像列漏進分類輸入，被記成利息收入——券商那側已記過配息，等於重複計息，故分類輸入必須排除所有已處理的列；(2) 某前綴規則把「提前贖回」掃成配息收入——那是債券本金返還，差一個字元就把本金當收入 |
| <日期> | **組合階段（§6）由紙上規格變成實作，並修訂三處**：自動連結門檻調整（`R1_exact` 光靠金額與日期不到自動門檻，必須再命中摘要線索）；新增「同分且對側不唯一一律降級待審」與其唯一例外（完全二分圖的同額群組）；新增 §6.2.1「只有一邊的連結」 | 使用者要求「有把握的直接連，沒把握的列出來給我看」。實測發現原本的門檻會直接自動採用一批明顯錯誤的配對——小額整數在多帳戶間必然碰撞。把金額日期降為「必要但不充分」、要求摘要線索互相指認之後，82 組自動連結沒有一組是錯的。同分打平原本要「取最高信心」，但同分時那等於隨機挑一個，所以改為降級待審 |
| <日期> | §2.6-1 新增「權威可以只涵蓋一段期間」：帳戶明細只能下載最近一年時，涵蓋到的日子由明細建 txn、涵蓋不到的維持原來的來源，涵蓋範圍由資料本身算出且必須有不重複入帳的檢查 | 銀行C 有兩份文件描述同一筆錢：交易通知書（多年）與網銀明細（最近一年，有銀行印的逐列餘額）。原本只用通知書建現金，結果是**帳是錯的**：通知書上贖回那一列印的是「申請金額」，銀行帳上根本沒有對應入帳，而薪資、卡費等整個帳戶的真實活動完全看不見。改成「明細涵蓋期間內明細說了算」之後，四個帳戶第一次有了可驗證的餘額鏈 |
| <日期> | **Phase 2 由「不實作」改為「已開始，住在 pipeline 之外」**：§0 階段劃分改寫（刪除「agent 不應花時間在分析功能上」，改為「分析一律外掛、不得回頭改動帳本層」）；新增 §7.2 明訂 `analysis/` 的位置、單向依賴與規矩 | 使用者決定「現在就可以先做這些測試」，第一份報告已實作完成。憲法不能繼續寫「不實作」——但真正要守住的不是「不做分析」，是**分析不得回頭污染帳本層**，所以改成寫明界線而不是禁止 |