商户管理产品需求文档

版本：2026-09-11 更新版

本模块帮助平台运营建立、查找和维护商户档案，并让商户用户维护自己的联系资料与故障通知配置。本次重点纳入手动填写商户编号、编号唯一性校验、创建后锁定编号、关联删除保护与保存冲突提示。

1 目标与范围

平台超级管理员通过「基础信息管理 → 商户管理」管理全部商户；所属商户已确定的普通用户通过「我的商户」查看和维护本商户资料。

本期覆盖商户列表、搜索、新增、编辑、删除、我的商户、故障推送渠道和配置变更记录。点位、设备、人员的建立与关联分别在对应模块完成。本页负责维护商户档案及保护已有业务关联。

当前界面仍混用「客户」和「商户」：例如「新增客户」「客户编号」均指商户。本需求统一使用商户称谓，截图保留当前界面原文。

2 角色与操作边界

本角色矩阵描述产品访问要求。不能以隐藏按钮作为跨商户权限验收的唯一依据。

3 平台查看与查找商户

3.1 查看商户列表

进入商户管理后，显示客户总数、合作中、点位总数和设备总数四项概览。列表按头像、客户编号、客户信息、状态、操作展示；客户信息包含名称、联系人、电话与故障推送渠道。状态区分「合作中」与「已暂停」。

商户编号独立成列，便于平台识别同名或相似名称的商户。推送渠道展示邮箱推送、公众号推送或未配置推送；邮箱渠道同时显示通知邮箱。

3.2 搜索商户

在搜索框输入商户名称、联系人或电话，列表随输入过滤；清空后恢复全部商户。英文名称与联系人搜索不区分大小写。没有匹配项时显示「暂无客户数据」。当前搜索不支持按商户编号检索，统计卡不会随搜索结果变化。

4 新增商户与编号规则

4.1 新增流程

1. 平台超级管理员点击「新增客户」。
2. 填写商户名称、商户编号、联系人和联系电话；四项均为必填。
3. 按需填写地址、备注并配置邮箱推送；新商户需先保存基础资料，再在人员管理配置公众号接收员工。
4. 点击保存。校验成功后关闭弹窗、显示成功提示并更新列表及统计；新商户默认「合作中」，记录创建日期。
5. 点击取消或关闭按钮放弃本次未保存内容。

4.2 商户编号

建议编号从 C001 开始寻找未占用值，不保证按最后一条记录递增。建议值也必须在保存时再次校验。

4.3 校验与错误反馈

缺少必填项时提示「请填写必填项」；新编号格式不符时提示「商户编号格式不正确,请输入 C 加至少三位数字」；编号已占用时提示「商户编号已存在,请更换」。失败时保留弹窗和已输入内容，不新增商户。

5 编辑资料与我的商户

5.1 平台编辑商户

点击列表中的编辑按钮，弹窗带入现有资料。平台可修改商户名称、联系人、电话、通知配置、地址和备注；商户编号保持只读，并说明创建后不可修改。成功保存后显示「商户信息已更新」。平台修改名称后，已有商户相关展示名称应同步更新，商户身份与关联保持不变。

5.2 我的商户

商户用户进入后仅显示本商户资料卡，包括名称、编号、合作状态、合作模式、联系人、联系电话、故障通知邮箱、故障推送渠道、地址、入驻时间和备注。未填写的一般信息显示短横线，未设置邮箱显示「未设置」。

点击「编辑资料」后可以维护联系资料和通知配置，名称与编号只读。商户名称下方提示由平台运营维护。保存后仍回到本商户资料卡。若找不到所属商户，显示「未找到你所属的商户信息,请联系管理员」。

6 故障推送配置

邮箱推送与公众号推送可以同时启用，也可以均不启用。列表与资料卡应反映已保存的配置；截图中的邮箱均为演示地址。

6.1 邮箱推送

勾选邮箱推送后可填写通知邮箱，启用该渠道必须提供格式合法的邮箱。关闭邮箱推送时邮箱输入框禁用。当前保存还会校验已有的非空邮箱格式，邮箱不合法时阻止保存并提示检查。

6.2 公众号推送

公众号接收人从本商户员工中确定，员工必须账号启用、具有故障接收权限并已登记公众号接收身份。配置动作在人员管理完成，本商户表单不手动填写接收人名单。

新增商户尚未保存、或本商户没有符合条件的接收员工时，不允许新勾选公众号推送，并提示先保存商户基础资料或前往人员管理补充接收人。保存时重新检查，不能保存没有可达接收人的公众号推送配置。

6.3 自动调整与变更记录

当系统核对到已启用公众号推送的商户没有可达接收人时，自动关闭该渠道，保留其他渠道并记录调整。平台可通过「推送配置变更记录」查看最近记录和数量。记录包含时间、商户、调整类型与原因，最多保留最近 20 条；无记录时提示「暂无自动调整记录」。查看后确认可清空记录，取消则保留。

