Skip to content
BranchesTags

Repository files navigation

外贸企业单证备案系统

AI 驱动的外贸企业单证备案管理系统，支持智能文档识别（OCR）、完整度分析、缺失单证检测、收汇凭证匹配等功能。

功能特性

核心功能

  • 备案管理：报关单备案、单证上传、完整度校验、备案提交/撤销
  • AI 智能分析：自动识别单证完整度、检测缺失单证、收汇凭证匹配、四流一致性检查
  • OCR 文档识别：基于多模态大模型的 PDF/图片文档识别，支持批量处理
  • 收汇管理：外汇收入登记、拆分、核销单关联
  • 客户管理：外商信息管理
  • 报表统计：备案完成率、收汇情况等多维度统计
  • 单证配置：可配置的单证模板和勾稽关系规则

AI 能力

  • 多模态 LLM 文档识别（支持 PDF、JPEG、PNG）
  • 智能完整度评分（0-100 分）
  • 缺失单证自动检测与提醒
  • 收汇凭证智能匹配
  • 四流一致性（合同、报关、收汇、单证）检查

技术栈

后端

技术 版本 说明
Node.js 18+ 运行时
Express 4.21 Web 框架
Sequelize 6.37 ORM
SQLite 6.0 数据库（开发环境）
MySQL 3.x 数据库（生产环境，可选）
BullMQ 5.81 异步任务队列（需 Redis）
ioredis 5.11 Redis 客户端
JWT 9.0 认证
Multer 1.4 文件上传
pdf2pic 3.2 PDF 转图片
Helmet 8.0 安全头
Swagger 5.0 API 文档

前端

技术 版本 说明
React 19.2 UI 框架
Vite 8.0 构建工具
Ant Design 6.3 UI 组件库
Zustand 5.0 状态管理
React Router 7.15 路由
Axios 1.16 HTTP 客户端
ECharts 6.0 图表
Day.js 1.11 日期处理

项目结构

dzba/
├── backend/                    # 后端服务
│   ├── src/
│   │   ├── config/             # 配置（数据库、Swagger）
│   │   ├── middlewares/        # 中间件（认证、限流、企业隔离）
│   │   ├── models/             # 数据模型（Sequelize）
│   │   ├── routes/             # 路由
│   │   ├── services/           # 业务逻辑
│   │   │   ├── aiAnalysisService.js   # AI 分析服务
│   │   │   ├── ocrService.js          # OCR 识别服务
│   │   │   ├── ocrQueue.js            # OCR 异步队列
│   │   │   ├── fileStorage.js         # 文件存储
│   │   │   └── redis.js               # Redis 连接（优雅降级）
│   │   ├── scripts/            # 初始化脚本
│   │   ├── utils/              # 工具函数
│   │   └── app.js              # 入口文件
│   ├── data/                   # SQLite 数据库文件
│   ├── uploads/                # 上传文件存储
│   ├── .env.example            # 环境变量示例
│   └── package.json
├── frontend/                   # 前端应用
│   ├── src/
│   │   ├── components/         # 公共组件
│   │   │   ├── AiUploadPanel.jsx      # AI 上传面板
│   │   │   └── AiAnalysisPanel.jsx    # AI 分析面板
│   │   ├── pages/              # 页面
│   │   │   ├── FilingManagement.jsx   # 备案管理
│   │   │   ├── DocConfig.jsx          # 单证配置
│   │   │   ├── ExchangeRegistration.jsx # 收汇登记
│   │   │   ├── CustomerManagement.jsx # 客户管理
│   │   │   ├── Dashboard.jsx          # 仪表盘
│   │   │   └── ...
│   │   ├── store/              # 状态管理（Zustand）
│   │   ├── layouts/            # 布局
│   │   └── App.jsx             # 路由配置
│   ├── vite.config.js          # Vite 配置
│   └── package.json
└── README.md

快速开始

前置要求

  • Node.js 18+
  • （可选）Redis 6+ — 用于 OCR 异步队列
  • （可选）MySQL 8+ — 生产环境数据库

安装

# 克隆项目
git clone https://github.com/painrice/dzba.git
cd dzba

# 安装后端依赖
cd backend
npm install

# 安装前端依赖
cd ../frontend
npm install

配置

# 后端环境变量
cd backend
cp .env.example .env
# 编辑 .env 文件配置数据库、JWT、LLM API 等

.env 示例：

# 服务端口
PORT=3000
NODE_ENV=development

# JWT 密钥（生产环境必须修改）
JWT_SECRET=your-secret-key-here

