# 检定证书管理系统

**Repository Path**: ydbso/calibration_system

## Basic Information

- **Project Name**: 检定证书管理系统
- **Description**: 检定证书管理系统
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-24
- **Last Updated**: 2026-04-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 检定证书管理系统

## 项目简介

检定证书管理系统是一套面向计量检定实验室的全流程管理平台，用于管理**数字指示秤（电子汽车衡）**的检定业务。系统依据 **JJG 539-2016 数字指示秤检定规程**，实现了从客户管理、设备台账、标准器管理到检定数据录入、证书自动生成的完整业务闭环。

核心功能包括：
- 客户和设备档案管理，支持到期预警
- 标准器有效期跟踪
- 检定任务全生命周期管理（草稿 → 已检定 → 待审核 → 已批准 → 已签发 → 已完成）
- 七项检定数据的在线录入（置零准确度、称量、除皮准确度、除皮后称量、重复性、偏载、鉴别阈）
- 基于 Word/Excel 模板一键生成检定证书和原始记录
- 自动计算载荷点和最大允许误差（MPE）
- 模拟数据生成功能，用于演示和测试

## 技术栈

| 层级 | 技术 |
|------|------|
| 前端 | React 19 + Vite + Ant Design 6 + react-router-dom v6 + dayjs |
| 后端 | Express 5 + MySQL (mysql2/promise) + JWT + bcryptjs |
| 文档生成 | docxtemplater + PizZip（Word 证书）/ ExcelJS（Excel 原始记录） |
| 文件上传 | multer |

## 运行与开发

### 环境要求

- Node.js
- MySQL 数据库

### 数据库初始化

导入 `server/database/init.sql` 创建数据库和表。默认数据库名 `calibration_system`，默认管理员账号 `admin`。

### 后端（server 目录）

```bash
cd server
npm install
npm run dev      # 开发模式（nodemon 热重载），端口 3001
npm start        # 生产模式
```

环境变量（`.env` 文件）：
- `DB_HOST` / `DB_PORT` / `DB_USER` / `DB_PASSWORD` / `DB_NAME` — 数据库连接
- `JWT_SECRET` / `JWT_EXPIRES_IN` — JWT 配置
- `PORT` — 服务端口，默认 3001
- `UPLOAD_DIR` — 生成文件存储目录

### 前端（client 目录）

```bash
cd client
npm install
npm run dev      # 开发模式，端口 3000
npm run build    # 生产构建
npm run lint     # ESLint 检查
```

前端通过 Vite 开发代理将 `/api` 和 `/uploads` 请求转发到后端 `localhost:3001`。

### 重置管理员密码

```bash
cd server
node utils/resetPassword.js    # 将 admin 密码重置为 admin123
```

## 系统架构

### 目录结构

```
calibration_system/
├── client/                      # 前端 React 应用
│   ├── src/
│   │   ├── api/index.js         # Axios 封装，所有 API 调用
│   │   ├── router/index.jsx     # 路由配置与登录鉴权
│   │   ├── components/Layout.jsx # 主布局（侧边栏 + 顶栏）
│   │   └── pages/
│   │       ├── Login/           # 登录页
│   │       ├── Dashboard/       # 首页仪表盘（到期提醒、统计）
│   │       ├── Customers/       # 客户管理
│   │       ├── Devices/         # 设备台账
│   │       ├── Standards/       # 标准器管理（列表 + 新建/编辑）
│   │       ├── Templates/       # 模板管理（上传/下载 Word、Excel 模板）
│   │       └── Tasks/           # 检定任务（列表 + 新建 + 详情/数据录入）
│   └── vite.config.js           # Vite 配置（端口 3000，API 代理）
│
├── server/                      # 后端 Express 应用
│   ├── app.js                   # 入口：中间件注册、路由挂载、错误处理
│   ├── config/
│   │   ├── database.js          # MySQL 连接池（mysql2/promise）
│   │   └── jwt.js               # JWT 密钥和过期时间
│   ├── middleware/auth.js       # JWT 认证中间件 + 管理员权限检查
│   ├── utils/response.js        # 统一响应格式工具类
│   ├── models/
│   │   ├── index.js             # BaseModel：通用 CRUD 基类
│   │   ├── User.js              # 用户模型（密码 bcrypt 加密）
│   │   ├── Customer.js          # 客户模型（支持名称搜索）
│   │   ├── Device.js            # 设备模型（到期查询、关联客户、更新检定日期）
│   │   ├── Standard.js          # 标准器模型（有效期筛选）
│   │   ├── Template.js          # 模板模型（按类别和类型查询）
│   │   └── Task.js              # 任务模型（关联查询、JSON 数据存取、标准器关联）
│   ├── controllers/             # 业务逻辑控制器
│   ├── routes/                  # 路由定义（RESTful API）
│   ├── services/
│   │   ├── certificateService.js    # 证书编号生成（按类别独立计数、年度重置、行锁并发安全）
│   │   └── documentService.js       # Word/Excel 文档生成（模板占位符填充）
│   ├── templates/               # 上传的模板文件存储目录
│   └── utils/resetPassword.js   # 管理员密码重置脚本
│
├── uploads/                     # 生成的证书和原始记录文件
└── server/database/init.sql     # 数据库建表和初始数据
```

