开放ERP系统 (open-erp)

基于 webman v2 + Flutter 的全栈ERP系统。

功能清单

下载

ERP 模块

各业务模块间的数据流转：

• 采购收货 → 自动入库（移动加权平均成本核算） → 自动生成应付
• 销售发货 → 自动出库 → 自动生成应收
• 收付款 → 核销应收应付 → 更新日记账
• 凭证审核 → 自动更新总账(科目汇总) + 明细账(逐笔记录)
• 资产负债表 → 自动汇总总账期末余额生成
• 现金流量表 → 自动汇总现金银行日记账生成（经营/投资/筹资三分类）
• 审批工作流 → 业务单据提交审批 → 多节点流转 → 审批结果回调业务模块
• 消息通知 → 审批/预警/系统事件触发 → 实时推送 → 用户标记已读
• MRP → 基于销售订单+BOM → 计算物料需求 → 生成采购建议/生产建议

技术栈

核心依赖

国际化

国际化 | Accept-Language 头自动检测 | 中文/English 双语支持

项目结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

open-erp/
├── app/
│   ├── admin/controller/       # 系统管理控制器 (14 个)
│   ├── api/v1/controller/      # 客户端 API（版本由 API-Version 请求头控制）
│   ├── controller/             # 业务模块控制器 (70 个)
│   │   ├── product/            # 商品/分类/品牌/仓库/库位/供应商/客户 (7 个)
│   │   ├── purchase/           # 采购申请/订单/收货/退货/结算 (5 个)
│   │   ├── sales/              # 销售报价/订单/发货/退货/结算 (5 个)
│   │   ├── inventory/          # 库存/流水/调拨/盘点/预警 (5 个)
│   │   ├── finance/            # 应收应付/凭证/收付款/日记账/总账/明细账/报表/资产/税务/多币种/预算/成本利润中心 (20 个)
│   │   ├── crm/                # 商机/跟进/漏斗/联系人/公海池/合同/报价/营销/工单/分析 (10 个)
│   │   ├── workflow/           # 工作流定义/审批提交/批准/拒绝/撤回 (2 个)
│   │   ├── notification/       # 通知列表/已读/未读计数 (1 个)
│   │   ├── project/            # 项目/任务/工时记录 (3 个)
│   │   ├── hr/                 # 部门/员工/职位/考勤/请假/薪资 (5 个)
│   │   ├── manufacturing/      # BOM/生产订单/工艺路线/工作站/MRP (5 个)
│   │   └── report/             # 报表模板/数据集/执行/定时调度 (2 个)
│   ├── service/                # 业务逻辑层
│   │   ├── inventory/          # 出入库 + 移动加权平均成本核算
│   │   ├── finance/            # 应收应付自动生成 + 核销
│   │   └── notification/       # 通知发送服务
│   ├── model/                  # 121 个 Eloquent 模型（多模块共用）
│   ├── middleware/             # 9 个中间件
│   ├── common/                 # Hashids/Snowflake/Encryption 服务
│   └── queue/                  # 队列任务
├── apps/
│   ├── flutter/                # Flutter 跨平台（Web PC + iOS/Android/macOS/Windows/Linux）
│   └── harmonyos/              # HarmonyOS 原生客户端
├── config/                     # 配置文件（含中文注释）
│   ├── plugin/hg/apidoc/        # API 文档配置
├── database/
│   ├── migrations/             # SQL 迁移文件（18 个，122 张表）
│   └── backup/                 # 备份/恢复脚本
├── docs/                       # 架构、设计、安全、API 文档
├── tests/                      # PHPUnit 测试（11 个测试文件，90 个测试方法，168 条断言）
├── resource/
│   └── translations/           # 翻译文件 (zh_CN, en)
│       ├── zh_CN/              # 中文翻译 (127 键)
│       └── en/                 # English translations (127 keys)
├── public/                     # 公共入口
├── runtime/                    # 运行时文件
└── vendor/                     # Composer 依赖

环境要求

• PHP >= 8.3
• Composer 2.x
• MySQL >= 8.0
• Flutter >= 3.41（仅前端开发需要）
• Elasticsearch >= 7.x（可选，搜索功能需要）

快速开始

1. 安装依赖

1

composer install

2. 配置环境变量

