# 智慧监督AI文书写作服务 - 启动说明

## 快速启动步骤

### 1. 创建虚拟环境（推荐）

**Windows系统：**
```bash
# 运行安装脚本
setup_env.bat
```

**Linux/Mac系统：**
```bash
# 运行安装脚本
chmod +x setup_env.sh
./setup_env.sh
```

**手动创建虚拟环境：**
```bash
# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# Windows:
venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt
```

### 2. 配置环境变量

复制 `.env.example` 为 `.env`：

```bash
# Windows:
copy .env.example .env

# Linux/Mac:
cp .env.example .env
```

编辑 `.env` 文件，填入你的配置：

```env
# ========== AI服务提供商配置 ==========
# 选择使用的AI服务提供商
# 可选值: 'huawei' 或 'siliconflow'
# 默认值: 'siliconflow'
AI_PROVIDER=siliconflow

# ========== 华为大模型API配置（当 AI_PROVIDER=huawei 时使用） ==========
HUAWEI_API_ENDPOINT=http://10.100.31.26:3001/v1/chat/completions
HUAWEI_API_KEY=sk-PoeiV3qwyTIRqcVc84E8E24cD2904872859a87922e0d9186
HUAWEI_MODEL=DeepSeek-R1-Distill-Llama-70B
HUAWEI_API_TIMEOUT=180
HUAWEI_API_MAX_TOKENS=12000

# ========== 硅基流动API配置（当 AI_PROVIDER=siliconflow 时使用） ==========
SILICONFLOW_URL=https://api.siliconflow.cn/v1/chat/completions
SILICONFLOW_API_KEY=你的硅基流动API密钥
SILICONFLOW_MODEL=deepseek-ai/DeepSeek-V3.2-Exp
SILICONFLOW_API_TIMEOUT=120
SILICONFLOW_API_MAX_TOKENS=2000

# ========== 数据库配置 ==========
DB_HOST=152.136.177.240
DB_PORT=5012
DB_USER=finyx
DB_PASSWORD=6QsGK6MpePZDE57Z
DB_NAME=finyx

# ========== MinIO配置 ==========
MINIO_ENDPOINT=minio.datacubeworld.com:9000
MINIO_ACCESS_KEY=JOLXFXny3avFSzB0uRA5
MINIO_SECRET_KEY=G1BR8jStNfovkfH5ou39EmPl34E4l7dGrnd3Cz0I
MINIO_SECURE=true
MINIO_BUCKET=finyx
```

**AI服务提供商选择说明：**

- **华为大模型**：设置 `AI_PROVIDER=huawei`，并配置 `HUAWEI_API_KEY` 和 `HUAWEI_API_ENDPOINT`
- **硅基流动**：设置 `AI_PROVIDER=siliconflow`（默认值），并配置 `SILICONFLOW_API_KEY`

如果配置的AI服务不完整，系统会自动尝试使用另一个可用的服务。

### 3. 启动服务

确保虚拟环境已激活，然后运行：

```bash
python app.py
```

服务启动后，你会看到：

```
服务启动在 http://localhost:7500
测试页面: http://localhost:7500/
模板字段管理页面: http://localhost:7500/template-field-manager
Swagger API文档: http://localhost:7500/api-docs
```

### 4. 访问测试页面

在浏览器中打开以下页面：

- **测试页面**: http://localhost:7500/ - 用于测试AI解析和文档生成功能
- **模板字段管理页面**: http://localhost:7500/template-field-manager - 用于管理模板和字段的关联关系
- **Swagger API文档**: http://localhost:7500/api-docs - 查看完整的API接口文档并在线测试

## 测试接口

### 使用Web测试页面

1. 访问 http://localhost:7500/
2. 在"AI解析"标签页中：
   - 在"输入数据"区域填写输入字段
   - 在"输出字段"区域填写需要提取的字段编码
   - 点击"开始解析"按钮
   - 查看解析结果
3. 在"文档生成"标签页中：
   - 填写字段数据
   - 选择要生成的文件（fileId）
   - 点击"生成文档"按钮
   - 查看生成的文档信息（包含下载链接）

### 使用Swagger API文档测试

1. 访问 http://localhost:7500/api-docs
2. 找到要测试的接口（如 `/api/ai/extract`）
3. 点击 "Try it out" 按钮
4. 填写请求参数
5. 点击 "Execute" 执行请求
6. 查看响应结果

