1Bug（程式錯誤）:
 2- 導致功能失敗或程式崩潰
 3- 需要立即修正
 4- 透過測試失敗發現
 5
 6Code Smell（程式異味）:
 7- 程式功能正常運作
 8- 暗示設計問題，未來可能導致維護困難
 9- 透過程式碼檢視或靜態分析發現
10- 透過重構改善

 1設計階段檢測 vs 實作階段檢測：
 2
 3設計階段（Ticket 粒度）:
 4- 修正成本: 低（只需要調整設計）
 5- 影響範圍: 小（尚未實作程式碼）
 6- 風險: 低（無需修改既有程式碼）
 7
 8實作階段（Code Review）:
 9- 修正成本: 中（需要重寫部分程式碼）
10- 影響範圍: 中（可能影響多個檔案）
11- 風險: 中（需要回歸測試）
12
13維護階段（上線後）:
14- 修正成本: 高（需要大規模重構）
15- 影響範圍: 大（可能影響多個模組）
16- 風險: 高（可能引入新 Bug）

 1Code Smell 分類體系（基於[層級隔離派工方法論](/record/layered-ticket-methodology/) 第 2.2 節五層架構定義）
 2
 3A. 跨層級 Code Smells（違反層級隔離）
 4   ├─ A1. Shotgun Surgery（散彈槍手術）
 5   ├─ A2. Feature Envy（功能嫉妒）
 6   ├─ A3. Inappropriate Intimacy（不當親密關係）
 7   └─ A4. Leaky Abstraction（抽象滲漏）
 8
 9B. 單層級 Code Smells（違反單一職責）
10   ├─ B1. Divergent Change（發散式變更）
11   ├─ B2. Large Class（大類別）
12   ├─ B3. Long Method（長方法）
13   └─ B4. Dead Code（死程式碼）
14
15C. Ticket 粒度相關 Code Smells
16   ├─ C1. God Ticket（全能 Ticket）
17   ├─ C2. Incomplete Ticket（不完整 Ticket）
18   └─ C3. Ambiguous Responsibility（職責模糊 Ticket）

 1需求：書籍新增「出版社」欄位
 2
 3反例 Shotgun Surgery 模式：
 4- Layer 1 (UI): BookDetailWidget 新增 publisher Text
 5- Layer 2 (Behavior): BookDetailController 新增 publisher 屬性
 6- Layer 3 (UseCase): GetBookDetailUseCase 新增 publisher 參數
 7- Layer 5 (Domain): Book Entity 新增 publisher 欄位
 8
 9問題分析：
10- 修改 4 個層級（Layer 1, 2, 3, 5）
11- 修改至少 4 個檔案
12- 違反單層修改原則
13- 風險：任一層級修改錯誤都會影響整個功能
14
15正例 正確做法（引入 Facade）：
16- Phase 1 [Layer 5]: Book Entity 新增 publisher 欄位
17- Phase 2 [Layer 3]: BookDetailFacade 更新回傳資料
18- Phase 3 [Layer 2]: Presenter 轉換新增 publisher
19- Phase 4 [Layer 1]: UI 顯示 publisher
20
21改善效果：
22- 每個 Phase 只修改單一層級
23- 變更影響範圍可控
24- 風險降低

 1// 反例：Shotgun Surgery：新增欄位需要修改 4 層
 2
 3// Layer 5 (Domain)
 4class Book {
 5  final String title;
 6  final ISBN isbn;
 7  final String publisher; // 新增欄位
 8}
 9
