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. 系统概述](#1-系统概述)
  - [2. 环境要求](#2-环境要求)
  - [3. 安装与启动](#3-安装与启动)
  - [4. 登录与账号](#4-登录与账号)
  - [5. 界面与模块导航](#5-界面与模块导航)
  - [6. 业务模块操作指南](#6-业务模块操作指南)
  - [7. 典型业务流程](#7-典型业务流程)
  - [8. 系统管理](#8-系统管理)
  - [9. 日常运维](#9-日常运维)
  - [10. 常见问题与排查](#10-常见问题与排查)
  - [11. 附录](#11-附录)

---

## 快速开始

```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
```

| 服务 | 地址 | 说明 |
|------|------|------|
| 前端 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`。

**项目结构**

```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/

---

## 操作手册

### 1. 系统概述

#### 1.1 产品简介

云海财务系统是一款高效、智能、专业的企业财务与项目管理平台，主要面向中大型企业、工程建设及跨国分公司，提供：

- 项目全生命周期管理与成本核算
- 预支、报销、付款、核销等财务单据流转
- 采购申请、订单、库存与付款计划管理
- 供应商、分包商、客户及物流公司集中维护
- 多语言界面（简体中文、English、ไทย、ລາວ）

#### 1.2 核心能力

| 模块分组 | 主要功能 |
|----------|----------|
| 项目管理 | 项目建档、合同金额、进度状态、付款节点 |
| 预算报价 | 预算项目创建、报价明细 |
| 施工管理 | 施工总览、施工日志、里程碑跟踪 |
| 审批管理 | 待审批单据、待执行付款 |
| 财务申请 | 预支、报销、付款、核销申请 |
| 财务管理 | 财务概览、汇率、项目成本、预支核销状态 |
| 采购管理 | 商品、采购申请/订单、付款计划、库存 |
| 合作伙伴 | 供应商、分包商、客户、物流公司 |
| 后台管理 | 用户/角色、流程模板、分类、导入、日志、备份 |

#### 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