# 客户管理新增字段(社会信用代码等 7 项)- 前端联调方案 ## 涉及页面 - CRM → 客户管理 → 客户列表 - CRM → 客户管理 → 新增/编辑客户弹窗 - CRM → 客户管理 → 客户详情 ## 业务流程与数据带入 1. 新增/编辑客户时,可录入 7 个新字段,保存后持久化到 `crm_customer` 表。 2. 列表展示 7 个新字段;「所属上级经销商」展示其名称(`parentDealerName`)。 3. 列表支持按 6 个新字段筛选(社会信用代码、身份证号、客户姓名、备案流水号、所属区域、所属上级经销商)。 4. 「所属上级经销商」复用 CRM 客户主数据,选择弹窗与客户选择组件一致;后端校验不能选择客户自身。 5. 详情页展示 7 个新字段,其中「所属上级经销商」展示名称。 ## API | 方法 | 路径 | 说明 | |------|------|------| | GET | /crm/customer/page | 客户分页(新增筛选参数、响应字段) | | POST | /crm/customer/create | 新增客户(新增请求字段) | | PUT | /crm/customer/update | 修改客户(新增请求字段) | | GET | /crm/customer/get | 客户详情(新增响应字段) | ### 请求字段新增(create / update) | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | socialCreditCode | String | 否 | 社会信用代码,最长 64 字符 | | idCardNo | String | 否 | 身份证号,最长 32 字符 | | customerName | String | 否 | 客户姓名,最长 64 字符 | | filingSerialNo | String | 否 | 备案流水号,最长 64 字符 | | bankAccountName | String | 否 | 银行账户名称,最长 128 字符 | | region | String | 否 | 所属区域,最长 64 字符 | | parentDealerId | Long | 否 | 所属上级经销商编号,关联客户表 `id` | ### 查询参数新增(page) | 参数 | 类型 | 匹配方式 | 说明 | |------|------|----------|------| | socialCreditCode | String | 模糊匹配 | 社会信用代码 | | idCardNo | String | 模糊匹配 | 身份证号 | | customerName | String | 模糊匹配 | 客户姓名 | | filingSerialNo | String | 模糊匹配 | 备案流水号 | | region | String | 模糊匹配 | 所属区域 | | parentDealerId | Long | 精确匹配 | 所属上级经销商编号 | ### 响应字段新增(page / get) | 字段 | 类型 | 说明 | |------|------|------| | socialCreditCode | String | 社会信用代码 | | idCardNo | String | 身份证号 | | customerName | String | 客户姓名 | | filingSerialNo | String | 备案流水号 | | bankAccountName | String | 银行账户名称 | | region | String | 所属区域 | | parentDealerId | Long | 所属上级经销商编号 | | parentDealerName | String | 所属上级经销商名称(由后端批量回填,仅展示用) | **响应示例:** ```json { "code": 0, "data": { "id": 1001, "name": "某某农业合作社", "customerName": "张三", "socialCreditCode": "91320600MA1XXXXXXX", "idCardNo": "320602199001011234", "filingSerialNo": "BA2026000001", "bankAccountName": "南通某某农业有限公司", "region": "南通", "parentDealerId": 900, "parentDealerName": "某某经销商" }, "msg": "" } ``` ## 字段展示规则 | 字段 | 展示位置 | 说明 | |------|----------|------| | customerName | 新增/编辑、列表、筛选、详情 | 客户姓名,与「客户名称」并存 | | socialCreditCode | 新增/编辑、列表、筛选、详情 | 社会信用代码 | | idCardNo | 新增/编辑、列表、筛选、详情 | 身份证号 | | filingSerialNo | 新增/编辑、列表、筛选、详情 | 备案流水号 | | bankAccountName | 新增/编辑、列表、详情 | 银行账户名称 | | region | 新增/编辑、列表、筛选、详情 | 所属区域(自由文本) | | parentDealerId | 新增/编辑、筛选 | 所属上级经销商,复用客户选择组件 | | parentDealerName | 列表、详情 | 所属上级经销商名称,空值展示 `-` | ## 业务规则说明 | 场景 | 规则 | |------|------| | 所属上级经销商 | 复用 CRM 客户主数据,自关联 `parent_dealer_id → crm_customer.id` | | 自关联校验 | 编辑客户时,所属上级经销商不能选择客户自身,后端返回「所属上级经销商不能选择客户自身」 | | 数据权限 | 列表查询仍受 CRM 数据权限控制,「所属上级经销商」下拉可选范围由客户选择组件决定 | | 空值 | 新增字段均非必填;列表空值展示 `-` | ## 注意事项 - 「客户姓名」(`customerName`)与既有「客户名称」(`name`)为两个独立字段,不要混用。 - 「所属区域」(`region`)为自由文本,与既有「地址」(`areaId` 省市区级联)互不影响。 - 新增字段已加入导出 Excel 列,导出文件自动包含;`parentDealerName` 仅用于展示,不可作为保存入参。 - 数据库需先执行 `sql/mysql/crm_customer_dealer_fields_20261106.sql`。