1. Cuộc cách mạng “Prompt như Mã nguồn”

Khái niệm sử dụng một tệp Markdown, cụ thể là .github/copilot-instructions.md, làm nguồn bối cảnh tập trung và bền vững cho Copilot đang thay đổi cách các nhà phát triển tương tác với AI. Lợi ích chính của phương pháp này là nó biến các prompt trò chuyện phù du thành một tạo tác (artifact) bền vững, có thể kiểm soát phiên bản và tồn tại cùng với mã nguồn. Điều này mang lại nhiều lợi thế:

• Tính nhất quán: Mọi nhà phát triển trong nhóm, và mọi phiên trò chuyện mới, đều bắt đầu với cùng một bộ chỉ dẫn cơ bản, đảm bảo rằng sự hướng dẫn của AI là nhất quán trong toàn bộ dự án.
• Khả năng lặp lại: Các kết quả trở nên dễ dự đoán hơn vì bối cảnh cốt lõi không thay đổi.
• Khả năng chia sẻ: Bản thiết kế kiến trúc có thể được chia sẻ và cải tiến bởi toàn bộ nhóm, biến kiến thức của chuyên gia thành một tài sản có thể tái sử dụng.

Để kích hoạt hành vi này, các nhà phát triển cần định cấu hình IDE của họ. Ví dụ, trong Visual Studio Code, việc đặt cài đặt github.copilot.chat.codeGeneration.useInstructionFiles thành true sẽ chỉ thị cho Copilot tự động sử dụng tệp copilot-instructions.md cho mọi yêu cầu trò chuyện trong không gian làm việc đó.

2. Giải phẫu một Tệp Hướng dẫn

Một tệp copilot-instructions.md hiệu quả không phải là một tập hợp các ghi chú ngẫu nhiên. Nó là một tài liệu có cấu trúc cao, được thiết kế để cung cấp cho AI một cái nhìn toàn diện về dự án. Bảng dưới đây trình bày các thành phần thiết yếu của một tệp hướng dẫn, tổng hợp các phương pháp hay nhất từ nhiều nguồn khác nhau. Bảng này đóng vai trò như một mẫu có thể tái sử dụng để các nhà phát triển tạo ra các tệp hướng dẫn của riêng họ, hệ thống hóa các thực tiễn tốt nhất thành một danh sách kiểm tra duy nhất, có thể hành động.

3. Tài liệu có Mục đích Kép

Một tệp copilot-instructions.md được cấu trúc tốt không chỉ là một công cụ để hướng dẫn AI. Nó còn phục vụ một mục đích kép quan trọng: nó vừa là một đặc tả kỹ thuật có thể đọc được bằng máy cho AI, vừa là tài liệu kiến trúc có thể đọc được bởi con người.

Các thành phần được nêu trong bảng trên—Tổng quan Dự án, Ngăn xếp Công nghệ, API—là những thành phần giống hệt như trong một tệp README.md hoặc một tài liệu thiết kế kiến trúc tốt. Khi một nhà phát triển viết tệp này để hướng dẫn Copilot, họ đồng thời tạo ra tài liệu cấp cao. Một nhà phát triển mới tham gia dự án có thể đọc tệp duy nhất này để hiểu các mục tiêu, kiến trúc và ràng buộc của dự án, giúp quá trình giới thiệu (onboarding) nhanh hơn và hiệu quả hơn.

Điều này tạo ra một vòng lặp phản hồi tích cực: để có được kết quả tốt hơn từ AI, các nhà phát triển được khuyến khích tạo và duy trì tài liệu chất lượng cao. Tài liệu này trở thành một “tài liệu sống” vì tác động trực tiếp của nó đến hiệu quả phát triển đảm bảo rằng nó sẽ không bị lỗi thời. Phương pháp này có thể thu hẹp khoảng cách giữa mã nguồn và tài liệu, có khả năng dẫn đến các hệ thống phần mềm được tài liệu hóa tốt hơn và dễ bảo trì hơn, được thực thi bởi nhu cầu thực tế là phải hướng dẫn đối tác AI một cách hiệu quả.

