Kiến trúc hệ thống & Design Patterns

Để xây dựng một hệ thống vừa có khả năng điều khiển trình duyệt (Browser Automation) vừa tích hợp AI, chúng ta cần một kiến trúc lỏng lẻo (loosely coupled) để dễ dàng thay thế các thành phần.

1. High-Level Architecture

Hệ thống hoạt động theo mô hình Pipeline tuần tự 7 giai đoạn:

graph TD
    User((User)) -->|Input| CLI[guide_ai.py]
    CLI -->|Config| Orch{Orchestrator}
    
    subgraph "Stage 1: Record"
        Orch -->|Call| Rec[Recorder]
        Rec -->|Generate| Script[recorded_script.py]
    end

    subgraph "Stage 2: Parse"
        Orch -->|Read| Parser[Parser]
        Parser -->|Extract| Actions[List[Action]]
    end
    
    subgraph "Stage 5: Replay"
        Orch -->|Execute| Replayer[Replayer]
        Replayer -->|Capture| Screens[Screenshots]
    end

    subgraph "Stage 6: Analyze"
        Orch -->|Process| Analyzer[Analyzer]
        Analyzer -->|Call| AI((Gemini/OpenAI))
        AI -->|Desc| Steps[List[Step]]
    end

    subgraph "Stage 7: Document"
        Orch -->|Format| DocGen[Doc Generator]
        DocGen -->|Save| Output[guide.md / guide.html]
    end

2. Các thành phần chính (Components)

2.1. Orchestrator (src/orchestrator.py)

• Vai trò: Nhạc trưởng điều phối toàn bộ luồng công việc.
• Nhiệm vụ: Kết nối các module rời rạc (Recorder, Parser, Replayer, Analyzer, DocGenerator) thành một quy trình hoàn chỉnh.
• Workflow: Record -> Parse -> Init AI -> Upload Config -> Replay -> Analyze -> Generate.

2.2. Recorder (src/recorder.py)

• Vai trò: Ghi lại thao tác người dùng.
• Công nghệ: Sử dụng playwright codegen thông qua subprocess.
• Output: File recorded_script.py chứa code Python thô của Playwright.

2.3. Parser (src/parser.py)

• Vai trò: Đọc hiểu script đã ghi.
• Nhiệm vụ: Phân tích file recorded_script.py để trích xuất danh sách các hành động (Action) như click, fill, goto...
• Logic: Sử dụng Regex hoặc AST để parse code.

2.4. Replayer (src/replayer.py)

• Vai trò: Thực thi lại và chụp ảnh.
• Nhiệm vụ: Chạy lại các Action đã parse trên trình duyệt thật và chụp ảnh màn hình (Screenshot) tại mỗi bước.
• Tính năng: Hỗ trợ upload ảnh lên server (thông qua src/uploader.py) nếu được cấu hình.

2.5. Analyzer (src/analyzer.py)

• Vai trò: Bộ não AI.
• Nhiệm vụ: Gửi ảnh chụp màn hình đến Google Gemini hoặc OpenAI để sinh mô tả văn bản.
• Fallback: Nếu không dùng AI hoặc AI lỗi, nó sẽ dùng get_action_hint để tạo mô tả dựa trên code (ví dụ: "Click [Login]").

2.6. Doc Generator (src/doc_generator.py)

• Vai trò: Trình bày kết quả.
• Nhiệm vụ: Tổng hợp danh sách Step thành file Markdown và HTML đẹp mắt.

3. Luồng dữ liệu (Data Flow)

1. Recording: User thao tác -> recorded_script.py.
2. Parsing: recorded_script.py -> List[Action].
3. Replaying: List[Action] -> List[Screenshot] (Local path hoặc Remote URL).
4. Analyzing: List[Screenshot] -> List[Step] (kèm Description).
5. Generating: List[Step] -> guide.md, guide.html.

4. Tại sao chọn kiến trúc này?

Ưu điểm

• Separation of Concerns: Mỗi module chỉ làm một việc duy nhất. Analyzer không cần biết về Playwright, Recorder không cần biết về AI.
• Resilience: Nếu AI bị lỗi, hệ thống vẫn hoạt động nhờ cơ chế Fallback của Analyzer.
• Flexibility: Có thể thay đổi AI Provider (trong Analyzer) hoặc cách lưu file (trong Uploader) mà không ảnh hưởng luồng chính.

Nhược điểm

• Latency: Quy trình Replay tốn thời gian vì phải chạy lại trình duyệt thật.
• Complexity: Việc parse code Python (Parser) có thể phức tạp nếu script chứa logic lạ.

5. Thư mục dự án thực tế

automation-guide/
├── guide_ai.py              # Entry Point (CLI + Interactive)
├── src/
│   ├── orchestrator.py      # Core Logic - điều phối workflow
│   ├── recorder.py          # Playwright Codegen Wrapper
│   ├── parser.py            # Code Parser + Action Hint
│   ├── replayer.py          # Action Executor + Screenshot
│   ├── analyzer.py          # AI Integration (Gemini/OpenAI)
│   │                        # - Auto-detect models
│   │                        # - Fallback mechanism
│   │                        # - Prompt engineering
│   ├── doc_generator.py     # Markdown/HTML Builder (Jinja2)
│   ├── uploader.py          # Image Upload Service
│   ├── config_manager.py    # Env & API Key Management
│   └── models.py            # Data Classes (Action, Screenshot, Step)
├── output/                  # Generated guides (gitignored)
│   └── {hostname}/
│       └── {guide_name}/
│           ├── recorded_script.py
│           ├── guide.md
│           ├── guide.html
│           └── images/
├── build_exe.bat            # Build portable EXE
└── .env                     # API Keys (gitignored)

6. Đánh giá kiến trúc

Ưu điểm

Tiêu chí	Đánh giá
Separation of Concerns	⭐⭐⭐⭐⭐ Mỗi module 1 nhiệm vụ
Testability	⭐⭐⭐⭐ Dễ mock từng module
Extensibility	⭐⭐⭐⭐ Dễ thêm AI provider mới
Resilience	⭐⭐⭐⭐⭐ Fallback 3 tầng

Nhược điểm

Tiêu chí	Vấn đề
Coupling	Parser phụ thuộc vào format của Playwright codegen
State Management	Global variables trong analyzer.py
Error Handling	Một số exception chưa được handle cụ thể