(P2) CW Market Overview

CW Market Overview tải dữ liệu chứng quyền có bảo đảm (CW) của toàn thị trường HOSE từ các nguồn công khai, tính định giá, biến động và rủi ro, ghi vào một file Excel và dựng một file dashboard HTML duy nhất gồm 4 tab. Bài này mô tả đủ chi tiết để bạn dựng lại một hệ thống tương tự từ đầu: lấy dữ liệu ở đâu, tính từng con số thế nào, lưu trung gian ra sao, ráp dashboard bằng cách nào, và nên làm theo thứ tự nào.

1. Hệ thống làm gì

Đầu vào là bảng giá và thống kê công khai. Đầu ra là ba thứ:

• CW Dashboard.html: một file tự chứa (dữ liệu nhúng sẵn), 4 tab, đổi Sáng/Tối và EN/VI, mở bằng trình duyệt, gửi được qua email.
• CW Market Overview.xlsx: sheet Horizon (mỗi CW một dòng, 35 cột chỉ số) và RawData (dữ liệu thô từng nguồn).
• GARCH Volatility Result/: tham số, dự báo và kiểm định của mô hình GARCH / GJR-GARCH.

2. Kiến trúc và ba chế độ chạy

Hệ thống chia ba lớp, mỗi lớp chỉ đọc đầu ra của lớp trước. Nhờ vậy có thể dựng lại dashboard mà không tải lại dữ liệu, và sửa giao diện mà không chạm vào phần tính toán.

2.1 Các bước của main.py

2.2 Ba chế độ chạy

Dashboard có hai góc nhìn chuyển bằng nút: Sync (mọi số liệu cùng một ngày as-of) và Real-time (giá của phiên mới nhất; các số chỉ công bố sau phiên như tự doanh vẫn giữ ngày Sync và được ghi rõ ngày).

3. Cây thư mục

CW_Market_Overview/
├─ Run CW Market Overview.bat   chạy đầy đủ (Sync)
├─ Run Live.bat                 cập nhật trong phiên
├─ Rebuild Dashboard.bat        chỉ dựng lại dashboard
├─ main.py                      điều phối các bước 0 → 9
├─ live.py                      vòng lặp chế độ Live
├─ build_dashboard.py           lệnh cho Rebuild
├─ CW Market Overview.xlsx      khuôn Excel: Horizon, RawData
├─ config/api_config.py         MỌI THAM SỐ (mục 11)
├─ src/
│  ├─ ensure_python.bat         tìm / tự cài Python lần đầu
│  ├─ as_of.py                  chọn ngày dữ liệu, bảng DATA CHECK
│  ├─ api_client.py             gọi SSI
│  ├─ step_cache.py             cache kết quả từng bước theo ngày
│  ├─ historical_loader.py      lịch sử giá, HV, Yang-Zhang
│  ├─ underlying_liquidity.py   giá trị khớp, ADV
│  ├─ cw_history.py             giá đóng cửa CW theo ngày
│  ├─ vdsc_quotes.py            giá chào trong phiên (LiveDragon)
│  ├─ proprietary_trading.py    tự doanh (VNDIRECT)
│  ├─ option_pricing.py         Black-Scholes, IV, delta
│  ├─ cw_processor.py           bảng master từng CW
│  ├─ volatility_models.py      GARCH, GJR-GARCH, backtest
│  ├─ garch_pipeline.py         GARCH theo kỳ hạn CW
│  ├─ iv_monitor.py             giải IV dạng mảng, tín hiệu IV
│  ├─ realtime.py               ảnh chụp phiên mới nhất
│  ├─ kafi_inventory.py         tồn kho nội bộ (tuỳ chọn)
│  ├─ raw_data.py, excel_exporter.py, workbook_io.py   ghi Excel
│  └─ dashboard/
│     ├─ build.py               ráp dashboard
│     ├─ market_data.py         tab 1
│     ├─ client_data.py         tab 2
│     ├─ vol_data.py, iv_db.py  tab 3 (IV hằng ngày)
│     ├─ kafi_batches.py        phân phối theo lô
│     ├─ kafi_extra.py          CW đã hết ngày giao dịch nhưng chưa đáo hạn
│     ├─ events_data.py         sự kiện quyền (tự phát hiện)
│     ├─ mm_data.py             chất lượng chào giá
│     └─ template/              head.html · body.html · app.js.html · settings.js.html · logo
└─ data/                        CSV trung gian, cache, quotes, realtime (mục 8)