10// Layer 3 (UseCase)
11class GetBookDetailUseCase {
12  Future<Book> execute(String id) async {
13    final book = await repository.findById(id);
14    // 需要處理 publisher
15    return book;
16  }
17}
18
19// Layer 2 (Behavior)
20class BookDetailController {
21  String? publisher; // 新增屬性
22
23  void loadBookDetail(String id) async {
24    final book = await getBookDetailUseCase.execute(id);
25    publisher = book.publisher; // 新增處理
26  }
27}
28
29// Layer 1 (UI)
30class BookDetailWidget {
31  Widget build(BuildContext context) {
32    return Column(
33      children: [
34        Text(controller.title),
35        Text(controller.publisher ?? ''), // 新增顯示
36      ],
37    );
38  }
39}
40
41// 正例：引入 Facade 隔離變更
42
43// Layer 4 (Domain Interface)
44abstract class IBookDetailFacade {
45  Future<BookDetailViewModel> getBookDetail(String id);
46}
47
48// Layer 3 (UseCase - Facade Implementation)
49class BookDetailFacade implements IBookDetailFacade {
50  Future<BookDetailViewModel> getBookDetail(String id) async {
51    final book = await bookRepository.findById(id);
52    return BookPresenter.toViewModel(book); // 統一轉換
53  }
54}
55
56// Layer 2 (Behavior - Presenter)
57class BookPresenter {
58  static BookDetailViewModel toViewModel(Book book) {
59    return BookDetailViewModel(
60      title: book.title.value,
61      isbn: book.isbn.value,
62      publisher: book.publisher, // 新增欄位在這裡處理
63    );
64  }
65}
66
67// Layer 1 (UI) - 無需修改
68class BookDetailWidget {
69  Widget build(BuildContext context) {
70    return Column(
71      children: [
72        Text(viewModel.title),
73        Text(viewModel.isbn),
74        Text(viewModel.publisher), // 直接使用 ViewModel
75      ],
76    );
77  }
78}
79
80改善效果：
81- 未來新增欄位只需要修改 Layer 3 (Facade) 和 Layer 2 (Presenter)
82- Layer 1 (UI) 和 Layer 5 (Domain) 的修改影響已隔離

 1// 反例：Feature Envy：UI 直接存取 Domain Entity
 2
 3import 'package:book_overview_app/domains/library/entities/book.dart';
 4// 反例：UI 層不應 import Domain Entity
 5
 6class BookDetailWidget extends StatelessWidget {
 7  final Book book; // 反例：直接依賴 Domain Entity
 8
 9  Widget build(BuildContext context) {
10    return Column(
11      children: [
12        Text(book.title.value),        // 反例：存取內部欄位
13        Text(book.isbn.value),         // 反例：存取內部欄位
14        Text(book.author.name),        // 反例：存取內部欄位
15        Text(book.isNewRelease() ? '新書' : ''), // 反例：呼叫 Domain 方法
16      ],
17    );
18  }
19}
20
21問題分析：
22- UI 層 import Domain Entity（違反依賴方向）
23- UI 直接存取 Entity 內部欄位（緊耦合）
24- UI 呼叫 Domain 業務方法（職責混亂）
25- Domain 修改會影響 UI（高風險）
26
27// 正例：透過 ViewModel 轉換
28
29// Layer 2: 定義 ViewModel
30import 'package:book_overview_app/presentation/view_models/book_view_model.dart';
31
32class BookViewModel {
33  final String title;
34  final String isbn;
35  final String author;
36  final bool isNew;
37
38  BookViewModel({
39    required this.title,
40    required this.isbn,
41    required this.author,
42    required this.isNew,
43  });
44}
45
46// Layer 2: Presenter 轉換（資料轉換職責）
47class BookPresenter {
48  static BookViewModel toViewModel(Book book) {
49    return BookViewModel(
50      title: book.title.value,      // 提取內部欄位
51      isbn: book.isbn.value,        // 提取內部欄位
52      author: book.author.name,     // 提取內部欄位
53      isNew: book.isNewRelease(),   // 執行 Domain 方法
54    );
55  }
56}
57
58// Layer 1: UI 使用 ViewModel
59class BookDetailWidget extends StatelessWidget {
60  final BookViewModel viewModel; // 正例：依賴 ViewModel
61
62  Widget build(BuildContext context) {
63    return Column(
64      children: [
65        Text(viewModel.title),    // 正例：使用轉換後的資料
66        Text(viewModel.isbn),     // 正例：使用轉換後的資料
67        Text(viewModel.author),   // 正例：使用轉換後的資料
68        Text(viewModel.isNew ? '新書' : ''), // 正例：使用轉換後的狀態
69      ],
70    );
71  }
72}
73
74改善效果：
75- UI 層不依賴 Domain Entity（降低耦合）
76- Presenter 集中處理資料轉換（符合 Layer 2 職責）
77- Domain 修改不影響 UI（只需調整 Presenter）
78- 測試更容易（Mock ViewModel 即可）

 1// 反例：Inappropriate Intimacy：Domain 依賴 UseCase
 2
 3// Layer 5 (Domain)
 4import 'package:book_overview_app/application/use_cases/add_book_to_favorite_use_case.dart';
 5// 反例：Domain 不應 import UseCase
 6
 7class Book {
 8  final String id;
 9  final Title title;
10  final AddBookToFavoriteUseCase favoriteUseCase; // 反例：Domain 依賴 UseCase
11
12  void addToFavorite() {
13    favoriteUseCase.execute(this.id); // 反例：Domain 不應呼叫 UseCase
14  }
15}
16
17問題分析：
18- Domain 依賴外層（UseCase）
19- 違反依賴方向規則
20- Domain 失去獨立性和可重用性
21- 測試困難（Domain 測試需要 Mock UseCase）
22
23// 正例：Domain 只定義業務邏輯
24
25// Layer 5 (Domain) - 獨立且純淨
26class Book {
27  final String id;
28  final Title title;
29  bool isFavorited = false; // 正例：只記錄狀態
30
31  void markAsFavorite() {
32    this.isFavorited = true; // 正例：只處理業務邏輯
33  }
34
35  void unmarkFromFavorite() {
36    this.isFavorited = false;
37  }
38}
39
40// Layer 3 (UseCase) - 協調業務流程
41class AddBookToFavoriteUseCase {
42  final IBookRepository bookRepository;
43  final IFavoriteRepository favoriteRepository;
44
45  Future<void> execute(String bookId) async {
46    // 1. 取得書籍
47    final book = await bookRepository.findById(bookId);
48
49    // 2. 執行 Domain 方法
50    book.markAsFavorite(); // 正例：UseCase 呼叫 Domain 方法
51
52    // 3. 儲存狀態
53    await bookRepository.save(book);
54    await favoriteRepository.add(bookId);
55  }
56}
57
58// Layer 2 (Behavior/Controller) - 觸發 UseCase
59class BookDetailController {
60  final AddBookToFavoriteUseCase addToFavoriteUseCase;
61
62  void onFavoriteButtonPressed(String bookId) async {
63    await addToFavoriteUseCase.execute(bookId); // 正例：呼叫方向
64  }
65}
66
67改善效果：
68- Domain 獨立且純淨（不依賴外層）
69- 依賴方向正確（Layer 2 → Layer 3 → Layer 5）
70- Domain 可重用性高
71- 測試容易（Domain 無外部依賴）

 1// 反例：Leaky Abstraction：介面洩漏實作細節
 2
 3// Layer 4 (Domain Interface)
 4abstract class IBookRepository {
 5  Future<Book> findBySql(String sql);        // 反例：洩漏 SQL 實作
 6  Future<List<Book>> queryWithCursor(Cursor cursor); // 反例：洩漏資料庫 Cursor
 7  Future<void> saveToSqlite(Book book);      // 反例：洩漏 SQLite 實作
 8}
 9
