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. 安装依赖

```bash
pip install -r requirements.txt
```

### 2. 配置环境变量

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

```bash
# 数据库配置
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. 运行应用

```bash
python app.py
```

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

### 4. 测试API

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

或使用curl：

```bash
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`

## 开发

### 代码格式化

```bash
black .
ruff .
```

### 运行测试 (计划中)

```bash
pytest
```

## 许可证

内部使用