# EAM 资产管理系统

**Repository Path**: MerlinRong/EAM

## Basic Information

- **Project Name**: EAM 资产管理系统
- **Description**: 企业拥有大量且种类繁杂的设备资产（如生产设备、车辆、电梯、空调、IT 资产等）。传统管理方式存在台账不清、维护滞后、备件库存不合理、维修成本难以统计等痛点。本项目旨在构建一套全生命周期的 EAM 系统，实现资产数字化、维护预防化、工单流转自动化及决策数据化。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-10-07
- **Last Updated**: 2026-10-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">

# EAM 资产管理系统

**Enterprise Asset Management — 全生命周期企业资产管理平台**

![Python](https://img.shields.io/badge/Python-3.11-3776AB?logo=python&logoColor=white)
![FastAPI](https://img.shields.io/badge/FastAPI-0.115-009688?logo=fastapi&logoColor=white)
![Vue.js](https://img.shields.io/badge/Vue-3.5-4FC08D?logo=vuedotjs&logoColor=white)
![TypeScript](https://img.shields.io/badge/TypeScript-5.6-3178C6?logo=typescript&logoColor=white)
![PostgreSQL](https://img.shields.io/badge/PostgreSQL-16-4169E1?logo=postgresql&logoColor=white)
![Docker](https://img.shields.io/badge/Docker-Compose-2496ED?logo=docker&logoColor=white)
![Tests](https://img.shields.io/badge/tests-44%20passed-brightgreen)

设备台账 · 预防性维护 · 工单流转 · 扫码巡检 · 备件库存 · 折旧报废 · 统计报表

</div>

---

## 📋 目录

- [功能特性](#-功能特性)
- [技术栈](#-技术栈)
- [架构总览](#-架构总览)
- [快速开始](#-快速开始)
- [生产部署](#-生产部署)
- [运行测试](#-运行测试)
- [项目结构](#-项目结构)
- [关键设计决策](#-关键设计决策)
- [Git 提交规范](#-git-提交规范)
- [路线图](#-路线图)

## ✨ 功能特性

### 资产管理
- 🌳 **多级分类树**：物化路径优化子树查询，支持 BOM 父子设备层级
- 🏷️ **属性模板**：按分类自定义扩展属性（JSONB），前端动态表单渲染
- 📱 **二维码体系**：HMAC 签名 + 版本号，防伪造扫码、重置即作废
- 📉 **智能折旧**：直线法 / 双倍余额递减（末两年自动转直线）/ 工作量法

### 维护与工单
- 🔁 **工单状态机**：显式转移表驱动，非法流转 422、角色越权 403
- ⏱️ **SLA 管理**：按设备重要等级自动匹配时限，临期预警、超时升级督办
- 🤖 **PM 自动生成**：Celery Beat 定时扫描，周期幂等去重
- 📍 **扫码巡检**：验签 + 路线校验防假巡检，异常项一键转维修工单

### 备件与报表
- 📦 **库存事务**：行级锁 + before/after 流水快照，杜绝超卖
- 🔔 **安全库存预警**：阈值触发通知，支持自动采购申请
- 📊 **数据看板**：MTBF / MTTR / 故障原因帕累托 / 维修成本多维分析
- 🕵️ **全程审计**：SQLAlchemy 事件监听零侵入记录变更前后值

## 🛠 技术栈

| 层级 | 技术 |
| --- | --- |
| 后端 | FastAPI · SQLAlchemy 2.0 (async) · Alembic · Celery |
| 数据 | PostgreSQL 16 · Redis 7 |
| 前端 | Vue 3 · TypeScript · Element Plus · ECharts · Pinia |
| 部署 | Docker Compose · Nginx |

## 🏗 架构总览

```
                 ┌───────────────┐
    用户 ────────▶│     Nginx      │
                 └──────┬────────┘
              ┌─────────┴─────────┐
              ▼                   ▼
        Vue3 SPA (dist)     FastAPI × 4 workers
                            api → services → models
                            状态机 · 策略模式 · RBAC
                              │            │
              ┌───────────────┤            │
              ▼               ▼            ▼
        PostgreSQL 16     Redis 7     Celery Worker/Beat
       （业务库）     （缓存/锁/MQ）  PM生成·SLA升级·月度折旧·库存预警
```

## 🚀 快速开始

### 1. 后端

```bash
git clone https://gitee.com/MerlinRong/EAM.git
cd EAM/backend

python -m venv .venv
.venv\Scripts\pip install -e ".[dev]"   # Windows
# Linux/macOS: source .venv/bin/activate && pip install -e ".[dev]"

# 启动中间件（可选，缺省回退 SQLite）
docker compose -f deploy/docker-compose.dev.yml up -d

.venv\Scripts\python -m uvicorn app.main:app --reload
```

> API 文档：http://localhost:8000/docs · 健康检查：`/health`
> 默认管理员 `admin / admin123`（⚠️ 仅 seed 用途，登录后请立即修改）

### 2. 前端

```bash
cd frontend
npm install
npm run dev     # http://localhost:5173，/api 自动代理到 :8000
```

## 🐳 生产部署

```bash
# 1. 配置环境变量（修改全部密钥！）
cp deploy/.env.example deploy/.env

# 2. 构建前端
cd frontend && npm run build

# 3. 一键编排
docker compose -f deploy/docker-compose.yml up -d --build

# 4. 首次部署生成数据库
cd backend
alembic revision --autogenerate -m "init"
alembic upgrade head
```

服务清单：`nginx`(80) · `fastapi-app`(×4) · `celery-worker` · `celery-beat` · `postgresql:16` · `redis:7`，全部带健康检查与自动重启。

## ✅ 运行测试

```bash
cd backend
.venv\Scripts\python -m pytest tests/ -q
# 44 passed — 状态机全量转移表 / 折旧三算法边界 / 二维码验签
#             库存防超卖 / PM 幂等 / SLA 时限 / 扫码防伪
```

## 📁 项目结构

```
EAM/
├── backend/
│   ├── app/
│   │   ├── api/v1/          # 路由层（auth/assets/work_orders/inspections/spare_parts/...）
│   │   ├── services/        # 业务层：状态机、库存事务、折旧策略、PM 生成
│   │   ├── models/          # SQLAlchemy 2.0 异步模型
│   │   ├── tasks/           # Celery 任务 + Beat 调度表
│   │   ├── core/            # JWT / RBAC / 配置 / 统一响应
│   │   └── db/              # 会话管理 / 审计监听
│   ├── tests/               # pytest（44 项）
│   └── alembic/             # 数据库迁移
├── frontend/
│   └── src/
│       ├── api/             # axios 封装 + 契约对齐
│       ├── views/           # 看板/台账/工单看板/报表/H5扫码报修
│       ├── stores/          # Pinia（auth RBAC）
│       └── router/          # 路由 + 登录守卫
└── deploy/                  # Docker Compose / Nginx / .env.example
```

## 💡 关键设计决策

| 主题 | 方案 | 为什么 |
| --- | --- | --- |
| 工单流转 | 显式状态机转移表 | 全量可测试、可导出文档，新增状态只改表不改逻辑 |
| 扩展属性 | JSONB + 属性模板 | 避免动态加列，GIN 索引可查，服务端 Schema 校验 |
| 二维码 | HMAC 签名 + 版本号 | 防伪造打卡；重置旧码立即失效 |
| 库存扣减 | `SELECT ... FOR UPDATE` + 流水快照 | 并发防超卖，任意流水可独立还原现场 |
| 折旧 | 策略模式注册表 | 新算法零侵入接入（开闭原则） |
| 审计 | SQLAlchemy 事件监听 | 业务代码零侵入，before/after 差异自动采集 |

## 📌 Git 提交规范

Conventional Commits，每次功能改动完成即创建对应 commit：

```
feat(P2): 工单状态机     fix(库存): 并发领用超卖     test(折旧): 双倍余额用例
```

## 🗺 路线图

- [x] P0-P5 核心域开发（资产 / 工单 / 巡检 / 备件 / 折旧 / 报表）
- [ ] 工作流引擎对接（维修/报废审批，当前为内置 `decide` 模拟，需实现 `WorkflowAdapter`）
- [ ] 消息通道扩展（企微/钉钉/邮件/短信，当前落库 inapp）
- [ ] PostgreSQL 并发压测（testcontainers，QPS ≥ 1000）
- [ ] 移动端相机扫码（BarcodeDetector，当前支持手工粘贴/输入码）

---

<div align="center">

Made with ❤️ by EAM Team

</div>