admin/yunhaifinance
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update 2026-06-24 10:47:45

Browse Source
This commit is contained in:
yi
2026-06-24 10:47:45 +08:00
parent ffc7eef984
commit 94625d4f3f
29 changed files with 1417 additions and 158 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+530 -62
View File
@@ -1,87 +1,555 @@
# 云海财务系统
## 1. 项目简介
**研发运营**：新觅
**版本**：1.0.0 | **更新**：2026-06-23
- **项目概述**：云海财务系统是一款高效、智能、专业的企业财务与项目管理平台，能够全方位提升企业的项目监控与资金流转效率。
- **项目定位**：主要面向中大型企业、工程建设及跨国分公司，提供财务报销、项目预算与进度管理服务。
- **核心价值**：实现项目与财务数据的无缝对接，简化审批流，实时监控预算使用情况，确保企业资金健康与合规。
面向工程建设与跨国分公司的企业财务与项目管理平台，实现项目成本、采购供应链与资金流转的一体化管理，支持预支、报销、付款、核销等完整财务审批链路。
## 2. 整体架构与技术栈
| 层级 | 技术选型 |
|------|----------|
| 后端 | Node.js 18 + Express |
| 前端 | React 18 + TypeScript + Ant Design 5 + Vite |
| 数据库 | PostgreSQL 15 |
| 部署 | Docker Compose（本地构建镜像） |
本系统采用前后端分离的现代化架构，通过 Docker 容器化部署以确保高可用性。
---
### 技术栈展示：
- **后端技术**：Node.js + Express
- **前端技术**：React 18 + TypeScript + Ant Design 5 + Vite
- **数据库**：PostgreSQL 15
- **部署技术**：Docker / Docker Compose
## 目录
### 系统架构图
*(暂无架构图，系统分为前端应用容器、后端 API 容器及独立的 PostgreSQL 数据库容器)*
- [快速开始](#快速开始)
- [操作手册](#操作手册)
- [1. 系统概述](#1-系统概述)
- [2. 环境要求](#2-环境要求)
- [3. 安装与启动](#3-安装与启动)
- [4. 登录与账号](#4-登录与账号)
- [5. 界面与模块导航](#5-界面与模块导航)
- [6. 业务模块操作指南](#6-业务模块操作指南)
- [7. 典型业务流程](#7-典型业务流程)
- [8. 系统管理](#8-系统管理)
- [9. 日常运维](#9-日常运维)
- [10. 常见问题与排查](#10-常见问题与排查)
- [11. 附录](#11-附录)
## 3. 项目目录概览
---
```text
├── backend/ # 后端服务源码
│ ├── routes/ # API路由
│ ├── services/ # 业务逻辑
│ ├── migrations/ # 数据库迁移脚本
│ └── app.js # 后端主程序
├── frontend/ # 前端服务源码
│ ├── src/ # React源码及组件
│ └── vite.config.ts # Vite配置
├── scripts/ # 初始化脚本 (如 init_sample_data.sql)
└── docker-compose.full.yml # Docker本地部署配置
## 快速开始
```bash
# 方式一：Docker 一键部署（推荐）
docker compose -f docker-compose.full.yml up -d --build
# 检查服务状态
docker compose -f docker-compose.full.yml ps
# 健康检查
curl http://localhost:10051/api/health
```
## 4. 核心业务功能
| 服务 | 地址 | 说明 |
|------|------|------|
| 前端 Web | http://localhost:10050 | Nginx 托管 SPA，API 反向代理至后端 |
| 后端 API | http://localhost:10051 | REST API，健康检查 `/api/health` |
| PostgreSQL | localhost:10052 | 容器内端口 5432，仅调试时直连 |
- **项目管理**：支持项目的创建、进度跟踪、合同与里程碑管理。
- **财务管理**：包括财务报销、预支款申请、付款申请与核销流程。
- **采购与供应链**：商品管理、采购申请、订单管理与入库记录。
- **伙伴管理**：集中管理供应商、分包商与客户信息。
- **数据分析与仪表盘**：直观展示核心财务数据及项目状态。
| 角色 | 用户名 | 默认密码 |
|------|--------|----------|
| 系统管理员 | `admin` | `X123c321@` |
| 财务专员 | `finance` | `X123c321@` |
| 项目经理 | `manager` | `X123c321@` |
| 普通员工 | `employee` | `X123c321@` |
## 5. 实际应用场景示例
> 以上账号由 `scripts/init_sample_data.sql` 初始化。生产环境请立即修改默认密码与 `JWT_SECRET`。
- **跨国分公司财务管控**：海外分公司提交预支与报销申请，总部可在线审核，统一汇率转换及预算扣减。
- **工程类项目核算**：将施工日志与项目付款节点绑定，确保按进度结算分包商款项。
- **企业日常运营**：员工出差报销、办公采购，全流程数字化审批与记录。
**项目结构**
## 6. 帮助解决的核心问题
```text
company-finance-system/
├── backend/ # Express API 服务
│ ├── routes/ # 业务路由
│ ├── migrations/ # 数据库迁移脚本
│ └── app.js # 入口
├── frontend/ # React 前端
│ └── src/pages/ # 业务页面
├── scripts/
│ ├── init_schema.sql # 完整表结构（Docker 首次初始化）
│ └── init_sample_data.sql # 示例业务数据
└── docker-compose.full.yml # 全栈部署配置
```
- **财务数据孤岛**：项目信息与财务开销割裂，难以追踪真实成本。
- **审批效率低下**：传统纸质或邮件审批慢、易遗漏。
- **预算超支风险**：缺乏实时的数据监控及超支预警机制。
**新觅源码库**：https://www.xinmi.cloud/
## 7. 快速开始
---
### 环境要求
- Docker 及 Docker Compose
- Node.js (如需本地独立运行)
## 操作手册
### 安装与运行步骤 (基于 Docker)
### 1. 系统概述
本系统内置了 `docker-compose.full.yml` 文件及示例数据初始化脚本，可一键启动全套服务。
#### 1.1 产品简介
1. **一键构建与启动**：
```bash
docker-compose -f docker-compose.full.yml up -d --build
```
2. **检查服务状态**：
```bash
docker-compose -f docker-compose.full.yml ps
```
云海财务系统是一款高效、智能、专业的企业财务与项目管理平台，主要面向中大型企业、工程建设及跨国分公司，提供：
### 访问地址与默认账号
- **前端访问地址**：`http://localhost:10050`
- **后端 API 地址**：`http://localhost:10051`
- **默认管理员账号**：`admin` / `X123c321@` (具体密码请参考登录页提示)
- 项目全生命周期管理与成本核算
- 预支、报销、付款、核销等财务单据流转
- 采购申请、订单、库存与付款计划管理
- 供应商、分包商、客户及物流公司集中维护
- 多语言界面（简体中文、English、ไทย、ລາວ）
### 常见问题
- **数据库未初始化**：如果首次启动未完成数据装载，可执行 `docker-compose down -v` 删除未初始化的数据卷后重新启动。
- **端口冲突**：如果 `10050` 或 `10051` 端口已被占用，请修改 `docker-compose.full.yml` 中的端口映射。
#### 1.2 核心能力
## 8. 运行示例截图
| 模块分组 | 主要功能 |
|----------|----------|
| 项目管理 | 项目建档、合同金额、进度状态、付款节点 |
| 预算报价 | 预算项目创建、报价明细 |
| 施工管理 | 施工总览、施工日志、里程碑跟踪 |
| 审批管理 | 待审批单据、待执行付款 |
| 财务申请 | 预支、报销、付款、核销申请 |
| 财务管理 | 财务概览、汇率、项目成本、预支核销状态 |
| 采购管理 | 商品、采购申请/订单、付款计划、库存 |
| 合作伙伴 | 供应商、分包商、客户、物流公司 |
| 后台管理 | 用户/角色、流程模板、分类、导入、日志、备份 |
*(截图预留位置)*
#### 1.3 技术架构
```text
┌─────────────┐ /api/* ┌─────────────┐ SQL ┌──────────────┐
│ 浏览器 │ ──────────────► │ Nginx:80 │ ───────────► │ Express:3000 │
│ :10050 │ │ (frontend) │ proxy │ (backend) │
└─────────────┘ └─────────────┘ └──────┬───────┘
│
▼
┌──────────────┐
│ PostgreSQL │
│ :5432→10052 │
└──────────────┘
```
![系统架构示意](docs/images/image-20260623-architecture.png)
---
### 2. 环境要求
| 项 | 要求 |
|----|------|
| Docker | 20.10+ |
| Docker Compose | v2+ |
| 磁盘 | 建议 ≥ 2 GB（含数据库与上传文件卷） |
| 浏览器 | Chrome / Edge / Firefox 最新两个主版本 |
本地开发（可选）：
| 项 | 要求 |
|----|------|
| Node.js | 18+ |
| npm | 9+ |
| PostgreSQL | 15（或使用 `docker-compose.yml` 仅启动数据库） |
---
### 3. 安装与启动
#### 3.1 Docker 全栈部署（推荐）
`docker-compose.full.yml` 包含三个服务：`postgres`、`backend`、`frontend`。
```bash
# 构建并后台启动
docker compose -f docker-compose.full.yml up -d --build
# 查看日志
docker compose -f docker-compose.full.yml logs -f backend
# 停止服务
docker compose -f docker-compose.full.yml down
# 重置数据库（会删除数据卷，重新执行 init_sample_data.sql）
docker compose -f docker-compose.full.yml down -v
docker compose -f docker-compose.full.yml up -d --build
```
首次启动时，PostgreSQL 容器会自动挂载 `scripts/init_sample_data.sql` 完成表结构与示例数据初始化。
#### 3.2 环境变量（Docker）
可在项目根目录创建 `.env` 文件，或在启动前导出变量：
| 变量 | 默认值 | 说明 |
|------|--------|------|
| `DB_USER` | `postgres` | 数据库用户名 |
| `DB_PASSWORD` | `changeme` | 数据库密码 |
| `DB_NAME` | `company_finance` | 数据库名 |
| `JWT_SECRET` | `please-change-this-secret` | JWT 签名密钥，**生产必改** |
| `CORS_ORIGIN` | （空） | 逗号分隔的允许来源；为空时允许所有来源 |
#### 3.3 本地开发
```bash
# 方式一：仅启动数据库
docker compose -f docker-compose.yml up -d
# 后端
cd backend
npm install
# 配置环境变量（参考下表）
npm run dev
# 前端（新终端）
cd frontend
npm install
npm run dev
```
后端本地环境变量（`backend/.env`）：
| 变量 | 示例值 | 说明 |
|------|--------|------|
| `DB_HOST` | `localhost` | 数据库主机 |
| `DB_PORT` | `5432` | 数据库端口（Docker 映射为 `10052`） |
| `DB_NAME` | `company_finance` | 数据库名 |
| `DB_USER` | `postgres` | 数据库用户 |
| `DB_PASSWORD` | `changeme` | 数据库密码 |
| `PORT` | `3000` | API 监听端口 |
| `JWT_SECRET` | 随机长字符串 | JWT 密钥 |
| `NODE_ENV` | `development` | 运行环境 |
> 注意：`backend/.env.example` 中仍保留 SQLite 示例，当前版本实际使用 PostgreSQL，请以 `db.js` 与 `docker-compose.full.yml` 为准。
---
### 4. 登录与账号
1. 浏览器访问 http://localhost:10050
2. 输入用户名与密码，或点击登录页「测试账户」快捷登录
3. 登录成功后跳转至工作台（`/dashboard`）
4. JWT 令牌有效期为 **24 小时**，过期后需重新登录
| 角色 | 用户名 | 权限概述 |
|------|--------|----------|
| 系统管理员 | `admin` | 全部业务功能 + 后台管理（用户、角色、流程、备份等） |
| 财务专员 | `finance` | 财务审批、付款执行、汇率与报表 |
| 项目经理 | `manager` | 项目、施工、预算及关联业务 |
| 普通员工 | `employee` | 发起预支/报销/采购等申请，查看授权范围数据 |
![image-20260624104319931](images/image-20260624104319931.png)
---
### 5. 界面与模块导航
登录后左侧为主业务菜单，右上角可切换语言与个人中心；管理员可通过用户菜单进入「后台管理」（`/admin`）。
| 菜单 | 路由 | 说明 |
|------|------|------|
| 工作台 | `/dashboard` | 核心指标与待办概览 |
| 项目管理 | `/projects` | 项目列表与详情 |
| 预算报价 | `/budget-projects` | 预算项目维护 |
| 施工管理 | `/construction` | 施工总览、日志、里程碑 |
| 待审批 | `/approval` | 待审批单据处理 |
| 待执行 | `/execution` | 待执行付款操作 |
| 预支申请 | `/advances` | 预支款申请 |
| 报销申请 | `/reimbursements` | 费用报销 |
| 付款申请 | `/payment-requests` | 对外付款申请 |
| 核销申请 | `/verification` | 预支/付款核销 |
| 财务概览 | `/finance` | 财务数据总览 |
| 汇率管理 | `/exchange-rates` | 多币种汇率维护 |
| 项目成本 | `/project-cost` | 按项目归集成本 |
| 预支核销状态 | `/advances/verification-status` | 预支款核销进度 |
| 报表分析 | `/reports` | 财务报表与分析 |
| 商品管理 | `/products` | 物料/商品主数据 |
| 采购申请 | `/purchase-requests` | 采购需求发起 |
| 采购订单 | `/purchase-orders` | 采购订单管理 |
| 付款计划 | `/payment-plans` | 采购付款计划 |
| 库存管理 | `/inventory` | 入库与库存台账 |
| 供应商管理 | `/suppliers` | 供应商档案 |
| 分包商管理 | `/subcontractors` | 分包商档案 |
| 客户管理 | `/customers` | 客户档案 |
| 物流管理 | `/logistics-companies` | 物流公司维护 |
![image-20260624104306842](images/image-20260624104306842.png)
---
### 6. 业务模块操作指南
#### 6.1 项目管理
**路径**：`/projects`
**功能概述**：维护工程项目基本信息、合同金额、负责人及状态，关联客户与后续财务、施工数据。
| 元素 | 说明 |
|------|------|
| 项目编码 | 唯一标识，如 `P2026-001` |
| 合同金额 | 项目总收入基准 |
| 状态 | 规划中 / 进行中 / 已完成等 |
| 付款节点 | 与 `/api/payment-nodes` 联动，按进度结算 |
![image-20260624104333660](images/image-20260624104333660.png)
#### 6.2 预算报价
**路径**：`/budget-projects`
**功能概述**：创建预算项目、维护报价明细，为后续采购与成本对比提供基准。
| 元素 | 说明 |
|------|------|
| 预算项目 | 独立于执行项目的报价载体 |
| 报价明细 | 支持分项录入与汇总 |
![image-20260624104344479](images/image-20260624104344479.png)
#### 6.3 施工管理
**路径**：`/construction`、`/construction/:id/logs`、`/construction/:id/milestones`
**功能概述**：跟踪工程施工进度，记录施工日志与里程碑，支撑按进度付款。
| 元素 | 说明 |
|------|------|
| 施工总览 | 各项目施工状态一览 |
| 施工日志 | 按日记录现场情况 |
| 里程碑 | 关键节点完成确认 |
#### ![image-20260624104509907](images/image-20260624104509907.png)
#### ![image-20260624104525295](images/image-20260624104525295.png)6.4 财务申请（预支 / 报销 / 付款 / 核销)
**路径**：`/advances`、`/reimbursements`、`/payment-requests`、`/verification`
**功能概述**：员工发起各类财务单据，经审批后进入执行环节；预支款需后续报销或核销冲抵。
| 单据类型 | 典型场景 |
|----------|----------|
| 预支申请 | 出差、现场备用金 |
| 报销申请 | 费用实报实销 |
| 付款申请 | 对供应商/分包商付款 |
| 核销申请 | 预支款与发票/实付对齐 |
![image-20260624104539379](images/image-20260624104539379.png)
![image-20260624104548854](images/image-20260624104548854.png)
![image-20260624104557054](images/image-20260624104557054.png)
#### 6.5 审批与执行
**路径**：`/approval`、`/execution`
**功能概述**：审批人处理待办单据；财务人员在「待执行」中完成实际付款操作。
| 环节 | 说明 |
|------|------|
| 待审批 | 按角色权限审批通过或驳回 |
| 待执行 | 审批通过后登记付款执行记录 |
![image-20260624104635658](images/image-20260624104635658.png)
#### 6.6 采购与库存
**路径**：`/products`、`/purchase-requests`、`/purchase-orders`、`/payment-plans`、`/inventory`
**功能概述**：从商品主数据到采购申请、订单、付款计划及入库的全链路管理。
| 环节 | 说明 |
|------|------|
| 采购申请 | 业务部门提出采购需求 |
| 采购订单 | 审批后生成正式订单 |
| 付款计划 | 按合同约定拆分付款期次 |
| 库存管理 | 收货入库与库存查询 |
![image-20260624104653703](images/image-20260624104653703.png)
#### 6.7 合作伙伴
**路径**：`/suppliers`、`/subcontractors`、`/customers`、`/logistics-companies`
**功能概述**：集中维护供应商、分包商、客户及物流公司联系人与业务信息。
![image-20260624104704292](images/image-20260624104704292.png)
#### 6.8 财务管理与报表
**路径**：`/finance`、`/exchange-rates`、`/project-cost`、`/reports`
**功能概述**：汇总财务收支、维护多币种汇率、按项目分析成本利润，输出报表。
| 功能 | 说明 |
|------|------|
| 汇率管理 | 支持跨国分公司币种换算 |
| 项目成本 | 将采购、人工、分包等费用归集到项目 |
| 报表分析 | 项目成本利润等分析视图 |
![image-20260624104623194](images/image-20260624104623194.png)
---
### 7. 典型业务流程
#### 7.1 员工出差预支与报销
```text
员工提交预支申请 → 项目经理/财务审批 → 财务执行付款
↓
出差结束提交报销 → 审批通过 → 与预支款核销冲抵
```
#### 7.2 工程采购全流程
```text
维护商品主数据 → 提交采购申请 → 审批 → 生成采购订单
↓
制定付款计划 → 收货入库（库存） → 按期付款申请 → 执行付款
```
#### 7.3 工程项目按进度付款
```text
创建项目与客户合同 → 设置付款节点/里程碑 → 施工日志确认进度
↓
分包商付款申请 → 审批 → 付款执行 → 项目成本归集
```
#### 7.4 跨国分公司财务管控
```text
维护汇率 → 海外分公司以本地币种申请 → 总部统一审批
↓
折算为本位币记账 → 项目成本与报表按统一口径输出
```
---
### 8. 系统管理
管理员登录后，点击右上角用户菜单 → **后台管理**，进入 `/admin` 区域。
| 菜单 | 路由 | 功能 |
|------|------|------|
| 用户管理 | `/admin/users` | 增删改用户、重置信息 |
| 角色权限 | `/admin/roles` | 角色与权限配置 |
| 流程管理 | `/admin/process` | 审批流程定义 |
| 工程模板管理 | `/admin/process-templates` | 施工/业务流程模板 |
| 财务分类管理 | `/admin/expense-categories` | 费用科目分类 |
| Excel 批量导入 | `/admin/excel-import` | 批量导入主数据 |
| 系统日志 | `/admin/logs` | 操作与系统日志查询 |
| 数据备份 | `/admin/backup` | 备份记录与恢复入口 |
| 关于系统 | `/admin/about` | 版本与技术信息 |
---
### 9. 日常运维
#### 9.1 健康检查
```bash
curl http://localhost:10051/api/health
```
正常返回 JSON，包含 `success: true` 及 API 端点列表。
#### 9.2 查看日志
```bash
# 后端日志
docker compose -f docker-compose.full.yml logs -f backend
# 前端 Nginx 日志
docker compose -f docker-compose.full.yml logs -f frontend
# 数据库日志
docker compose -f docker-compose.full.yml logs -f postgres
```
#### 9.3 重启服务
```bash
docker compose -f docker-compose.full.yml restart backend frontend
```
#### 9.4 数据备份
- 数据库数据持久化在 Docker 卷 `yunhaifinance-postgres-data`
- 上传文件持久化在 `yunhaifinance-upload-data`（挂载至后端 `/app/uploads`）
- 可通过 `pg_dump` 手动备份：
```bash
docker exec yunhaifinance-postgres pg_dump -U postgres company_finance > backup.sql
```
#### 9.5 更新部署
```bash
git pull
docker compose -f docker-compose.full.yml up -d --build
```
---
### 10. 常见问题与排查
| 现象 | 可能原因 | 处理办法 |
|------|----------|----------|
| 前端能开但接口 502 | 后端未就绪或崩溃 | `docker compose logs backend` 查错；确认数据库可连 |
| 登录提示用户名或密码错误 | 初始化脚本未执行 | `docker compose down -v` 后重新 `up --build` |
| 端口被占用 | 10050/10051/10052 冲突 | 修改 `docker-compose.full.yml` 左侧端口映射 |
| 登录后很快掉线 | JWT 过期（24h） | 重新登录；生产可调整后端 `expiresIn` |
| 上传失败 | 请求体超限 | 后端限制 50MB；Nginx 代理限制 10MB |
| 跨域问题 | `CORS_ORIGIN` 配置 | 生产环境在 `.env` 中设置允许的域名 |
| 数据库连接失败 | 密码或主机名错误 | 核对 `DB_*` 环境变量与 postgres 容器状态 |
---
### 11. 附录
#### 11.1 环境变量速查
| 变量 | 服务 | 默认值 | 说明 |
|------|------|--------|------|
| `DB_HOST` | backend | `postgres`（Docker） | 数据库主机 |
| `DB_PORT` | backend | `5432` | 数据库端口 |
| `DB_NAME` | backend / postgres | `company_finance` | 数据库名 |
| `DB_USER` | backend / postgres | `postgres` | 数据库用户 |
| `DB_PASSWORD` | backend / postgres | `changeme` | 数据库密码 |
| `JWT_SECRET` | backend | `please-change-this-secret` | JWT 密钥 |
| `CORS_ORIGIN` | backend | （空） | CORS 白名单 |
| `PORT` | backend | `3000` | API 端口 |
| `NODE_ENV` | backend | `production`（Docker） | 运行环境 |
#### 11.2 主要 API 前缀
| 前缀 | 说明 |
|------|------|
| `/api/auth` | 登录、令牌校验 |
| `/api/projects` | 项目管理 |
| `/api/advances` | 预支款 |
| `/api/reimbursements` | 报销 |
| `/api/payment-requests` | 付款申请 |
| `/api/verifications` | 核销 |
| `/api/purchase-requests` | 采购申请 |
| `/api/purchase-orders` | 采购订单 |
| `/api/inventory` | 库存 |
| `/api/finance-stats` | 财务统计 |
| `/api/health` | 健康检查 |
#### 11.3 默认账号
| 用户名 | 姓名 | 角色 | 邮箱 |
|--------|------|------|------|
| `admin` | 系统管理员 | admin | admin@xinmi.cloud |
| `finance` | 财务专员 | finance | finance@xinmi.cloud |
| `manager` | 项目经理 | manager | manager@xinmi.cloud |
| `employee` | 普通员工 | employee | employee@xinmi.cloud |
默认密码均为 `X123c321@`（与登录页测试账户一致）。
#### 11.4 相关链接
| 名称 | 地址 |
|------|------|
| 新觅源码库 | https://www.xinmi.cloud/ |
---
**新觅**
文档版本：1.0.0 | 2026-06-23