diff --git a/docs/superpowers/specs/2026-06-21-ops-project-structure-data-model-api-design.md b/docs/superpowers/specs/2026-06-21-ops-project-structure-data-model-api-design.md new file mode 100644 index 0000000..2de40e9 --- /dev/null +++ b/docs/superpowers/specs/2026-06-21-ops-project-structure-data-model-api-design.md @@ -0,0 +1,1079 @@ +# 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 适配层、故障救援和审计边界均有明确落点。