# 維港帳房

這是一個以 **Flask + SQLite + 原生 HTML/CSS/JavaScript** 編寫的個人單機股票、投資組合與 MPF 持倉帳本。所有帳戶、標的、交易及本機市場設定保存在專案根目錄的單一 `ledger.db` 檔案；不使用 Docker、雲端資料庫、OAuth、TypeScript、打包工具或 CSS 框架。

## 啟動方式

系統環境須具備 Python 3。首次使用時，於專案根目錄執行：

```bash
python3 -m pip install -r requirements.txt
```

然後啟動本機服務：

```bash
python3 app.py
```

然後在瀏覽器開啟 `http://127.0.0.1:8787`。首次使用時設定至少 8 個字元的本機密碼。

預設服務只監聽 `127.0.0.1`，不會對區域網路公開。若要改用其他本機埠口，可先設定 `LEDGER_PORT`，例如 `LEDGER_PORT=8890 python3 app.py`。`LEDGER_HOST` 只應在受信任網絡或受控測試中明確設定，正常個人使用不建議更改。

## 功能與計算基礎

| 功能 | 實作方式 |
| --- | --- |
| 帳戶工作表 | 銀行、券商及 MPF 帳戶各自保存交易，交易帳可按帳戶及標的篩選。 |
| 真平均成本 | 買入成本 = 數量 × 價格 × 匯率 + 佣金 + 費用 + 稅款；賣出會按交易當刻的平均成本扣減。 |
| 已實現損益 | 賣出淨收入 − 該批售出單位的平均成本。股息獨立累積，不混入已實現買賣損益。 |
| 公司行動 | 拆細／合併以舊：新比例調整持股，不改變總投入成本，因此自動調整平均價。 |
| MPF | 新增 MPF 帳戶及 MPF 市場標的後，以「MPF 供款」當作單位買入；可記錄提取。 |
| 市場資料 | 可選 Yahoo Finance 公開圖表端點或自行輸入 Alpha Vantage API 金鑰。市場資料不是保證即時資料。 |
| 交易成本 | 港股預設採 HKEX 公開頁所列印花稅、SFC／AFRC 徵費及交易費；券商佣金、平台費與美股監管費由使用者填入。 |

## 資料安全及備份

在「設定與備份」頁下載 `ledger.db`。該檔案包含所有個人交易資料及本機設定，應只儲存在受保護位置。此版本刻意不設匯入覆蓋功能，避免意外刪除或改寫帳目。

## 資料來源與重要提醒

港股成本預設費率參照 [香港交易所交易費用頁](https://www.hkex.com.hk/Services/Rules-and-Forms-and-Fees/Fees/Securities-(Hong-Kong)/Trading/Transaction?sc_lang=en)：印花稅 0.1%（雙方、向上捨入整元）、SFC 徵費 0.0027%、AFRC 徵費 0.00015%、交易費 0.00565%。費率、豁免範圍及券商收費可改變，正式記帳請以成交單及券商賬單為準。

Alpha Vantage 的官方文件指出，即時與 15 分鐘延時美股資料有授權與訂閱條件；請按供應商條款及你的使用資格設定資料來源。[1](https://www.alphavantage.co/documentation/) [2](https://www.alphavantage.co/realtime_data_policy/)

> 本工具只用作個人資料記錄與研究用途，並非個人化投資、稅務或法律意見。