31 KiB
31 KiB
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. 后端目录结构
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/ 当前不存在。后续从前端模板初始化后，建议使用以下业务边界：
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：
// 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. 资源与业务系统模型
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. 指标、模板与时序映射模型
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. 采集、发现与探测模型
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 模型
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. 告警与事件治理模型
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. 通知与工单模型
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 接口模型
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、流量与知识库模型
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. 报表、大屏、权限与审计模型
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 文件设计
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 文件设计
统一前缀：
/{ServiceKey}/v1
后续服务键建议从模板的 Sample 调整为 OPS。
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 统一响应
成功响应：
{
"code": "OK",
"message": "成功",
"traceId": "01HX...",
"suggestion": "",
"data": {}
}
错误响应：
{
"code": "COLLECT_AUTH_FAILED",
"message": "凭据不可用，请检查凭据引用和设备权限",
"traceId": "01HX...",
"suggestion": "修改凭据后重新执行采集任务",
"data": {
"currentStatus": "failed"
}
}
分页响应：
{
"code": "OK",
"message": "成功",
"traceId": "01HX...",
"data": {
"total": 100,
"page": 1,
"size": 20,
"list": []
}
}
17.2 资源与业务系统
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 指标与时序
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 接口：
// 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 采集与发现
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
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 告警与事件治理
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 通知与工单
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 接口
内部资产管理：
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 前端专用接口：
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 接口规划
拓扑：
GET /topologies
POST /topologies
GET /topologies/:id/nodes
GET /topologies/:id/links
IPAM：
GET /ipam/subnets
POST /ipam/subnets
GET /ipam/addresses
POST /ipam/scan-tasks
GET /ipam/change-records
流量：
GET /traffic/links
POST /traffic/links
GET /traffic/policies
POST /traffic/policies
GET /traffic/anomalies
知识库：
GET /knowledge/categories
POST /knowledge/categories
GET /knowledge/articles
POST /knowledge/articles
POST /knowledge/articles/:id/publish
POST /knowledge/articles/:id/review
17.10 报表、大屏、权限与审计
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。
示例：
// Resource 是 OPS 的统一监控资源主表。
// 覆盖 OPS-002 至 OPS-014、OPS-031，用于承载主机、网络设备、数据库、
// 虚拟化、URL/API 等被监控对象。状态流转必须通过 statemachine 校验。
type Resource struct {
models.BaseModel
}
不建议的注释：
// Name 是名称
Name string
19. 实施顺序建议
第一批实现：
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
第二批实现：
models/report/
models/asset/
logic/report/
logic/dashboard/
logic/room3d/
routers/report.go
routers/dashboard.go
routers/room3d.go
第三批实现：
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 适配层、故障救援和审计边界均有明确落点。