Bài toán ví dụ: Xây dựng một module lấy dữ liệu báo cáo Yahoo DSP

4.1. Nhiệm vụ: Lấy Dữ liệu Hiệu suất Quảng cáo

Mục tiêu được xác định rõ ràng: “Chúng ta sẽ xây dựng một kịch bản Python có khả năng xác thực với API Yahoo DSP, yêu cầu một báo cáo hiệu suất cho một nhà quảng cáo nhất định, tải xuống báo cáo dưới dạng CSV và nạp nó vào một DataFrame của pandas để phân tích.”

4.2. Phần 1: Soạn thảo Bản thiết kế (copilot-instructions.md)

Bước đầu tiên là tạo ra bản thiết kế kiến trúc sẽ hướng dẫn Copilot trong suốt quá trình phát triển. Tệp copilot-instructions.md hoàn chỉnh cho dự án này được trình bày dưới đây. Nó được xây dựng bằng cách sử dụng mẫu từ Phần 2 và được điền đầy đủ các chi tiết cụ thể được tổng hợp từ tài liệu API của Yahoo.

Tổng quan Dự án

Dự án này là một công cụ dòng lệnh Python để lấy báo cáo hiệu suất quảng cáo hàng ngày từ API Yahoo DSP. Công cụ sẽ xác thực, yêu cầu một báo cáo tùy chỉnh, thăm dò cho đến khi báo cáo sẵn sàng, tải xuống và hiển thị dữ liệu bằng pandas.

Danh sách Tính năng

• Xác thực với API Yahoo DSP bằng luồng OAuth 2.0 Client Credentials với một JSON Web Token (JWT).
• Tạo và gửi một yêu cầu báo cáo không đồng bộ với các dimension và metric được chỉ định.
• Thăm dò điểm cuối API một cách định kỳ để kiểm tra trạng thái của yêu cầu báo cáo.
• Sau khi báo cáo thành công, tải xuống tệp CSV từ URL được cung cấp.
• Nạp dữ liệu CSV vào một DataFrame của pandas và hiển thị 5 hàng đầu tiên.
• Quản lý thông tin nhạy cảm (Client ID, Client Secret) bằng cách sử dụng các biến môi trường từ tệp .env.

Ngăn xếp Công nghệ

• Python 3.10+
• requests (phiên bản 2.31.0 hoặc mới hơn) để thực hiện các yêu cầu HTTP.
• PyJWT (phiên bản 2.8.0 hoặc mới hơn) để tạo và ký JWT.
• pandas (phiên bản 2.2.0 hoặc mới hơn) để xử lý dữ liệu.
• python-dotenv để quản lý các biến môi trường.

Cấu trúc Dự án

yahoo_dsp_client/
├── src/
│ ├── init.py
│ ├── auth.py # Chứa logic xác thực và tạo token.
│ ├── reporting.py # Chứa logic tạo và lấy báo cáo.
│ └── main.py # Điểm vào chính, điều phối quy trình.
├──.env # Lưu trữ thông tin xác thực (không commit vào git).
└── requirements.txt # Liệt kê các gói phụ thuộc của Python.

API

# API

## Luồng Xác thực (OAuth 2.0 với JWT)

1.  **Tạo JWT:**
    -   **Header:** `{ "alg": "HS256", "typ": "JWT" }`
    -   **Payload (Claims):**
        -   `iss`: Client ID
        -   `sub`: Client ID
        -   `aud`: `https://id.b2b.yahooinc.com/identity/oauth2/access_token`
        -   `exp`: Thời gian hết hạn (timestamp), phải nhỏ hơn 1 giờ kể từ thời điểm hiện tại.
    -   **Signature:** Ký header và payload bằng Client Secret sử dụng thuật toán HS256.

