ccdi/openspec/changes/add-intermediary-blacklist/design.md

# Design: 中介人员黑名单管理模块

## 数据库设计

### 表：dpc_intermediary_blacklist

中介人员/机构黑名单主表。

```sql
CREATE TABLE `dpc_intermediary_blacklist` (
  `intermediary_id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '中介ID',
  `name` VARCHAR(100) NOT NULL COMMENT '姓名/机构名称',
  `certificate_no` VARCHAR(50) DEFAULT NULL COMMENT '证件号',
  `intermediary_type` CHAR(1) NOT NULL DEFAULT '1' COMMENT '中介类型（1个人 2机构）',
  `status` CHAR(1) NOT NULL DEFAULT '0' COMMENT '状态（0正常 1停用）',
  `remark` VARCHAR(500) 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 (`intermediary_id`),
  KEY `idx_name` (`name`),
  KEY `idx_certificate_no` (`certificate_no`),
  KEY `idx_intermediary_type` (`intermediary_type`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='中介人员黑名单表';
```

### 字段说明

| 字段名 | 类型 | 说明 | 必填 | 默认值 |
|-------|------|------|-----|-------|
| intermediary_id | BIGINT | 中介ID（主键） | 是 | 自增 |
| name | VARCHAR(100) | 姓名/机构名称 | 是 | - |
| certificate_no | VARCHAR(50) | 证件号 | 否 | NULL |
| intermediary_type | CHAR(1) | 中介类型（1个人 2机构） | 是 | '1' |
| status | CHAR(1) | 状态（0正常 1停用） | 是 | '0' |
| remark | VARCHAR(500) | 备注 | 否 | NULL |
| create_by | VARCHAR(64) | 创建者 | 是 | - |
| create_time | DATETIME | 创建时间 | 是 | - |
| update_by | VARCHAR(64) | 更新者 | 否 | '' |
| update_time | DATETIME | 更新时间 | 否 | NULL |

### 索引设计

- 主键索引：`intermediary_id`
- 普通索引：`name`（支持按名称搜索）
- 普通索引：`certificate_no`（支持按证件号精确匹配）
- 普通索引：`intermediary_type`（支持按类型筛选）

## 后端设计

### 模块结构

```
ruoyi-dpc/
├── src/main/java/com/ruoyi/dpc/
│   ├── controller/
│   │   └── DpcIntermediaryBlacklistController.java
│   ├── domain/
│   │   ├── DpcIntermediaryBlacklist.java
│   │   ├── dto/
│   │   │   ├── DpcIntermediaryBlacklistAddDTO.java
│   │   │   ├── DpcIntermediaryBlacklistEditDTO.java
│   │   │   └── DpcIntermediaryBlacklistQueryDTO.java
│   │   └── vo/
│   │       └── DpcIntermediaryBlacklistVO.java
│   ├── mapper/
│   │   └── DpcIntermediaryBlacklistMapper.java
│   └── service/
│       ├── IDpcIntermediaryBlacklistService.java
│       └── impl/
│           └── DpcIntermediaryBlacklistServiceImpl.java
└── src/main/resources/mapper/dpc/
    └── DpcIntermediaryBlacklistMapper.xml
```

### Controller 层设计

**DpcIntermediaryBlacklistController**

```java
@RestController
@RequestMapping("/dpc/intermediary")
public class DpcIntermediaryBlacklistController extends BaseController {

    /**
     * 查询中介黑名单列表
     */
    @PreAuthorize("@ss.hasPermi('dpc:intermediary:list')")
    @GetMapping("/list")
    public TableDataInfo list(DpcIntermediaryBlacklistQueryDTO queryDTO) {
        // 分页查询逻辑
    }

    /**
     * 导出中介黑名单列表
     */
    @PreAuthorize("@ss.hasPermi('dpc:intermediary:export')")
    @Log(title = "中介黑名单", businessType = BusinessType.EXPORT)
    @PostMapping("/export")
    public void export(HttpServletResponse response, DpcIntermediaryBlacklistQueryDTO queryDTO) {
        // 导出逻辑
    }

    /**
     * 获取中介黑名单详细信息
     */
    @PreAuthorize("@ss.hasPermi('dpc:intermediary:query')")
    @GetMapping(value = "/{intermediaryId}")
    public AjaxResult getInfo(@PathVariable Long intermediaryId) {
        // 查询详情逻辑
    }

    /**
     * 新增中介黑名单
     */
    @PreAuthorize("@ss.hasPermi('dpc:intermediary:add')")
    @Log(title = "中介黑名单", businessType = BusinessType.INSERT)
    @PostMapping
    public AjaxResult add(@Validated @RequestBody DpcIntermediaryBlacklistAddDTO addDTO) {
        // 新增逻辑
    }

    /**
     * 修改中介黑名单
     */
    @PreAuthorize("@ss.hasPermi('dpc:intermediary:edit')")
    @Log(title = "中介黑名单", businessType = BusinessType.UPDATE)
    @PutMapping
    public AjaxResult edit(@Validated @RequestBody DpcIntermediaryBlacklistEditDTO editDTO) {
        // 修改逻辑
    }

    /**
     * 删除中介黑名单
     */
    @PreAuthorize("@ss.hasPermi('dpc:intermediary:remove')")
    @Log(title = "中介黑名单", businessType = BusinessType.DELETE)
    @DeleteMapping("/{intermediaryIds}")
    public AjaxResult remove(@PathVariable Long[] intermediaryIds) {
        // 删除逻辑
    }

    /**
     * 下载导入模板
     */
    @PostMapping("/importTemplate")
    public void importTemplate(HttpServletResponse response) {
        // 生成 Excel 模板
    }

    /**
     * 导入中介黑名单
     */
    @PreAuthorize("@ss.hasPermi('dpc:intermediary:import')")
    @Log(title = "中介黑名单", businessType = BusinessType.IMPORT)
    @PostMapping("/importData")
    public AjaxResult importData(MultipartFile file) {
        // 导入逻辑
    }
}
```

### Service 层设计

**IDpcIntermediaryBlacklistService**

```java
public interface IDpcIntermediaryBlacklistService {

    /**
     * 查询中介黑名单列表
     */
    List<DpcIntermediaryBlacklistVO> selectIntermediaryList(DpcIntermediaryBlacklistQueryDTO queryDTO);

    /**
     * 查询中介黑名单详细信息
     */
    DpcIntermediaryBlacklistVO selectIntermediaryById(Long intermediaryId);

    /**
     * 新增中介黑名单
     */
    int insertIntermediary(DpcIntermediaryBlacklistAddDTO addDTO);

    /**
     * 修改中介黑名单
     */
    int updateIntermediary(DpcIntermediaryBlacklistEditDTO editDTO);

    /**
     * 批量删除中介黑名单
     */
    int deleteIntermediaryByIds(Long[] intermediaryIds);

    /**
     * 导入中介黑名单数据
     */
    String importIntermediary(List<DpcIntermediaryBlacklistAddDTO> addDTOList, boolean isUpdateSupport);
}
```

### Domain 层设计

**实体类注解**

```java
public class DpcIntermediaryBlacklist {

    /** 中介ID */
    private Long intermediaryId;

    /** 姓名/机构名称 */
    @Excel(name = "姓名/机构名称")
    private String name;

    /** 证件号 */
    @Excel(name = "证件号")
    private String certificateNo;

    /** 中介类型 */
    @Excel(name = "中介类型", readConverterExp = "1=个人,2=机构")
    private String intermediaryType;

    /** 状态 */
    @Excel(name = "状态", readConverterExp = "0=正常,1=停用")
    private String status;

    /** 备注 */
    @Excel(name = "备注")
    private String remark;

    /** 创建者 */
    private String createBy;

    /** 创建时间 */
    private Date createTime;

    /** 更新者 */
    private String updateBy;

    /** 更新时间 */
    private Date updateTime;
}
```

## 前端设计

### 页面结构

```
ruoyi-ui/src/views/dpcIntermediary/
├── index.vue           # 主页面（列表 + 搜索）
└── components/
    └── form-dialog.vue  # 新增/编辑对话框
```

### 主要功能组件

**1. 搜索区**
- 按姓名/机构名称搜索（模糊）
- 按证件号搜索（精确）
- 按中介类型筛选（下拉：全部/个人/机构）
- 按状态筛选（下拉：全部/正常/停用）

**2. 操作按钮区**
- 新增按钮
- 导入按钮
- 导出按钮
- 下载模板按钮

**3. 数据表格**
- 列：姓名/机构名称、证件号、中介类型、状态、创建时间、操作
- 操作列：编辑、删除

**4. 新增/编辑对话框**
- 姓名/机构名称（必填）
- 证件号（选填）
- 中介类型（必填，单选：个人/机构）
- 状态（必填，单选：正常/停用）
- 备注（选填，文本域）

**5. 导入对话框**
- 上传 Excel 文件
- 显示导入结果（成功/失败数量）
- 显示错误详情（如有）

### API 设计

**dpcIntermediary.js**

```javascript
import request from '@/utils/request'

// 查询中介黑名单列表
export function listIntermediary(query) {
  return request({
    url: '/dpc/intermediary/list',
    method: 'get',
    params: query
  })
}

// 查询中介黑名单详细
export function getIntermediary(intermediaryId) {
  return request({
    url: '/dpc/intermediary/' + intermediaryId,
    method: 'get'
  })
}

// 新增中介黑名单
export function addIntermediary(data) {
  return request({
    url: '/dpc/intermediary',
    method: 'post',
    data: data
  })
}

// 修改中介黑名单
export function updateIntermediary(data) {
  return request({
    url: '/dpc/intermediary',
    method: 'put',
    data: data
  })
}

// 删除中介黑名单
export function delIntermediary(intermediaryIds) {
  return request({
    url: '/dpc/intermediary/' + intermediaryIds,
    method: 'delete'
  })
}

// 导出中介黑名单
export function exportIntermediary(query) {
  return request({
    url: '/dpc/intermediary/export',
    method: 'post',
    params: query
  })
}

// 下载导入模板
export function importTemplate() {
  return request({
    url: '/dpc/intermediary/importTemplate',
    method: 'post'
  })
}

// 导入中介黑名单
export function importData(data) {
  return request({
    url: '/dpc/intermediary/importData',
    method: 'post',
    data: data
  })
}
```

## Excel 导入导出设计

### Excel 模板格式

| 姓名/机构名称 | 证件号 | 中介类型 | 状态 | 备注 |
|-------------|-------|---------|------|------|
| 张三 | 110101199001011234 | 个人 | 正常 | 测试数据 |
| XX中介公司 | 91110000XXXXXXXXXX | 机构 | 正常 | - |

### 导入数据验证规则

1. **姓名/机构名称**：必填，长度 1-100 字符
2. **证件号**：选填，长度不超过 50 字符
3. **中介类型**：必填，只能填"个人"或"机构"
4. **状态**：必填，只能填"正常"或"停用"
5. **备注**：选填，长度不超过 500 字符

### 导入错误处理

- 记录每一行的错误信息
- 返回导入结果统计（成功数、失败数）
- 失败数据不写入数据库
- 支持更新模式（可选）

## 权限设计

| 权限标识 | 说明 | 对应接口 |
|---------|------|---------|
| dpc:intermediary:list | 查询中介黑名单列表 | GET /dpc/intermediary/list |
| dpc:intermediary:query | 查询中介黑名单详情 | GET /dpc/intermediary/{id} |
| dpc:intermediary:add | 新增中介黑名单 | POST /dpc/intermediary |
| dpc:intermediary:edit | 修改中介黑名单 | PUT /dpc/intermediary |
| dpc:intermediary:remove | 删除中介黑名单 | DELETE /dpc/intermediary/{ids} |
| dpc:intermediary:export | 导出中介黑名单 | POST /dpc/intermediary/export |
| dpc:intermediary:import | 导入中介黑名单 | POST /dpc/intermediary/importData |

## 菜单设计

在系统菜单表中添加以下菜单记录：

```sql
-- 一级菜单：信息维护
INSERT INTO sys_menu VALUES (
    2000, '信息维护', NULL, 1, 0, 'dpc', NULL, 1, 0, 'M', '0', '0', '', 'example', 'admin', NOW(), '', NULL, '信息维护目录'
);

-- 二级菜单：中介库管理
INSERT INTO sys_menu VALUES (
    2001, '中介库管理', 2000, 1, 0, 'intermediary', 'dpcIntermediary/index', 1, 0, 'C', '0', '0', 'dpc:intermediary:list', 'user', 'admin', NOW(), '', NULL, '中介库管理菜单'
);

-- 中介库管理按钮权限
INSERT INTO sys_menu VALUES (2002, '中介查询', 2001, 1, 0, '', '', 1, 0, 'F', '0', '0', 'dpc:intermediary:query', '#', 'admin', NOW(), '', NULL, '');
INSERT INTO sys_menu VALUES (2003, '中介新增', 2001, 2, 0, '', '', 1, 0, 'F', '0', '0', 'dpc:intermediary:add', '#', 'admin', NOW(), '', NULL, '');
INSERT INTO sys_menu VALUES (2004, '中介修改', 2001, 3, 0, '', '', 1, 0, 'F', '0', '0', 'dpc:intermediary:edit', '#', 'admin', NOW(), '', NULL, '');
INSERT INTO sys_menu VALUES (2005, '中介删除', 2001, 4, 0, '', '', 1, 0, 'F', '0', '0', 'dpc:intermediary:remove', '#', 'admin', NOW(), '', NULL, '');
INSERT INTO sys_menu VALUES (2006, '中介导出', 2001, 5, 0, '', '', 1, 0, 'F', '0', '0', 'dpc:intermediary:export', '#', 'admin', NOW(), '', NULL, '');
INSERT INTO sys_menu VALUES (2007, '中介导入', 2001, 6, 0, '', '', 1, 0, 'F', '0', '0', 'dpc:intermediary:import', '#', 'admin', NOW(), '', NULL, '');
```

## 字典数据设计

### 中介类型（dpc_intermediary_type）

| 字典值 | 字典标签 | 排序 | 状态 |
|-------|---------|-----|------|
| 1 | 个人 | 1 | 正常 |
| 2 | 机构 | 2 | 正常 |

## 技术约束

1. **后端框架**：Spring Boot 3.5.8
2. **ORM 框架**：MyBatis 3.0.5
3. **Excel 处理**：EasyExcel 3.3.4（依赖 `replace-poi-with-easyexcel` change）
4. **前端框架**：Vue 2.6.12 + Element UI 2.15.14
5. **数据库**：MySQL 8.2.0
6. **字符编码**：UTF-8（utf8mb4）