project_husbandry_back/lab-service/lab-lims/AGENTS.md

# lab-lims — LIMS 核心模块

**路径:** `project_husbandry_back/lab-service/lab-lims/`
**包名:** `org.springblade.lims.*`
**规模:** 后端最大模块（约 250+ Java 源文件）

## 包结构

```
org.springblade.lims/
├── api/              # 内部 API DTO（3 个文件）
├── config/           # 模块级配置（2 个文件）
├── controller/       # REST 接口（47 个控制器）
├── demo/             # 演示/测试桩（2 个文件）
├── excel/            # Excel 导出处理器（13 个文件）
├── feign/            # Feign 客户端实现（1 个文件）
├── mapper/           # MyBatis-Plus Mapper（46 个文件）
├── Scheduled/        # 定时任务（1 个文件）
├── service/          # 业务逻辑（92 个文件）
├── tools/            # 工具类（1 个文件）
└── utils/            # 工具类（15 个文件）
```

## 领域控制器分类

| 领域 | 关键控制器 |
|------|-----------|
| 样品/委托 | Entrust、HandleSample、RetentionSample、Simple、SimpleRel、SimpleSet、LsReservedSample |
| 检测/检验 | Examine、ExamineItem、ExamineResult、ExamineTask、ExamineBasis、SimpleDoExamineLog |
| 安全/危化品 | DangerApply、DangerApplyLog、DangerMoveLog、DangerRecoveryLog、DangerStorage |
| 仪器设备 | Instrument、InstrumentMaintLog、InstrumentUseLog、TemperatureControl |
| 试剂/实验动物 | Reagent、ReagentUseLog、ExperimentalAnimal |
| 质量/标准 | QualityStandard、DetermineFormula |
| 合同/维修 | Contract、ContractSample、RepairApplication、ScrapApplication |
| 环境 | EnvDict、EnvLog、DisinfectLog、SewageDischargeLog |
| 模板/蓝图 | Template、TaskBlueprint、LsTemplateLog |
| 日志/审计 | LsAuditTrailLog、LsEventLog、LsTemperatureHumidityLog |
| 统计/大屏 | LsDataStatistic、LargeScreen |

## 约定规范

- **CRUD**: 标准 SpringBlade 模式 controller → service（接口）→ service/impl → mapper
- **Excel**: 导出处理器放在 `excel/` 包下，每个实体对应一个
- **Mapper**: MyBatis-Plus BaseMapper 扩展，XML 映射文件在 resources 中
- **内部 API**: DTO 放在 `api/` 包中，仅供模块内部使用
- **定时任务**: `Scheduled` 包存放 @Scheduled 任务（不在 service/ 中）

## 反模式

- 无单元测试（仅有 `demo/` 空壳）
- `Scheduled` 包只有单个类 — 功能可能不完整

---

## 检验业务流程（6 阶段）

```
委托登记 → 接样 → 任务分配 → 领取与检测 → 审核与报告 → 留样处理
```

### 阶段 1: 委托登记
- **控制器:** `EntrustController` (`/entrust`)
- **实体:** `f_entrust_main`（Entrust）
- **操作:** 创建委托单，填写送检单位、样品名称数量、养殖情况、免疫情况、接样日期
- **类型:** `entrustType` = 1（委托单）/ 2（合同单）
- **前端页面:** `sampleRegister.vue`

### 阶段 2: 接样
- **控制器:** `SimpleController` (`/simple`)
- **实体:** `f_entrust_simple`（Simple）
- **操作:** 确认样品、分配检测编号（`experieNum`）、设置留样/实验样数量
- **核心字段:** `samplingDate`（接样日期）、`simpleState`（样品状态）、`isReagent`（是否留样）
- **前端页面:** `sampleRecive.vue` / `receive.vue`

### 阶段 3: 任务分配
- **控制器:** `TaskBlueprint`（任务书）+ `ETask`（子任务）
- **实体:** `f_task_blueprint` / `f_etask`
- **流程:** 委托单 → 生成任务书 → 按科室拆分子任务 → 每个子任务包含对应检验项
- **科室流转:** ETask.flowTo 指向下游科室，flowTime 记录流转日期
- **ETask.status:** 0=待领取 → 1=待检测 → 流转

### 阶段 4: 领取与检测
- **控制器:** `ExamineController` (`/examine`)
- **实体:** `f_examine`（Examine）+ `f_examine_result`（ExamineResult）
- **流程:**
  1. 实验员领取任务 → `receiveSubmit()` → `isDistribute=1`, `lockBy` 锁定人
  2. 输入检测结果 → 原始记录、温湿度、仪器、试剂、图片
  3. 支持多批次检测（`ExamineResult.batch`）
  4. 支持撤回领取（`receiveRevoke()`）
  5. 提交后更新样品所在位置（`simpleCurrPlace`）
- **isFinished:** "-1"=待检测 → "1"=已完成
- **前端页面:** `experimentItem.vue` / `testMethod.vue` / `testBasis.vue`

