(P3) CW Dashboard – User Guide

Bài trước mô tả cách CW Dashboard theo dõi lãi lỗ sổ chứng quyền có bảo đảm (CW). Bài này đi vào phần làm: bộ code gồm những file nào, cần chuẩn bị dữ liệu gì, chạy theo thứ tự nào, và engine tính ra từng con số ra sao. Làm theo từ đầu đến cuối, bạn có một dashboard chạy trên máy mình với dữ liệu mẫu trong vài phút, rồi thay bằng dữ liệu thật.

1. Bộ code gồm những gì

Bộ code tách làm hai chương trình độc lập, chạy nối tiếp nhau:

Tách như vậy để logic P&L chỉ nằm ở một chỗ (engine). Dashboard chỉ đọc, cộng gộp theo bộ lọc và tính Greeks; mở bao nhiêu người cùng lúc cũng không làm thay đổi số liệu.

Hai cách đo P&L được tính song song:

• Mark-to-Market: CW đang lưu hành định giá theo giá đóng cửa trên sàn. Khớp với số liệu kế toán.
• Mark-to-Model: CW đang lưu hành định giá theo Black-Scholes với IV định giá nội bộ. Phản ánh hiệu quả kinh tế của sổ phòng hộ, không bị nhiễu bởi giá CW trên sàn lệch khỏi giá trị lý thuyết.

2. Luồng dữ liệu

3. Cây thư mục

cw_pnl_dashboard/
├── run_demo.bat          tạo dữ liệu mẫu -> engine -> dashboard (chạy thử)
├── run_engine.bat        chạy engine
├── run_dashboard.bat     mở dashboard
├── run.sh                bản cho macOS / Linux: ./run.sh demo | engine | dashboard | test
├── config.json           tham số + định nghĩa Lô phát hành
├── requirements.txt      pandas
├── README.md             hướng dẫn chi tiết
├── cwpnl/
│   ├── pricing.py        Black-Scholes, Greeks, giải IV (chỉ dùng thư viện chuẩn)
│   ├── common.py         đọc cấu hình và các file đầu vào
│   ├── engine.py         tính P&L luỹ kế -> data/pnl.db
│   ├── server.py         API JSON + phục vụ giao diện
│   └── static/
│       ├── index.html    giao diện 5 tab
│       └── vendor/       Chart.js 4.4.4 (giấy phép MIT)
├── tools/
│   ├── make_sample_data.py   sinh dữ liệu giả lập để chạy thử
│   ├── self_test.py          kiểm tra công thức bằng ví dụ tính tay
│   └── find_python.bat       tìm Python, tự cài thư viện còn thiếu
└── data/
    ├── input/            dữ liệu đầu vào (CSV)
    └── pnl.db            engine tạo ra

4. Dữ liệu cần chuẩn bị

Tất cả là file CSV đặt trong data/input/, dòng đầu là tên cột, mã hoá UTF-8. Ngày dạng YYYY-MM-DD. Giá và tiền tính bằng đồng (không phải nghìn đồng). Ba file đầu là bắt buộc.

4.1 trades.csv — giao dịch của sổ (bắt buộc)

date,leg,symbol,side,qty,price,fee,subaccount
2026-07-15,CW,CGHI2701,SELL,50000,1250,19,
2026-07-15,UL,GHI,BUY,8000,31200,374,HEDGE02
2026-07-20,CW,CGHI2701,BUY,10000,1180,4,

Mỗi dòng có thể là một lệnh khớp hoặc tổng khớp trong ngày theo mã và chiều. Kết quả như nhau vì engine dùng giá bình quân gia quyền.

4.2 prices.csv — giá đóng cửa (bắt buộc)

4.3 cw_metadata.csv — điều khoản CW (bắt buộc)

4.4 cw_iv.csv — IV định giá nội bộ (nên có)

Ba cột date, cw, iv: IV áp dụng từ ngày date, viết dạng thập phân (0.42 = 42%). Mỗi lần bộ phận định giá đổi IV thì thêm một dòng. CW chưa có IV: engine dùng default_iv; dashboard tính Greeks bằng IV giải từ giá thị trường, không được thì IV mặc định và gắn nhãn cảnh báo.

4.5 File tuỳ chọn

5. Cấu hình — config.json

{
  "input_dir": "data/input",
  "db_path": "data/pnl.db",
  "risk_free_rate": 0.08,
  "cof_rate": 0.08,
  "default_iv": 0.40,
  "index_symbol": "VN30",
  "start_date": "2025-10-16",
  "end_date": null,
  "port": 8050,
  "host": "127.0.0.1",
  "batches": {
    "Lô 1": { "start_date": "2025-10-16", "subaccounts": ["HEDGE01"],
              "cws": ["CABC2601", "CABC2602", "CDEF2601", "CDEF2602"] },
    "Lô 2": { "start_date": "2026-07-01", "subaccounts": ["HEDGE02"],
              "cws": ["CGHI2701", "CGHI2702", "CJKL2701", "CJKL2702"] }
  }
}