### 使用curl命令测试

**AI解析接口：**

```bash
curl -X POST http://localhost:7500/api/ai/extract \
  -H "Content-Type: application/json" \
  -d "{
    \"inputData\": [
      {
        \"fieldCode\": \"clue_info\",
        \"fieldValue\": \"被举报用户名称是张三，年龄30岁，某公司总经理\"
      },
      {
        \"fieldCode\": \"target_basic_info_clue\",
        \"fieldValue\": \"张三，男，汉族，1980年5月出生，山西太原人，本科学历\"
      }
    ],
    \"outputData\": [
      {\"fieldCode\": \"target_name\"},
      {\"fieldCode\": \"target_gender\"},
      {\"fieldCode\": \"target_age\"}
    ]
  }"
```

**文档生成接口：**

```bash
curl -X POST http://localhost:7500/api/ai/generate-document \
  -H "Content-Type: application/json" \
  -d "{
    \"inputData\": [
      {
        \"fieldCode\": \"target_name\",
        \"fieldValue\": \"张三\"
      },
      {
        \"fieldCode\": \"target_gender\",
        \"fieldValue\": \"男\"
      }
    ],
    \"fpolicFieldParamFileList\": [
      {
        \"fileId\": 1765273961563507,
        \"fileName\": \"请示报告卡.docx\"
      }
    ]
  }"
```

### 使用Python脚本测试

**AI解析接口：**

```python
import requests

url = "http://localhost:7500/api/ai/extract"
data = {
    "inputData": [
        {
            "fieldCode": "clue_info",
            "fieldValue": "被举报用户名称是张三，年龄30岁，某公司总经理"
        },
        {
            "fieldCode": "target_basic_info_clue",
            "fieldValue": "张三，男，汉族，1980年5月出生，山西太原人，本科学历"
        }
    ],
    "outputData": [
        {"fieldCode": "target_name"},
        {"fieldCode": "target_gender"},
        {"fieldCode": "target_age"},
        {"fieldCode": "target_organization_and_position"}
    ]
}

response = requests.post(url, json=data)
print(response.json())
```

**文档生成接口：**

```python
import requests

url = "http://localhost:7500/api/ai/generate-document"
data = {
    "inputData": [
        {
            "fieldCode": "target_name",
            "fieldValue": "张三"
        },
        {
            "fieldCode": "target_gender",
            "fieldValue": "男"
        }
    ],
    "fpolicFieldParamFileList": [
        {
            "fileId": 1765273961563507,
            "fileName": "请示报告卡.docx"
        }
    ]
}

response = requests.post(url, json=data)
print(response.json())
```

## API接口说明

### 1. AI字段提取接口

**接口地址**: `POST /api/ai/extract` 或 `POST /ai/extract`

**功能**: 从输入的非结构化文本中提取结构化字段数据

**请求参数**:
```json
{
    "inputData": [
        {
            "fieldCode": "clue_info",
            "fieldValue": "被举报用户名称是张三，年龄30岁"
        }
    ],
    "outputData": [
        {"fieldCode": "target_name"},
        {"fieldCode": "target_gender"}
    ]
}
```

**响应格式**:
```json
{
    "code": 0,
    "data": {
        "outData": [
            {
                "fieldCode": "target_name",
                "fieldValue": "张三"
            },
            {
                "fieldCode": "target_gender",
                "fieldValue": "男"
            }
        ]
    },
    "msg": "ok",
    "isSuccess": true
}
```

### 2. 文档生成接口

**接口地址**: `POST /api/ai/generate-document` 或 `POST /ai/generate-document`

**功能**: 根据输入数据填充Word模板并生成文档

**请求参数**:
```json
{
    "inputData": [
        {
            "fieldCode": "target_name",
            "fieldValue": "张三"
        }
    ],
    "fpolicFieldParamFileList": [
        {
            "fileId": 1765273961563507,
            "fileName": "请示报告卡.docx"
        }
    ]
}
```

**响应格式**:
```json
{
    "code": 0,
    "data": {
        "documentId": "DOC202411260001",
        "documentName": "请示报告卡_张三.docx",
        "fpolicFieldParamFileList": [
            {
                "fileId": 1765273961563507,
                "fileName": "请示报告卡_张三.docx",
                "filePath": "/615873064429507639/20251205090700/请示报告卡_张三.docx",
                "downloadUrl": "https://minio.datacubeworld.com:9000/finyx/..."
            }
        ]
    },
    "msg": "ok",
    "isSuccess": true
}
```

