313 lines
9.8 KiB
Markdown
313 lines
9.8 KiB
Markdown
# VSS 架构设计文档
|
||
|
||
> **作者**：Nitload-NSI
|
||
> **创建日期**：2026-03-17
|
||
> **所属项目**：StgSharp 框架 / 工业上位机架构预演
|
||
> **文档状态**：精简版草案
|
||
|
||
---
|
||
|
||
## 1. 文档定位
|
||
|
||
本文档用于说明 VSS 的整体架构思想、三层职责划分与层间关系。
|
||
具体类型定义、命名与边界，以《VSS 三层类型基座设计草案》为准。
|
||
|
||
当前版本需要特别强调一点：
|
||
State 层不再被描述为几个并列的中枢对象，而是对外统一表现为一个单例 `StateHost`。
|
||
|
||
---
|
||
|
||
## 2. 设计评估
|
||
|
||
把整个 State 层对外收敛为 `StateHost` 单例，是比旧描述更合理的做法。
|
||
|
||
原因有三点：
|
||
|
||
- 它明确了唯一中枢，避免旧版文档中的多个中枢概念同时被读成并列核心。
|
||
- 它明确了所有权，说明命令接入、状态抽象和服务管理都属于同一个运行时边界。
|
||
- 它更符合宿主型系统的实际组织方式，对外暴露一个主机，对内再展开结构，比暴露多个概念性中枢更稳定。
|
||
|
||
这个设计也有一个边界需要保留：
|
||
虽然 `ServiceManager` 现在被放入 `StateHost` 的下层，但这并不意味着状态与能力本体被混为一层。
|
||
`AppState` 仍然是状态抽象，`ServiceManager` 仍然只是服务管理结构，具体服务对象依然属于能力层。
|
||
|
||
另外，前侧命令链路只定义命令而不定义结果也是不完整的。
|
||
如果 `FrontCommandHost` 已经区分 `StateChangeCommand` 与 `ExecuteCommand`，那么还必须存在统一的 `CommandResult`，用于把执行完成状态回传给 View。
|
||
|
||
---
|
||
|
||
## 3. 架构总览
|
||
|
||
VSS 当前建议的核心结构如下：
|
||
|
||
View / Electron / HMI / 外设 / 其他宿主
|
||
↓
|
||
StateHost（单例）
|
||
├─ 上层：FrontCommandHost
|
||
├─ 中层：AppState
|
||
└─ 下层：ServiceManager
|
||
↓
|
||
Service / ServiceHost / 具体能力实例
|
||
|
||
这个结构表达的是：
|
||
|
||
1. 对外，State 层只有一个统一入口，即 `StateHost`。
|
||
2. 对内，`StateHost` 全息展开为上中下三层。
|
||
3. 服务能力通过 `ServiceManager` 被纳入统一调度，而不是直接散落在外部结构中。
|
||
|
||
其基本流程可以概括为：
|
||
|
||
1. 外部宿主产生交互或控制请求。
|
||
2. 请求进入 `StateHost`。
|
||
3. `StateHost` 的上层 `FrontCommandHost` 接收并区分 `StateChangeCommand` 与 `ExecuteCommand`。
|
||
4. `StateHost` 的中层 `AppState` 参与状态判断与状态更新。
|
||
5. 当命令涉及能力执行时，`StateHost` 的下层 `ServiceManager` 负责调度服务。
|
||
6. 命令处理完成后，`StateHost` 统一生成 `CommandResult` 回传给 View。
|
||
7. 状态变化与结果通知分别承担状态同步和执行完成通知两类职责。
|
||
|
||
---
|
||
|
||
## 4. View 层
|
||
|
||
### 4.1 定位
|
||
|
||
View 层是前侧交互来源的统一抽象。
|
||
它不等同于传统窗口或页面，而是所有外部交互入口与宿主环境的集合。
|
||
|
||
View 层只负责两件事：
|
||
|
||
- 承接交互
|
||
- 将交互转化为命令并送入 `StateHost`
|
||
|
||
同时，View 还需要能够接收由 `StateHost` 回传的 `CommandResult`，从而知道某次执行型命令是否已经完成。
|
||
|
||
它不再承担中枢职责，也不直接持有服务调度责任。
|
||
|
||
### 4.2 基础类型
|
||
|
||
#### ViewHost
|
||
|
||
`ViewHost` 是前侧宿主的统一抽象，用于表示任何可以承接界面表现、输入来源或外部交互来源的宿主对象。
|
||
|
||
#### StateChangeCommand
|
||
|
||
`StateChangeCommand` 用于表达对系统状态的直接修改请求。
|
||
|
||
#### ExecuteCommand
|
||
|
||
`ExecuteCommand` 用于表达需要进入执行流程的命令请求。
|
||
|
||
#### CommandResult
|
||
|
||
`CommandResult` 用于表达某次前侧命令处理完成后的统一结果通知。
|
||
|
||
### 4.3 小结
|
||
|
||
View 层的职责不是承载业务逻辑，而是把复杂、多样、异构的交互来源收敛成稳定命令，然后统一送入 `StateHost`。
|
||
|
||
对于执行类命令，View 不能只依赖状态变化判断是否结束，还应通过 `CommandResult` 获得明确的完成通知。
|
||
|
||
---
|
||
|
||
## 5. State 层
|
||
|
||
### 5.1 定位
|
||
|
||
State 层是 VSS 的唯一状态与调度中枢。
|
||
它对外统一表现为 `StateHost` 单例，对内展开为三层结构。
|
||
|
||
### 5.2 内部结构
|
||
|
||
#### StateHost
|
||
|
||
`StateHost` 是 State 层唯一对外暴露的运行时主机。
|
||
|
||
它负责：
|
||
|
||
- 接收来自外部宿主的命令
|
||
- 统一组织命令接入、状态抽象和服务管理
|
||
- 统一处理状态同步、事件广播、服务结果回流和 `CommandResult` 回传
|
||
|
||
#### 上层：FrontCommandHost
|
||
|
||
`FrontCommandHost` 是 `StateHost` 的上层，用于承接前侧命令输入。
|
||
它属于 State 内部结构，不再被视为 View 层自己的中介中心。
|
||
|
||
在命令协议上，`FrontCommandHost` 至少要面对两类前向命令：
|
||
|
||
- `StateChangeCommand`
|
||
- `ExecuteCommand`
|
||
|
||
对应地，State 在处理完成后还需要回传统一的 `CommandResult`。
|
||
|
||
#### 中层：AppState
|
||
|
||
`AppState` 是 `StateHost` 的中层状态抽象，是全局状态树根。
|
||
它代表状态本体，而不是状态宿主。
|
||
|
||
#### 下层：ServiceManager
|
||
|
||
`ServiceManager` 是 `StateHost` 的下层服务管理结构。
|
||
它负责把命令向下转化为具体能力调度，并将结果回流状态体系。
|
||
|
||
#### 配套结构
|
||
|
||
State 层还包括：
|
||
|
||
- `PanelState`，用于表示局部状态单元
|
||
|
||
此外，observer 语义仍然存在，但在 `StgSharp.UserInterface` 中不再通过 `OnStateChanged` / `StateChangeObserver` 这类手写公共类型表达。
|
||
|
||
这里更准确的说法是：状态写入后的轻量 observer 逻辑，改为由源生成器围绕具体状态节点直接分布式织入。
|
||
|
||
在传统 MVVM 中，observer 往往同时承担：
|
||
|
||
- 内部逻辑回调
|
||
- VM 内部广播变化
|
||
- 通知 View 重绘
|
||
- 通知 Data / 业务执行
|
||
|
||
而在 VSS 中，这四项职责被拆开处理：
|
||
|
||
- 内部逻辑回调：由 Service 或具体业务实现承担
|
||
- VM 内部广播变化：由源生成器生成的轻量 observer hook 承担
|
||
- 通知 View 重绘：由 command/result 与同步符号链路承担
|
||
- 通知 Data / 业务执行：由 command/result 与 service 调度承担
|
||
|
||
其中 `CommandResult` 仍用于通知某次命令已经处理完成。
|
||
|
||
### 5.3 小结
|
||
|
||
State 层现在应被理解为一个统一主机，而不是多个同级中心。
|
||
`StateHost` 对外是单例边界，对内则由 `FrontCommandHost`、`AppState` 和 `ServiceManager` 三层共同构成。
|
||
|
||
---
|
||
|
||
## 6. Service 层
|
||
|
||
### 6.1 定位
|
||
|
||
Service 层仍然是系统能力的承载层，但其管理入口已经被明确收敛到 `StateHost` 的下层 `ServiceManager`。
|
||
|
||
因此，Service 层关注的重点是：
|
||
|
||
- 被调度的具体服务对象
|
||
- 服务装载与完成事件
|
||
- 服务运行宿主与能力实例
|
||
|
||
Service 内部完成事件可以回流到 `StateHost`，但前侧最终接收到的仍应是统一的 `CommandResult`，而不是直接暴露服务内部事件。
|
||
|
||
### 6.2 基础类型
|
||
|
||
#### ServiceLoadCommand
|
||
|
||
`ServiceLoadCommand` 用于表达服务装载请求。
|
||
|
||
#### ServiceLoadAccomplishmentEvent
|
||
|
||
`ServiceLoadAccomplishmentEvent` 用于表达服务装载完成后的结果通知。
|
||
|
||
#### ServiceHost
|
||
|
||
`ServiceHost` 用于表达某一类服务实例的直接宿主或执行载体。
|
||
|
||
### 6.3 小结
|
||
|
||
`ServiceManager` 属于 State 的下层管理结构，而 `ServiceHost` 与具体服务实例才属于能力层主体。
|
||
这样可以在统一调度和能力解耦之间保持清晰边界。
|
||
|
||
---
|
||
|
||
## 7. 层间关系
|
||
|
||
### 7.1 View → State
|
||
|
||
View 层通过命令把交互送入 `StateHost`。
|
||
命令首先由 `FrontCommandHost` 接入，再由 `StateHost` 统一协调后续动作。
|
||
当前前侧协议至少应包含：
|
||
|
||
- `StateChangeCommand`
|
||
- `ExecuteCommand`
|
||
- `CommandResult`
|
||
|
||
### 7.2 State 内部关系
|
||
|
||
State 内部的关系是：
|
||
|
||
- 上层 `FrontCommandHost` 负责接命令
|
||
- 中层 `AppState` 负责持状态
|
||
- 下层 `ServiceManager` 负责管服务
|
||
|
||
三者共同组成一个统一的 State 运行时主机。
|
||
|
||
### 7.3 State → Service
|
||
|
||
当命令涉及能力执行时，`StateHost` 通过下层 `ServiceManager` 调度服务对象。
|
||
服务执行结果再统一回流 `StateHost`，由其决定状态更新与通知广播。
|
||
对于 View 而言，某次执行是否完成，应以 `CommandResult` 为准，而不是直接依赖服务内部事件。
|
||
|
||
---
|
||
|
||
## 8. 与 MVVM 的区别
|
||
|
||
相较于 MVVM，VSS 更强调统一运行时主机，而不是围绕界面绑定建立系统中心。
|
||
|
||
主要区别在于：
|
||
|
||
- MVVM 通常以界面和 ViewModel 配合为中心，VSS 以 `StateHost` 为唯一中枢
|
||
- MVVM 更适合界面驱动型应用，VSS 更适合多输入源、多宿主、强状态调度的软件
|
||
- VSS 明确区分状态本体、命令接入和服务管理，但又把它们统一收束在同一个 State 边界内
|
||
|
||
---
|
||
|
||
## 9. 适用场景
|
||
|
||
VSS 更适合以下场景：
|
||
|
||
- 工业上位机
|
||
- 多输入源 HMI
|
||
- 仿真与控制软件
|
||
- 支持无头运行的软件
|
||
- 需要多宿主接入的系统
|
||
|
||
对于纯数据展示、轻量表单或前端页面驱动型应用，MVVM 仍可能是更直接的选择。
|
||
|
||
---
|
||
|
||
## 10. 当前建议保留的最小类型清单
|
||
|
||
### View 层
|
||
|
||
- `ViewHost`
|
||
- `StateChangeCommand`
|
||
- `ExecuteCommand`
|
||
- `CommandResult`
|
||
|
||
### State 层
|
||
|
||
- `StateHost`
|
||
- `FrontCommandHost`
|
||
- `AppState`
|
||
- `PanelState`
|
||
- `ServiceManager`
|
||
|
||
### Service 层
|
||
|
||
- `ServiceLoadCommand`
|
||
- `ServiceLoadAccomplishmentEvent`
|
||
- `ServiceHost`
|
||
|
||
---
|
||
|
||
## 11. 结论
|
||
|
||
VSS 的重点不在于先定义某一种具体界面实现，而在于先定义稳定的运行时骨架。
|
||
在当前阶段，更准确的表达应当是：
|
||
|
||
- View 层负责交互来源
|
||
- State 层对外统一表现为 `StateHost` 单例
|
||
- `StateHost` 对内全息展开为 `FrontCommandHost`、`AppState`、`ServiceManager` 三层
|
||
- 前侧命令协议由 `StateChangeCommand`、`ExecuteCommand`、`CommandResult` 构成闭环
|
||
- Service 层负责承载被调度的具体能力对象
|
||
|
||
这一定义比旧版本更清楚地表达了唯一中枢、运行时边界和内部层次关系。 |