{"id":47634261,"url":"https://github.com/poyuchenlaw/shanbot","last_synced_at":"2026-04-02T00:00:18.452Z","repository":{"id":342961818,"uuid":"1175444190","full_name":"poyuchenlaw/shanbot","owner":"poyuchenlaw","description":"Restaurant AI Assistant LINE Bot — Invoice OCR, Menu Management, Financial Reports, Tax Export. Built for small restaurants and catering companies.","archived":false,"fork":false,"pushed_at":"2026-03-29T10:00:16.000Z","size":633,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-03-29T13:32:46.954Z","etag":null,"topics":["accounting","ai","catering","fastapi","invoice","line-bot","ocr","paddleocr","python","restaurant","tax","traditional-chinese"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/poyuchenlaw.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-07T18:09:13.000Z","updated_at":"2026-03-29T10:00:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/poyuchenlaw/shanbot","commit_stats":null,"previous_names":["poyuchenlaw/shanbot"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/poyuchenlaw/shanbot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/poyuchenlaw%2Fshanbot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/poyuchenlaw%2Fshanbot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/poyuchenlaw%2Fshanbot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/poyuchenlaw%2Fshanbot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/poyuchenlaw","download_url":"https://codeload.github.com/poyuchenlaw/shanbot/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/poyuchenlaw%2Fshanbot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31293139,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T21:15:39.731Z","status":"ssl_error","status_checked_at":"2026-04-01T21:15:34.046Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["accounting","ai","catering","fastapi","invoice","line-bot","ocr","paddleocr","python","restaurant","tax","traditional-chinese"],"created_at":"2026-04-02T00:00:16.224Z","updated_at":"2026-04-02T00:00:18.408Z","avatar_url":"https://github.com/poyuchenlaw.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 小膳 Shanbot — AI 團膳內帳管理系統\n\n\u003e 拍發票、算菜成本、出月結報表、報稅匯出 — 全部在 LINE 上完成。\n\nShanbot 是一個開源的 LINE Bot，專為團膳公司與小型餐飲業者設計。透過 AI 驅動的發票 OCR、智慧菜單管理、自動財務報表，幫助餐飲業者從每天的紙本作業中解放出來。\n\n## 功能一覽\n\n| 功能 | 說明 |\n|------|------|\n| **拍照記帳（OCR）** | 拍照即辨識收據/發票 — 三引擎自動切換（PaddleOCR PP-OCRv5 → Gemini VLM → HunyuanOCR） |\n| **財務報表** | 月結 / 年結 / 資產負債表 / 損益表，一鍵生成（符合中小企業會計準則） |\n| **採購管理** | 供應商資料管理、食材行情自動同步、比價分析 |\n| **菜單企劃** | AI 菜單建議 + 成本估算 + 行銷海報圖片生成 |\n| **稅務匯出** | MOF 格式 / 會計軟體格式，報稅季資料自動整理，扣抵自動分類 |\n| **GDrive 歸檔** | 發票照片自動重命名、分類歸檔到 Google Drive |\n| **LINE 六宮格選單** | 拍照記帳 / 財務資料 / 採購管理 / 菜單企劃 / 報表生成 / 使用說明 |\n\n## 系統架構\n\n```\nLINE Messaging API\n       │\n       ▼\n  FastAPI (port 8025)  ←── PM2 process manager\n       │\n       ├── handlers/          → 指令路由 + 拍照 + 菜單對話 + Postback\n       ├── services/          → OCR + 財報 + 稅務 + 行情 + AI + GDrive\n       ├── state_manager.py   → SQLite 資料管理\n       └── task_manager.py    → 排程器 (心跳 + 市場同步 + 月結)\n\nLLM 三層降級：\n  Claude Code CLI → llm-router (Gemini/Groq fallback) → Gemini Direct API\n\nOCR 三引擎：\n  PaddleOCR PP-OCRv5（本地，最快）\n       ↓ 失敗\n  Gemini VLM（雲端，最準）\n       ↓ 失敗\n  HunyuanOCR via HF Inference（備援）\n\n部署：\n  PM2 + Cloudflare Tunnel (HTTPS) → LINE Webhook\n```\n\n## 專案結構\n\n```\nshanbot/\n├── main.py                → FastAPI webhook 入口 (port 8025)\n├── state_manager.py       → SQLite 資料管理\n├── task_manager.py        → 排程器 (心跳 + 市場同步 + 月結)\n├── ecosystem.config.js    → PM2 設定檔\n├── handlers/\n│   ├── command_handler.py → 指令路由\n│   ├── photo_handler.py   → 發票/收據拍照 OCR\n│   ├── menu_handler.py    → 菜單管理對話\n│   ├── file_handler.py    → 檔案上傳處理\n│   └── postback_handler.py → LINE Postback 處理\n├── services/\n│   ├── ocr_service.py     → 三引擎 OCR (PaddleOCR + Gemini + Hunyuan)\n│   ├── financial_report_service.py → 四大財務報表\n│   ├── tax_export_service.py → 稅務匯出 (MOF + 會計軟體)\n│   ├── market_service.py  → 食材行情同步\n│   ├── menu_ai_service.py → AI 菜單建議\n│   ├── gdrive_service.py  → Google Drive 歸檔\n│   ├── flex_builder.py    → LINE Flex Message 模板\n│   └── richmenu_service.py → LINE Rich Menu 管理\n├── config/\n│   ├── .env               → 環境變數（不入版控）\n│   └── .env.example       → 環境變數範本\n└── tests/                 → 測試\n```\n\n## 自行部署指南\n\n### 前置條件\n\n1. **Linux / WSL2 環境**（PaddleOCR 需要 Linux）\n2. **Python 3.10+**\n3. **Node.js 18+**（用於 PM2 進程管理）\n4. **Claude Code CLI**（`npm install -g @anthropic-ai/claude-code`，需 Anthropic API Key 或 Claude Pro/Max 訂閱）\n5. **LINE Messaging API 帳號**（至 [LINE Developers Console](https://developers.line.biz/console/) 建立 Channel）\n6. **Cloudflare Tunnel**（或其他 HTTPS 反向代理，如 ngrok）\n\n### 安裝\n\n```bash\ngit clone https://github.com/poyuchenlaw/shanbot.git\ncd shanbot\npython3 -m venv venv\nsource venv/bin/activate\npip install -r requirements.txt\n```\n\n### 設定環境變數\n\n```bash\ncp config/.env.example config/.env\n```\n\n用文字編輯器打開 `config/.env`，填入你的金鑰（詳見下方[環境變數說明](#環境變數說明)）。\n\n### 啟動\n\n```bash\n# 直接啟動\npython main.py\n\n# 或用 PM2 管理（推薦，自動重啟 + 日誌管理）\nnpm install -g pm2\npm2 start ecosystem.config.js\npm2 save\n```\n\nBot 會在 `http://localhost:8025` 啟動。\n\n### 設定 Webhook\n\n1. 用 Cloudflare Tunnel 或 ngrok 將 HTTPS 流量轉發到 `localhost:8025`\n2. 在 [LINE Developers Console](https://developers.line.biz/console/) 設定 Webhook URL 為你的公開 HTTPS URL + `/webhook`\n3. 驗證健康狀態：`curl http://localhost:8025/health` 應回傳 200\n\n### 一鍵部署提示詞\n\n安裝好 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) 後，在專案目錄執行 `claude` 並貼上以下提示詞，即可自動完成部署：\n\n```\n請幫我部署小膳 Shanbot 內帳系統：\n1. 建立 Python venv 並安裝 requirements.txt\n2. 複製 config/.env.example 為 config/.env，提示我填入：\n   - LINE_CHANNEL_SECRET 和 LINE_CHANNEL_ACCESS_TOKEN（從 LINE Developers Console 取得）\n   - GEMINI_API_KEY（從 Google AI Studio https://aistudio.google.com/apikey 免費取得）\n   （ADMIN_USER_ID 無需手動設定，第一位與 Bot 互動的使用者會自動成為管理員）\n3. 初始化 SQLite 資料庫\n4. 用 PM2 啟動服務：pm2 start ecosystem.config.js \u0026\u0026 pm2 save\n5. 設定 Cloudflare Tunnel 或 ngrok 將 HTTPS 流量轉發到 localhost:8025\n6. 在 LINE Developers Console 設定 Webhook URL 為你的公開 HTTPS URL + /webhook\n7. 建立 Rich Menu（6 格：拍照記帳/財務資料/採購管理/菜單企劃/報表生成/使用說明）\n8. 驗證：curl http://localhost:8025/health 應回傳 200\n```\n\n## 環境變數說明\n\n| 變數 | 必填 | 說明 | 取得方式 |\n|------|------|------|----------|\n| `LINE_CHANNEL_ID` | 選填 | LINE Channel ID | [LINE Developers Console](https://developers.line.biz/console/) → Channel 基本設定 |\n| `LINE_CHANNEL_SECRET` | **必填** | LINE Channel Secret | 同上 → Channel Secret |\n| `LINE_CHANNEL_ACCESS_TOKEN` | **必填** | LINE Channel Access Token | 同上 → Messaging API → 發行 Long-lived Token |\n| `GEMINI_API_KEY` | **必填** | Google Gemini API Key（OCR + AI 功能） | [Google AI Studio](https://aistudio.google.com/apikey)（免費額度） |\n| `GEMINI_MODEL` | 選填 | Gemini 模型名稱 | 預設 `gemini-2.5-flash` |\n| `LLM_ROUTER_URL` | 選填 | LLM Router 服務位址 | 自建 LLM Router，預設 `http://127.0.0.1:8010/chat` |\n| `HUNYUAN_OCR_API_KEY` | 選填 | HunyuanOCR 備援引擎 Token | [Hugging Face Tokens](https://huggingface.co/settings/tokens) |\n| `HUNYUAN_OCR_API_URL` | 選填 | HunyuanOCR API 端點 | 預設 `https://router.huggingface.co/hf-inference/models/tencent/HunyuanOCR` |\n| `EINVOICE_APP_ID` | 選填 | 電子發票 API App ID | [財政部電子發票平台](https://www.einvoice.nat.gov.tw) 申請 |\n| `EINVOICE_API_KEY` | 選填 | 電子發票 API Key | 同上 |\n| `GDRIVE_LOCAL` | 選填 | Google Drive 本地同步路徑 | 安裝 Google Drive 桌面版後的本地掛載路徑 |\n| `COMPANY_TAX_ID` | 選填 | 公司統一編號 | 用於稅務匯出 |\n| `COMPANY_TAX_REG_NO` | 選填 | 公司稅籍編號 | 用於稅務匯出 |\n| `COMPANY_NAME` | 選填 | 公司名稱 | 用於報表標題 |\n| `PUBLIC_BASE_URL` | 選填 | 公開 HTTPS URL | 你的 Cloudflare Tunnel / ngrok 網址 |\n| `PORT` | 選填 | 服務埠號 | 預設 `8025` |\n| `DB_PATH` | 選填 | SQLite 資料庫路徑 | 預設 `./data/shanbot.db` |\n| `LOG_LEVEL` | 選填 | 日誌等級 | `DEBUG` / `INFO` / `WARNING`，預設 `INFO` |\n\n## 排程自動化\n\n| 排程 | 頻率 | 功能 |\n|------|------|------|\n| HeartbeatScheduler | 每小時 | 系統健康檢查 |\n| MarketSyncScheduler | 每日 | 食材行情同步 |\n| MonthlySummaryScheduler | 每月 | 月結報表自動生成 |\n\n## 誰適合用？\n\n- 團膳公司（每天大量採購單、發票）\n- 小型餐廳（老闆兼會計，沒時間整理帳）\n- 早餐店 / 便當店（簡單記帳 + 成本控制）\n- 任何需要在 LINE 上管理餐飲財務的人\n\n## 報稅省時效果\n\n| 傳統方式 | 使用小膳 |\n|---------|---------|\n| 每天手動輸入發票 30 分鐘 | 拍照 3 秒自動辨識歸檔 |\n| 月底整理帳目 2-3 小時 | 一鍵生成月結報表 |\n| 報稅季整理 2-3 天 | 稅務匯出 1 分鐘完成 |\n| **每月耗時 ~20 小時** | **每月耗時 ~1 小時** |\n\n## 技術棧\n\nPython / FastAPI / SQLite / PaddleOCR / LINE Messaging API / Claude Code / Gemini API / PM2\n\n## Roadmap\n\n- [x] v1.0 — 基礎 OCR + 菜單 + 財務報表\n- [x] v2.0 — LINE 六宮格介面 + 市場行情 + 稅務匯出\n- [x] v2.3 — 稅務扣抵自動分類 + 菜單行銷海報\n- [x] v2.4 — 拍照記帳五項修復 + GDrive 歸檔強化\n- [ ] v3.0 — 食材主表建立 + 價格比對警報\n- [ ] v3.1 — Docker 一鍵部署\n- [ ] v3.2 — 多店管理（一個 Bot 管多家店）\n- [ ] v4.0 — 電子發票 API 串接（免拍照）\n\n## 授權\n\nMIT License — 免費使用、修改、商用。詳見 [LICENSE](LICENSE)。\n\n## 關於\n\n由[廣信法律會計事務所](https://kuangshin.tw)開發維護。我們相信好的工具應該免費給大家用。\n\n如果你是餐飲業者，除了帳務問題，遇到勞資糾紛、食安法規、租賃合約等法律問題，也歡迎聯繫我們。\n\n---\n\n*Built with FastAPI + PaddleOCR + LINE Messaging API + Claude AI + Gemini*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpoyuchenlaw%2Fshanbot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpoyuchenlaw%2Fshanbot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpoyuchenlaw%2Fshanbot/lists"}