yunhaifinance/README.md

云海财务系统

研发运营：新觅
版本：1.0.0 | 更新：2026-06-23

面向工程建设与跨国分公司的企业财务与项目管理平台，实现项目成本、采购供应链与资金流转的一体化管理，支持预支、报销、付款、核销等完整财务审批链路。

层级	技术选型
后端	Node.js 18 + Express
前端	React 18 + TypeScript + Ant Design 5 + Vite
数据库	PostgreSQL 15
部署	Docker Compose（本地构建镜像）

---

目录

• 快速开始
• 操作手册
  • 1. 系统概述
  • 2. 环境要求
  • 3. 安装与启动
  • 4. 登录与账号
  • 5. 界面与模块导航
  • 6. 业务模块操作指南
  • 7. 典型业务流程
  • 8. 系统管理
  • 9. 日常运维
  • 10. 常见问题与排查
  • 11. 附录

---

快速开始

# 方式一：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. 登录与账号

1. 浏览器访问 http://localhost:10050
2. 输入用户名与密码，或点击登录页「测试账户」快捷登录
3. 登录成功后跳转至工作台（/dashboard）
4. 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