4. Nguồn dữ liệu và cách gọi

4.1 Bảy địa chỉ đang dùng

4.2 Quy tắc chung

• Gửi header giống trình duyệt (User-Agent, Accept). VNDIRECT cần thêm Referer và Origin = https://dstock.vndirect.com.vn.
• SSI trả "code": "SUCCESS" khi thành công. API có phân trang thì lặp page tới hết.
• Đơn vị: giá lịch sử SSI và giá LiveDragon theo nghìn đồng (nhân 1.000). Mốc thời gian nến ngày là 00:00 giờ Việt Nam: đổi sang múi Asia/Ho_Chi_Minh trước khi lấy ngày.
• Tỷ lệ chuyển đổi dạng chữ “1.7245:1”: lấy số trước dấu hai chấm.
• Tự doanh: lượng CW nhà đầu tư nắm = luỹ kế sellingVol − buyingVol của TCPH. Không dùng netVol của VNDIRECT vì ngược dấu. Lỗi mạng phải gọi lại (tối đa 3 lần), không được biến thành số 0.
• Tải bù, không tải lại: mỗi lần chạy chỉ tải phần còn thiếu (mã mới, ngày mới). Dữ liệu LiveDragon phải lưu lại hằng ngày vì máy chủ chỉ giữ khoảng 3 tháng.
• Tìm lại một API khi nó đổi: mở trang bảng giá bằng Chrome, F12 → Network → Fetch/XHR, thao tác trên trang, chọn yêu cầu mới, xem Headers và Response, chuột phải → Copy as cURL để thử lại.

4.3 Ví dụ gọi nhanh

import requests
H = {"User-Agent": "Mozilla/5.0", "Accept": "application/json, text/plain, */*"}

# 1. Bảng CW
cw = requests.get("https://iboard-query.ssi.com.vn/stock/cw/hose", headers=H, timeout=30).json()
rows = cw["data"]["coveredWarrantData"]
print(len(rows), "CW", rows[0]["stockSymbol"], rows[0]["exerciseRatio"])

# 6. Tự doanh một mã CW
HV = {**H, "Referer": "https://dstock.vndirect.com.vn/", "Origin": "https://dstock.vndirect.com.vn"}
p = requests.get("https://api-finfo.vndirect.com.vn/v4/proprietary_trading",
                 params={"q": f"code:{rows[0]['stockSymbol']}", "sort": "date", "page": 1, "size": 100},
                 headers=HV, timeout=30).json()

# 7. Bảng giá trong phiên của một CW, một ngày
s = requests.Session(); s.headers.update({**H, "X-Requested-With": "XMLHttpRequest",
                                          "Referer": "https://livedragon.vdsc.com.vn/general/intradayBoard.rv"})
s.get("https://livedragon.vdsc.com.vn/general/intradayBoard.rv", timeout=20)          # cookie
snap = s.post("https://livedragon.vdsc.com.vn/general/intradaySearch.rv",
              data={"stockCode": rows[0]["stockSymbol"], "boardDate": "16/10/2026"}, timeout=30).json()
print(len(snap.get("list") or []), "ảnh chụp")

4.4 Nguồn nội bộ (tuỳ chọn)

Hai biểu đồ dùng số chính xác hơn nếu có dữ liệu nội bộ của TCPH nhà; không có thì hệ thống tự ước tính:

5. Một ngày dữ liệu cho mọi nguồn

Mọi con số trong Excel và chế độ Sync phải mô tả cùng một phiên đã đóng. Quy tắc trong as_of.py:

1. Ngày làm việc, chạy từ 15:00 trở đi → ứng viên là hôm nay. Chạy trước 15:00 hoặc cuối tuần → ngày làm việc liền trước.
2. Ứng viên chỉ được dùng khi mọi nguồn đã có ngày đó: tự doanh VNDIRECT (thường công bố muộn nhất; kiểm tra bằng q=date:YYYY-MM-DD&size=5), nến ngày của CW, nến ngày của cổ phiếu, stock-info.
3. Thiếu một nguồn → lùi một ngày làm việc và kiểm tra lại, tối đa 7 lần.
4. Chốt ngày xong thì cắt mọi nguồn về ngày đó: giá và khối lượng CW, giá cơ sở, thanh khoản, lịch sử cho HV/GARCH, tự doanh luỹ kế, số ngày còn lại.
5. In bảng DATA CHECK: mỗi nguồn một dòng, OK nếu đúng ngày, XX nếu lệch. Dashboard từ chối dựng nếu workbook và các CSV khác ngày.

6. Công thức cho từng CW

Ký hiệu: S giá cơ sở, K giá thực hiện, CR tỷ lệ chuyển đổi (số CW đổi 1 cổ phiếu), W giá CW, T = số ngày lịch còn lại / 365, r lãi suất phi rủi ro (mặc định 7%, một mức cho mọi CW), N(·) hàm phân phối chuẩn tích luỹ, n(·) hàm mật độ.

6.1 Ví dụ tính tay

Một CW giả định: S = 30.000 đ, K = 32.000 đ, CR = 4, W = 900 đ, còn 120 ngày, r = 7%.

7. Biến động: HV, Yang-Zhang, GARCH, IV hằng ngày

7.1 HV và Yang-Zhang theo kỳ hạn gốc

Mỗi CW có kỳ hạn gốc = ngày đáo hạn − ngày giao dịch đầu (ví dụ 12 tháng). HV đo trên đúng khoảng ngày lịch đó, tính ngược từ ngày as-of; ít hơn 20 lợi suất thì lấy 20 phiên gần nhất.

7.2 GARCH và GJR-GARCH

• Tải khoảng 5 năm giá cơ sở, ước lượng trên 750 phiên gần nhất, phân phối Student-t (thư viện arch).
• Bỏ những ngày có |lợi suất| > 7,5% (thường do sự kiện quyền chưa điều chỉnh).
• Giới hạn persistence α + β + γ/2 ≤ 0,99 để vol dài hạn không bùng nổ.
• Dự báo vol bình quân cho các kỳ hạn 21, 63, 126, 189, 252, 315 phiên; mỗi CW lấy kỳ hạn khớp với kỳ hạn gốc của nó.
• Tuỳ chọn backtest walk-forward: huấn luyện tối thiểu 500 phiên, ước lượng lại mỗi 20 phiên, chấm điểm bằng QLIKE, kiểm định Diebold-Mariano và VaR Kupiec.

7.3 IV hằng ngày cho tab 3

IV trong bảng master dùng giá đóng cửa, dễ nhiễu vì phiên ATC. Tab 3 dùng một chuỗi IV hằng ngày ổn định hơn, ưu tiên theo thứ tự:

1. Có công cụ quét IV trong phiên (ví dụ 10 phút/lần, giá giữa bid/ask): IV ngày = trung bình các lần quét; ngày có ít hơn 3 lần quét thì bỏ.
2. Không có: tự tính từ giá giữa (Bid + Ask)/2 của ảnh chụp chào giá chặt cuối cùng trước 14:30 (chênh lệch ≤ max(3 bước giá, 6% giá giữa)). Giá cơ sở lấy cùng thời điểm: giá khớp cuối trước 14:30 của cổ phiếu, quy đổi theo hệ số điều chỉnh của SSI.
3. Không có giá chào hai chiều thì dùng giá đóng cửa của ngày có khớp lệnh.

8. Dữ liệu trung gian và workbook

Dashboard không đọc API mà đọc các file dưới đây. Đây là “hợp đồng” giữa lớp tính toán và lớp trình bày: giữ đúng tên cột thì có thể thay phần lấy dữ liệu mà không sửa dashboard.

8.1 Sheet Horizon

Dòng 7 là tiêu đề, dữ liệu từ dòng 8. Code tìm cột theo tên, không theo vị trí, nên có thể chèn cột hoặc đổi định dạng trong Excel. 35 cột theo thứ tự:

CW · Ticker · Issuer · Last trading date · Listed volume · DTE · Conversion ratio · Delta · CW price trading · CW price theory · Strike price · Spot price · Breakeven price · % Increase to Breakeven · Intrinsic Value / CW Price · Status · Leverage · HV · IV · IV-HV · Yang-Zhang vol · GARCH · GJR-GARCH · Market trading value · Market ADV 1 months · Market ADV 3 months · YTD Market ADV · CW trading volume · CW trading value · Buy volume · Buy value · Sell volume · Sell value · Net sold · % distribution

Ghi Excel qua chính ứng dụng Excel (thư viện xlwings) để giữ nguyên định dạng, công thức và biểu đồ của khuôn. Trước khi ghi: hỏi đóng file nếu đang mở, sao lưu bản cũ (giữ 30 bản trong data/backup/), ghi ra file tạm rồi mới thay.

9. Ráp dashboard thành một file

Ý tưởng: Python tính sẵn mọi thứ thành JSON; khuôn HTML có các chỗ giữ chỗ dạng __TÊN__; build.py thay chỗ giữ chỗ bằng JSON rồi ghép thành một file. Trình duyệt chỉ việc vẽ và lọc, không cần máy chủ.

1. build.py kiểm tra các file đầu vào cùng ngày as-of, rồi lần lượt gọi từng module. Mỗi module đọc data/cache/web_data.json, thêm một khoá, ghi lại. Module phụ lỗi thì chỉ in WARNING, dashboard vẫn dựng (phần đó trống).
2. Đọc 4 khuôn: head.html (CSS, biến màu sáng/tối), body.html (bố cục 4 tab), app.js.html (toàn bộ JavaScript), settings.js.html (đổi giao diện, từ điển EN→VI).
3. Thay chỗ giữ chỗ bằng json.dumps(..., ensure_ascii=False), ghi ra file tạm rồi đổi tên (không bao giờ để lại file dở dang).

9.1 Những kỹ thuật giúp file nhẹ và dễ sửa

• Chuỗi IV dạng mảng gọn: mỗi CW-ngày là một mảng [chỉ số ngày, S, W, bid, ask, close, IV, IV P10, IV P90, vega, nguồn, số lần quét] thay vì đối tượng có tên trường, giảm dung lượng nhiều lần.
• Biểu đồ SVG tự vẽ bằng chuỗi HTML, không phụ thuộc thư viện hay mạng.
• Bảng sắp xếp dùng chung: một hàm sortTable(id, cột, dòng, {key, asc}), mỗi cột khai báo khoá, tiêu đề, hàm hiển thị, hàm tô màu.
• Song ngữ không sửa HTML: giao diện viết bằng tiếng Anh; settings.js.html giữ từ điển cụm từ Anh → Việt và một MutationObserver dịch mọi nút chữ mới xuất hiện. Thêm nhãn mới thì thêm một dòng vào từ điển.
• Sáng/Tối: mọi màu là biến CSS, đổi bằng thuộc tính data-theme trên thẻ html; lựa chọn được trình duyệt ghi nhớ.
• Chế độ Live: khi dựng từ live.py, trang được chèn giờ cập nhật kế tiếp và tự tải lại đúng lúc đó, giữ tab đang xem qua phần # của địa chỉ.

10. Nội dung và công thức từng tab

10.1 Tab 1 · Competitor Overview

10.2 Tab 2 · Client Overview

“Nhà đầu tư” là phía đối diện của tự doanh TCPH: nhà đầu tư mua = TCPH bán. Mỗi giao dịch tự doanh trong ngày được gắn đặc điểm của CW tại ngày đó: moneyness theo giá cơ sở ngày đó, DTE ngày đó, đòn bẩy hiệu dụng = S / (giá bình quân × CR) × N(d1) với σ = HV 60 phiên tại ngày đó. Cộng theo kỳ chọn (Hôm nay, 1 tuần, 1 tháng, 3 tháng hoặc tự chọn) ra dòng tiền mua, bán, ròng theo nhóm, theo mã cơ sở và theo ngày.

10.3 Tab 3 · Volatility

10.4 Tab 4 · Risk & Events

4.1 Rủi ro sổ CW của TCPH nhà. Tính cho mọi CW còn lưu hành, kể cả CW đã qua ngày giao dịch cuối nhưng chưa đáo hạn. OI = lượng lưu hành (số niêm yết − tồn kho, hoặc ước tính từ tự doanh). σ = IV; dùng HV nếu CW ITM sâu (moneyness > 15%), giá trị thời gian < 5% giá CW, hoặc không có IV; không có cả hai và ITM thì delta = 1/CR.

Ví dụ tiếp mục 6.1 với OI = 2.000.000 CW: khoản phải trả 1,80 tỷ (toàn bộ là giá trị thời gian) · Delta CW −7,82 tỷ (cần khoảng 260.500 cổ phiếu để phòng hộ) · Gamma (1%) −0,86 triệu · Vega 34,3 triệu mỗi điểm IV · Theta +9,77 triệu/ngày · cơ sở +7%: chưa phòng hộ −588 triệu, đã phòng hộ −41 triệu.

