# 交易市场管理 — 技术方案

> 依据：同目录 `交易市场管理功能需求.md`。交易市场 **CRUD** + 单图照片 + **逻辑删除**；列表**名称模糊**、**运营状态精确**筛选；**不含**地图标点。

---

## 1. 技术架构

| 项 | 说明 |
| --- | --- |
| **后端** | RuoYi **v3.9.2**（**springboot2** 分支）：JDK 8、Spring Boot 2.x、Spring MVC、MyBatis、Druid |
| **数据库** | MySQL **5.7.39**，InnoDB，`utf8mb4` |
| **前端** | 若依 Vue2；照片上传复用 `POST /common/upload`（本方案不展开页面） |

**分层**：`Controller` → `Service`（`TradeMarketValidation`、删旧照片）→ `Mapper`/XML → `domain`。

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

**业务摘要**

| 场景 | 行为 |
| --- | --- |
| 新增 | 校验必填；`operate_status` 缺省 `1`（正常）；`del_flag=0` |
| 修改 | 全字段可改；换照片删旧 `photo_file_path` |
| 列表/详情 | 仅 `del_flag=0`；排序 `create_time DESC, id DESC` |
| 列表筛选 | `market_name` 模糊；`operate_status` 精确 |
| 删除 | `del_flag=2`；删照片文件；有关联时 `ServiceException` |

---

## 2. 数据库设计

### 2.1 表 `biz_trade_market`（交易市场）

| 字段 | 类型 | 非空 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| `id` | `bigint(20)` | Y | 自增 | 主键 |
| `market_name` | `varchar(32)` | Y | — | 市场名称（**1～10** 字） |
| `detail_address` | `varchar(200)` | Y | — | 详细地址（**1～200** 字） |
| `person_in_charge` | `varchar(32)` | Y | — | 负责人（**1～10** 字） |
| `contact_phone` | `varchar(20)` | Y | — | 联系方式（手机号） |
| `operate_status` | `tinyint(4)` | Y | `1` | `1` 正常 `2` 停业 `3` 注销 |
| `photo_file_url` | `varchar(512)` | N | NULL | 照片访问 URL |
| `photo_file_path` | `varchar(512)` | N | NULL | 照片存储路径（`/profile/...`） |
| `del_flag` | `char(1)` | Y | `'0'` | `0` 存在 `2` 删除 |
| `create_by` / `create_time` / `update_by` / `update_time` | 若依惯例 | — | — | 审计 |

**索引**：`PRIMARY KEY (id)`；`KEY idx_market_name (market_name)`；`KEY idx_operate_status (operate_status)`；`KEY idx_create_time (create_time)`；`KEY idx_del_flag (del_flag)`。

> **名称唯一**：`market_name` 在 `del_flag=0` 范围内由 Service 校验唯一（不设库级唯一索引，避免逻辑删除后无法复用名称）。

### 2.2 DDL（MySQL 5.7）

```sql
CREATE TABLE `biz_trade_market` (
  `id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT '主键',
  `market_name` varchar(32) NOT NULL COMMENT '市场名称',
  `detail_address` varchar(200) NOT NULL COMMENT '详细地址',
  `person_in_charge` varchar(32) NOT NULL COMMENT '负责人',
  `contact_phone` varchar(20) NOT NULL COMMENT '联系方式',
  `operate_status` tinyint(4) NOT NULL DEFAULT '1' COMMENT '1正常 2停业 3注销',
  `photo_file_url` varchar(512) DEFAULT NULL COMMENT '照片URL',
  `photo_file_path` varchar(512) 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`),
  KEY `idx_market_name` (`market_name`),
  KEY `idx_operate_status` (`operate_status`),
  KEY `idx_create_time` (`create_time`),
  KEY `idx_del_flag` (`del_flag`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='交易市场';
```

### 2.3 枚举

**运营状态 `operate_status`**

| 值 | 标签 |
| --- | --- |
| 1 | 正常 |
| 2 | 停业 |
| 3 | 注销 |

**删除标记 `del_flag`**

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

---

## 3. 接口设计

**统一响应**：`AjaxResult` / `TableDataInfo`。

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

**Base Path**：`/livestock/tradeMarket`

| # | 说明 | Method | URI | 权限 |
| --- | --- | --- | --- | --- |
| 3.1 | 分页列表 | GET | `/livestock/tradeMarket/list` | `list` |
| 3.2 | 详情 | GET | `/livestock/tradeMarket/{id}` | `query` |
| 3.3 | 新增 | POST | `/livestock/tradeMarket` | `add` |
| 3.4 | 修改 | PUT | `/livestock/tradeMarket` | `edit` |
| 3.5 | 删除 | DELETE | `/livestock/tradeMarket/{ids}` | `remove` |

