# 隔离圈位管理 — 技术方案

> 依据：同目录 `隔离圈位管理功能需求.md`。圈位台账 **CRUD** + **逻辑删除** + **编号自动生成（2 位）** + **全局默认隔离天数（单条配置）**；列表圈位编号 **模糊**筛选。

---

## 1. 技术架构

| 项 | 说明 |
| --- | --- |
| **后端** | RuoYi **v3.9.2**（**springboot2** 分支）：JDK 8、Spring Boot 2.x、Spring MVC、MyBatis、Druid |
| **数据库** | MySQL **5.7.39**，InnoDB，`utf8mb4` |
| **前端** | 若依 Vue2；字段 **小驼峰**（本方案不展开页面） |

**分层**：`Controller` → `Service`（`IsolationPenValidation`、`IsolationSettingValidation`、**编号生成**）→ `Mapper`/XML → `domain`。

**代码包（建议）**：`com.ruoyi.web.modules.trademarket`

**业务摘要**

| 场景 | 行为 |
| --- | --- |
| 新增圈位 | 校验通过后 `PenCodeGenerator` 分配 `pen_code`（`01`～`99`）；`del_flag=0` |
| 修改圈位 | **不可改** `pen_code`；仅更新 `remark` |
| 列表/详情 | 仅 `del_flag=0`；排序 `pen_code ASC, id ASC` |
| 列表筛选 | `pen_code` **模糊** `LIKE %keyword%` |
| 删除圈位 | `del_flag=2`；下游引用时 `ServiceException` |
| 隔离天数配置 | 表 `biz_isolation_setting` **仅保留一行**；无记录则 `INSERT`，有则 `UPDATE` |

---

## 2. 数据库设计

### 2.1 表 `biz_isolation_pen`（隔离圈位台账）

| 字段 | 类型 | 非空 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| `id` | `bigint(20)` | Y | 自增 | 主键 |
| `pen_code` | `char(2)` | Y | — | 圈位编号 `01`～`99`，**全局唯一** |
| `remark` | `varchar(50)` | N | NULL | 圈位备注（≤50 字） |
| `del_flag` | `char(1)` | Y | `'0'` | `0` 存在 `2` 删除 |
| `create_by` / `create_time` / `update_by` / `update_time` | 若依惯例 | — | — | 审计 |

**索引**：`PRIMARY KEY (id)`；`UNIQUE KEY uk_pen_code (pen_code)`；`KEY idx_del_flag (del_flag)`。

### 2.2 表 `biz_isolation_setting`（默认隔离天数，单行）

| 字段 | 类型 | 非空 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| `id` | `bigint(20)` | Y | `1` | 主键；**固定为 1**，全表仅一行 |
| `default_days` | `int(11)` | Y | — | 默认隔离天数，**1～3650** |
| `remark` | `varchar(50)` | N | NULL | 配置备注（≤50 字） |
| `create_by` / `create_time` / `update_by` / `update_time` | 若依惯例 | — | — | 审计 |

**索引**：`PRIMARY KEY (id)`。

> **实现约定**：`IsolationSettingService.save` 对 `id=1` 执行 `INSERT … ON DUPLICATE KEY UPDATE` 或先 `selectById(1)` 再分支插入/更新，禁止出现 `id>1` 的生效配置。

### 2.3 DDL（MySQL 5.7）

```sql
CREATE TABLE `biz_isolation_pen` (
  `id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT '主键',
  `pen_code` char(2) NOT NULL COMMENT '圈位编号01-99',
  `remark` varchar(50) DEFAULT NULL COMMENT '圈位备注',
  `del_flag` char(1) NOT NULL DEFAULT '0' COMMENT '0存在 2删除',
  `create_by` varchar(64) DEFAULT '' COMMENT '创建者',
  `create_time` datetime DEFAULT NULL COMMENT '创建时间',
  `update_by` varchar(64) DEFAULT '' COMMENT '更新者',
  `update_time` datetime DEFAULT NULL COMMENT '更新时间',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_pen_code` (`pen_code`),
  KEY `idx_del_flag` (`del_flag`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='隔离圈位';

CREATE TABLE `biz_isolation_setting` (
  `id` bigint(20) NOT NULL DEFAULT 1 COMMENT '固定主键1',
  `default_days` int(11) NOT NULL COMMENT '默认隔离天数',
  `remark` varchar(50) DEFAULT NULL COMMENT '配置备注',
  `create_by` varchar(64) DEFAULT '' COMMENT '创建者',
  `create_time` datetime DEFAULT NULL COMMENT '创建时间',
  `update_by` varchar(64) DEFAULT '' COMMENT '更新者',
  `update_time` datetime DEFAULT NULL COMMENT '更新时间',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='默认隔离天数配置';
```

### 2.4 枚举

**删除标记 `del_flag`（圈位表）**

| 值 | 含义 |
| --- | --- |
| 0 | 正常 |
| 2 | 已逻辑删除 |

### 2.5 编号生成（`PenCodeGenerator`）

与承销商模块一致：在 `del_flag=0` 范围内取 `MAX(pen_code)` + 1，格式 `%02d`；上限 `99`；与插入**同一事务**，避免并发重复。

---

## 3. 接口设计

**统一响应**：`AjaxResult` / `TableDataInfo`（`code`、`msg`、`data` / `rows`、`total`）。

**权限标识**：`tradeMarket:isolationPen:list|query|add|edit|remove|config`

