悠遊卡對帳流程 — 寶星停車

系統資訊

正式機	start_parking.kuch.com.tw
Odoo 版本	17.0
模組	starparking_custom
Model	sp.easycard.settlement

停車場資訊

名稱	楊梅富岡
手續費率	2.1%
撥款週期	D+1
悠遊卡平台	cmas-merchant.easycard.com.tw

驗證結果 (2026-04-01)

測試單號	ECS00001
測試區間	3/25 - 3/31
載入筆數	396 筆
功能狀態	正常

對帳單狀態流程

草稿

→

已確認

→

完成

狀態說明： 草稿 = 可編輯、載入明細；已確認 = 明細比對完成、停車記錄標記為已對帳/未匹配；完成 = 對帳結案。

操作步驟

進入悠遊卡對帳頁面

或直接使用 URL：

https://start_parking.kuch.com.tw/web#action=519&view_type=list

新增對帳單

點擊新增按鈕，系統自動產生對帳單號（ECS00001, ECS00002...）。

填入以下欄位：

欄位	說明	範例
`起始日期`	對帳起始日	2026-03-25
`結束日期`	對帳結束日	2026-03-31
`停車場`	預設楊梅富岡	楊梅富岡
`手續費率(%)`	預設 2.1%	2.10

載入停車明細

點擊載入明細按鈕。

系統會搜尋該日期區間內、收費方式為「悠遊卡」的所有停車出場記錄，並連結到此對帳單。

注意：重複點擊「載入明細」會先清除舊的連結，再重新載入。不會產生重複資料。

載入後自動計算：

計算公式

悠遊卡總金額 = 所有悠遊卡停車記錄金額加總

手續費 = 總金額 × 2.1% (四捨五入到小數第 2 位)

預期撥款金額 = 總金額 - 手續費

差異金額 = 實際撥款金額 - 預期撥款金額

填入實際撥款金額

登入悠遊卡商店帳務平台，查詢該期間的撥款總額。

項目	值
平台網址	https://cmas-merchant.easycard.com.tw:7090
商店代號	08760482
帳號	08760482B

將查到的撥款金額填入 實際撥款金額 欄位。差異金額會自動更新。

理想結果：差異金額 = 0（或接近 0），代表撥款金額與停車收入一致。

確認對帳

點擊確認對帳按鈕。

系統會根據差異金額自動判斷：

條件	停車記錄標記	說明
`\|差異\| < 1 元`	已匹配 (matched)	金額吻合
`\|差異\| ≥ 1 元`	未匹配 (unmatched)	需人工檢查

對帳單狀態從「草稿」變為「已確認」。

完成對帳

確認無誤後，點擊完成按鈕結案。

對帳單狀態變為「完成」，整個對帳流程結束。

測試驗證結果

ECS00001 測試對帳單

日期區間：2026-03-25 ~ 2026-03-31

交易筆數：396 悠遊卡筆數：396 總金額：22,190.00 手續費：465.99 預期撥款：21,724.01

功能	結果	說明
建立對帳單	PASS	ECS00001 自動編號正常
載入明細	PASS	396 筆悠遊卡記錄正確載入
金額計算	PASS	22,190 × 2.1% = 465.99, 22,190 - 465.99 = 21,724.01
序號產生	PASS	ir.sequence ECS + 5 碼
停車場預設	PASS	楊梅富岡
手續費率預設	PASS	2.10%

資料模型

sp.easycard.settlement (悠遊卡對帳單)

欄位	類型	說明
`name`	Char	對帳單號（自動序號 ECSxxxxx）
`date_from`	Date	起始日期
`date_to`	Date	結束日期
`parking_lot`	Char	停車場（預設楊梅富岡）
`fee_rate`	Float	手續費率 %（預設 2.1）
`actual_amount`	Float	實際撥款金額（手動填入）
`total_records`	Integer	交易筆數（computed）
`easycard_count`	Integer	悠遊卡筆數（computed）
`total_parking_amount`	Float	悠遊卡總金額（computed）
`fee_amount`	Float	手續費（computed）
`expected_amount`	Float	預期撥款金額（computed）
`difference`	Float	差異金額（computed）
`record_ids`	One2many	關聯停車明細（sp.parking.record）
`state`	Selection	草稿 / 已確認 / 完成
`note`	Text	備註

sp.parking.record 關聯欄位

欄位	類型	說明
`settlement_id`	Many2one	所屬對帳單
`reconcile_state`	Selection	待對帳 / 已匹配 / 未匹配
`payment_method`	Selection	收費方式（悠遊卡 = easycard）

停車明細擷取腳本

對帳前須確保停車明細已從 PLS API 擷取到 Odoo。

# PLS API 版（推薦）— 自動分段查詢，含發票資訊
python scripts/fetch_parking_api.py --date-from 2026-03-25 --date-to 2026-03-31

# 指定正式機 Odoo
python scripts/fetch_parking_api.py \
  --odoo-url http://localhost:8069 \
  --odoo-db start_parking \
  --odoo-user admin \
  --odoo-password Admin123

# Playwright 版（備用）— 從網頁 UI 擷取
python scripts/fetch_parking_records.py --date-from 2026-03-25 --date-to 2026-03-26

PLS API 限制：單次查詢最大 7 天區間，腳本會自動分段。防重複機制：unique(card_number, out_time, company_id)。

常見問題

Q: 差異金額不為零怎麼辦？

可能原因 1	悠遊卡結算批次時間不完全對齊日曆日（Sharon 用 13:03~23:59 篩選）
可能原因 2	跨日交易歸屬不同（出場時間 vs 結算時間）
可能原因 3	部分交易被退款或異常扣款
處理方式	調整日期區間或在備註欄記錄差異原因

Q: 載入明細為 0 筆？

可能原因 1	該日期區間沒有執行 PLS API 擷取腳本
可能原因 2	日期範圍設定錯誤
處理方式	先執行 fetch_parking_api.py，再回來載入明細

Q: 可以重新載入明細嗎？

可以	在草稿狀態下，再次點擊「載入明細」會先清除舊連結再重新載入
注意	已確認或完成狀態下無法載入（按鈕隱藏）