#### 3.1.1 列表 Query

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `pageNum` / `pageSize` | int | N | 默认 `1` / `20` |
| `marketName` | string | N | 名称**模糊**：`market_name LIKE %value%` |
| `operateStatus` | int | N | **精确**：`1` / `2` / `3` |

**列表行扩展（驼峰）**：`operateStatusName`（字典或 Service 填充）。

**排序**：`create_time DESC, id DESC`。

#### 3.2.1 详情 `data`

`id`、`marketName`、`detailAddress`、`personInCharge`、`contactPhone`、`operateStatus`、`operateStatusName`、`photoFileUrl`、`photoFilePath`、审计字段。

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

| 字段 | 新增 | 修改 | 说明 |
| --- | --- | --- | --- |
| `id` | — | Y | 主键 |
| `marketName` | Y | Y | 1～10 字，trim |
| `detailAddress` | Y | Y | 1～200 字 |
| `personInCharge` | Y | Y | 1～10 字 |
| `contactPhone` | Y | Y | 大陆手机号 |
| `operateStatus` | Y | Y | `1` / `2` / `3`；新增缺省 `1` |
| `photoFileUrl` / `photoFilePath` | N | N | 成对；可空表示无图 |

#### 3.4 照片约定

1. 前端先调 `POST /common/upload`，将返回的 `url`、`fileName` 写入 `photoFileUrl`、`photoFilePath`。  
2. 修改替换或逻辑删除时，Service 删除旧 `photo_file_path` 物理文件（路径校验与项目一致）。

#### 3.5 服务端校验（`TradeMarketValidation`）

| 项 | 规则 |
| --- | --- |
| 名称 | trim 后 1～10 字；未删除记录内**名称唯一** |
| 详细地址 | trim 后 1～200 字 |
| 负责人 | trim 后 1～10 字 |
| 手机 | 项目统一手机号规则 |
| 运营状态 | ∈ {1, 2, 3} |
| 照片 | 可空；后缀 `jpg`/`jpeg`/`png`；≤10MB；url/path 成对 |
| 删除 | 未删；`TradeMarketReferenceChecker.hasReference(id)` 为 false（本期可占位 `false`） |

#### 3.6 Mapper 约定

- 条件均带 `del_flag='0'`。  
- 模糊：`AND market_name LIKE CONCAT('%', #{marketName}, '%')`  
- 精确：`AND operate_status = #{operateStatus}`（非空时）  
- 逻辑删除：`UPDATE … SET del_flag='2' WHERE id=? AND del_flag='0'`。

---

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

| 类型 | 名称 | 权限标识 |
| --- | --- | --- |
| 菜单 | 交易市场管理 | `livestock:tradeMarket:list` |
| 按钮 | 查询 | `livestock:tradeMarket:query` |
| 按钮 | 新增 | `livestock:tradeMarket:add` |
| 按钮 | 修改 | `livestock:tradeMarket:edit` |
| 按钮 | 删除 | `livestock:tradeMarket:remove` |

组件路径：`livestock/tradeMarket/index`（「畜牧流通资源管理」目录下）。

---

## 5. 模块路径对照

| 项 | 检疫站 | 交易市场（本模块） | 交易市场平台·栏位 |
| --- | --- | --- | --- |
| 表名 | `biz_quarantine_station` | `biz_trade_market` | `biz_market_stall` 等 |
| Base Path | `/livestock/quarantineStation` | `/livestock/tradeMarket` | `/tradeMarket/marketStall` |
| 名称字段 | `station_name` | `market_name` | 自动编号 |
| 权限前缀 | `livestock:quarantineStation:*` | `livestock:tradeMarket:*` | `tradeMarket:marketStall:*` |

> **命名说明**：畜牧流通主档使用 `/livestock/tradeMarket`，与交易市场平台 `/tradeMarket/*` 路径前缀区分，避免路由与权限混用。

---

## 6. 交付清单

- [ ] `sql/biz_trade_market.sql`、菜单权限 SQL  
- [ ] `BizTradeMarket`、Mapper/XML、Service、Controller  
- [ ] `TradeMarketValidation`、照片文件清理  
- [ ] 单元测试（校验、名称唯一、模糊 SQL）  
- [ ] MockMvc（list、CRUD、删除有关联）

---

## 7. 修订记录

| 版本 | 说明 |
| --- | --- |
| 1.0 | 初稿：`biz_trade_market`；CRUD+逻辑删除+单图；`/livestock/tradeMarket`；名称模糊+运营状态精确 |
