SOP-001：CRM 客户创建 E2E 测试

支持复制到 Excel 的标准 SOP 模板；每个 任务（Task ID） 表示一个可打卡的子文档，便于人工/机器按照序号完成并记录进度。

文档元数据

• 文档类型：SOP / Checklist
• 适用场景：http://localhost:3000/crm/customer 客户管理界面 + 后端 API 验证
• 创建者：QA / 自动化工程
• 最近更新时间：2025-12-21
• 相关接口定义：core/openapi/crm.swagger.json 中 CustomerService 模块（特别是 POST /api/v1/customers、GET /api/v1/customers）

前置条件

条件	检查方式
本地或测试环境可访问 http://localhost:3000/crm/customer	浏览器打开，页面未返回 500/404
已使用有客户权限的用户登录	登录接口/前端登录流程成功，能加载左侧导航
测试数据准备就绪	记录将使用的客户名称/编号，不重复已有记录
API Key 或 Session 可用于后端验证（可选）	CustomerService 的 ApiKeyAuth 或登录 Token 可用于 GET/POST /api/v1/customers

任务矩阵（Excel Checklist 行模板）

每个任务独立一个表格，依次执行并记录状态；状态列可直接粘贴到 Excel 以打勾 [ ] → [x]。

任务 T1：环境与账号验证

入口：http://localhost:3000/crm/customer

Action Steps	Input / Payload	预期结果	验证方式	证据	状态	下游任务
步骤1：打开浏览器	—	浏览器启动成功	浏览器窗口打开	屏幕截图	[ ]	步骤 2
步骤2：输入 URL	http://localhost:3000/crm/customer	页面开始加载	地址栏显示正确 URL	屏幕截图	[ ]	步骤 3
步骤3：登录	账号/密码	登录成功，跳转到主页	左侧导航栏显示	屏幕截图、浏览器日志	[ ]	步骤 4
步骤4：导航到「客户」	点击左侧「客户」菜单	页面成功加载、显示客户列表表格、无 500 错误	UI：存在标题「客户」、表格；Console：无错误	屏幕截图、浏览器日志	[ ]	T2

任务 T2：新建客户 UI 操作

前置条件：T1 成功且当前在客户列表

Action Steps	Input / Payload	预期结果	验证方式	证据	状态	下游任务
步骤1：点击右上「创建客户」按钮	—	弹出客户创建对话框	对话框显示，标题为「创建客户」	屏幕截图	[ ]	步骤 2
步骤2：填写公司名称	公司名称：测试公司-QA-E2E-{{timestamp}}	字段成功填写，无验证错误	输入框显示正确内容	屏幕截图	[ ]	步骤 3
步骤3：填写客户简称	客户简称：测试QA{{timestamp}}	字段成功填写，无验证错误	输入框显示正确内容	屏幕截图	[ ]	步骤 4
步骤4：填写联系电话	联系电话：13800138000	字段成功填写，无验证错误	输入框显示正确内容	屏幕截图	[ ]	步骤 5
步骤5：点击创建按钮	—	对话框关闭，新条目出现在列表，显示成功提示	UI：新行出现；toast：创建成功	截图 + 系统提示	[ ]	T3

字段验证规则说明：

字段	验证规则	错误提示
公司名称	必填，最少 2 个字符	"最少两个字符"
客户简称	必填，最少 2 个字符	"最少两个字符"
联系电话	必填，最少 2 个字符	"最少两个字符"

任务 T3：后端确认

前置条件：T2 成功

Action Steps	Input / Payload	预期结果	验证方式	证据	状态	下游任务
步骤1：记录客户简称/编号	从 UI 复制客户简称和系统生成的编号（如 KH20251221-0001）	简称和编号已记录	笔记/剪贴板	文本记录	[ ]	步骤 2
步骤2：调用 GET /api/v1/customers	filters=shortName:eq:测试QA{{timestamp}} 携带有效 Token/API Key	响应状态码 200，返回客户列表	HTTP 状态码	API Response	[ ]	步骤 3
步骤3：校验返回数据	检查返回的第一项客户数据	客户简称、电话与创建时一致	JSON 字段：shortName、phone、name	Response Body + curl command	[ ]	T4

任务 T4：数据一致性 & 清理

前置条件：T3 返回预期

Action Steps	Input / Payload	预期结果	验证方式	证据	状态	下游任务
步骤1：比对 UI 与 API 数据	UI 显示的客户简称/公司名称/电话，API 返回的数据	两者完全一致	人工/脚本比对	比对结果截图/日志	[ ]	步骤 2
步骤2：记录客户 ID	从 API 响应中提取 id	ID 已记录	笔记/日志	客户 ID 记录	[ ]	步骤 3
步骤3：验证客户列表显示	刷新客户列表页面	新创建的客户显示在列表中，显示正确的编号、简称	UI 列表中存在该客户	截图	[ ]	步骤 4
步骤4：清理测试数据（可选）	调用 DELETE /api/v1/customers/{id} 或标记为待清理	删除成功（状态码 200）或标记完成	API 响应或数据库标记	删除请求响应 + 记录日志	[ ]	—

