5.4 KiB
Dieya Risk Prediction Backend
本项目参考 dy_finance_agent_backend 的分层方式，使用 Python 3.11、FastAPI、Pydantic v2、SQLAlchemy 2.x Async、PostgreSQL 和 Alembic。
本地启动
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
python -m uvicorn app.main:app --host 127.0.0.1 --port 18474
创建本地密码账号（密码只保存哈希）：
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 数据：
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 建外键权限的数据库账号执行：
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 签名、处理中状态与部署说明见 外部接口文档。
非钉钉操作人可用 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。