2.  **Trao đổi JWT lấy Access Token:**
    -   **Phương thức:** `POST`
    -   **Endpoint:** `https://id.b2b.yahooinc.com/identity/oauth2/access_token`
    -   **Headers:** `Content-Type: application/x-www-form-urlencoded`
    -   **Body (form-encoded):**
        -   `grant_type`: `client_credentials`
        -   `client_id`: Client ID của bạn
        -   `client_secret`: Client Secret của bạn
        -   `assertion`: JWT đã tạo
    -   **Phản hồi thành công (JSON):** Chứa `access_token`.

## Luồng Báo cáo

1.  **Tạo Yêu cầu Báo cáo:**
    -   **Phương thức:** `POST`
    -   **Endpoint:** `http://api-sched-v3.admanagerplus.yahoo.com/yamplus_api/extreport/`
    -   **Headers:**
        -   `Content-Type: application/json`
        -   `X-Auth-Method: OAuth2`
        -   `X-Auth-Token: {access_token}`
    -   **Body (JSON):** Một đối tượng `reportOption` chi tiết. Ví dụ:
        ```json
        {
          "reportOption": {
            "dimensionTypeIds": ,
            "metricTypeIds": 
          },
          "intervalTypeId": 1,
          "dateTypeId": 4,
          "accountIds": ["{advertiser_id}"]
        }
        ```
    -   **Phản hồi thành công (JSON):** Chứa `customerReportId`.

2.  **Thăm dò Trạng thái Báo cáo:**
    -   **Phương thức:** `GET`
    -   **Endpoint:** `http://api-sched-v3.admanagerplus.yahoo.com/yamplus_api/extreport/?customerReportId={report_id}`
    -   **Headers:**
        -   `X-Auth-Method: OAuth2`
        -   `X-Auth-Token: {access_token}`
    -   **Phản hồi (JSON):** Chứa `status` (`SUBMITTED`, `PROCESSING`, `SUCCESS`, `FAILED`) và `url` (khi thành công).

# Dữ liệu Tham chiếu API

## Bảng 2: Các Dimension Báo cáo Thường dùng

| Tên Dimension | ID Dimension | Mô tả |
| :--- | :--- | :--- |
| Advertiser | 4 | ID và tên của nhà quảng cáo. |
| Campaign | 5 | ID và tên của chiến dịch. |
| Line | 6 | ID và tên của mục hàng (line item). |
| Ad | 7 | ID và tên của quảng cáo. |
| Country | 19 | Quốc gia của người tiêu dùng. |
| Device Category | 23 | Loại thiết bị (ví dụ: Desktop, Mobile). |

## Bảng 3: Các Metric Báo cáo Thường dùng

| Tên Metric | ID Metric | Mô tả |
| :--- | :--- | :--- |
| Impressions | 1 | Số lần quảng cáo được hiển thị. |
| Clicks | 2 | Số lần quảng cáo được nhấp vào. |
| CTR | 11 | Tỷ lệ Nhấp (Clicks / Impressions). |
| Conversions | 23 | Số lượng hành động chuyển đổi. |
| Advertiser Spending | 44 | Tổng ngân sách đã chi tiêu (chi phí). |
| CPA | 43 | Chi phí cho mỗi Hành động (Chi tiêu / Chuyển đổi). |

# Tiêu chuẩn Mã hóa

- Tuân thủ nghiêm ngặt tiêu chuẩn PEP 8.
- Sử dụng gợi ý kiểu (type hints) cho tất cả các chữ ký hàm và biến quan trọng.
- Sử dụng f-strings để định dạng chuỗi.
- Viết các hàm nhỏ, có mục đích duy nhất.

# Bảo mật & Xử lý Lỗi

