Discord 建檔、揪團、點餐、結算;校內網站只負責查閱。
金額由程式依庫內價格計算,模型不得自行定價。
實驗室中午要點什麼、誰點了什麼、最後誰該付多少——這件事不該再散落在十則訊息裡。
AIPARC ETA 把餐廳菜單、論壇揪團與帳本收進同一套系統:寫入走 Discord bot,查閱走校內網站,資料放 PostgreSQL。自然語言與菜單辨識只用免費 LLM API。菜單對帳 OCR(PP-OCRv6 small)是本 Repository ocr/ sidecar,Compose 會一起啟動;沒設 OCR_BASE_URL(且不走 Compose)才略過。沒有金鑰時按鈕與下拉仍可點餐。
現況(0.2.0 + Unreleased) 三個產品功能已落地;這一輪再依
PLAN/AEPARC_EAT_Revise_1.md補上直書菜單對帳(本 Repository OCR 容器)、自然語言取消/查帳/推薦、誰欠誰、對話記憶、防幻覺,以及網站儀表板與深淺色。 離線測試 77 項、npm run smoke、npm run route:check與本機網站頁面已通過。Discord 端的真人操作尚未驗收(含/記憶);指令表有增減,部署後請跑npm run register。
|
|
|
|
| 還有這些 | 為什麼這樣做 |
|---|---|
| 直書菜單也讀得出來 | 本 Repository ocr/(PP-OCRv6 small ONNX)先算出版面方向與閱讀順序,再交給視覺模型,最後回頭對帳標出沒核對上的行。權重在 ocr/models/。 |
| 不會編菜單給你 | 判準是「資料庫答得了嗎」:答得了就用資料庫回(菜單、品項、推薦都來自 menu_items),答不了才交給模型,而且回完還要過一次守門。 |
| 記得住 | 短期記得這個頻道最近的對話,長期記得你明講要它記的事(/記憶),也認得出伺服器、頻道與是誰在問。 |
| 校內網站唯讀 | 沒有公有網域;寫入只留一條授權路徑(Discord)。 |
| 深淺色與無障礙 | 主題切換走 View Transitions 的圓形遮罩;系統設為減少動態時完全不做動畫。 |
| 規則優先、模型墊底 | 對得到就不打 LLM,省免費層配額,結果也比較可預測。 |
價格只來自 menu_items |
模型負責「指到哪一項、要幾份」,不得改帳。 |
| 繁中/英式英文 | Discord 語言為中文(繁/簡)時畫面用繁體中文,其餘用英式英文。 |
網站畫面為 2026-09-18 本機實拍(儀表板、品牌標誌、導覽列)。Discord 為 2026-09-19 論壇貼文實拍。
http://<伺服器內網IP>:3000/。樣式內嵌;深淺色切換存在本機,系統設為減少動態時不做動畫。/設定 論壇 頻道:#訂餐
/設定 通知 身分組:@訂餐
↓
/餐廳 新增 四海豆漿大王
↓
/菜單 上傳 (或 /菜單 輸入)→ 核對草稿(含 OCR 標記,若有)→ 確認寫入
↓
/揪團 餐廳 + 截止分鐘 + 可選收款人 → 論壇貼文(可 ping 身分組)
↓
按「點餐」選數量與品項,或打字 「我要兩個蛋餅跟一杯豆漿」
↓
「取消豆漿」/截止後顯示「截止」
↓
/結算 → /帳務 誰欠誰 · /帳務 我的 · /記憶 我的 · /網站
網站對應頁面:/ 儀表板、/restaurants/:id 菜單、/sessions/:id 該場彙總、/ledger/:guild-id 誰欠誰。
@ 一下就可以用自然語言問事情。能從資料庫查到的,一律不交給模型:
「四海豆漿大王有甚麼好吃的」 → 那家還沒建菜單 → 照實說不知道(不會編菜給你)
「有沒有豆腐鍋可以吃」 → 查 menu_items → 列出真的有的店家與價格
「推薦吃甚麼」「幫我挑」 → 從菜單抽幾樣真的存在的給你選
「給我麵店」 → 先問「你是說老余麵店嗎?」再給菜單
「我還欠多少」「誰欠我錢」 → 查帳本 → 帳務 Embed
「記住我不吃牛」 → 寫進長期記憶,之後都記得
「你有記憶功能嗎」 → 程式照實回答記得多少,不讓模型自己說
「你喜歡賽馬娘嗎」「今天天氣真好」 → 資料庫答不了,交給模型接話;回完還要過一次守門
改過自然語言流程之後,用 npm run route:check 拿真實資料庫確認每句話會走到哪一條路。
flowchart LR
D[Discord 使用者] --> B[bot 容器]
C[校內瀏覽器] --> W[web 容器]
B --> P[(PostgreSQL 18.6)]
W --> P
B --> L[免費 LLM API<br/>Groq / Gemini / Mistral]
B --> O[ocr 容器<br/>PP-OCRv6 small]
L -.-> B
兩個入口共用資料庫,都不直接寫 SQL:bot 與 web 只呼叫 db/ 與 domain/。LLM 閘道走 OpenAI 相容 wire format,換一家只換 base_url、金鑰、模型 ID,不引任何 LLM SDK。OCR 是本 Repository ocr/ 的獨立容器(映像 aiparc-eta:ocr),不要跑在 bot 行程裡;web 與 bot 共用映像 aiparc-eta:app。
| 層 | 目錄 | 可以依賴 |
|---|---|---|
| 共用 | src/shared/ |
無 |
| 資料 | src/db/ |
shared |
| 業務 | src/domain/ |
shared、db 型別 |
| 模型 | src/llm/ |
shared、domain |
| 入口 | src/bot/、src/web/ |
以上皆可;彼此不互相 import |
契約與拓樸寫在 SPEC/。產品意圖在 PLAN/plan_initial.md,這一輪修訂在 PLAN/AEPARC_EAT_Revise_1.md。衝突時:程式碼 > SPEC > PLAN。
需要 Docker Engine 28+(Compose v2/v5)與已填寫的 .env。本機開發另需 Node.js ≥ 24.12。
Copy-Item .env.example .envcp .env.example .env至少填 POSTGRES_DB、POSTGRES_USER、POSTGRES_PASSWORD。Discord 權杖與 LLM 金鑰可稍後再補:沒填時 bot 只維持健康檢查,網站與資料庫仍可啟動。
校內要讓 Embed 與 /網站 帶得出連結,再填 PUBLIC_BASE_URL(例如 http://10.0.0.12:3000)。Compose 會把 bot 的 OCR_BASE_URL 覆寫成 http://ocr:8868,不必在 .env 填;本機直接跑 npm run start:bot 才指 http://127.0.0.1:8868。權重若遺失,在 ocr/ 執行 node scripts/fetch-models.ts。
遷移會在 web/bot 啟動時自動套用,不必另下指令。
docker compose up --build -d
docker compose ps四個服務(postgres、ocr、web、bot)都應為 healthy。瀏覽器或 curl 開 http://127.0.0.1:3000/health,應看到 ok: true 與資料庫時間;OCR 探針在 http://127.0.0.1:8868/health。
- 開發者後台 → Bot → Privileged Gateway Intents → 打開 Message Content Intent。沒開的話自然語言點餐與貼菜單都會拿到空字串。
- 邀請時至少要有:檢視頻道、發送訊息、在討論串發送訊息、建立貼文、嵌入連結、加上反應。
- 在伺服器裡指定論壇頻道,
/揪團才有地方開貼文;要開團時 ping 身分組再設通知:
/設定 論壇 頻道:#訂餐
/設定 通知 身分組:@訂餐
這一輪指令表有增減(拿掉 /點餐、新增 /網站 與 /記憶、截止改成整數分鐘)。部署後請跑 npm run register(或 docker compose exec bot node src/scripts/register-commands.ts)。
| 指令 | 用途 | 需要 |
|---|---|---|
npm run check |
型別檢查 + 77 項離線測試 | — |
npm test |
只跑測試 | — |
npm run smoke |
建檔→菜單→揪團→點餐→結算→帳務,跑完自清 | 資料庫 |
npm run route:check |
拿真實資料庫驗自然語言路由(該擋在模型前的還擋著) | 資料庫 |
npm run llm:check |
每家供應商實際打一次 | 金鑰、外網 |
npm run register |
重新註冊斜線指令 | Discord 權杖 |
停止容器:docker compose down(資料卷會保留)。連資料一併刪除是 docker compose down -v,先確認。
校內 24/7 伺服器、備份與連續運行注意事項見 DEPLOY.md。
AIPARC-ETA/
├── src/
│ ├── web.ts / bot.ts 行程進入點
│ ├── config.ts 環境變數(缺必要值就失敗並印變數名)
│ ├── shared/ 時間、金額、文字正規化、日誌
│ ├── db/ 一張表一個模組;遷移在 db/sql/
│ ├── domain/ 菜單正規化、點餐彙總、結算、債務、OCR 對帳
│ ├── llm/ 供應商、換手、任務提示詞、OCR 客戶端
│ ├── bot/ 指令、元件、訊息、在地化字串
│ ├── web/ 頁面與唯讀 JSON API
│ └── scripts/ smoke、llm-check、register-commands、route-check
├── logo/ 標誌原稿;網站 `/assets/` 與 Embed 縮圖從這裡讀
├── test/ node:test 離線測試(也是行為說明書)
├── SPEC/ 架構與資料契約
├── PLAN/ 規劃草稿、修訂清單與菜單範例圖
├── docs/ 英文 README、貢獻指南、Hero/Demo 圖
├── compose.yaml postgres / ocr / web / bot
├── ocr/ PP-OCRv6 small sidecar(權重在 models/)
├── LICENSE MIT(程式與文件)
├── TRADEMARKS.md AIPARC 名稱與組織標誌
├── DEPLOY.md 校內部屬
└── CHANGELOG.md 變更紀錄
根目錄 requirements.txt 依現況不列 pip 套件——這不是 Python 專案。應用相依以根目錄 package.json 為準;OCR sidecar 另有 ocr/package.json(onnxruntime-node、sharp),不要裝進 bot 映像。
斜線指令(中文 ≤ 6 字,英文 ≤ 10 字母)
| 英文(預設) | 中文 | 作用 |
|---|---|---|
/restaurant |
/餐廳 |
新增/清單/資訊 |
/menu |
/菜單 |
查看、上傳、輸入、版本 |
/groupbuy |
/揪團 |
開論壇貼文;截止時間填分鐘數 |
/settle |
/結算 |
結算並寫入帳本 |
/ledger |
/帳務 |
我的/總覽/誰欠誰/付款 |
/memory |
/記憶 |
我的/記住/忘記 |
/help |
/說明 |
使用說明 |
/website |
/網站 |
網站連結按鈕 |
/setup |
/設定 |
指定揪團論壇與通知身分組(需管理伺服器權限) |
貼文裡點餐用按鈕或直接打字,不需要另一支斜線指令;/點餐 已在 Unreleased 移除。
restaurant 選項開自動完成,回傳值是資料庫 id。完整流程見 SPEC/bot-interactions.md。
網站頁面與唯讀 API
| 路徑 | 內容 |
|---|---|
GET / |
儀表板:數字卡、最近揪團與餐廳 |
GET /restaurants · /restaurants/:id |
餐廳清單與上線中的菜單 |
GET /sessions · /sessions/:id |
揪團清單與該場全體清單、每人應付 |
GET /ledger · /ledger/:guild-id |
誰欠誰、最少轉帳建議、個人結餘 |
GET /status |
資料庫、LLM 用量與各伺服器使用情形 |
GET /assets/logo.svg |
標誌(白名單靜態檔,Embed 也用同一組位址) |
GET /health |
服務與資料庫時間 |
GET /api/overview |
儀表板彙總 |
GET /api/restaurants |
keyword 可篩選 |
GET /api/sessions |
guild 可篩選,最近 30 場 |
GET /api/ledger/:guild-id |
每個人的結餘 |
GET /api/debts/:guild-id |
誰欠誰與最少轉帳建議 |
GET /api/llm-usage |
hours 預設 24 |
金額在 JSON 裡以元為單位。非 GET 回 405。契約見 SPEC/web-api.md。
環境變數(名稱,不含祕密)
| 變數 | 必要 | 說明 |
|---|---|---|
POSTGRES_* |
✓ | 資料庫連線。容器內 POSTGRES_HOST 覆寫成 postgres、POSTGRES_PORT 覆寫成 5432;.env 的 POSTGRES_PORT 只影響主機對映 |
APP_HOST / APP_PORT |
網站,預設 0.0.0.0:3000 |
|
BOT_HEALTH_PORT |
bot 健康檢查,預設 3001 |
|
TZ |
預設 Asia/Taipei |
|
DISCORD_BOT_TOKEN / DISCORD_CLIENT_ID |
bot 要用時 | 沒填就不連 Discord、不註冊指令 |
*_API_KEYS |
逗號分隔多把;留空=跳過該供應商 | |
*_MODEL / *_VISION_MODEL |
有金鑰沒填模型 ID=跳過並記原因,不拿猜的 ID 去打 | |
LLM_ALLOW_METERED |
true 才啟用標成計費的供應商;iAI 為免費層,不需開 |
|
LOCAL_LLM_BASE_URL |
本機模型保底;不要在容器內跑本地 LLM | |
PUBLIC_BASE_URL |
網站對外位址;Embed 標誌與 /網站 的連結按鈕用它 |
|
OCR_BASE_URL |
菜單對帳 OCR。Compose 覆寫成 http://ocr:8868;本機直跑 bot 才填 http://127.0.0.1:<OCR_HOST_PORT> |
|
OCR_HOST_PORT |
主機對映 OCR 的埠,預設 8868;容器內仍聽 8868 |
|
OCR_TIMEOUT_MS |
Compose 給 60000;程式預設 20000 |
範本與註解在 .env.example。.env 不進 Git、不進映像。
LLM 閘道與兩條紅線
供應商:Groq(文字第一棒)→ Gemini(視覺第一棒)→ Mistral → iAI → 本機。iAI 為校內免費層。
- 空回覆或要 JSON 卻挖不出來視為該家失敗並換下一家(Gemini 免費層常把 token 花在思考上,或回一段無法解析的字)。
- 429/5xx 同一把重試一次再換手;401/403 立刻換下一把。
- 菜單圖片辨識與文字模型分開排隊。Compose 會先打本 Repository
ocr/的 PP-OCRv6 small 對帳;只標記不改草稿。menu-vision/menu-text開require_json。
紅線:價格永遠查 menu_items;規則對得到就不呼叫模型。細節見 SPEC/llm-gateway.md。採用前請跑 npm run llm:check,價目表上有的模型不一定打得到。
執行時期(2026-09-18 查證)
- Node.js 24 Active LTS(Krypton),≥ 24.12 以 type stripping 直接跑
.ts,無建置步驟 - PostgreSQL 18.6(
postgres:18.6-alpine;19 當時仍為 beta) - discord.js 14.27、
pg8.23 - 映像:
web/bot共用aiparc-eta:app(node:24-bookworm-slim,非 rootnode,COPY logo ./logo);OCR 另建aiparc-eta:ocr - 編排檔:
compose.yaml(Compose Specification,不含過時的version欄);postgres與ocr埠只綁127.0.0.1 - 品牌色取自標誌:金
#eabf29、藍#259fc8(網站與 Embed 共用)
實驗室內部專案。改程式前請讀 CONTRIBUTING.md(English)與 .cursorrules。
簡要約定:變數/函式 snake_case;註解與維護者錯誤訊息用繁體中文;動到契約要同步 SPEC/;每次變更更新 CHANGELOG.md 的 Unreleased(Keep a Changelog 2.0.0;發版才給新版號);npm run check 要全綠。不要抄隔壁 AIPAR-ordering-system 的程式或架構。
程式與文件以 MIT License 授權。
實驗室 AIPARC 的名稱、名義與組織標誌不在 MIT 範圍內。 不得拿去當自己專案、服務或 fork 的品牌,也不得暗示為實驗室官方產品。事實陳述(例如「改自 AIPARC ETA」)可以。細節見 TRADEMARKS.md。
package.json 的 "private": true 只表示不要發到 npm Registry,與著作權授權無關。
第三方維持原授權:npm 相依套件見各自的 license 欄;ocr/models/ 的 PP-OCRv6 small ONNX 權重來自 PaddleOCR,為 Apache-2.0。.env、資料庫內容與 Discord 權杖不在授權範圍,也不該進版本控制。

