# eams-control

**Repository Path**: holyhandcn/eams-control

## Basic Information

- **Project Name**: eams-control
- **Description**: 企业资产全生命周期管理系统后端
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# EAMS 后端（eams-control）

EAMS 资产管理系统的后端（Spring Boot 单体）。它负责业务数据与权限，并且在标签打印链路里承担一个**边界清晰**的角色：**只产出「单张标签的指令片段」，不碰打印机**。

- 前端：`../eams-ui`（Vite dev :3087，走 `/api` → 本服务 `/eams`）
- 打印工具：`../eams-print-server`（Python 桌面客户端，**与前端并列**的第二个打印发起端）
- 打印落地：**本机 TSC PrintServer**（默认 `ws://127.0.0.1:8888`）——由前端或工具去连，**本服务不连**

---

## 一、架构

```
前端 /api/*  ──►  eams-control :8087  /eams/*   ──►  MySQL 8（业务+参数）
                     │  │                 ├─►  Redis（token 会话 / bd_param 缓存 / 验证码计数）
                     │  │                 ├─►  MinIO :9090（附件）
                     │  │                 └─►  XXL-JOB（admin :8058，执行器 :9087，如每日折旧）
                     │  └─ 自研权限：注解 + 拦截器 + 切面（权限串如 asset:list）
                     └─ 标签打印：只产出指令片段 JSON（含最终版面坐标），不含 openport/closeport
```

包结构（**两套并行组织**，新代码按业务域放 `modules/`）：

| 位置 | 内容 |
|---|---|
| `modules/<域>/` | `entity` / `mapper` / `dto` / `vo`：asset、basic(Bd\*)、check、repair、scrap、transfer、stats、sys、todo |
| `controller/` `service/` | 19 个控制器 + 18 个服务：auth、file、health 等横切能力与部分聚合接口 |
| `common/` | `result`（`Result`/`PageResult`）、`enums`、`constant`、`model` |
| `config/` `aspect/` `annotation/` `interceptor/` `exception/` `utils/` `job/` | 配置、权限切面、操作日志注解、全局异常、工具、定时任务 |

技术栈：JDK **1.8**（强约束）· Spring Boot **2.7.18** · MyBatis 2.1.3 + PageHelper 5.1.10（**不是** MyBatis-Plus）· MySQL 8 · Redis(Lettuce) · MinIO 8.5 · XXL-JOB 2.5 · EasyExcel · Hutool。

配置：`src/main/resources/application.properties`（开发默认）+ `application-prod.properties`（`--spring.profiles.active=prod`，敏感值走 `${ENV:默认值}`）。
**业务参数不在配置文件里**，而在数据库表 `bd_param`（「基础数据 > 参数管理」页面维护）。

## 二、核心功能

- **认证授权**：登录换 token（Redis）、当前用户信息、菜单树、角色与权限串、操作日志（`@OperationLog`）。
- **基础数据**：部门、资产分类、字典、**参数 `bd_param`**（含标签打印的 `label.*` 共 30+ 项）。
- **资产台账**：列表/详情/履历历史、二维码数据源 `AssetQrcodeVO`、Excel 导入导出。
- **业务闭环**：调拨申请、维修、报废、盘点（任务/报告）、统计大屏数据、待办。
- **标签打印指令产出**（见下节）。
- **健康检查**：`GET /health`（浅）与 `GET /health/ready`（深：逐项探 MySQL/Redis，异常返回 503 与 `costMs`）。

## 三、标签打印：本服务只到这里为止

`service/LabelPrintService.java` 做的事：

1. 读参数：`bd_param` 的 `label.*`（`dpi/width_mm/height_mm/speed/density/sensor/gap_*/direction/qr_x/qr_cell/qr_fit_height/qr_ecc/qr_multiline/font_face/font_height/title/title_height/title_top/qr_text_gap/line_gap/max_batch/timeout_sec` …）。
2. 产出**单张标签的指令片段**（`LabelCommandItemVO.commands`），顺序固定：
   `clearbuffer → setup → DIRECTION → CODEPAGE UTF-8 → [标题 windowsfont] → QRCODE → [文字 windowsfont ×N] → printlabel 1,1`
   —— **不含 `openport_*` / `closeport`**（打印机由客户端决定，同一份指令可用不同打印机重放）。
3. 回传**最终生效版面坐标**（`LabelLayoutVO`：标题/二维码/每行文字的 x、y、字号、cell…），前端预览直接照抄，保证「预览即所打」。
4. 留痕：前端打印后回调写二维码履历。

对外接口（均在 `/asset` 下，权限 `asset:list`）：

| 接口 | 用途 |
|---|---|
| `GET /asset/label/params` | 回传当前生效的 `label.*` 参数（含 `wsUrl`、`ecc`、`maxBatch`、`timeoutSec` …） |
| `POST /asset/label/commands` | 入参 `items[{assetId, serialNo, qrText, qrModules?}]`，出参每项的 `commands` + `layout` |

