COA Document Workflow POC

一个可运行、可修改的 COA 文件标准化工作流参考实现。项目公开的是一套真实 POC 的业务理解与工程方法，而不是一个可直接替代企业实施的通用 SaaS 产品。

• 在线体验：https://poc.kysion.work/coa-document-workflow-poc/
• GitHub：https://github.com/HiOne0826/coa-document-workflow-poc
• License：Apache-2.0

这个项目解决什么问题

企业收到的供应商 COA 往往来自不同厂商，文件格式、字段名称、单位、判定标准和版式都不一致。真正的工作不只是 OCR，而是把文件放进一条可复核、可追溯、可归档的业务流程：

供应商 PDF / 图片
→ 文档解析与字段提取
→ 企业字段、单位和规则标准化
→ 人工对照原件复核
→ 按企业模板生成 HTML / PDF / JSON
→ 确认、归档或发送到下游系统

本仓库实现了其中最小但完整的闭环：

1. 批量上传 PDF、JPG、PNG，并创建后台提取任务。
2. 从数字 PDF 或扫描件中恢复文本和字段证据。
3. 按字段别名、产品画像、单位和值规则生成 COA 草稿。
4. 在同一页面对照原件、来源证据和目标结果进行人工复核。
5. 按企业模板生成版本化的 HTML、PDF 和 JSON，并保留审计状态。

它适合用于评估“文档标准化如何进入企业真实流程”，不应被理解为单独上传文件就能自动产生完整业务价值。生产价值通常来自规则共建、角色分工、权限、异常处理、系统集成和持续运营。

主要页面

• 批量上传：创建批次，上传多份供应商文件并查看处理进度。
• 字段复核：左右对照原文件、提取证据和 COA 草稿，修正后确认。
• 文件归档：查看、下载已经确认的 HTML、PDF 和 JSON 版本。

