name: data-analysis-backend
description: "Use when implementing or modifying data analysis backend features including endpoints, aggregations, dimensions, or formatters. Ensures Clean Architecture principles, three-layer separation (Endpoint-Service-Repository), and standardized 8-step pipeline workflow. Prevents common anti-patterns like SQL in domain layer or DB schema leakage."

Data Analysis Backend Development Guide

Overview

這個 skill 指導 Agent 遵循數據分析後端的架構設計原則。核心目標是建立一個高擴充性、低耦合、可預期流程的系統。

核心架構原則

三層架構 (Three-Layer Architecture)

Endpoint Layer (HTTP)
    ↓
Application Service Layer (Orchestration)
    ↓
Domain Layer (Business Logic)
    ↓
Infrastructure Layer (DB/SQL)

依賴反轉原則 (Dependency Inversion)
- Domain Layer 定義 contracts (interfaces)，不知道任何 DB schema
- Infrastructure Layer 實作這些 contracts，處理 SQL 和 DB 連接
- Service Layer 協調 Domain 和 Infrastructure，但不直接操作 DB

關鍵設計決策
1. Semantic → Physical 分離：Domain 用語意化的 DimensionSpec，QueryBuilder 轉換為實際 SQL
2. 標準化 Pipeline：所有 endpoint 遵循相同的 8-step 流程
3. 無狀態 Aggregation：Aggregation 是純粹的計算邏輯，不依賴特定 DB 結構
4. View-Only Formatter：Formatter 只做資料重組，不重新計算數值

The Standard 8-Step Pipeline

所有數據分析 endpoint 必須遵循此標準流程：

┌─────────────────────────────────────────────────────────────┐
│ 1. Validate Request                                         │
│    Layer: Endpoint                                          │
│    Input: HTTP Request                                      │
│    Output: Validated DTO                                    │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ 2. Build DimensionSpec                                      │
│    Layer: Endpoint → Service                                │
│    Input: DTO fields (e.g., groupBy, dateRange)             │
│    Output: DimensionSpec (semantic definition)              │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ 3. Resolve AggregationSpec                                  │
│    Layer: Service                                           │
│    Input: Aggregation name or type                          │
│    Output: AggregationSpec (with MetricContracts)           │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ 4. Build QueryPlan                                          │
│    Layer: Service → Infrastructure                          │
│    Input: DimensionSpec + AggregationSpec                   │
│    Output: LogicalQuery or SQL string                       │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ 5. Execute Query                                            │
│    Layer: Infrastructure                                    │
│    Input: SQL query                                         │
│    Output: Raw DB rows                                      │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ 6. Aggregate Result                                         │
│    Layer: Service                                           │
│    Input: Raw rows + AggregationSpec                        │
│    Output: Aggregated data (MetricContract values)          │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ 7. Format Visualization                                     │
│    Layer: Service → Endpoint                                │
│    Input: Aggregated data + Format type                     │
│    Output: Formatted response (chart config, table, etc.)   │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ 8. Return Response                                          │
│    Layer: Endpoint                                          │
│    Input: Formatted data                                    │
│    Output: HTTP Response (200 OK + JSON)                    │
└─────────────────────────────────────────────────────────────┘

Step-by-Step 職責說明

Step 1: Validate Request
- 檢查必要參數存在性
- 驗證日期範圍格式
- 驗證 groupBy 欄位合法性
- 回傳驗證錯誤 (400 Bad Request)

Step 2: Build DimensionSpec
- 將 HTTP 參數轉為語意化的 DimensionSpec
- 不包含任何 DB 欄位名稱
- 範例: { dimensions: ['channel', 'date'], timeGrain: 'day' }

Step 3: Resolve AggregationSpec
- 從 AggregationRegistry 取得對應的 Aggregation
- 包含需要計算的 MetricContracts
- 定義 compute 邏輯（純函數）

Step 4: Build QueryPlan
- QueryBuilder 將 DimensionSpec 轉為 LogicalQuery
- LogicalQuery 透過 DB Dialect 轉為實際 SQL
- 這是唯一知道 DB schema 的地方