### API 接口

所有接口前缀 `/api`，除登录外均需 JWT 认证（`Authorization: Bearer <token>`）。

| 模块 | 方法 | 路径 | 说明 | 权限 |
|------|------|------|------|------|
| 认证 | POST | `/api/auth/login` | 登录 | 公开 |
| 认证 | GET | `/api/auth/profile` | 获取当前用户 | 登录 |
| 认证 | POST | `/api/auth/change-password` | 修改密码 | 登录 |
| 客户 | GET/POST | `/api/customers` | 列表/创建 | 登录 |
| 客户 | GET/PUT/DELETE | `/api/customers/:id` | 详情/更新/删除 | 登录 |
| 设备 | GET/POST | `/api/devices` | 列表/创建 | 登录 |
| 设备 | GET/PUT/DELETE | `/api/devices/:id` | 详情/更新/删除 | 登录 |
| 设备 | GET | `/api/devices/expiring/list` | 即将到期设备 | 登录 |
| 设备 | GET | `/api/devices/expired/list` | 已过期设备 | 登录 |
| 标准器 | GET | `/api/standards` | 列表 | 登录 |
| 标准器 | GET | `/api/standards/active/list` | 有效标准器 | 登录 |
| 标准器 | POST/PUT/DELETE | `/api/standards(/:id)` | 增删改 | 管理员 |
| 模板 | GET | `/api/templates` | 列表 | 登录 |
| 模板 | POST | `/api/templates/upload` | 上传模板 | 管理员 |
| 模板 | GET | `/api/templates/:id/download` | 下载模板 | 登录 |
| 任务 | GET/POST | `/api/tasks` | 列表/创建 | 登录 |
| 任务 | GET/PUT/DELETE | `/api/tasks/:id` | 详情/更新/删除 | 登录 |
| 任务 | POST | `/api/tasks/:id/data` | 保存检定数据 | 登录 |
| 任务 | PUT | `/api/tasks/:id/standards` | 更新关联标准器 | 登录 |
| 任务 | POST | `/api/tasks/:id/submit` | 提交审核 | 登录 |
| 任务 | POST | `/api/tasks/:id/approve` | 审核通过 | 登录 |
| 任务 | POST | `/api/tasks/:id/generate` | 生成证书文档 | 登录 |
| 任务 | GET | `/api/tasks/:id/download` | 下载文档 | 登录 |
| 任务 | GET | `/api/tasks/stats/this-month` | 本月统计 | 登录 |

### API 响应格式

所有接口统一返回：

```json
{
  "code": 200,
  "success": true,
  "message": "操作成功",
  "data": {}
}
```

### 数据库表结构

| 表名 | 说明 | 关键字段 |
|------|------|----------|
| `users` | 用户表 | username, password(bcrypt), role(admin/operator) |
| `customers` | 客户表 | name, address, contact_person, contact_phone |
| `devices` | 设备台账 | device_name, device_model, serial_no, customer_id, category, verification_cycle, next_verification_date, status |
| `standards` | 标准器表 | name, measurement_range, accuracy, cert_no, validity_date, status |
| `templates` | 模板表 | name, template_type(word/excel), category, file_path |
| `verification_tasks` | 检定任务表 | task_no, device_id, customer_id, certificate_no, verification_date, validity_date, conclusion, status, task_data(JSON), certificate_file, rawdata_file |
| `task_standards` | 任务-标准器关联表 | task_id, standard_id |
| `certificate_rules` | 证书编号规则表 | category, prefix, current_year, current_seq |

### 证书编号生成规则

证书编号按设备类别独立计数，格式为：**前缀 + 年份 + 序号 + 后缀**

- 类别 A（衡器类）：默认前缀 `陕鼎(衡)字第`，后缀 `号`，如 `陕鼎(衡)字第2026001号`
- 每年自动重置序号从 001 开始
- 使用数据库行锁（`FOR UPDATE`）保证并发安全

