负责 Incident 记录、运维指标、告警/SLA 读模型,以及 Webhook/CAP 恢复、配置热刷新和 Host 服务重启的受控操作端口。
一张图读懂主路径
珊瑚色节点表示本模块的核心决策或状态边界。
能力边界
- 没有受保护状态机的 Incident 严重度、状态记录与 JSON 备注快照
- 通过 owner Port 提供租户 Webhook 死信视图与全局 CAP 故障操作
- 当前进程指标,以及受控配置热刷新与服务重启契约
模块明确不包含:Incident、指标、告警与 SLA 持久化归模块本地。Webhook、CAP、配置提供器与服务编排仍归各自 owner 或 adapter;只有失败关闭 Port 不足以证明操作可达。
代码地图
| 项目 | 主要职责 |
|---|---|
BitzOrcas.Platform.OpsExtension.Contracts | 公开契约、端口、DTO 与事件 |
BitzOrcas.Platform.OpsExtension.Application | 命令、查询、处理器与应用策略 |
BitzOrcas.Platform.OpsExtension.Infrastructure | 持久化、连接器与框架适配器 |
源码位置: src/Platform/OpsExtension
核心用例
CreateIncidentUpdateIncidentStatusRetryDeadLetterRetryCapFailedMessageReloadConfigRestartServiceCommandGetRuntimeMetricsGetObservabilitySeriesQuery
阅读用例时,先看请求契约和权限声明,再跟进处理器调用的聚合或端口,最后检查提交后的事件、缓存和审计。
关键模型与契约
| 关键类型 | 阅读重点 |
|---|---|
IncidentRecord | 运维事件状态 |
IOpsExtensionStore | 事件与读模型端口 |
ICapRetryPort | CAP 重试适配器 |
IConfigReloadPort | 配置热刷新适配器 |
IHostServiceRestartPort | 服务编排适配器 |
用例边界示例
| 字段 | 说明 |
|---|---|
| 代表性契约 | RetryDeadLetterCommand |
| 返回结果 | Result |
| 审查重点 | 使用可信租户与 Webhooks owner 重试 Port;不要虚构当前源码并未持久化的 retry-attempt 聚合。 |
示例伪代码
var tenantId = currentUser.User.TenantId;var actorKey = currentUser.User.ActorUserId;var deliveryId = command.DeliveryId.Trim();// ① 敏感操作先过审批门:ApprovalTicket 无效即拒绝(DeliveryFailureApprovalRequired)。if (!await approvalGate.ValidateAsync(command.ApprovalTicket, cancellationToken)) return Result.Failure(OpsExtensionErrors.DeliveryFailureApprovalRequired);// ② 动作前先落意图审计;意图审计写不进去则整体失败关闭(DeliveryFailureAuditUnavailable)。var intentPersisted = await DeliveryFailureAudit.TryRecordAsync(activityAuditSink, new ActivityRecord("DeliveryFailure.Webhook.Retry.Intent", actorKey, tenantId, true, $"delivery={deliveryId}", command.ApprovalTicket, clock.UtcNow), logger, cancellationToken);if (!intentPersisted) return Result.Failure(OpsExtensionErrors.DeliveryFailureAuditUnavailable);// ③ 意图落库后才执行真实重投:Adapter 重入 WebhookDeliveryService,保留 owner guard。var retry = await webhookRetry.RetryAsync(tenantId, deliveryId, cancellationToken);var outcome = retry.IsSuccess ? retry.GetValueOrThrow().Status : retry.Error.Code;// ④ 完成审计使用 CancellationToken.None:即使请求中止也必须留下处置结果。var completionPersisted = await DeliveryFailureAudit.TryRecordAsync(activityAuditSink, new ActivityRecord("DeliveryFailure.Webhook.Retry.Completed", actorKey, tenantId, retry.IsSuccess, $"delivery={deliveryId},outcome={outcome}", command.ApprovalTicket, clock.UtcNow), logger, CancellationToken.None);// ⑤ 真实重投失败优先返回其错误;完成审计缺失则以 OutcomeUnknown 显式暴露未知态。if (retry.IsFailure) return Result.Failure(retry.Error);if (!completionPersisted) return Result.Failure(OpsExtensionErrors.DeliveryFailureOutcomeUnknown);return Result.Success(retry.GetValueOrThrow());集成关系
Webhook 与 CAP 有具体适配器;配置刷新取决于 AgileConfig,服务重启委托外部编排器而不是杀死 API 进程。操作 Port 不可用时统一失败关闭。
跨模块协作遵循以下方向:
- 调用方依赖本模块公开 Contracts 或窄端口。
- 状态变化通过版本化集成事件传播。
- 具体数据库、消息、缓存、文件或厂商 SDK 留在 Infrastructure。
- 组合根先注册失败关闭默认实现,再接入生产适配器。
安全、租户与隐私
权限目录已经按 Read/View/Manage 与授权动作对齐,并由 Governance Generator 收集。仍需注意:operations.extension 虽声明为默认关闭,当前用例没有运行时 Feature 门控;Incident 的 Resolved/Closed 也不足以单独充当敏感运维动作的审批证据。
模块保存租户数据时必须写入 TenantId,列表和详情使用同一授权规则。日志、事件和审计只保留诊断所需字段。
失败语义、幂等与可观测性
Webhook 重试重新进入 owner 投递逻辑,CAP 重试条件重置基础表;审计失败当前可能覆盖已经完成的动作结果。
| 情况 | 处理原则 |
|---|---|
| 校验、未找到、冲突或禁止 | 返回类型化 Result/Error,并由统一映射生成 Problem Details |
| 适配器或关键状态不可用 | 安全或高价值操作失败关闭;只读降级必须显式标记 |
| 重复请求或重复事件 | 使用稳定幂等键,数据库唯一约束作为最后防线 |
| 外部超时 | 传播取消,记录脱敏诊断,仅对安全操作执行有界重试 |
测试矩阵
| # | 必须覆盖 | 建议层级 |
|---|---|---|
| 1 | 全部 32 条生成端点声明与精确权限码 | 单元 + 集成 |
| 2 | 跨租户 Incident/Webhook 访问 | 集成/契约 |
| 3 | Webhook/CAP 重放与适配器失败 | 集成/契约 |
| 4 | Incident 并发、审批绑定与审计双重失败 | 集成/契约 |
测试还要固定一条通用红线:租户 A 的标识、缓存键、事件或查询条件不能让租户 B 读取或修改数据。
源码导航与变更检查
在 BitzOrcasVNext 仓库根目录运行:
# 列出公开类型,确认新增契约是否真的属于模块边界。rg -n "^public (sealed |abstract |static |partial )*(record|class|interface|enum)" src/Platform/OpsExtension -g '*.cs'
# 检查跨层引用;调用方不应依赖另一个模块的 Infrastructure。rg -n "ProjectReference|PackageReference" src/Platform/OpsExtension -g '*.csproj'
# 查找待补实现和省略式代码;预期没有命中。rg -n "TODO|FIXME|// \.\.\.|省略" src/Platform/OpsExtension -g '*.cs'扩展与发布检查
- 新能力是否由明确的 Contracts、权限和 Feature Key 表达?
- 持久化、连接器和 Provider 是否可以通过窄适配器替换?
- 生产组合是否仍命中 Null/Unavailable 默认实现?健康检查会不会误报绿色?
- 事务、事件、缓存失效、审计和后台任务是否有失败与重试证据?
- 中英文文档、图表、契约测试和运维手册是否随代码一起更新?