复制并修改环境变量（可选，不配置则使用 config/*.php 中的默认值）:

1

cp .env.example .env

关键配置项：

生产环境务必修改所有密钥为随机字符串。

3. 初始化数据库

按顺序执行 database/migrations/ 下的 SQL 文件：

1
2
3
4

# 建表
mysql -u root -p < database/migrations/2026_05_16_000000_init_tables.sql
# 播种权限数据
mysql -u root -p < database/migrations/2026_05_20_000001_seed_permissions.sql

4. 启动服务

1

php start.php start

默认监听 http://0.0.0.0:8787。

5. 启动前端（可选）

Flutter 管理后台（Web 端）:

1
2
3

cd apps/flutter
flutter pub get
flutter run -d chrome    # Web 端（PC 管理后台风格）

HarmonyOS 客户端（手机端）:

使用 DevEco Studio 打开 apps/harmonyos/ 目录，连接真机或模拟器运行。

6. Docker Compose 一键部署（推荐生产环境）

项目提供完整的 Docker 编排方案，包含 5 个服务：Nginx、PHP (webman app)、MySQL、Redis、Elasticsearch。

1
2
3
4
5
6
7
8
9
10
11
12
13

# 1. 配置 Docker 环境变量
cp .env.docker .env

# 2. 启动所有服务
docker-compose up -d

# 3. 初始化数据库（进入 app 容器执行）
docker-compose exec app mysql -h mysql -u root -p < database/migrations/2026_05_16_000000_init_tables.sql
docker-compose exec app mysql -h mysql -u root -p < database/migrations/2026_05_20_000001_seed_permissions.sql

# 4. 访问
# http://localhost:8787  (webman)
# http://localhost:8080  (Nginx 反向代理)

• Dockerfile: PHP 8.3 + OPcache + Composer，基于 php:8.3-cli
• docker-compose.yml: 5 个服务编排，网络隔离，数据卷持久化
• .env.docker: Docker 环境专用环境变量

数据库规范

• 表前缀: erik_
• 主键: 所有表主键均为 id BIGINT UNSIGNED NOT NULL，禁用 AUTO_INCREMENT
• ID 生成: 主键 ID 由应用层 SnowflakeService::generate() 生成，分布式唯一
• 必备字段: 每张表必须包含 id, created_at, updated_at
• 软删除: 需要软删除的表添加 deleted_at DATETIME DEFAULT NULL
• 敏感字段: 手机号、邮箱、身份证号等使用 encryptable 插件自动加解密，数据库字段使用 VARCHAR(500) 存储密文

API 规范

API 文档

项目使用 hg/apidoc 自动生成接口文档，访问 /apidoc 查看。

• 管理端接口 (Admin)：25 个模块分组，含完整请求参数和响应结构
• 客户端接口 (Service API)：认证/验证码/商品 3 个分组
• 所有接口标注了 JWT 认证、API 版本、国际化等全局请求头

统一响应格式

1
2
3
4
5

{
    "code": 0,
    "message": "success",
    "data": {}
}

业务错误码

国际化

请求头 Accept-Language 自动切换语言（zh-CN → 中文, en → English），默认中文。

ID 处理

• 请求/响应中的 ID: 使用 hashids 加密为字符串，不暴露真实数据库 ID
• 接口路径: GET /admin/user/{hashid} — 路径中的 {id} 为 hashid 字符串
• 数据库存储: BIGINT 原值，由 snowflake 生成

API 版本

API 版本通过请求头控制，不在 URL 中体现：

1

API-Version: v1

• 未携带版本号时默认使用 v1
• 不支持的版本返回 400 Bad Request
• 新增版本时只需创建 app/api/{version}/controller/ 目录，中间件注册新版本即可

限流

基于 Redis 滑动窗口算法，默认 60 次/分钟/IP/路由。敏感接口更严格：

• 登录：10 次/分钟
• 注册：5 次/分钟

响应头包含 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset。超限返回 429 并附带 Retry-After。

中间件架构

全局中间件对所有请求生效，按序执行：

1
2
3
4
5
6
7
8

Locale（Accept-Language 自动检测，设置语言环境）
  → Cors（跨域预处理 + 响应头）
  → SecurityFilter（HTTP方法限制/请求体大小/Content-Type校验/XSS/SQL注入/路径遍历/命令注入/CSRF 攻击拦截）
  → RateLimit（Redis 滑动窗口限流 + 账号锁定：5次登录失败锁定15分钟）
  → ApiVersion（API 版本校验，/api 路由组）
  → AdminAuth（JWT 认证 + 黑名单，/admin 路由组）
  → AdminPermission（RBAC 鉴权，/admin 路由组）
  → OperationLog（POST/PUT/DELETE 自动记录，含来源端检测，/admin 路由组）

/health 和 /api/docs 为公开端点，仅经过 Locale → Cors → SecurityFilter → RateLimit。

安全增强：

• 账号锁定：连续 5 次登录失败，账号自动锁定 15 分钟，期间登录返回 429
• 并发会话限制：同一用户最多 3 个有效 Token，超出时最旧 Token 自动加入黑名单
• security.txt：GET /.well-known/security.txt 提供 RFC 9116 标准安全联系信息
• Nginx 安全配置：参考 docs/nginx-security.conf 提供完整的反向代理安全加固示例

认证

登录与注册需要先通过点击验证码校验：

1. 客户端请求 POST /api/captcha/generate 获取验证码图片（base64 PNG）和文字目标列表
2. 用户按顺序点击图中对应文字位置，收集点击坐标 [{x, y}, ...]
3. 登录时一并提交 captcha_key 和 clicks，服务端先校验验证码再校验凭证

1
2
3
4
5
6
7
8
9

POST /api/auth/login
Content-Type: application/json

{
  "username": "admin",
  "password": "******",
  "captcha_key": "abc123...",
  "clicks": [{"x": 120, "y": 85}, {"x": 210, "y": 140}, {"x": 95, "y": 170}]
}

管理端后续接口需要 JWT 认证：

1

Authorization: Bearer <token>

登录成功后返回 access_token，有效期 2 小时；另返回 refresh_token，有效期 14 天。

登出时 Token 加入 Redis 黑名单，有效期内不可复用。POST /admin/profile/logout

敏感操作二次确认

删除用户、角色、权限等敏感操作需要在请求体中传入当前登录用户的 password 进行身份二次确认：

1
2
3
4
5

DELETE /admin/user/{id}
Content-Type: application/json
Authorization: Bearer <token>

{ "password": "******" }

API 列表

所有 /api/* 接口需要在请求头中携带 API-Version: v1（不传则默认 v1）。

公开接口

管理端接口（需 JWT + RBAC）

业务接口（需 JWT + RBAC）

客端接口（需 API-Version 头）

前端说明

Flutter 管理后台（PC 风格）

• 布局: 侧边栏（可折叠 64px/240px）+ 顶栏 + 内容区，响应式三断点（手机/平板/桌面）
• 页面: 登录、仪表盘、用户管理、角色权限、系统配置、操作日志、个人中心
• 状态管理: GetX（ApiService 单例 + AuthService Token 持久化）
• 仪表盘: 统计卡片、趋势折线图（fl_chart）、饼图、最近操作日志
• 导出: Excel/PDF 导出，PDF 含不可移除版权信息
• 批量操作: 多选批量删除、批量启用/禁用
• 主题: Material 3 浅色/深色双主题

HarmonyOS 移动端

• 页面: 登录、仪表盘、用户列表/详情、个人中心
• 认证: JWT Bearer + 401 自动无感刷新 Token，刷新失败自动重定向登录页
• 存储: Token 通过 AppStorage 管理

开发规范

• 全局函数/类引用不加前置 \，统一使用 use 导入
• 所有 PHP 文件头部必须包含版权声明
• 所有配置文件必须包含中文注释说明
• 数据库主键必须由应用层 snowflake 生成，禁止自增
• API 层所有参数和响应中的 ID 必须通过 hashids 加解密
• AdminPermission 中间件使用 Redis 缓存用户权限（TTL=60s），消除 N+1 查询瓶颈

部署

Docker Compose（推荐）

项目根目录提供 docker-compose.yml，编排 5 个服务：

PHP 镜像通过 Dockerfile 构建，基础镜像 php:8.3-cli，启用 OPcache。

1
2

cp .env.docker .env
docker-compose up -d

CI/CD

GitHub Actions 持续集成流水线：.github/workflows/ci.yml

• PHP 语法检查 (php -l)
• PHPUnit 单元测试
• Flutter 静态分析 (flutter analyze)

数据库备份

database/backup/ 目录：

• backup.sh — mysqldump + gzip 备份，自动清理 30 天前旧备份
• restore.sh — 交互式恢复，列出可用备份供选择

Nginx 安全配置

生产部署请参考 docs/nginx-security.conf 配置反向代理安全加固。

开放ERP系统提供三个版本，适应不同规模企业的需求。

版本概览

功能对比

系统管理

商品与基础数据

采购管理

销售管理

库存管理

财务管理

CRM

平台能力

扩展模块

适用场景

升级路径

1
2
3
4
5
6
7
8

Lite (简化版)
  ├─ 62 表 / 12 业务模块 / 无审批/通知/HR/制造/报表
  │
  ├─ Standard (标准版)
  │    ├─ 72 表 / 12 业务模块 / 更精简的数据模型
  │
  └─ Full (完整版)
       └─ 122 表 / 6 业务模块 / 全面的企业平台能力

赏

一只PHP开发的程序猿，偶尔搞搞摄影、画画、写作、顺便睡觉。

支付宝

微信