- **KHÔNG BAO GIỜ** mã hóa cứng Client ID hoặc Client Secret trong mã nguồn. Luôn tải chúng từ tệp `.env`.
- Triển khai xử lý lỗi mạnh mẽ cho các yêu cầu API, bao gồm kiểm tra mã trạng thái HTTP và xử lý các phản hồi lỗi JSON.
- Tạo các lớp ngoại lệ tùy chỉnh (ví dụ: `AuthError`, `ReportError`) để xử lý các lỗi cụ thể của API.

# Ghi chú của Nhà phát triển

- Logic thăm dò phải bao gồm một khoảng thời gian chờ (ví dụ: 30 giây) giữa các lần thử để tránh làm quá tải API.
- Triển khai một cơ chế hết thời gian (timeout) cho vòng lặp thăm dò (ví dụ: 10 phút) để ngăn chặn các vòng lặp vô hạn.
- Đầu ra cuối cùng phải là một DataFrame của pandas được in ra giao diện điều khiển.

4.3. Phần 2: Hướng dẫn triển khai từng bước

Với bản thiết kế đã sẵn sàng, giờ là lúc bắt đầu xây dựng. Phần này sẽ mô phỏng cuộc đối thoại giữa nhà phát triển và Copilot Chat, cho thấy các prompt chính xác được sử dụng ở mỗi giai đoạn.

Bước 1: Dựng khung Dự án

Nhà phát triển bắt đầu bằng cách yêu cầu Copilot tạo cấu trúc tệp và thư mục đã được xác định.
Prompt:

@workspace #file:copilot-instructions.md Dựa trên Cấu trúc Dự án được xác định trong tệp hướng dẫn của chúng ta, hãy tạo các tệp và thư mục trống cần thiết.

Copilot sẽ thực hiện lệnh này, tạo ra cây thư mục src/ với các tệp auth.py, reporting.py, main.py và các tệp khác ở cấp gốc.

Bước 2: Triển khai Xác thực (auth.py)

Tiếp theo, nhà phát triển tập trung vào mô-đun xác thực. Prompt được tạo ra một cách cẩn thận để tham chiếu đến các chi tiết cụ thể trong bản thiết kế.
Prompt:

@workspace #file:src/auth.py Dựa trên Luồng Xác thực trong tệp hướng dẫn, hãy tạo một hàm tên là 'get_access_token'. Hàm này nên nhận client_id và client_secret làm đối số. Nó cần xây dựng một JWT với các claim được chỉ định, ký nó bằng HS256, và trao đổi nó để lấy một access token tại điểm cuối đã cho. Hãy đảm bảo xử lý các lỗi yêu cầu tiềm ẩn và trả về access token từ phản hồi JSON.

Copilot, với bối cảnh từ copilot-instructions.md, sẽ tạo ra một hàm Python sử dụng PyJWT để tạo token và requests để thực hiện yêu cầu POST, tuân thủ chính xác các đặc tả đã cho.

Bước 3: Triển khai Tạo Báo cáo (reporting.py)

Bây giờ đến lượt phần đầu tiên của logic báo cáo.
Prompt:

@workspace #file:src/reporting.py Tạo một hàm tên là 'create_report_request'. Hàm này nên nhận access_token, advertiser_id, một danh sách các ID dimension và một danh sách các ID metric. Sử dụng Hợp đồng API trong tệp hướng dẫn, nó phải xây dựng payload JSON và POST nó đến điểm cuối báo cáo. Hàm nên trả về 'customerReportId' từ phản hồi.

Copilot sẽ sử dụng cấu trúc payload mẫu và điểm cuối từ tệp hướng dẫn để tạo ra hàm này, đảm bảo định dạng yêu cầu là chính xác.

Bước 4: Triển khai Thăm dò Báo cáo (reporting.py)

Phần thứ hai của logic báo cáo là vòng lặp thăm dò.
Prompt:

