产品需求文档：我的商户 / 商户管理（按用户流程）
说明： 同一页面在不同角色下呈现两种视图：超级管理员看到的是「商户管理」全量列表；普通用户（绑定单个商户的账号）看到的是「我的商户」自己所属商户的资料卡。源截图位于
../screenshots/customers-prd/。1. 介绍 / 概述
本页面承载「商户」这一基础数据。商户是设备 / 点位 / 故障通知等模块的归属维度，也是普通用户账号的最外层数据范围。
两种视图共用同一份代码，按当前账号角色切换：
- 超级管理员视图（商户管理）：全量商户列表，可新增、编辑、删除、搜索。侧边栏菜单显示为「商户管理」。
- 普通用户视图（我的商户）：单一商户资料卡，只能查看和编辑自己所属商户的字段。商户名称由平台运营维护，普通用户改不了。侧边栏菜单显示为「我的商户」。
商户的关键字段：客户编号、客户名称、合作模式（直营 / 代理 / 加盟）、联系人、联系电话、故障通知邮箱、客户地址、入驻时间、备注、状态（合作中 / 已暂停）。
2. 目标
- 让超管在一个页面里维护全部商户的基础资料，并实时看到客户规模、合作状态、点位与设备总数。
- 让普通用户在「我的商户」页清晰看到自己所属商户的全部资料，并能维护故障通知邮箱等可改字段。
- 让商户名称的修改权限收敛到平台运营手里，避免普通用户随意改名导致跨模块联动（点位、设备）出现脏数据。
- 让故障通知邮箱字段在故障管理页可直接读到，做到「商户改邮箱 → 故障告警自动指向新邮箱」。
- 让删除前要二次确认，避免误删导致下游模块脏数据。
3. 用户流程 / 用户故事
UF-001：超管打开商户管理并查看汇总（超管视图）
描述： 作为超级管理员，我希望进入页面立刻看到平台上全部商户和关键规模指标。
主流程：
- 超管登录后从侧边栏点击「商户管理」。
- 页面标题展示「商户管理」，副标题「管理商户信息和合作关系」。
- 页面上方展示 4 张统计卡：客户总数、合作中、点位总数、设备总数。
- 页面下方展示商户列表（每行：头像、客户编号、客户信息、状态、操作）。
验收标准：
- 超管视图标题为「商户管理」，副标题「管理商户信息和合作关系」，侧边栏菜单文案也是「商户管理」。
- 页头右上角提供「➕ 新增客户」按钮。
- 统计卡包含 4 张：🏢 客户总数、✅ 合作中、📍 点位总数、⚙️ 设备总数。
- 列表表头 5 列：头像 / 客户编号 / 客户信息 / 状态 / 操作。
- 每行客户信息含：客户名称、👤 联系人、📞 联系电话、✉️ 故障通知邮箱（未设置时显示「未设置故障邮箱」）。
- 状态徽章：合作中 = 「● 合作中」（绿色），已暂停 = 「○ 已暂停」（灰色）。
- 每行行末提供「✏️ 编辑」「🗑️ 删除」操作按钮。
参考截图：
UF-002：普通用户查看自己所属商户的资料（普通用户视图）
描述： 作为绑定到某个商户的普通用户，我希望进入页面看到自己商户的完整资料卡。
主流程：
- 普通用户登录后从侧边栏点击「我的商户」。
- 页面标题展示「我的商户」，副标题「查看与维护我所属商户的资料」。
- 页面展示自己商户的资料卡片，包含商户名称、编号、合作模式、联系人、联系电话、故障通知邮箱、商户地址、入驻时间、备注，以及右上角「✏️ 编辑资料」按钮。
验收标准：
- 普通用户视图标题为「我的商户」，副标题「查看与维护我所属商户的资料」，侧边栏菜单文案也是「我的商户」。
- 资料卡片顶部展示首字头像、商户名称、商户编号、状态徽章（合作中 / 已暂停）。
- 头部副信息一行显示「合作模式 · 入驻时间 入驻 · 备注」（任一字段为空时跳过对应片段；全为空时显示「尚未填写补充信息」）。
- 资料项 9 行：商户名称、商户编号、合作模式、联系人、联系电话、故障通知邮箱（未填时显示「未设置」）、商户地址、入驻时间、备注。
- 右上角按钮「✏️ 编辑资料」，点击进入编辑弹窗（见 UF-005）。
- 当账号没有绑定任何商户、或绑定的商户不存在时，展示空状态：⚠️ 图标 + 「未找到你所属的商户信息,请联系管理员」。
参考截图：
UF-003：搜索商户（超管视图）
描述： 作为超管，平台商户多了之后我希望能搜索找到目标商户。
主流程：
- 超管在搜索框输入关键字。
- 列表按关键字过滤。
验收标准：
- 搜索框 placeholder 为「搜索客户名称、联系人、电话...」。
- 搜索同时匹配客户名称、联系人姓名、联系电话三个字段；匹配大小写不敏感。
- 搜索框只在超管视图显示；普通用户视图没有列表，因此不展示搜索框。
- 统计卡反映的是全部商户的口径，不随搜索关键字变化。
UF-004：新增客户（超管视图）
描述： 作为超管，我希望能新增一个商户并填入基础资料。
主流程：
- 超管点击页头右上角「➕ 新增客户」。
- 系统弹出「新增客户」表单。
- 超管输入客户名称、联系人、联系电话等必填字段，可选填故障通知邮箱、客户地址、备注。
- 超管点击「保存」，系统创建商户并刷新列表与统计卡。
验收标准：
- 必填字段：客户名称、联系人、联系电话。任一为空时提示「请填写必填项」并阻止保存。
- 故障通知邮箱字段下方提示「✉️ 设备发生故障时,系统会向该邮箱发送通知;留空表示不接收通知」。
- 故障通知邮箱有格式校验：填了但格式不合法时提示「邮箱格式不正确,请检查」并阻止保存；留空允许。
- 客户地址、备注为选填字段（textarea）。
- 表单底部提供「取消 / 保存」按钮。
- 「➕ 新增客户」按钮只在超管视图可见。
参考截图：
UF-005：编辑商户资料（两种视图，权限不同）
描述： 作为超管或普通用户，我希望能修改商户的可写字段；但「商户名称」是受平台运营保护的，普通用户改不了。
主流程：
- 超管在列表行点击「✏️」，或普通用户在资料卡右上角点击「✏️ 编辑资料」。
- 系统弹出编辑表单，预填已有字段。
- 用户修改字段。
- 用户点击「保存」，系统更新数据并 toast「商户信息已更新」。
验收标准：
- 普通用户视图：客户名称字段为只读，背景灰、光标为禁止；字段下方显示提示「🔒 商户名称由平台运营维护,如需修改请联系运营」。
- 普通用户即使绕过只读样式提交修改后的客户名称，系统也会强制保留原名，不应用更名。
- 超管视图：客户名称字段可改，提示文案隐藏。
- 超管改名生效后，需要把新商户名同步到所有关联存储（设备、点位、人员的所属商户显示）。
- 故障通知邮箱可被两种角色修改；同样走邮箱格式校验。
- 必填项（客户名称、联系人、联系电话）任一为空时阻止保存。
- 保存成功后 toast「商户信息已更新」；普通用户视图的资料卡随之实时刷新。
参考截图：
UF-006：删除客户（超管视图）
描述： 作为超管，对不再合作的商户我希望能从平台移除。
主流程：
- 超管在列表行点击「🗑️」。
- 系统弹出二次确认对话框。
- 确认后从列表中移除该商户。
- toast 提示「客户已删除」并刷新列表与统计卡。
验收标准：
- 删除按钮只在超管视图可见。
- 删除前必须经过二次确认；用户取消时不删除。
- 删除成功后 toast「客户已删除」并刷新统计卡。
- 无回收站，确认通过即直接删除。
UF-007：移动端
描述： 作为超管 / 普通用户，我希望在手机上也能完成关键的查看与编辑操作。
主流程：
- 用户在手机打开商户页面。
- 页面按当前角色切换视图。
- 列表 / 资料卡 / 编辑弹窗自适应单列布局。
验收标准：
- 窄屏下统计卡为单列纵向排布。
- 列表行 / 资料卡不出现横向滚动；所有字段都可见。
- 编辑弹窗可滚动浏览全部字段，并能正常提交。
- 移动端顶部展示当前视图的标签（「我的商户」或「商户管理」），与桌面端保持一致。
参考截图：
4. 功能需求
- 双视图：同一页面按当前账号角色渲染「商户管理」（超管全量列表）或「我的商户」（普通用户单卡资料）；侧边栏菜单文案随之联动。
- 统计卡：4 张（客户总数、合作中、点位总数、设备总数），仅超管视图展示。
- 搜索框：仅超管视图展示，匹配客户名称、联系人、联系电话，大小写不敏感。
- 商户字段：客户编号、客户名称、合作模式、联系人、联系电话、故障通知邮箱、客户地址、入驻时间、备注、状态。
- 故障通知邮箱：可空，填写时做邮箱格式校验；故障管理页直接读这个字段做告警推送目标。
- 新增客户：仅超管，必填客户名称 / 联系人 / 联系电话。
- 编辑商户：超管能改全部字段（含客户名称）；普通用户能改除「客户名称」之外的所有可写字段。
- 客户名称受保护：普通用户编辑表单中客户名称只读；即使绕过只读样式，提交时也强制保留原名。
- 跨模块联动：超管改商户名称后，系统将新名同步到关联存储（设备、点位、人员等模块所展示的所属商户名）。
- 删除客户：仅超管，删除前二次确认，无回收站。
- 状态徽章：「● 合作中」（绿色）与「○ 已暂停」（灰色）两种。
- 空状态：普通用户未绑定到任何商户时，展示空状态卡片提示联系管理员。
5. 当前版本限制
- 状态字段（合作中 / 已暂停）只在新增 / 编辑的内部数据里维护，本页未提供直接切换状态的按钮。
- 合作模式（直营 / 代理 / 加盟）作为字段保存，但在桌面端列表中未单独成列；只在资料卡片的合作模式行展示。
- 没有商户详情子页 / 关联设备列表 / 关联点位列表 / 合作合同附件等扩展信息。
- 故障通知邮箱仅支持单地址，不支持多邮箱、抄送、群组。
- 客户编号由系统在新增时分配，本页不提供改编号的入口。
- 普通用户视图不分页、不切换商户；账号天然绑定单一商户。
- 删除商户后没有「孤儿数据」清理流程：原本关联到该商户的点位 / 设备 / 人员需在各自模块手动处理。