spec.md 20 KB
功能规格：商家门店分管账号与通知路由
功能标识：022-merchant-store-subaccounts
创建日期：2026-08-28
状态：草案
输入：商家主账号可为多个店铺创建和分配分管账号；分管账号登录商家端后，只能查看和操作被授权店铺的订单、商品及退款；店铺通知优先发送给该店所有已登录的分管账号，无可接收分管账号时发送给主账号。
用户场景与测试
用户故事 1：主账号管理分管账号及店铺授权（优先级：P1）
商家主账号可以创建独立登录的分管账号，并为一个账号分配一个或多个属于自己的店铺。主账号可以调整授权店铺、重置密码、停用或重新启用分管账号。
优先级原因：账号和店铺授权关系是后续数据隔离、业务操作和通知路由的基础。
独立测试：主账号创建一个分管账号并分配两家店铺，分管账号使用独立凭据成功登录；主账号取消其中一家店铺授权后，该账号只剩另一家店铺的访问权限。
验收场景：
- 假如 主账号拥有店铺 A、店铺 B，当 主账号创建分管账号甲并同时分配 A、B，那么 账号甲可以使用独立账号登录，且同时拥有 A、B 的授权。
- 假如 店铺 C 不属于当前主账号，当 主账号尝试将账号甲分配给店铺 C，那么 系统拒绝保存且不产生越权关系。
- 假如 账号甲已经负责 A、B，当 主账号取消其店铺 A 授权，那么 账号甲立即失去 A 的数据和操作权限，但仍可访问 B。
- 假如 账号甲被停用，当 账号甲尝试登录或继续调用商家业务接口，那么 系统拒绝访问。
- 假如 当前登录者是分管账号，当 其尝试创建、编辑授权、停用或重置其他分管账号，那么 系统拒绝操作。
用户故事 2：分管账号按授权店铺开展经营（优先级：P1）
分管账号登录现有商家端后，店铺列表直接展示其负责的全部店铺，无需切换或保存“当前店铺”。分管账号可以在这些店铺范围内管理商品、订单、营业状态、店铺基础资料和退款，但不能访问未授权店铺。
优先级原因：这是分管账号承担门店日常经营工作的核心价值，并且必须保证店铺间数据隔离。
独立测试：给账号甲授权店铺 A、B，保留同一主账号下未授权的店铺 C；验证账号甲的店铺列表及各业务列表只包含 A、B，对 C 的详情、修改、订单操作和退款请求均被后端拒绝。
验收场景：
- 假如 账号甲负责 A、B，当 其打开商家端店铺列表，那么 系统返回 A、B，不返回同一主账号的店铺 C。
- 假如 账号甲负责 A、B，当 其同时查询两家店铺的订单或商品，那么 系统按授权集合返回结果，不要求先选择当前店铺。
- 假如 账号甲负责 A，当 其操作 A 的订单、商品、营业状态、店铺基础资料或退款，那么 系统允许符合原业务规则的操作。
- 假如 账号甲未负责 C，当 其通过伪造店铺 ID、订单 ID 或商品 ID 尝试读取或修改 C 的数据，那么 后端拒绝操作且不泄露 C 的业务数据。
- 假如 当前登录者是分管账号，当 其调用新增店铺接口，那么 系统拒绝创建；前端是否隐藏入口不影响后端校验结果。
- 假如 当前登录者是分管账号，当 其尝试删除店铺、修改收款配置、提现、结算或查看跨店财务汇总，那么 系统拒绝操作。
用户故事 3：通知发送给店铺在线分管账号（优先级：P1）
订单或其他店铺业务产生商家通知时，系统根据通知对应的店铺查找所有已启用、已登录且仍有该店授权的分管账号，并向这些账号全部发送通知。如果没有符合条件的分管账号，则向店铺所属主账号发送通知。
优先级原因：让实际负责门店的人及时处理业务，并在无人负责时通过主账号兜底，避免漏单或延迟处理。
独立测试：店铺 A 同时配置账号甲、乙、丙；甲和乙已登录，丙未登录。触发 A 的新订单通知，验证甲、乙分别收到推送和消息记录，丙与主账号不收到；随后使甲、乙退出登录，再次触发通知，验证只发送给主账号。
验收场景：
- 假如 店铺 A 的账号甲、乙均已登录且可接收推送，当 A 产生商家通知，那么 甲、乙都收到通知，并分别拥有自己的站内消息记录。
- 假如 店铺 A 存在已登录分管账号，当 A 产生商家通知，那么 主账号不再重复接收该通知。
- 假如 店铺 A 没有已登录且可接收通知的分管账号，当 A 产生商家通知，那么 通知发送给主账号作为兜底。
- 假如 账号甲同时负责 A、B，当 A 产生通知，那么 账号甲收到 A 的通知；未负责 A 的其他分管账号不接收。
- 假如 多个接收账号意外登记了相同的设备标识，当 系统发送同一业务通知，那么 同一设备只收到一次外部推送，但每个应接收账号仍保留可追溯的消息归属。
- 假如 通知无法解析出有效店铺，但可以确定原商家主账号，当 系统执行通知路由，那么 直接发送给该主账号并记录异常，不向无关分管账号广播。
用户故事 4：权限变更立即生效（优先级：P2）
主账号调整分管账号状态或店铺授权后，新的查询、操作和通知路由立即使用最新权限，不能继续依赖登录时缓存的旧店铺集合。
优先级原因：人员离职、调店或临时代班时需要及时收回或调整权限，防止越权操作和错误通知。
独立测试：账号甲保持登录状态，主账号取消其店铺 A 授权；无需账号甲重新登录，随后查询 A、操作 A 订单及触发 A 通知，均不再将甲视为有效分管账号。
验收场景：
- 假如 账号甲仍处于登录状态，当 主账号取消其 A 的授权，那么 甲下一次访问 A 时立即被拒绝，A 的后续通知也不再发送给甲。
- 假如 账号甲仍处于登录状态，当 主账号停用甲，那么 甲的后续业务请求被拒绝，且不再收到任何所分管店铺通知。
- 假如 主账号重新启用甲但尚未重新分配任何店铺，当 甲登录商家端，那么 可以完成身份认证，但店铺列表为空且不能操作店铺业务。
用户故事 5：平台按主商家查看和管控分管账号（优先级：P2）
平台管理员继续将商家主账号作为唯一商家管理对象。分管账号不进入现有商家列表、商家审核、商家导出或商家数量统计，而是在对应主商家的详情或下级入口中呈现。平台管理员可以查看分管账号及其负责店铺，并可出于安全或合规原因强制停用或重新启用账号。
优先级原因：平台需要了解实际经营账号并具备风险处置能力，同时不能把一个商家的员工账号错误计算成多个商家。
独立测试：主商家创建三个分管账号后，平台商家列表、导出和商家数量仍只增加一个主商家；从该主商家进入分管账号页面可看到三个账号及店铺授权，并可强制停用其中一个账号。
验收场景：
- 假如 一个主商家拥有三个分管账号，当 平台查询商家列表、导出商家或统计商家数量，那么 只把主账号计为一个商家，三个分管账号均不出现也不计数。
- 假如 平台管理员打开主商家的分管账号入口，当 查询完成，那么 可以看到每个分管账号的姓名、手机号、账号状态、在线状态或最后登录时间、负责店铺和创建时间。
- 假如 平台管理员强制停用分管账号甲，当 甲尝试登录、继续调用商家接口或等待店铺通知，那么 系统拒绝其访问且不再向其发送通知。
- 假如 主账号尝试重新启用被平台强制停用的账号甲，当 提交启用操作，那么 系统仍保持平台停用状态，只有平台管理员可以解除。
- 假如 平台管理员查看分管账号，当 尝试修改店铺授权或重置密码，那么 平台不提供此能力；店铺授权和密码管理仍由所属主账号负责。
边界情况
- 分管账号手机号已被现有用户、商家、骑手或其他分管账号使用时，不允许重复创建账号。
- 一个分管账号只能隶属于一个商家主账号，但可以关联该主账号名下多个店铺。
- 店铺转移所有权、删除或失效时，关联授权必须失效，不能继续用于查询、操作或通知。
- 主账号不能通过分管账号管理功能被降级、停用或删除。
- 分管账号提交的店铺 ID、订单 ID、商品 ID 和退款目标不一致时，按目标业务数据实际所属店铺校验，不能只校验请求参数。
- 分管账号已登录但缺少有效推送标识时，不计入该次通知的可接收账号；如果因此没有任何可接收分管账号，则由主账号兜底。
- 单个分管账号重复关联同一家店铺时，系统保持一条有效授权，不产生重复授权或重复通知。
- 同一通知批量发送给多个账号时，单个账号发送失败不得阻止其他账号接收；失败结果需要被记录以便排查。
- 主账号自身未登记有效推送标识时，系统仍需生成主账号的站内消息记录，并记录外部推送未发送原因。
- 分管账号同时存在“主账号停用”和“平台强制停用”时，任一停用条件都必须阻止登录、业务访问和通知接收；主账号不能解除平台停用。
- 主商家被平台停用时，其全部分管账号即使自身状态正常，也不能登录、操作店铺或接收通知。
- 平台通过直接构造查询参数访问分管账号时，通用商家列表、商家审核和商家导出仍必须排除分管账号。
需求
功能需求
- FR-001：系统必须区分商家主账号和分管账号，同时保持两者使用现有商家端身份认证体系。
- FR-002：系统必须只允许商家主账号创建分管账号；创建时至少提供手机号、姓名和初始密码。
- FR-003：系统必须保证分管账号登录标识在现有用户体系内唯一，不能因账号类型不同而重复。
- FR-004：系统必须允许主账号重置分管账号密码、启用或停用分管账号。
- FR-005：系统必须只允许主账号管理隶属于自己的分管账号，禁止跨商家读取或修改。
- FR-006：系统必须支持一个分管账号关联同一主账号名下的一个或多个店铺，并保证相同账号与店铺的有效授权唯一。
- FR-007：系统必须验证被分配店铺属于当前主账号，禁止建立跨商家店铺授权。
- FR-008：分管账号不能自行注册为某个商家的分管账号，也不能自行变更所属主账号或授权店铺。
- FR-009：主账号的店铺列表必须保持返回其拥有的全部店铺；分管账号的店铺列表必须只返回其当前有效授权店铺。
- FR-010：系统不得要求分管账号选择或持久化“当前店铺”；每次查询和操作都必须依据实际目标门店进行授权校验。
- FR-011：所有店铺范围的列表查询必须在后端按当前账号的可访问店铺集合过滤，不能只依赖前端隐藏数据。
- FR-012：所有店铺范围的详情和修改操作必须从目标数据解析实际门店归属，并校验当前账号权限，不能仅信任客户端提交的门店 ID。
- FR-013：分管账号必须可以在授权店铺范围内查看和操作订单、商品、营业状态、店铺基础资料及退款，且仍需满足各业务原有状态流转和校验规则。
- FR-014：分管账号必须禁止新增或删除店铺、管理分管账号、修改收款配置、提现、结算及查看跨店财务汇总。
- FR-015：新增店铺接口必须在后端明确校验当前登录者为主账号；不能将前端入口隐藏视为权限控制。
- FR-016：账号停用或店铺授权移除后，新的查询、操作和通知路由必须立即使用最新权限，不得要求重新登录后才生效。
- FR-017：店铺业务通知必须以实际店铺为路由依据；订单通知优先使用订单保存的门店归属。
- FR-018：通知路由必须选择该店所有已启用、拥有有效授权、处于有效商家端登录状态且具有有效推送标识的分管账号。
- FR-019：当存在一个或多个符合条件的分管账号时，系统必须向这些账号全部发送通知，并且不向主账号重复发送。
- FR-020：当不存在符合条件的分管账号时，系统必须向店铺所属主账号发送通知作为兜底。
- FR-021：系统必须为每个业务接收账号分别保存站内消息归属；外部推送缺少标识或发送失败不得导致站内消息丢失。
- FR-022：同一次通知向多个账号发送时，系统必须按设备标识去重外部推送，并隔离单个接收者的发送失败。
- FR-023：通知无法解析店铺但可以确定主账号时，系统必须直接发送给主账号、记录异常并禁止无范围广播。
- FR-024：分管账号的退款权限必须限定在其有效授权店铺的订单内，且不得绕过现有支付渠道、订单状态和退款校验。
- FR-025：系统必须保留主账号原有账号、店铺、订单和通知行为的兼容性；未创建分管账号的商家继续按原流程运行。
- FR-026：商家端必须向主账号提供分管账号列表、创建、编辑、授权、停用和密码重置入口，并向分管账号隐藏或禁用主账号专属入口。
- FR-027：新增用户可见文本和业务错误必须支持越南语、简体中文、繁体中文和英文。
- FR-028：分管账号必须使用独立于商家主账号的账号类别，不能作为商家主账号参与平台商家列表、审核、导出或数量统计。
- FR-029：平台必须在主商家的详情或下级入口中展示所属分管账号，不得将分管账号作为顶级商家行呈现。
- FR-030：平台分管账号视图必须展示姓名、手机号、账号状态、在线状态或最后登录时间、负责店铺和创建时间。
- FR-031：平台管理员必须可以强制停用或重新启用分管账号；主账号不能解除平台强制停用。
- FR-032：主账号停用和平台强制停用必须作为相互独立的限制条件，任一条件生效时都禁止分管账号登录、访问业务和接收通知。
- FR-033：平台不得修改分管账号的店铺授权或密码；这些能力只属于该账号的主账号。
- FR-034：主商家被平台停用时，系统必须同时禁止其全部分管账号登录、访问商家业务和接收店铺通知。
- FR-035：平台现有商家新增、修改和审核入口不得创建分管账号或把普通账号转换为分管账号。
- FR-036：需要服务端会话撤销能力的商家业务接口，其 JWT 签名、有效期和 Redis 会话存在性必须在进入 Controller 前由统一认证层完成，不得由各 Controller 重复执行会话认证。
- FR-037：Controller 只能使用统一认证通过后的 Token 身份执行门店、订单、商品等业务归属校验；会话服务只负责退出、批量撤销和在线状态查询。
关键实体
- 商家账号：登录商家端的身份。角色分为主账号和分管账号；分管账号隶属于唯一主账号并具有独立登录凭据、启停状态和推送信息。
- 店铺：由主账号拥有的经营单元，是商品、订单、退款权限和通知路由的数据边界。
- 店铺授权：分管账号与店铺之间的有效关联；一个账号可以有多个店铺授权，一个店铺可以有多个分管账号。
- 通知接收者：某次店铺通知最终选出的账号，可能是所有符合条件的分管账号，也可能是在无人可接收时兜底的主账号。
- 通知消息：归属于具体接收账号的站内消息记录；外部推送是该消息的送达通道，不取代账号级消息记录。
- 账号控制状态：分管账号同时具有主账号控制状态和平台控制状态；只有两者都允许时账号才可登录、操作和接收通知。
成功标准
可衡量结果
- SC-001：主账号能够在一次创建流程中完成分管账号建立并分配多个店铺，成功后该账号可立即登录。
- SC-002：在自动化越权测试中，分管账号对未授权店铺的列表、详情、修改、订单操作、商品操作和退款请求拦截率达到 100%。
- SC-003：店铺存在多个符合条件的在线分管账号时，所有符合条件账号均产生自己的消息记录，主账号不产生重复消息。
- SC-004：店铺没有符合条件的分管账号时，主账号兜底消息产生率达到 100%。
- SC-005：分管账号停用或授权移除后，无需重新登录，其下一次业务请求和下一次通知路由均使用新权限。
- SC-006：未配置任何分管账号的现有商家，其新增店铺、店铺列表、订单、商品、退款和通知流程保持原有可用行为。
- SC-007：同一通知的单个接收账号推送失败时，其他符合条件账号仍能完成消息入库和推送尝试。
- SC-008：任意数量的分管账号都不会改变平台商家列表、导出和商家数量统计中的主商家数量。
- SC-009：平台强制停用后，主账号无法绕过该状态重新启用分管账号，相关登录、业务访问和通知测试拦截率达到 100%。
- SC-010：缺少、过期、签名错误或 Redis 会话不存在的商家 Token 均在进入 Controller 前被拒绝；有效 App/PC 商家 Token 只执行一次集中会话认证并可正常进入业务处理。
假设
- 继续复用现有商家端账号登录、Token、设备标识和站内消息机制，不为分管账号建立第二套认证系统。
- “已登录分管账号”指账号已启用、存在有效商家端登录状态且登记了有效推送标识；App 位于前台或后台不影响推送资格。
- 第一阶段沿用现有单账号当前推送标识模型；同一账号多设备同时接收不在本功能范围内。
- 一个分管账号只隶属于一个主账号；跨商家代运营账号不在本功能范围内。
- 第一阶段采用固定的主账号/分管账号权限边界，不提供按按钮勾选的细粒度自定义权限。
- 不引入排班或“当前值班账号”；同店多个符合条件的分管账号全部接收通知。
- 订单和其他核心业务数据具有可解析的门店归属；历史异常数据无法解析门店时按主账号兜底并记录异常。
非目标
- 不实现一个分管账号同时隶属于多个商家主体。
- 不实现分管账号自助注册、自助申请加入店铺或店铺间转移。
- 不实现自定义角色、逐菜单权限配置或逐操作权限配置。
- 不实现值班排班、只通知一个当前值班人员或抢单式门店通知。
- 不实现同一账号多设备会话和多设备推送标识管理。
- 不改变骑手、普通用户或平台管理后台的账号体系。
- 不允许平台管理员修改分管账号店铺授权或重置分管账号密码。
- 不改变订单、支付、退款或配送本身的业务状态流转，只增加门店范围授权和通知接收者路由。