版面与内容口径（**权威来源**）：

| 项 | 口径 |
|---|---|
| 右侧文字 | **3 项**：`资产编码` / `资产名称` / `所属部门`；**字段名一行 + 值一行**，值超宽**换行不截断**；空值 `-` |
| 二维码正文 | 由**前端**生成（本服务只做 TSPL 归一化：`\n` → `"; "`、双引号→单引号）；模块数由前端用 `qrcode` 库算出 `qrModules` 一并提交 |
| 标题 | 固定**顶部居中单行**；字号 `title_height`、顶端留白 `title_top`，过宽先缩字号再截断 |
| 二维码 | `QRCODE x,y,ECC,cell,A,0,M2,"…"`；`cell` 以参数为**上限**并按正文区高度自动封顶（绝不溢出） |
| 静区 | `qr_x` 与 `qr_text_gap` 同时是静区；低于 `4 × cell` 只记 warn，**不擅自替用户改值** |

## 四、与前端、打印工具的关系与约束

| 关系 | 事实 | 约束 |
|---|---|---|
| 前端 → 本服务 | `/api/*` →（dev 代理 / nginx 重写）`/eams/*`；`Authorization: Bearer`；统一 `Result{code,message,data}`，前端直接拿 `data` | Controller **只用 GET/POST**；分页 `page/size` → `{total,list}`；数组参数 `arr.join(',')` |
| 本服务 → 打印服务 | **没有任何连接** | 打印落地由客户端负责；本服务不得引入打印相关 IO/依赖 |
| 本服务 ⇄ 打印工具 | **不通信、不共享进程**，只共享**指令契约** | 工具的 `app/webcompat.py` 是本类 `buildItem()` 的**逐条移植** ⇒ **改版面/内容/指令序列必须两侧同步**；契约以工具侧 `docs/PROTOCOL.md` §3.1/§5 为对照文档 |
| 内容口径单一来源 | 二维码 9 项在 `eams-ui/src/utils/qrcodeContent.ts`；右侧 3 项在本类 `LINE_LABELS` | 改字段清单要同时改：前端 `FIELD_ORDER` → 本类 `LINE_LABELS` → 工具 `app/model.py` 的两个常量 |
| 两处刻意差异 | 只在工具侧：标题按**粗体**下发（`style=2`）、`DIRECTION` 默认 **1** | 不要"顺手对齐"回去；已在工具 PROTOCOL §3.1 标注 |
| 参数分叉 | Web 侧参数在本服务 `bd_param.label.*`；工具用自己的 `config.json`（`print` 段 + 每打印机 `profiles`），默认值对齐但**独立维护** | 两边改参数互不影响；现场以各自界面为准 |
| 版本号 | `eams.app-version`（application.properties）= pom `<version>` = `eams-ui/package.json` | **三处必须同步** |

## 五、开发与构建

```bash
mvn spring-boot:run                 # :8087 /eams
mvn clean package                   # → target/eams-control.jar
java -jar target/eams-control.jar --spring.profiles.active=prod
```

启动依赖顺序：MySQL(3306) → Redis(6379) → MinIO(9090) → XXL-JOB admin(8058) → 本服务(8087)；前端 dev 代理指向 8087。

数据库变更约定（`src/main/resources/db/`）：

- `init.sql`：全量建表 + 参数种子（新增参数必须同时改这里）。
- `alter/YYYY-MM-DD_NN_简短描述.sql`：**当天序号从 01 起、按文件名字典序执行、必须幂等**（MySQL 8 没有 `ADD COLUMN IF NOT EXISTS`，用 `information_schema`+`PREPARE` 或 `ON DUPLICATE KEY UPDATE`）；禁止 `DROP DATABASE` / `TRUNCATE` 生产表；每批改动同步写 `CHANGELOG.md`。

## 六、目录速查

```
src/main/java/com/lssjzmn/eams/
├── EamsApplication.java
├── modules/{asset,basic,check,repair,scrap,transfer,stats,sys,todo}/…   # 按业务域
├── controller/ service/ dto/ vo/                                        # 聚合接口与横切能力
├── common/{result,enums,constant,model}/
├── config/ aspect/ annotation/ interceptor/ exception/ utils/ job/
└── service/LabelPrintService.java    ★ 标签指令片段的唯一产出口
src/main/resources/
├── application.properties / application-prod.properties / logback-spring.xml
└── db/{init.sql, alter/}
```

## 七、文档索引

| 文档 | 内容 |
|---|---|
| `CHANGELOG.md` | 后端变更记录（含口径与回退历史） |
| `deploy/DEPLOY.md` | 部署步骤与检查清单 |
| `src/main/resources/db/alter/README.md` | DDL 增量脚本约定 |
| `../eams-ui/README.md` | 前端架构与接口约定 |
| `../eams-print-server/README.md` | 打印工具（并列的第二个打印发起端） |
| `../标签打印方案_TSC-PrintServer.md` | 标签打印方案（跨三者的总体设计） |