zkxw/openspec/changes/basic-info-management/specs/customer-management/spec.md

ADDED Requirements

Requirement: 租户内客户列表与分页

系统 SHALL 提供已认证管理端用户可用的客户分页查询接口，数据范围限定为当前用户所属租户，且默认排除 del_flag=1 的记录。列表默认排序 SHALL 为 create_time DESC（若无自定义排序）。

Scenario: 分页查询成功

• WHEN 调用方请求客户列表且传入合法分页参数
• THEN 系统返回当前租户下未删除客户的分页数据，且不包含其他租户客户

Requirement: 客户新增与身份证去重

系统 SHALL 支持创建客户，字段包含客户姓名（必填）、性别、身份证号、年龄、联系电话、客户标签（逗号分隔）、备注等，与 biz_customer 一致。当 id_card_no 非空时，系统 SHALL 拒绝在同一租户下创建与已有未删除客户相同身份证号的新记录，并返回可展示的业务错误信息。

Scenario: 同名不同人可共存

• WHEN 请求创建客户 A 与客户 B，二者 customer_name 相同但 id_card_no 不同或其一为空
• THEN 系统允许分别创建成功

Scenario: 身份证重复拒绝创建

• WHEN 请求创建客户且 id_card_no 与同一租户下已存在未删除客户相同
• THEN 系统拒绝创建并返回明确提示（含义与需求「已创建」一致）

Requirement: 客户修改与删除

系统 SHALL 支持按主键更新未删除客户的可编辑字段；更新时若修改 id_card_no 为非空，SHALL 执行与同租户未删除记录的去重校验（排除自身）。系统 SHALL 仅支持软删除（del_flag=1），SHALL NOT 物理删除业务数据。

Scenario: 更新身份证冲突

• WHEN 将某客户的 id_card_no 改为另一未删除客户已占用的号码
• THEN 系统拒绝更新并返回业务错误

Scenario: 软删除客户

• WHEN 请求删除某客户主键
• THEN 系统将对应行 del_flag 置为 1，列表默认查询不再返回该记录

Requirement: Web 管理端客户维护页

Web 管理端 SHALL 提供客户列表页，包含筛选（至少支持姓名/电话/身份证关键字类检索，若后端实现）、工具栏、表格、分页；SHALL 提供新增与编辑弹窗表单（label-position="top"，布局符合 Fresh Mint 与项目 CRUD 弹窗规范）。

Scenario: 用户在页面完成一次新增

• WHEN 用户在客户页填写合法信息并提交保存
• THEN 系统调用后端创建接口并在成功后刷新列表