Hermes/multi-simadmin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9bc0f27f126515f5acfd76a94b60076dcda25564
multi-simadmin/docs/product/personas-and-workflows.md
T

19 KiB
Raw Blame History

用户角色、任务与端到端流程

目标：以可执行用户任务约束页面、API、状态和风险交互，而不是从旧页面反推功能。

Phase 0.1 文档导航：返回项目章程｜现状审计｜角色与流程（本文）｜信息架构

1. 角色定义

P1 日常运维员

  • 环境： 管理 5–100 个 SimAdmin 实例，频繁查看在线、认证、信号、版本和任务结果。
  • 目标： 快速发现异常，做低风险恢复或把高风险动作交给 Job。
  • 痛点： 卡片难比较；空值无法判断不支持还是失败；切换设备时担心误操作。
  • 权限假设： V1 是本机单操作者，不实现 RBAC；仍记录本地 actor/session 标识。
  • 成功指标： 从 Fleet 进入异常实例并找到失败采集项不超过 3 次导航。

P2 网络与设备工程师

  • 环境： 调整运营商注册、APN、频段/小区锁定、radio/data/roaming/airplane、WLAN/DDNS、eSIM。
  • 目标： 在变更前看清当前值和 capability，变更后保留证据并能诊断失败。
  • 痛点： 上游版本差异；网络切换会暂时断连；错误 raw JSON 难解释。
  • 成功指标： 所有 R2/R3 变更都有预检、影响说明、明确目标和逐步结果。

P3 系统维护者

  • 环境： 接入/移除实例、管理凭据、轮询参数、服务/系统重启和 OTA。
  • 目标： 安全配置控制台，确保升级、数据和回滚可靠。
  • 痛点： 密码保存语义含糊；大文件上传与重启无进度；配置失败可能产生半状态。
  • 成功指标： 实例 CRUD、导入和凭据操作可预览且原子；OTA/重启可追踪。

P4 审计与故障复盘者

  • 环境： 在故障后按时间、实例、操作和 requestId 查询。
  • 目标： 重建操作链路，确定参数摘要、风险、执行结果及部分失败范围。
  • 痛点： 临时提示消失；日志可能含敏感信息；批量动作只给总成功/失败。
  • 成功指标： 单次操作从 audit 可跳到 Job 和逐实例 item，且不暴露 secret。

2. 共同交互契约

2.1 状态语言

所有页面使用相同术语：

  • 实例：在线、离线、需要认证、退化、未知。
  • 新鲜度：最新、陈旧、已过期、未知，并显示最后成功时间。
  • 能力：支持、不支持、需要认证、退化、未知。
  • 请求：空闲、加载中、成功、失败。
  • 批量项：排队、已跳过、执行中、成功、失败、已取消。

不支持不得渲染成空值；失败不得清除最后成功数据，而应保留数据并标“陈旧”。领域/API 新鲜度枚举统一为 fresh，中文显示“最新”，禁止使用 API 枚举 latest；三个正交状态及组合规则以项目章程 7.6为准。

2.2 写操作确认卡

所有 R1–R3 在提交前至少显示：

目标：实例名称 + 稳定 ID + URL origin
操作：业务名称 + operationId
当前值：结构化字段
目标值：结构化字段
变更：逐字段 diff
风险：R1 / R2 / R3 + 具体影响
支持性：capability 与上次探测时间
执行方式：立即 / Job / 批量逐项

R2/R3 还必须显示预检结果和失败阻断项；确认 token 的完整绑定、首次尝试即消费规则以项目章程 7.3为唯一规范。若用户在确认期间切换实例、修改表单或配置发生变化，旧确认作废并回到预检。

执行政策统一为：R3 无例外全部创建 Job；R2 默认创建 Job。只有单目标 operation 被 OperationRegistry 显式标记 syncSafe=true，并登记同步安全理由及覆盖超时、结果落点和误重放的测试时，R2 才可同步执行；批量 R2 无论单项是否 syncSafe 都创建父 Job 和逐实例 item。