10問題分析：
11- 介面包含「SQL」、「Cursor」、「Sqlite」等實作關鍵字
12- 外層（UseCase）需要知道使用 SQL 資料庫
13- 無法更換實作（綁定 SQLite）
14- 違反介面契約原則
15
16// 正例：抽象介面
17
18// Layer 4 (Domain Interface) - 抽象且純淨
19abstract class IBookRepository {
20  Future<Book> findById(String id);          // 正例：隱藏實作細節
21  Future<List<Book>> findByAuthor(String author); // 正例：業務概念
22  Future<List<Book>> findAll();              // 正例：簡單明確
23  Future<void> save(Book book);              // 正例：抽象操作
24  Future<void> delete(String id);            // 正例：抽象操作
25}
26
27// Layer 5 (Infrastructure) - 具體實作可替換
28class SqliteBookRepository implements IBookRepository {
29  @override
30  Future<Book> findById(String id) async {
31    // SQL 實作細節在這裡
32    final result = await db.query(
33      'books',
34      where: 'id = ?',
35      whereArgs: [id],
36    );
37    return Book.fromJson(result.first);
38  }
39}
40
41// Layer 5 (Infrastructure) - 另一種實作
42class FirestoreBookRepository implements IBookRepository {
43  @override
44  Future<Book> findById(String id) async {
45    // Firestore 實作細節在這裡
46    final doc = await firestore.collection('books').doc(id).get();
47    return Book.fromJson(doc.data()!);
48  }
49}
50
51改善效果：
52- 介面抽象且純淨（不包含實作細節）
53- 可輕鬆更換實作（SQLite → Firestore）
54- UseCase 不需要知道資料庫實作
55- 符合依賴倒置原則

 1// 反例：Divergent Change：單一 Controller 承擔多個職責
 2
 3class BookController {
 4  // 群組 A：列表頁面邏輯（3 個方法）
 5  List<BookViewModel> bookList = [];
 6
 7  void loadBookList() {
 8    // 載入書籍列表
 9  }
10
11  void refreshBookList() {
12    // 重新整理列表
13  }
14
15  void sortBookList(String sortBy) {
16    // 排序列表
17  }
18
19  // 群組 B：詳情頁面邏輯（3 個方法）
20  BookViewModel? bookDetail;
21
22  void loadBookDetail(String id) {
23    // 載入書籍詳情
24  }
25
26  void updateBookDetail() {
27    // 更新書籍詳情
28  }
29
30  void deleteBook() {
31    // 刪除書籍
32  }
33
34  // 群組 C：搜尋邏輯（2 個方法）
35  List<BookViewModel> searchResults = [];
36
37  void searchBooks(String query) {
38    // 搜尋書籍
39  }
40
41  void clearSearchResults() {
42    // 清空搜尋結果
43  }
44}
45
46問題分析：
47- 3 個方法群組（列表、詳情、搜尋）
48- 3 種變更原因（列表變更、詳情變更、搜尋變更）
49- 類別名稱過於籠統（BookController）
50- 違反 SRP 原則
51
52// 正例：拆分為多個單一職責 Controller
53
54// Controller 1：只負責列表
55class BookListController {
56  List<BookViewModel> bookList = [];
57
58  void loadBookList() { }
59  void refreshBookList() { }
60  void sortBookList(String sortBy) { }
61}
62
63// Controller 2：只負責詳情
64class BookDetailController {
65  BookViewModel? bookDetail;
66
67  void loadBookDetail(String id) { }
68  void updateBookDetail() { }
69  void deleteBook() { }
70}
71
72// Controller 3：只負責搜尋
73class BookSearchController {
74  List<BookViewModel> searchResults = [];
75
76  void searchBooks(String query) { }
77  void clearSearchResults() { }
78}
79
80改善效果：
81- 每個 Controller 只有 1 個變更原因
82- 職責明確且單一
83- 可讀性提升
84- 測試更容易（測試範圍更小）

 1// 反例：Large Class：職責過多（500+ 行）
 2
 3class BookService { // 總行數：500+ 行
 4  // 新增書籍（20 個方法）
 5  Future<void> addBook(Book book) { }
 6  Future<void> addMultipleBooks(List<Book> books) { }
 7  Future<void> importBooksFromCsv(String filePath) { }
 8  // ... 17 個其他方法
 9
10  // 查詢書籍（15 個方法）
11  Future<Book> findBook(String id) { }
12  Future<List<Book>> findBooksByAuthor(String author) { }
13  Future<List<Book>> searchBooks(String query) { }
14  // ... 12 個其他方法
15
16  // 統計分析（10 個方法）
17  Future<BookStats> getStatistics() { }
18  Future<Map<String, int>> getBooksByGenre() { }
19  Future<List<Book>> getMostPopular() { }
20  // ... 7 個其他方法
21
22  // 匯出報表（8 個方法）
23  Future<void> exportReport() { }
24  Future<void> exportToPdf() { }
25  Future<void> exportToExcel() { }
26  // ... 5 個其他方法
27}
28
29問題分析：
30- 總行數: 500+ 行（超過 300 行標準）
31- public 方法: 53 個（超過 15 個標準）
32- 4 種不同職責（新增、查詢、統計、匯出）
33- 違反 SRP 原則
34
35// 正例：拆分為多個職責明確的 Service
36
37// Service 1：書籍管理（新增、更新、刪除）
38class BookManagementService {
39  Future<void> addBook(Book book) { }
40  Future<void> updateBook(Book book) { }
41  Future<void> deleteBook(String id) { }
42}
43
44// Service 2：書籍查詢
45class BookQueryService {
46  Future<Book> findById(String id) { }
47  Future<List<Book>> findByAuthor(String author) { }
48  Future<List<Book>> search(String query) { }
49}
50
51// Service 3：書籍統計
52class BookStatisticsService {
53  Future<BookStats> getStatistics() { }
54  Future<Map<String, int>> getBooksByGenre() { }
55  Future<List<Book>> getMostPopular() { }
56}
57
58// Service 4：報表匯出
59class BookReportService {
60  Future<void> exportToPdf() { }
61  Future<void> exportToExcel() { }
62  Future<void> exportToCsv() { }
63}
64
65改善效果：
66- 每個 Service < 200 行
67- 職責單一且明確
68- 可測試性提升
69- 可維護性提升

  1// 反例：Long Method：80 行方法
  2
  3Future<void> processBookOrder(Order order) async {
  4  // 驗證訂單（20 行）
  5  if (order.items.isEmpty) {
  6    throw ValidationException('訂單不能為空');
  7  }
  8
  9  for (var item in order.items) {
 10    if (item.quantity <= 0) {
 11      throw ValidationException('數量必須大於 0');
 12    }
 13    if (item.price < 0) {
 14      throw ValidationException('價格不能為負數');
 15    }
 16  }
 17
 18  // 計算價格（20 行）
 19  double total = 0;
 20  double discount = 0;
 21
 22  for (var item in order.items) {
 23    total += item.price * item.quantity;
 24  }
 25
 26  if (total > 1000) {
 27    discount = total * 0.1;
 28  } else if (total > 500) {
 29    discount = total * 0.05;
 30  }
 31
 32  total -= discount;
 33
 34  // 庫存檢查（20 行）
 35  for (var item in order.items) {
 36    final stock = await inventoryRepository.getStock(item.bookId);
 37    if (stock < item.quantity) {
 38      throw InsufficientStockException(
 39        '書籍 ${item.bookId} 庫存不足'
 40      );
 41    }
 42  }
 43
 44  // 建立訂單（20 行）
 45  order.total = total;
 46  order.discount = discount;
 47  order.status = OrderStatus.pending;
 48  order.createdAt = DateTime.now();
 49
 50  await repository.save(order);
 51
 52  // 扣除庫存
 53  for (var item in order.items) {
 54    await inventoryRepository.reduceStock(
 55      item.bookId,
 56      item.quantity,
 57    );
 58  }
 59}
 60
 61問題分析：
 62- 方法行數: 80 行（超過 50 行標準）
 63- 4 個邏輯區塊（驗證、計算、庫存、建立）
 64- 巢狀層級: 3 層（for + if）
 65- 難以理解和測試
 66
 67// 正例：拆分為多個小方法
 68
 69Future<void> processBookOrder(Order order) async {
 70  _validateOrder(order);              // 步驟 1
 71  final total = _calculateTotal(order); // 步驟 2
 72  await _checkInventory(order);       // 步驟 3
 73  await _saveOrder(order, total);     // 步驟 4
 74}
 75
 76void _validateOrder(Order order) {
 77  if (order.items.isEmpty) {
 78    throw ValidationException('訂單不能為空');
 79  }
 80
 81  for (var item in order.items) {
 82    _validateOrderItem(item);
 83  }
 84}
 85
 86void _validateOrderItem(OrderItem item) {
 87  if (item.quantity <= 0) {
 88    throw ValidationException('數量必須大於 0');
 89  }
 90  if (item.price < 0) {
 91    throw ValidationException('價格不能為負數');
 92  }
 93}
 94
 95double _calculateTotal(Order order) {
 96  double total = 0;
 97
 98  for (var item in order.items) {
 99    total += item.price * item.quantity;
100  }
101
102  final discount = _calculateDiscount(total);
103  return total - discount;
104}
105
106double _calculateDiscount(double total) {
107  if (total > 1000) return total * 0.1;
108  if (total > 500) return total * 0.05;
109  return 0;
110}
111
112Future<void> _checkInventory(Order order) async {
113  for (var item in order.items) {
114    final stock = await inventoryRepository.getStock(item.bookId);
115    if (stock < item.quantity) {
116      throw InsufficientStockException(
117        '書籍 ${item.bookId} 庫存不足'
118      );
119    }
120  }
121}
122
123Future<void> _saveOrder(Order order, double total) async {
124  order.total = total;
125  order.status = OrderStatus.pending;
126  order.createdAt = DateTime.now();
127
128  await repository.save(order);
129  await _reduceInventory(order);
130}
131
132Future<void> _reduceInventory(Order order) async {
133  for (var item in order.items) {
134    await inventoryRepository.reduceStock(
135      item.bookId,
136      item.quantity,
137    );
138  }
139}
140
141改善效果：
142- 主方法只有 4 行（清楚的流程）
143- 每個私有方法 < 20 行
144- 邏輯分離且可測試
145- 可讀性大幅提升

 1# 檢測 unused 警告
 2dart analyze | grep "unused"
 3
 4# 檢測程式碼覆蓋率
 5flutter test --coverage
 6genhtml coverage/lcov.info -o coverage/html
 7# 檢查 coverage/html 中 0% 覆蓋率的程式碼
 8
 9# 搜尋註解掉的程式碼
