282 lines
19 KiB
Markdown
282 lines
19 KiB
Markdown
# 用户角色、任务与端到端流程
|
||
|
||
> 目标：以可执行用户任务约束页面、API、状态和风险交互，而不是从旧页面反推功能。
|
||
|
||
> Phase 0.1 文档导航：[返回项目章程](./project-charter.md)｜[现状审计](./current-system-audit.md)｜**角色与流程**（本文）｜[信息架构](./information-architecture.md)
|
||
|
||
## 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](./project-charter.md#76-三个正交页面状态)为准。
|
||
|
||
### 2.2 写操作确认卡
|
||
|
||
所有 R1–R3 在提交前至少显示：
|
||
|
||
```text
|
||
目标：实例名称 + 稳定 ID + URL origin
|
||
操作：业务名称 + operationId
|
||
当前值：结构化字段
|
||
目标值：结构化字段
|
||
变更：逐字段 diff
|
||
风险：R1 / R2 / R3 + 具体影响
|
||
支持性：capability 与上次探测时间
|
||
执行方式：立即 / Job / 批量逐项
|
||
```
|
||
|
||
R2/R3 还必须显示预检结果和失败阻断项；确认 token 的完整绑定、首次尝试即消费规则以[项目章程 7.3](./project-charter.md#73-确认令牌唯一规范)为唯一规范。若用户在确认期间切换实例、修改表单或配置发生变化，旧确认作废并回到预检。
|
||
|
||
执行政策统一为：R3 无例外全部创建 Job；R2 默认创建 Job。只有单目标 operation 被 OperationRegistry 显式标记 `syncSafe=true`，并登记同步安全理由及覆盖超时、结果落点和误重放的测试时，R2 才可同步执行；批量 R2 无论单项是否 `syncSafe` 都创建父 Job 和逐实例 item。
|
||
|
||
## 3. 关键流程
|
||
|
||
### WF-01 添加并验证实例
|
||
|
||
**角色：** P3<br>
|
||
**入口：** `/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<br>
|
||
**入口：** `/fleet`
|
||
|
||
1. 默认表格展示名称/ID、总状态、认证、版本、标签、运营商、信号、关键异常、最后成功时间、延迟。
|
||
2. 用户按 `离线/需要认证/退化/陈旧` 筛选，可叠加标签、版本、运营商、能力和文本搜索。
|
||
3. 列排序和列显隐保留本地偏好；默认异常优先，卡片仅为可选视图。
|
||
4. 点击异常单元格进入实例对应模块或状态详情，而不只进入泛化详情。
|
||
5. 自动状态通过 SSE 更新；手动刷新请求 scheduler，不直接从浏览器扇出上游请求。
|
||
|
||
**分支与恢复：**
|
||
|
||
- 初始 loading：表格骨架并保留列头，不显示“0 台”。
|
||
- 整体刷新失败：保留上次数据并显示 stale banner、最后成功时间、requestId 和重试。
|
||
- 单实例失败：只标该行；其他行仍更新。
|
||
- 无匹配：区分未配置、搜索无结果和筛选无结果，提供对应动作。
|
||
|
||
**验收：** 使用[项目章程 8.4](./project-charter.md#84-可重复验收协议与冻结责任)的确定性 100 实例 fixture、计时与导航口径；筛选后目标位于首个 viewport，或最多一跳分页/行详情可见，不允许逐卡/逐行滚动寻找；部分失败不阻断成功行。
|
||
|
||
### WF-03 查看实例与能力导航
|
||
|
||
**角色：** P1/P2<br>
|
||
**入口：** `/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 项验收账本](./operation-acceptance-matrix.md) 引用的 OperationRegistry 为唯一事实源；例如 WLAN connect 为 R1，而 notifications config 为 R2 Job，不因出现在同一产品模块而套用统一风险。<br>
|
||
**角色：** 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。<br>
|
||
**角色：** 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](./project-charter.md#74-preparationjob-与-attempt-固定模型)为准。
|
||
|
||
### WF-06 批量操作
|
||
|
||
**角色：** P1/P3<br>
|
||
**入口：** `/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<br>
|
||
**页面：** `/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<br>
|
||
**页面：** `/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<br>
|
||
**页面：** `/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<br>
|
||
**入口：** `/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<br>
|
||
**入口：** `/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。
|