# mingzhi

**Repository Path**: sh_huahui/mingzhi

## Basic Information

- **Project Name**: mingzhi
- **Description**: 财务智能审核规则库以及智能化审核项目
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-07
- **Last Updated**: 2026-09-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 明审：财务智能审核 MVP

## P0/P1 内网试用能力

已加入登录与系统/组织权限、草稿发布预览、条件规则、异常闭环、累计凭证占用、附件预处理/分类拆页和评测工具。首次打开需创建管理员；原无令牌脚本现在会返回401。详见 [交付记录](docs/p0-p1-release.md)。未做实在智能联调，使用自有HTTP客户端；真实模型效果与国产实机仍待验证。

## 通用财务智审版本

新增场景中心、通用主从表、独立审核方案、通用凭证分摊与场景包导入导出。费用报销、采购付款、收款核销共用引擎；日常填写使用中文动态表单，JSON折叠在高级区。详见 [通用化交付记录](docs/generic-platform-release.md)。当前示例数据均为模拟，不代表实际制度。

## 第三批更新

出差主单/审批/明细可视化编辑、记录检索分页、费用类别白名单、跨单据附件复用提示、离线源码制包与校验已加入，详见 [第三批交付记录](docs/batch-3-release.md)。新接口 GET /api/v1/records 支持 system/form/decision/human_decision/document/limit/offset；原 submissions 接口保留兼容。

## 第一、二批集成版本

最新进展以 [两批交付记录](docs/batch-1-2-release.md) 为准：PostgreSQL 真连接验证、出差主从表与附件分摊、OCR 重启恢复与失败重试、模型中断重试、离线交付底座均已加入。最终联合测试 62 项全部通过。当前 8765 保留 SQLite 历史，独立 PostgreSQL 开发入口见 deploy/start-postgres-dev.ps1；未自动搬迁旧数据。

下文部分初期描述中的“重启不可恢复”和“未接 PostgreSQL”已由上述新版本替代；国产实机、达梦、完整离线包和多人权限仍未完成。

## 财务校验与案例回放

审核规则增加 `field_gt`（value 为比较字段编码）和 `sum_ne`（value 为参与求和的字段编码数组），支持非负 tolerance；字段均需定义为 number，缺失输入返回未知。计算使用 Decimal，当前合计针对主表字段，不是明细子表。

在财务审核调试页填写案例名称、人工预期结论和预期问题编号后保存。在“案例与回放”选择最多 20 条运行，报告保存完整配置与案例快照。案例固定 history_fixture（默认空数组），不读取实时正式历史。

新增接口：`GET/POST /api/v1/test-cases`；`GET/POST /api/v1/evaluations`。回放 POST 传 case_ids 数组，可带 draft_config。结果 matched 要求结论与问题编号集合均一致；模型不可用计为执行异常。它不代表真实财务准确率。

完整测试：`python -m unittest -v test_server.py test_extras.py test_quality.py`。

## 最新调整：财务数据智审

- 菜单为“模型配置”，仅管理模型资源与连接测试。
- “系统与表单”选择审核类型：规则、模型、规则与模型联合、人工；模型和财务审核说明同处配置。
- “财务审核调试”支持普通、大额和缺项样例，展示字段校验、规则实际值与比较值、模型意见及耗时。
- `POST /api/v1/debug` 与正式审核共用执行逻辑，可传 `audit_type` 和 `draft_config`；不写入正式历史、不会污染重复检查和学习样本。
- 正式提交可传与已发布配置一致的 `audit_type`；不允许客户端任意跳过配置的审核类型。
- 模型意见保持辅助性质，规则拦截优先；人工复核要求可单独配置。

下文早期版本中的“接口试跑”和“小模型审核”分别已替换为“财务审核调试”和“模型配置”。

Python 3.11+；规则审核为标准库，OCR 需要 requirements-ocr.txt 中的依赖。界面、附件和识别计算在本机运行。

## 附件与 OCR