3. 关键流程

WF-01 添加并验证实例

角色： P3
入口： /instances/new 或 /settings/instances 的“添加实例”

  1. 输入稳定 ID、名称、URL、描述、标签和认证模式。
  2. URL 在客户端做格式提示，服务端执行权威 URL/SSRF 校验。
  3. 凭据选择 不保存/设置；编辑时必须明确 保留/设置/清除，不能用空密码猜语义。
  4. 点击“测试连接”，BFF 先以严格只读 R0 返回 health、延迟、上游版本、auth-status 和 capability 初探；不得在 R0 请求中夹带凭据。
  5. 若需要密码，可另行使用 R1-S credential verify/login 专用会话流程提交一次性临时密码；按 actor+session+instance 限速并只审计无 secret 元数据，绝不自动重放。除非另行选择本地 SecretStore reference“设置”，临时密码不保存；设备 setup/password 改动只能走 R3 专用 Job。
  6. 测试结果按阶段显示，不把 health 成功等同于认证成功。
  7. 保存后事务写入实例与 tags，secret 仅保存 reference；client registry reconcile。
  8. 成功跳转 /instances/:id/overview；reconcile pending 时显示持久退化提示并允许重试。

分支与恢复：

  • URL/SSRF 拒绝：字段级错误，禁止发起上游连接。
  • 不可达/超时：允许保存为 disabled 草稿，默认不进入轮询；不得误标在线。
  • 401：显示“可达，需要认证”，允许重新输入临时密码。
  • 不支持 capability endpoint：保存实例，但导航只展示已确认模块和未知待探测模块。
  • ID 重复/revision 冲突：保留输入，提示选择新 ID 或刷新。

验收： 密码不出现在响应、地址栏、audit 参数、日志；保存成功后 Fleet 只有一个该 ID。

WF-02 Fleet 定位异常

角色： P1
入口： /fleet

  1. 默认表格展示名称/ID、总状态、认证、版本、标签、运营商、信号、关键异常、最后成功时间、延迟。
  2. 用户按 离线/需要认证/退化/陈旧 筛选，可叠加标签、版本、运营商、能力和文本搜索。
  3. 列排序和列显隐保留本地偏好；默认异常优先，卡片仅为可选视图。
  4. 点击异常单元格进入实例对应模块或状态详情，而不只进入泛化详情。
  5. 自动状态通过 SSE 更新；手动刷新请求 scheduler，不直接从浏览器扇出上游请求。

分支与恢复：

  • 初始 loading：表格骨架并保留列头，不显示“0 台”。
  • 整体刷新失败：保留上次数据并显示 stale banner、最后成功时间、requestId 和重试。
  • 单实例失败：只标该行；其他行仍更新。
  • 无匹配：区分未配置、搜索无结果和筛选无结果，提供对应动作。

验收： 使用项目章程 8.4的确定性 100 实例 fixture、计时与导航口径；筛选后目标位于首个 viewport，或最多一跳分页/行详情可见，不允许逐卡/逐行滚动寻找；部分失败不阻断成功行。

WF-03 查看实例与能力导航

角色： P1/P2
入口： /instances/:id/overview

  1. 顶部固定显示实例身份、总状态、认证、新鲜度和安全“原站打开”链接。
  2. 左侧/窄屏模块导航由 capability 决定：supported 可进入；degraded 带标记；unsupported 默认隐藏但可在“能力详情”查看原因；unknown 显示探测中/重试。
  3. overview 展示设备、SIM、蜂窝、系统资源和关键异常摘要，各卡链接到对应模块。
  4. 切换实例后，旧 instanceId 的请求被取消或因 owner/query key 不匹配而丢弃。

验收： 404 capability 不展示为 -；刷新页面可恢复相同实例与模块路由。

WF-04 执行 R1 可逆设置