10grep -r "^[[:space:]]*//.*{" lib/

 1// 反例：Dead Code 範例
 2
 3class BookService {
 4  // 未使用的方法（dart analyze 會警告）
 5  void unusedMethod() {
 6    print('這個方法從未被呼叫');
 7  }
 8
 9  // 無法到達的程式碼
10  void processBook(Book book) {
11    return; // 提前返回
12
13    // 反例：以下程式碼永遠不會執行
14    print('處理書籍');
15    saveBook(book);
16  }
17
18  // 註解掉的程式碼（已過時）
19  // void oldImplementation() {
20  //   // 舊的實作方式，已被新方法取代
21  //   // 但程式碼保留了 2 個月
22  // }
23
24  // 未使用的變數
25  final String unusedVariable = 'never used';
26}
27
28// 正例：移除 Dead Code
29
30class BookService {
31  // 只保留實際使用的方法
32  void processBook(Book book) {
33    print('處理書籍');
34    saveBook(book);
35  }
36}
37
38改善效果：
39- 程式碼簡潔
40- 降低維護成本
41- 無混淆和誤導

1步驟 1: 計算 Ticket 涉及的檔案數
2步驟 2: 判斷檔案所屬的層級
3步驟 3: 計算跨幾個層級
4  ├─ > 3 層級 → God Ticket
5  └─ 1 層級 → 良好 Ticket

 1Ticket: 新增「書籍評分」完整功能
 2
 3檔案清單（12 個檔案）:
 4
 51. lib/presentation/widgets/book_detail_widget.dart (Layer 1)
 62. lib/presentation/widgets/rating_widget.dart (Layer 1)
 73. lib/presentation/controllers/book_detail_controller.dart (Layer 2)
 84. lib/presentation/controllers/rating_controller.dart (Layer 2)
 95. lib/application/use_cases/rate_book_use_case.dart (Layer 3)