Step 5: Execute Query
- Infrastructure Layer 執行 SQL
- 回傳原始 DB rows
- 處理連接池、錯誤重試

Step 6: Aggregate Result
- 使用 AggregationSpec 的 compute 函數
- 計算 MetricContract 定義的所有指標
- 輸出標準化的 aggregated data

Step 7: Format Visualization
- 根據 output format (chart/table/pivot) 重組資料
- 不做任何數值計算
- 範例: 將 flat array 轉為 nested hierarchy

Step 8: Return Response
- 包裝為 HTTP response
- 加上 metadata (total, page, etc.)
- 回傳 200 OK

Layer Responsibilities

✅ Endpoint Layer

該做的事
- ✅ Validate HTTP request
- ✅ Parse query parameters
- ✅ Build DimensionSpec from request
- ✅ Call Service methods
- ✅ Apply formatter
- ✅ Return HTTP response with status codes
- ✅ Handle endpoint-level errors (400, 404, 500)

不該做的事
- ❌ Business logic computation
- ❌ SQL query generation
- ❌ Direct DB access
- ❌ Data aggregation logic
- ❌ Metric calculation
- ❌ Join or filter logic

Checkpoint Questions
- 這個 endpoint handler 有超過 50 行嗎？（可能包含太多邏輯）
- 有看到 SQL 字串嗎？（應該在 Infrastructure）
- 有 for-loop 計算數值嗎？（應該在 Service/Domain）

✅ Application Service Layer

該做的事
- ✅ Orchestrate DimensionSpec + AggregationSpec
- ✅ Call QueryBuilder to build LogicalQuery
- ✅ Call Repository to execute query
- ✅ Aggregate raw results using AggregationSpec
- ✅ Coordinate multiple domain operations
- ✅ Transaction management (if needed)

不該做的事
- ❌ HTTP concerns (status codes, headers)
- ❌ SQL generation (delegate to QueryBuilder)
- ❌ Direct DB connection management
- ❌ Request validation (done in Endpoint)
- ❌ Visualization formatting (done in Formatter)

Checkpoint Questions
- Service 方法有處理 HTTP status code 嗎？（應該在 Endpoint）
- Service 直接使用 DB client 嗎？（應該透過 Repository）
- Service 包含 SQL template strings 嗎？（應該在 QueryBuilder）

✅ Domain Layer

該做的事
- ✅ Define DimensionSpec (semantic dimensions)
- ✅ Define AggregationSpec (metric contracts + compute logic)
- ✅ Define MetricContract (metric definitions)
- ✅ Define business rules (pure functions)
- ✅ Define interfaces for repositories
- ✅ Domain validation logic

不該做的事
- ❌ Know about DB schema (table names, column names)
- ❌ SQL query strings
- ❌ Join conditions
- ❌ DB-specific data types
- ❌ HTTP request/response structures
- ❌ Visualization formats

Checkpoint Questions
- DimensionSpec 包含 DB table 或 column 名稱嗎？（應該是語意化名稱）
- AggregationSpec 的 compute 函數有 SQL 嗎？（應該是純計算）
- Domain model 有 import DB client 嗎？（絕對禁止）

Critical Rule: Semantic Naming

// ❌ BAD: DB schema leakage
interface DimensionSpec {
  groupBy: ['user_channels.channel_name', 'DATE(created_at)']
}

// ✅ GOOD: Semantic naming
interface DimensionSpec {
  dimensions: ['channel', 'date'],
  timeGrain: 'day'
}

✅ Infrastructure Layer

該做的事
- ✅ Implement QueryBuilder (Semantic → SQL)
- ✅ Implement DB Dialect (LogicalQuery → SQL)
- ✅ DB connection management
- ✅ Execute SQL queries
- ✅ Map DB rows to domain objects
- ✅ Handle DB-specific errors

不該做的事
- ❌ Business logic (revenue calculation, conversion rate)
- ❌ Aggregation logic (should use AggregationSpec)
- ❌ Visualization transformation
- ❌ Request validation
- ❌ Define business rules