例： 开关 data、roaming、WLAN 等可逆设置。具体 operation 风险、确认和执行方式以 117 项验收账本 引用的 OperationRegistry 为唯一事实源；例如 WLAN connect 为 R1，而 notifications config 为 R2 Job，不因出现在同一产品模块而套用统一风险。
角色： P1/P2

  1. 在业务页读取当前值和 fetchedAt。
  2. 编辑结构化表单；字段按 schema 校验。
  3. 提交前显示目标实例、当前→目标 diff、R1 影响。
  4. 若当前值 expired，则要求刷新或明确“基于陈旧数据继续”。
  5. 用户确认后 BFF 重新校验 operation、capability、revision 和请求 schema。
  6. 执行并写 audit；页面刷新目标资源并显示成功值。

失败恢复： 409/revision 变化重新加载 diff；401 引导登录；超时显示“结果未知”并通过后续读取核实，不直接宣称失败回滚。

WF-05 执行 R2/R3 单实例操作

例： operator register、band/cell lock、baseband restart、eSIM profile enable/delete、系统重启、OTA apply。
角色： P2/P3

  1. 用户在专用业务页选择动作和参数。
  2. BFF prepare 执行 capability、认证、当前状态、参数、冲突 Job 和可恢复性预检。
  3. UI 展示确认卡。R3 要求复述目标（如输入实例 ID 或 profile 名称）并说明不可逆/中断影响。
  4. prepare 只创建短期 Preparation；确认入口按章程规则消费一次性 token 后才创建 Job。R3 创建 Job，R2 默认创建 Job，返回 202 和稳定 jobId。仅满足 2.2 所述 OperationRegistry syncSafe 例外的单目标 R2 可同步返回结构化结果。
  5. Job 跳转或展开 /jobs/:jobId 并由 SSE 更新阶段和日志摘要；同步安全 R2 则在原业务页显示结果并关联 audit。
  6. Job 完成后刷新受影响资源，audit 关联 jobId/requestId。

失败恢复：

  • capability/revision/实例切换：token 作废，重新 prepare。
  • 执行中断连：Job 保持 running/unknown-result，按 operation 策略轮询验证，不重复执行非幂等动作。
  • 可重试失败：只开放 registry 声明的 retry；重新预检/确认且不复用旧 token，随后创建具有新 jobId 和独立 Attempt 的新 Job。新 Job 的 retryOfJobId 指向直接来源，rootJobId 指向最初 Job；来源 Job 及其 Attempt/事件保持终态不可变。Job/Attempt/Item 以项目章程 7.4为准。

WF-06 批量操作

角色： P1/P3
入口： /fleet 多选；只显示验收账本明确标记 fleetBatchable=true 的动作。上游 Registry 旧字段 batchable 仅表示单实例内的资源批量，不表示跨实例 Fleet 批量。

  1. 用户多选实例并选择业务动作。
  2. 系统逐实例预检 capability、认证、当前值和冲突 Job。
  3. 确认页分组显示“将执行 N、将跳过 M”，每个跳过项有原因。
  4. 用户确认后创建父 Job 和逐实例 items；并发受全局/实例上限控制。
  5. /jobs/:jobId 展示逐项 queued/running/succeeded/failed/skipped/cancelled。
  6. 取消只影响尚未开始或 registry 声明可取消的 item。
  7. 重试创建新的父 Job，只复制用户明确选择且 registry 判定可重试的失败 items；每个新 item 以 sourceJobItemId 指向来源 item。成功项绝不复制或重放，未选择/不可重试/skipped 项不进入新父 Job。新父 Job 使用新 jobId、独立状态和 Attempt，并通过 retryOfJobId/rootJobId 保留 lineage；SSE/audit 关联新 jobId + attemptId + jobItemId 并保留来源关联。

验收： 3 成功、1 失败、2 不支持的结果必须为 partially-succeeded，不能显示绿色“全部成功”。

