SECS-ENDPOINT-ROLES.md

Host 与 Equipment 端点

角色与连接模式正交

SecsHost 和 SecsEquipment 表达 SECS 应用角色； HsmsConnectionMode.Active 与 Passive 只表达哪一端建立 TCP 连接。库不从其中一个推断另一个。

当前真实 TCP 回环持续验证以下两种常见拓扑：

Host	Equipment	已验证方向
Active	Passive	Host Primary/Equipment Secondary；Equipment Primary/Host Secondary
Passive	Active	Host Primary/Equipment Secondary；Equipment Primary/Host Secondary

这两种连接方向具有相同的动态消息和事务能力。角色不会改变 Select、T3、 T5、T6、T7、T8、Linktest 或运输重连语义。

端点所有权

每个角色端点拥有一个 HsmsConnection 和一个 HsmsPrimaryRouter，并公开以下组合能力：

• Start、等待 Selected、读取状态和单消费者事件流；
• 发送动态 Primary、手工回复未匹配 Primary；
• 运行期注册与分派 Primary 处理器；
• Linktest、Deselect 和 Separate；
• 异步释放整个端点。

释放角色端点会释放其连接。角色在构造后固定，连接方向、地址、协议 Session ID 和计时器仍通过显式 HsmsConnectionOptions 提供。

await using var equipment = new SecsEquipment(
    new HsmsConnectionOptions(
        IPAddress.Any,
        port: 5000,
        HsmsConnectionMode.Passive,
        sessionId: 0,
        t3,
        t5,
        t6,
        t7,
        t8));

using var route = equipment.RegisterPrimaryHandler(
    stream: 1,
    function: 1,
    HandleAreYouOnlineAsync);

equipment.Start();
await equipment.WaitUntilSelectedAsync(cancellationToken);

以上只展示 API 组合，消息含义和计时器值不是标准推荐或默认值。

能力边界

基础角色端点故意保持对称：Host 和 Equipment 都可能发起 Primary，也都 可能处理对端 Primary。独立 GEM 层通过依赖具体的 SecsHost 或 SecsEquipment 类型提供不同业务能力， 而不是修改 HSMS 状态机或根据 Active/Passive 猜测角色。

当前 GEM 切片已实现工程配置下的通讯建立、在线状态与应用转换策略、变量、 设备常量、时钟、报告定义、事件链接、Collection Event，以及最小报警通知 和远程命令； 报警目录查询支持运行期注册，Host 也可启停单个已注册报警的通知发送。 Host 与 Equipment 的 GEM 服务都可注册单一通讯建立策略；拒绝保留双方 既有通讯状态和对端身份，应用可在同一 Selected 会话显式重试。两侧也可 显式等待断线后的下一次 Selected 并发起一次通讯恢复；取消、拒绝或传输 失败不会启动后台重试，成功也不恢复断线前在线状态。Equipment 入站远程 命令、主动 Collection Event 和报警通知都可注册默认不启用的应用状态策略。 远程命令还支持运行期精确目录、全局回退和默认启用的逐项本地可用性；禁用 精确项不会进入全局回退。报警历史/批量控制、完整命令权限/参数 Schema/ 调度及自动恢复仍未实现。相关行为、事件循环要求和未核对边界见 GEM-FOUNDATION.md，项目不声明 GEM 合规。