@workspace #file:src/reporting.py Bây giờ, hãy tạo một hàm tên là 'poll_report_status'. Hàm này nên nhận access_token và report_id. Nó nên thực hiện một yêu cầu GET đến điểm cuối báo cáo mỗi 30 giây cho đến khi trạng thái là 'SUCCESS' hoặc 'FAILED'. Nếu thành công, nó nên trả về URL tải xuống. Hãy triển khai một cơ chế hết thời gian sau 10 phút.

Prompt này chỉ định không chỉ hành động cơ bản mà còn cả các ràng buộc quan trọng (khoảng thời gian chờ, hết thời gian) được nêu trong Ghi chú của Nhà phát triển trong bản thiết kế.

Bước 5: Điều phối (main.py)

Cuối cùng, nhà phát triển kết hợp tất cả lại trong tệp thực thi chính.
Prompt:

@workspace #file:src/main.py Tạo khối thực thi chính. Nó nên: 1. Tải thông tin xác thực từ tệp.env. 2. Gọi 'get_access_token'. 3. Gọi 'create_report_request' với các ID dimension và metric mẫu từ bảng tham chiếu của chúng ta (ví dụ: Campaign và Clicks ). 4. Chuyển kết quả cho 'poll_report_status'. 5. Nếu một URL tải xuống được trả về, hãy tải xuống tệp CSV và nạp nó vào một DataFrame của pandas. 6. In 5 hàng đầu tiên của DataFrame.

Copilot sẽ tạo ra mã điều phối, nhập các hàm từ auth.py và reporting.py và thực hiện toàn bộ quy trình từ đầu đến cuối.

4.4. Sức mạnh của một Bản thiết kế

Quá trình triển khai từng bước này cho thấy một nguyên tắc cơ bản: tệp copilot-instructions.md hoạt động như một “giàn giáo” cho quá trình suy luận của AI. Bằng cách cung cấp tên của các hàm, các điểm cuối API, và các cấu trúc dữ liệu ngay từ đầu, nhà phát triển đã giới hạn “không gian giải pháp” của AI một cách hiệu quả.

Khi nhà phát triển yêu cầu Copilot “tạo một hàm tên là ‘get_access_token'” ở Bước 2, Copilot không được giao nhiệm vụ thiết kế một luồng xác thực. Nó được giao nhiệm vụ triển khai một luồng đã được thiết kế sẵn bằng cách sử dụng các thư viện và điểm cuối đã được chỉ định. Điều này làm giảm đáng kể khả năng nó bịa ra một phương thức xác thực khác hoặc sử dụng sai thư viện. Bản thiết kế cung cấp các lan can bảo vệ giữ cho AI đi đúng con đường mong muốn.

Phương pháp này cho phép một nhà phát triển cấp cao hoặc một kiến trúc sư thiết kế cấu trúc cấp cao và các hợp đồng của hệ thống trong tệp Markdown, sau đó giao phó việc triển khai các hợp đồng đó, vốn thường mang tính lặp lại, cho Copilot (hoặc cho một nhà phát triển cấp dưới sử dụng Copilot). Đây là một mẫu hình mạnh mẽ để mở rộng quy mô các nhóm phát triển và đảm bảo tính nhất quán về kiến trúc trên toàn bộ dự án.

5. Kỹ thuật Nâng cao và Các Phương pháp Hay nhất

Việc làm chủ quy trình làm việc do Markdown dẫn lối không chỉ dừng lại ở việc tạo ra bản thiết kế ban đầu. Phần này cung cấp các mẹo chuyên nghiệp bổ sung để giúp các nhà phát triển tinh chỉnh quy trình, xử lý các thách thức phổ biến và duy trì sự kiểm soát đối với sản phẩm cuối cùng.

5.1. Điều chỉnh Hướng đi và Tinh chỉnh Lặp đi lặp lại

Không phải lúc nào Copilot cũng tạo ra mã hoàn hảo ngay lần đầu tiên. Ví dụ, nó có thể tạo ra một hàm xử lý lỗi nhưng lại bỏ qua một mã lỗi API cụ thể. Có hai phương pháp chính để điều chỉnh.

