# Incident / Remediation 优化与重构计划 ## 1. 背景 当前 Incident 与 Remediation 相关能力分布在两个项目中： - 前端：`management-portal-ui` - 后端：`devops-work/devops-work` 从现有实现看，这两套能力已经具备完整可用的业务闭环： - Incident 列表、详情、编辑 - Incident timeline / log - Incident postmortem TODO action - 从 Incident 发起 Remediation Ticket - Remediation Ticket 的审批流、阶段流转、详情展示 但随着功能累积，这块系统已经呈现出明显的结构性债务。当前问题不是单点 bug，而是领域模型、流程定义、前后端职责、数据结构和 UI 组织方式都逐步发生了漂移。 本计划文档的目标是： - 梳理 Incident / Remediation 当前实现现状 - 明确现有问题和技术债 - 给出分阶段优化与重构方案 - 降低未来变更成本，提高一致性和可维护性 ## 2. 现状总览 ### 2.1 Incident 当前职责 Incident 目前承担了以下职责： - 事故基础元信息管理 - Timeline / log 记录 - 事故详情页展示 - Postmortem 文档入口 - Postmortem TODO action 管理 - Remediation Ticket 的发起入口 从产品语义上看，Incident 是事故主实体。 ### 2.2 Remediation 当前职责 Remediation Ticket 目前承担了以下职责： - 基于 Incident 发起客户补偿/补救流程 - 记录跨角色阶段性输入信息 - 维护审批流与状态流转 - 展示当前阶段、责任人、审批记录 - 生成最终 remediation 文档 从产品语义上看，Remediation 是围绕 Incident 展开的独立流程实体。 ### 2.3 两者当前关系 当前两者的关系是： - 一个 Incident 可以对应多个 Remediation Ticket - Remediation Ticket 通过 `associated_incident_id` 关联 Incident - 从 Incident Postmortem 页面跳转发起 Remediation - Remediation 详情页会回显关联 Incident 的摘要信息 这个关系本身是合理的，但当前实现仍然比较松散，更多是“前端跳转 + ID 关联”，而不是一套清晰的领域协作模型。 ## 3. 当前实现中的主要问题 ## 3.1 领域字典和状态定义没有单一真源 ### 现象 Incident 和 Remediation 的状态、阶段、字段语义在多个位置重复维护： - 后端 entity - 后端 model - 后端 phase / actor - 前端页面常量 - 前端表单逻辑 其中已经存在实际漂移： - 根据当前代码路径，`GET /api/v1/devops/incidents/:id` 会将数据库中的 `status` 字符串原样透传给前端；前端页面当前使用的是 `ongoing / post-mortem / under-improvement / archived` - 但后端 `entity/incident.go` 里仍保留了旧的 `running/completed` 枚举，说明领域定义与实际接口行为已经发生漂移 - Remediation phase 在前端 `phases.tsx` 维护一套展示与输入定义 - 后端 `phase/*.go` 再维护一套阶段流转和校验逻辑 ### 问题 - 新增或调整状态时容易漏改 - 前后端容易对同一字段产生不同理解 - 代码阅读成本高，排查问题需要来回对照 - 未来做国际化、配置化、低代码化都很困难 ### 优化方向 - 建立 Incident / Remediation 的统一领域字典 - 后端输出枚举、阶段元数据和字段定义 - 前端不再硬编码 phase/status/component/todo-status ## 3.2 Incident 的领域边界过宽，内部仍偏“松散 CRUD” ### 现象 Incident 模块看似是一个完整领域，但内部其实是多套并列 CRUD： - incident 主表 - incident log - postmortem - postmortem timeline - postmortem todo action 这些能力虽然围绕 Incident 展开，但后端大部分仍是直接 CRUD，领域动作和状态约束较弱。 同时，incident validation 很薄，缺少真正的业务约束。 ### 问题 - Incident 状态流转缺乏统一规则 - 很多页面逻辑只能靠前端控制，而不是后端保障 - TODO action、postmortem、timeline 之间缺少统一抽象 - 后续要引入自动化、审计、策略控制时成本很高 ### 优化方向 - 把 Incident 从“资源集合”收敛为“领域对象” - 以领域动作替代自由更新 - 明确状态机、可执行动作、字段可编辑范围 ## 3.3 Remediation 状态机实现分散，维护成本高 ### 现象 Remediation 的核心逻辑散落在多处： - `phase/*.go` 负责每个 phase 的校验和下一跳 - `actors/*.go` 负责状态下的行为 - `helpers/helpers.go` 负责责任人分配 - 前端 `phases.tsx` 负责展示、表单字段、checklist - 配置文件负责 phase 对应的责任人邮箱 这本质上是“一套流程系统”，但当前实现是分散的命令式代码。 ### 问题 - 修改一个 phase 需要同时改前端、后端、配置 - 很难快速回答“某个阶段到底需要哪些字段、由谁审批、下一步去哪” - 流程变更容易引入隐蔽回归 - 难以做可视化配置、流程审计、测试覆盖 ### 优化方向 - 将 Remediation 重构为声明式 workflow - 用统一 phase definition 驱动： - 字段输入 - 校验 - 审批人选择 - 下一阶段路由 - 前端 step / form / checklist 展示 ## 3.4 前端与后端职责划分不清，页面层承载过多业务逻辑 ### 现象 前端页面中存在大量业务规则： - Incident status 文本映射 - known components 列表 - Remediation 每个 phase 的字段定义 - phase 的审批 checklist - 表单和接口字段间的手工转换 同时，前端还在做一些明显属于领域层的数据转换，例如： - `components` 用空格拼接和拆分 - `biz_regions` 用字符串 join / split - `jira_issues` 用字符串 join / split ### 问题 - 前端很难保持与后端一致 - 页面组件承担了过多非 UI 逻辑 - 复用性差，测试成本高 - 同样的语义在多个页面重复实现 ### 优化方向 - 让后端返回面向 UI 的稳定 DTO - 前端只负责渲染和交互，不负责“猜业务语义” - 抽离页面级配置，避免在组件内硬编码领域信息 ## 3.5 数据模型表达力不足，存在“字符串拼接式建模” ### 现象 Incident 中有多个字段仍然采用“字符串拼接”的方式表达多值属性，例如： - `components` - `biz_regions` - `jira_issues` Remediation 中也存在一些语义接近但层次不清的字段： - `phase` - `status` - `appr_id` - `current_responsible_person_email` - 多个阶段性字段直接平铺在 ticket 主表上 ### 问题 - 数据结构不自描述 - DTO、entity、model 之间需要大量转换 - 很难约束字段合法性 - 检索、统计、演进都不方便 ### 优化方向 - Incident 的多值字段改为结构化表达 - Remediation 的阶段输入信息考虑引入“phase payload”抽象 - 降低主表字段膨胀程度 ## 3.6 Incident TODO 与 Remediation 的边界合理，但协作模型不清晰 ### 当前理解 这两者不是重复系统，而是两类不同动作： - Incident Postmortem TODO - 面向内部整改 - 更偏执行项和跟踪项 - 常与 Feishu task 联动 - Remediation Ticket - 面向客户补偿/补救 - 更偏阶段审批与跨角色协作 - 有更严格的 phase / approval 逻辑 ### 当前问题 虽然边界合理，但协作关系不清晰： - 哪些场景应该建 TODO，哪些场景应该发 remediation，没有系统引导 - Remediation 是否应该引用某个 TODO action，目前没有模型表达 - 用户只能从页面经验中理解，不容易形成稳定心智模型 ### 优化方向 - 在产品和数据模型中明确两者关系 - 定义 Incident 后续动作体系 - 让 UI 更清晰地表达“整改动作”和“客户补偿流程”的区别 ## 3.7 Remediation 责任人分配策略过于静态 ### 现象 当前责任人主要由配置文件中的固定邮箱决定： - 按 biz region 分配 Region TSE Leader - 按 cluster type 分配 RDG SLA Owner - 其他阶段配置固定负责人 ### 问题 - 组织变化时维护成本高 - 容易形成单点依赖 - 无法很好支持轮值、代理、临时授权等场景 ### 优化方向 - 中长期引入“角色 -> 人员解析”机制 - 将责任人配置从单人邮箱升级为角色/组/策略 ## 3.8 审批流和业务流耦合方式仍偏底层 ### 现象 当前 remediation 通过 approval service 驱动 phase 流转，这个方向本身是对的。 但当前 ticket 内部需要同时维护： - `status` - `phase` - `appr_id` - `current_responsible_person_email` 审批记录又额外落在 `remediation_ticket_approvals` 表中。 ### 问题 - 阅读和调试时，需要同时理解 ticket、approval、ticket_approval 三套信息 - phase 推进的真实来源不够直观 - 对幂等、重试、并发版本控制的处理零散 ### 优化方向 - 把 approval 视为 workflow engine 的一个节点能力 - 统一 ticket 当前状态和审批状态的投影视图 - 建立更明确的 transition event 记录 ## 4. 重构目标 本次优化不建议只做零散修补，而应围绕以下目标推进： ### 4.1 统一领域语言 建立 Incident / Remediation 的统一术语、状态、阶段、字段字典。 ### 4.2 统一流程定义 让 Remediation 的 phase、校验、下一跳、责任人、前端展示来自同一套定义。 ### 4.3 统一前后端契约 减少前端硬编码和 join/split 适配，后端输出稳定且结构化的 DTO。 ### 4.4 降低未来变更成本 使新增阶段、调整流程、增加字段、改审批人等变更可以低风险完成。 ### 4.5 为后续产品扩展做准备 包括但不限于： - 更多 remediation 类型 - 更复杂的审批路由 - incident 后续动作统一视图 - 更强的审计和报表能力 ## 5. 优化方案 ## 5.1 方案一：统一 Incident / Remediation 领域字典 ### 目标 建立单一真源，消除前后端漂移。 ### 做法 - 后端新增统一元数据定义模块 - 输出以下配置或 API： - incident status 列表 - incident tier 列表 - remediation phase 列表 - remediation phase label - todo status 列表 - component options - 前端页面全部改为消费该元数据 ### 收益 - 所有页面展示一致 - 枚举变更不再多处修改 - 为 workflow 配置化打基础 ## 5.2 方案二：Incident 从 CRUD 聚合升级为状态化领域对象 ### 目标 把 Incident 变成受控领域对象，而不是任意字符串资源。 ### 做法 - 明确 incident 生命周期 - 引入后端领域动作： - 创建 incident - 更新事故基础信息 - 追加事件 - 开始 postmortem - 归档 incident - 发起 remediation - 将更新入口从“随意 PUT 任意字段”逐步收敛为命令式接口 ### 收益 - 状态流转更清晰 - 权限控制更自然 - 后续自动化更容易接入 ## 5.3 方案三：将 Remediation 重构为声明式 Workflow ### 目标 将现在散落在 phase、actor、前端页面中的规则收口成一套声明式配置。 ### 建议抽象 每个 phase 至少描述： - phase id - label - 是否终态 - 可填写字段 - 字段校验 - approval checklist - 责任人解析策略 - 下一阶段路由规则 ### 后端落地 - phase engine 基于 definition 执行 - actor 简化为通用 transition executor - approval 成为 workflow node 的一种实现 ### 前端落地 - step 组件、详情渲染、表单渲染全部基于同一份 phase definition ### 收益 - 流程变更成本显著下降 - 前后端一致性大幅提升 - 更容易补测试 ## 5.4 方案四：重构数据模型，去掉字符串拼接式字段 ### Incident 建议改造： - `components`: 从拼接字符串改为结构化数组或关联表 - `biz_regions`: 从拼接字符串改为结构化数组 - `jira_issues`: 从拼接字符串改为结构化数组 ### Remediation 建议改造： - 将每个阶段特有字段从“主表平铺”逐步演进为 `phase_payload` - 保留当前主表字段作为兼容层，分阶段迁移 ### 收益 - DTO 更稳定 - 前端不再做拆拼接 - 查询和统计更方便 ## 5.5 方案五：明确 Incident TODO 与 Remediation 的产品关系 ### 目标 让用户和系统都能清楚区分： - 内部整改动作 - 客户补偿/补救动作 ### 做法 - 在 Incident 页面中将“TODO Actions”和“Remediation Tickets”并列展示 - 在文案和交互上明确： - TODO 用于内部行动项 - Remediation 用于客户补偿流程 - 视业务需要增加： - remediation 的发起原因 - remediation 与某些 action item 的引用关系 ### 收益 - 降低用户困惑 - 更利于报表和管理 ## 5.6 方案六：升级责任人解析机制 ### 短期 - 保留当前配置方式 - 将单个邮箱升级为“候选组 / 角色配置” ### 中期 - 接入组织角色、用户组、轮值信息 - 支持按 region、cluster type、业务线等规则动态解析 ### 收益 - 降低运维成本 - 降低单点人员依赖 ## 6. 分阶段实施计划 ## 6.1 第一阶段：低风险治理 ### 目标 先做“统一定义”和“收口重复逻辑”，不大改数据库和主流程。 ### 范围 - 清理过时枚举和命名漂移 - 建立统一 metadata 输出 - 前端去掉硬编码 status / phase / component - 梳理 Incident 与 Remediation API DTO - 加强后端 validation ### 预期收益 - 一致性明显提升 - 后续重构风险降低 ## 6.2 第二阶段：流程收敛 ### 目标 把 Remediation 现有状态机收口为声明式 workflow。 ### 范围 - 统一 phase definition - 后端改造 phase/actor - 前端改为 schema-driven 渲染 - 责任人解析逻辑抽象化 ### 预期收益 - 流程变更成本明显下降 - 可维护性大幅提升 ## 6.3 第三阶段：模型重构 ### 目标 解决字符串拼接式字段和主表膨胀问题。 ### 范围 - Incident 多值字段结构化 - Remediation phase payload 抽象 - DTO / entity / model 统一命名和边界 ### 预期收益 - 数据结构更稳 - 前后端转换逻辑显著减少 ## 6.4 第四阶段：产品层重塑 ### 目标 让 Incident 后续动作体系更清晰。 ### 范围 - Incident 页面中统一展示： - timeline - postmortem - todo actions - remediation tickets - 明确发起 remediation 的条件、原因和上下文 ### 预期收益 - 用户认知更清晰 - 产品边界更稳定 ## 6.5 来自 DM-11220 子任务的需求信号整理 除了代码层面暴露出的结构问题，`DM-11220` 相关 child items 也提供了很明确的需求信号。将这些问题与当前代码现状结合后，可以归纳为以下几类。 ### A. Remediation 展示与审批体验问题 对应子任务： - `DM-11546` - `Refine remediation process and bugs` - `DM-11968` - `Refine remediation bugs and experience improvements` 已记录的问题包括： - Root cause analysis 区域中，请求人/角色展示不匹配 - 右侧 panel 的状态展示可能固定在错误审批阶段 - approval message card 中的 requester 展示不正确 - approval history 展示不完整 - 需要展示完整 approval flow - Global Desk 阶段需要支持 approvers - remediation 创建弹窗无法关闭 - SLA 值超出 remediation 范围时缺少通知 - remediation 需要支持 essential clusters 这些问题反映出当前 remediation 存在三类薄弱点： - 视图层依赖过多前端本地推断，状态与角色展示容易失真 - approval 流程虽然在后端存在，但前端没有完整、稳定地把它投影出来 - 创建入口和适用范围仍不够产品化，缺少校验、通知和场景支持 这进一步支持前文提出的重构方向： - 将 approval / phase / requester / approver 的展示统一基于后端 workflow 元数据 - 补齐 remediation 可视化流程视图 - 让适用范围、分支规则、通知策略进入正式产品模型 ### B. Incident 时间、组件、链接与告警治理问题 对应子任务： - `DM-12089` - `update incident alert rule` - `DM-12749` - `Incident component config and severity helper` - `DM-12750` - `Unify incident time model in UTC` - `DM-12751` - `Fix incident Jira link persistence and retrieval` 这些问题说明 Incident 目前至少有以下短板： - 告警规则与 Incident 建模没有形成稳定闭环 - component 与 severity 缺少统一配置源 - 时间模型存在时区或表示不一致问题 - Jira link 的存储和读取逻辑不稳定 它们基本都指向同一个核心问题： - Incident 主数据的结构化程度不够 - 前后端在时间、组件、外部引用等基础字段上的契约不够清晰 ### C. Incident 后续动作能力不足 对应子任务： - `DM-12752` - `Postmortem snapshot archival and preview` - `DM-12753` - `Repair incident todo action workflow` - `DM-12754` - `Feishu incident lifecycle sync and warning workflow` - `DM-12755` - `Implement incident scoring algorithm in system` - `DM-12761` - `Record postmortem meeting recording reference` 这些问题表明，Incident 在“后续动作”和“复盘资产沉淀”上还有明显缺口： - postmortem 缺少 snapshot / archival / preview 能力 - TODO action workflow 不稳定 - incident 与 Feishu 生命周期联动不完整 - 系统尚未内建 incident scoring - postmortem meeting recording 这样的复盘资料尚无正式建模 这说明 Incident 目前更像“事故记录页”，还没有真正升级为“事故生命周期工作台”。 换句话说，Incident 未来需要承载的不只是： - 事故元信息 - timeline - postmortem 还需要承载： - 复盘资产沉淀 - 生命周期同步 - 自动化评分与治理 - 内外部后续动作的统一入口 ### D. 需求侧对整体重构方向的启示 从这些 DM 可以看到，业务侧实际持续遇到的问题并不是孤立的 bug，而是沿着以下几条主线反复出现： - 流程展示不完整 - 状态和角色展示不一致 - 基础字段和配置没有统一真源 - postmortem / todo / remediation / external sync 之间缺少统一模型 - 系统缺少对“事故后续动作”的整体抽象 因此，这些 DM 并不只是零散修复项，它们实际上强化了本计划中的几个判断： - Incident 和 Remediation 已经不适合继续用页面级 patch 的方式演进 - 需要统一领域字典和流程定义 - 需要把 Incident 后续动作体系整体重构为更清晰的产品与领域模型 - 需要把 Remediation 从“页面驱动的审批功能”升级为“workflow 驱动的流程系统” ## 6.6 问题分级与处置策略 为了避免后续把所有问题都混在一起处理，这里将问题分为两类： - 快速修补项 - 必须通过结构性重构解决的项 ### 6.6.1 快速修补项 这类问题通常具备以下特征： - 能通过修正字段映射、接口返回、页面状态管理、前端交互来解决 - 不需要改变核心领域模型 - 不需要重新设计流程引擎 建议纳入短周期迭代处理。 #### Remediation - `DM-11546` Root cause analysis 区域中 requester / role 展示不匹配 - `DM-11546` 右侧 panel 显示错误审批阶段 - `DM-11546` approval message card requester 展示错误 - `DM-11546` approval history 展示不完整 - `DM-11968` remediation creation panel 无法关闭 - `DM-11968` SLA 值超出 remediation 范围时缺少通知 #### Incident - `DM-12750` Incident 时间模型统一为 UTC - `DM-12751` Jira link persistence / retrieval 修复 - `DM-12753` Incident TODO action workflow 修复 - `DM-12761` 增加 postmortem meeting recording reference ### 6.6.2 必须通过结构性重构解决的项 这类问题通常具备以下特征： - 涉及 phase / status / approver / metadata 的统一定义 - 涉及 Incident 与 Remediation 边界和协作模型 - 需要后端领域模型或 workflow 机制调整 - 即使短期修掉表象，后续也会反复出现 建议作为专题推进，而不是页面级 patch。 #### Remediation - `DM-11968` Display approval flow - `DM-11968` Add approvers for Global Desk phase - `DM-11968` Support essential clusters #### Incident - `DM-12089` Update incident alert rule - `DM-12749` Incident component config and severity helper - `DM-12752` Postmortem snapshot archival and preview - `DM-12754` Feishu incident lifecycle sync and warning workflow - `DM-12755` Implement incident scoring algorithm in system ### 6.6.3 判断标准 后续判断一个问题应该走哪条路径，可以按以下标准： - 如果问题可以通过“修字段映射、补接口字段、修页面交互、补提示”解决，则优先视为快速修补项 - 如果问题涉及“统一 phase / status / approver / metadata / 生命周期建模”，则应视为结构性重构项 - 如果同类问题已经在不同 DM 中反复出现，则应优先判断其背后是否存在系统性设计问题，而不是继续逐个打补丁 ### 6.6.4 建议处理顺序 建议采用“双轨制”推进： #### 轨道一：快速修补 优先修复对当前使用体验影响最大的项目： 1. approval history / requester / role 展示 2. remediation 创建弹窗关闭问题 3. incident Jira link 存取问题 4. UTC 时间模型问题 5. incident TODO action workflow 局部问题 #### 轨道二：结构性重构 并行启动设计和逐步落地： 1. 统一 Incident / Remediation metadata 2. 声明式 Remediation workflow 3. Incident 生命周期与后续动作模型 4. 数据模型结构化改造 这种方式的目标是： - 短期体验问题不积压 - 中长期结构问题不再被页面补丁掩盖 - 避免把“需要重构的问题”误当作普通 bug 无限延期 ## 7. 建议优先级 ### P0 - 清理 Incident 过时状态枚举 - 建立统一 metadata / 字典输出 - 去掉前端硬编码 component / phase / status - 加强 Incident / Remediation validation ### P1 - 声明式 Remediation workflow 设计与落地 - 前端 phase schema 驱动渲染 - 责任人解析抽象 ### P2 - Incident 多值字段结构化改造 - Remediation phase payload 改造 - Incident / Remediation 后续动作统一视图 ## 8. 风险与注意事项 ## 8.1 风险一：前后端同步改造范围大 建议通过兼容层推进，不要一次性替换所有页面和接口。 ## 8.2 风险二：流程定义改造可能影响线上审批 声明式 workflow 改造时必须保证旧流程兼容，建议先做旁路实现和双写验证。 ## 8.3 风险三：数据库改造成本较高 涉及多值字段结构化和 phase payload 改造时，应优先采用“新增字段 + 兼容读取 + 分阶段回填”的方式。 ## 9. 推荐落地顺序 建议按以下顺序推进： 1. 统一字典与枚举 2. 清理前端硬编码与 DTO 转换 3. 增强后端 validation 与领域约束 4. 设计并落地声明式 remediation workflow 5. 数据模型结构化改造 6. 重构 Incident 后续动作的产品呈现 ## 10. 结论 Incident / Remediation 当前不是“不能用”，而是已经到了需要从“功能堆叠”走向“领域收敛”的阶段。 如果只做零散修补，短期可以继续维持，但每增加一个状态、阶段、字段、审批人规则，系统复杂度都会继续上升。 更合理的路径是： - 先统一定义 - 再重构流程 - 最后收敛模型 这样可以在不打断现有业务的前提下，逐步把这套系统从“能跑”提升到“清晰、稳定、可演进”。