junhong_cmp_fiber/internal/routes/audit.go

package routes

import (
	"github.com/gofiber/fiber/v2"

	"github.com/break/junhong_cmp_fiber/internal/handler/admin"
	"github.com/break/junhong_cmp_fiber/internal/model/dto"
	auditquery "github.com/break/junhong_cmp_fiber/internal/query/audit"
	integrationquery "github.com/break/junhong_cmp_fiber/internal/query/integration"
	"github.com/break/junhong_cmp_fiber/pkg/openapi"
)

// registerAuditRoutes 注册平台基础审计调查只读路由。
func registerAuditRoutes(router fiber.Router, handler *admin.AuditHandler, doc *openapi.Generator, basePath string) {
	agent := router.Group("/agent/resource-activities")
	Register(agent, doc, basePath+"/agent/resource-activities", "GET", "/:resource_type/:identifier", handler.AgentResourceActivities, RouteSpec{
		Summary:     "查询代理资源活动",
		Description: "resource_type/identifier 来自代理当前业务页面稳定字段；店铺范围只读取认证上下文。仅查询 retention 标明的在线窗口，归档范围不从对象存储读取。",
		Tags:        []string{"资源活动"}, Input: new(dto.SubjectResourceActivityRequest), Output: new(auditquery.SubjectActivityPage), Auth: true,
	})
	enterprise := router.Group("/enterprise/resource-activities")
	Register(enterprise, doc, basePath+"/enterprise/resource-activities", "GET", "/:resource_type/:identifier", handler.EnterpriseResourceActivities, RouteSpec{
		Summary:     "查询企业资源活动",
		Description: "仅支持企业当前有效授权的卡和设备；企业身份只读取认证上下文。仅查询 retention 标明的在线窗口，响应不包含平台内部调查字段。",
		Tags:        []string{"资源活动"}, Input: new(dto.SubjectResourceActivityRequest), Output: new(auditquery.SubjectActivityPage), Auth: true,
	})

	audit := router.Group("/audit")
	groupPath := basePath + "/audit"

	Register(audit, doc, groupPath, "GET", "/events", handler.ListEvents, RouteSpec{
		Summary:     "查询全局审计事件",
		Description: "筛选值来自调查人员输入或其他调查节点的稳定引用；缺省只查 retention 标明的在线窗口，归档范围返回稳定错误。固定倒序分页，不提供导出、修改或删除。",
		Tags:        []string{"审计调查"}, Input: new(dto.AuditEventListRequest), Output: new(auditquery.EventPage), Auth: true,
	})
	Register(audit, doc, groupPath, "GET", "/events/:event_id", handler.GetEvent, RouteSpec{
		Summary:     "查询审计事件详情",
		Description: "event_id 来自 investigation_refs；只查询在线 PostgreSQL，未命中仍返回资源不存在，不扫描对象存储。返回全部资源快照和各资源 before/after。",
		Tags:        []string{"审计调查"}, Input: new(dto.AuditEventIDParams), Output: new(auditquery.EventDetail), Auth: true,
	})
	Register(audit, doc, groupPath, "GET", "/actors/:kind/:id/events", handler.ListActorEvents, RouteSpec{
		Summary:     "查询操作者行为时间线",
		Description: "kind/id 来自事件 actor_ref 或平台账号选择器；历史名称直接使用事件快照，不查询当前账号名称覆盖历史。",
		Tags:        []string{"审计调查"}, Input: new(dto.AuditActorEventsRequest), Output: new(auditquery.EventPage), Auth: true,
	})
	// 资源搜索静态路径必须先于资源动态时间线路径，避免被动态参数吞掉。
	Register(audit, doc, groupPath, "GET", "/resources/search", handler.SearchResources, RouteSpec{
		Summary:     "精确搜索注册资源",
		Description: "卡支持 ICCID/VirtualNo，设备支持 VirtualNo/IMEI/SN，店铺、订单、退款使用各自稳定编号。当前资源不存在时仅按 Registry 白名单快照字段精确查找历史，不做任意 JSON 模糊搜索。",
		Tags:        []string{"审计调查"}, Input: new(dto.AuditResourceSearchRequest), Output: new(auditquery.ResourceSearchPage), Auth: true,
	})
	Register(audit, doc, groupPath, "GET", "/resources/:resource_type/:resource_id/timeline", handler.ResourceTimeline, RouteSpec{
		Summary:     "查询通用资源时间线",
		Description: "resource_type/resource_id 必须来自业务页面稳定字段、资源搜索结果或 investigation_refs。事件在资源作为 primary、affected 或 reference 时均会返回。",
		Tags:        []string{"审计调查"}, Input: new(dto.AuditResourceTimelineRequest), Output: new(auditquery.EventPage), Auth: true,
	})
	Register(audit, doc, groupPath, "GET", "/requests/:request_id/timeline", handler.RequestTimeline, RouteSpec{
		Summary:     "查询请求关联时间线",
		Description: "request_id 来自审计或外部集成节点，也可从 Access Log 粘贴。只组合 retention 在线窗口内的持久化事实，不扫描 Access Log 或对象存储。",
		Tags:        []string{"审计调查"}, Input: new(dto.AuditRequestTimelineParams), Output: new(auditquery.LinkTimeline), Auth: true,
	})
	Register(audit, doc, groupPath, "GET", "/correlations/:correlation_id/timeline", handler.CorrelationTimeline, RouteSpec{
		Summary:     "查询业务关联时间线",
		Description: "correlation_id 来自稳定调查引用。只组合 retention 在线窗口内的持久化事实；相同 correlation 不用于猜测技术重试。",
		Tags:        []string{"审计调查"}, Input: new(dto.AuditCorrelationTimelineParams), Output: new(auditquery.LinkTimeline), Auth: true,
	})
	Register(audit, doc, groupPath, "GET", "/finance/timeline", handler.FinanceTimeline, RouteSpec{
		Summary:     "查询资金调查时间线",
		Description: "可使用任一稳定资金条件进入；缺省只查 retention 在线窗口，归档范围不返回部分结果。关联事实由服务端解析，金额以业务账本为权威。",
		Tags:        []string{"审计调查"}, Input: new(dto.AuditFinanceTimelineRequest), Output: new(auditquery.FinanceTimelinePage), Auth: true,
	})
	Register(audit, doc, groupPath, "GET", "/risks/overview", handler.RiskOverview, RouteSpec{
		Summary:     "查询风险调查总览",
		Description: "时间范围最长31天，缺省时使用当前在线窗口；只聚合高风险、资金、安全、失败、拒绝、部分成功和结果未知事件。",
		Tags:        []string{"审计调查"}, Input: new(dto.AuditRiskOverviewRequest), Output: new(auditquery.RiskOverview), Auth: true,
	})
	Register(audit, doc, groupPath, "GET", "/risks/events", handler.RiskEvents, RouteSpec{
		Summary:     "查询风险事件明细",
		Description: "筛选条件来自风险总览分桶或调查人员输入，缺省只查 retention 在线窗口；明细返回 investigation_refs，不提供处置或封禁能力。",
		Tags:        []string{"审计调查"}, Input: new(dto.AuditRiskEventsRequest), Output: new(auditquery.RiskEventPage), Auth: true,
	})
	// Integration 总览静态路径必须先于动态详情路径，避免 overview 被当作 integration_id。
	Register(audit, doc, groupPath, "GET", "/integrations/overview", handler.IntegrationOverview, RouteSpec{
		Summary:     "查询外部集成交互总览",
		Description: "筛选和时间范围来自调查输入或关联视角跳转；缺省只查 retention 在线窗口，归档范围返回稳定错误。总览区分五类结果。",
		Tags:        []string{"审计调查"}, Input: new(dto.IntegrationOverviewRequest), Output: new(integrationquery.Overview), Auth: true,
	})
	Register(audit, doc, groupPath, "GET", "/integrations", handler.ListIntegrations, RouteSpec{
		Summary:     "查询外部集成交互列表",
		Description: "组合筛选来自调查输入或稳定引用；缺省只查 retention 在线窗口，归档范围不返回空页或部分结果。固定倒序分页，不提供任意摘要搜索。",
		Tags:        []string{"审计调查"}, Input: new(dto.IntegrationListRequest), Output: new(integrationquery.ListPage), Auth: true,
	})
	Register(audit, doc, groupPath, "GET", "/integrations/:integration_id", handler.GetIntegration, RouteSpec{
		Summary:     "查询外部集成交互详情",
		Description: "integration_id 来自稳定引用；只查询在线 PostgreSQL，未命中仍返回资源不存在。展示结构化详情和在线尝试序列，不提供归档读取、恢复、修改、删除或导出。",
		Tags:        []string{"审计调查"}, Input: new(dto.IntegrationIDParams), Output: new(integrationquery.DetailResponse), Auth: true,
	})
}