说明：每个 任务 可视作独立文档，便于 API 或进度采集工具抓取 Task ID + Status + Evidence 等字段。

API 参考（必须遵循的接口）

接口	方法	说明	关键字段 & 数据格式
/api/v1/customers	POST	创建客户	body 需要 coreCreateCustomerRequest 定义，包含 customer 对象。customer 必须提供： - name（string）：客户名称/公司名称 - shortName（string）：客户简称 - phone（string）：联系电话 可选字段：companyName、type、industry、address、email、personInCharge 等。
/api/v1/customers	GET	列表/确认客户	可通过 filters=shortName:eq:<value>、pageSize=1 精确定位刚创建的记录；响应 coreListCustomersResponse 里的 customers 数组含 coreCustomer 结构，可比对 id、shortName、phone、no。
/api/v1/customers/{customerId}	GET	获取单个客户详情	通过客户 ID 获取完整客户信息，包含关联的主体、联系人、银行账户等。
/api/v1/customers/assign	POST（若需权限分配）	赋予客户给用户	请求体参考 coreAssignCustomerRequest，用于附加权限或工作流测试。

参见完整定义：core/openapi/crm.swagger.json 中 definitions 下 coreCustomer, coreCreateCustomerRequest, coreListCustomersResponse，以及 securityDefinitions 中 ApiKeyAuth。

客户对象字段说明（coreCustomer）

字段名	类型	必填	说明
id	integer	否（自动生成）	客户 ID
no	string	否（自动生成）	客户编号（如 KH20251221-0001）
name	string	是	客户名称
shortName	string	是	客户简称
companyName	string	否	公司名称
type	string	否	客户类型
industry	string	否	所属行业
address	string	否	地址
phone	string	是	电话
email	string	否	邮箱
personInCharge	string	否	负责人
level	string	否	客户等级
source	string	否	客户来源

进度采集模板（机器辅助/人手填报）

Task ID	Status	Evidence	Operator	Timestamp	Notes
T1	[ ] / [x]	screen-T1.png	qa-bot	2025-12-21T09:00:00	"登录成功"
T2	[ ] / [x]	screen-T2.png	qa-zhang	2025-12-21T09:03:00	"客户信息已填写"
T3	[ ] / [x]	api-response-T3.json	qa-bot	2025-12-21T09:05:00	"API 验证成功"
T4	[ ] / [x]	screen-T4.png	qa-zhang	2025-12-21T09:06:00	"数据一致性验证通过"

Tip：监控系统可定时读取 Task ID + Status 列；每次 status 变更都写入对应 Evidence 和 Timestamp 以供追踪。

异常与恢复

• 页面未加载：确认后端服务运行 gateway + admin；查看浏览器 Console、Network 500/401；记录 Request ID 并换账号重试。
• 创建失败：记录 toast 错误、截图，使用 GET /api/v1/customers 检查是否已部分创建，再决定是否重试或清除。
• 表单验证错误：检查字段长度，确保公司名称、客户简称、联系电话均至少 2 个字符。
• API 返回 default 错误：拦截 googlerpcStatus 中 code 与 message，附加 curl 命令传给开发。
• 客户编号重复：系统自动生成唯一编号，如发生重复说明后端服务异常，需联系开发排查。

测试数据示例

成功案例

{
  "customer": {
    "name": "测试公司-QA-E2E-20251221093000",
    "shortName": "测试QA20251221",
    "phone": "13800138000"
  }
}

预期响应：

{
  "id": 12345,
  "no": "KH20251221-0001",
  "name": "测试公司-QA-E2E-20251221093000",
  "shortName": "测试QA20251221",
  "phone": "13800138000",
  "status": {...}
}

失败案例

案例一：字段长度不足

{
  "customer": {
    "name": "A",
    "shortName": "B",
    "phone": "1"
  }
}

预期：前端验证阻止提交，显示"最少两个字符"错误提示。

案例二：缺少必填字段

{
  "customer": {
    "name": "测试公司"
  }
}

预期：前端验证阻止提交，显示字段验证错误。

附录：Checklist 导出格式

Task ID,Task Name,Status,Evidence,Operator,Notes
T1,环境与账号验证,[ ],screen-T1.png,qa-bot,"login ok"
T2,新建客户 UI 操作,[ ],screen-T2.png,qa-bot,"create dialog ok"
T3,后端确认,[ ],api-response.json,qa-bot,"API verified"
T4,数据一致性 & 清理,[ ],screen-T4.png,qa-bot,"data consistency ok"

直接复制上述 CSV/Excel 内容可实现标准化追踪。

相关文档

• CRM 操作手册 - 客户模块
• 产品创建 E2E SOP