Checkpoint Questions
- QueryBuilder 包含 revenue 計算邏輯嗎？（應該在 AggregationSpec）
- Repository 做資料聚合運算嗎？（應該回傳 raw rows）
- Infrastructure 定義 business metrics 嗎？（應該在 Domain）

Development Workflows

Workflow 1: Adding a New Endpoint

檢查清單
- [ ] Step 1: Define route and handler in Endpoint Layer
- 範例: router.get('/api/analytics/revenue-by-channel', handler)
- [ ] Step 2: Implement request DTO validation
- 檢查 required fields: dateRange, groupBy, etc.
- [ ] Step 3: Build DimensionSpec from request
typescript const dimensionSpec: DimensionSpec = { dimensions: req.query.groupBy.split(','), timeGrain: req.query.timeGrain || 'day', dateRange: parseDateRange(req.query.dateRange) };
- [ ] Step 4: Resolve or create AggregationSpec
- 從 AggregationRegistry.get('revenue-by-channel') 取得
- 如果不存在，先走 Workflow 2 新增 Aggregation
- [ ] Step 5: Call Service with Specs
typescript const result = await analyticsService.aggregate(dimensionSpec, aggregationSpec);
- [ ] Step 6: Apply formatter (if needed)
typescript const formatted = chartFormatter.format(result, 'bar-chart');
- [ ] Step 7: Return HTTP response
typescript res.status(200).json({ data: formatted, metadata: { total: result.length } });
- [ ] Step 8: Add integration test
- 測試完整 request → response flow
- 驗證 response schema

參考範例: assets/templates/standard-endpoint.ts

Workflow 2: Adding a New Aggregation

