# 订单回款系统 **Repository Path**: teampanel/order-receivable-system ## Basic Information - **Project Name**: 订单回款系统 - **Description**: 订单回款系统 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-09-05 - **Last Updated**: 2026-09-05 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 订单回款系统 > **核心目标：将客户欠款核对时间从 10 分钟降到 1 分钟内。** --- ## 目录 - [项目简介](#项目简介) - [技术栈](#技术栈) - [项目结构](#项目结构) - [架构设计](#架构设计) - [核心功能](#核心功能) - [系统截图](#系统截图) - [快速开始](#快速开始) - [启动后端](#启动后端) - [启动前端](#启动前端) - [API 接口清单](#api-接口清单) - [数据模型](#数据模型) - [ERP 对接说明](#erp-对接说明) - [账号信息](#账号信息) --- ## 项目简介 当前企业核对客户欠款为人工操作，逐笔翻查 ERP 系统中的订单与回款记录、手工计算差额，核对一个客户约需 10 分钟。本系统通过对接自有 ERP 系统 API，将客户、订单、回款数据同步到本地数据库，并提供自动试算欠款余额的 Web 管理后台，实现**单客户对账时间缩短至 1 分钟左右（查询时间下降约 90%）**。 --- ## 技术栈 | 层级 | 技术 | 说明 | |------|------|------| | 后端 | Java 17 + Spring Boot 3.2.5 + Maven | RESTful API，Spring Data JPA | | 前端 | Vue3 + TypeScript + Vite + Element Plus + Pinia + Tailwind | 基于 Art Design Pro 中后台模板 | | 数据库 | H2（默认，零依赖可跑）/ MySQL（生产切换） | 本地镜像存储客户/订单/回款数据 | | 鉴权 | JWT (JJWT) | 简易 JWT 登录鉴权 | --- ## 项目结构 ``` order-receivable-system/ ├── docs/ │ └── DESIGN.md # 设计基线文档（含完整 API 契约与数据模型） ├── backend/ # Spring Boot 3.2 后端 │ ├── pom.xml │ └── src/main/java/com/xxwei/receivable/ │ ├── ReceivableApplication.java # 启动类 │ ├── config/ # 跨域、JWT 拦截、数据初始化配置 │ ├── controller/ # REST 控制器（8 个业务接口） │ ├── dto/ # 数据传输对象（VO、查询条件、统一响应包装） │ ├── entity/ # JPA 实体（customer/order/payment/sync_log/sys_user） │ ├── repository/ # Spring Data JPA 仓库接口 │ ├── service/ # 业务逻辑层（Reconciliation/Sync/Auth） │ └── erp/ # ERP 网关 SPI + Mock/Http 实现 │ └── src/main/resources/ │ ├── application.yml # H2 file 模式（默认） │ └── application-mysql.yml # MySQL 切换配置 └── frontend/ # Art Design Pro Vue3 前端 ├── package.json └── src/ ├── views/receivable/ # 回款管理业务页面（6 个） ├── api/receivable.ts # 后端接口封装 ├── router/modules/receivable.ts # 路由模块 └── utils/http/ # 请求封装与响应拦截器 ``` --- ## 架构设计 ``` ┌───────────────────────────────────────────────┐ │ Art Design Pro 前端 (Vue3) │ │ 登录 / 仪表盘 / 客户欠款列表 / 客户对账明细 / │ │ 订单与回款台账 / ERP 同步管理 │ └────────────────────┬──────────────────────────┘ │ REST /api（axios，统一鉴权头） ┌────────────────────▼──────────────────────────┐ │ Spring Boot 后端 │ │ AuthController(/api/auth) │ │ CustomerController / OrderController / │ │ PaymentController / ReconciliationController │ │ DashboardController / SyncController │ │ 服务层：ReconciliationService(核心对账试算) │ │ SyncService(拉取同步) │ │ 数据层：JPA Repository（含余额聚合查询） │ │ ERP 对接层：ErpGateway(SPI) │ │ ├─ MockErpGateway（默认，内置样例数据） │ │ └─ HttpErpGateway（占位，接真实 API 时实现） │ └────────────────────┬──────────────────────────┘ │ ┌────────────▼────────────┐ │ H2(file) / MySQL │ 本地镜像：customer/orders/payments/sync_log └─────────────────────────┘ ``` **设计要点：** 1. **本地镜像 + 同步拉取**：客户/订单/回款主数据由 ERP 同步到本地库，业务查询与对账全部走本地，不再逐个客户跨系统翻查。 2. **欠款口径**：`客户欠款余额 = Σ订单应收金额(未结清部分) − Σ已核销回款金额`。明细可下钻到"订单 + 回款"两级。 3. **ERP 解耦**：所有外部查询收敛到 `ErpGateway` 接口；接真实 ERP 时仅需新增实现并配置开关，不动业务层。 --- ## 核心功能 | 功能 | 说明 | |------|------| | **客户欠款概览** | 仪表盘展示：客户总数、应收总额、已回款、未回款余额、逾期金额、逾期客户数；12 个月回款趋势图；逾期欠款 Top 客户列表 | | **客户欠款列表** | 关键字搜索 + 分页表格（客户名称/编码/联系人/区域/信用额度/应收/已回款/欠款余额/逾期金额）；列头排序；行操作"对账明细"跳转到明细页 | | **客户对账单** | 单客户维度，汇总卡片 + 未回款订单表（逾期行红色标记）+ 回款记录表，替代人工翻查的核对流程 | | **订单台账** | 客户下拉、订单号模糊、状态下拉、日期区间筛选；分页表格含状态 Tag；当页金额小计 | | **回款台账** | 客户下拉、回款单号模糊、回款方式下拉、日期区间筛选；分页表格 | | **ERP 同步管理** | 手动触发数据同步（客户/订单/回款/全量），展示同步结果明细与最近同步日志 | --- ## 系统截图 ### 回款概览仪表盘 展示核心指标卡片（客户总数、应收/已回款/欠款/逾期、逾期客户数）+ 12 个月回款趋势折线图 + 逾期欠款 Top10 列表。 ![回款概览](screenshots/01_dashboard.png) ### 客户欠款列表 关键字搜索 + 分页表格，包含应收、已回款、欠款余额、逾期金额等关键列，列头支持排序，行操作提供"对账明细"与"详情"。 ![客户欠款列表](screenshots/02_customers.png) ### 客户对账单 单客户维度，汇总卡片 + 未回款订单表（逾期订单红色标记）+ 回款记录表，替代人工翻查核对。 ![客户对账单](screenshots/06_statement.png) ### 订单台账 支持客户下拉、订单号模糊、状态下拉、日期区间筛选，分页表格含金额小计。 ![订单台账](screenshots/03_orders.png) ### 回款台账 支持客户下拉、回款单号模糊、回款方式下拉、日期区间筛选，分页表格。 ![回款台账](screenshots/04_payments.png) ### ERP 数据同步 手动触发同步按钮（客户/订单/回款/全量），展示同步结果明细与最近同步日志。 ![数据同步](screenshots/05_sync.png) --- ## 快速开始 ### 启动后端 ```bash cd backend mvn spring-boot:run # 默认端口 8080，H2 file 模式零依赖可跑 # 内置 40 客户/260 订单/503 回款样例数据，启动自动初始化 ``` 切换 MySQL： ```bash # 1. 建库 mysql -uroot -p -e "CREATE DATABASE IF NOT EXISTS receivable DEFAULT CHARACTER SET utf8mb4;" mysql -uroot -p receivable < src/main/resources/schema.sql # 2. 修改 application-mysql.yml 账号密码 mvn spring-boot:run -Dspring-boot.run.profiles=mysql ``` ### 启动前端 ```bash cd frontend pnpm install pnpm dev # 默认端口 3006，开发模式已配置 VITE_API_PROXY_URL = http://localhost:8080 # 生产构建：pnpm build ``` **注意**：开发模式下，Vite 代理会将 `/api/**` 请求转发到后端 `http://localhost:8080`，前后端无需跨域配置。 --- ## API 接口清单 统一响应包装：`{ "code": 0, "message": "ok", "data": { } }`。除 `/api/auth/login` 外，所有接口均需在请求头携带 `Authorization: Bearer `。 | 方法 | 路径 | 说明 | |------|------|------| | POST | /api/auth/login | 登录 | | GET | /api/auth/me | 当前用户信息 | | GET | /api/dashboard/summary | 仪表盘汇总数据 | | GET | /api/customers | 客户欠款列表（分页 + 关键字） | | GET | /api/customers/{id} | 客户详情 + 欠款汇总 | | GET | /api/customers/{id}/statement | 单客户对账明细 | | GET | /api/orders | 订单台账（分页 + 筛选） | | GET | /api/payments | 回款台账（分页 + 筛选） | | POST | /api/sync/run | 触发数据同步 | | GET | /api/sync/logs | 最近同步日志列表 | --- ## 数据模型 | 表名 | 说明 | |------|------| | `customer` | 客户主数据（本地镜像，erp_customer_id 唯一索引） | | `orders` | 应收订单（erp_order_id 唯一索引，status 枚举：DRAFT/OPEN/PARTIAL/PAID/OVERDUE/CANCELLED） | | `payments` | 客户回款流水（erp_payment_id 唯一索引） | | `sync_run_log` | 同步任务日志（类型/触发人/状态/处理总数） | | `sys_user` | 登录用户（admin/admin123） | 核心对账在 `customer_id` 维度聚合，百万级以下本地聚合秒级返回。 --- ## ERP 对接说明 所有外部 ERP 数据拉取收敛到 `ErpGateway` 接口： ```java public interface ErpGateway { String name(); List pullCustomers(); List pullOrders(); List pullPayments(); } ``` 当前默认使用 `MockErpGateway`（内置 40 客户/260 订单/503 回款样例数据，幂等 upsert）。 接入真实 ERP 时： 1. 新建 `HttpErpGateway` 实现，通过 HTTP 调 ERP 接口 2. 在 `application.yml` 配置 `erp.gateway=http` 3. 业务层无需改动，数据同步自动走新实现 --- ## 账号信息 | 账号 | 密码 | 角色 | |------|------|------| | admin | admin123 | ADMIN | ## 商务合作或定制 QQ： 467643531