# Pattern [Tên Pattern]

> **Mô tả**: Mô tả ngắn gọn về khi nào và tại sao sử dụng pattern này

## Tổng quan Pattern

```mermaid
graph LR
    Input[Đầu vào/Yêu cầu] --> Process[Xử lý Pattern]
    Process --> Output[Đầu ra/Kết quả]
    
    subgraph Pattern["Triển khai Pattern"]
        Process --> Step1[Bước 1]
        Step1 --> Step2[Bước 2]
        Step2 --> Step3[Bước 3]
    end
    
    style Input fill:#e1f5ff
    style Output fill:#d4edda
    style Pattern fill:#f0e1ff
```

## Khi nào sử dụng

Sử dụng pattern này khi:
- Tình huống 1: Mô tả khi pattern này có lợi
- Tình huống 2: Trường hợp sử dụng khác
- Tình huống 3: Bối cảnh bổ sung

**NÊN sử dụng pattern này cho**:
- ✅ Trường hợp 1
- ✅ Trường hợp 2

**KHÔNG NÊN sử dụng pattern này cho**:
- ❌ Anti-pattern 1
- ❌ Anti-pattern 2

## Khái niệm Cốt lõi

### Nguyên tắc Chính

1. **Nguyên tắc 1**: Mô tả nguyên tắc cốt lõi đầu tiên
2. **Nguyên tắc 2**: Mô tả nguyên tắc cốt lõi thứ hai
3. **Nguyên tắc 3**: Mô tả nguyên tắc cốt lõi thứ ba

## Triển khai

### Triển khai Cơ bản

Giải thích từng bước về cách triển khai pattern này.

```typescript
// Ví dụ triển khai cơ bản

/**
 * Class triển khai pattern
 */
export class ExamplePattern {
  /**
   * Constructor với các dependencies
   */
  constructor(
    private dependency1: Dependency1,
    private dependency2: Dependency2
  ) {}

  /**
   * Phương thức cốt lõi triển khai pattern
   * 
   * @param input - Dữ liệu đầu vào
   * @returns Kết quả đã xử lý
   */
  async execute(input: InputType): Promise<OutputType> {
    // Bước 1: Validate đầu vào
    this.validateInput(input);

    // Bước 2: Xử lý
    const processed = await this.process(input);

    // Bước 3: Trả về kết quả
    return this.formatOutput(processed);
  }

  private validateInput(input: InputType): void {
    // Logic validation
    if (!input) {
      throw new Error('Đầu vào là bắt buộc');
    }
  }

  private async process(input: InputType): Promise<ProcessedType> {
    // Logic nghiệp vụ cốt lõi
    return await this.dependency1.transform(input);
  }

  private formatOutput(processed: ProcessedType): OutputType {
    // Định dạng cho đầu ra
    return {
      success: true,
      data: processed,
    };
  }
}
```

### Triển khai Nâng cao

Triển khai phức tạp hơn với các tính năng bổ sung.

```typescript
// Triển khai nâng cao với caching và xử lý lỗi

export class AdvancedExamplePattern extends ExamplePattern {
  constructor(
    dependency1: Dependency1,
    dependency2: Dependency2,
    private cache: CacheService,
    private logger: Logger
  ) {
    super(dependency1, dependency2);
  }

  async execute(input: InputType): Promise<OutputType> {
    // Thử cache trước
    const cacheKey = this.getCacheKey(input);
    const cached = await this.cache.get<OutputType>(cacheKey);
    
    if (cached) {
      this.logger.info('Cache hit', { key: cacheKey });
      return cached;
    }

    try {
      // Thực thi logic pattern
      const result = await super.execute(input);

      // Cache kết quả
      await this.cache.set(cacheKey, result, 300); // 5 phút

      return result;
    } catch (error) {
      // Xử lý lỗi
      this.logger.error('Thực thi pattern thất bại', { error, input });
      throw new PatternExecutionError('Thực thi thất bại', { cause: error });
    }
  }

  private getCacheKey(input: InputType): string {
    return `pattern:example:${JSON.stringify(input)}`;
  }
}
```

## Sơ đồ Pattern

### Cấu trúc Class

```mermaid
classDiagram
    class ExamplePattern {
        -dependency1: Dependency1
        -dependency2: Dependency2
        +execute(input: InputType): OutputType
        -validateInput(input: InputType): void
        -process(input: InputType): ProcessedType
        -formatOutput(processed: ProcessedType): OutputType
    }
    
    class AdvancedExamplePattern {
        -cache: CacheService
        -logger: Logger
        +execute(input: InputType): OutputType
        -getCacheKey(input: InputType): string
    }
    
    ExamplePattern <|-- AdvancedExamplePattern
```

### Luồng Tuần tự