1. Tinh chỉnh ở cấp độ Prompt: Đây là một sự điều chỉnh chiến thuật. Nhà phát triển có thể đưa ra một prompt tiếp theo để tinh chỉnh mã hiện có. Ví dụ: Tái cấu trúc hàm trước để cũng xử lý mã trạng thái 429 Too Many Requests bằng cách triển khai một cơ chế thử lại theo cấp số nhân (exponential backoff). Điều này hiệu quả cho các chỉnh sửa một lần.
2. Tinh chỉnh ở cấp độ Bản thiết kế: Đây là một sự điều chỉnh chiến lược. Thay vì chỉ sửa một trường hợp, nhà phát triển có thể cập nhật chính tệp copilot-instructions.md. Bằng cách thêm một quy tắc mới vào phần “Bảo mật & Xử lý Lỗi” như Tất cả các lệnh gọi API phải triển khai cơ chế thử lại theo cấp số nhân cho các lỗi 429 và 5xx, nhà phát triển đã làm cho quy tắc này trở nên bền vững. Bất kỳ mã nào được tạo ra trong tương lai liên quan đến các lệnh gọi API giờ đây sẽ tuân thủ ràng buộc mới này, cải thiện tính mạnh mẽ của toàn bộ ứng dụng.

5.2. Quản lý Bối cảnh ở Quy mô lớn

Trong các dự án lớn, phức tạp với hàng chục tệp, việc cung cấp toàn bộ không gian làm việc làm bối cảnh có thể trở nên quá lớn hoặc nhiễu. Copilot có thể bị phân tâm bởi các tệp không liên quan. Để giải quyết vấn đề này, các nhà phát triển nên sử dụng các công cụ quản lý bối cảnh một cách chính xác.⁶

• Các biến và đối tượng tham gia trò chuyện: Sử dụng các từ khóa như @workspace, #file:<tên_tệp>, và #selection để tập trung sự chú ý của Copilot. Ví dụ, prompt @workspace #file:src/auth.py #file:src/reporting.py Giải thích mối quan hệ giữa hai tệp này sẽ chỉ thị cho Copilot chỉ xem xét hai tệp đó, bỏ qua phần còn lại của dự án.
• Các cuộc trò chuyện theo luồng: Đối với các dự án có nhiều tính năng riêng biệt, hãy bắt đầu các cuộc trò chuyện hoặc luồng mới cho mỗi tính năng. Điều này giữ cho lịch sử trò chuyện của mỗi luồng luôn phù hợp và sạch sẽ, ngăn chặn bối cảnh từ một tính năng này “rò rỉ” và ảnh hưởng đến việc tạo mã cho một tính năng khác.

5.3. Con người trong Vòng lặp: Bước không thể bỏ qua

Điều quan trọng nhất cần nhớ là mã do AI tạo ra là một điểm khởi đầu, không phải là một sản phẩm hoàn chỉnh.⁷ Sự giám sát nghiêm ngặt của con người là bước không thể thiếu trong quy trình.

• Đánh giá Mã nguồn (Code Review): Mã của Copilot phải được xem xét kỹ lưỡng như mã của bất kỳ thành viên nào trong nhóm. Hãy kiểm tra tính đúng đắn, khả năng đọc, hiệu suất và khả năng bảo trì.
• Phân tích Bảo mật: Đặc biệt khi xử lý xác thực, dữ liệu người dùng hoặc các API bên ngoài, hãy kiểm tra mã do AI tạo ra để tìm các lỗ hổng bảo mật tiềm ẩn. Đừng bao giờ mù quáng tin tưởng rằng nó đã xử lý đúng cách việc làm sạch đầu vào hoặc quản lý thông tin xác thực.³
• Kiểm thử: Viết các bài kiểm thử đơn vị và tích hợp toàn diện để xác thực hành vi của mã. Copilot có thể là một trợ thủ đắc lực trong việc này; bạn có thể yêu cầu nó tạo các bài kiểm thử cho các hàm mà nó vừa viết, đảm bảo phạm vi bao phủ và tính đúng đắn.³

