# ERP-Tax

**Repository Path**: lan0811/erp-tax

## Basic Information

- **Project Name**: ERP-Tax
- **Description**: 财务ERP-面向中国个体工商户与小型公司的单机版轻量业财一体系统
- **Primary Language**: NodeJS
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: https://erp.lanaiw.top
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-25
- **Last Updated**: 2026-08-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<p align="center">
  <img src="./docs/assets/readme-banner.svg" width="100%" alt="财务 ERP V1 顶部横幅" />
</p>

<p align="center">
  <img src="./docs/assets/finance-erp-icon.png" width="160" alt="财务 ERP 应用图标" />
</p>

<h1 align="center">财务 ERP V1</h1>

<p align="center">
  面向中国个体工商户与小型公司的单机版轻量业财一体系统
</p>

<p align="center">
  <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript_5-3178C6?style=flat-square&logo=typescript&logoColor=white" />
  <img alt="React" src="https://img.shields.io/badge/React_19-20232A?style=flat-square&logo=react&logoColor=61DAFB" />
  <img alt="Ant Design" src="https://img.shields.io/badge/Ant_Design_6-0170FE?style=flat-square&logo=antdesign&logoColor=white" />
  <img alt="Vite" src="https://img.shields.io/badge/Vite_7-646CFF?style=flat-square&logo=vite&logoColor=white" />
  <img alt="NestJS" src="https://img.shields.io/badge/NestJS_11-E0234E?style=flat-square&logo=nestjs&logoColor=white" />
  <img alt="Fastify" src="https://img.shields.io/badge/Fastify_5-000000?style=flat-square&logo=fastify&logoColor=white" />
  <img alt="SQLite" src="https://img.shields.io/badge/SQLite-003B57?style=flat-square&logo=sqlite&logoColor=white" />
  <img alt="Electron" src="https://img.shields.io/badge/Electron_44-47848F?style=flat-square&logo=electron&logoColor=white" />
</p>

<p align="center">
  <img alt="Windows" src="https://img.shields.io/badge/Windows_10+-0078D4?style=flat-square&logo=windows11&logoColor=white" />
  <img alt="Local First" src="https://img.shields.io/badge/Local--first-127.0.0.1-2B5CE6?style=flat-square" />
  <img alt="Tests" src="https://img.shields.io/badge/Tests-41_passed-059669?style=flat-square" />
  <img alt="OpenAPI" src="https://img.shields.io/badge/OpenAPI-71_operations-6BA539?style=flat-square&logo=openapiinitiative&logoColor=white" />
  <img alt="License" src="https://img.shields.io/badge/License-AGPL--3.0-red?style=flat-square&logo=gnu&logoColor=white" />
</p>

---

## 产品定位

财务 ERP V1 是一套运行在 Windows 本机的轻量业财一体工作台，覆盖服务业与商贸场景。销售、采购、库存、资金、票据与税务测算最终汇入简易账或复式账，并形成可追溯的账簿、报表、审计与备份数据。

系统坚持本机优先：Web 与 Electron 只通过绑定在 `127.0.0.1` 的 NestJS API 访问 SQLite，数据库不会由浏览器直接读写。金额统一使用整数分，时区为 `Asia/Shanghai`，V1 仅支持人民币与小规模纳税人场景。

> 税务功能用于测算和申报辅助，不会连接电子税务局，也不替代最终申报。

## 核心能力

| 领域 | 已实现能力 |
| --- | --- |
| 组织与权限 | 多经营主体、多账套、跨年会计期间；老板/管理员、会计、出纳、仓管四类账套角色 |
| 三类账簿 | 个体户简易账、个体户复式账、小企业会计准则账套 |
| 财务核算 | 科目、辅助核算、期初余额、凭证草稿、送审、审核、记账、红字冲销、结账与授权反结账 |
| 财务报表 | 余额表、总账、明细账、资产负债表、利润表、现金流量表；简易账经营利润表 |
| 采购与销售 | 销售、销售退货、采购、采购退货、费用报销、收付款及应收应付账龄 |
| 库存 | 多仓库入出库、调拨、盘点、库存预警、移动加权平均成本与负库存拦截 |
| 自动凭证 | 已审核业务单据按账套规则幂等生成待审凭证，可从业务追溯到凭证 |
| 票据与银行 | 发票手工/CSV/Excel/XML 导入、PDF/OFD/XML 原件附件、查重、流水候选匹配与余额调节 |
| 税务测算 | 增值税、附加税费、企业所得税预缴、个体经营所得；规则按版本和生效日期保存 |
| 数据管理 | CSV/XLSX 导入导出、打印/PDF、错误回滚、审计日志、数据快照、自动/手动备份与恢复预检 |