106. lib/application/use_cases/get_book_rating_use_case.dart (Layer 3)
117. lib/domain/entities/book.dart (Layer 5)
128. lib/domain/entities/rating.dart (Layer 5)
139. lib/domain/value_objects/rating_value.dart (Layer 5)
1410. lib/infrastructure/repositories/book_repository_impl.dart (Layer 5)
1511. lib/infrastructure/repositories/rating_repository_impl.dart (Layer 5)
1612. lib/infrastructure/database/rating_table.dart (Layer 5)
17
18分析結果:
19- 檔案數: 12 個（> 10 個標準）
20- 層級跨度: 4 層（Layer 1, 2, 3, 5）
21- 預估工時: 24 小時（> 16 小時標準）
22- 判斷: God Ticket
23
24建議拆分（引用[層級隔離派工方法論](/record/layered-ticket-methodology/) 第 5.4 節拆分指引）:
25- Ticket 1 [Layer 5]: Rating Value Object 和 Entity 設計
26- Ticket 2 [Layer 5]: Rating Repository 實作
27- Ticket 3 [Layer 3]: RateBookUseCase 實作
28- Ticket 4 [Layer 3]: GetBookRatingUseCase 實作
29- Ticket 5 [Layer 2]: Controller 整合 UseCase
30- Ticket 6 [Layer 1]: UI 新增評分元件
31
32改善效果:
33- 每個 Ticket 只修改 1-3 個檔案
34- 每個 Ticket 只涉及 1 個層級
35- 預估工時: 每個 Ticket 2-4 小時
36- 風險可控

 1完整 Ticket 必須包含:
 2- Phase 1: 功能設計完成
 3- Phase 2: 測試設計完成（測試檔案存在）
 4- Phase 3: 實作完成（程式碼檔案）
 5- Phase 4: 重構評估完成
 6
 7Incomplete Ticket 特徵:
 8- 缺少測試檔案（Phase 2 未完成）
 9- 缺少驗收條件（Phase 1 設計不完整）
10- 缺少工作日誌（無法追蹤進度）

 1步驟 1: 檢查 git diff 中的檔案
 2  ├─ 是否包含 test/ 目錄的檔案？
 3  └─ 測試檔案數量 vs 程式碼檔案數量比例
 4
 5步驟 2: 檢查 Ticket 描述
 6  └─ 是否包含「驗收條件」章節？
 7
 8步驟 3: 檢查工作日誌
 9  ├─ docs/work-logs/vX.Y.Z-*.md 是否存在？
10  └─ 是否完成 Phase 1-4 記錄？

1職責明確 Ticket 格式:
2標題: [Layer X] 清楚的功能描述
3描述: 明確說明修改哪一層的哪個檔案
4驗收: 只驗證該層級的職責
5
6職責模糊 Ticket 特徵:
7標題: 沒有 [Layer X] 標示
8描述: 混合多個層級的職責
9驗證: 跨多個層級的驗證

 1反例 職責模糊 Ticket:
 2標題: 實作書籍詳情頁面
 3描述: 實作書籍詳情頁面的所有功能
 4驗收: 可以顯示書籍詳情
 5
 6問題分析:
 7- 無層級標示
 8- 「所有功能」範圍不明確
 9- 驗收條件過於籠統
10
11正例 職責明確 Ticket:
12標題: [Layer 2] 實作書籍詳情頁面事件處理
13描述: 實作 BookDetailController 的事件處理方法，
14      整合 GetBookDetailUseCase 並轉換為 ViewModel
15驗收:
16  - BookDetailController.loadBookDetail() 呼叫 UseCase
17  - BookPresenter.toViewModel() 正確轉換資料
18  - 錯誤處理正確顯示錯誤訊息
19
20改善效果:
21- 層級明確（Layer 2）
22- 職責清楚（事件處理 + 資料轉換）
23- 驗收條件可驗證

 1Ticket 設計（Phase 1）
 2  ↓
 3檢查 Ticket 粒度（C1, C3, A1）
 4  ├─ 通過 → 測試設計（Phase 2）
 5  └─ 失敗 → 拆分 Ticket
 6
 7測試設計（Phase 2）
 8  ↓
 9檢查測試範圍（C2）
10  ├─ 通過 → 實作執行（Phase 3）
11  └─ 失敗 → 補充測試
12
13實作執行（Phase 3）
14  ↓
15檢查程式碼品質（A2, A3, A4, B2, B3）
16  ├─ 通過 → Code Review
17  └─ 失敗 → 修正程式碼
18
19Code Review
20  ↓
21全面檢查所有 Code Smell
22  ├─ 通過 → 合併 PR
23  └─ 失敗 → 重構
24
25Phase 4 重構評估
26  ↓
27識別需要重構的 Code Smell（B1, B2, B3, B4）
28  ├─ 有需要 → 執行重構
29  └─ 無需要 → 完成

 1良好 Ticket（單層修改）:
 2- 檔案數: 1-5 個
 3- 層級跨度: 1 層
 4- 依賴鏈: 不需要修改
 5
 6需要注意（考慮拆分）:
 7- 檔案數: 6-10 個
 8- 層級跨度: 2 層
 9- 依賴鏈: 需要修改 1-2 層
10
11Shotgun Surgery（散彈槍手術）:
12- 檔案數: > 10 個
13- 層級跨度: > 2 層
14- 依賴鏈: 需要同步修改多層

 1步驟 1: 列出 Ticket 涉及的所有檔案
 2步驟 2: 使用[層級隔離派工方法論](/record/layered-ticket-methodology/) 第 2.4 節的決策樹判斷每個檔案屬於哪一層
 3步驟 3: 統計跨幾個層級
 4  ├─ 1 層級 → 良好設計
 5  ├─ 2 層級 → 需要檢查是否可拆分
 6  └─ > 2 層級 → Shotgun Surgery
 7
 8步驟 4: 如果檢測到 Shotgun Surgery
 9  ├─ 檢查是否為特殊場景（架構遷移、Hotfix）
10  ├─ 分析是否可以拆分為多個 Ticket
11  └─ 評估架構設計是否有問題（引入 Adapter/Facade）

 1良好設計:
 2- UI 依賴 ViewModel，不依賴 Domain Entity
 3- Controller 包含 Presenter 轉換邏輯
 4- 透過介面依賴，不依賴具體實作
 5
 6Feature Envy:
 7- UI 直接依賴 Domain Entity
 8- 直接存取 Entity 的內部欄位（如 book.isbn.value）
 9- 缺少 ViewModel 或 Presenter 轉換層
