ops/docs/superpowers/specs/2026-06-21-ops-project-structure-data-model-api-design.md

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