本页配置验收与实际消息送达验收分开进行；页面截图不作为消息已送达的证据。

7 删除与异常保护

7.1 删除商户

平台点击删除时，先判断是否仍关联点位、员工或设备。有任一关联时直接阻止，并提示「该商户仍被点位、员工或设备引用,请先解除关联」。没有关联时弹出删除确认；取消保留数据，确认且保存成功后移除商户并更新统计。

7.2 保存冲突与失败

如果当前页面打开后商户资料已在其他页面更新，保存和删除均应阻止覆盖，提示「商户数据已在其他页面更新,请刷新后重试」。保存失败时提示「商户数据保存失败,请重试」，原数据保留，不显示成功结果；编辑弹窗保留，便于用户处理后重试。

8 验收清单与本期边界

当前页面只展示合作模式和合作状态，未提供编辑合作模式、暂停或恢复合作的操作入口；本次不将这些操作写成已支持。当前也未提供分页、批量导入导出和按编号搜索。

统计卡中点位和设备数量存在演示兜底数据。正式验收须使用真实业务数据确认统计口径，不能将截图中的 8 个点位、15 台设备视为真实统计结果。

9 本次更新与截图说明

本次纳入商户编号手动输入、格式整理与唯一性、历史关联占用、编号不可变更、删除关联保护、跨页面保存冲突、角色区分和故障通知渠道。

截图于 2026-09-11 从当前本地原型实际采集，使用演示商户，桌面视口为 1440 × 1080。图1至图6依次对应平台列表、新增表单、重复编号、平台编辑、我的商户与商户编辑。截图反映当前界面，移动端效果需另行验收。

10 页面字段字典

本字典覆盖商户管理列表、我的商户资料卡、新增与编辑弹窗、统计及推送变更记录。同一业务字段在不同位置使用不同名称时合并说明；按钮与页面标识另表说明，避免与商户档案字段混淆。图1至图6可作为下表对应区域的参考截图。

「必填」指保存商户资料时必须提供；「只读」指本页不能修改；未单列长度限制的字段，当前页面未提供明确的最大长度约束。示例仅用于解释含义。

10.1 商户档案字段

对应图1的列表、图2和图4的管理表单、图5和图6的我的商户。

10.2 故障通知字段

对应图1的渠道标签、图2和图4的表单、图5和图6的商户资料。渠道配置表示接收意愿和可达条件，不表示故障消息已经发送或送达。

10.3 统计与搜索字段

对应图1。统计为平台商户管理视图的整体概览，不随名称、联系人或电话的搜索结果变化；我的商户不展示这组统计。

10.4 推送配置变更记录字段

平台通过页面右上角「推送配置变更记录」查看，记录反映渠道调整，不是故障事件列表、消息送达记录或全部商户操作日志。

10.5 页面标识与操作入口

下列元素不属于商户档案字段，但会影响字段展示或保存，补充说明其用途。

页面公共框架中的登录姓名、登录电话用于识别当前登录者，不是正在查看的商户联系人；「中文／EN」用于切换界面语言，「退出」用于退出当前登录，「☰」用于小屏幕展开或收起导航。这些公共控件不属于商户资料编辑范围。

11 商户关联模块补充需求

商户功能上线后，点位、人员和设备不能继续按平台全量数据独立展示。三类数据都必须有清晰的商户归属，且列表、统计、创建、编辑、删除和详情操作使用同一套归属规则。本节是对点位管理、人员管理和设备管理的补充要求，不改变前文商户档案的字段定义。

当前检查结论如下：

11.1 三类数据的归属关系

当前原型同时出现了商户编号和设备侧历史商户键两种表达方式。正式实现前必须确定一个正式商户编号作为跨模块关联依据，并由所有模块统一使用；历史数据需要提供一次性映射和异常清单，不能由各页面各自猜测对应关系。

11.2 点位管理补充需求（P0）

11.2.1 列表和统计

1. 普通商户用户进入点位管理后，只展示本商户点位；搜索、分类筛选、状态筛选和统计卡都只计算本商户数据。
2. 平台管理员可以按商户筛选，也可以查看全部点位。待分配点位和商户归属异常点位只对平台管理员可见，并显示明确的异常状态。
3. 点位总数、运营中点位数和设备总数必须使用真实的商户范围数据计算；没有数据时显示 0，不使用演示数字代替真实结果。
4. 点位列表至少展示商户名称或商户编号，避免平台管理员在不同商户存在同名点位时无法区分。

11.2.2 新增和编辑