### 阶段 5: 审核与报告
- **控制器:** `ExamineController` + `reportlist.vue`
- **操作:** 检测完成 → 提交审核（status=3）→ 审核通过（status=4）/ 作废（status=-1）
- **审核字段:** Entrust 记录 `organizationBy`（编制人）、`verifyBy`（审核人）、`approvalBy`（审批人）
- **报告:** `isGenreport` 控制是否生成报告
- **前端页面:** 审核相关页面 / `reportlist.vue`

### 阶段 6: 留样处理
- **控制器:** `HandleSampleController` (`/handleSample`)
- **实体:** `HandleSample`
- **操作:** 留样销毁申请与审批、样品处理登记表下载
- **打印:** `simpleHandlePrint()`（销毁申请表）、`simpleRegisterPrint()`（处理登记表）
- **前端页面:** `RetentionSample.vue` / `sampleDispose.vue`

---

## 状态机定义

### Entrust.entrustStatus

| 状态值 | 含义 | 触发操作 |
|---|---|---|
| `(新建)` | 委托单创建 | 提交委托登记 |
| `-0.5` | 待重订 | 某条检验被作废时自动触发 |
| `000` | 待领取 | 任务分配后等待领取 |
| `111` | 待检测 | 实验员已领取任务 |
| `2.1` | 流转中 | 科室间流转 |
| `3` | 待审核 | 检测完成提交审核 |
| `4` | 审核通过 | 审核通过 |
| `7` / `8` | 已完成 | 流程结束 |
| `-1` | 作废 | 审核作废 |

### Examine 字段状态

| 字段 | 值含义 |
|---|---|
| `isDistribute` | 0=未分配, 1=已分配 |
| `isFinished` | "-1"=待检测, "0"=未完成, "1"=已完成 |
| `status` | -1=作废, 0=正常, 1=审核通过 |
| `examineStatus` | 自定义检验状态 |

### ETask.status

| 值 | 含义 |
|---|---|
| 0 | 待领取 |
| 1 | 待检测 |
| (其他) | 流转中 / 已完成 |

---

## 数据模型关系

```
Entrust ──→ Simple ──→ ExamineItem
(f_entrust_main)  │        (t_examine_item)
                  │            ├── ExamineWay (t_examine_way)
                  │            └── ExamineBasis (t_examine_basis)
                  │
                  └──→ TaskBlueprint ──→ ETask ──→ Examine ──→ ExamineResult
                       (f_task_blueprint)  (f_etask)  (f_examine)  (f_examine_result)
                                             ↑
                                         科室流转
                                        flowTo → 下游科室
```

### 关键约束
- `Examine.examineItemId` → `ExamineItem.id`（检测项目）
- `Examine.examineWayId` → `ExamineWay.id`（检测方法）
- `Examine.examineBasisId` → `ExamineBasis.id`（检测依据）
- `Examine.eTaskId` → `ETask.id`（所属子任务）
- `Examine.entrustId` → `Entrust.id`（所属委托单）
- `ExamineResult.examineId` → `Examine.id`（所属检验）
- `ETask.taskBlueprintId` → `TaskBlueprint.id`（所属任务书）
- `TaskBlueprint.entrustId` → `Entrust.id`（所属委托单）
- `Simple.entrustId` → `Entrust.id`（所属委托单）

---

## 科室流转机制

核心实现在 `ExamineServiceImpl.updateSimpleCurrPlace()`：

1. 当前科室检测完成 → 通过 `ETask.flowTo` 找到下游科室
2. 更新当前科室所有检验的 `simpleCurrPlace` 为科室名称
3. 更新下游科室对应检验记录，将 `simpleCurrPlace` 设置为当前科室（物理流转到下游）
4. 记录 `ETask.flowTime` = 当前时间

---

## 业务逻辑要点

- **状态驱动流程:** 每一步修改对应字段，无统一状态机，状态值在 controller/service 中硬编码字符串比较
- **双状态体系:** `Examine.status` 与 `Entrust.entrustStatus` 是两套独立状态，修改时需联动 (如 `Examine` 作废时需回写 `Entrust.entrustStatus=-0.5`)
- **领取锁:** `Examine.lockBy` 记录锁定人，防止多人同时领取同一检验
- **支持合同单:** `entrustType=2` 时关联 `Contract` 和 `ContractSample`
- **批量操作:** 新增样品 (`insertSimples`)、修改检验 (`updateExamineBatch`) 等接口支持批量

---

## 实体与数据库表映射

| 实体类 | 表名 | 说明 |
|---|---|---|
| `Entrust` | `f_entrust_main` | 委托单主表 |
| `Simple` | `f_entrust_simple` | 样品表 |
| `Examine` | `f_examine` | 检验记录 |
| `ExamineResult` | `f_examine_result` | 检验结果 |
| `ExamineItem` | `t_examine_item` | 检验项目字典 |
| `ExamineWay` | `t_examine_way` | 检验方法字典 |
| `ExamineBasis` | `t_examine_basis` | 检验依据字典 |
| `ETask` | `f_etask` | 子任务（按科室拆分） |
| `TaskBlueprint` | `f_task_blueprint` | 任务书 |
| `HandleSample` | `f_handle_sample` | 留样处理 |