**Base Path**：`/tradeMarket/isolationPen`

### 3.1 圈位接口

| # | 说明 | Method | URI | 权限 |
| --- | --- | --- | --- | --- |
| 3.1.1 | 分页列表 | GET | `/tradeMarket/isolationPen/list` | `list` |
| 3.1.2 | 详情 | GET | `/tradeMarket/isolationPen/{id}` | `query` |
| 3.1.3 | 新增 | POST | `/tradeMarket/isolationPen` | `add` |
| 3.1.4 | 修改 | PUT | `/tradeMarket/isolationPen` | `edit` |
| 3.1.5 | 删除 | DELETE | `/tradeMarket/isolationPen/{ids}` | `remove` |

#### 列表 Query

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `pageNum` / `pageSize` | int | N | 默认 `1` / `20` |
| `penCode` | string | N | 圈位编号**模糊**：`pen_code LIKE %value%` |

**排序**：`pen_code ASC, id ASC`。

#### 详情 `data`（驼峰）

`id`、`penCode`、`remark`、审计字段。

#### 新增 / 修改 Body（驼峰）

| 字段 | 新增 | 修改 | 说明 |
| --- | --- | --- | --- |
| `id` | — | Y | 主键 |
| `penCode` | — | — | **禁止传入**；仅响应带回 |
| `remark` | N | N | ≤50 字，trim；空串存 `NULL` |

#### 圈位校验（`IsolationPenValidation`）

| 项 | 规则 |
| --- | --- |
| 备注 | 有内容时 1～50 字 |
| 修改 | 禁止改 `pen_code`；记录存在且 `del_flag=0` |
| 删除 | 未删；`IsolationPenReferenceChecker.hasReference(id)` 为 false（本期可占位 `false`） |

#### 删除

- 单条：`DELETE /tradeMarket/isolationPen/{ids}`，传一个 id。  
- `UPDATE … SET del_flag='2' WHERE id=? AND del_flag='0'`。

### 3.2 默认隔离天数接口

| # | 说明 | Method | URI | 权限 |
| --- | --- | --- | --- | --- |
| 3.2.1 | 查询当前配置 | GET | `/tradeMarket/isolationPen/setting` | `config` |
| 3.2.2 | 保存配置 | PUT | `/tradeMarket/isolationPen/setting` | `config` |

#### 查询 `data`（驼峰）

| 字段 | 说明 |
| --- | --- |
| `defaultDays` | 默认隔离天数；**无记录时** `data` 为 `null` 或各字段为空（前端按未配置处理） |
| `remark` | 配置备注 |
| `updateBy` / `updateTime` | 最近修改审计（有记录时返回） |

#### 保存 Body（驼峰）

| 字段 | 必填 | 说明 |
| --- | --- | --- |
| `defaultDays` | Y | 整数，`1～3650` |
| `remark` | N | ≤50 字 |

#### 配置校验（`IsolationSettingValidation`）

| 项 | 规则 |
| --- | --- |
| `defaultDays` | 非空、整数、∈ [1, 3650] |
| `remark` | 有内容时 ≤50 字 |

> **说明**：不提供删除配置接口；仅覆盖更新。

### 3.3 Mapper 约定（圈位）

- 查询条件均带 `del_flag='0'`。  
- 模糊：`AND pen_code LIKE CONCAT('%', #{penCode}, '%')`。

---

## 4. 菜单与权限（示例）

| 类型 | 名称 | 权限标识 |
| --- | --- | --- |
| 菜单 | 隔离圈位管理 | `tradeMarket:isolationPen:list` |
| 按钮 | 查询 | `tradeMarket:isolationPen:query` |
| 按钮 | 新增 | `tradeMarket:isolationPen:add` |
| 按钮 | 修改 | `tradeMarket:isolationPen:edit` |
| 按钮 | 删除 | `tradeMarket:isolationPen:remove` |
| 按钮 | 设置隔离天数 | `tradeMarket:isolationPen:config` |

组件路径：`tradeMarket/isolationPen/index`（「交易市场平台」目录下）。

---

## 5. 与承销商模块对照

| 项 | 承销商 | 隔离圈位 |
| --- | --- | --- |
| 主表 | `biz_distributor` | `biz_isolation_pen` |
| 扩展 | — | `biz_isolation_setting`（单行） |
| 列表筛选 | 编号、名称模糊 | 仅**编号模糊** |
| 特色能力 | 销售去向 | **默认隔离天数** 独立接口 |
| Base Path | `/tradeMarket/distributor` | `/tradeMarket/isolationPen` |

---

## 6. 交付清单

- [ ] `sql/biz_isolation_pen.sql`、`sql/biz_isolation_setting.sql`、菜单权限 SQL  
- [ ] `BizIsolationPen`、`BizIsolationSetting`、Mapper/XML、Service、Controller  
- [ ] `PenCodeGenerator`、`IsolationPenValidation`、`IsolationSettingValidation`  
- [ ] 单元测试（编号生成、天数范围、模糊 SQL）  
- [ ] MockMvc（圈位 CRUD、setting 读写）

---

## 7. 修订记录

| 版本 | 说明 |
| --- | --- |
| 1.0 | 初稿：`biz_isolation_pen` + `biz_isolation_setting`；CRUD + 逻辑删除；2 位编号；`/tradeMarket/isolationPen` 及 `/setting` |