Web 前端重写全量流程与交互图集 #1382

A-nony-mous · 2025-09-01T14:13:31Z

A-nony-mous
Sep 1, 2025

系统上下文 (C4 Level 1)
逻辑与部署分层
服务内部组件 / Bridge 适配层
核心运行 (一条龙) 全链路时序
运行状态机 & 事件模型
WebSocket 事件分类与广播路径
账户管理交互
配置与资源(模型)下载流程
增量更新 / 引导器策略
日志与遥测流向
任务取消 / 异常回退序列
前端页面模块装载/数据获取模式
渐进迁移阶段路线

1. 系统上下文 (C4 Level 1)

flowchart LR
    User["用户 / 玩家 / 运维"] -->|HTTP| WebClient["Web 前端 SPA"]
    User -->|HTTP| Electron["Electron 客户端"]
    subgraph Host[本地或远程主机]
        API["FastAPI 应用"]
        WS["WebSocket 服务"]
        Static["静态资源打包产物"]
        Biz["业务逻辑 ZContext"]
        RunReg["RunRegistry 任务状态"]
        Bridge["Bridge 适配层"]
        Telemetry["遥测日志管道"]
    end
    WebClient -->|REST /api/v1| API
    Electron -->|REST| API
    WebClient <-->|WS| WS
    Electron <-->|WS| WS
    API --> Bridge --> Biz --> RunReg --> WS
    Biz --> Telemetry --> WS
    API --> Static

2. 逻辑与部署分层

flowchart TB
    subgraph Presentation[表示层]
        FE["Web SPA"]
        ElectronApp["Electron 客户端"]
        Legacy["旧 GUI (退役)"]
    end
    subgraph Interface[接口层]
        Routers["FastAPI Routers"]
        WSHandler["WS 分发器"]
        Auth["鉴权令牌"]
    end
    subgraph BridgeLayer[Bridge 适配]
        DTO["DTO / Schemas"]
        Mapper["映射器"]
        Facade["门面 Facade"]
    end
    subgraph Domain[领域业务]
        ZCtx[ZContext]
        RunRegistry[RunRegistry]
        Executors[执行器]
        ConfigSvc[配置服务]
        AccountSvc[账户服务]
        ResourceSvc[资源服务]
        BattleSvc[战斗助手]
        HollowSvc[空洞迷失]
        PatrolSvc[巡回]
    end
    subgraph Infra[基础设施]
        FS[文件系统]
        Models[模型文件]
        External[外部公告]
        SystemRes[系统资源]
        TelemetryPipe[日志遥测]
    end
    FE --> Routers
    ElectronApp --> Routers
    Routers --> BridgeLayer --> Domain --> Infra
    WSHandler --> RunRegistry
    TelemetryPipe --> WSHandler

3. 服务内部组件 / Bridge 适配层

classDiagram
    class RouterRuns {
        +start_run()
        +cancel_run()
        +get_status()
    }
    class BridgeFacade {
        +to_domain(dto) -> domain_obj
        +from_domain(domain_obj) -> dto
        +coordinate(run_type, params)
    }
    class RunRegistry {
        +create(runId,type,params)
        +update(runId,status,progress,logs)
        +get(runId)
        +cancel(runId)
        +subscribe(runId,listener)
    }
    class Executor {
        +execute(runContext)
    }
    class ZContext
    class LogEmitter {
        +emit(level,message,runId?)
    }
    RouterRuns --> BridgeFacade
    BridgeFacade --> ZContext
    BridgeFacade --> RunRegistry
    RunRegistry --> Executor
    Executor --> LogEmitter
    LogEmitter --> RunRegistry

4. 核心运行 (一条龙) 全链路时序

