yuqei/ai-contract-platform
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Refactor contract platform workflows and UI

Browse Source
This commit is contained in:
yuqei
2026-06-21 09:14:36 +08:00
parent 93089e2a89
commit a89f4c7050
113 changed files with 12367 additions and 1504 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/DEPLOYMENT.md
-346
View File
@@ -1,346 +0,0 @@
# AI Contract Platform 生产部署指南
> 本文档记录了实际部署过程中遇到的问题和解决方案，避免以后部署走弯路。
## 部署架构
| 组件 | 部署位置 | 目录 | 端口 |
|------|---------|------|------|
| 前端 Next.js | 阿里云 ECS (47.94.178.212) | `/opt/apps/ai-contract-web/current` | 容器内 3000 |
| 前端 Gateway | 阿里云 ECS | 同上 | 127.0.0.1:18083 |
| 后端 FastAPI | 192.168.3.90 | `/opt/apps/ai-contract-platform` | 8001:8000 |
| 后端 Gateway | 192.168.3.90 | `/opt/apps/ai-contract-platform-gateway` | 10.20.0.11:18083 |
| PostgreSQL | 192.168.3.90 | - | 5432 |
| Redis | 192.168.3.90 | - | 6379 |
| MinIO | 192.168.3.90 | - | 9000 |
**域名**: `contact.yuqei.com`
**流量路径**:
```
contact.yuqei.com → 阿里云 nginx (127.0.0.1:18083)
├── /api/ → 后端服务器 10.20.0.11:18083 → backend:8000
├── /health → 后端服务器 health check
└── 其他 → 阿里云 Next.js 容器:3000
```
## 构建注意事项（重要！）
### ⚠️ Git Bash 路径转换问题
**问题**: 在 Windows Git Bash 环境下构建 Next.js 时，环境变量 `/api/v1` 会被错误地转换成 Windows 路径 `C:/Program Files/Git/api/v1`。
**解决方案**: 使用 `MSYS_NO_PATHCONV=1` 环境变量防止路径转换：
```bash
# 正确的构建命令（在 Git Bash 中执行）
MSYS_NO_PATHCONV=1 NEXT_PUBLIC_API_BASE_URL="/api/v1" BACKEND_BASE_URL="http://10.20.0.11:18083" npm run build
```
**错误示例**:
```bash
# 这会导致 API_BASE_URL = "C:/Program Files/Git/api/v1"
NEXT_PUBLIC_API_BASE_URL=/api/v1 npm run build
# 这会导致 API_BASE_URL = "//api/v1"，浏览器解析为 "http://api/v1"
NEXT_PUBLIC_API_BASE_URL="//api/v1" npm run build
```
### Next.js 环境变量特性
**关键点**: `NEXT_PUBLIC_*` 和 `BACKEND_BASE_URL` 是**构建时**嵌入的环境变量，运行时设置无效！
- `NEXT_PUBLIC_API_BASE_URL` - 嵌入到浏览器 JS 中，用于客户端 API 请求
- `BACKEND_BASE_URL` - 嵌入到 `server.js` 中，用于 Next.js rewrites（服务器端代理）
构建后这些值被硬编码到 JS 文件中，docker-compose 的 environment 设置无法覆盖。
## 部署步骤
### 1. 本地构建前端
```bash
cd frontend
# 使用 MSYS_NO_PATHCONV=1 防止 Git Bash 路径转换
MSYS_NO_PATHCONV=1 NEXT_PUBLIC_API_BASE_URL="/api/v1" BACKEND_BASE_URL="http://10.20.0.11:18083" npm run build
# 打包 standalone 输出
rm -rf .next/standalone/.next/static
cp -r .next/static .next/standalone/.next/
tar -czf frontend-standalone.tar.gz -C .next/standalone .
```
### 2. 上传到阿里云
```bash
scp frontend-standalone.tar.gz root@47.94.178.212:/tmp/
```
### 3. 在阿里云部署
```bash
ssh root@47.94.178.212
# 解压到 app 目录
cd /opt/apps/ai-contract-web/current/app
rm -rf .next server.js node_modules public
tar -xzf /tmp/frontend-standalone.tar.gz
# 重启容器
cd /opt/apps/ai-contract-web/current
docker compose down
docker compose up -d --build
```
### 4. 后端部署（192.168.3.90）
> 当前线上目录 `/opt/apps/ai-contract-platform` 可能是发布包解压目录，不一定是 Git 工作区。
> 执行 `git pull` 前必须先确认 `git rev-parse --is-inside-work-tree` 返回 `true`。
#### 方式 A：服务器目录是 Git 工作区
```bash
ssh root@192.168.3.90
cd /opt/apps/ai-contract-platform
git rev-parse --is-inside-work-tree
git pull origin main
docker compose -f docker-compose.server.yml build backend legal-change-impact-worker
docker compose -f docker-compose.server.yml up -d backend legal-change-impact-worker
```
#### 方式 B：服务器目录是发布包目录（当前线上常见形态）
此方式用于后端单独热修复或后端发布包部署。发布前先备份将被覆盖的文件，发布后只重建后端服务，避免无关前端变更进入线上。
```bash
# 本地同步修复文件示例
scp backend/vendor/shared-ai-platform-sdk/shared_ai_platform_sdk/client.py \
root@192.168.3.90:/opt/apps/ai-contract-platform/backend/vendor/shared-ai-platform-sdk/shared_ai_platform_sdk/client.py
# 服务器上重建并重启后端相关容器
ssh root@192.168.3.90
cd /opt/apps/ai-contract-platform
docker compose -f docker-compose.server.yml build backend legal-change-impact-worker
docker compose -f docker-compose.server.yml up -d backend legal-change-impact-worker
```
发布后检查：
```bash
docker ps --format "table {{.Names}}\t{{.Status}}" | grep ai-contract-platform
docker logs --since 5m ai-contract-platform-backend-1
```
## 配置文件
### docker-compose.yml（阿里云前端）
```yaml
services:
ai-contract-web:
build:
context: ./app
dockerfile: Dockerfile
image: local/ai-contract-web:0.0.1
container_name: ai-contract-web
restart: unless-stopped
environment:
NODE_ENV: production
HOSTNAME: 0.0.0.0
PORT: 3000
# 注意：以下环境变量在运行时设置无效，必须在构建时设置
# BACKEND_BASE_URL: http://10.20.0.11:18083
# NEXT_PUBLIC_API_BASE_URL: /api/v1
extra_hosts:
- "10.20.0.11:host-gateway" # 让容器能访问内网 IP
networks:
- ai-contract-web-proxy
ai-contract-web-gateway:
image: nginx:1.27-alpine
container_name: ai-contract-web-gateway
restart: unless-stopped
ports:
- "127.0.0.1:18083:80"
volumes:
- ./nginx/web-gateway.conf:/etc/nginx/conf.d/default.conf:ro
- /opt/apps/ai-contract-web/logs/nginx:/var/log/nginx
depends_on:
- ai-contract-web
networks:
- ai-contract-web-proxy
networks:
ai-contract-web-proxy:
name: ai-contract-web-proxy
```
### nginx/web-gateway.conf（阿里云）
```nginx
upstream ai_contract_web {
server ai-contract-web:3000;
}
upstream ai_contract_api {
server 10.20.0.11:18083; # 后端服务器 gateway
}
server {
listen 80;
server_name contact.yuqei.com;
charset utf-8;
client_max_body_size 100m;
# API 代理到后端服务器
location /api/ {
proxy_pass http://ai_contract_api/api/;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_buffering off;
proxy_connect_timeout 10s;
proxy_send_timeout 300s;
proxy_read_timeout 300s;
}
# 前端 Next.js
location / {
proxy_pass http://ai_contract_web;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
}
```
## 默认账号
| 账号 | 密码 | 角色 |
|------|------|------|
| admin@example.com | 123456 | admin |
## 常见问题排查
### 1. 登录报"网络异常"
**原因**: `NEXT_PUBLIC_API_BASE_URL` 构建时值错误（如 `C:/Program Files/Git/api/v1` 或 `//api/v1`）
**排查**:
```bash
# 检查部署的 JS 文件中的 API_BASE_URL
curl -s 'http://contact.yuqei.com/_next/static/chunks/*.js' | grep -oP 'tl="[^"]*"'
# 正确值应为: tl="/api/v1"
# 错误值: tl="C:/Program Files/Git/api/v1" 或 tl="//api/v1"
```
**解决**: 使用 `MSYS_NO_PATHCONV=1` 重新构建前端
### 2. 容器无法访问后端
**原因**: 容器内无法访问内网 IP `10.20.0.11`
**解决**: 在 docker-compose.yml 中添加 `extra_hosts`
### 3. API 请求 404
**检查**: nginx 是否正确代理 `/api/` 到后端 gateway
```bash
# 测试 nginx gateway 代理
ssh root@47.94.178.212 "curl -s http://127.0.0.1:18083/api/v1/auth/login -X POST -H 'Content-Type: application/json' -d '{\"account\":\"admin@example.com\",\"password\":\"123456\"}'"
```
### 4. 检查后端日志
```bash
ssh root@192.168.3.90 "docker logs ai-contract-platform-backend-1 --tail 30"
```
### 5. Chat 页面历史会话 500
**现象**: 登录后进入 `http://contact.yuqei.com/chat`，页面提示 `历史会话加载失败 Request failed with status code 500`。
**排查**:
```bash
ssh root@192.168.3.90 "docker logs ai-contract-platform-backend-1 --tail 120"
```
如果日志出现如下错误，说明后端容器内的 vendored shared AI SDK 与业务代码配置不一致：
```text
TypeError: SharedAIPlatformClient.__init__() got an unexpected keyword argument 'api_prefix'
```
**解决**: 发布包含 `backend/vendor/shared-ai-platform-sdk/shared_ai_platform_sdk/client.py` 修复的后端代码，并重建 `backend` 与 `legal-change-impact-worker`。
## 验证部署
```bash
# 1. 测试前端页面
curl -s -o /dev/null -w "%{http_code}" http://contact.yuqei.com/
# 2. 测试 API 登录
curl -s -X POST 'http://contact.yuqei.com/api/v1/auth/login' \
-H 'Content-Type: application/json' \
-d '{"account":"admin@example.com","password":"123456"}'
# 3. 测试后端 health check
curl -s http://10.20.0.11:18083/health
# 4. 测试生产 readiness
curl -s http://contact.yuqei.com/api/v1/system/readiness
```
登录态页面验证重点：
- `http://contact.yuqei.com/workspace` 可正常进入工作台
- `http://contact.yuqei.com/contracts` 可加载合同列表
- `http://contact.yuqei.com/chat` 不再出现历史会话 500，后端日志中 `/api/v1/conversations?page=1&page_size=20` 返回 200
## 目录结构
### 阿里云 `/opt/apps/ai-contract-web/current/`
```
├── docker-compose.yml
├── nginx/
│ └── web-gateway.conf
└── app/
├── Dockerfile
├── server.js # Next.js standalone 服务器
├── .next/
│ ├── static/ # 静态 JS/CSS
│ └── server/ # 服务端渲染代码
├── public/
├── node_modules/
└── package.json
```
### 后端服务器 `/opt/apps/ai-contract-platform/`
```
├── docker-compose.server.yml
├── .env
├── backend/
│ ├── Dockerfile
│ ├── app/
│ ├── migrations/
│ └── requirements.txt
└── frontend/ # 本地开发用，不部署
```
## 相关文档
- [[deploy/README.md]] - 部署说明
- [[deploy/web-gateway.conf]] - nginx 配置模板
- [[deploy/docker-compose.yml]] - docker-compose 模板
docs/DEPLOYMENT_TROUBLESHOOTING.md
-199
View File
@@ -1,199 +0,0 @@
# Deployment Troubleshooting Guide
## Known Issues & Solutions
### 1. Database Password with Special Characters in DATABASE_URL
**Problem**: When the database password contains special characters (especially `%`), the backend container fails to connect with:
```
sqlalchemy.exc.OperationalError: (psycopg.OperationalError) connection failed:
FATAL: password authentication failed for user "postgres"
```
**Root Cause**: The `DATABASE_URL` uses URL encoding. When the password contains `%`, the URL parser interprets it as a URL-encoded character. For example, `%81` gets decoded as a single byte instead of the literal characters `%81`.
**Example**:
- Original password: `example%password`
- In docker-compose.yml `POSTGRES_PASSWORD`: use **exact** password: `example%password`
- In `DATABASE_URL`: must URL-encode the `%` as `%25`: `example%25password`
**Solution**:
```yaml
# docker-compose.server.yml
environment:
POSTGRES_PASSWORD: example%password # Exact password for postgres
DATABASE_URL: postgresql+psycopg://postgres:example%25password@postgres:5432/ai_contract_platform
```
**Rule of thumb**: Any `%` in a URL must be written as `%25`. This applies to `DATABASE_URL`, `REDIS_URL`, and any other URL-based configuration.
### 2. Missing Template Files at Startup
**Problem**: Backend crashes on startup with:
```
FileNotFoundError: [Errno 2] No such file or directory:
'/project-docs/phase13-legal-knowledge-template-library/contract-templates/...'
```
**Root Cause**: Docker build doesn't include `project-docs/` directory. The `template_service.py` tries to load template markdown files at import time.
**Solution**: Fixed in commit `323e7cf`. The `_load_phase13_template_asset` function now:
1. Returns `None` if source files are missing
2. Filters out `None` entries from `DEFAULT_TEMPLATES` at module load time
### 3. Missing `_context` Method in RemoteSharedAIPlatformClient
**Problem**: Chat API returns 500 error:
```
AttributeError: 'RemoteSharedAIPlatformClient' object has no attribute '_context'
```
**Root Cause**: The `RemoteSharedAIPlatformClient` class uses `self._context(current_user)` in many methods, but the method was never defined.
**Solution**: Fixed in commit `3ff384c`. Added the `_context` method:
```python
def _context(self, current_user: Dict[str, Any]) -> SharedAIRequestContext:
return SharedAIRequestContext(
tenant_id=current_user.get("tenant_id", ""),
user_id=current_user.get("id", ""),
user_role=current_user.get("role", "admin"),
)
```
### 4. Shared AI SDK missing `api_prefix`
**Problem**: Chat history or shared AI features return 500. Backend logs show:
```text
TypeError: SharedAIPlatformClient.__init__() got an unexpected keyword argument 'api_prefix'
```
**Root Cause**: The contract backend passes `SHARED_AI_PLATFORM_API_PREFIX` into the vendored `shared-ai-platform-sdk`, but the deployed SDK version does not accept `api_prefix`.
**Solution**: Deploy the fixed vendored SDK file and rebuild backend services:
```bash
scp backend/vendor/shared-ai-platform-sdk/shared_ai_platform_sdk/client.py \
root@192.168.3.90:/opt/apps/ai-contract-platform/backend/vendor/shared-ai-platform-sdk/shared_ai_platform_sdk/client.py
ssh root@192.168.3.90
cd /opt/apps/ai-contract-platform
docker compose -f docker-compose.server.yml build backend legal-change-impact-worker
docker compose -f docker-compose.server.yml up -d backend legal-change-impact-worker
```
**Verify**:
```bash
curl -s http://contact.yuqei.com/api/v1/system/readiness
docker logs --since 5m ai-contract-platform-backend-1
```
The `/api/v1/conversations?page=1&page_size=20` request should return 200 after logging in and opening `/chat`.
### 5. 前端登录报"网络异常" - Git Bash 路径转换问题 ⚠️
**问题**: 前端部署后登录失败，浏览器控制台显示请求发送到错误的 URL（如 `http://api/v1/auth/login` 或 `http://C:/Program Files/Git/api/v1/auth/login`）
**根本原因**: 在 Windows Git Bash 环境下构建 Next.js 时：
- `NEXT_PUBLIC_API_BASE_URL=/api/v1` 被错误地转换成 Windows 路径 `C:/Program Files/Git/api/v1`
- `NEXT_PUBLIC_API_BASE_URL="//api/v1"` 被浏览器解析为 `http://api/v1`（协议相对 URL）
**错误示例**:
```bash
# 这会导致 API_BASE_URL = "C:/Program Files/Git/api/v1"
NEXT_PUBLIC_API_BASE_URL=/api/v1 npm run build
# 这会导致 API_BASE_URL = "//api/v1"，浏览器解析为 "http://api/v1"
NEXT_PUBLIC_API_BASE_URL="//api/v1" npm run build
```
**正确做法**:
```bash
# 使用 MSYS_NO_PATHCONV=1 防止路径转换
MSYS_NO_PATHCONV=1 NEXT_PUBLIC_API_BASE_URL="/api/v1" BACKEND_BASE_URL="http://10.20.0.11:18083" npm run build
```
**排查方法**:
```bash
# 检查部署的 JS 文件中 API_BASE_URL 的实际值
curl -s 'http://contact.yuqei.com/_next/static/chunks/*.js' | grep -oP 'tl="[^"]*"'
# 正确值: tl="/api/v1"
# 错误值: tl="C:/Program Files/Git/api/v1" 或 tl="//api/v1"
```
### 6. Next.js 环境变量运行时无效
**问题**: 在 docker-compose 的 environment 中设置了 `NEXT_PUBLIC_API_BASE_URL`，但前端仍然使用旧值
**原因**: `NEXT_PUBLIC_*` 和 `BACKEND_BASE_URL` 是**构建时**嵌入的环境变量，运行时设置无效！这些值会被硬编码到 JS 文件中。
**解决方案**: 必须在 `npm run build` 时设置环境变量：
```bash
MSYS_NO_PATHCONV=1 NEXT_PUBLIC_API_BASE_URL="/api/v1" BACKEND_BASE_URL="http://10.20.0.11:18083" npm run build
```
### 7. Docker 容器无法访问内网 IP
**问题**: 前端容器内无法访问后端服务器的内网 IP（如 `10.20.0.11`）
**解决方案**: 在 docker-compose.yml 中添加 `extra_hosts`:
```yaml
services:
ai-contract-web:
extra_hosts:
- "10.20.0.11:host-gateway" # 映射到 Docker 宿主机
```
## 部署架构
| 组件 | 部署位置 | 目录 | 端口 |
|------|---------|------|------|
| 前端 Next.js | 阿里云 ECS (47.94.178.212) | `/opt/apps/ai-contract-web/current` | 容器内 3000 |
| 前端 Gateway | 阿里云 ECS | 同上 | 127.0.0.1:18083 |
| 后端 FastAPI | 192.168.3.90 | `/opt/apps/ai-contract-platform` | 8001:8000 |
| 后端 Gateway | 192.168.3.90 | `/opt/apps/ai-contract-platform-gateway` | 10.20.0.11:18083 |
| PostgreSQL | 192.168.3.90 | - | 5432 |
| Redis | 192.168.3.90 | - | 6379 |
| MinIO | 192.168.3.90 | - | 9000 |
**域名**: `contact.yuqei.com`
## 部署脚本
项目提供了便捷的部署脚本：
```bash
# 构建前端
./scripts/build-frontend.sh
# 部署前端到阿里云
./scripts/deploy-frontend.sh
```
## Deployment Checklist
1. **验证密码编码**: 检查 `DATABASE_URL` 中 `%` 是否编码为 `%25`
2. **前端构建环境变量**: 使用 `MSYS_NO_PATHCONV=1` 防止路径转换
3. **确认服务器部署形态**: `/opt/apps/ai-contract-platform` 不一定是 Git 工作区，先执行 `git rev-parse --is-inside-work-tree`
4. **同步最新代码或发布包**: Git 工作区用 `git pull origin main`；发布包目录用 `scp`/解压包覆盖目标文件
5. **后端重建**: `docker compose -f docker-compose.server.yml build backend legal-change-impact-worker`
6. **后端启动**: `docker compose -f docker-compose.server.yml up -d backend legal-change-impact-worker`
7. **验证**: `curl -s http://contact.yuqei.com/api/v1/system/readiness`，并确认 `/chat` 登录态下历史会话加载不再 500
## Server Information
- **Server**: 192.168.3.90
- **Project directory**: `/opt/apps/ai-contract-platform`
- **SSH key**: `~/.ssh/water_audit_ed25519`
- **SSH user**: `root`
- **Gitea**: http://192.168.3.90:3000
- **Frontend**: http://192.168.3.90:3003
- **Backend API**: http://192.168.3.90:8001
- **Secret handling**: production passwords and API keys are stored on the server in `.env`; do not copy secrets into docs
## 默认账号
| 账号 | 密码 | 角色 |
|------|------|------|
| admin@example.com | 123456 | admin |
docs/archive/2026-06-17-strategy-refresh/AI法律文书助手_合并整理版.md
-5059
View File
File diff suppressed because one or more lines are too long
docs/archive/2026-06-17-strategy-refresh/README.md
-6
View File
@@ -1,6 +0,0 @@
# 2026-06-17 Strategy Refresh Archive
本目录保存被新规划替代的旧 `docs/` 文档。
当前保留为历史资料，不再作为当前执行依据。
docs/archive/2026-06-17-strategy-refresh/integration-plan.md
-219
View File
@@ -1,219 +0,0 @@
# AI法律文书助手文档 — 分析融合方案
**分析日期**：2026-05-29
**源文档**：`docs/AI法律文书助手_合并整理版.md`（~960KB）
**文档定位**：契智 LexForge AI 法律文书的完整产品规划 + Prompt Engineering 手册
---
## 一、文档核心价值总结
该文档不是技术实现文档，而是**产品规划 + Prompt 工程 + 测试标准**的综合设计文档。包含四大块可吸收内容：
| 区块 | 篇幅 | 可吸收程度 | 说明 |
|------|------|-----------|------|
| Prompt Engineering 完整手册 | ~600 行 | ⭐⭐⭐⭐⭐ | 可直接导入 prompt_asset 系统 |
| 质量保障与测试方案 | ~40 行 | ⭐⭐⭐⭐ | KPI 体系和评估标准可复用 |
| 合同类型条款清单 | ~30 行 | ⭐⭐⭐⭐ | 必备条款 checklists 可充实模板 |
| 审查维度框架 | ~50 行 | ⭐⭐⭐ | 5 维度审查框架可丰富现有 review |
---
## 二、Prompt Engineering 手册 — 可导入内容
文档的 **Part 2 (Prompt Engineering 完整手册)** 包含 14 个部分的完整 Prompt 模板，可直接导入 `prompt_asset` 系统作为种子数据。
### 2.1 System Prompt（全局系统提示词）
文件行 ~1503-1527，可直接创建为 `prompt_type = "legal_chat"` 或 `system_prompt` 类型的 prompt asset：
```json
{
"prompt_key": "system_prompt_legal_assistant_v1",
"prompt_type": "system_prompt",
"name": "AI 法律助手全局系统提示词",
"description": "契智 LexForge AI 法律文书助手的核心 System Prompt",
"content": "你的身份：你是\"契智AI法律助手\"，一个专业的中国法律文书AI工具...（完整内容在文档 ~1503-1527 行）"
}
```
**建议优先级：高** — 可立即提升 AI 回复的专业性和一致性。
### 2.2 文书智能生成 Prompt 模板（~行 1539-1747）
共 6 个生成场景：
| 场景 | 文档行号 | 系统已有 | 可补充 |
|------|---------|---------|--------|
| 通用文书生成框架 | ~1541 | 有 `contract_generation` prompt | 增加结构化输出要求、HTML 格式约束 |
| 买卖合同生成 | ~1565 | 类似 `procurement_goods` | 增加合规重点、行业惯例参考值 |
| 劳动合同生成 | ~1597 | 有 `labor_contract` prompt | 增加法定必备条款 checklist（最有价值） |
| 保密协议生成 | ~1645 | 有 `nda_commercial` prompt | 增加保密信息定义规则、排除条款 |
| 服务合同生成 | ~1675 | 有 `service_general` prompt | SLA 标准、交付物清单 |
| 股权转让协议 | ~1709 | 系统暂无 | 新增！高价值场景的 prompt |
**建议优先级：高** — 特别是"劳动合同"和"股权转让"的 prompt 比我们现有的更详细。
### 2.3 文书审查 Prompt 模板（~行 1749-1850）
审查维度（~行 1761-1776）比现有实现更完整：
| 维度 | 文档描述 | 系统现状 | 补充价值 |
|------|---------|---------|---------|
| 维度1：文书类型识别与结构完整性 | 判断类型 + 必备条款检查 | 有 keyword 匹配 | 可改用 AI 判定 |
| 维度2：当事人信息审查 | 完整性/一致性/身份明确 | 仅 basic_info 提取 | 增加交叉验证逻辑 |
| 维度3：核心条款风险审查 | 权利义务对等/责任边界/数字明确 | 有 risk_items | 审查粒度更细 |
| 维度4：法规合规校验 | 逐条校验 + 法条引用 | 已有 legal_basis | 增加最新法规同步机制 |
| 维度5：措辞审查 | 模糊表述/口语化/数字格式 | 无此维度 | 新增维度 |
风险等级定义（~行 1780）：
```
🔴 高风险: 重大经济损失/违反强制性法律/缺少必备条款
🟡 中风险: 潜在风险/措辞模糊/对等性不足
🔵 低风险: 可优化/可更专业/格式规范化
```
**建议优先级：中** — 可用于优化 review prompt 的结构。
### 2.4 条款推荐 Prompt（~行 1852-1916）
两套 Prompt：
1. **缺失条款推荐**（~行 1854-1886）— 按合同类型的完整条款清单
2. **条款优化推荐**（~行 1886-1916）— 措辞优化、缺失细节、矛盾检测
**完整条款清单（~行 1864）** 最有价值：以买卖合同为例，列出了 **17 个条款**的完整清单并标注了"★必备/☆推荐/○视情况"。可直接用于充实我们的 `clause_completion_suggestions` 功能。
**建议优先级：中** — 条款分类体系可整合进 clause_suggestion 逻辑。
### 2.5 措辞优化与改写 Prompt（~行 2004-2079）
包含：
- **7.1 措辞专业化**（~行 2006-2049）— 口语→法律专业表述，有对照表
- **7.2 条款改写**（~行 2051-2079）— 偏向特定方角度的条款改写
**口语→专业对照表**（~行 2018-2035）：
| 口语表述 | 专业表述 |
|---------|---------|
| 尽快/尽早 | 应在 [具体期限] 内 |
| 差不多/大概 | 误差不超过 ±[具体比例] |
| 按规矩/按规定 | 按照 [具体法规名称] 的规定 |
| 到时候再说 | 双方应于 [具体时间] 另行协商 |
| 尽量/尽可能 | 应尽商业上合理的努力 |
| 归你/归我 | 知识产权归 [具体方] 所有 |
**建议优先级：中** — 可开发新的 `wording_optimization` prompt asset。
---
## 三、质量保障体系 — 可参考指标
### 3.1 生成质量 KPI（~行 968-978）
| 指标 | 目标值 | 系统现状 | 差距 |
|------|-------|---------|------|
| 结构完整性（必备条款覆盖率） | ≥ 95% | 仅有 keyword 检测 | 无 AI 评分 |
| 条款准确性（律师评分） | ≥ 4/5 | 无此维度 | 需引入人工+AI 混合评价 |
| 法规合规性（法条准确率） | ≥ 95% | 有 legal_source_count | 缺少准确率校验 |
| 措辞专业性（律师评分） | ≥ 4/5 | 无此维度 | 新维度 |
### 3.2 审查质量 KPI（~行 979-988）
| 指标 | 目标值 | 系统现状 | 差距 |
|------|-------|---------|------|
| 风险识别召回率 | ≥ 90% | 无此指标 | 需构建标注测试集 |
| 风险识别精确率 | ≥ 85% | 无此指标 | 同上 |
| 风险等级准确率 | ≥ 80% | 无此指标 | 需验证 |
| 修改建议采纳率 | ≥ 60% | 有 clause_action 统计 | 已有数据基础 |
**建议优先级：低** — KPI 体系可作为后续运营指标扩展参考，非紧急。
---
## 四、领域知识 — 可充实现有常量
### 4.1 合同类型必备条款清单
文档（~行 1864）提供了按合同类型的完整条款清单。示例——买卖合同：
```
必备 ★：当事人信息、标的物、价款、付款、交付、验收、质量保证、违约责任、争议解决
推荐 ☆：不可抗力、保密、通知送达、合同变更、合同解除、附则
视情况 ○：知识产权、保险、知识产权
```
**可充实** `DEFAULT_RISK_RULES` 中的条款覆盖度检查。
### 4.2 劳动法专项检查规则（~行 1810-1826）
8 项专项检查，包含具体法条引用和判定逻辑：
1. 试用期合规 — 《劳动合同法》第19条
2. 工资标准合规 — 最低工资/构成/加班比例
3. 工作时间合规 — 工时制度/审批/加班上限
4. 社会保险与福利 — 五险一金/违法约定
5. 违约金合规 — ⚠️ 第25条禁止
6. 竞业限制合规 — 期限/补偿/范围
7. 解除与终止条款 — 法定情形/违法条款
8. 其他违法条款 — 押金/扣押证件/放弃社保
**建议优先级：高** — 可直接新增到 `DEFAULT_RISK_RULES`，丰富劳动合同审查。
---
## 五、融合实施方案 — 执行状态
### Phase 1 — 立即导入（1-2 天）✅ 已完成
```
1. ✅ 创建 seed_prompts_from_doc.py 种子脚本
- system_prompt_legal_assistant（legal_chat）
- contract_review_structured_v2（contract_review）
- clause_recommendation_completeness（clause_recommendation）
脚本路径: tools/seed_prompts_from_doc.py
状态: 语法验证通过，部署后执行
2. ✅ 扩展 DEFAULT_RISK_RULES 劳动合同规则
- 更新 5 条现有规则补充细节（试用期工资、工时审批、放弃社保等）
- 新增 3 条规则（违约金禁止、押金禁止、重复试用检查）
- 劳动合同规则总数: 5 → 8 条
```
### Phase 2 — 功能增强（3-5 天）✅ 已完成
```
1. ✅ 措辞优化 Prompt
- 新建 wording_rewrite_professional（wording_rewrite）
- 含口语→专业表述对照表（10组映射）
- 种子脚本中已定义
2. ✅ 条款分类体系整合
- 新增 CLAUSE_COMPLETENESS_CHECKLIST（8 种合同类型，共 39 条条款定义）
- 新增 _get_clause_checklist() / _check_clause_completeness() 方法
- 集成到 _build_generation_quality_summary，质量检查会按合同类型输出缺失条款
- 合同类型覆盖：通用、采购、服务、技术开发、劳动、保密、租赁、投融资
```
### Phase 3 — 质量体系（可延后）🔲 未开始
```
1. 构建标注测试集
2. 实现指标自动化计算
3. 建立 A/B 评估流水线
```
---
## 六、总结
| 类别 | 数量 | 建议优先级 |
|------|------|-----------|
| 可直接导入的 Prompt 模板 | 12+ 个 | 高 — 立即可做 |
| 可扩展的审查规则（劳动法专项） | 8 项 | 高 |
| 可按合同类型扩展的条款清单 | 6+ 种 | 中 |
| 可新增的审查维度 | 2 项（当事人信息/措辞） | 中 |
| 可参考的质量 KPI | 8 项 | 低 — 非紧急 |
**最高 ROI 动作**：把文档中的 System Prompt 和审查 Prompt 导入到 `prompt_asset` 表作为种子数据，立即可让 AI 回复更专业、更结构化。
docs/npc-law-database-api.md
-282
View File
@@ -1,282 +0,0 @@
# 国家法律法规数据库 (flk.npc.gov.cn) API 接口文档
## 概述
国家法律法规数据库由全国人大常委会办公厅主办，提供法律法规的查询、浏览和下载服务。本文档记录了通过逆向分析发现的API接口。
## 已发现的API端点
### 1. 搜索建议API (Search Suggestions)
**端点**: `GET /law-search/prompts/search`
**描述**: 根据法律名称关键词获取搜索建议列表
**参数**:
- `title` (string, required): 搜索关键词
**示例请求**:
```bash
curl "https://flk.npc.gov.cn/law-search/prompts/search?title=%E6%B0%91%E6%B3%95%E5%85%B8"
```
**示例响应**:
```json
{
"code": 200,
"msg": "操作成功",
"data": [
{
"title": "民法典",
"titleHighlight": "<em class='highlight'>民法典</em>"
},
{
"title": "中华人民共和国民法典",
"titleHighlight": "中华人民共和国<em class='highlight'>民法典</em>"
},
{
"title": "云南省人民代表大会常务委员会关于深入学习宣传和实施《中华人民共和国民法典》的决定",
"titleHighlight": "云南省人民代表大会常务委员会关于深入学习宣传和实施《中华人民共和国<em class='highlight'>民法典</em>》的决定"
}
]
}
```
### 2. 法律详情API (Law Details)
**端点**: `GET /law-search/search/flfgDetails`
**描述**: 根据bbbs ID获取法律详细信息
**参数**:
- `bbbs` (string, required): 法律的唯一标识符（32位十六进制字符串）
**示例请求**:
```bash
curl "https://flk.npc.gov.cn/law-search/search/flfgDetails?bbbs=ff808081729d1efe01729d50b5c500bf"
```
**示例响应**:
```json
{
"msg": "操作成功",
"code": 200,
"data": {
"bbbs": "ff808081729d1efe01729d50b5c500bf",
"title": "中华人民共和国民法典",
"flxz": "法律",
"zdjgName": "全国人民代表大会",
"gbrq": "2020-05-28",
"sxrq": "2021-01-01",
"ossFile": {
"ossWordPath": "prod/20200528/827f65fcb68f40cb941eed996c5212b0.docx",
"ossPdfPath": "prod/20200528/bd53dd912c1048f2aecbaa229238334b.pdf"
},
"content": {
"id": "79890000-3e3b-0016-4922-08dd7af76244",
"title": "中华人民共和国民法典",
"children": [...]
}
}
}
```
**注意**: bbbs ID是法律的唯一标识符，为32位十六进制字符串格式。需要先通过搜索API获取。
### 3. 文档下载API (Document Download)
**端点**: `GET /law-search/download/pc`
**描述**: 下载法律文档（DOCX格式）
**参数**:
- `format` (string, required): 文档格式，支持 `docx`
- `bbbs` (string, required): 法律的唯一标识符（32位十六进制字符串）
**示例请求**:
```bash
curl "https://flk.npc.gov.cn/law-search/download/pc?format=docx&bbbs=ff808081729d1efe01729d50b5c500bf"
```
### 4. 统计数据API (Aggregate Data)
**端点**: `GET /law-search/index/aggregateData`
**描述**: 获取法律法规分类统计数据
**示例请求**:
```bash
curl "https://flk.npc.gov.cn/law-search/index/aggregateData"
```
**示例响应**:
```json
{
"code": 200,
"msg": "操作成功",
"data": {
"flflCount": [
{"count": 1, "id": 1, "key": "宪法"},
{"count": 310, "id": 2, "key": "法律"},
{"count": 610, "id": 14, "key": "行政法规"},
{"count": 2, "id": 15, "key": "监察法规"},
{"count": 15755, "id": 16, "key": "地方法规"},
{"count": 559, "id": 27, "key": "司法解释"}
],
"xfsd": [...],
"popularSearch": [
{
"bbbs": "ff808081729d1efe01729d50b5c500bf",
"flxz": "法律",
"gbrq": "2020-05-28",
"title": "中华人民共和国民法典"
}
],
"popularDownload": [...],
"xf": {
"bbbs": "2c909fdd678bf17901678bf5a483004b",
"title": "中华人民共和国宪法（2018年修正文本）"
}
}
}
```
**重要发现**: 此API返回的数据中包含了热门搜索和热门下载法律的完整信息，包括bbbs ID！这提供了一种直接获取法律列表的方法。
### 5. 高级搜索API (Advanced Search)
**端点**: `POST /law-search/search/list`
**描述**: 根据条件搜索法律列表
**Content-Type**: `application/json`
**请求参数** (推测，需要进一步验证):
- `title` (string): 法律名称
- `page` (number): 页码
- `size` (number): 每页数量
- 其他可能的搜索参数待确认
**注意**: 此API需要POST请求和正确的Content-Type。在测试中遇到了编码问题，可能需要特定的请求头或参数格式。
### 6. 其他发现的端点
通过JavaScript逆向分析发现的其他API端点:
- `POST /law-search/highSearch/highSearch` - 高级搜索
- `GET /law-search/highSearch/hitDisplay` - 高级搜索命中显示
- `GET /law-search/highSearch/xgzl` - 高级搜索相关资料
- `GET /law-search/search/enumData` - 搜索枚举数据
- `GET /law-search/search/hitDisplay` - 搜索命中显示
- `GET /law-search/search/recommend` - 推荐搜索
- `GET /law-search/search/xgzl` - 相关资料
- `GET /law-search/search/xgzlDetails` - 相关资料详情
- `GET /law-search/search/xgwjDetails` - 相关文件详情
- `GET /law-search/download/batch` - 批量下载
- `GET /law-search/amazonFile/previewLink` - 文件预览链接
- `GET /law-search/index/captchaImage` - 验证码图片
- `GET /law-search/index/fljc` - 法律检索
## bbbs ID 说明
### 什么是bbbs ID?
bbbs是法律法规在数据库中的唯一标识符，为32位十六进制字符串格式（如 `ff808081729d1efe01729d50b5c500bf`）。每个法律文档都有唯一的bbbs ID。
### 如何获取bbbs ID?
**方法1**: 通过统计数据API（推荐）
1. 调用 `/law-search/index/aggregateData` API
2. 从返回的 `popularSearch` 或 `popularDownload` 数组中获取法律的bbbs ID
**方法2**: 通过搜索建议API
1. 使用 `/law-search/prompts/search` 获取搜索建议
2. 点击搜索结果进入详情页
3. 从URL中提取bbbs参数
**方法3**: 通过新发布法规列表
- 从统计数据API的 `xfsd` 字段获取最新发布的法规列表
### bbbs ID 格式
bbbs ID是32位十六进制字符串，示例:
- `ff808081729d1efe01729d50b5c500bf` - 中华人民共和国民法典
- `ff808181796a636a0179822a19640c92` - 中华人民共和国刑法
- `2c909fdd678bf17901678bf5a483004b` - 中华人民共和国宪法
### URL结构
详情页URL格式:
```
https://flk.npc.gov.cn/detail2.html?[bbbs]
```
示例:
```
https://flk.npc.gov.cn/detail2.html?ff808081729d1efe01729d50b5c500bf
```
## 工作流程
### 推荐的法律获取流程
#### 方法1: 使用统计数据API获取热门法律（最简单）
1. **获取统计数据**: 调用 `/law-search/index/aggregateData` API
2. **提取bbbs**: 从 `popularSearch` 或 `popularDownload` 数组中获取法律的bbbs ID
3. **获取详情**: 使用 `/law-search/search/flfgDetails` API获取法律详细信息
4. **下载文档**: 使用 `/law-search/download/pc` API下载DOCX文档
#### 方法2: 通过搜索获取特定法律
1. **搜索法律**: 使用 `/law-search/prompts/search` API搜索法律名称
2. **获取bbbs**: 从搜索结果中获取法律名称，然后访问详情页获取bbbs
3. **获取详情**: 使用 `/law-search/search/flfgDetails` API获取法律详细信息
4. **下载文档**: 使用 `/law-search/download/pc` API下载DOCX文档
## 实际应用示例
### 获取民法典的详细信息
```bash
# 1. 获取统计数据API中的热门搜索
curl -s "https://flk.npc.gov.cn/law-search/index/aggregateData" | jq '.data.popularSearch'
# 2. 从返回结果中找到民法典的bbbs: ff808081729d1efe01729d50b5c500bf
# 3. 获取详细信息
curl -s "https://flk.npc.gov.cn/law-search/search/flfgDetails?bbbs=ff808081729d1efe01729d50b5c500bf" | jq '.data'
# 4. 下载DOCX文档
curl -O "https://flk.npc.gov.cn/law-search/download/pc?format=docx&bbbs=ff808081729d1efe01729d50b5c500bf"
```
### 获取所有310部法律的方法（待验证）
由于 `/law-search/search/list` API需要POST请求且参数不明确，目前可通过以下方式获取部分法律：
1. 使用统计数据API获取热门法律（约10部）
2. 使用搜索建议API逐个搜索法律名称
3. 可能需要研究高级搜索API或分类列表API
## 限制与注意事项
1. **编码问题**: 某些API对UTF-8编码要求严格，需要正确设置请求头
2. **反爬机制**: 网站可能有反爬虫机制，频繁请求可能被限制
3. **数据完整性**: 不是所有法律都提供DOCX下载
4. **API稳定性**: 这些是逆向分析发现的非官方API，可能随时变化
## 待研究内容
1. **搜索列表API**: `/law-search/search/list` 的完整参数和使用方法 - 这是获取完整法律列表的关键
2. **高级搜索**: `/law-search/highSearch/highSearch` 的功能 - 可能提供更强大的搜索能力
3. **分类列表**: 如何获取特定分类（如"法律"、"行政法规"）的完整列表 - 可能需要参数中的分类ID
4. **bbbs ID生成规律**: 研究bbbs ID是否有规律可循，是否可以预测
## 参考资源
- 官方网站: https://flk.npc.gov.cn
- JavaScript源码: https://flk.npc.gov.cn/assets/index-UYjjaqh-.js
## 更新日志
- 2026-06-15: 初始版本，发现基本API端点