## 技术架构

<p align="center">
  <img src="./docs/assets/technical-architecture.svg" width="100%" alt="财务 ERP 技术架构图" />
</p>

只有 API 进程可以访问数据库、附件和备份目录。Web 模式与桌面模式复用同一套 React UI、REST API 和会计规则，不维护两套业务逻辑。

## 技术栈

| 层级 | 技术 | 用途 |
| --- | --- | --- |
| Monorepo | ![npm](https://img.shields.io/badge/npm_Workspaces-CB3837?style=flat-square&logo=npm&logoColor=white) | 管理 `apps/*` 与 `packages/*` 工作区 |
| 语言 | ![TypeScript](https://img.shields.io/badge/TypeScript_5-3178C6?style=flat-square&logo=typescript&logoColor=white) | Web、API、桌面端和共享包统一类型系统 |
| Web | ![React](https://img.shields.io/badge/React_19-20232A?style=flat-square&logo=react&logoColor=61DAFB) ![Vite](https://img.shields.io/badge/Vite_7-646CFF?style=flat-square&logo=vite&logoColor=white) | 单页应用与开发构建 |
| UI | ![Ant Design](https://img.shields.io/badge/Ant_Design_6-0170FE?style=flat-square&logo=antdesign&logoColor=white) | 符合财务场景 Design System 的组件与图标 |
| API | ![NestJS](https://img.shields.io/badge/NestJS_11-E0234E?style=flat-square&logo=nestjs&logoColor=white) ![Fastify](https://img.shields.io/badge/Fastify_5-000000?style=flat-square&logo=fastify&logoColor=white) | 本机 REST API、鉴权、OpenAPI 与领域编排 |
| 数据 | ![SQLite](https://img.shields.io/badge/SQLite_3-003B57?style=flat-square&logo=sqlite&logoColor=white) | 本地事务、WAL、迁移与完整备份 |
| 桌面端 | ![Electron](https://img.shields.io/badge/Electron_44-47848F?style=flat-square&logo=electron&logoColor=white) | 安全加载本机 Web 服务的开发桌面壳 |
| 测试 | ![Vitest](https://img.shields.io/badge/Vitest-6E9F18?style=flat-square&logo=vitest&logoColor=white) ![Playwright](https://img.shields.io/badge/Playwright-2EAD33?style=flat-square&logo=playwright&logoColor=white) | 单元、集成、Windows Edge 与 Electron 端到端验收 |

## 仓库结构

```text
erp-tax/
├─ apps/
│  ├─ api/          NestJS + Fastify 本机 API、SQLite 迁移与集成测试
│  ├─ desktop/      Electron 开发壳
│  └─ web/          React + Vite + Ant Design 界面与 Playwright 测试
├─ packages/
│  ├─ accounting/   共享会计规则
│  ├─ config/       环境变量加载与校验
│  ├─ contracts/    类型、OpenAPI 文档与生成客户端契约
│  └─ ui/           共享 UI 包
├─ docs/
│  ├─ web-user-guide.md       Web / 桌面 GUI 共用图文教程
│  ├─ diagrams/               Mermaid 图表源码与渲染配置
│  └─ assets/                 品牌与教程图片资源
├─ scripts/         开发启动、E2E 服务与 OpenAPI 生成脚本
├─ .env.example     完整环境变量模板
└─ playwright.config.ts
```

## 环境要求

- Windows 10 或更高版本，64 位
- Git for Windows，用于克隆仓库和版本管理
- Node.js 24 LTS 或兼容版本
- npm 11 或更高版本
- Microsoft Edge，用于默认的 Windows Web 端到端测试

### 安装 Git

推荐在 Windows PowerShell 中通过 `winget` 安装 Git for Windows：

```powershell
winget install --id Git.Git --exact
```

也可以前往 [Git 官方网站](https://git-scm.com/download/win) 下载 Windows 64 位安装包。安装时可保留默认选项，完成后重新打开 PowerShell，使 `PATH` 环境变量生效。

确认 Git 已正确安装：

```powershell
git --version
```

### 安装 Node.js 与项目依赖

推荐在 Windows PowerShell 中通过 `winget` 安装 Node.js LTS：

```powershell
winget install --id OpenJS.NodeJS.LTS --exact
```

也可以前往 [Node.js 中文网](https://nodejs.cn/) 下载 Windows 64 位安装包。安装时保留 npm 与“添加到 PATH”选项，完成后重新打开 PowerShell。

确认 Node.js 与 npm 版本满足要求：

```powershell
node --version
npm --version
```

如果 Node.js 已满足要求但 npm 低于 11，可单独升级 npm：

```powershell
npm install --global npm@11
```

最后进入本仓库根目录，一次安装全部 npm workspaces 依赖：

```powershell
npm install
```

无需分别进入 `apps/*` 或 `packages/*` 安装依赖；根目录命令会按照 `package-lock.json` 和工作区配置完成安装，并自动构建共享包。

## 快速开始

在 PowerShell 中执行：

```powershell
Copy-Item .env.example .env
npm install
npm run dev:web
```

首次启动前，请在 `.env` 中把 `ERP_SESSION_SECRET` 替换为至少 32 个随机字符。可以使用 PowerShell 生成安全随机值：

```powershell
[Convert]::ToHexString(
  [Security.Cryptography.RandomNumberGenerator]::GetBytes(48)
).ToLower()
```

启动完成后访问：

- Web 工作台：<http://127.0.0.1:8081>
- API 健康检查：<http://127.0.0.1:8082/api/v1/health>
- OpenAPI 文档：<http://127.0.0.1:8082/api/v1/docs>

首次访问会进入初始化向导，一次创建本机管理员、经营主体、账套和启用期间。后续可在“组织与权限”中继续新增主体、账套、会计年度和成员角色。

## 使用教程

Web 模式与桌面 GUI 使用同一套界面和操作流程，完整说明见 [《财务 ERP Web / 桌面 GUI 使用教程》](./docs/web-user-guide.md)。教程覆盖首次初始化、基础资料、进销存、票据税务、凭证、报表、权限、导入导出与备份恢复。

## 启动方式

### Web 模式

同时启动 Vite Web 与 NestJS API：

```powershell
npm run dev:web
```

默认端口：Web `8081`，API `8082`。

### Electron 桌面模式

启动 Web、API，等待健康检查通过后打开 Electron：

```powershell
npm run dev:gui
```

Electron 开启上下文隔离、禁用 Node 集成并阻止非本机导航。V1 只提供开发桌面壳，不生成安装包。

## 常用命令

| 命令 | 说明 |
| --- | --- |
| `npm run dev:web` | 启动 Web 与 API 开发服务 |
| `npm run dev:gui` | 启动 Web、API 与 Electron 桌面壳 |
| `npm run typecheck` | 检查所有工作区 TypeScript 类型 |
| `npm run lint` | 执行全仓 ESLint 静态检查 |
| `npm test` | 运行 Vitest 单元与 API 集成测试 |
| `npm run build` | 构建所有工作区 |
| `npm run check` | 依次执行类型、Lint、测试与生产构建 |
| `npm run e2e` | 运行 Windows Edge 与 Electron 关键流程 |
| `npm run e2e:web` | 只运行 Web 端到端流程 |
| `npm run e2e:electron` | 构建并运行 Electron 端到端流程 |
| `npm run openapi:generate` | 更新 OpenAPI JSON 与前端生成客户端 |

## 环境配置

所有端口、路径与运行策略均来自 `.env`，代码中不写死本机目录。完整字段及默认开发值见 [`.env.example`](./.env.example)。

| 配置组 | 主要变量 |
| --- | --- |
| Web / API | `ERP_WEB_HOST`、`ERP_WEB_PORT`、`ERP_API_HOST`、`ERP_API_PORT`、`ERP_API_PREFIX` |
| 安全与会话 | `ERP_ALLOWED_ORIGINS`、`ERP_SESSION_SECRET`、`ERP_SESSION_COOKIE`、`ERP_SESSION_TTL_HOURS` |
| 本地数据 | `ERP_DATABASE_PATH`、`ERP_ATTACHMENTS_DIR`、`ERP_BACKUPS_DIR` |
| 会计运行时 | `ERP_TIMEZONE`、`ERP_CURRENCY`、`ERP_ALLOW_NEGATIVE_INVENTORY` |
| 文件限制 | `ERP_MAX_ATTACHMENT_MB` |
| E2E 隔离 | `ERP_E2E_WEB_PORT`、`ERP_E2E_API_PORT` |

`.env`、`.data`、测试结果和构建产物均已加入 `.gitignore`。端到端测试使用独立端口和隔离数据目录，不会修改日常账套。

## API 与前端客户端

REST API 统一使用 `/api/v1`，当前包含 71 个操作。Swagger 文档由 API 启动时提供，固定契约保存在：

- [`packages/contracts/openapi/finance-erp.openapi.json`](./packages/contracts/openapi/finance-erp.openapi.json)
- [`apps/web/src/generated/openapi-client.ts`](./apps/web/src/generated/openapi-client.ts)

所有错误响应统一包含 `code`、`message`、`details` 与 `requestId`。修改控制器后执行 `npm run openapi:generate`，并将契约与生成客户端一并提交。

## 数据与安全

- API 仅绑定 `127.0.0.1`，默认不向局域网或公网开放。
- SQLite 开启 WAL，并以事务保护初始化、导入、业务审核、记账和恢复流程。
- 本地账号使用随机盐与 `scrypt` 强密码哈希；会话令牌只保存摘要。
- 已记账凭证不可编辑或删除，只能生成关联红字凭证冲销。
- 已结会计期间禁止写入；反结账仅限老板或账套管理员。
- 关键操作记录账号、时间、来源、请求 ID 及前后状态。
- 附件保存原文件、元数据与 SHA-256；读取时重新校验完整性。
- 每日首次启动自动备份，也支持手动备份、完整性预检与指定备份恢复。

## 质量状态

当前验收结果：

- 类型检查、ESLint 与生产构建通过
- 15 个测试文件、41 项单元/集成测试通过
- 三类账簿样例的期初、交易、报表勾稽与结账测试通过
- Windows Edge Web 与 Electron 关键 Playwright 流程通过
- `npm run dev:web` 与 `npm run dev:gui` 已在 Windows 64 位环境验证
- npm 官方安全审计为 0 个已知漏洞

## 开源协议

本项目（财务 ERP V1）© 2026 Lan0811，以 [GNU Affero General Public License v3.0](./LICENSE)（AGPL-3.0）开源发布。核心要点：

- 您可以自由使用、学习、修改和分发本项目，包括个人与内部商用使用。
- 如果您修改了本项目，或以任何形式向他人提供修改版本的运行（包括将其部署为网络服务），则必须将修改后的完整源码以 AGPL-3.0 同样开源。
- 项目按“AS IS”提供，不附带任何明示或默示担保，详见 LICENSE 第 15、16 条。

**商业授权**：AGPL 之外的闭源分发、嵌入式集成、SaaS 化部署或其他需要豁免 AGPL 义务的商业场景，请联系作者获取商业授权。

## 问题反馈与功能建议

如果发现功能异常、界面问题、性能或稳定性问题，或希望提出新功能与操作体验建议，请先搜索 [Gitee Issues](https://gitee.com/lan0811/erp-tax/issues)，确认没有相同反馈后再创建 Issue。

提交前请参考仓库内的 [中文 Issue 模板](./.gitee/ISSUE_TEMPLATE.zh-CN.md)，并尽量提供：

- 反馈类型与清晰的问题或需求描述
- 可以稳定复现问题的操作步骤
- 实际结果与预期结果
- App 版本、Windows 版本、发生时间及复现频率
- 已遮挡账号、金额、税号等个人或经营信息的截图或录屏

请勿在 Issue 中提交账号、密码、会话令牌、签名文件、完整数据库、未脱敏票据或其他敏感信息。模板中的提交前检查清单可以帮助维护者更快定位和处理问题。

## V1 范围边界

V1 不包含一般纳税人完整申报、税局/银行直连、直接开票、一键报税、OCR、工资、固定资产、外币、预算、生产制造、批次/序列号、POS、电商平台、多门店、云同步、移动 App、局域网/公网部署、Electron 安装包及历史凭证迁移。

如需扩展功能，应继续保持本机数据边界、整数金额、账套隔离、审计追踪和不可逆记账规则。

---

<p align="center">
  本机运行 · 数据自持 · 业财一体 · 可审计恢复
</p>