fs-lawrisk/docs/guides/README.md

LawRisk Backend

智能法律风险检索系统 - Flask后端服务

项目简介

LawRisk是一个基于Flask的Python后端服务，为政务许可和风险提示提供智能检索功能。使用向量嵌入和LLM匹配技术，帮助用户根据自然语言查询找到相关的许可证、执照和法律风险信息。

技术栈

• 框架: Flask 2.3+
• 数据库: PostgreSQL (pg8000驱动)
• AI服务: 阿里云DashScope
  • 嵌入模型: text-embedding-v4
  • 对话模型: qwen-plus-latest
• 开发工具: Black, Ruff, Pytest

项目结构

市监局-lawRisk-backend/
├── app.py                      # Flask应用入口
├── requirements.txt            # Python依赖
├── .env                        # 环境配置
│
├── lawrisk/                    # 主应用包
│   ├── __init__.py
│   ├── api/                    # API路由层
│   │   ├── v1.py              # V1 API (legacy)
│   │   └── v2.py              # V2 API (current)
│   ├── services/               # 业务逻辑层
│   │   ├── lawrisk_service.py  # 核心检索服务
│   │   ├── lawrisk_v2_service.py  # V2增强服务
│   │   └── licensing_repo.py   # 数据仓库
│   ├── middleware/             # 中间件
│   │   └── smart_cors_middleware.py
│   └── utils/                  # 工具模块
│       ├── env_loader.py
│       ├── export_risk_json.py
│       └── ingest_lawrisk.py
│
├── static/                     # 静态资源
│   └── v2_tester.html         # API测试页面
│
├── tests/                      # 测试套件 (计划中)
│   └── __init__.py
│
├── data/                       # 数据文件
│   ├── risk_tables_export.json
│   └── licensing_risks_dump.sql
│
└── docs/                       # 项目文档
    ├── PRD.md
    ├── API.md
    ├── V2_API文档.md
    ├── AGENTS.md
    ├── DB_GUIDE.md
    └── CLAUDE.md

快速开始

1. 安装依赖

pip install -r requirements.txt

2. 配置环境变量

复制.env文件并配置数据库和API密钥：

# 数据库配置
PG_HOST=your_db_host
PG_PORT=5432
PG_USER=postgres
PG_PASSWORD=your_password
PG_DATABASE=fs_law_risk

LIC_PG_HOST=your_db_host
LIC_PG_DATABASE=licensing_risks

# DashScope API
DASHSCOPE_API_KEY=your_api_key
DASHSCOPE_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

3. 运行应用

python app.py

应用将在 http://localhost:8000 启动

4. 测试API

访问 http://localhost:8000/static/v2_tester.html 进行API测试

或使用curl：

curl http://localhost:8000/healthz
curl -X POST "http://localhost:8000/fs-ai-asistant/api/workflow/lawrisk/v2" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "query=我要办一家电影院&debug=1"

身份认证

• 设置 FLASK_SECRET_KEY 保护会话 Cookie，同时通过 LAWRISK_ADMIN_USERNAME 和 LAWRISK_ADMIN_PASSWORD 注入首个管理员账号。
• 首次启动会自动创建 auth_users 表，用于存储用户名、哈希密码、角色（role）和级别（grade）。
• 登录页位于 /fs-ai-asistant/lawrisk/login，API 客户端可以调用 /auth/me 获取当前登录信息。

数据备份与恢复 (Checkpoint)

• 系统提供 Checkpoint 功能，可对数据库全表进行 JSON 序列化备份。
• 支持二进制数据（如 bytes, memoryview）的 Base64 自动转换，确保 Excel 原始文件等资产的完整备份。
• 管理员可通过管理后台 /db_admin 手动创建、列出或恢复检查点。

API文档

• V1 API: 查看 docs/API.md
• V2 API: 查看 docs/V2_API文档.md
• 数据库指南: 查看 docs/DB_GUIDE.md

开发

代码格式化

black .
ruff .

运行测试 (计划中)

pytest

许可证

内部使用