sequenceDiagram
    autonumber
    participant FE as 前端
    participant API as POST /api/v1/runs/start
    participant Facade as BridgeFacade
    participant Ctx as ZContext
    participant RR as RunRegistry
    participant Exec as Executor(协程)
    participant WS as WS 分发
    FE->>API: start(payload)
    API->>Facade: 校验 + 构建 DomainInput
    Facade->>Ctx: 读取配置 / 校正参数
    Facade->>RR: create(runId,PENDING)
    RR-->>API: run meta
    API-->>FE: 200 {runId}
    RR->>Exec: schedule(runId)
    Exec->>RR: status=RUNNING
    RR-->>WS: event started
    loop 周期循环
        Exec->>RR: progress / log
        RR-->>WS: emit progress/log
    end
    Exec->>RR: status=COMPLETED
    RR-->>WS: event completed
    FE-->>WS: (已订阅接收事件)

5. 运行状态机 & 事件模型

stateDiagram-v2
    [*] --> PENDING
    PENDING --> RUNNING: schedule
    RUNNING --> COMPLETED: success
    RUNNING --> FAILED: exception
    RUNNING --> CANCELLED: user_cancel
    PENDING --> CANCELLED: cancel_before_start
    FAILED --> RETRYING: (可选 backoff)
    RETRYING --> RUNNING
    COMPLETED --> [*]
    CANCELLED --> [*]
    FAILED --> [*]

classDiagram
    class Event {string type; string timestamp; string runId?; object data}
    class Started
    class Progress
    class Log
    class Completed
    class Failed
    class Cancelled
    Event <|-- Started
    Event <|-- Progress
    Event <|-- Log
    Event <|-- Completed
    Event <|-- Failed
    Event <|-- Cancelled

6. WebSocket 事件分类与广播路径

flowchart LR
    subgraph Source[事件源]
    RR[RunRegistry 状态变更]
    LogQ[日志 / 遥测]
    SysEvt[系统事件 更新/错误]
    end
    RR --> Dispatcher[事件聚合 Dispatcher]
    LogQ --> Dispatcher
    SysEvt --> Dispatcher
    Dispatcher --> WSClients[已连接客户端]
    classDef cat1 fill:#eef,stroke:#447;
    classDef cat2 fill:#efe,stroke:#484;
    classDef cat3 fill:#fee,stroke:#844;
    RR:::cat1
    LogQ:::cat2
    SysEvt:::cat3

7. 账户管理交互

sequenceDiagram
    autonumber
    participant FE as 前端
    participant ACC as /accounts API
    participant Cfg as ConfigSvc
    participant Ctx as ZContext
    FE->>ACC: GET /accounts
    ACC->>Cfg: load list
    Cfg-->>ACC: accounts[]
    ACC-->>FE: 200 accounts[]
    FE->>ACC: POST /accounts {new}
    ACC->>Cfg: persist
    Cfg-->>ACC: ok
    ACC-->>FE: 201 created
    FE->>ACC: POST /accounts/{id}/activate
    ACC->>Ctx: switch_instance(id)
    Ctx-->>ACC: ok
    ACC-->>FE: 200 {activeId}
    ACC-->>WS: event account_switched

8. 配置与资源(模型)下载流程

flowchart LR
    FE -->|GET /resources/models| APIRes[资源路由]
    APIRes --> ResSvc[ResourceSvc]
    ResSvc --> FS[(本地缓存)]
    ResSvc --> RemoteRepo[(远程仓库/CDN)]
    RemoteRepo -->|下载+校验| ResSvc
    ResSvc -->|meta 路径 presigned| APIRes
    APIRes -->|JSON meta| FE
    FE -->|直连下载| CDN[(CDN)]

9. 增量更新 / 引导器策略

flowchart LR
    Launcher[轻量引导器 EXE] --> Check[检查 latest.json]
    Check -->|版本落后| FetchPatch[下载 patch/full]
    FetchPatch --> Verify[sha256 校验]
    Verify --> Stage[解压 staging/]
    Stage --> Replace[原子替换 app/]
    Replace --> Restart[提示或自动重启]
    Check -->|最新| LoadApp[加载 app/src]
    Launcher --> LoadApp

10. 日志与遥测流向

