# 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 适配层、故障救援和审计边界均有明确落点。