WF-07 短信与通话

角色： P1
页面： /instances/:id/messages、/instances/:id/calls

  • 短信：统计/列表/会话 → 发送（号码与内容校验）→ 结果；删除消息/会话/批量清空按 R3 强确认并列出数量。
  • 通话：实时通话 → 拨号/接听/挂断 → 状态；音量/转移/设置结构化编辑；历史、IMS、voicemail 独立区域。通话记录支持单条和批量删除，均为 R3：确认页列出实例、记录 ID/对端号码、时间及数量，要求复述实例 ID（批量时同时复述数量），全部创建 Job；结果落到 /jobs/:jobId 的逐项结果并刷新通话历史，audit 仅保存脱敏号码摘要、数量、jobId/requestId，不保存敏感通话内容。
  • 实时状态与历史查询分离；拨号超时不自动重复。

验收： 发送或拨号时目标实例和号码始终可见；短信及通话记录删除不由通用 JSON 完成；通话记录删除必须有 R3 强确认、Job 详情和关联 audit 可追踪。

WF-08 eSIM 生命周期

角色： P2
页面： /instances/:id/esim

  1. 查看 work mode、eSIM config、lpac、eUICC 和 profiles capability。
  2. 下载 profile 时校验激活信息；其风险与执行方式按 Registry 当前值 R1/direct 验收，不在产品文档中另行升级。
  3. enable/rename 使用专用表单；enable 的 Registry 当前值为 R1/direct；切换工作模式按其 Registry R2/Job 政策说明连接影响。
  4. delete 为 R3：展示 ICCID/名称/状态，要求复述 profile，确认不可恢复。
  5. 完成后重新获取 profile 和 connectivity；失败保留上次 profile 数据并标 stale。

WF-09 OTA

角色： P3
页面： /instances/:id/ota

  1. 查看当前版本、commit、latest release、OTA 状态和 compatibility。
  2. 选择在线准备或本地包上传；上传使用专用流式接口并显示字节进度、校验和与取消。
  3. prepare 完成后显示包版本、目标版本、空间/电量/连接等上游可得预检。
  4. apply 为 R3 Job；确认中说明服务中断和重连窗口。
  5. 应用后以版本/health 重现作为完成证据；仅 HTTP 断开不能判成功。
  6. cancel 仅在上游状态允许时出现。

验收： 50MB body 不进入普通 JSON proxy、audit 正文或浏览器内存字符串化流程。

WF-10 Job 跟踪、取消与重试

角色： P1/P3
入口： /jobs、/jobs/:jobId

  1. 按状态、operation、实例、风险、时间筛选。
  2. 查看父 Job、items、阶段、尝试次数、requestId、耗时和最近事件。
  3. 可取消性由 operation/job 当前阶段决定；按钮不可用时解释原因。
  4. 重试先展示将重试的 items 和参数摘要；非幂等动作必须重新核实目标状态。
  5. 用户确认重试后创建新 Job，而不是重新打开来源 Job 或向其追加 Attempt；详情同时展示直接来源和根 Job lineage。
  6. 进程重启后 queued/running 任务按恢复策略标记并继续或进入需人工核实状态；已终态 Job、Attempt 和事件不得改变。
  7. Job 尚未终态时，仅幂等且 registry 明确允许的网络级内部重试可在同一 Attempt 内按次数/deadline/backoff 上限执行，并记录每次 transport try；非幂等操作及任何用户发起的 retry 均不得使用该机制。

WF-11 审计与复盘

角色： P4
入口： /audit、/audit/:eventId

  1. 按实例、operation、风险、结果、actor、requestId、jobId 和时间检索。
  2. 列表显示时间、目标、动作、风险、结果、耗时。
  3. 详情显示参数脱敏摘要、body digest、准备/确认/执行阶段、上游 HTTP/错误摘要。
  4. 从 audit 跳到 Job/实例模块；从 Job 返回关联 audit。
  5. 导出时沿用相同 redaction，不导出 password、cookie、token、短信正文等策略定义的敏感内容。

