# 公告领域事件与可观测性

> 最后更新日期：2025-12-20

本文档列出公告领域事件及推荐监控指标，方便事件订阅与追踪。

## 事件清单

| 事件名 | 触发时机 | 载荷字段 | 备注 |
| --- | --- | --- | --- |
| `tenant-announcement.published` | 公告发布成功后 | `announcementId`、`publishedAt`、`targetType` | 对应 `AnnouncementPublished` |
| `tenant-announcement.revoked` | 公告撤销成功后 | `announcementId`、`revokedAt` | 对应 `AnnouncementRevoked` |

### 事件载荷示例

```json
{
  "announcementId": 900123456789012345,
  "publishedAt": "2025-12-20T12:00:00Z",
  "targetType": "roles"
}
```

```json
{
  "announcementId": 900123456789012345,
  "revokedAt": "2025-12-20T13:00:00Z"
}
```

## 事件流示意

```mermaid
flowchart LR
  Cmd[Publish/Revoke Command] --> Handler[Handler]
  Handler --> Bus[IEventPublisher]
  Bus --> Topic[Event Bus]
  Topic --> Sub1[通知服务]
  Topic --> Sub2[审计/报表]
```

## 推荐指标

- `announcement.created.count`：公告创建次数
- `announcement.published.count`：公告发布次数
- `announcement.revoked.count`：公告撤销次数
- `announcement.read.count`：公告已读次数
- `announcement.visible.count`：用户可见公告数量（采样）
- `announcement.query.latency`：公告查询耗时（P95/P99）

## 建议日志字段

```text
announcementId, tenantId, status, targetType, operatorUserId, traceId
```

> 事件发布位置：`PublishAnnouncementCommandHandler` 与 `RevokeAnnouncementCommandHandler`。