Windows 桌面工具，從 CSV 名冊批次產生實驗報酬收據（.docx），自動依「本國 / 外國」套用不同範本，最後合併成單一檔案。雙擊 .exe 即可，不需要 Python 或任何套件。
- 到本 repo 的 Releases 頁面下載
GenReceipt.exe（約 250 MB，因為內含 Python 直譯器、pandas 等執行時所需的所有套件） - 把
GenReceipt.exe放到這個資料夾的根目錄（跟input/、output/同層） - 雙擊
GenReceipt.exe開啟
第一次啟動需要 5–15 秒（程式會解壓內含套件到暫存區），之後同一次開機重啟都是秒開。
Gen_receipt_GUI/
├── GenReceipt.exe ← 從 Releases 下載後放這裡
├── input/
│ ├── template.docx ← 本國收據範本
│ ├── template_foreign.docx ← 外國收據範本
│ └── all_apps_wide-*.csv ← 範例名冊（你的實際 CSV 也放這）
└── output/
└── receipts_時間戳/ ← 每次執行會建一個新資料夾，不會蓋掉舊的
├── 1_時間戳.docx ← 個別收據（每位受試者一份）
├── 2_時間戳.docx
├── ...
└── final_receipt_時間戳.docx ← 全部合併版
- 雙擊
GenReceipt.exe，視窗開啟後：- CSV 檔：手動選你要產收據的 CSV
- 本國範本 / 外國範本 / 輸出資料夾：第一次啟動會自動帶入預設路徑（指到
input/、output/）；之後會記住你上次選的路徑
- 確認「產生後合併成單一 final_receipt」要不要勾（預設勾）
- 按「執行」
- 完成後跳出提示，按「開啟輸出資料夾」可直接打開檔案位置
每次執行會產出：
- 個別收據：
{序號}_{時間戳}.docx（每位一份） - 合併版：
final_receipt_{時間戳}.docx（所有人合在一份檔案）
上次選的路徑會記在
%USERPROFILE%\.gen_receipt_config.json，下次啟動自動填回。
CSV 欄位名稱沿用 oTree 匯出格式（所有欄位都以 Stage_Payment_Info.1.player. 為前綴，下表為簡潔起見省略）。
| CSV 欄位（去前綴） | 對應 Word 合併欄位 | 內容 | 本國必填 | 外國必填 |
|---|---|---|---|---|
is_foreign |
（不合併，僅用來判斷套哪個範本） | 是 → 外國；其他（否 或空）→ 本國 |
✓ | ✓ |
school |
school |
學校 | ✓ | ✓ |
student_id |
student_id |
學號 | ✓ | ✓ |
name |
name |
姓名 | ✓ | ✓ |
address |
address |
地址 | ✓ | ✓ |
total_payment |
pay |
報酬金額（注意 CSV 與範本欄名不同） | ✓ | ✓ |
id_number |
id |
身分證字號（CSV 與範本欄名不同） | ✓ | — |
arc |
arc |
居留證號 | — | ✓ |
passport |
passport |
護照號碼 | — | ✓ |
nation |
nation |
國籍 | — | ✓ |
stay |
stay |
居留期間（例：6個月以上） |
— | ✓ |
CSV 內若還有其他欄位（例如 oTree 匯出常會帶
address_code郵遞區號等其他資料）會被忽略，不影響執行。
範例請參考 input/all_apps_wide-2026-05-19.csv。
判斷邏輯：程式只看 is_foreign 欄位 ——
是→ 用template_foreign.docx，會帶入 ARC / 護照 / 國籍 / 居留期間- 其他值（包含
否、空白）→ 用template.docx，會帶入身分證字號
CSV 編碼用 UTF-8；用 Excel 開時若中文亂碼，可改用 Excel 的「資料 → 從文字/CSV」匯入，並選擇 UTF-8。
兩個 Word 範本控制收據的版面、文字、表格樣式：
input/template.docx— 本國收據範本input/template_foreign.docx— 外國收據範本
- 用 Word 打開
.docx - 像編輯一般 Word 文件一樣修改：改文字、調字型、加表格邊框、改頁邊距等等
- 不要動到合併欄位（在 Word 裡看起來像
«name»、«pay»的灰底文字） - 存檔。下次跑
GenReceipt.exe就會用新的版面
如果只在 .docx 加了一個合併欄位、但程式碼裡沒對應的 mapping，那個欄位產出時會空白。如果要：
- 新增欄位：要在原始碼的
merge_datadict 加上 key → CSV 加對應欄位 → .docx 插入合併欄位 → 重 build .exe - 刪除欄位：移除 .docx 裡的合併欄位即可（程式碼裡保留 key 不會出錯）
原始碼不在這個 repo 內，需要請開發者修改後重新打包。
在 Word 裡用「插入 → 文件組件 → 功能變數 → MergeField」插入合併欄位，欄位名稱必須是以下清單之一：
兩個範本都可用：
| 欄位名稱 | 內容 |
|---|---|
experiment_id |
在 CSV 中的列序（從 1 開始） |
school |
學校 |
student_id |
學號 |
name |
姓名 |
address |
地址 |
pay |
報酬金額 |
year |
民國年（程式自動計算，例：2026 → 115） |
month |
月（執行當天的月份） |
day |
日（執行當天的日期） |
僅本國範本（template.docx）：
| 欄位名稱 | 內容 |
|---|---|
id |
身分證字號 |
僅外國範本（template_foreign.docx）：
| 欄位名稱 | 內容 |
|---|---|
arc |
居留證號 |
passport |
護照號碼 |
nation |
國籍 |
stay |
居留期間 |
**
year/month/day用的是執行 .exe 當天的日期，不是 CSV 內容。**這是為了讓收據日期反映「實際發放當天」，不是實驗發生當天。如果你需要的是別的日期邏輯，要改原始碼。
Q: 想分散式給多人用，每個人都要下載 250 MB 嗎？ A: 是。.exe 內含完整 Python 環境，所以才這麼大。優點是對方不用裝 Python。
Q: 第一次開啟很慢？
A: PyInstaller 單檔模式會把內含的套件解壓到 %TEMP%，第一次 5–15 秒正常。同一次開機之後的啟動都會快很多。
Q: 跑到一半說「找不到外國範本」？
A: CSV 裡有 is_foreign == 是 的列，但沒指定外國範本檔案。把外國範本路徑選上即可。
Q: 程式跑完但內容是空的？
A: 通常是 Word 範本裡的合併欄位名稱跟程式預期的不一樣。例如 .docx 寫 «pay_amount» 但程式給的是 pay，名稱沒對上就會空白。對照上面的欄位清單檢查。
Q: 想要程式不要每次都建子資料夾、直接放在 output/ 根目錄？ A: 需改原始碼。目前為了避免覆蓋舊收據才強制建子資料夾。
請見 Releases 頁面。