```mermaid
sequenceDiagram
    participant Client as Khách hàng
    participant Pattern as ExamplePattern
    participant Dep1 as Dependency1
    participant Cache as CacheService
    
    Client->>Pattern: execute(input)
    Pattern->>Cache: get(cacheKey)
    Cache-->>Pattern: null (cache miss)
    Pattern->>Pattern: validateInput(input)
    Pattern->>Dep1: transform(input)
    Dep1-->>Pattern: processed
    Pattern->>Pattern: formatOutput(processed)
    Pattern->>Cache: set(cacheKey, result, ttl)
    Cache-->>Pattern: void
    Pattern-->>Client: result
```

## Ví dụ Sử dụng

### Ví dụ 1: Sử dụng Cơ bản

Tình huống sử dụng cơ bản với giải thích.

```typescript
// Thiết lập
const dependency1 = new Dependency1();
const dependency2 = new Dependency2();
const pattern = new ExamplePattern(dependency1, dependency2);

// Thực thi pattern
const input: InputType = {
  id: '123',
  data: 'example',
};

const result = await pattern.execute(input);

console.log(result);
// Kết quả: { success: true, data: { ... } }
```

### Ví dụ 2: Sử dụng Nâng cao

Sử dụng nâng cao với caching được bật.

```typescript
// Thiết lập với các dependencies bổ sung
const cache = new CacheService();
const logger = new Logger();
const pattern = new AdvancedExamplePattern(
  dependency1,
  dependency2,
  cache,
  logger
);

// Lần gọi đầu tiên (cache miss)
const result1 = await pattern.execute(input);

// Lần gọi thứ hai (cache hit)
const result2 = await pattern.execute(input); // Trả về kết quả cached
```

## Best Practices

### Thực hành Được đề xuất

1. **Nguyên tắc 1**: Mô tả best practice với lý do
2. **Nguyên tắc 2**: Hướng dẫn quan trọng khác
3. **Nguyên tắc 3**: Khuyến nghị bổ sung

**Cấu hình**:
```typescript
const config = {
  timeout: 5000,
  retries: 3,
  cacheTime: 300, // 5 phút
};
```

## Lỗi Thường gặp

### Lỗi 1: [Mô tả]

```typescript
// ❌ KHÔNG TỐT: Triển khai không chính xác
const result = await pattern.execute(null); // Sẽ throw error
```

```typescript
// ✅ TỐT: Triển khai chính xác
if (input) {
  const result = await pattern.execute(input);
}
```

**Tại sao**: Giải thích tại sao cách tiếp cận đầu tiên là không tốt và cách thứ hai là tốt.

## Cân nhắc Hiệu suất

**Mô tả**: Đặc điểm hiệu suất và mẹo tối ưu hóa.

| Khía cạnh | Tác động | Giảm thiểu |
|-----------|----------|------------|
| Sử dụng RAM | Trung bình | Sử dụng caching có chiến lược |
| Sử dụng CPU | Thấp | N/A |
| Thao tác I/O | Cao | Triển khai connection pooling |

## Kiểm thử

```typescript
// Unit test cho pattern

describe('ExamplePattern', () => {
  let pattern: ExamplePattern;
  let mockDep1: jest.Mocked<Dependency1>;

  beforeEach(() => {
    mockDep1 = {
      transform: jest.fn(),
    } as any;

    pattern = new ExamplePattern(mockDep1, {} as any);
  });

  it('nên thực thi thành công', async () => {
    // Chuẩn bị
    const input = { id: '123', data: 'test' };
    const expectedProcessed = { transformed: true };
    mockDep1.transform.mockResolvedValue(expectedProcessed);

    // Thực thi
    const result = await pattern.execute(input);

    // Kiểm tra
    expect(result.success).toBe(true);
    expect(result.data).toEqual(expectedProcessed);
    expect(mockDep1.transform).toHaveBeenCalledWith(input);
  });

  it('nên throw error cho đầu vào không hợp lệ', async () => {
    // Mong đợi lỗi cho đầu vào null
    await expect(pattern.execute(null as any))
      .rejects
      .toThrow('Đầu vào là bắt buộc');
  });
});
```

## Patterns Liên quan

Các patterns khác bổ sung hoặc liên quan đến pattern này.

- [Pattern Liên quan 1](./related-pattern-1.md) - Cách nó liên quan
- [Pattern Liên quan 2](./related-pattern-2.md) - So sánh
- [Pattern Thay thế](./alternative-pattern.md) - Khi nào sử dụng thay thế

## Tài nguyên Bổ sung

### Tài liệu Liên quan

- [Hướng dẫn Thiết kế API](../api-design.md) - Pattern này khớp với thiết kế API như thế nào
- [Xử lý Lỗi](../error-handling-patterns.md) - Xử lý lỗi cho pattern này
- [Hướng dẫn Kiểm thử](../testing-patterns.md) - Chiến lược kiểm thử

---

**Cập nhật lần cuối**: YYYY-MM-DD  
**Độ phức tạp**: Beginner/Intermediate/Advanced  
**Danh mục**: [Tên Danh mục]  
**Tác giả**: Tên của bạn