10- 欄位存取次數 > 3 次

 1步驟 1: 檢查 UI Widget 的依賴
 2  ├─ 是否直接依賴 Domain Entity？
 3  └─ 是否透過 ViewModel？
 4
 5步驟 2: 檢查 Controller 是否包含 Presenter
 6  ├─ 是否有 toViewModel() 轉換方法？
 7  └─ 是否直接將 Entity 傳給 UI？
 8
 9步驟 3: 統計內層欄位存取次數
10  ├─ 存取 Entity 內部欄位（如 .value）> 3 次 → Feature Envy
11  └─ 透過 ViewModel 存取 → 良好設計

1正確依賴方向（外層→內層）:
2Layer 1 → Layer 2 → Layer 3 → Layer 4 ← Layer 5
3
4違反依賴方向（Inappropriate Intimacy）:
5- Layer 5 → Layer 3（Domain 依賴 UseCase）
6- Layer 5 → Layer 2（Domain 依賴 Controller）
7- Layer 3 ← → Layer 5（循環依賴）

 1步驟 1: 檢查 Domain Entity 的 import 語句
 2  ├─ 是否 import UseCase？ →
 3  ├─ 是否 import Controller？ →
 4  └─ 只 import 同層或 Layer 4 介面？ →
 5
 6步驟 2: 檢查 UseCase 的依賴
 7  ├─ 是否依賴 Layer 4 介面？ →
 8  └─ 是否依賴 Layer 5 具體類別？ →（應透過介面）
 9
10步驟 3: 使用工具檢測循環依賴
11  └─ dart analyze 會報告循環依賴錯誤

1良好抽象介面:
2- 方法名稱描述「做什麼」，不描述「怎麼做」
3- 參數是 Domain 概念，不是技術細節
4- 不包含資料庫、網路等實作關鍵字
5
6Leaky Abstraction:
7- 介面包含 SQL、HTTP、Cache 等關鍵字
8- 參數包含資料庫特定類型（如 Cursor）
9- 回傳類型包含框架特定類型（如 HttpResponse）

 1步驟 1: 檢查 Repository 介面定義
 2  ├─ 方法名稱是否包含實作關鍵字？
 3  │  - findBySql() → 洩漏 SQL
 4  │  - findById() → 抽象概念
 5  │
 6  └─ 參數類型是否為 Domain 類型？
 7     - String sql → 技術細節
 8     - String id → Domain 概念
 9
10步驟 2: 檢查 Event 定義
11  └─ 是否包含 UI 特定資料（如 BuildContext）？ →

1單一職責類別:
2- 只有 1 個變更原因
3- 類別職責可以用一句話描述
4- 所有方法圍繞同一個核心概念
5
6Divergent Change:
7- > 2 個變更原因（如「列表變更」和「詳情變更」）
8- 方法可以分為 2+ 個明確的群組
9- 類別名稱過於籠統（如 BookController、BookService）

 1步驟 1: 分析類別的 public 方法
 2  └─ 將方法按職責分組
 3
 4步驟 2: 統計分組數量
 5  ├─ 1 組 → 單一職責
 6  ├─ 2 組 → 考慮拆分
 7  └─ > 2 組 → Divergent Change
 8
 9步驟 3: 檢查歷史修改記錄
10  └─ git log --oneline {file}
11  └─ 分析修改原因是否多樣化

 1良好大小類別:
 2- 總行數: < 200 行
 3- public 方法: < 10 個
 4- 屬性: < 8 個
 5
 6需要注意（考慮拆分）:
 7- 總行數: 200-300 行
 8- public 方法: 10-15 個
 9- 屬性: 8-12 個
10
11Large Class:
12- 總行數: > 300 行
13- public 方法: > 15 個
14- 屬性: > 12 個

1# 檢測單一檔案行數
2wc -l lib/presentation/controllers/book_controller.dart
3
4# 檢測所有 Controller 檔案大小
5find lib -name "*_controller.dart" -exec wc -l {} \; | sort -rn
6
7# 使用 dart analyze 檢測複雜度
8# （需要配置 analysis_options.yaml）

 1良好方法:
 2- 行數: < 30 行
 3- 巢狀層級: < 3 層
 4- 邏輯區塊: < 3 個
 5
 6需要注意:
 7- 行數: 30-50 行
 8- 巢狀層級: 3 層
 9- 邏輯區塊: 3-4 個
10
11Long Method:
12- 行數: > 50 行
13- 巢狀層級: > 3 層
14- 邏輯區塊: > 4 個

 1步驟 1: 統計方法行數
 2  └─ 從方法簽名到結束大括號的行數
 3
 4步驟 2: 分析巢狀層級
 5  └─ 統計最深的 if/for/while 巢狀深度
 6
 7步驟 3: 識別邏輯區塊
 8  └─ 統計註解數量（通常用來分隔邏輯區塊）
 9  └─ > 3 個註解區塊 → 應該拆分方法
10
11步驟 4: 檢查方法命名
12  └─ 方法名稱是否包含「And」？ → 可能做太多事情
13     - validateAndSaveBook() → 應拆分為 validate() 和 save()

 1# 檢測 unused 警告
 2dart analyze | grep "unused"
 3
 4# 檢測程式碼覆蓋率
 5flutter test --coverage
 6genhtml coverage/lcov.info -o coverage/html
 7# 檢查 coverage/html 中 0% 覆蓋率的程式碼
 8
 9# 搜尋註解掉的程式碼
10grep -r "^[[:space:]]*//.*{" lib/

 1良好 Ticket 粒度:
 2- 檔案數: 1-5 個
 3- 層級跨度: 1 層
 4- 預估工時: 2-8 小時（1 個工作天內）
 5
 6需要拆分:
 7- 檔案數: 6-10 個
 8- 層級跨度: 2 層
 9- 預估工時: 8-16 小時（1-2 天）
10
11God Ticket:
12- 檔案數: > 10 個
13- 層級跨度: > 2 層
14- 預估工時: > 16 小時（> 2 天）

 1步驟 1: 列出 Ticket 需要修改的檔案清單
 2步驟 2: 統計檔案數量
 3步驟 3: 使用[層級隔離派工方法論](/record/layered-ticket-methodology/) 第 2.4 節決策樹判斷每個檔案的層級
 4步驟 4: 計算層級跨度
 5步驟 5: 評估預估工時
 6
 7判斷:
 8  ├─ 符合良好標準 → 可執行
 9  ├─ 符合需要拆分標準 → 建議拆分