flowchart TB
    Exec[任务执行] --> LogEmitter[LogEmitter]
    LogEmitter --> Queue[(队列)]
    Queue --> Formatter[结构化格式化]
    Formatter --> FanOut{分发}
    FanOut --> WSLog[WS 推送]
    FanOut --> LocalFile[本地文件]
    FanOut --> TelemetrySink[(可选远程上传)]

11. 任务取消 / 异常回退序列

sequenceDiagram
    autonumber
    participant FE as 前端
    participant API as POST /runs/{id}/cancel
    participant RR as RunRegistry
    participant Exec as Executor
    participant WS as WS
    FE->>API: cancel(id)
    API->>RR: mark CANCEL_REQUESTED
    RR-->>Exec: cancellation flag
    Exec->>Exec: 检查点/安全中断
    Exec->>RR: status=CANCELLED
    RR-->>WS: event cancelled
    API-->>FE: 200

12. 前端页面模块装载/数据获取模式

flowchart TB
    RouteChange[路由切换] --> Guard[权限/实例就绪守卫]
    Guard --> CacheCheck{本地缓存有效?}
    CacheCheck -->|是| Render[渲染组件]
    CacheCheck -->|否| FetchSeq[并行拉取]
    FetchSeq --> REST[REST 批量接口]
    FetchSeq --> WSSub[WebSocket 订阅]
    REST --> Merge[合并初始状态]
    WSSub --> Merge
    Merge --> Render
    Render --> LiveUpdate[增量更新状态]

13. 渐进迁移阶段路线

gantt
    dateFormat  YYYY-MM-DD
    axisFormat  %m/%d
    title 渐进迁移 (示例时间占位)
    section 阶段1 基础
    FastAPI骨架          :done,    p1, 2025-08-15,2025-08-25
    RunRegistry+WS       :active,  p2, 2025-08-20,2025-09-05
    section 阶段2 核心接口
    一条龙完整接口       :p3, 2025-09-01,2025-09-15
    账户/设置/资源       :p4, 2025-09-01,2025-09-18
    section 阶段3 扩展
    战斗/空洞/巡回       :p5, 2025-09-16,2025-10-05
    Dev工具/助手         :p6, 2025-09-25,2025-10-10
    section 阶段4 前端
    SPA骨架+认证         :p7, 2025-09-05,2025-09-15
    Dashboard+Runs面板   :p8, 2025-09-12,2025-09-25
    其余页面迭代         :p9, 2025-09-20,2025-10-15
    section 阶段5 打包
    Electron集成         :p10, 2025-10-10,2025-10-20
    引导器增量更新       :p11, 2025-10-15,2025-10-25

设计要点速记

BridgeFacade 保持 “薄” —— 只做 DTO 映射 + 调度，不重写业务。
所有长任务统一 RunRegistry + 事件流，前端只做通用订阅渲染。
事件定义与状态机独立，便于扩展新事件而不破坏状态机逻辑。
前端首屏策略：缓存+批量拉取+WS 增量；降低首屏接口瀑布。
更新与资源拉取分离，减少耦合；更新失败不影响已下载模型的继续使用。

Navigation Menu

Repository navigation

Web 前端重写全量流程与交互图集 #1382

Uh oh!

{{title}}

Uh oh!

Replies: 0 comments

Select a reply

Uh oh!

Web 前端重写 全量流程与交互图集 #1382

Uh oh!

A-nony-mous Sep 1, 2025

1. 系统上下文 (C4 Level 1)

2. 逻辑与部署分层

3. 服务内部组件 / Bridge 适配层

4. 核心运行 (一条龙) 全链路时序

5. 运行状态机 & 事件模型

6. WebSocket 事件分类与广播路径

7. 账户管理交互

8. 配置与资源(模型)下载流程

9. 增量更新 / 引导器策略

10. 日志与遥测流向

11. 任务取消 / 异常回退序列

12. 前端页面模块装载/数据获取模式

13. 渐进迁移阶段路线

设计要点速记

Replies: 0 comments

Web 前端重写全量流程与交互图集 #1382

A-nony-mous
Sep 1, 2025