云海财务系统
研发运营：新觅
版本：1.0.0 | 更新：2026-06-23
面向工程建设与跨国分公司的企业财务与项目管理平台，实现项目成本、采购供应链与资金流转的一体化管理，支持预支、报销、付款、核销等完整财务审批链路。
| 层级 | 技术选型 |
|---|---|
| 后端 | Node.js 18 + Express |
| 前端 | React 18 + TypeScript + Ant Design 5 + Vite |
| 数据库 | PostgreSQL 15 |
| 部署 | Docker Compose（本地构建镜像） |
目录
快速开始
# 方式一：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
| 服务 | 地址 | 说明 |
|---|---|---|
| 前端 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@ |
以上账号由
scripts/init_sample_data.sql初始化。生产环境请立即修改默认密码与JWT_SECRET。
项目结构
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/
操作手册
1. 系统概述
1.1 产品简介
云海财务系统是一款高效、智能、专业的企业财务与项目管理平台，主要面向中大型企业、工程建设及跨国分公司，提供：
- 项目全生命周期管理与成本核算
- 预支、报销、付款、核销等财务单据流转
- 采购申请、订单、库存与付款计划管理
- 供应商、分包商、客户及物流公司集中维护
- 多语言界面（简体中文、English、ไทย、ລາວ）
1.2 核心能力
| 模块分组 | 主要功能 |
|---|---|
| 项目管理 | 项目建档、合同金额、进度状态、付款节点 |
| 预算报价 | 预算项目创建、报价明细 |
| 施工管理 | 施工总览、施工日志、里程碑跟踪 |
| 审批管理 | 待审批单据、待执行付款 |
| 财务申请 | 预支、报销、付款、核销申请 |
| 财务管理 | 财务概览、汇率、项目成本、预支核销状态 |
| 采购管理 | 商品、采购申请/订单、付款计划、库存 |
| 合作伙伴 | 供应商、分包商、客户、物流公司 |
| 后台管理 | 用户/角色、流程模板、分类、导入、日志、备份 |
1.3 技术架构
┌─────────────┐ /api/* ┌─────────────┐ SQL ┌──────────────┐
│ 浏览器 │ ──────────────► │ Nginx:80 │ ───────────► │ Express:3000 │
│ :10050 │ │ (frontend) │ proxy │ (backend) │
└─────────────┘ └─────────────┘ └──────┬───────┘
│
▼
┌──────────────┐
│ PostgreSQL │
│ :5432→10052 │
└──────────────┘
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。
# 构建并后台启动
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 本地开发
# 方式一：仅启动数据库
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. 登录与账号
- 浏览器访问 http://localhost:10050
- 输入用户名与密码，或点击登录页「测试账户」快捷登录
- 登录成功后跳转至工作台（
/dashboard） - JWT 令牌有效期为 24 小时，过期后需重新登录
| 角色 | 用户名 | 权限概述 |
|---|---|---|
| 系统管理员 | admin |
全部业务功能 + 后台管理（用户、角色、流程、备份等） |
| 财务专员 | finance |
财务审批、付款执行、汇率与报表 |
| 项目经理 | manager |
项目、施工、预算及关联业务 |
| 普通员工 | employee |
发起预支/报销/采购等申请，查看授权范围数据 |
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 |
物流公司维护 |
6. 业务模块操作指南
6.1 项目管理
路径：/projects
功能概述：维护工程项目基本信息、合同金额、负责人及状态，关联客户与后续财务、施工数据。
| 元素 | 说明 |
|---|---|
| 项目编码 | 唯一标识，如 P2026-001 |
| 合同金额 | 项目总收入基准 |
| 状态 | 规划中 / 进行中 / 已完成等 |
| 付款节点 | 与 /api/payment-nodes 联动，按进度结算 |
6.2 预算报价
路径：/budget-projects
功能概述：创建预算项目、维护报价明细，为后续采购与成本对比提供基准。
| 元素 | 说明 |
|---|---|
| 预算项目 | 独立于执行项目的报价载体 |
| 报价明细 | 支持分项录入与汇总 |
6.3 施工管理
路径：/construction、/construction/:id/logs、/construction/:id/milestones
功能概述：跟踪工程施工进度，记录施工日志与里程碑，支撑按进度付款。
| 元素 | 说明 |
|---|---|
| 施工总览 | 各项目施工状态一览 |
| 施工日志 | 按日记录现场情况 |
| 里程碑 | 关键节点完成确认 |
6.4 财务申请（预支 / 报销 / 付款 / 核销)
路径：/advances、/reimbursements、/payment-requests、/verification
功能概述：员工发起各类财务单据，经审批后进入执行环节；预支款需后续报销或核销冲抵。
| 单据类型 | 典型场景 |
|---|---|
| 预支申请 | 出差、现场备用金 |
| 报销申请 | 费用实报实销 |
| 付款申请 | 对供应商/分包商付款 |
| 核销申请 | 预支款与发票/实付对齐 |
6.5 审批与执行
路径：/approval、/execution
功能概述：审批人处理待办单据；财务人员在「待执行」中完成实际付款操作。
| 环节 | 说明 |
|---|---|
| 待审批 | 按角色权限审批通过或驳回 |
| 待执行 | 审批通过后登记付款执行记录 |
6.6 采购与库存
路径：/products、/purchase-requests、/purchase-orders、/payment-plans、/inventory
功能概述：从商品主数据到采购申请、订单、付款计划及入库的全链路管理。
| 环节 | 说明 |
|---|---|
| 采购申请 | 业务部门提出采购需求 |
| 采购订单 | 审批后生成正式订单 |
| 付款计划 | 按合同约定拆分付款期次 |
| 库存管理 | 收货入库与库存查询 |
6.7 合作伙伴
路径：/suppliers、/subcontractors、/customers、/logistics-companies
功能概述：集中维护供应商、分包商、客户及物流公司联系人与业务信息。
6.8 财务管理与报表
路径：/finance、/exchange-rates、/project-cost、/reports
功能概述：汇总财务收支、维护多币种汇率、按项目分析成本利润，输出报表。
| 功能 | 说明 |
|---|---|
| 汇率管理 | 支持跨国分公司币种换算 |
| 项目成本 | 将采购、人工、分包等费用归集到项目 |
| 报表分析 | 项目成本利润等分析视图 |
7. 典型业务流程
7.1 员工出差预支与报销
员工提交预支申请 → 项目经理/财务审批 → 财务执行付款
↓
出差结束提交报销 → 审批通过 → 与预支款核销冲抵
7.2 工程采购全流程
维护商品主数据 → 提交采购申请 → 审批 → 生成采购订单
↓
制定付款计划 → 收货入库（库存） → 按期付款申请 → 执行付款
7.3 工程项目按进度付款
创建项目与客户合同 → 设置付款节点/里程碑 → 施工日志确认进度
↓
分包商付款申请 → 审批 → 付款执行 → 项目成本归集
7.4 跨国分公司财务管控
维护汇率 → 海外分公司以本地币种申请 → 总部统一审批
↓
折算为本位币记账 → 项目成本与报表按统一口径输出
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 健康检查
curl http://localhost:10051/api/health
正常返回 JSON，包含 success: true 及 API 端点列表。
9.2 查看日志
# 后端日志
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 重启服务
docker compose -f docker-compose.full.yml restart backend frontend
9.4 数据备份
- 数据库数据持久化在 Docker 卷
yunhaifinance-postgres-data - 上传文件持久化在
yunhaifinance-upload-data（挂载至后端/app/uploads） - 可通过
pg_dump手动备份：
docker exec yunhaifinance-postgres pg_dump -U postgres company_finance > backup.sql
9.5 更新部署
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