6. Các bước chạy

6.1 Lần đầu

1. Cài Python 3.10+ từ python.org. Trên Windows, tick Add python.exe to PATH khi cài.
2. Giải nén bộ code vào một thư mục bất kỳ, ví dụ D:\cw_pnl_dashboard.
3. Bấm đúp run_demo.bat (macOS/Linux: ./run.sh demo). Lần đầu script tự cài pandas, sinh dữ liệu giả lập (4 mã cơ sở, 8 CW, 2 Lô, khoảng một năm), chạy engine rồi mở trình duyệt.
4. Kiểm tra công thức: python tools/self_test.py phải in TẤT CẢ ĐỀU ĐÚNG.

6.2 Chuyển sang dữ liệu thật

1. Xoá các file mẫu trong data/input/.
2. Đặt 3 file bắt buộc trades.csv, prices.csv, cw_metadata.csv (mục 4), thêm cw_iv.csv và các file tuỳ chọn nếu có.
3. Sửa config.json: ngày bắt đầu, lãi suất, danh sách Lô với đúng mã CW và tiểu khoản phòng hộ.
4. Bấm đúp run_engine.bat. Đọc log: số phiên, số giao dịch, các dòng CẢNH BÁO.
5. Bấm đúp run_dashboard.bat.

6.3 Hằng ngày

7. Engine tính gì: ví dụ tính tay

Engine xử lý từng phiên theo thứ tự thời gian, giữ trạng thái cho mỗi CW và mỗi cặp (cổ phiếu, tiểu khoản):

Ví dụ dưới đây chính là bộ kiểm tra trong tools/self_test.py: CW giá thực hiện 10.000 đ, tỷ lệ 2:1, đáo hạn 12/01/2026; cof_rate 3,65%/năm.

Dashboard cộng các số luỹ kế này theo ngày rồi tính:

Khi lọc theo mã cơ sở hoặc trader, COF của Lô được chia theo tỷ trọng giá vốn phòng hộ của nhóm đang lọc. Cộng các nhóm lại luôn bằng tổng: đã kiểm tra trên dữ liệu mẫu, tổng theo Lô, theo trader, theo mã cơ sở và theo hai nửa kỳ đều khớp với P&L toàn sổ.

8. Cơ sở dữ liệu đầu ra — data/pnl.db

File này mở được bằng DB Browser for SQLite, Python (pandas.read_sql) hoặc Excel qua Power Query, nên có thể dùng làm nguồn cho các báo cáo khác.

9. Dashboard và API

Giao diện lấy dữ liệu qua 6 API JSON (đều là GET, tham số trên URL), có thể gọi từ Excel hoặc script khác:

10. Kiểm tra và lỗi thường gặp

11. Giới hạn và hướng mở rộng

• Cửa sổ S5: trong 5 phiên trước đáo hạn, nghĩa vụ CW đã bị chốt dần theo giá bình quân, nhưng Mark-to-Model vẫn định giá bằng Black-Scholes trên giá hiện tại. P&L có thể dao động trong vài phiên này rồi trở về đúng ở ngày tất toán. Có thể cải tiến bằng cách định giá theo phần S5 đã biết cộng phần còn lại.
• Một lãi suất phi rủi ro cho mọi CW; mỗi CW một IV (không nội suy bề mặt IV).
• Đầu vào là CSV xuất tay. Bước tiếp theo hợp lý là đọc thẳng từ cơ sở dữ liệu giao dịch, hoặc dùng Power Query gộp file xuất hằng ngày thành trades.csv.
• Server không có đăng nhập. Không đổi host thành 0.0.0.0 nếu không muốn máy khác trong mạng xem được số liệu.
• Có thể lên lịch chạy engine tự động bằng Task Scheduler (Windows) hoặc cron (macOS/Linux) sau giờ đóng cửa.

12. Bản quyền và miễn trừ

• Bộ code và bài viết do tác giả tự viết. Dữ liệu mẫu (mã ABC, DEF, GHI, JKL, các CW và tiểu khoản) hoàn toàn giả lập, không phản ánh vị thế hay kết quả của bất kỳ tổ chức nào.
• Mô hình Black-Scholes là kiến thức công khai (Black, F. & Scholes, M., 1973, “The Pricing of Options and Corporate Liabilities”, Journal of Political Economy).
• Thư viện dùng kèm: Chart.js 4.4.4 (MIT, file giấy phép đi kèm trong static/vendor/), pandas (BSD), SQLite (public domain), Python (PSF License).
• VN30, HOSE là tên gọi thuộc chủ sở hữu tương ứng, chỉ dùng để mô tả.
• Bài viết là chia sẻ kỹ thuật, không phải khuyến nghị đầu tư. Kiểm tra kỹ số liệu trước khi dùng cho báo cáo chính thức.