WF-12 认证失效恢复

角色： P1/P3

  1. 任一模块收到 401 时，将相关 capability 标 auth-required，但保留上次成功数据并标 stale。
  2. 顶部显示持久认证提示；用户可用保存凭据重登或输入一次性临时密码。
  3. 登录成功只重试安全的 R0 查询；不得自动重放写操作或 R1-S 会话操作。
  4. 返回原模块；原 R1–R3 草稿可保留，但必须重新 prepare/确认。

WF-13 两阶段删除实例

角色： P3；入口： /settings/instances/:id

  1. R3 prepare 展示 stable ID、canonical origin、关联 Job/审计保留范围及将销毁的 secret reference；确认消费 token 后创建删除 Job，并在同一事务把实例从 active|disabled 标为 deleting。
  2. deleting 后立即停止新轮询、R1-S 会话操作和所有新写操作，导航/Fleet 默认隐藏；Job 保存完成删除所需的不可变配置 snapshot 与 secret reference（不复制 secret）。
  3. 不可取消点定义为删除 Attempt 首次开始销毁 adapter/session 或 secret 的原子步骤；此前取消可回到原 active/disabled，此后取消按钮永久禁用，系统必须继续清理或进入人工处理。
  4. 不可取消点后先停止并删除 adapter/client/session，再销毁 SecretStore secret，随后清除业务配置并转为脱敏 tombstoned；tombstone 仅保留 stable ID/脱敏名称摘要、删除时间/actor、最终结果及 jobId/attemptId/audit 链路，不含 origin、凭据或业务 snapshot。
  5. purged 是后续保留期/管理员策略对 tombstone 业务字段的清理标记；purge 只清业务配置/残余脱敏展示字段，永不删除或改写审计记录。

失败恢复： 不可取消点前失败，事务恢复原 active/disabled 并恢复 scheduler；不可取消点后失败保持 deleting、禁止操作并标人工处理。若 registry 允许用户重试，须先核实 adapter/session/secret 各步骤状态，再创建具备 lineage 的新 Job；来源 Job/Attempt 保持终态不可变，且绝不重建或猜测 secret。

4. 页面状态验收模板

每个业务页至少验收以下状态：

状态 必须行为
初始 loading 保持页面结构和标题，控件禁用，不伪造空数据
success/fresh 显示值、采集时间和可用操作
empty 解释“确实为空”及下一动作，与 unsupported 区分
stale 保留最后数据，显示最后成功时间、失败原因、刷新入口
error 持久错误、requestId、重试；不只 toast
unsupported 能力解释、探测证据/版本；不显示可执行控件
auth-required 登录入口；不清空历史数据；不自动重放写请求
degraded/partial 标出失败子项，成功子项仍可用
forbidden by risk/policy 解释政策或前置条件，不提供通用代理绕过

5. 跨流程验收场景

  1. 实例切换竞态： A 页面慢请求未完成时切到 B；A 响应不得写入 B 页面或触发 B 的确认。
  2. 配置 revision 变化： prepare 后修改实例 URL；旧 token 执行必须失败。
  3. 部分失败： 批量 6 台中 2 台 unsupported、1 台 timeout；结果逐项保留且父 Job 为 partial。
  4. 认证过期： R2 prepare 后会话过期；执行不得自动登录后裸重放，必须重新预检/确认。
  5. 陈旧数据： 刷新失败时显示上次成功值和时间；用户能区分“当前未知”与“上次值”。
  6. 重启恢复： Job running 时重启 BFF；恢复后不重复执行非幂等上游操作，并提示核实状态。
  7. 敏感数据： 用 canary password/token/cookie 执行所有流程；响应、日志、audit、snapshot、fixture 和导出均无 canary。
Reference in New Issue View Git Blame Copy Permalink