#事件中心设计方案

事件中心用于回答一个很实际的问题：平台里刚刚发生了什么？

构建、发布、Hook、访问入口和证书都有自己的状态页，但用户排查问题时往往不知道该先打开哪一页。事件中心把这些变化按时间串起来，让用户先看到事情经过，再进入对应页面看日志和资源详情。

#放在哪里

事件中心作为 DevOps 主导航里的一级页面，放在“项目空间”后面。它面向所有登录用户，而不是只放在系统管理区域。

• 普通用户默认看到自己有权访问的项目空间事件。
• 平台管理员默认先看“与我相关”，需要时再切换到全部事件。
• 项目空间概览展示最近几条事件，并提供“查看全部”链接，跳转到带项目筛选的事件中心。
• 应用的构建、部署和访问页面保留就地状态，同时可以跳转到带应用筛选的事件中心。

第一版不在项目空间里再增加一个完整“事件”Tab，避免同一份列表出现两套入口。项目空间只提供摘要和筛选后的跳转。

#事件和现有记录有什么区别

平台已经有几类记录，但它们解决的问题不同，不能直接合并成一张表。

目前通知服务只有在规则匹配并生成投递记录后才保存事件快照。没有通知规则的业务变化不会留下完整事件历史。事件中心落地后，顺序要调整为“先保存事件，再匹配通知”。

#核心流程

构建、发布、Hook、网关或证书状态发生变化
                    |
                    v
           写入 PlatformEvent
              /             \
             v               v
       事件中心查询       通知规则匹配
                              |
                              v
                    NotificationDelivery

业务模块只提交结构化事件，不直接调用飞书、SMTP 等渠道。通知系统读取同一条 PlatformEvent，按规则决定是否发送。

#已实现的数据模型

000031_platform_events 迁移会创建 platform_events 表。事件写入后只追加、不修改，保存以下字段：

常用筛选字段需要单独建索引，不要只把所有信息塞进 detail_json。detail_json 只放事件特有内容，例如镜像引用、Git SHA、证书域名或失败阶段。

#事件类型

事件类型使用 <资源>.<动作或结果>，名称稳定后不要随意修改。

当前第一批已接入：

第二批再接镜像站连接、Git Webhook、运行副本异常、共享配置变更和平台级运维事件。成功和进行中的事件可以进入事件中心，但通知默认只选择失败、过期等需要处理的事件。

状态同步任务必须比较新旧状态，只在状态真正变化时写事件。例如证书每分钟同步一次，但不能每分钟重复写一条 certificate.issued。

#事件页面

页面顶部使用一组紧凑筛选器：

• 时间范围：今天、最近 7 天、最近 30 天和自定义范围。
• 首次打开默认选择警告和错误级别，优先展示需要处理的事件；用户清空级别筛选后可以查看全部事件，URL 中的显式筛选条件优先。
• 项目空间、应用和部署配置都支持多选。应用候选来自已选项目空间，部署配置候选来自已选应用。
• 分类、事件类型和严重级别支持多选；选择分类后，事件类型只展示对应分类中的选项。
• 结果支持多选，例如同时查看进行中和失败事件。

列表按时间倒序展示，主行包含事件摘要、资源、状态和时间。点击详情按钮后展开或打开侧边面板，展示：

• 完整时间和操作人。
• 项目空间、应用、部署配置和主要资源。
• 原始失败摘要和结构化详情。
• 构建日志、Release、Hook、访问入口或证书页面的直达链接。
• 关联通知的投递状态。
• correlation_id 相同的前后事件。

第一版不做“全部已读”或未读红点。事件中心是活动和诊断记录，不是消息收件箱。后续确实需要待办能力时，再为可处理事件增加独立的确认状态。

build.failed 的构建链接包含 BuildRun ID。打开后会进入对应应用的构建页，筛选、滚动并高亮失败的构建记录，而不是只停留在构建列表顶部。历史事件也会在查询时补齐这个链接。

