1080 lines
31 KiB
Markdown
1080 lines
31 KiB
Markdown
# OPS 项目目录、数据模型与接口文件设计
|
||
|
||
## 1. 设计目标
|
||
|
||
本文根据现有项目文档和 `server/` 模板结构，重新设计 OPS 的实际业务目录、完整数据模型文件边界和 REST 接口文件边界。
|
||
|
||
本设计替代已删除的旧设计文档，不以旧文档为基线。
|
||
|
||
目标：
|
||
|
||
- 保留模板验证过的 Go 分层骨架：`cmd/`、`internal/config/`、`internal/impl/`、`internal/models/`、`internal/logic/`、`internal/routers/`。
|
||
- 按 OPS-001 至 OPS-033 完整功能需求设计数据模型，先完整建模，再按阶段实现。
|
||
- 首期优先打通“资源纳管 -> 采集/探测/Trap/Syslog -> 原始事件 -> 告警 -> 通知 -> 工单 -> 报表/大屏/审计”闭环。
|
||
- 让 `templates/` 仅作为只读参考，不参与实际业务实现，不被实际业务代码 import。
|
||
- 为后续生成 Go 模型、DTO、Service、Router 文件提供清晰边界和注释规范。
|
||
|
||
## 2. 关键决策
|
||
|
||
采用“按业务域拆分，保留模板分层”的 B 方案。
|
||
|
||
不采用以下方案：
|
||
|
||
- 不做模板最小改造。原因是告警、工单、采集和权限会挤在少量文件中，后续维护困难。
|
||
- 不新增大规模 `domain/service/repository` 重构层。原因是首期目标是可运行、可验收，过度重构会偏离模板和当前交付节奏。
|
||
|
||
约束：
|
||
|
||
- `templates/front_sample/standard` 和 `templates/server_sample/` 只读参考。
|
||
- 实际后端业务只落在 `server/`。
|
||
- 未来实际前端业务只落在 `web/`。
|
||
- 不新增旧项目名。
|
||
- 命令示例只使用 Windows PowerShell。
|
||
- PostgreSQL 保存事务数据，TDengine 保存时序样本，业务代码通过适配层访问 TDengine。
|
||
|
||
## 3. 后端目录结构
|
||
|
||
```text
|
||
server/
|
||
cmd/
|
||
main/
|
||
main.go
|
||
cli/
|
||
main.go
|
||
etc/
|
||
ops_dev.example.yaml
|
||
ops_test.example.yaml
|
||
ops_prod.example.yaml
|
||
internal/
|
||
config/
|
||
config.go
|
||
impl/
|
||
new.go
|
||
postgres.go
|
||
redis.go
|
||
tsdb.go
|
||
file_store.go
|
||
models/
|
||
base.go
|
||
resource/
|
||
metric/
|
||
collector/
|
||
event/
|
||
alert/
|
||
notification/
|
||
ticket/
|
||
asset/
|
||
topology/
|
||
ipam/
|
||
traffic/
|
||
knowledge/
|
||
report/
|
||
iam/
|
||
audit/
|
||
logic/
|
||
response/
|
||
statemachine/
|
||
resource/
|
||
metric/
|
||
collector/
|
||
event/
|
||
alert/
|
||
notification/
|
||
ticket/
|
||
asset/
|
||
topology/
|
||
ipam/
|
||
traffic/
|
||
knowledge/
|
||
report/
|
||
dashboard/
|
||
iam/
|
||
audit/
|
||
room3d/
|
||
routers/
|
||
register.go
|
||
resource.go
|
||
metric.go
|
||
collector.go
|
||
event.go
|
||
alert.go
|
||
notification.go
|
||
ticket.go
|
||
asset.go
|
||
topology.go
|
||
ipam.go
|
||
traffic.go
|
||
knowledge.go
|
||
report.go
|
||
dashboard.go
|
||
iam.go
|
||
audit.go
|
||
room3d.go
|
||
test/
|
||
resource/
|
||
collector/
|
||
event/
|
||
alert/
|
||
notification/
|
||
ticket/
|
||
room3d/
|
||
```
|
||
|
||
目录职责：
|
||
|
||
- `models/`：GORM 表结构、表名、索引、唯一约束和基础查询。模型文件不写状态机和业务编排。
|
||
- `logic/`：业务编排、DTO、状态机、权限判断、错误救援、审计记录和外部适配。
|
||
- `logic/statemachine/`：资源、采集、原始事件、告警、事件、通知、工单状态流转集中定义。
|
||
- `logic/response/`：统一响应、错误码、`traceId` 和 `suggestion`。
|
||
- `routers/`：HTTP 路由注册和参数绑定。Router 不直接操作数据库。
|
||
- `impl/`：PostgreSQL、Redis、TDengine、文件存储等基础设施实例。
|
||
- `test/`：HTTP 接口样例、验收脚本和后端测试支撑文件。
|
||
|
||
## 4. 前端目录结构
|
||
|
||
`web/` 当前不存在。后续从前端模板初始化后，建议使用以下业务边界：
|
||
|
||
```text
|
||
web/
|
||
src/
|
||
api/
|
||
types/
|
||
common.ts
|
||
resource.ts
|
||
metric.ts
|
||
collector.ts
|
||
event.ts
|
||
alert.ts
|
||
notification.ts
|
||
ticket.ts
|
||
asset.ts
|
||
report.ts
|
||
iam.ts
|
||
resource.ts
|
||
metric.ts
|
||
collector.ts
|
||
event.ts
|
||
alert.ts
|
||
notification.ts
|
||
ticket.ts
|
||
asset.ts
|
||
report.ts
|
||
dashboard.ts
|
||
iam.ts
|
||
audit.ts
|
||
room3d.ts
|
||
views/
|
||
dashboard/
|
||
monitor/
|
||
events/
|
||
alerts/
|
||
tickets/
|
||
reports/
|
||
screens/
|
||
iam/
|
||
system/
|
||
room3d-api/
|
||
store/
|
||
modules/
|
||
user.ts
|
||
permission.ts
|
||
ops-state.ts
|
||
components/
|
||
ops-state/
|
||
trace-error/
|
||
resource-selector/
|
||
alert-severity/
|
||
ticket-transition/
|
||
```
|
||
|
||
前端规则：
|
||
|
||
- API 类型按业务域放入 `src/api/types/`。
|
||
- 页面组件不得直接拼接非法状态，状态枚举以后端返回和前端类型定义为准。
|
||
- 所有错误状态展示 `traceId`。
|
||
- loading、empty、error、success、partial、forbidden、stale、operating、operation_failed 必须可被页面表达。
|
||
|
||
## 5. 数据模型总体原则
|
||
|
||
数据模型先覆盖完整 OPS-001 至 OPS-033，再按阶段实现：
|
||
|
||
- P1：首期必须实现或迁移，用于验收核心闭环。
|
||
- P2：上下文增强，先设计模型边界，后续按任务实现。
|
||
- P3：运营治理和智能化，先预留统计口径。
|
||
|
||
统一规则：
|
||
|
||
- 所有核心表包含 `id`、`tenant_id`、`created_at`、`updated_at`、`created_by`、`updated_by`、`deleted_at`、`version`。
|
||
- 关键状态变化写 `audit_logs` 或对应 transition 表。
|
||
- 敏感凭据不保存明文，只保存 `secret_ref` 和脱敏描述。
|
||
- TDengine 样本不做 GORM 模型，只在 PostgreSQL 中保存指标定义、序列映射和保留策略。
|
||
- 模型文件注释必须说明表职责、阶段和对应需求编号。
|
||
|
||
建议 `server/internal/models/base.go`：
|
||
|
||
```go
|
||
// BaseModel 是 OPS 事务表的通用字段。
|
||
// 所有需要审计、租户隔离或软删除的业务表都应嵌入该结构。
|
||
type BaseModel struct {
|
||
ID string `gorm:"column:id;type:varchar(64);primaryKey" json:"id"`
|
||
TenantID string `gorm:"column:tenant_id;type:varchar(64);index" json:"tenantId"`
|
||
CreatedAt time.Time `gorm:"column:created_at" json:"createdAt"`
|
||
UpdatedAt time.Time `gorm:"column:updated_at" json:"updatedAt"`
|
||
CreatedBy string `gorm:"column:created_by;type:varchar(64)" json:"createdBy"`
|
||
UpdatedBy string `gorm:"column:updated_by;type:varchar(64)" json:"updatedBy"`
|
||
DeletedAt gorm.DeletedAt `gorm:"column:deleted_at;index" json:"-"`
|
||
Version int `gorm:"column:version;default:1" json:"version"`
|
||
}
|
||
```
|
||
|
||
## 6. 资源与业务系统模型
|
||
|
||
```text
|
||
server/internal/models/resource/
|
||
business_system.go
|
||
resource_type.go
|
||
resource.go
|
||
resource_relation.go
|
||
resource_group.go
|
||
credential.go
|
||
```
|
||
|
||
| 文件 | 表名 | 阶段 | 对应需求 | 职责 |
|
||
| --- | --- | --- | --- | --- |
|
||
| `business_system.go` | `business_systems` | P1 | OPS-001、OPS-011、OPS-033 | HIS、LIS、PACS、EMR 等业务系统建模。 |
|
||
| `resource_type.go` | `resource_types` | P1 | OPS-002 至 OPS-012 | 主机、H3C 网络设备、数据库、虚拟化、URL/API 等资源类型。 |
|
||
| `resource.go` | `resources` | P1 | OPS-002 至 OPS-014、OPS-031 | 统一监控资源主表。 |
|
||
| `resource_relation.go` | `resource_relations` | P1/P2 | OPS-013、OPS-033 | 资源依赖、业务拓扑、基础拓扑关系。 |
|
||
| `resource_group.go` | `resource_groups`、`resource_group_members` | P2 | OPS-013、OPS-031 | 资源分组、多级分组、自动分组结果。 |
|
||
| `credential.go` | `credentials` | P1 | OPS-002 至 OPS-011、OPS-031 | 凭据引用和脱敏摘要。 |
|
||
|
||
核心字段：
|
||
|
||
- `business_systems`：`name`、`code`、`level`、`network_zone`、`owner_org_id`、`owner_user_id`、`health_status`、`description`。
|
||
- `resource_types`：`code`、`name`、`category`、`vendor`、`default_metric_template_id`、`icon`。
|
||
- `resources`：`name`、`resource_type_id`、`vendor`、`model`、`ip`、`hostname`、`business_system_id`、`owner_org_id`、`owner_user_id`、`asset_id`、`status`、`collect_status`、`highest_alert_severity`。
|
||
- `resource_relations`：`source_resource_id`、`target_resource_id`、`relation_type`、`description`。
|
||
- `credentials`：`name`、`type`、`secret_ref`、`masked_summary`、`owner_org_id`、`status`。
|
||
|
||
索引建议：
|
||
|
||
- `resources(tenant_id, resource_type_id, status)`。
|
||
- `resources(tenant_id, ip)`。
|
||
- `resources(tenant_id, business_system_id)`。
|
||
- `business_systems(tenant_id, code)` 唯一。
|
||
- `resource_types(code)` 唯一。
|
||
|
||
## 7. 指标、模板与时序映射模型
|
||
|
||
```text
|
||
server/internal/models/metric/
|
||
metric_template.go
|
||
metric_definition.go
|
||
metric_series.go
|
||
metric_retention_policy.go
|
||
```
|
||
|
||
| 文件 | 表名 | 阶段 | 对应需求 | 职责 |
|
||
| --- | --- | --- | --- | --- |
|
||
| `metric_template.go` | `metric_templates` | P1 | OPS-002 至 OPS-011、OPS-031 | 资源类型、厂商、协议维度的指标模板。 |
|
||
| `metric_definition.go` | `metric_definitions` | P1 | OPS-002 至 OPS-014 | 指标编码、单位、类型、默认采集周期和阈值建议。 |
|
||
| `metric_series.go` | `metric_series` | P1 | OPS-002、OPS-004、OPS-007、OPS-011、OPS-027 | PostgreSQL 到 TDengine 时序序列的映射。 |
|
||
| `metric_retention_policy.go` | `metric_retention_policies` | P1 | OPS-015、OPS-027 | 原始样本保留、降采样、聚合保留策略。 |
|
||
|
||
核心字段：
|
||
|
||
- `metric_templates`：`name`、`resource_type_id`、`vendor`、`version`、`status`。
|
||
- `metric_definitions`：`template_id`、`resource_type_id`、`metric_code`、`metric_name`、`unit`、`value_type`、`default_interval_seconds`、`threshold_hint`。
|
||
- `metric_series`：`resource_id`、`metric_definition_id`、`metric_code`、`tsdb_name`、`series_key`、`labels_json`、`retention_policy_id`。
|
||
- `metric_retention_policies`：`name`、`raw_retention_days`、`downsample_rule`、`status`。
|
||
|
||
TDengine 访问规则：
|
||
|
||
- 业务代码只调用 `logic/metric/tsdb_adapter.go`。
|
||
- 查询统一使用 `resource_id + metric_code + time_range`。
|
||
- 不在资源、告警、报表逻辑中散落 TDengine SQL。
|
||
|
||
## 8. 采集、发现与探测模型
|
||
|
||
```text
|
||
server/internal/models/collector/
|
||
collector_task.go
|
||
collector_run.go
|
||
discovery_task.go
|
||
discovery_result.go
|
||
probe_target.go
|
||
agent_node.go
|
||
```
|
||
|
||
| 文件 | 表名 | 阶段 | 对应需求 | 职责 |
|
||
| --- | --- | --- | --- | --- |
|
||
| `collector_task.go` | `collector_tasks` | P1 | OPS-002 至 OPS-011、OPS-031 | 采集任务定义。 |
|
||
| `collector_run.go` | `collector_runs` | P1 | OPS-031 | 单次采集执行记录和失败原因。 |
|
||
| `discovery_task.go` | `discovery_tasks` | P1/P2 | OPS-004、OPS-016、OPS-017、OPS-031 | 自动发现任务。 |
|
||
| `discovery_result.go` | `discovery_results` | P2 | OPS-016、OPS-017、OPS-031 | 自动发现结果和匹配资源。 |
|
||
| `probe_target.go` | `probe_targets` | P1 | OPS-011 | URL/API/端口探测目标。 |
|
||
| `agent_node.go` | `agent_nodes` | P2 | OPS-032 | 跨网代理节点。 |
|
||
|
||
核心字段：
|
||
|
||
- `collector_tasks`：`resource_id`、`collector_type`、`protocol`、`credential_id`、`schedule_cron`、`interval_seconds`、`timeout_seconds`、`retry_limit`、`status`。
|
||
- `collector_runs`：`task_id`、`started_at`、`finished_at`、`run_status`、`success_count`、`failed_count`、`error_code`、`error_message`、`trace_id`、`last_success_at`。
|
||
- `discovery_tasks`：`name`、`scan_range`、`protocols_json`、`credential_id`、`schedule_cron`、`status`。
|
||
- `probe_targets`：`resource_id`、`target_url`、`method`、`expected_status`、`timeout_seconds`、`status`。
|
||
- `agent_nodes`：`name`、`region`、`network_zone`、`mode`、`last_heartbeat_at`、`status`。
|
||
|
||
救援要求：
|
||
|
||
- 采集失败写 `collector_runs`。
|
||
- 连续失败达到阈值后写平台内部 `raw_events`。
|
||
- `COLLECT_UNREACHABLE`、`COLLECT_AUTH_FAILED`、`COLLECT_TIMEOUT` 必须可区分。
|
||
|
||
## 9. 事件、Syslog 与 Trap 模型
|
||
|
||
```text
|
||
server/internal/models/event/
|
||
raw_event.go
|
||
syslog_rule.go
|
||
trap_dictionary.go
|
||
event_replay_job.go
|
||
```
|
||
|
||
| 文件 | 表名 | 阶段 | 对应需求 | 职责 |
|
||
| --- | --- | --- | --- | --- |
|
||
| `raw_event.go` | `raw_events` | P1 | OPS-010、OPS-018、OPS-021 | 原始事件池，保留解析前后状态。 |
|
||
| `syslog_rule.go` | `syslog_rules` | P1 | OPS-010 | Syslog 匹配、字段提取和级别映射。 |
|
||
| `trap_dictionary.go` | `trap_dictionaries` | P1 | OPS-010 | Trap OID 字典、恢复 OID 和级别配置。 |
|
||
| `event_replay_job.go` | `event_replay_jobs` | P1 | OPS-010 | 补规则后的事件重放任务。 |
|
||
|
||
核心字段：
|
||
|
||
- `raw_events`：`source_type`、`source_id`、`resource_id`、`event_key`、`occurred_at`、`severity`、`title`、`message`、`payload_json`、`parse_status`、`matched_rule_id`、`suppressed_policy_id`。
|
||
- `syslog_rules`：`name`、`match_expr`、`extract_expr`、`severity_mapping_json`、`status`。
|
||
- `trap_dictionaries`：`vendor`、`oid`、`name`、`severity`、`recover_oid`、`description`、`status`。
|
||
- `event_replay_jobs`：`name`、`scope_type`、`scope_id`、`status`、`result_summary_json`。
|
||
|
||
规则：
|
||
|
||
- 未解析 Trap/Syslog 不删除。
|
||
- 重放动作必须写审计。
|
||
- 被抑制事件仍可查询，并记录命中的策略 ID。
|
||
|
||
## 10. 告警与事件治理模型
|
||
|
||
```text
|
||
server/internal/models/alert/
|
||
alert_rule.go
|
||
alert.go
|
||
incident.go
|
||
incident_alert.go
|
||
silence_policy.go
|
||
dedup_rule.go
|
||
correlation_rule.go
|
||
escalation_policy.go
|
||
alert_quality_stat.go
|
||
```
|
||
|
||
| 文件 | 表名 | 阶段 | 对应需求 | 职责 |
|
||
| --- | --- | --- | --- | --- |
|
||
| `alert_rule.go` | `alert_rules` | P1 | OPS-018、OPS-020 | 阈值、Trap、Syslog、可用性告警规则。 |
|
||
| `alert.go` | `alerts` | P1 | OPS-018 至 OPS-021 | 告警实例和生命周期。 |
|
||
| `incident.go` | `incidents` | P1 | OPS-021、OPS-022 | 多告警归并后的事件。 |
|
||
| `incident_alert.go` | `incident_alerts` | P1 | OPS-018、OPS-021 | 事件与告警关联。 |
|
||
| `silence_policy.go` | `silence_policies` | P1 | OPS-018 | 屏蔽和维护窗口。 |
|
||
| `dedup_rule.go` | `dedup_rules` | P1 | OPS-018 | 去重窗口和匹配表达式。 |
|
||
| `correlation_rule.go` | `correlation_rules` | P1/P2 | OPS-018、OPS-013 | 压缩、依赖、抑制规则。 |
|
||
| `escalation_policy.go` | `escalation_policies` | P1 | OPS-020 | 超时升级策略。 |
|
||
| `alert_quality_stat.go` | `alert_quality_stats` | P3 | OPS-018 后续优化 | 告警质量评分和规则优化依据。 |
|
||
|
||
核心字段：
|
||
|
||
- `alert_rules`：`name`、`scope_type`、`scope_id`、`metric_code`、`condition_expr`、`duration_seconds`、`recover_expr`、`severity`、`status`。
|
||
- `alerts`：`alert_key`、`resource_id`、`rule_id`、`first_seen_at`、`last_seen_at`、`recovered_at`、`severity`、`status`、`summary`。
|
||
- `incidents`：`incident_no`、`title`、`severity`、`status`、`owner_user_id`、`business_system_id`、`opened_at`、`closed_at`。
|
||
- `silence_policies`：`name`、`scope_type`、`scope_id`、`start_at`、`end_at`、`reason`、`status`。
|
||
- `alert_quality_stats`：`rule_id`、`noise_count`、`false_positive_count`、`avg_ack_seconds`、`avg_resolve_seconds`、`score`。
|
||
|
||
## 11. 通知与工单模型
|
||
|
||
```text
|
||
server/internal/models/notification/
|
||
notification_policy.go
|
||
notification_template.go
|
||
notification_record.go
|
||
|
||
server/internal/models/ticket/
|
||
ticket.go
|
||
ticket_transition.go
|
||
ticket_comment.go
|
||
ticket_sla_record.go
|
||
ticket_dispatch_rule.go
|
||
```
|
||
|
||
| 文件 | 表名 | 阶段 | 对应需求 | 职责 |
|
||
| --- | --- | --- | --- | --- |
|
||
| `notification_policy.go` | `notification_policies` | P1 | OPS-019、OPS-020 | 通知策略。 |
|
||
| `notification_template.go` | `notification_templates` | P1 | OPS-019、OPS-030 | 站内消息、短信、邮件模板。 |
|
||
| `notification_record.go` | `notification_records` | P1 | OPS-019、OPS-021 | 通知发送记录、失败原因和重试。 |
|
||
| `ticket.go` | `tickets` | P1 | OPS-022 | 工单主表。 |
|
||
| `ticket_transition.go` | `ticket_transitions` | P1 | OPS-022 | 工单状态流转记录。 |
|
||
| `ticket_comment.go` | `ticket_comments` | P1 | OPS-022、OPS-026 | 工单处理记录和附件。 |
|
||
| `ticket_sla_record.go` | `ticket_sla_records` | P1/P3 | OPS-022、运营治理 | 工单 SLA 和处理时长统计。 |
|
||
| `ticket_dispatch_rule.go` | `ticket_dispatch_rules` | P1 | OPS-019、OPS-022 | 自动派单规则。 |
|
||
|
||
核心字段：
|
||
|
||
- `notification_records`：`channel`、`alert_id`、`incident_id`、`receiver`、`send_status`、`retry_count`、`provider_code`、`error_message`、`sent_at`。
|
||
- `tickets`：`ticket_no`、`title`、`source_type`、`source_id`、`alert_id`、`incident_id`、`resource_id`、`assignee_id`、`status`、`priority`、`closed_at`。
|
||
- `ticket_transitions`：`ticket_id`、`from_status`、`to_status`、`operator_id`、`reason`、`trace_id`。
|
||
- `ticket_dispatch_rules`：`name`、`match_expr`、`assignee_type`、`assignee_id`、`status`。
|
||
|
||
规则：
|
||
|
||
- 通知失败不阻断告警确认和工单流转。
|
||
- 同一告警不能重复自动创建多个未关闭工单。
|
||
- 工单非法流转返回 `STATE_CONFLICT`。
|
||
|
||
## 12. 资产、机房与 3D 接口模型
|
||
|
||
```text
|
||
server/internal/models/asset/
|
||
data_center.go
|
||
room.go
|
||
rack.go
|
||
rack_unit.go
|
||
asset.go
|
||
environment_device.go
|
||
```
|
||
|
||
| 文件 | 表名 | 阶段 | 对应需求 | 职责 |
|
||
| --- | --- | --- | --- | --- |
|
||
| `data_center.go` | `data_centers` | P2，首期接口 | OPS-023 | 数据中心层级。 |
|
||
| `room.go` | `rooms` | P2，首期接口 | OPS-023 | 机房、楼层和状态。 |
|
||
| `rack.go` | `racks` | P2，首期接口 | OPS-024 | 机柜坐标、容量和状态。 |
|
||
| `rack_unit.go` | `rack_units` | P2，首期接口 | OPS-024 | U 位占用和资源/资产绑定。 |
|
||
| `asset.go` | `assets` | P2 | OPS-025 | 资产台账。 |
|
||
| `environment_device.go` | `environment_devices` | P2 | OPS-012、OPS-023 | 动环设备和机房关联。 |
|
||
|
||
3D 机房接口规则：
|
||
|
||
- `room3d` 返回聚合 DTO，不直接暴露内部 GORM 模型。
|
||
- 必须返回数据更新时间。
|
||
- 资产未绑定监控资源时，接口返回 `bindStatus=unbound`，不影响机柜结构展示。
|
||
- 数据权限过滤在 `logic/room3d/service.go` 中执行。
|
||
|
||
## 13. 拓扑、IPAM、流量与知识库模型
|
||
|
||
```text
|
||
server/internal/models/topology/
|
||
topology_map.go
|
||
topology_node.go
|
||
topology_link.go
|
||
|
||
server/internal/models/ipam/
|
||
ip_subnet.go
|
||
ip_address.go
|
||
ip_scan_task.go
|
||
ip_change_record.go
|
||
|
||
server/internal/models/traffic/
|
||
network_link.go
|
||
traffic_policy.go
|
||
traffic_anomaly.go
|
||
|
||
server/internal/models/knowledge/
|
||
knowledge_category.go
|
||
knowledge_article.go
|
||
knowledge_relation.go
|
||
knowledge_audit.go
|
||
```
|
||
|
||
这些模型主要属于 P2：
|
||
|
||
- `topology_*`：OPS-013，网络拓扑、业务拓扑和资源关系视图。
|
||
- `ip_*`：OPS-016、OPS-017，子网、IP、扫描、冲突和变更。
|
||
- `traffic_*`：OPS-014、OPS-015，链路、应用/协议策略、流量异常。
|
||
- `knowledge_*`：OPS-026，知识分类、条目、关联检测点和审核日志。
|
||
|
||
实现建议：
|
||
|
||
- 首期可只使用 `resource_relations` 支撑基础拓扑和业务视图。
|
||
- P2 再迁移完整拓扑、IPAM、流量和知识库表。
|
||
- 未获现场授权前，不执行生产网段扫描。
|
||
|
||
## 14. 报表、大屏、权限与审计模型
|
||
|
||
```text
|
||
server/internal/models/report/
|
||
report_template.go
|
||
report_job.go
|
||
report_export.go
|
||
dashboard.go
|
||
dashboard_widget.go
|
||
|
||
server/internal/models/iam/
|
||
organization.go
|
||
user.go
|
||
role.go
|
||
user_role.go
|
||
role_permission.go
|
||
data_scope.go
|
||
|
||
server/internal/models/audit/
|
||
audit_log.go
|
||
system_log.go
|
||
```
|
||
|
||
| 文件 | 表名 | 阶段 | 对应需求 | 职责 |
|
||
| --- | --- | --- | --- | --- |
|
||
| `report_template.go` | `report_templates` | P1 | OPS-027 | 报表模板和查询结构。 |
|
||
| `report_job.go` | `report_jobs` | P1 | OPS-027 | 报表生成任务。 |
|
||
| `report_export.go` | `report_exports` | P1 | OPS-027 | 导出文件记录。 |
|
||
| `dashboard.go` | `dashboards` | P1 | OPS-001、OPS-028 | 首页模块和大屏配置。 |
|
||
| `dashboard_widget.go` | `dashboard_widgets` | P1 | OPS-001、OPS-028 | 大屏组件数据源和布局。 |
|
||
| `organization.go` | `organizations` | P1 | OPS-029、OPS-030 | 组织部门。 |
|
||
| `user.go` | `users` | P1 | OPS-029、OPS-030 | 用户账号。 |
|
||
| `role.go` | `roles` | P1 | OPS-029 | 角色。 |
|
||
| `user_role.go` | `user_roles` | P1 | OPS-029 | 用户角色关联。 |
|
||
| `role_permission.go` | `role_permissions` | P1 | OPS-029 | 功能权限。 |
|
||
| `data_scope.go` | `data_scopes` | P1 | OPS-029 | 数据权限范围。 |
|
||
| `audit_log.go` | `audit_logs` | P1 | 全部关键操作 | 审计日志。 |
|
||
| `system_log.go` | `system_logs` | P1 | OPS-030 | 系统运行日志查询。 |
|
||
|
||
审计必写动作：
|
||
|
||
- 资源新增、修改、停用、退役。
|
||
- 凭据引用变更。
|
||
- 告警确认、忽略、恢复、失效、派单。
|
||
- 屏蔽、抑制、升级、通知策略变更。
|
||
- 工单接单、转交、撤回、挂起、重启、关闭。
|
||
- 权限、角色、数据权限变更。
|
||
- 报表导出和敏感数据查看。
|
||
|
||
## 15. Logic 文件设计
|
||
|
||
```text
|
||
server/internal/logic/
|
||
response/
|
||
response.go
|
||
errors.go
|
||
trace.go
|
||
statemachine/
|
||
resource.go
|
||
collector.go
|
||
raw_event.go
|
||
alert.go
|
||
incident.go
|
||
notification.go
|
||
ticket.go
|
||
resource/
|
||
dto.go
|
||
service.go
|
||
metric/
|
||
dto.go
|
||
service.go
|
||
tsdb_adapter.go
|
||
collector/
|
||
dto.go
|
||
service.go
|
||
rescue.go
|
||
event/
|
||
dto.go
|
||
receiver.go
|
||
parser.go
|
||
replay.go
|
||
alert/
|
||
dto.go
|
||
service.go
|
||
evaluator.go
|
||
dedup.go
|
||
silence.go
|
||
escalation.go
|
||
notification/
|
||
dto.go
|
||
service.go
|
||
retry.go
|
||
channel.go
|
||
ticket/
|
||
dto.go
|
||
service.go
|
||
transition.go
|
||
dispatch.go
|
||
asset/
|
||
dto.go
|
||
service.go
|
||
report/
|
||
dto.go
|
||
service.go
|
||
export.go
|
||
dashboard/
|
||
dto.go
|
||
service.go
|
||
iam/
|
||
dto.go
|
||
service.go
|
||
permission.go
|
||
data_scope.go
|
||
audit/
|
||
dto.go
|
||
service.go
|
||
room3d/
|
||
dto.go
|
||
service.go
|
||
```
|
||
|
||
规则：
|
||
|
||
- `dto.go` 定义请求和响应结构，不直接向前端暴露 GORM 模型。
|
||
- `service.go` 做业务编排、权限判断、状态机调用和审计记录。
|
||
- `rescue.go` 处理失败救援，例如采集失败、通知失败、派单失败。
|
||
- `tsdb_adapter.go` 是 TDengine 访问边界。
|
||
- `statemachine/*.go` 只定义状态、合法迁移和校验方法。
|
||
|
||
## 16. Router 文件设计
|
||
|
||
统一前缀：
|
||
|
||
```text
|
||
/{ServiceKey}/v1
|
||
```
|
||
|
||
后续服务键建议从模板的 `Sample` 调整为 `OPS`。
|
||
|
||
```text
|
||
server/internal/routers/
|
||
register.go
|
||
resource.go
|
||
metric.go
|
||
collector.go
|
||
event.go
|
||
alert.go
|
||
notification.go
|
||
ticket.go
|
||
asset.go
|
||
topology.go
|
||
ipam.go
|
||
traffic.go
|
||
knowledge.go
|
||
report.go
|
||
dashboard.go
|
||
iam.go
|
||
audit.go
|
||
room3d.go
|
||
```
|
||
|
||
Router 规则：
|
||
|
||
- `register.go` 只负责调用各业务域注册函数。
|
||
- 每个业务域一个 `RegisterXxxRoutes`。
|
||
- 写操作挂鉴权中间件。
|
||
- 只做参数绑定和基础校验，业务校验放到 `logic/`。
|
||
- 不在 Router 中直接调用 `impl.DBService`。
|
||
|
||
## 17. REST API 设计
|
||
|
||
### 17.1 统一响应
|
||
|
||
成功响应：
|
||
|
||
```json
|
||
{
|
||
"code": "OK",
|
||
"message": "成功",
|
||
"traceId": "01HX...",
|
||
"suggestion": "",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
错误响应：
|
||
|
||
```json
|
||
{
|
||
"code": "COLLECT_AUTH_FAILED",
|
||
"message": "凭据不可用，请检查凭据引用和设备权限",
|
||
"traceId": "01HX...",
|
||
"suggestion": "修改凭据后重新执行采集任务",
|
||
"data": {
|
||
"currentStatus": "failed"
|
||
}
|
||
}
|
||
```
|
||
|
||
分页响应：
|
||
|
||
```json
|
||
{
|
||
"code": "OK",
|
||
"message": "成功",
|
||
"traceId": "01HX...",
|
||
"data": {
|
||
"total": 100,
|
||
"page": 1,
|
||
"size": 20,
|
||
"list": []
|
||
}
|
||
}
|
||
```
|
||
|
||
### 17.2 资源与业务系统
|
||
|
||
```text
|
||
GET /resources
|
||
POST /resources
|
||
GET /resources/:id
|
||
PUT /resources/:id
|
||
POST /resources/:id/enable
|
||
POST /resources/:id/disable
|
||
POST /resources/:id/maintenance
|
||
POST /resources/:id/decommission
|
||
GET /resources/:id/metrics
|
||
GET /resources/:id/alerts
|
||
GET /resources/:id/collector-runs
|
||
|
||
GET /resource-types
|
||
POST /resource-types
|
||
GET /business-systems
|
||
POST /business-systems
|
||
GET /business-systems/:id/health
|
||
GET /business-systems/:id/resources
|
||
```
|
||
|
||
### 17.3 指标与时序
|
||
|
||
```text
|
||
GET /metric-templates
|
||
POST /metric-templates
|
||
GET /metric-definitions
|
||
POST /metric-definitions
|
||
GET /metric-series
|
||
POST /metrics/query
|
||
POST /metrics/aggregate
|
||
POST /metrics/topn
|
||
GET /metric-retention-policies
|
||
POST /metric-retention-policies
|
||
```
|
||
|
||
`TSDBAdapter` 接口：
|
||
|
||
```go
|
||
// TSDBAdapter 定义 OPS 访问 TDengine 的唯一业务入口。
|
||
// 业务逻辑只能通过该接口读写时序样本，不能散落 TDengine 专有 SQL。
|
||
type TSDBAdapter interface {
|
||
WriteBatch(ctx context.Context, samples []MetricSample) error
|
||
QueryRange(ctx context.Context, req QueryRangeRequest) (QueryRangeReply, error)
|
||
Aggregate(ctx context.Context, req AggregateRequest) (AggregateReply, error)
|
||
TopN(ctx context.Context, req TopNRequest) (TopNReply, error)
|
||
CheckHealth(ctx context.Context) error
|
||
}
|
||
```
|
||
|
||
### 17.4 采集与发现
|
||
|
||
```text
|
||
GET /collector-tasks
|
||
POST /collector-tasks
|
||
GET /collector-tasks/:id
|
||
PUT /collector-tasks/:id
|
||
POST /collector-tasks/:id/enable
|
||
POST /collector-tasks/:id/disable
|
||
POST /collector-tasks/:id/run-now
|
||
GET /collector-tasks/:id/runs
|
||
|
||
GET /collector-runs
|
||
GET /collector-runs/:id
|
||
|
||
GET /discovery-tasks
|
||
POST /discovery-tasks
|
||
POST /discovery-tasks/:id/run-now
|
||
GET /discovery-results
|
||
|
||
GET /probe-targets
|
||
POST /probe-targets
|
||
PUT /probe-targets/:id
|
||
```
|
||
|
||
### 17.5 事件、Syslog 与 Trap
|
||
|
||
```text
|
||
POST /events/raw
|
||
GET /events/raw
|
||
GET /events/raw/:id
|
||
POST /events/raw/:id/replay
|
||
POST /events/replay-jobs
|
||
|
||
GET /syslog-rules
|
||
POST /syslog-rules
|
||
PUT /syslog-rules/:id
|
||
|
||
GET /trap-dictionaries
|
||
POST /trap-dictionaries
|
||
PUT /trap-dictionaries/:id
|
||
POST /trap-dictionaries/import
|
||
```
|
||
|
||
### 17.6 告警与事件治理
|
||
|
||
```text
|
||
GET /alerts
|
||
GET /alerts/:id
|
||
POST /alerts/:id/ack
|
||
POST /alerts/:id/ignore
|
||
POST /alerts/:id/recover
|
||
POST /alerts/:id/expire
|
||
POST /alerts/:id/dispatch-ticket
|
||
GET /alerts/:id/timeline
|
||
GET /alerts/:id/notifications
|
||
GET /alerts/:id/audits
|
||
|
||
GET /alert-rules
|
||
POST /alert-rules
|
||
PUT /alert-rules/:id
|
||
POST /alert-rules/:id/enable
|
||
POST /alert-rules/:id/disable
|
||
|
||
GET /silence-policies
|
||
POST /silence-policies
|
||
PUT /silence-policies/:id
|
||
|
||
GET /dedup-rules
|
||
POST /dedup-rules
|
||
|
||
GET /correlation-rules
|
||
POST /correlation-rules
|
||
|
||
GET /escalation-policies
|
||
POST /escalation-policies
|
||
|
||
GET /incidents
|
||
GET /incidents/:id
|
||
POST /incidents/:id/assign
|
||
POST /incidents/:id/start
|
||
POST /incidents/:id/suspend
|
||
POST /incidents/:id/resolve
|
||
POST /incidents/:id/close
|
||
```
|
||
|
||
### 17.7 通知与工单
|
||
|
||
```text
|
||
GET /notification-policies
|
||
POST /notification-policies
|
||
PUT /notification-policies/:id
|
||
|
||
GET /notification-templates
|
||
POST /notification-templates
|
||
PUT /notification-templates/:id
|
||
|
||
GET /notification-records
|
||
GET /notification-records/:id
|
||
POST /notification-records/:id/retry
|
||
|
||
GET /tickets
|
||
POST /tickets
|
||
GET /tickets/:id
|
||
POST /tickets/:id/accept
|
||
POST /tickets/:id/start
|
||
POST /tickets/:id/transfer
|
||
POST /tickets/:id/suspend
|
||
POST /tickets/:id/restart
|
||
POST /tickets/:id/withdraw
|
||
POST /tickets/:id/close
|
||
GET /tickets/:id/transitions
|
||
GET /tickets/:id/comments
|
||
POST /tickets/:id/comments
|
||
|
||
GET /ticket-dispatch-rules
|
||
POST /ticket-dispatch-rules
|
||
PUT /ticket-dispatch-rules/:id
|
||
```
|
||
|
||
### 17.8 资产、机房与 3D 接口
|
||
|
||
内部资产管理：
|
||
|
||
```text
|
||
GET /data-centers
|
||
POST /data-centers
|
||
GET /rooms
|
||
POST /rooms
|
||
GET /racks
|
||
POST /racks
|
||
GET /rack-units
|
||
PUT /rack-units/:id
|
||
GET /assets
|
||
POST /assets
|
||
PUT /assets/:id
|
||
POST /assets/:id/bind-resource
|
||
```
|
||
|
||
外包 3D 前端专用接口：
|
||
|
||
```text
|
||
GET /room3d/data-centers
|
||
GET /room3d/data-centers/:id/rooms
|
||
GET /room3d/rooms/:id/racks
|
||
GET /room3d/racks/:id/units
|
||
GET /room3d/resources/:id/status
|
||
GET /room3d/summary
|
||
```
|
||
|
||
### 17.9 P2 接口规划
|
||
|
||
拓扑：
|
||
|
||
```text
|
||
GET /topologies
|
||
POST /topologies
|
||
GET /topologies/:id/nodes
|
||
GET /topologies/:id/links
|
||
```
|
||
|
||
IPAM：
|
||
|
||
```text
|
||
GET /ipam/subnets
|
||
POST /ipam/subnets
|
||
GET /ipam/addresses
|
||
POST /ipam/scan-tasks
|
||
GET /ipam/change-records
|
||
```
|
||
|
||
流量：
|
||
|
||
```text
|
||
GET /traffic/links
|
||
POST /traffic/links
|
||
GET /traffic/policies
|
||
POST /traffic/policies
|
||
GET /traffic/anomalies
|
||
```
|
||
|
||
知识库：
|
||
|
||
```text
|
||
GET /knowledge/categories
|
||
POST /knowledge/categories
|
||
GET /knowledge/articles
|
||
POST /knowledge/articles
|
||
POST /knowledge/articles/:id/publish
|
||
POST /knowledge/articles/:id/review
|
||
```
|
||
|
||
### 17.10 报表、大屏、权限与审计
|
||
|
||
```text
|
||
GET /report-templates
|
||
POST /report-templates
|
||
POST /report-jobs
|
||
GET /report-jobs
|
||
GET /report-jobs/:id
|
||
POST /report-jobs/:id/export
|
||
GET /report-exports/:id/download
|
||
|
||
GET /dashboards
|
||
POST /dashboards
|
||
PUT /dashboards/:id
|
||
GET /dashboards/:id/widgets
|
||
POST /dashboards/:id/widgets
|
||
PUT /dashboard-widgets/:id
|
||
|
||
GET /iam/organizations
|
||
POST /iam/organizations
|
||
GET /iam/users
|
||
POST /iam/users
|
||
POST /iam/users/:id/enable
|
||
POST /iam/users/:id/disable
|
||
GET /iam/roles
|
||
POST /iam/roles
|
||
PUT /iam/roles/:id/permissions
|
||
PUT /iam/data-scopes/:id
|
||
|
||
GET /audit-logs
|
||
GET /system-logs
|
||
```
|
||
|
||
## 18. 注释规范
|
||
|
||
后续生成 Go 文件时使用中文注释，注释要说明业务意图，不重复代码字面含义。
|
||
|
||
推荐注释位置：
|
||
|
||
- 每个模型结构体顶部说明表职责、阶段和对应 OPS 编号。
|
||
- 每个状态机文件顶部说明状态来源和禁止绕过规则。
|
||
- 每个 Service 的公开方法说明业务动作和审计要求。
|
||
- 每个错误码说明触发场景、用户提示和建议动作。
|
||
- TDengine 适配器说明为什么不能在业务逻辑中直接写 TDengine SQL。
|
||
|
||
示例：
|
||
|
||
```go
|
||
// Resource 是 OPS 的统一监控资源主表。
|
||
// 覆盖 OPS-002 至 OPS-014、OPS-031，用于承载主机、网络设备、数据库、
|
||
// 虚拟化、URL/API 等被监控对象。状态流转必须通过 statemachine 校验。
|
||
type Resource struct {
|
||
models.BaseModel
|
||
}
|
||
```
|
||
|
||
不建议的注释：
|
||
|
||
```go
|
||
// Name 是名称
|
||
Name string
|
||
```
|
||
|
||
## 19. 实施顺序建议
|
||
|
||
第一批实现：
|
||
|
||
```text
|
||
models/base.go
|
||
models/resource/
|
||
models/metric/
|
||
models/collector/
|
||
models/event/
|
||
models/alert/
|
||
models/notification/
|
||
models/ticket/
|
||
models/iam/
|
||
models/audit/
|
||
logic/response/
|
||
logic/statemachine/
|
||
routers/register.go
|
||
```
|
||
|
||
第二批实现：
|
||
|
||
```text
|
||
models/report/
|
||
models/asset/
|
||
logic/report/
|
||
logic/dashboard/
|
||
logic/room3d/
|
||
routers/report.go
|
||
routers/dashboard.go
|
||
routers/room3d.go
|
||
```
|
||
|
||
第三批实现：
|
||
|
||
```text
|
||
models/topology/
|
||
models/ipam/
|
||
models/traffic/
|
||
models/knowledge/
|
||
logic/topology/
|
||
logic/ipam/
|
||
logic/traffic/
|
||
logic/knowledge/
|
||
```
|
||
|
||
## 20. 自审结论
|
||
|
||
- 本设计覆盖 OPS-001 至 OPS-033 的模型和接口边界。
|
||
- 首期闭环与 P2/P3 预留已分离。
|
||
- 未引入旧项目名。
|
||
- 未要求修改 `templates/`。
|
||
- 未使用 Linux 命令示例。
|
||
- 状态机、统一响应、TDengine 适配层、故障救援和审计边界均有明确落点。
|