使用说明
ContractGuard
作为人工智能工程案例研究构建的日本合同风险分析——LangGraph工作流+pgvector RAG+多模态摄入+可恢复流式用户体验。
⚠️ 不是法律服务。 该存储库从未进行过商业运营——《日本律师法》第72条为持牌律师保留了付费法律建议。代码库仅作为开源技术工件发布。输出不是法律意见。
状态
生产就绪的开源参考实现。全栈-- 前端、后端、OCR、支付、电子邮件、Postgres、Redis、错误跟踪 --与真正的集成连接在一起，随时可以部署。根据《律师法》第72条，它根本从未被启动过。
一份合成的日本合同被搁置 docs/samples/ 因此，克隆后可以立即端到端地执行本地流。
建筑
flowchart LR
U[React/Vite UI<br/>text, PDF, image upload] --> API[FastAPI routers]
API --> Q[Quote + PII + OCR budget guards]
Q --> PAY[KOMOJU checkout<br/>reference implementation]
PAY --> JOB[Persistent analysis job]
JOB --> SSE[Recoverable SSE stream<br/>status + events + after_seq]
JOB --> LG[LangGraph pipeline]
LG --> P[parse_contract]
P --> A[clause-by-clause risk analysis]
A --> T[tool call: analyze_clause_risk]
T --> RAG[(PostgreSQL pgvector<br/>331 Japanese legal articles)]
A --> S[tool call: generate_suggestion<br/>medium/high risks only]
S --> REP[report generation + translation]
REP --> CACHE[(Redis 72h report cache)]
REP --> DB[(PostgreSQL orders/reports/costs)]
技术栈
| 图层 | 堆栈 |
|---|---|
| 前端 | React、Vite、TypeScript、i18next（9种语言） |
| 后端 | FastAPI、SQLAlchemy异步、Alembic、APScheduler |
| AI工作流程 | LangGraph+OpenAI工具调用，MCP服务器 |
| RAG | PostgreSQL pgvector，331公共电子政务日本法规 |
| OCR | 谷歌云视觉(DOCUMENT_TEXT_DETECTION) |
| 存储 | PostgreSQL（订单/报告/事件），Redis（72小时缓存+速率限制） |
| 付款 | KOMOJU结账 |
| 电子邮件 | 重新发送 |
| 可观察性 | 哨兵+邮猪 |
| 基础设施 | Docker Compose（本地），Fly.io+Vercel（部署参考） |
快速入门（本地）
本地运行只需要 OpenAI API密钥.
cp .env.example .env
# Edit .env: set OPENAI_API_KEY
docker compose up --build
然后打开 http://localhost:5173 并上传 docs/samples/sample-contract-ja.txt.
在这种最小模式下：
- ✅ 纯文本合同和 基于文本的PDF （可选文本）端到端工作。
- ❌ 图像/扫描的PDF OCR 已禁用。要启用它，请添加
GOOGLE_APPLICATION_CREDENTIALS_JSON和GOOGLE_VISION_PROJECT_ID. - KOMOJU/在开发中重新发送自动绕过-没有真正的付款，没有真正的电子邮件。
生产设置
存储库的形状是通过设置来部署到生产环境中的 APP_ENV=production 并为每个外部服务提供证书：
| 服务 | 必需的环境变量 |
|---|---|
| OpenAI | OPENAI_API_KEY |
| 谷歌云视觉（OCR） | GOOGLE_APPLICATION_CREDENTIALS_JSON, GOOGLE_VISION_PROJECT_ID |
| KOMOJU（付款） | KOMOJU_SECRET_KEY, KOMOJU_PUBLISHABLE_KEY, KOMOJU_WEBHOOK_SECRET |
| 重新发送（电子邮件） | RESEND_API_KEY |
| 哨兵 | SENTRY_DSN, VITE_SENTRY_DSN |
| PostHog | POSTHOG_API_KEY, VITE_POSTHOG_KEY |
| 数据库/缓存 | DATABASE_URL （管理Postgres+pgvector）， REDIS_URL （托管Redis） |
| 应用程序 | FRONTEND_URL （非本地主机）， ADMIN_API_TOKEN |
当 APP_ENV=production，应用程序 拒绝开机 如果上述任何一项缺失或 FRONTEND_URL 仍然指向localhost。严格的验证逻辑存在 backend/config.py (validate_runtime()).
fly.toml 和 vercel.json 描述开发过程中使用的部署拓扑。该服务当前未托管。
流动
- 上传合同（文本、PDF或图像）。上传路线运行文本提取、PII检查、令牌估计、非合约检测和OCR预算保护。
- 签出参考路径创建订单。空KOMOJU凭据会在开发中触发本地旁路。
/review/:orderId启动或恢复持久分析作业，并流式传输页面刷新后的进度事件。- LangGraph解析子句，使用基于RAG的工具调用分析每个子句，并仅在风险需要时生成建议。
/report/:orderId显示保存的报告、条款摘录、风险过滤器和PDF导出，保留72小时。
分析后删除用户合同文本。矢量库仅包含公共电子政务法规；用户合约从未被嵌入。
演示
存储库映射
backend/agent/graph.py--LangGraph管道。backend/agent/tools.py--RAG接地工具调用。backend/services/analysis_executor.py--持续分析作业+事件源。backend/rag/store.py--pgvector存储和搜索。backend/config.py--运行时配置和严格验证。frontend/src/pages/ReviewPage.tsx--可恢复的分析进度UI。frontend/src/pages/ReportPage.tsx--带有风险过滤器和PDF导出的报告UI。tests/--后端pytest套件。scripts/smoke_local_flow.sh--端到端局部烟雾测试。