#权限

后端按资源归属做最终过滤：

• 项目成员只能读取自己有权访问的项目空间事件。
• 项目 Viewer 可以查看事件，但不能通过事件详情获得 Secret 或高权限操作入口。
• 平台管理员可以查看平台级事件，并手动切换到全部项目空间。
• 用户级事件只对本人和平台管理员可见。

事件内容不能保存或返回 Token、密码、Secret 值、完整 kubeconfig、Cookie、Authorization header 或原始终端命令。外部系统错误进入 message 前必须使用现有脱敏组件处理。

#API

已提供以下接口：

GET /api/v1/events
GET /api/v1/events/:eventId
GET /api/v1/events/catalog

列表接口支持分页、排序和筛选：

page, pageSize, sortOrder
projectIds, applicationIds, deploymentTargetIds
categories, types, severities
statuses, dateFrom, dateTo

复数筛选参数可以重复传递，例如 projectIds=prj_a&projectIds=prj_b。为兼容项目空间概览等已有跳转，接口仍接受 projectId、applicationId 等单值参数。

catalog 返回前端筛选器和通知规则共同使用的事件类型目录，包括类型、分类、默认严重级别、是否推荐通知和可用详情字段。前端只按稳定 key 做 i18n，不硬编码事件名称。

#通知系统调整

通知规则继续使用现有渠道、模板和适配器，只调整事件入口：

1. 业务模块调用事件服务写入 PlatformEvent。
2. 事件写入成功后，通知服务匹配启用的规则并生成 NotificationDelivery。
3. Worker 异步执行实际投递，业务事件不会等待外部渠道返回。
4. 投递记录只保存发送所需快照和结果，不再承担事件历史表的职责。

所有事件类型都可以被通知规则选择，但目录可以标记“推荐通知”。默认只勾选失败、过期和安全告警，避免成功事件淹没协作群。

#保留和清理

事件默认保留 90 天。Worker 使用独立的每日数据保留任务，每批最多清理 1000 条过期事件，避免长事务，也不会因为清理失败阻塞状态同步。平台管理员可以在站点设置中调整保留天数，或预览并清理指定时间段；通知投递使用自己的保留周期，审计日志不在通用清理范围内。

#上线后会看到什么

迁移不会倒推历史构建或发布记录。新版 API 和 Worker 启动后，新发生的构建、发布、Hook、访问入口和证书状态变化会进入事件中心。如果刚升级完页面为空，触发一次构建或发布即可验证整条链路。

如果事件仍被通知投递引用，删除事件后投递记录保留自己的事件快照，历史投递页面仍能查看当时发送的内容。

旧测试数据或异常写入可能把 detail_json、links_json 保存为 JSON null。事件 API 会把这类值和无法解析的对象统一返回为 {}，前端也会在 API 边界再次归一化，因此缺少详情或链接只会隐藏对应区域，不会影响事件列表和详情页。

#实施顺序

1. 新增 PlatformEvent 模型、迁移、事件目录和写入服务。
2. 调整通知服务，先落事件再匹配规则，同时兼容已有失败事件。
3. 接入构建、发布、Hook、访问入口和证书状态变化。
4. 增加事件列表 API、权限过滤和前端事件页。
5. 在项目空间概览和应用页面增加筛选跳转。
6. 增加保留策略、清理任务、指标和事件去重测试。

#验收标准

• 没有配置通知规则时，构建或发布失败仍会出现在事件中心。
• 同一业务变化只产生一条事件，Worker 重试和周期同步不会重复刷屏。
• 普通成员看不到其他项目空间或平台级事件。
• 事件详情可以直达对应构建、发布、Hook、访问入口或证书页面。
• 通知投递使用同一个事件 ID，并能从事件详情查看发送结果。
• 关闭所有通知渠道不会影响事件记录。
• 敏感字段不会进入事件表、API 响应或通知模板变量。