ContractGuard

作为 AI 工程案例研究构建的日本合同风险分析工具 — LangGraph 工作流 + pgvector RAG + 多模态摄入 + 可恢复的流式 UX。

⚠️ 非法律服务。 本仓库从未进行商业运营 — 日本《律师法》第 72 条（弁護士法第72条）规定有偿法律咨询仅限持牌律师。本代码库仅作为开源技术工件发布。输出内容不构成法律意见。

中文文档 | 日本語 | License

状态

生产就绪的开源参考实现。全栈架构 — 前端、后端、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)]

技术栈

快速开始 (本地)

本地运行仅需一个 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 / Resend — 无真实支付，无真实邮件。

生产环境设置

本仓库通过设置 APP_ENV=production 并为每个外部服务提供凭据来部署到生产环境：

当 APP_ENV=production 时，如果缺少上述任何内容或 FRONTEND_URL 仍指向 localhost，应用将拒绝启动。严格验证逻辑位于 backend/config.py (validate_runtime()) 中。

fly.toml 和 vercel.json 描述了开发过程中使用的部署拓扑。该服务目前未托管。

流程

1. 上传合同（文本、PDF 或图像）。上传路由执行文本提取、PII 检查、Token 估算、非合同检测和 OCR 预算防护。

2. 结账参考路径创建订单。在开发环境中，空的 KOMOJU 凭据会触发本地绕过。

3. /review/:orderId 启动或恢复持久化分析作业，并流式传输在页面刷新后依然有效的进度事件。

4. LangGraph 解析条款，通过基于 RAG 的工具调用分析每个条款，并仅在风险需要时生成建议。

5. /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 — 端到端本地冒烟测试。