4.2 Lịch sự kiện. CW đáo hạn trong 30/45/90 ngày và giá trị thanh toán dự kiến; CW mới niêm yết 30 ngày; sự kiện quyền của mã cơ sở được phát hiện từ dữ liệu giá, không cần lịch ngoài: hệ số = giá điều chỉnh (SSI) / giá chưa điều chỉnh (LiveDragon) mỗi ngày, lấy trung vị trượt 3 ngày; hệ số đổi hơn 0,5% → ngày giao dịch không hưởng quyền, tỷ lệ = hệ số trước / hệ số sau.

4.3 Chất lượng tạo lập thị trường. Tính theo thời gian trên toàn phiên liên tục (9:15–11:30, 13:00–14:30, bỏ 5 phút đầu mỗi nửa phiên), không dùng một ảnh chụp cuối ngày. Mỗi trạng thái bảng giá có trọng số bằng số giây nó tồn tại. Loại các giây không thể chào hai chiều: cổ phiếu cơ sở trắng một bên (đứng trần/sàn), hoặc CW chào bán ở giá sàn 10 đ.

11. Bảng tham số

Mọi tham số nằm trong một file config/api_config.py, chia mục [A]–[I]. Code đọc bằng getattr(config, "TÊN", mặc_định), nên thiếu dòng nào thì dùng mặc định, và bản cũ của file cấu hình vẫn chạy với code mới.

12. Dựng lại từ đầu: lộ trình 8 chặng

Thứ tự dưới đây đi từ phần có giá trị ngay đến phần nâng cao. Mỗi chặng có một phép kiểm tra; qua được mới làm chặng sau. Làm một mình mất vài tuần; làm cùng trợ lý AI thì mỗi chặng thường gói gọn trong một buổi.

12.1 Mẫu yêu cầu khi làm cùng trợ lý AI

Dán bài viết này vào cuộc trò chuyện, rồi yêu cầu từng chặng một. Ví dụ cho chặng 2:

Dựa trên mục 6 của tài liệu đính kèm, viết file option_pricing.py gồm:
- black_scholes_call(S, K, T, r, sigma, CR) trả giá MỘT CW (đã chia CR)
- implied_volatility(W, S, K, T, r, CR): Brent trong [0.0001, 5]; không có nghiệm thì trả NaN
- call_delta(S, K, T, r, sigma) trả N(d1)
Viết kèm test: S=30000, K=32000, CR=4, W=900, T=120/365, r=0.07 phải ra IV ≈ 0.603,
N(d1) ≈ 0.521. Chỉ dùng numpy, scipy.

Ba nguyên tắc giúp mỗi chặng ra đúng ngay:

• Luôn nêu đơn vị (đồng hay nghìn đồng, ngày lịch hay phiên) và dấu (ai bán, ai mua).
• Yêu cầu kèm một phép kiểm tra bằng số cụ thể như cột thứ ba ở bảng trên.
• Giữ tên cột của các file trung gian ở mục 8, để các chặng sau ghép vào không phải sửa lại.

13. Vận hành và lỗi thường gặp

14. Dữ liệu nội bộ, bản quyền và miễn trừ

• Tồn kho, tiểu khoản, số cổ phiếu phòng hộ và đường dẫn thư mục nội bộ là dữ liệu của tổ chức. Không đưa vào bài viết, không đăng dashboard có các số này ra ngoài; chỉ chia sẻ trong nội bộ theo quy định của đơn vị.
• Dữ liệu thị trường thuộc SSI, VNDIRECT, VDSC và Sở Giao dịch Chứng khoán TP.HCM; chỉ dùng trong phạm vi điều khoản của từng nơi.
• Ví dụ số trong bài (CW 30.000/32.000, OI 2 triệu CW) là giả định, không phản ánh vị thế của tổ chức nào.
• Mô hình Black-Scholes (Black & Scholes, 1973), GARCH (Bollerslev, 1986), GJR-GARCH (Glosten, Jagannathan & Runkle, 1993), Yang-Zhang (Yang & Zhang, 2000) là kiến thức công khai. Thư viện dùng kèm: pandas, numpy, scipy (BSD), arch (NCSA), xlwings (BSD), openpyxl (MIT), requests (Apache 2.0).
• 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.