檢查清單
- [ ] Step 1: Define AggregationSpec
typescript const revenueByChannelAgg: AggregationSpec = { name: 'revenue-by-channel', metrics: [/* MetricContracts */], compute: (rows) => { /* pure function */ } };
- [ ] Step 2: Define required MetricContracts
typescript const totalRevenueMetric: MetricContract = { name: 'total_revenue', type: 'currency', aggregation: 'sum', semanticField: 'transaction_amount' // NOT DB column name };
- [ ] Step 3: Implement compute formula (pure function)
- 輸入: raw DB rows
- 輸出: aggregated metrics
- 禁止: SQL, DB access, side effects
- [ ] Step 4: Register in AggregationRegistry
typescript AggregationRegistry.register(revenueByChannelAgg);
- [ ] Step 5: Test with multiple DimensionSpecs
- 測試不同 groupBy 組合
- 測試不同 time grains
- 確保 compute 邏輯通用
- [ ] Step 6: Add unit tests
- 測試 compute 函數的邊界條件
- Mock raw rows, 驗證輸出

參考範例: assets/examples/aggregation-spec.ts

Anti-Pattern 警告: 參考 assets/anti-patterns/sql-in-aggregation.ts

Workflow 3: Adding/Modifying Dimensions

檢查清單
- [ ] Step 1: Update DimensionSpec definition
typescript // 新增 'product_category' dimension type SupportedDimension = 'channel' | 'date' | 'product_category';
- [ ] Step 2: Update QueryBuilder dimension mapping
typescript // In QueryBuilder const dimensionMapping = { 'channel': 'user_channels.channel_name', 'date': 'DATE(orders.created_at)', 'product_category': 'products.category' // New mapping };
- [ ] Step 3: Update DB Dialect if needed
- 如果涉及新的 JOIN 或複雜轉換
- 範例: dimension 需要 window function
- [ ] Step 4: Test all existing Aggregations
- 確保 new dimension 不會破壞現有 aggregations
- 執行 regression tests
- [ ] Step 5: Update integration tests
- 測試新 dimension 的 groupBy 組合
- 測試 dimension + 各種 timeGrain

參考範例: assets/examples/dimension-spec.ts

Anti-Pattern 警告: 參考 assets/anti-patterns/db-fields-in-dimension.ts

Workflow 4: Adding/Modifying Output Formats

檢查清單
- [ ] Step 1: Define or update IVisualizationFormatter
typescript interface IChartFormatter { format(data: AggregatedData, chartType: string): ChartConfig; }
- [ ] Step 2: Implement format transformation
- 輸入: aggregated data (已計算完成的 metrics)
- 輸出: visualization-specific structure
- 禁止: 重新計算數值、filtering、aggregation
- [ ] Step 3: Ensure no re-computation
```typescript
// ✅ GOOD: Reorganize only
format(data) {
return data.map(row => ({ x: row.date, y: row.revenue }));
}

// ❌ BAD: Re-calculating
format(data) {
const total = data.reduce((sum, row) => sum + row.amount, 0); // NO!
return { total, items: data };
}
```
- [ ] Step 4: Test with multiple Aggregations
- 確保 formatter 通用，不綁定特定 aggregation
- 測試 edge cases (empty data, single row, etc.)
- [ ] Step 5: Update response schema
- 更新 API documentation
- 更新 TypeScript types

參考範例: assets/examples/logical-query.ts

Anti-Pattern 警告: 參考 assets/anti-patterns/formatter-computation.ts

Architecture Anti-Patterns

🚨 Anti-Pattern 1: SQL in Aggregation

問題描述
AggregationSpec 的 compute 函數包含 SQL query 或 DB-specific 邏輯。

為何有害
- 違反依賴反轉原則
- Aggregation 無法獨立測試
- 無法替換 DB 實作
- 破壞 Domain Layer 的純粹性

正確做法
- Aggregation compute 接收 raw rows，做純計算
- SQL 由 QueryBuilder 根據 MetricContract 生成
- Aggregation 不知道資料從哪來

範例: 參考 assets/anti-patterns/sql-in-aggregation.ts

🚨 Anti-Pattern 2: DB Schema in DimensionSpec

問題描述
DimensionSpec 包含 DB table names, column names, 或 JOIN conditions。

為何有害
- Domain Layer 耦合 Infrastructure
- 修改 DB schema 需要改 Domain code
- 無法抽換 data source
- 語意不清晰

正確做法
- DimensionSpec 使用語意化名稱 ('channel', 'date')
- QueryBuilder 負責 semantic → physical mapping
- DB schema 變更只影響 Infrastructure Layer

範例: 參考 assets/anti-patterns/db-fields-in-dimension.ts

🚨 Anti-Pattern 3: Computation in Formatter

問題描述
Formatter 重新計算 metrics、做 filtering、或執行 aggregation。

為何有害
- Duplication of logic
- Formatter 應該是 view layer，不該有 business logic
- 難以測試和維護
- 可能與 Aggregation 計算不一致

正確做法
- Formatter 只做資料重組和格式轉換
- 所有計算在 Aggregation Layer 完成
- Formatter 是 stateless, pure function

範例: 參考 assets/anti-patterns/formatter-computation.ts

🚨 Anti-Pattern 4: Divergent Endpoint Flow

問題描述
Endpoint 不遵循標準 8-step pipeline，直接呼叫 Repository 或包含 SQL。

為何有害
- 架構不一致，難以維護
- 繞過 Domain Layer 的 business rules
- 無法 reuse Aggregation logic
- Code duplication

正確做法
- 所有 endpoint 遵循相同 pipeline
- 透過 DimensionSpec + AggregationSpec 表達需求
- 讓 Service Layer 協調流程

範例: 參考 assets/anti-patterns/divergent-endpoint.ts

Quick Reference

核心抽象定義

DimensionSpec: 語意化的維度定義，不知道 DB schema

interface DimensionSpec {
  dimensions: string[];      // e.g., ['channel', 'date']
  timeGrain?: 'hour' | 'day' | 'week' | 'month';
  dateRange?: { start: Date; end: Date };
}

AggregationSpec: Metric contracts + 計算邏輯

interface AggregationSpec {
  name: string;
  metrics: MetricContract[];
  compute: (rows: any[]) => AggregatedData;
}

MetricContract: 單一指標的定義

interface MetricContract {
  name: string;
  type: 'number' | 'currency' | 'percentage';
  aggregation: 'sum' | 'avg' | 'count' | 'min' | 'max';
  semanticField: string;  // Semantic name, NOT DB column
}

LogicalQuery: 中間層 query representation

interface LogicalQuery {
  select: MetricContract[];
  groupBy: string[];  // Semantic dimension names
  where?: FilterCondition[];
  orderBy?: OrderByClause[];
}

依賴方向圖

┌─────────────────────────────────────────────────────────┐
│                    Endpoint Layer                       │
│                (HTTP Request/Response)                  │
└────────────────────┬────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────────────┐
│              Application Service Layer                  │
│         (Orchestration, DimensionSpec,                  │
│               AggregationSpec)                          │
└────────────────────┬────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────────────┐
│                  Domain Layer                           │
│        (Business Rules, Contracts, Specs)               │
│             [No DB knowledge]                           │
└────────────────────┬────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────────────┐
│             Infrastructure Layer                        │
│     (QueryBuilder, DB Dialect, Repository)              │
│      [Only layer that knows DB schema]                  │
└─────────────────────────────────────────────────────────┘

依賴規則
- Endpoint → Service → Domain → Infrastructure (單向)
- Domain 定義 interface，Infrastructure 實作
- Infrastructure 不能被 Domain import

常用檢查項目

Before committing code, check:
- [ ] 所有 endpoint 遵循 8-step pipeline
- [ ] DimensionSpec 無 DB column names
- [ ] AggregationSpec compute 無 SQL
- [ ] Formatter 無重新計算 metrics
- [ ] Domain Layer 無 import DB client
- [ ] 所有 semantic names 有對應的 QueryBuilder mapping

When reviewing PRs, look for:
- [ ] SQL strings in Domain or Service Layer
- [ ] DB schema knowledge in DimensionSpec
- [ ] Business logic in Endpoint handlers
- [ ] Aggregation logic in Formatters
- [ ] Direct DB access in Service Layer

Detailed References

需要更詳細的資訊時，參考以下文件:

• Domain Models 詳解: references/domain-models.md
• DimensionSpec 完整定義和使用範例
• AggregationSpec 設計原則
• MetricContract 類型系統

• LogicalQuery 結構說明

• Query Builder 指南: references/query-builder-guide.md

• Semantic → Physical 轉換機制
• DB Dialect 實作範例
• SQL 構建最佳實踐

• JOIN 和 subquery 處理

• Formatter 指南: references/formatter-guide.md

• Formatter 職責邊界
• Chart/Table/Pivot 格式轉換
• 通用格式定義
• Edge case 處理

Code Templates

完整程式碼範例:

• Standard Endpoint: assets/templates/standard-endpoint.ts
• DimensionSpec Example: assets/examples/dimension-spec.ts
• AggregationSpec Example: assets/examples/aggregation-spec.ts
• MetricContract Example: assets/examples/metric-contract.ts
• LogicalQuery Example: assets/examples/logical-query.ts

反面教材 (請勿模仿):
- assets/anti-patterns/sql-in-aggregation.ts
- assets/anti-patterns/db-fields-in-dimension.ts
- assets/anti-patterns/formatter-computation.ts
- assets/anti-patterns/divergent-endpoint.ts

Summary

遵循這個指南，確保:
1. ✅ 所有 endpoint 遵循標準 8-step pipeline
2. ✅ Domain Layer 保持純粹，不知道 DB schema
3. ✅ Infrastructure Layer 集中處理 SQL 生成
4. ✅ Aggregation 是可 reuse 的 pure functions
5. ✅ Formatter 只做 view transformation

當有疑問時，問自己:
- 這段 code 放在哪一層?
- 它有違反該層的職責嗎?
- 它有依賴不該依賴的東西嗎?

遵循這些原則，系統將保持高擴充性和可維護性。