Vai trò của nhà phát triển không bị giảm đi; nó chỉ thay đổi. Trọng tâm chuyển từ việc gõ mã lặp đi lặp lại sang việc giám sát, xác thực và tích hợp chiến lược.

# Tổng quan Dự án
Dự án này là một công cụ dòng lệnh Python để lấy báo cáo hiệu suất quảng cáo hàng ngày từ API Yahoo DSP. Công cụ sẽ xác thực, yêu cầu một báo cáo tùy chỉnh, thăm dò cho đến khi báo cáo sẵn sàng, tải xuống và hiển thị dữ liệu bằng pandas.
# Danh sách Tính năng
- Xác thực với API Yahoo DSP bằng luồng OAuth 2.0 Client Credentials với một JSON Web Token (JWT).
- Tạo và gửi một yêu cầu báo cáo không đồng bộ với các dimension và metric được chỉ định.
- Thăm dò điểm cuối API một cách định kỳ để kiểm tra trạng thái của yêu cầu báo cáo.
- Sau khi báo cáo thành công, tải xuống tệp CSV từ URL được cung cấp.
- Nạp dữ liệu CSV vào một DataFrame của pandas và hiển thị 5 hàng đầu tiên.
- Quản lý thông tin nhạy cảm (Client ID, Client Secret) bằng cách sử dụng các biến môi trường từ tệp .env.
# Ngăn xếp Công nghệ
- Python 3.10+
- requests (phiên bản 2.31.0 hoặc mới hơn) để thực hiện các yêu cầu HTTP.
- PyJWT (phiên bản 2.8.0 hoặc mới hơn) để tạo và ký JWT.
- pandas (phiên bản 2.2.0 hoặc mới hơn) để xử lý dữ liệu.
- python-dotenv để quản lý các biến môi trường.

# Cấu trúc Dự án
yahoo_dsp_client/
├── src/
│   ├── __init__.py
│   ├── auth.py         # Chứa logic xác thực và tạo token.
│   ├── reporting.py    # Chứa logic tạo và lấy báo cáo.
│   └── main.py         # Điểm vào chính, điều phối quy trình.
├── .env                # Lưu trữ thông tin xác thực (không commit vào git).
└── requirements.txt    # Liệt kê các gói phụ thuộc của Python.

# Hợp đồng API

## Luồng Xác thực (OAuth 2.0 với JWT) [1]

1.  **Tạo JWT:**
    -   **Header:** `{ "alg": "HS256", "typ": "JWT" }`
    -   **Payload (Claims):**
        -   `iss`: Client ID
        -   `sub`: Client ID
        -   `aud`: `https://id.b2b.yahooinc.com/identity/oauth2/access_token`
        -   `exp`: Thời gian hết hạn (timestamp), phải nhỏ hơn 1 giờ kể từ thời điểm hiện tại.
    -   **Signature:** Ký header và payload bằng Client Secret sử dụng thuật toán HS256.

2.  **Trao đổi JWT lấy Access Token:**
    -   **Phương thức:** `POST`
    -   **Endpoint:** `https://id.b2b.yahooinc.com/identity/oauth2/access_token`
    -   **Headers:** `Content-Type: application/x-www-form-urlencoded`
    -   **Body (form-encoded):**
        -   `grant_type`: `client_credentials`
        -   `client_id`: Client ID của bạn
        -   `client_secret`: Client Secret của bạn
        -   `assertion`: JWT đã tạo
    -   **Phản hồi thành công (JSON):** Chứa `access_token`.

## Luồng Báo cáo [2]