# 数据库（SQLite）
DB_STORAGE=./data/filing_system.sqlite

# Redis（可选，用于 OCR 异步队列）
REDIS_HOST=localhost
REDIS_PORT=6379

# 大模型 API（OCR 和 AI 分析）
LLM_API_BASE_URL=https://api.deepseek.com/v1
LLM_API_KEY=your-api-key
LLM_VISION_MODEL=deepseek-vl2

# 文件上传限制
MAX_FILE_SIZE=20971520

初始化数据库

cd backend
npm run init-db

启动

# 启动后端（端口 3000）
cd backend
npm start

# 启动前端（端口 5173）
cd frontend
npm run dev

访问

默认账号

用户名 密码 企业
admin 123456 深圳市XX国际贸易有限公司
manager1 123456 深圳市XX国际贸易有限公司
staff1 123456 深圳市XX国际贸易有限公司

API 概览

认证

方法 路径 说明
POST /api/auth/login 登录
POST /api/auth/refresh 刷新 Token
GET /api/auth/profile 获取用户信息

备案管理

方法 路径 说明
GET /api/filings 备案列表（分页）
GET /api/filings/:id 备案详情
POST /api/filings 创建备案记录
PUT /api/filings/:id 更新备案
POST /api/filings/:id/submit 提交备案
POST /api/filings/:id/revoke 撤销备案
POST /api/filings/:id/documents/:idx/skip 跳过单证
POST /api/filings/:id/documents/:idx/unskip 取消跳过

AI 分析

方法 路径 说明
POST /api/ai/analyze/:filingId 执行 AI 分析
GET /api/ai/analyze/:filingId/result 获取分析结果
GET /api/ai/analyze/:filingId/history 分析历史
GET /api/ai/analyze/:filingId/exchange-receipts 收汇凭证列表
POST /api/ai/analyze/:filingId/recheck 重新分析

OCR 识别

方法 路径 说明
POST /api/ocr/filing-package/batch 批量 OCR 识别
GET /api/ocr/tasks/:id 查询任务状态
GET /api/ocr/tasks/:id/result 获取识别结果

文件上传

方法 路径 说明
POST /api/upload 单文件上传
POST /api/upload/multiple 多文件上传
GET /api/download/:id 文件下载
GET /api/files/:id 文件信息
DELETE /api/files/:id 删除文件

单证配置

方法 路径 说明
GET /api/doc-config/templates 单证模板列表
POST /api/doc-config/templates 创建模板
PUT /api/doc-config/templates/:id 更新模板
DELETE /api/doc-config/templates/:id 删除模板
GET /api/doc-config/rules 勾稽规则列表
POST /api/doc-config/rules 创建规则
PUT /api/doc-config/rules/:id 更新规则
DELETE /api/doc-config/rules/:id 删除规则

数据模型

核心实体

  • BizFilingRecord — 备案记录
  • BizFilingDocument — 备案单证（含跳过标记）
  • BizDeclaration — 报关单
  • BizExchangeRecord — 收汇记录
  • SysAttachment — 附件
  • SysAiAnalysis — AI 分析结果
  • SysDocTemplate — 单证模板
  • SysDocRule — 勾稽关系规则

部署

前端构建

cd frontend
npm run build
# 输出到 dist/ 目录

生产环境配置

  1. 配置 .env 文件：设置 NODE_ENV=production、JWT_SECRET、数据库连接等
  2. 如使用 MySQL，修改 backend/src/config/database.js 切换 dialect
  3. 配置 Redis 以启用 OCR 异步队列

Docker 部署（建议）

# docker-compose.yml 示例
version: '3.8'
services:
  backend:
    build: ./backend
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - REDIS_HOST=redis
    depends_on:
      - redis
  frontend:
    build: ./frontend
    ports:
      - "80:80"
  redis:
    image: redis:7-alpine

架构说明

设计原则

  • 依赖降级：Redis 不可用时系统仍可正常运行（仅 OCR 队列不可用）
  • 企业隔离：所有 API 按企业 ID 隔离数据
  • 单证模板化：企业可自定义必填单证清单，无需修改代码
  • 文件本地存储：默认本地文件系统，可扩展至 MinIO/S3

安全特性

  • JWT 认证 + Token 刷新
  • 接口限流（登录、上传）
  • 企业数据隔离
  • Helmet 安全头
  • 操作日志审计

License

MIT

About

AI 驱动的外贸企业单证备案管理系统，支持智能文档识别（OCR）、完整度分析、缺失单证检测、收汇凭证匹配等功能。

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages