ccdi/openspec/changes/add-intermediary-blacklist/specs/intermediary-blacklist/spec.md

# Spec: 中介人员黑名单管理

## ADDED Requirements

### Requirement: 系统SHALL支持查询中介黑名单列表

系统MUST提供查询功能，允许用户查询系统中已维护的中介人员/机构黑名单列表，以便了解当前黑名单库的内容。

#### Scenario: 分页查询中介黑名单列表

**Given** 用户已登录系统且具有 `dpc:intermediary:list` 权限
**When** 用户访问中介库管理页面
**Then** 系统应显示中介黑名单列表，支持分页展示

#### Scenario: 按名称模糊搜索中介黑名单

**Given** 用户已登录系统且具有 `dpc:intermediary:list` 权限
**And** 系统中存在姓名为"张三"的中介人员
**When** 用户在搜索框输入"张"并点击搜索
**Then** 系统应返回所有姓名中包含"张"的中介记录

#### Scenario: 按证件号精确搜索中介黑名单

**Given** 用户已登录系统且具有 `dpc:intermediary:list` 权限
**And** 系统中存在证件号为"110101199001011234"的中介人员
**When** 用户在搜索框输入"110101199001011234"并点击搜索
**Then** 系统应返回该证件号对应的中介记录

#### Scenario: 按中介类型筛选中介黑名单

**Given** 用户已登录系统且具有 `dpc:intermediary:list` 权限
**And** 系统中存在个人和机构两种类型的中介记录
**When** 用户选择中介类型为"个人"并点击搜索
**Then** 系统应仅返回中介类型为"个人"的记录

#### Scenario: 按状态筛选中介黑名单

**Given** 用户已登录系统且具有 `dpc:intermediary:list` 权限
**And** 系统中存在正常和停用两种状态的中介记录
**When** 用户选择状态为"正常"并点击搜索
**Then** 系统应仅返回状态为"正常"的记录

#### Scenario: 组合条件查询中介黑名单

**Given** 用户已登录系统且具有 `dpc:intermediary:list` 权限
**When** 用户同时输入名称"张"、选择中介类型为"个人"、选择状态为"正常"并点击搜索
**Then** 系统应返回同时满足所有条件的记录

---

### Requirement: 系统SHALL支持新增中介黑名单

系统MUST提供新增功能，允许用户手动添加中介人员或机构到黑名单中，以建立和维护黑名单库。

#### Scenario: 新增个人类型的中介黑名单

**Given** 用户已登录系统且具有 `dpc:intermediary:add` 权限
**When** 用户点击"新增"按钮
**And** 填写姓名为"张三"
**And** 填写证件号为"110101199001011234"
**And** 选择中介类型为"个人"
**And** 选择状态为"正常"
**And** 点击"确定"按钮
**Then** 系统应保存中介信息并提示"操作成功"
**And** 列表中应显示新增的记录

#### Scenario: 新增机构类型的中介黑名单

**Given** 用户已登录系统且具有 `dpc:intermediary:add` 权限
**When** 用户点击"新增"按钮
**And** 填写机构名称为"XX中介公司"
**And** 填写证件号为"91110000XXXXXXXXXX"
**And** 选择中介类型为"机构"
**And** 选择状态为"正常"
**And** 点击"确定"按钮
**Then** 系统应保存中介信息并提示"操作成功"
**And** 列表中应显示新增的记录

#### Scenario: 新增时不填写证件号

**Given** 用户已登录系统且具有 `dpc:intermediary:add` 权限
**When** 用户点击"新增"按钮
**And** 仅填写姓名为"张三"
**And** 不填写证件号
**And** 选择中介类型为"个人"
**And** 选择状态为"正常"
**And** 点击"确定"按钮
**Then** 系统应保存中介信息并提示"操作成功"

#### Scenario: 新增时姓名为空应校验失败

**Given** 用户已登录系统且具有 `dpc:intermediary:add` 权限
**When** 用户点击"新增"按钮
**And** 不填写姓名
**And** 点击"确定"按钮
**Then** 系统应提示"姓名/机构名称不能为空"
**And** 不保存数据

#### Scenario: 新增时姓名超过100字符应校验失败

**Given** 用户已登录系统且具有 `dpc:intermediary:add` 权限
**When** 用户点击"新增"按钮
**And** 填写姓名为101个字符的字符串
**And** 点击"确定"按钮
**Then** 系统应提示"姓名/机构名称长度不能超过100个字符"
**And** 不保存数据

#### Scenario: 新增时填写备注信息

**Given** 用户已登录系统且具有 `dpc:intermediary:add` 权限
**When** 用户点击"新增"按钮
**And** 填写必填信息
**And** 填写备注为"涉及多起违规交易"
**And** 点击"确定"按钮
**Then** 系统应保存中介信息及备注
**And** 列表中应显示新增的记录

---

### Requirement: 系统SHALL支持编辑中介黑名单

系统MUST提供编辑功能，允许用户修改已存在的中介黑名单信息，以更新或纠正数据。

#### Scenario: 编辑中介黑名单的基本信息

**Given** 用户已登录系统且具有 `dpc:intermediary:edit` 权限
**And** 系统中存在一条中介记录
**When** 用户点击该记录的"编辑"按钮
**And** 修改姓名为"李四"
**And** 点击"确定"按钮
**Then** 系统应更新中介信息并提示"操作成功"
**And** 列表中应显示更新后的姓名

#### Scenario: 编辑中介黑名单的证件号

**Given** 用户已登录系统且具有 `dpc:intermediary:edit` 权限
**And** 系统中存在一条中介记录
**When** 用户点击该记录的"编辑"按钮
**And** 修改证件号为"110101199001011235"
**And** 点击"确定"按钮
**Then** 系统应更新证件号并提示"操作成功"

#### Scenario: 编辑中介黑名单的状态为停用

**Given** 用户已登录系统且具有 `dpc:intermediary:edit` 权限
**And** 系统中存在一条状态为"正常"的中介记录
**When** 用户点击该记录的"编辑"按钮
**And** 修改状态为"停用"
**And** 点击"确定"按钮
**Then** 系统应更新状态并提示"操作成功"
**And** 该记录在列表中应显示为"停用"状态

#### Scenario: 编辑时姓名为空应校验失败

**Given** 用户已登录系统且具有 `dpc:intermediary:edit` 权限
**And** 系统中存在一条中介记录
**When** 用户点击该记录的"编辑"按钮
**And** 清空姓名字段
**And** 点击"确定"按钮
**Then** 系统应提示"姓名/机构名称不能为空"
**And** 不更新数据

---

### Requirement: 系统SHALL支持删除中介黑名单

系统MUST提供删除功能，允许用户删除不再需要的中介黑名单记录，以保持黑名单库的准确性。

#### Scenario: 删除单条中介黑名单记录

**Given** 用户已登录系统且具有 `dpc:intermediary:remove` 权限
**And** 系统中存在一条中介记录
**When** 用户点击该记录的"删除"按钮
**And** 确认删除操作
**Then** 系统应删除该记录并提示"操作成功"
**And** 列表中不再显示该记录

#### Scenario: 批量删除中介黑名单记录

**Given** 用户已登录系统且具有 `dpc:intermediary:remove` 权限
**And** 系统中存在多条中介记录
**When** 用户勾选3条记录
**And** 点击"删除"按钮
**And** 确认删除操作
**Then** 系统应删除选中的3条记录并提示"操作成功"
**And** 列表中不再显示这3条记录

---

### Requirement: 系统SHALL支持导出中介黑名单

系统MUST提供导出功能，允许用户将查询结果导出为 Excel 文件，以便进行离线分析或备份。

#### Scenario: 导出所有中介黑名单数据

