# Dieya Risk Prediction Backend

本项目参考 `dy_finance_agent_backend` 的分层方式，使用 Python 3.11、FastAPI、Pydantic v2、SQLAlchemy 2.x Async、PostgreSQL 和 Alembic。

## 本地启动

```powershell
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
python -m uvicorn app.main:app --host 127.0.0.1 --port 18474
```

创建本地密码账号（密码只保存哈希）：

```powershell
python scripts/create_user.py --emp-no admin001 --name 管理员 --role admin --password "请替换为强密码" --email admin@dieya.com
```

钉钉免登需要额外配置 `RISK_DINGTALK_APP_KEY`、`RISK_DINGTALK_APP_SECRET`、`RISK_DINGTALK_CORP_ID` 和 `RISK_DINGTALK_AGENT_ID`；前端在钉钉容器中调用 `requestAuthCode()`，后端换码后签发本系统 JWT。

认证接口：`POST /api/v1/auth/login`、`GET /api/v1/auth/me`、`GET /api/v1/auth/dingtalk/config`、`POST /api/v1/auth/dingtalk/login`。

审核接口：`POST /api/v1/risk-items`、`GET /api/v1/risk-items/pending`、`POST /api/v1/risk-items/{id}/review`。

OCR 接口：`POST /api/v1/ocr/recognize` 接收最多 5 个 JPG、PNG 或 PDF 文件，图片调用百度 WebImage，PDF 调用 PaddleOCR-VL 文档解析；返回可编辑字段、检测数值、置信度及标准库判定。`POST /api/v1/ocr/judge` 用于人工修正检测值后重新判定，`GET /api/v1/ocr/files/{file_id}` 通过登录鉴权读取原始附件。启用前配置 `BAIDU_OCR_API_KEY` 和 `BAIDU_OCR_SECRET_KEY`，并执行数据库迁移。

角色采用管理员 `admin`、产品经理 `product_manager`、审核员 `reviewer`、普通用户 `user` 四类。模型权重由管理员通过 `GET/PATCH /api/v1/model-config` 维护，七维权重合计必须为 100%，修改仅对新评估生效。

钉钉免登用户按两级规则同步：钉钉管理员或部门主管映射为 `admin`（已包含审核权限），其他钉钉用户统一映射为 `user`。`product_manager` 和 `reviewer` 仅保留给非钉钉账号或后续独立用户管理流程使用。

健康检查：`GET http://127.0.0.1:18474/api/v1/health`

数据库表结构和字段释义通过 Alembic 管理。执行 `python -m alembic upgrade head` 会创建或更新表、索引、外键及 PostgreSQL 表/字段注释。

导入 PRD 数据：

```powershell
python -m alembic upgrade head
python scripts/import_excel_data.py `
  --anomaly-file "C:\Users\Administrator\Desktop\异常数据汇总表.xlsx" `
  --standard-file "C:\Users\Administrator\Desktop\标准文件.xlsx"
```

脚本只导入异常明细 Sheet 的 2,448 条记录，以及标准文件中的“包装/包材/法规/内料”四个分类 Sheet 共 219 条记录；“总表”不重复导入。脚本可重复执行，已导入行会按源文件、Sheet 和 Excel 行号自动跳过。原始异常文本和标准附件链接会完整保留，不做截断。

供应商清洗采用“原始字段保留 + 主数据 + 多对多关联”方式，不覆盖 `anomaly_cases.supplier`。使用具备建表及对 `anomaly_cases` 建外键权限的数据库账号执行：

```powershell
python -m alembic upgrade head
python scripts/clean_suppliers.py
```

脚本会拆分 `/`、`、`、逗号、分号及换行分隔的复合供应商，生成 `supplier_master` 和 `anomaly_case_suppliers`；自动结果默认处于“待确认”状态。管理员应补充主数据中的标准名称、别名、城市与省份后再标记为“已确认”。供应商搜索会优先匹配标准名称、简称、别名、城市和省份；迁移尚未执行时自动回退到原始字段搜索。

风险评估预览：`POST http://127.0.0.1:18474/api/v1/risk-predictions/preview`。指标值表示风险程度（0-100），接口返回的综合分按 PRD 转换为安全得分，分数越高风险越低；等级阈值为 80/60/40/20。

外部系统风险报告：`POST /api/v1/integrations/risk-assessments/report` 使用 HMAC 签名鉴权，返回 Markdown 报告及 `X-Risk-Score`、`X-Risk-Level` 等响应头。`GET` 同路径按 `requestId` 查询已保存报告。启用前执行 `python -m alembic upgrade head`，配置 `RISK_INTEGRATION_CLIENTS` JSON 密钥表，并确保操作人已在本地绑定钉钉 UnionId 且拥有 `risk.assess` 操作权限；默认不自动创建用户。完整参数、GET/POST 签名、处理中状态与部署说明见 [外部接口文档](docs/外部系统风险评估报告接口.md)。

非钉钉操作人可用 `operator.externalUserId`，通过 `RISK_INTEGRATION_OPERATOR_MAPPINGS` 按调用系统显式映射到本地账号；仍校验本地状态及权限。开通工具：`python scripts/setup_external_risk.py allow-user --client-id dieya-plm --external-user-id superadmin --employee-no plm_superadmin --name "周子墨"`。该模式与钉钉身份二选一，配置后需重启后端。


对话页真实 AI：配置 `RISK_LLM_API_KEY`、`RISK_LLM_BASE_URL` 和 `RISK_LLM_MODEL` 后，调用 `POST /api/v1/conversations/{id}/stream`。接口使用 OpenAI 兼容 Chat Completions 协议，先提取 `intent/category/specification/packaging/supplier/factory/stage/confidence` 语义 JSON，再通过 SSE 返回增量文本；最近 20 条消息作为上下文，完整助手消息、语义结果和风险评分会在流结束后持久化。也兼容参考项目的 `OPENAI_API_KEY`、`LLM_BASE_URL`、`LLM_MODEL` 配置名。未配置密钥时返回明确的 503，不生成模拟回复。

架构说明见 [docs/architecture.md](docs/architecture.md)。