### 3. 获取文件配置列表接口

**接口地址**: `GET /api/file-configs`

**功能**: 获取所有可用的文件配置列表，用于查询可用的fileId

**响应格式**:
```json
{
    "code": 0,
    "data": {
        "fileConfigs": [
            {
                "fileId": 1765273961563507,
                "fileName": "1.请示报告卡（XXX）",
                "filePath": "/615873064429507639/TEMPLATE/2025/12/1.请示报告卡（XXX）.docx"
            }
        ]
    },
    "isSuccess": true
}
```

### 4. 获取字段配置接口

**接口地址**: `GET /api/fields?businessType=INVESTIGATION`

**功能**: 获取指定业务类型的输入和输出字段配置

**响应格式**:
```json
{
    "code": 0,
    "data": {
        "fields": {
            "input_fields": [...],
            "output_fields": [...]
        }
    },
    "isSuccess": true
}
```

### 5. 模板字段关联管理接口

**接口地址**: 
- `GET /api/template-field-relations` - 获取所有模板和字段的关联关系
- `POST /api/template-field-relations` - 保存模板和字段的关联关系

**功能**: 管理模板和字段的关联关系

## 验证服务

运行测试脚本验证服务是否正常：

```bash
python test_scripts/test_service.py
```

## 常见问题

### 1. 提示"未配置AI服务"

**原因**：`.env` 文件中没有正确设置AI服务配置

**解决**：
- 如果使用硅基流动，确保设置了 `SILICONFLOW_API_KEY`
- 如果使用华为大模型，确保设置了 `HUAWEI_API_KEY` 和 `HUAWEI_API_ENDPOINT`
- 检查 `AI_PROVIDER` 设置是否正确（'huawei' 或 'siliconflow'）

### 2. 数据库连接失败

**原因**：数据库服务不可访问或配置错误

**解决**：检查 `.env` 文件中的数据库配置（`DB_HOST`、`DB_PORT`、`DB_USER`、`DB_PASSWORD`、`DB_NAME`），确保数据库服务可访问

### 3. 模块导入失败

**原因**：依赖包未安装

**解决**：运行 `pip install -r requirements.txt` 安装所有依赖

### 4. 端口被占用

**原因**：7500端口已被其他程序使用

**解决**：修改 `app.py` 中的端口号，或设置环境变量 `PORT=其他端口号`

### 5. MinIO连接失败

**原因**：MinIO服务不可访问或配置错误

**解决**：检查 `.env` 文件中的MinIO配置（`MINIO_ENDPOINT`、`MINIO_ACCESS_KEY`、`MINIO_SECRET_KEY`），确保MinIO服务可访问

### 6. 文档生成失败

**原因**：模板文件不存在或字段数据不完整

**解决**：
- 检查 `fileId` 是否正确（可通过 `/api/file-configs` 接口查询）
- 确保 `inputData` 中包含模板所需的所有字段
- 检查模板文件是否存在于MinIO中

## 项目结构

```
.
├── app.py                 # Flask主应用
├── requirements.txt      # Python依赖
├── .env.example          # 环境变量配置示例
├── .env                  # 环境变量配置（需自行创建）
├── services/             # 服务层
│   ├── ai_service.py     # AI服务（大模型调用）
│   ├── field_service.py  # 字段服务（数据库操作）
│   └── document_service.py  # 文档生成服务
├── utils/                # 工具类
│   └── response.py       # 响应格式化
├── static/               # 静态文件
│   ├── index.html        # 测试页面
│   └── template_field_manager.html  # 模板字段管理页面
└── test_scripts/         # 测试脚本
    └── test_service.py   # 服务测试脚本
```

## 下一步

1. 配置API密钥后，服务即可正常使用
2. 访问测试页面进行功能测试
3. 使用Swagger API文档查看完整的接口说明
4. 使用模板字段管理页面配置模板和字段的关联关系
5. 根据实际需求调整字段配置和AI提示词

## 更多资源

- **Swagger API文档**: http://localhost:7500/api-docs - 查看完整的API接口文档
- **占位符与字段对照表**: 查看 `占位符与字段对照表.md` 了解所有可用的字段编码
- **技术文档**: 查看 `技术文档/` 目录了解更多技术细节