**Given** 用户已登录系统且具有 `dpc:intermediary:export` 权限
**And** 系统中存在100条中介记录
**When** 用户点击"导出"按钮
**And** 不设置任何筛选条件
**Then** 系统应生成包含100条记录的 Excel 文件并下载

#### Scenario: 导出筛选后的中介黑名单数据

**Given** 用户已登录系统且具有 `dpc:intermediary:export` 权限
**And** 系统中存在个人和机构两种类型的中介记录
**When** 用户筛选中介类型为"个人"
**And** 点击"导出"按钮
**Then** 系统应生成仅包含个人类型记录的 Excel 文件并下载

#### Scenario: 导出的 Excel 文件格式正确

**Given** 用户已登录系统且具有 `dpc:intermediary:export` 权限
**When** 用户点击"导出"按钮
**Then** Excel 文件应包含以下列：姓名/机构名称、证件号、中介类型、状态、备注、创建时间
**And** 表头应使用中文显示
**And** 数据应正确显示（中介类型、状态应显示中文而非数字）

---

### Requirement: 系统SHALL支持下载 Excel 导入模板

系统MUST提供模板下载功能，允许用户下载标准的 Excel 导入模板，以便按照模板格式准备数据后批量导入。

#### Scenario: 下载导入模板

**Given** 用户已登录系统且具有 `dpc:intermediary:import` 权限
**When** 用户点击"下载模板"按钮
**Then** 系统应生成 Excel 模板文件并下载
**And** 模板应包含示例数据行
**And** 模板应包含以下列：姓名/机构名称、证件号、中介类型、状态、备注

#### Scenario: 模板中的示例数据正确

**Given** 用户已登录系统且具有 `dpc:intermediary:import` 权限
**When** 用户下载导入模板
**Then** 模板应包含至少一行示例数据
**And** 示例数据应展示正确的填写格式
**And** 中介类型示例应为"个人"或"机构"
**And** 状态示例应为"正常"或"停用"

---

### Requirement: 系统SHALL支持通过 Excel 批量导入中介黑名单

系统MUST提供批量导入功能，允许用户通过 Excel 文件批量导入中介黑名单数据，以提高数据录入效率。

#### Scenario: 导入包含有效数据的 Excel 文件

**Given** 用户已登录系统且具有 `dpc:intermediary:import` 权限
**And** 用户已准备好包含10条有效数据的 Excel 文件
**When** 用户点击"导入"按钮
**And** 选择准备好的 Excel 文件
**And** 点击"确定"
**Then** 系统应导入10条记录并提示"成功导入10条数据"
**And** 列表中应显示这10条新增记录

#### Scenario: 导入时部分数据格式错误

**Given** 用户已登录系统且具有 `dpc:intermediary:import` 权限
**And** 用户准备的 Excel 文件包含10条数据
**And** 其中2条数据的姓名字段为空
**When** 用户点击"导入"按钮
**And** 选择 Excel 文件
**And** 点击"确定"
**Then** 系统应仅导入8条有效数据
**And** 提示"成功导入8条数据，失败2条数据"
**And** 显示失败行的错误详情

#### Scenario: 导入时中介类型值不在允许范围内

**Given** 用户已登录系统且具有 `dpc:intermediary:import` 权限
**And** 用户准备的 Excel 文件中某条记录的中介类型填写为"未知"
**When** 用户点击"导入"按钮
**And** 选择 Excel 文件
**And** 点击"确定"
**Then** 系统应提示该行数据"中介类型只能填写'个人'或'机构'"
**And** 该行数据不被导入

#### Scenario: 导入时状态值不在允许范围内

**Given** 用户已登录系统且具有 `dpc:intermediary:import` 权限
**And** 用户准备的 Excel 文件中某条记录的状态填写为"未知"
**When** 用户点击"导入"按钮
**And** 选择 Excel 文件
**And** 点击"确定"
**Then** 系统应提示该行数据"状态只能填写'正常'或'停用'"
**And** 该行数据不被导入

#### Scenario: 导入时证件号超过50字符

