ChatGPT 接入向导
让你在 ChatGPT 里直接「把这张发票发给 CAU 记账」。
ChatGPT 把上传的文件通过 Actions 推到 CAU，写入 financial_inbox，
自动跑 ReceiptAgent 生成草稿仕訳，最终再由你在 CAU 系统里 approve。
🔗 它怎么工作？
整条链路 5 个角色：
┌──────────┐ 上传发票 ┌──────────┐ Action POST ┌──────────┐
│ 你 │ ─────────────▶ │ ChatGPT │ ─────────────▶ │ CAU │
│ (浏览器) │ "请把这张发票 │ Custom │ openaiFileIdRefs│ /gpt- │
│ │ 发给 CAU" │ GPT │ (含临时下载链接)│ actions │
└──────────┘ └──────────┘ └────┬─────┘
│ 下载文件
▼
financial_inbox
│ 自动跑
▼
ReceiptAgent
│ 生成
▼
仕訳草稿 (pending)
│ 你在 CAU
▼
审核 / 入账
⚠️ ChatGPT 只能"提交草稿"，不能直接入账。这是设计上的边界—— AI 错了你能回滚，最终 posting 一定要走 CAU 的 approval 流程。
ChatGPT 在 OpenAI 云端跑，不能访问你 127.0.0.1。 你需要把 CAU 暴露到一个 HTTPS 公网域名。3 种方式从快到慢：
方式 A: ngrok（最快、5 分钟）
免费版重启会换域名，调试合适；正式用买固定域名。
# 1. 装一次 choco install ngrok # 或去 https://ngrok.com/download # 2. 注册账号、贴 authtoken（一次性） ngrok config add-authtoken YOUR_TOKEN # 3. 启动隧道（CAU 后端跑在 8000） ngrok http 8000 # 输出会给你: https://xxxx-xxx.ngrok-free.app ← 这就是公网域名
方式 B: Cloudflare Tunnel（免费、域名固定、性能好）
# 装 cloudflared，登录绑你自己的域名 cloudflared tunnel login # 创建一个 tunnel cloudflared tunnel create cau # 把 cau.yourdomain.com 路由到本地 8000 cloudflared tunnel route dns cau cau.yourdomain.com cloudflared tunnel run --url http://localhost:8000 cau
方式 C: 部署到 Railway / Render / Cloud Run（生产环境）
项目已含 railway.toml 和 Dockerfile。Railway 一键部署最简单。
# Railway railway up # 或 Render: 在 dashboard 选 "New Web Service" 指向你的 GitHub repo # Cloud Run: gcloud run deploy cau --source .
在 CAU 后端环境变量里设两个值，避免任何人都能用你的 Actions 端点：
# .env（项目根目录）添加两行，随便生成两个长字符串 GPT_ACTION_CLIENT_ID=cau_action_REPLACE_ME GPT_ACTION_CLIENT_SECRET=用 openssl rand -hex 32 生成的随机串
⚠️ 改完 .env 后必须重启 server，环境变量才生效。
如果不设置这两个值，oauth/authorize 端点会跳过校验——本地测试可以，公网慎用。
ChatGPT Custom GPT 需要一个 OpenAPI YAML。下面这份是项目自带的
docs/CHATGPT_ACTION_OPENAPI.yaml，已把 servers.url 自动替换成你 Step 1 填的域名。
📄 预览 YAML 内容
加载中…
打开 chatgpt.com/gpts/editor → 新建 GPT → 切到 Configure tab → 拉到底 → 点 Create new action。
① Schema
把 Step 3 复制的 YAML 整段粘贴到 Schema 文本框。
② Authentication → OAuth
③ Instructions（Custom GPT 系统提示，建议加上）
④ 保存后
ChatGPT 会自动加一个 redirect URI（形如 https://chatgpt.com/aip/g-xxx/oauth/callback）。
我们后端对 chatgpt.com/aip/ 和 chat.openai.com/aip/ 都已 whitelist，不需要额外配置。
在你的 Custom GPT 对话框里输入下面任一句，验证整条链路：
把这张发票上传到 CAU 系统记账
5月福山運送費的請求書，請幫我提交給 CAU 生成草稿仕訳
预期：
- 第一次会跳 OAuth 授权 → 让你登录 CAU（如果还没登）→ 返回 ChatGPT 拿到 access_token
- ChatGPT 调用
uploadReceiptFiles，CAU 写financial_inbox - ReceiptAgent 自动跑，返回
agent_reply+request_id - 回到 CAU 主页 → 收件箱 / AI 自治记账，能看到那张草稿
本地直连测试（不经过 ChatGPT）
用下面这个按钮直接 ping /health，确认本地后端正常：
❓ FAQ
backend/modules/oauth/__init__.py 的 _allowed_redirect_uri，目前只接受 https://chatgpt.com/aip/ 和 https://chat.openai.com/aip/ 开头。要扩白名单就在这函数里加。download_link 已过期（OpenAI 临时链接 TTL 很短）。让用户在 ChatGPT 里重新上传触发新链接即可。代码里已经做了空文件 400 拒绝。status=pending。回 CAU → AI 自治记账页 → 找到那条 → ✗ 拒绝；同时收件箱里也会保留原文件，可重传。10 个文件，单文件 20 MB。超过会返回 400/413。auto_process 设为 false（或在 Custom GPT Instructions 里告诉它）。文件还是会进 financial_inbox，但不会立即生成仕訳草稿，等你在 CAU 里手动选 "🤖 让 AI 起票"。