1.  **Tạo Yêu cầu Báo cáo:**
    -   **Phương thức:** `POST`
    -   **Endpoint:** `http://api-sched-v3.admanagerplus.yahoo.com/yamplus_api/extreport/`
    -   **Headers:**
        -   `Content-Type: application/json`
        -   `X-Auth-Method: OAuth2`
        -   `X-Auth-Token: {access_token}`
    -   **Body (JSON):** Một đối tượng `reportOption` chi tiết. Ví dụ:
        ```json
        {
          "reportOption": {
            "dimensionTypeIds":,
            "metricTypeIds":
          },
          "intervalTypeId": 1,
          "dateTypeId": 4,
          "accountIds": ["{advertiser_id}"]
        }
        ```
    -   **Phản hồi thành công (JSON):** Chứa `customerReportId`.

2.  **Thăm dò Trạng thái Báo cáo:**
    -   **Phương thức:** `GET`
    -   **Endpoint:** `http://api-sched-v3.admanagerplus.yahoo.com/yamplus_api/extreport/?customerReportId={report_id}`
    -   **Headers:**
        -   `X-Auth-Method: OAuth2`
        -   `X-Auth-Token: {access_token}`
    -   **Phản hồi (JSON):** Chứa `status` (`SUBMITTED`, `PROCESSING`, `SUCCESS`, `FAILED`) và `url` (khi thành công).

# Dữ liệu Tham chiếu API

## Bảng 2: Các Dimension Báo cáo Thường dùng [4]

| Tên Dimension | ID Dimension | Mô tả |
| :--- | :--- | :--- |
| Advertiser | 4 | ID và tên của nhà quảng cáo. |
| Campaign | 5 | ID và tên của chiến dịch. |
| Line | 6 | ID và tên của mục hàng (line item). |
| Ad | 7 | ID và tên của quảng cáo. |
| Country | 19 | Quốc gia của người tiêu dùng. |
| Device Category | 23 | Loại thiết bị (ví dụ: Desktop, Mobile). |

## Bảng 3: Các Metric Báo cáo Thường dùng [5]

| Tên Metric | ID Metric | Mô tả |
| :--- | :--- | :--- |
| Impressions | 1 | Số lần quảng cáo được hiển thị. |
| Clicks | 2 | Số lần quảng cáo được nhấp vào. |
| CTR | 11 | Tỷ lệ Nhấp (Clicks / Impressions). |
| Conversions | 23 | Số lượng hành động chuyển đổi. |
| Advertiser Spending | 44 | Tổng ngân sách đã chi tiêu (chi phí). |
| CPA | 43 | Chi phí cho mỗi Hành động (Chi tiêu / Chuyển đổi). |

# Tiêu chuẩn Mã hóa

- Tuân thủ nghiêm ngặt tiêu chuẩn PEP 8.
- Sử dụng gợi ý kiểu (type hints) cho tất cả các chữ ký hàm và biến quan trọng. [3]
- Sử dụng f-strings để định dạng chuỗi.
- Viết các hàm nhỏ, có mục đích duy nhất.

# Bảo mật & Xử lý Lỗi

- **KHÔNG BAO GIỜ** mã hóa cứng Client ID hoặc Client Secret trong mã nguồn. Luôn tải chúng từ tệp `.env`. [3]
- Triển khai xử lý lỗi mạnh mẽ cho các yêu cầu API, bao gồm kiểm tra mã trạng thái HTTP và xử lý các phản hồi lỗi JSON.
- Tạo các lớp ngoại lệ tùy chỉnh (ví dụ: `AuthError`, `ReportError`) để xử lý các lỗi cụ thể của API. [3]

# Ghi chú của Nhà phát triển

- Logic thăm dò phải bao gồm một khoảng thời gian chờ (ví dụ: 30 giây) giữa các lần thử để tránh làm quá tải API.
- Triển khai một cơ chế hết thời gian (timeout) cho vòng lặp thăm dò (ví dụ: 10 phút) để ngăn chặn các vòng lặp vô hạn.
- Đầu ra cuối cùng phải là một DataFrame của pandas được in ra giao diện điều khiển.