已接入 RapidOCR CPU 和 PDFium。可处理 PNG/JPEG、文字 PDF、扫描 PDF；多文件进入单工作进程队列，每个原生识别进程硬超时 180 秒。参考引擎：[RapidOCR](https://github.com/RapidAI/RapidOCR)、[PDFium Python 绑定](https://pypi.org/project/pypdfium2/)。

首次部署执行 `python -m venv .venv`，再执行 `.venv/Scripts/python.exe -m pip install -r requirements-ocr.txt`。使用 start.ps1 启动会优先使用虚拟环境。模型随 OCR 包安装；运行时不向外网发送附件。

“附件与 OCR”中先选择表单，添加附件类型并保存。每个表单的发票、回单、合同等类型可单独配置：文字优先/强制 OCR/仅文字层、DPI、页数限制、灰度、置信度提示、关键词、必需附件及字段标签映射。类型可改名，预置参数仅为起点。

上传支持单文件 10 MB，最多 20 页（按配置），2000 万像素，队列最多 20 个任务。超过限制或失败不会返回部分成功。重启时未完成任务标失败，调整配置后可重新上传；尚无自动断点续跑。

候选提取为标签匹配，并非所有票据版式通用的专用模型。多候选必须人工处理。页面预览、原文行、OCR 框和置信度留存；文字 PDF 的置信度为 null，不能视为 100% 正确。手写、复杂表格、印章与真伪查验不在本版保证范围。

确认字段后，勾选“加入本次审核”，调试和提交会带 attachment_ids。平台校验必需附件、识别完成状态、人工确认、映射值与表单一致性；金额按容差比较。不自动覆盖 RPA 传入的表单值。

每次正式审核和案例保存均固化附件识别及修正快照。模型/联合审核会将本次绑定附件的识别文本和确认字段一起发送给选定的本地模型，输入超限则返回 unknown；历史附件不会默认发送。

API：GET /api/attachment-presets；GET/POST /api/attachments（POST 输入 system、form、profile_id、filename、content_base64）；GET /api/attachments/{id}；POST /api/attachments/{id}/confirm（revision、reviewer、reason、values）；GET /api/attachments/{id}/pages/{page}。

文件和页面存储在 attachment-data/，元数据与人工修正保存在 SQLite。备份需同时包含数据库和 attachment-data。暂未提供自动清理、病毒扫描、实名签核与权限隔离，不应直接暴露公网。

测试：`.venv/Scripts/python.exe -m unittest -v test_server.py test_extras.py test_quality.py test_attachments.py`，包含真实 CPU OCR、文字 PDF 和扫描 PDF 回归测试。

## 启动

在本目录执行 `python server.py`，打开 http://127.0.0.1:8765 。也可在 PowerShell 执行 `./start.ps1`。

SQLite 数据文件首次启动自动创建为 `data.sqlite3`。关闭服务后复制此文件即可备份；不要在运行中直接复制用于正式备份。`AUDIT_DB`、`AUDIT_PORT` 环境变量可调整路径与端口。

## 已实现

- 系统、表单、字段和规则可通过界面配置；配置带版本冲突检测。
- 字段支持文本、数字、布尔及必填检查；额外字段保留但不执行类型检查。
- 命中条件支持大于、小于、等于、不等于、包含和同系统同表单历史重复。
- 审核方式：规则、人工、规则后人工复核。无规则时不会自动通过。
- 标准 JSON 提交与结果查询；请求编号幂等；不同内容复用编号返回 400。
- 每次提交保存原始数据、配置快照、检查结果。相同单据的新请求形成历史记录。
- 人工复核历史、最新人工结论、带标签的 JSON 学习样本导出。
- 页面展示最近 200 条记录，数据库保留全部历史。

## 标准接口

`POST /api/v1/submissions`，Content-Type: application/json：

```json
{
  "request_id": "your-unique-request-id",
  "system": "erp-demo",
  "form": "expense",
  "document_id": "BX001",
  "data": {"amount": 1200, "invoice": "INV001", "reason": "差旅"}
}
```

返回 submission_id、decision、findings、checks、config_version、created_at。规则结论为 passed / blocked / pending_review；approval_executed 始终 false。

- `GET /api/v1/submissions/{submission_id}`：完整详情及复核历史。
- `GET /api/v1/submissions`：最近 200 条。
- `POST /api/v1/submissions/{submission_id}/feedback`：提交 `decision`（passed/blocked）、`reviewer`、`reason`。
- `GET /api/v1/learning-samples`：人工标签样本，每次复核一条。
- `GET /api/config`：当前配置。
- `POST /api/config`：完整配置及当前 version，发布下一版。

任何 RPA 厂商都可使用 HTTP 节点调用。Node.js 可使用 fetch。浏览器 ERP 页面跨域请求未开放，需受控桥接；服务也未对其他电脑开放。

人工结论与原始规则判断分别保存。接口消费者应先检查是否存在 human_decision，再按企业流程处理；这里的结论不是 ERP 已审批成功的证明。

## 首次体验

1. 在系统与表单页面查看预置费用报销模型。
2. 接口试跑默认提交 6800 元，触发示例 5000 元限额拦截。
3. 修改为 1200 元并换 request_id，得到待复核（预置为混合审核）。
4. 在历史记录详情填写复核人、结论和原因。
5. 导出学习样本。再次启动服务，历史仍在。

## MVP 边界

这是本机单用户原型，不是已加固的内网生产系统。暂无身份认证、组织权限、文件附件/OCR、明细子表、异步任务、分页查询、自动模型训练、审批执行和不可篡改审计。复核人是手工输入。学习样本保存用于后续人工整理和评测，不会自动改规则。

预置限额仅为演示，不是税法或企业制度。重复检查扫描所有已提交历史（包含被驳回、未完成复核的单据），只做风险提示，不能确认重复付款。大数据量时需要专用索引与分页。

生产化前需要补充认证授权、HTTPS、组织隔离、数据保留策略、规范审批和数据库迁移。当前服务有本机绑定、Host/Origin 检查、JSON 大小限制、参数化 SQL、页面转义；不应直接改为 0.0.0.0 对外提供。

## 测试

运行 `python -m unittest -v test_server.py test_extras.py`。测试使用临时数据库，不污染演示数据。

## HTML 表单模板（新增）

“表单模板”页面内置费用报销、付款申请和采购申请三类示例。也可上传 UTF-8 HTML 文件或粘贴表单 HTML，提取后逐项编辑字段，再确认创建表单。

- 支持原生 input/select/textarea、显式 label、aria 标签、部分表格标签和值，以及 data-field 元素。
- 不运行脚本，不获取 HTML 引用的资源，不落库 HTML 原文和控件填充值。仅保留字段定义和来源哈希。
- hidden/password/file 等控件跳过；radio 合并；多选暂按文本处理。
- 复杂自定义组件、动态未渲染页面和重复明细子表需人工补充；字段标签和必填要求必须人工确认。
- 生成模板以“规则 + 人工复核”创建，不推断业务限额。
- `GET /api/templates` 获取示例，`POST /api/templates/extract` 传入 `{"html":"..."}` 获取候选结构；发布仍走 `/api/config`。

## 本地小模型辅助审核（新增）

“小模型审核”页面可配置多个本地模型，分别绑定不同表单。服务协议为 `/v1/chat/completions`；Ollama 兼容接口见 https://docs.ollama.com/api/openai-compatibility 。不自动安装或下载模型，也不预设已安装模型名称。

1. 在本机运行兼容服务，确认实际模型名称。
2. 添加配置，地址例如 `http://127.0.0.1:11434/v1`，填写模型名和超时（最多 60 秒）。
3. 点击“测试结构化响应”，只发送内置虚构样本。
4. 给表单选择模型并填写审核说明，保存发布。纯人工方式不调用模型。
5. 正常提交表单，结果多出 `model_review`，历史详情保留模型意见、模型名称和提示词版本。

首版只连接 127.0.0.1，不支持云端或远程内网地址、鉴权型模型服务；禁用代理和重定向。仅发送当前模板已声明字段，不传历史数据和原始 HTML。

模型为辅助能力，不改变规则拦截，也不会自动通过单据。异常响应、超时、未配置审核说明均返回 unknown。结构化意见中的原文引用做简单包含校验；这不是完整的事实验证。模型审核先保存原始单据，再调用服务，不长时间持有 SQLite 写锁。

重复 request_id 可能在模型执行期间返回 processing，可稍后按 submission_id 查询。若执行中进程终止，仍需人工复核或用新 request_id 重审；本版尚无模型任务恢复队列。模型调用效果需要真实脱敏样本评测，本机未安装模型时仅能验证接入协议与异常处理。