10  └─ 符合 God Ticket 標準 → 強制拆分

 1完整 Ticket:
 2- Phase 1: 功能設計完成
 3- Phase 2: 測試設計完成（測試檔案存在）
 4- Phase 3: 實作完成（程式碼檔案）
 5- Phase 4: 重構評估完成
 6
 7Incomplete Ticket:
 8- 缺少測試檔案（Phase 2 未完成）
 9- 缺少驗收條件（Phase 1 設計不完整）
10- 缺少工作日誌（無法追蹤進度）

 1步驟 1: 檢查 git diff 中的檔案
 2  ├─ 是否包含 test/ 目錄的檔案？
 3  └─ 測試檔案數量 vs 程式碼檔案數量比例
 4
 5步驟 2: 檢查 Ticket 描述
 6  └─ 是否包含「驗收條件」章節？
 7
 8步驟 3: 檢查工作日誌
 9  ├─ docs/work-logs/vX.Y.Z-*.md 是否存在？
10  └─ 是否完成 Phase 1-4 記錄？

1職責明確 Ticket:
2- 標題: [Layer X] 清楚的功能描述
3- 描述: 明確說明修改哪一層的哪個檔案
4- 驗收: 只驗證該層級的職責
5
6職責模糊 Ticket:
7- 標題: 沒有 [Layer X] 標示
8- 描述: 混合多個層級的職責
9- 驗收: 跨多個層級的驗證

 1步驟 1: 檢查 Ticket 標題格式
 2  ├─ 符合 [Layer X] 格式？ →
 3  └─ 無層級標示？ →
 4
 5步驟 2: 分析 Ticket 描述
 6  └─ 能否用一句話描述單一層級的職責？
 7
 8步驟 3: 檢查驗收條件
 9  ├─ 所有驗收條件都屬於同一層級？ →
10  └─ 驗收條件跨多層？ →

 1步驟 1: 分析變更的共同點
 2  └─ 識別哪些變更是因為相同的業務需求
 3
 4步驟 2: 引入 Facade 層
 5  └─ 建立統一的介面封裝跨層操作
 6
 7步驟 3: 重構為單層修改
 8  ├─ Layer 4: 定義 Facade 介面
 9  ├─ Layer 3: 實作 Facade
10  └─ Layer 2: 呼叫 Facade
11
12步驟 4: 驗證重構結果
13  └─ 未來相同變更只需要修改 Facade 實作

 1// 反例：Before: 新增欄位需要修改 4 層
 2// Layer 1: UI 新增 Widget
 3// Layer 2: Controller 新增屬性
 4// Layer 3: UseCase 新增參數
 5// Layer 5: Entity 新增欄位
 6
 7// 正例：After: 引入 BookDetailFacade
 8
 9// Layer 4: 定義介面
10abstract class IBookDetailFacade {
11  Future<BookDetailViewModel> getBookDetail(String id);
12}
13
14// Layer 3: 實作 Facade（統一處理資料整合）
15class BookDetailFacade implements IBookDetailFacade {
16  final IBookRepository bookRepository;
17  final IRatingRepository ratingRepository;
18
19  Future<BookDetailViewModel> getBookDetail(String id) async {
20    final book = await bookRepository.findById(id);
21    final rating = await ratingRepository.findByBookId(id);
22    return BookPresenter.toViewModel(book, rating);
23  }
24}
25
26// 重構效果:
27// 未來新增欄位只需要修改 Facade 實作（Layer 3）
28// Layer 1, 2, 5 都不需要修改

 1步驟 1: 識別 Feature Envy 位置
 2  └─ 外層存取內層內部欄位 > 3 次
 3
 4步驟 2: 引入 ViewModel
 5  └─ Layer 2 建立 ViewModel 類別
 6
 7步驟 3: 建立 Presenter 轉換方法
 8  └─ Layer 2 實作 toViewModel(Entity) → ViewModel
 9
10步驟 4: 重構 UI 依賴
11  └─ UI 改為依賴 ViewModel，不依賴 Entity

 1步驟 1: 分析方法分組
 2  └─ 將 public 方法按職責分組
 3
 4步驟 2: 為每個分組建立新類別
 5  └─ 拆分為 BookListController, BookDetailController, BookSearchController
 6
 7步驟 3: 移動方法到新類別
 8  └─ Move Method 重構
 9
10步驟 4: 更新依賴關係
11  └─ 更新 Widget 的依賴

 1步驟 1: 識別邏輯區塊
 2  └─ 統計註解數量（每個註解代表一個邏輯區塊）
 3
 4步驟 2: 為每個區塊建立私有方法
 5  └─ Extract Method 重構
 6
 7步驟 3: 重新命名方法
 8  └─ 使用動詞片語描述方法功能
 9
10步驟 4: 驗證重構結果
11  └─ 主方法 < 30 行
12  └─ 每個私有方法 < 20 行

 1優先級分數 = (影響範圍 × 3) + (業務風險 × 2) + (累積速度 × 1)
 2
 3影響範圍評分:
 4
 51 分: 單一檔案
 62 分: 2-3 個檔案
 73 分: 4-5 個檔案（單層）
 84 分: 6-10 個檔案（跨 2 層）
 95 分: > 10 個檔案（跨 3+ 層）
10
11業務風險評分:
12
131 分: 輔助功能（UI 優化）
142 分: 次要功能（搜尋）
153 分: 常用功能（列表顯示）
164 分: 重要功能（新增書籍）
175 分: 核心功能（資料同步）
18
19累積速度評分:
20
211 分: 已穩定，不再惡化
222 分: 偶爾新增（每季 1 次）
233 分: 定期新增（每月 1-2 次）
244 分: 頻繁新增（每週 1 次）
255 分: 持續惡化（每天都在新增）
26
27優先級判斷:
28分數 > 20 → 高優先級（立即修正）
29分數 10-20 → 中優先級（排入下個版本）
30分數 < 10 → 低優先級（重構階段處理）

 1步驟 1: 建立 feature branch
 2  └─ git checkout -b refactor/fix-shotgun-surgery
 3
 4步驟 2: 確保測試 100% 通過
 5  └─ flutter test（重構前基準）
 6
 7步驟 3: 執行重構
 8  └─ 每完成一個小步驟都執行測試
 9
