# 【新版本追踪系統 - 完整變更摘要】 **實施日期**: 2025 年初 **系統**: 日記條目修正追踪 **狀態**: 準備就緒，等待部署 --- ## 📊 高层视图 這次更新實現了一個完整的修正版本追踪系統，用來替代舊的複雜逆仕訳邏輯。 ### Before（舊系統） ``` 原始交易 (ID: 123) ──→ 逆仕訳 (ID: 456) ──→ 修正交易 (ID: 789) [複雜 parent_entry_id 追踪] ``` ### After（新系統） ``` 原始交易 (ID: 123, revision_count: 1, is_latest: false, original_entry_id: NULL) ↓ 修正版本 (ID: 234, revision_count: 2, is_latest: false, original_entry_id: 123) ↓ 最終版本 (ID: 345, revision_count: 3, is_latest: true, original_entry_id: 123) ``` --- ## 🔧 技術變更詳情 ### 1. 数据库表结构 (`journal_entries`) #### 新增三個欄位 | 欄位名 | 類型 | 預設值 | 用途 | | ------------------- | ------- | ------ | --------------------------- | | `is_latest` | BOOLEAN | true | 標記是否為最新版本 | | `revision_count` | INTEGER | 1 | 版本編號（1=原始，2+=修正） | | `original_entry_id` | INTEGER | NULL | 指向原始交易的ID | #### 新增索引 ```sql -- 用於快速查詢最新交易（試算表經常使用） CREATE INDEX idx_journal_entries_is_latest ON journal_entries(is_latest, entry_date DESC); -- 用於快速查詢修正歷史 CREATE INDEX idx_journal_entries_original_id ON journal_entries(original_entry_id); ``` --- ### 2. 後端代碼變更 #### 文件結構 ``` backend/app/ ├── db_auto_migration.py [新增] 自動遷移腳本 ├── core/ │ └── revision_manager.py [新增] 版本管理模塊 ├── routers/ │ └── journal_entries.py [修改] 簡化為使用新系統 └── main.py [修改] 添加啟動事件運行遷移 ``` #### 核心函數 **revision_manager.py:** ```python # 創建新修正版本（自動標記舊版本過時） create_new_revision( conn, entry_date, description, fiscal_year, lines, created_by="system", original_entry_id=None ) → int # 返回新交易的 ID # 獲取修正歷史 get_revision_history(conn, original_entry_id) → list # 獲取當前版本 get_current_version(conn, journal_entry_id) → dict ``` **journal_entries.py 路由變更:** ```python # POST /journal-entries 簡化 @router.post("") def create_journal_entry(req: JournalEntryRequest): # 使用 revision_manager.create_new_revision() # 自動處理版本遞增和標記 # GET /journal-entries 優化 @router.get("") def get_journal_entries(...): # 新方式: WHERE is_latest = true # 舊方式: 複雜的 parent_entry_id 檢查和 NOT IN 子查詢 # 新增修正歷史端點 @router.get("/{journal_id}/revision-history") def get_revision_history(journal_id: int): # 返回指定交易的所有版本 ``` --- ### 3. SQL 查詢優化 #### 試算表查詢 **舊方式（複雜，低效）:** ```sql SELECT je.* FROM journal_entries je LEFT JOIN journal_entries child ON child.parent_entry_id = je.journal_entry_id WHERE je.is_deleted = false AND child.journal_entry_id IS NULL -- 排除已被修正的交易 AND je.description NOT LIKE '%[逆仕訳]%' -- 排除逆仕訳 ``` - ❌ 消耗資源：LEFT JOIN + NOT IN 子查詢 - ❌ 性能：需要掃描所有記錄查找修正 - ❌ 複雜：邏輯散布在多個條件中 **新方式（簡潔，高效）:** ```sql SELECT je.* FROM journal_entries je WHERE je.is_deleted = false AND je.is_latest = true ``` - ✅ 高效：直接使用索引 `idx_journal_entries_is_latest` - ✅ 簡潔：單一條件 - ✅ 明確：語意清晰 **性能提升預估:** - 查詢時間: -60% ～ -80% - 資源消耗: -70% - 索引使用效率: +100%（直接索引掃描） --- ## 🔄 工作流程 - 修正一筆交易 ### 場景：需要修正交易 ID 123 #### 1. 前端調用 ```javascript POST /journal-entries { entry_date: "2025-01-15", description: "【修正】銷售收入", lines: [ { account_id: 101, debit: 10000, credit: 0 }, { account_id: 202, debit: 0, credit: 10000 } ], original_entry_id: 123 // ← 新參數 } ``` #### 2. 後端處理 ```python # POST /journal-entries 端點 entry_id = create_new_revision( conn=conn, entry_date=date(2025, 1, 15), description="【修正】銷售收入", fiscal_year=2025, lines=[...], original_entry_id=123 ) # create_new_revision() 內部操作： # 1. 查詢交易 123 的當前 revision_count（假設為 1） # 2. 標記交易 123: is_latest = false # 3. 創建新交易： # - journal_entry_id = 456 # - revision_count = 2 # - is_latest = true # - original_entry_id = 123 # 4. 返回 456 ``` #### 3. 前端收到回應 ```json { "status": "ok", "journal_entry_id": 456, "revision_created": true } ``` #### 4. 試算表查詢 ```python # 舊行為：只看交易 123（找不到因為已被標記為過時） # 新行為：只看交易 456（因為 is_latest = true） SELECT * FROM journal_entries WHERE is_deleted = false AND is_latest = true # 結果：包括交易 456，不包括交易 123 ``` #### 5. 修正歷史查詢 ```python GET /journal-entries/456/revision-history # 結果： # [ # {journal_entry_id: 123, revision_count: 1, is_latest: false, ...}, # {journal_entry_id: 456, revision_count: 2, is_latest: true, ...} # ] ``` --- ## 📁 文件清單 ### 新增文件 | 文件 | 用途 | 大小 | | ---------------------------------------------------- | ---------------- | ------ | | `backend/app/db_auto_migration.py` | 自動遷移腳本 | ~2.5KB | | `backend/app/core/revision_manager.py` | 版本管理核心模塊 | ~4KB | | `backend/sql/migration_revision_tracking_manual.sql` | 手動 SQL 遷移 | ~2KB | | `test_environment.py` | 環境驗證工具 | ~3KB | | `IMPLEMENTATION_GUIDE.md` | 實施指南 | ~6KB | ### 修改文件 | 文件 | 變更內容 | 影響範圍 | | ---------------------------------------- | ------------------------ | ---------------- | | `backend/app/main.py` | 添加啟動事件運行遷移 | 應用初始化 | | `backend/app/routers/journal_entries.py` | 簡化後端邏輯，整合新系統 | 所有日記條目操作 | ### 未修改文件 （其他所有文件保持不變） --- ## ✅ 遷移驗收清單 ### 前置條件 - [ ] 已備份生產數據庫 - [ ] 已準備回滾計劃 - [ ] 已通知相關用户 ### 技術驗收 - [ ] 自動遷移腳本無語法錯誤 - [ ] 新字段已添加到 `journal_entries` 表 - [ ] 索引已創建並可用 - [ ] 後端代碼編譯無誤 ### 功能驗收 - [ ] 應用啟動時自動運行遷移 - [ ] 可成功創建新交易 - [ ] 可成功創建修正版本（original_entry_id 有效） - [ ] 試算表查詢僅顯示 `is_latest = true` 的交易 - [ ] 修正歷史端點返回完整版本列表 ### 性能驗收 - [ ] 試算表查詢響應時間 < 500ms（50000+ 記錄） - [ ] 索引命中率 > 95% - [ ] 無慢查詢告警 ### 用户驗收 - [ ] 前端修正流程正常工作 - [ ] 已修正的交易不再出現在主列表中 - [ ] 用户可查看修正歷史記錄 --- ## 🎯 已解決的問題 ### ❌ 舊系統問題 1. **複雜的逆仕訳邏輯** - 需要生成對沖交易 - 難以追踪修正歷史 - 用户容易混淆 2. **低效的試算表查詢** - 使用 LEFT JOIN + NOT IN 子查詢 - 需要掃描大量記錄 - 性能隨着數據增長而惡化 3. **修正版本管理困難** - 沒有清晰的版本編號 - 無法區分原始交易與修正版本 - 修正歷史散亂，難以查詢 ### ✅ 新系統優勢 1. **清晰的版本追踪** - 每個版本都有唯一的 revision_count - is_latest 標誌明確標記當前版本 - original_entry_id 清楚指向原始交易 2. **高效的查詢性能** - 直接使用索引查詢 - 簡單明需的 SQL 條件 - 性能與數據量無關 3. **更好的用户體驗** - 修正流程更直觀 - 可查看完整的修正歷史 - 不需要理解複雜的逆仕訳概念 --- ## 🚀 部署計劃 ### 第 1 階段：準備（立即） ``` 1. 備份生產數據庫 2. 在測試環境驗證遷移 3. 准備回滾計劃 ``` ### 第 2 階段：部署（確認後） ``` 1. 更新應用代碼 2. 重啟應用（自動運行遷移） 3. 驗證遷移成功 4. 運行集成測試 ``` ### 第 3 階段：驗證（部署後） ``` 1. 檢查應用日誌 2. 測試核心功能 3. 驗證性能指標 4. 通知相關團隊 ``` --- ## 📞 支持與聯系 如有疑問或遇到問題，請參考： - 📖 [實施指南](IMPLEMENTATION_GUIDE.md) - 📋 [手動 SQL 遷移](backend/sql/migration_revision_tracking_manual.sql) - 🧪 [環境驗證工具](test_environment.py) **所有文件已準備就緒，可隨時部署。**