### 检定数据结构

检定任务的详细数据以 JSON 格式存储在 `verification_tasks.task_data` 字段中，包含七个检定项目的数据：

1. **置零准确度**（`zeroAccuracy`）：砝码 L₀、示值 I₀、附加载荷 ΔL、误差 E₀、MPE
2. **称量测试**（`weighingData`）：5 行数据，每行包含载荷、加载/卸载示值、附加载荷、误差、修正误差、MPE
3. **除皮准确度**（`tareAccuracy`）：与置零准确度结构相同
4. **除皮后称量**（`tareWeighingData`）：5 行，结构与称量测试相同
5. **重复性**（`repeatabilityData`）：3 次测量，计算极差 Eᵣ
6. **偏载**（`eccentricityData`）：最多 10 行（根据支承点数），含位置、载荷、误差、修正误差
7. **鉴别阈**（`discriminationData`）：3 个测试点

载荷点和 MPE 根据检定分度值 e 和最大称量 Max 自动计算，依据 JJG 539-2016 的规定：
- MPE：0\~500e 为 ±0.5e，500e\~2000e 为 ±1e，2000e 以上为 ±1.5e

### 文档生成机制

系统基于用户上传的模板文件生成证书和原始记录：

- **Word 证书**：使用 docxtemplater 库，模板中预定义中文命名占位符（如 `{证书编号}`、`{称量_载荷_1}`），系统将检定数据映射到占位符并填充
- **Excel 原始记录**：使用 ExcelJS 库，通过单元格坐标（如 `B2`、`A17`）直接写入数据

模板文件通过"模板管理"页面上传，按类别（如 `car_scale` 衡器类）和类型（word/excel）区分。

### 前端路由

| 路径 | 页面 | 说明 |
|------|------|------|
| `/login` | 登录 | 用户名密码登录 |
| `/` | 首页仪表盘 | 统计数据、设备到期提醒 |
| `/customers` | 客户管理 | CRUD |
| `/devices` | 设备台账 | CRUD，支持按客户跳转 |
| `/standards` | 标准器列表 | 全部/即将过期/已过期三个标签 |
| `/standards/create` | 新建标准器 | 表单 |
| `/standards/edit/:id` | 编辑标准器 | 表单 |
| `/templates` | 模板管理 | 上传/下载/删除 |
| `/tasks` | 任务列表 | 按状态、设备、关键词筛选 |
| `/tasks/create` | 新建任务 | 选设备、选日期、选标准器 |
| `/tasks/:id` | 任务详情 | 检定数据录入、计算、模拟、保存、生成证书 |

## 业务流程

```
客户建档 → 设备登记 → 创建检定任务 → 录入检定数据 → 生成证书
                                              ↓
                                   自动更新设备检定日期
```

1. **客户管理**：登记送检单位信息（名称、地址、联系人）
2. **设备台账**：登记被检设备信息，关联客户，设定检定周期，系统自动计算下次检定日期
3. **标准器管理**：登记计量标准器信息，跟踪有效期
4. **创建任务**：选择设备，自动确定客户，选择标准器，系统自动生成证书编号和有效期
5. **数据录入**：在任务详情页填写七项检定数据。支持"计算"按钮自动填充载荷和 MPE，支持"模拟"按钮生成测试数据
6. **生成证书**：一键生成 Word 检定证书和 Excel 原始记录，同步更新设备的检定日期
7. **首页监控**：仪表盘显示客户数、设备数、本月检定数和到期提醒

## 生产部署（1Panel）

服务器目录结构：

```
/www/sites/你的域名/index/    ← client/dist/ 里的所有文件（Nginx 托管静态文件）
/opt/calibration/server/      ← server 文件夹（Node.js 后端）
```

### 1. 构建并上传前端

```bash
cd client
npm run build
# 将 dist/ 里的所有文件上传到服务器 /www/sites/你的域名/index/
```

### 2. 启动后端

```bash
cd /opt/calibration/server
npm start        # 默认端口 3001
```

### 3. 1Panel 配置

在 1Panel 面板中创建网站：

1. **网站类型**：静态网站
2. **网站根目录**：`/www/sites/你的域名/index/`（前端静态文件）
3. **反向代理规则**（在网站设置 → 反向代理中添加）：
   - `/api` → `127.0.0.1:3001`
   - `/uploads` → `127.0.0.1:3001`
4. **SPA 路由**：在网站设置 → URL 重写中添加 `try_files $uri $uri/ /index.html;`，确保前端路由（如 `/tasks/123`）不会 404