V2 Web 入口是 /v2/，API 使用 /api/v2/*。旧 POC 接口仍保留兼容。

技术结构

• 前端：React、TypeScript、Vite、Arco Design、TanStack Query。
• API：FastAPI，负责校验、持久化和任务入队。
• Worker：Huey 独立进程，执行文档处理和渲染任务。
• 数据：SQLite 保存业务状态，本地 BlobStore 保存原件和版本产物。
• 模板：Jinja2 生成 HTML，Playwright/Chromium 生成 PDF。
• Agent 接入：HTTP API，以及仓库内提供的 stdio MCP Server / Skill 示例。

快速开始

需要 Docker Desktop，或 Docker Engine + Compose plugin。

git clone https://github.com/HiOne0826/coa-document-workflow-poc.git
cd coa-document-workflow-poc
cp .env.example .env
docker compose up -d --build
docker compose ps
curl -fsS http://127.0.0.1:8765/api/v2/health/ready

打开 http://127.0.0.1:8765/v2/。

Compose 会启动 web 和 worker 两个容器并共享持久卷。不要在未备份时执行 docker compose down -v。

不使用 Docker

推荐 Python 3.12 和 Node.js 22：

python3.12 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
cd frontend && npm ci && npm run build && cd ..
python -m uvicorn app.fastapi_app:app --host 127.0.0.1 --port 8765

另开一个终端启动 worker：

. .venv/bin/activate
python -m huey.bin.huey_consumer app.worker.huey \
  --workers=1 --worker-type=thread --delay=0.1 --max-delay=2

怎么使用

1. 打开 /v2/，创建一个批次。
2. 上传一份或多份 COA PDF / 图片。
3. 等待任务处理完成；失败任务可从界面或 API 重试。
4. 打开文档复核页，对照原件检查字段、单位、标准、结果和证据。
5. 修正字段并确认，系统会生成版本化输出。
6. 在归档页下载 HTML、PDF、JSON，或接入自己的归档系统。

就绪检查：

curl -fsS http://127.0.0.1:8765/api/v2/health/ready

列出批次：

curl -fsS http://127.0.0.1:8765/api/v2/batches

创建批次：

curl -fsS -X POST http://127.0.0.1:8765/api/v2/batches \
  -H 'Content-Type: application/json' \
  -d '{"name":"my-first-batch"}'

完整 API 可在服务启动后查看 /docs。

修改成自己的规则与格式

这个 POC 把容易变化的业务内容尽量放在配置和模板中。建议先复制现有配置，再做小步修改和回归测试。

1. 字段别名

编辑 app/config/field_aliases.json，把供应商的不同写法映射到企业标准字段，例如 Hg、Mercury 和 汞。

2. 单位与数值规则

• app/config/unit_rules.json：单位标准化和等价表达。
• app/config/value_rules.json：≤、≥、ND、范围值等表达的归一化。

3. 产品或客户规则

编辑 app/config/product_profiles.json。每个 profile 可以包含：

• 产品关键词与匹配条件；
• 企业使用的产品名称；
• 批次、包装、保质期等补充信息；
• 字段列表、标准值、单位和默认结果。

不要直接把真实生产规则改进唯一一份默认文件。更稳妥的做法是为客户建立独立分支或独立配置包，并用其自己的样例文件做回归测试。

4. 输出版式

当前 COA 模板位于 app/templates/coa/ingreland_coa_v1.html.j2。你可以复制为新的版本，例如：

app/templates/coa/acme_coa_v1.html.j2

然后同步更新模板版本选择、品牌信息、字段顺序、颜色、页眉、签章和打印样式。不要在原模板上覆盖多个客户的版式，否则升级和验收时很难判断使用了哪套规则。

5. 用自己的文件回归

测试清单在 tests/fixtures/coa/cases.json。新增客户规则时，至少保留以下配对：

供应商原始文件
→ 期望结构化 JSON
→ 期望模板版本
→ 期望 PDF / HTML 关键字段

运行：

.venv/bin/python -m pytest
cd frontend && npm run build

涉及真实客户文件时，应确认客户授权，并避免在 Issue、PR、日志或公开构建产物中泄露不应公开的数据。

让本地 Agent 帮你部署和修改

本项目适合交给能够读写本地仓库、运行命令和访问 HTTP API 的 coding agent。推荐把任务拆成三个明确阶段。

阶段一：本地部署

可以把下面的要求直接交给本地 Agent：

请检查这个仓库的 README、.env.example 和 docker-compose.yml。
在本机复制 .env.example 为 .env，使用 Docker Compose 启动 web 和 worker。
不要把服务绑定到公网地址。启动后访问 /api/v2/health/ready，确认 database、storage、queue 都为 true。

阶段二：按企业规则改造

把已脱敏的供应商文件、目标模板和验收表放到一个不公开的工作目录，再要求 Agent：

请先对比供应商原文件和目标 COA，列出字段映射、单位规则、值规则、产品规则和版式差异。
确认差异后再修改 app/config 下的 JSON 和新的 Jinja2 模板。
保留现有规则，不覆盖其他客户配置；为新规则补充测试用例并运行测试。

阶段三：部署验收

请先备份运行数据，再部署本次修改。
部署后验证 Web、worker、健康接口、实际文件上传、字段复核和 PDF 下载。
最后列出使用的规则版本、模板版本、测试文件和回滚位置。

不要只让 Agent “把 OCR 调通”。企业落地至少还应明确：规则负责人、复核人、异常处理、版本发布、数据权限、归档位置和验收样例。

MCP 接入

仓库中的 mcp_server.py 和 mcp.json 提供 stdio MCP 示例，可让支持 MCP 的本地 Agent 调用兼容接口。

cp mcp.json mcp.local.json

默认连接 http://127.0.0.1:8765。如需连接其他受信任服务，修改配置中的 API 地址；非本机服务必须使用 HTTPS。工具说明和调用链见 docs/MCP与Skill接入说明.md。

MCP 只是 Agent 与服务之间的调用接口，不会自动替你定义企业规则、判断字段是否正确或完成最终业务验收。

配置

常用环境变量见 .env.example：

• INGRELAND_BIND_ADDRESS、INGRELAND_PORT：兼容保留的监听配置名。
• MAX_BATCH_FILES、MAX_FILE_BYTES、MAX_PDF_PAGES：上传限制。
• OPENAI_API_KEY：可选模型凭据，只应保存在部署环境。
• LARK_APP_ID、LARK_APP_SECRET、LARK_ARCHIVE_CHAT_ID：可选飞书归档配置。

INGRELAND_* 是早期客户 POC 遗留的兼容环境变量。修改项目展示名称不会自动迁移已有部署的数据卷和环境变量；如需重命名这些内部标识，应单独设计兼容迁移。

备份与恢复

备份会使用 SQLite 在线备份 API并生成哈希清单，不要直接复制正在运行的 SQLite 文件：

mkdir -p backups
docker compose run --rm -v "$PWD/backups:/backup" web \
  python scripts/backup_v2.py backup /backup/coa-workflow-v2.tar.gz

恢复只允许写入空目录。完整步骤见 docs/V2部署与运维.md。

测试

.venv/bin/python -m pytest
.venv/bin/python scripts/smoke_v2_golden.py
.venv/bin/python scripts/smoke_v2_e2e.py
.venv/bin/python scripts/smoke_v2_compose.py
.venv/bin/python scripts/smoke_huey_recovery.py
cd frontend && npm run build && npm audit

部分 smoke 依赖本地客户样例目录，运行前请确认对应文件存在且你有权使用。

生产边界

• 当前版本没有应用层登录和多租户隔离。公网部署必须在反向代理、VPN 或企业网关层增加认证、TLS、限流和上传大小限制。
• 示例规则、模板和测试数据不等同于你所在企业的正式标准，必须经过业务负责人验收。
• AI 只生成字段候选，不应绕过人工复核直接形成正式质量文件。
• 源文件、字段草稿、复核记录和归档版本可能包含敏感数据，需要制定保存周期和访问权限。
• 飞书、模型和其他第三方凭据不得提交到 Git。

开源与案例边界

仓库保留了原客户 POC 的规则、模板和经授权测试材料，用于展示真实业务约束和回归方法。客户名称出现在案例材料中，不代表该客户为本开源项目背书，也不代表 Apache-2.0 许可授予任何客户名称、Logo 或商标的使用权。详见 NOTICE。

• 安全报告：SECURITY.md
• 贡献流程：CONTRIBUTING.md
• 行为准则：CODE_OF_CONDUCT.md
• 第三方依赖：THIRD_PARTY_NOTICES.md

License

代码以 Apache License 2.0 发布。客户材料、品牌资产和第三方内容仍受各自权利约束。