1. 商户用户新增点位时，商户归属自动使用当前商户且不可修改；表单不提供切换到其他商户的入口。
2. 平台管理员新增点位时，商户归属为必填；如果选择待分配，必须填写待分配原因和后续处理人。
3. 编辑点位时重新校验当前用户是否仍有该商户权限。通过列表隐藏点位不能替代保存时的权限校验。
4. 点位编码在同一平台内必须唯一，比较时忽略首尾空格和英文字母大小写；保存失败时明确指出冲突的商户和点位。
5. 已被设备使用的点位编码原则上不可直接修改。确需修改时，要同步更新设备当前关联并保留点位变更历史，不能产生无归属设备。
6. 经度和纬度必须成对填写并在有效范围内；只填写一项、超出范围或定位失败时不得保存为有效坐标。
7. 「负责人」建议从同一商户的人员账号中选择，并保存人员编号和当时的展示姓名；如本期仍保留自由文本，必须在字段说明中明确它只是联系电话快照，不代表权限或责任授权。

11.2.3 删除和异常处理

1. 被设备引用的点位不可直接删除，删除提示需列出受影响设备数量，并引导先换绑或解除设备。
2. 没有设备引用的点位删除后仍需保留操作记录，包括点位编号、原商户、操作人、时间和删除原因。
3. 商户暂停或删除时，旗下点位进入只读或待处理状态，具体状态必须在商户生命周期策略中统一定义，不能继续被普通用户新增设备绑定。

11.3 人员管理补充需求（P1）

1. 商户管理员和普通商户人员只能查看、编辑本商户人员；平台管理员需要提供「全部商户」和按商户筛选的人员视图，不能默认只显示某一个当前商户。
2. 创建人员时，非平台管理员的商户归属固定为当前商户；平台管理员可以选择商户或平台级角色。保存、编辑、禁用和删除时都要再次检查商户权限。
3. 人员可以被授权访问本商户的设备，但设备选择器只能显示同一商户设备；保存时重新检查设备仍属于该商户，不能只依赖页面上的已选列表。
4. 角色和设备范围之外，补充可选的「负责点位」范围。启用后，人员只能查看和处理其负责点位下的设备及故障；平台级角色可跨点位处理。若本期不做点位级权限，应在页面上明确负责人字段不产生访问权限。
5. 商户暂停时，商户人员的登录和操作状态需要有明确策略：默认停止新增和变更操作，并给出暂停原因；是否允许只读查看由业务确认。商户恢复后按暂停前账号状态恢复，不能自动启用原本已禁用的账号。
6. 商户删除前必须检查人员引用；删除或迁移人员时，需要处理其负责点位、设备范围和故障通知接收资格，不能留下失效的故障接收人。
7. 人员的商户、角色、点位范围、设备范围、故障通知资格和账号状态变更必须记录操作人、时间、变更前后值和原因，便于追查越权或漏通知问题。

11.4 设备管理补充需求（P0）

11.4.1 可见范围和操作权限

列表过滤只是入口体验，设备详情、销售开关、远程操作、录入信息、广告屏、温度、物料和故障记录等操作都必须再次校验当前人员和设备的商户、点位及设备范围。无权访问时统一提示「无权操作该设备」，不返回设备敏感信息。

11.4.2 点位绑定、转移和历史

1. 从设备详情快速创建点位时，点位商户自动使用设备商户；普通商户用户不能选择其他商户，也不能通过修改地址或名称改变商户归属。
2. 设备选择点位时，只显示同一商户且状态可用的点位；点位归属异常、商户已暂停或待删除时不可新绑定。
3. 设备转移商户必须由平台管理员发起，采用「原商户—目标商户—生效时间—原因—影响人员」的确认流程；转移后原商户人员立即失去设备访问权。
4. 设备换绑点位时保留历史点位和变更原因；点位删除、编码变更或商户转移不能静默改写历史故障、销售和维护记录。
5. 未录入、离线或归属异常设备要有单独状态，不应通过「未关联点位」掩盖商户归属问题；平台管理员可批量查看待处理清单。

11.4.3 数据和统计

1. 商户详情中的设备总数、点位设备数和设备状态统计必须按商户真实数据计算，并与设备管理筛选结果一致。
2. 设备的商户编号、点位编码和页面展示名称必须来自同一关联关系；发现设备指向不存在点位、点位指向不同商户或商户不存在时，显示归属异常并阻止继续产生关联。
3. 设备批量导入、批量换绑和批量配置（若后续提供）必须逐条校验商户范围，部分失败时返回逐条失败原因，不能整批静默成功。

11.5 跨模块验收清单

本节完成后，点位、人员和设备才具备与商户管理一致的租户边界。实现阶段应优先完成点位商户隔离、设备详情操作复核和关联标识统一，再补充人员的点位责任范围、商户状态联动和审计记录。