10步驟 4: 提交重構結果
11  └─ git commit -m "refactor: extract BookDetailFacade"
12
13步驟 5: Code Review
14  └─ 確保重構符合層級隔離原則
15
16步驟 6: 合併到主線
17  └─ git merge --no-ff refactor/fix-shotgun-surgery

1# 重構前
2flutter test --coverage
3# 記錄覆蓋率基準（如 85%）
4
5# 重構後
6flutter test --coverage
7# 確保覆蓋率不降低（≥ 85%）

 1// 反例：違規
 2class BookDetailWidget {
 3  Widget build(BuildContext context) {
 4    // 反例：業務規則不應在 UI 層
 5    if (book.publicationDate.year >= 2024) {
 6      return Text('新書');
 7    }
 8
 9    // 反例：業務計算不應在 UI 層
10    final discountedPrice = book.price * 0.9;
11    return Text('優惠價: $discountedPrice');
12  }
13}
14
15// 正例：業務邏輯在 Domain 層
16class Book {
17  bool isNewRelease() {
18    return publicationDate.year >= 2024;
19  }
20
21  double getDiscountedPrice() {
22    return price * 0.9;
23  }
24}
25
26// 正例：UI 使用 ViewModel
27class BookDetailWidget {
28  Widget build(BuildContext context) {
29    return Column(
30      children: [
31        if (viewModel.isNew) Text('新書'),
32        Text('優惠價: ${viewModel.discountedPrice}'),
33      ],
34    );
35  }
36}

 1// 反例：違規
 2class BookController {
 3  void validateBook(Book book) {
 4    // 反例：業務規則應在 Domain 層
 5    if (book.isbn.length != 13) {
 6      throw ValidationException('ISBN 必須是 13 碼');
 7    }
 8  }
 9}
10
11// 正例：業務規則在 Domain 層
12class ISBN {
13  final String value;
14
15  ISBN(this.value) {
16    if (value.length != 13) {
17      throw ValidationException('ISBN 必須是 13 碼');
18    }
19  }
20}

 1// 反例：違規
 2class GetBookDetailUseCase {
 3  Future<String> execute(String id) async {
 4    final book = await repository.findById(id);
 5    // 反例：UI 格式化不應在 UseCase
 6    return '書名: ${book.title}';
 7  }
 8}
 9
10// 正例：UseCase 回傳 Domain 類型
11class GetBookDetailUseCase {
12  Future<Book> execute(String id) async {
13    return await repository.findById(id);
14  }
15}
16
17// 正例：Presenter 負責轉換
18class BookPresenter {
19  static BookViewModel toViewModel(Book book) {
20    return BookViewModel(
21      displayText: '書名: ${book.title.value}',
22    );
23  }
24}

 1# Code Smell 檢測報告
 2
 3**檢測時間**: 2025-10-11 14:30
 4**檢測範圍**: PR #123 - [Layer 2] 實作書籍詳情頁面事件處理
 5**Reviewer**: @reviewer-name
 6
 7---
 8
 9## 檢測總結
10- **高優先級問題**: 1 個
11- **中優先級問題**: 1 個
12- **低優先級問題**: 0 個
13- **總體評估**: 需要修正後再合併
14
15---
16
17## 高優先級問題
18### Shotgun Surgery 檢測結果
19**檔案清單**:
20- lib/presentation/widgets/book_detail_widget.dart (Layer 1)
21- lib/presentation/controllers/book_detail_controller.dart (Layer 2)
22- lib/application/use_cases/get_book_detail_use_case.dart (Layer 3)
23- lib/domain/entities/book.dart (Layer 5)
24
25**分析**:
26- 檔案數: 4 個
27- 層級跨度: 4 層（Layer 1, 2, 3, 5）
28- 判斷: Shotgun Surgery
29
30**建議**:
31- 拆分為 4 個獨立 Ticket
32- 每個 Ticket 只修改單一層級
33- 引入 Facade 隔離變更
34
35**影響評估**:
36- 影響範圍: 5 分（跨 4 層）
37- 業務風險: 4 分（重要功能）
38- 累積速度: 2 分（偶爾新增）
39- 優先級分數: 25（高優先級）
40
41---
42
43## 中優先級問題
44### 警告 Large Class 檢測結果
45
46**檔案**: `lib/presentation/controllers/book_controller.dart`
47
48**分析**:
49- 總行數: 320 行（超過 300 行標準）
50- public 方法: 18 個（超過 15 個標準）
51- 方法分組: 3 組（列表、詳情、搜尋）
52
53**建議**:
54- Extract Class 重構
55- 拆分為 BookListController、BookDetailController、BookSearchController
56
57**影響評估**:
58- 影響範圍: 2 分（2-3 個檔案）
59- 業務風險: 3 分（常用功能）
60- 累積速度: 4 分（頻繁新增）
61- 優先級分數: 16（中優先級）
62
63---
64
65## 無檢測到的 Code Smell
66- Long Method
67- Dead Code
68- Feature Envy
69- Inappropriate Intimacy
70- Leaky Abstraction
71
72---
73
74## 測試覆蓋率
75- **覆蓋率**: 98%
76- **未覆蓋檔案**: `book_controller.dart` line 285-290
77- **建議**: 補充測試覆蓋未測試部分
78
79---
80
81## 總體建議
821. **立即處理**: Shotgun Surgery（高優先級）
83   - 拆分 PR 為 4 個獨立 Ticket
84   - 每個 Ticket 遵循單層修改原則
85
862. **下個版本處理**: Large Class（中優先級）
87   - 建立 Refactoring Ticket
88   - 執行 Extract Class 重構
89
903. **補充測試**: 測試覆蓋率不足部分
91   - 補充 line 285-290 測試
92
93---
94
95**審查結論**: 建議重構後再合併 PR
96**預估修正時間**: 4 小時