**Given** 用户已登录系统且具有 `dpc:intermediary:import` 权限
**And** 用户准备的 Excel 文件中某条记录的证件号为51个字符
**When** 用户点击"导入"按钮
**And** 选择 Excel 文件
**And** 点击"确定"
**Then** 系统应提示该行数据"证件号长度不能超过50个字符"
**And** 该行数据不被导入

#### Scenario: 导入时备注超过500字符

**Given** 用户已登录系统且具有 `dpc:intermediary:import` 权限
**And** 用户准备的 Excel 文件中某条记录的备注为501个字符
**When** 用户点击"导入"按钮
**And** 选择 Excel 文件
**And** 点击"确定"
**Then** 系统应提示该行数据"备注长度不能超过500个字符"
**And** 该行数据不被导入

#### Scenario: 导入时选择更新支持模式

**Given** 用户已登录系统且具有 `dpc:intermediary:import` 权限
**And** 系统中已存在一条证件号为"110101199001011234"的记录
**And** 用户准备的 Excel 文件包含相同证件号的记录但姓名不同
**When** 用户点击"导入"按钮
**And** 选择 Excel 文件
**And** 勾选"更新已存在数据"选项
**And** 点击"确定"
**Then** 系统应更新该证件号对应的记录
**And** 提示包含更新成功的消息

---

### Requirement: 系统SHALL验证用户权限

系统MUST根据用户的角色和权限控制其对中介黑名单功能的访问，确保未授权用户无法执行相应操作。

#### Scenario: 无权限用户访问列表应被拒绝

**Given** 用户已登录系统
**And** 该用户不具有 `dpc:intermediary:list` 权限
**When** 用户尝试访问中介库管理页面
**Then** 系统应提示"您没有权限执行此操作"
**And** 不显示列表数据

#### Scenario: 无权限用户尝试新增应被拒绝

**Given** 用户已登录系统
**And** 该用户不具有 `dpc:intermediary:add` 权限
**When** 用户尝试点击"新增"按钮
**Then** 系统应隐藏或禁用"新增"按钮

#### Scenario: 无权限用户尝试导出应被拒绝

**Given** 用户已登录系统
**And** 该用户不具有 `dpc:intermediary:export` 权限
**When** 用户尝试点击"导出"按钮
**Then** 系统应隐藏或禁用"导出"按钮

#### Scenario: 无权限用户尝试导入应被拒绝

**Given** 用户已登录系统
**And** 该用户不具有 `dpc:intermediary:import` 权限
**When** 用户尝试点击"导入"按钮
**Then** 系统应隐藏或禁用"导入"按钮

---

### Requirement: 系统SHALL记录操作日志

系统MUST记录用户对中介黑名单的关键操作，包括新增、修改、删除、导入等操作，以便审计和追溯。

#### Scenario: 新增操作应记录日志

**Given** 用户已登录系统且具有 `dpc:intermediary:add` 权限
**When** 用户成功新增一条中介记录
**Then** 系统应在操作日志中记录
**And** 日志应包含：操作人、操作时间、操作类型、操作内容

#### Scenario: 修改操作应记录日志

**Given** 用户已登录系统且具有 `dpc:intermediary:edit` 权限
**When** 用户成功修改一条中介记录
**Then** 系统应在操作日志中记录
**And** 日志应包含：操作人、操作时间、操作类型、修改内容

#### Scenario: 删除操作应记录日志

**Given** 用户已登录系统且具有 `dpc:intermediary:remove` 权限
**When** 用户成功删除一条中介记录
**Then** 系统应在操作日志中记录
**And** 日志应包含：操作人、操作时间、操作类型、删除的记录ID

#### Scenario: 导入操作应记录日志

**Given** 用户已登录系统且具有 `dpc:intermediary:import` 权限
**When** 用户成功导入中介数据
**Then** 系统应在操作日志中记录
**And** 日志应包含：操作人、操作时间、操作类型、导入数量