七月迭代短暂完结,还有很多后端的关键东西没有弄,这是一版赶时间做的东西

internal/model/dto/notification_dto.go

@@ -26,9 +26,9 @@ type NotificationItem struct {
 	Severity  string     `json:"severity" description:"通知级别 (info:提示, warning:警告, error:错误, critical:严重)"`
 	Title     string     `json:"title" description:"纯文本标题"`
 	Body      string     `json:"body" description:"纯文本正文"`
-	RefType   string     `json:"ref_type" description:"受控资源类型"`
-	RefID     string     `json:"ref_id" description:"受控资源ID"`
-	RefKey    string     `json:"ref_key" description:"受控资源Key"`
+	RefType   string     `json:"ref_type" description:"受控资源类型；可能为空。可选值及含义：system_config:系统配置, integration_log:外部集成日志, package:套餐, asset:C端资产, refund:退款, agent_recharge:代理充值, wecom_approval:企微审批, iot_card:物联网卡, device:设备, expiring_asset:临期资产列表, shop_fund:店铺资金概况, card_sync:卡同步记录。后台点击通知应调用目标解析接口，不得直接拼接路由"`
+	RefID     string     `json:"ref_id" description:"受控资源数字ID的十进制字符串；可能为空。refund、agent_recharge、wecom_approval、iot_card、device、expiring_asset、shop_fund、asset 等类型使用；仅用于资源定位，不是前端URL"`
+	RefKey    string     `json:"ref_key" description:"受控资源稳定Key或展示快照；可能为空。system_config 为配置Key，integration_log/card_sync 为集成标识，asset 为资产标识快照；仅用于定位或展示，不是前端URL"`
 	IsRead    bool       `json:"is_read" description:"是否已读"`
 	ReadAt    *time.Time `json:"read_at,omitempty" description:"首次已读时间（ISO 8601）"`
 	CreatedAt time.Time  `json:"created_at" description:"创建时间（ISO 8601）"`
@@ -54,10 +54,10 @@ type NotificationReadResponse struct {
 
 // NotificationTargetResponse 是通知受控目标解析结果，不包含任意 URL。
 type NotificationTargetResponse struct {
-	TargetType string `json:"target_type" description:"前端白名单目标类型；空表示不支持跳转"`
-	TargetID   *uint  `json:"target_id,omitempty" description:"受控数值目标ID"`
-	TargetKey  string `json:"target_key,omitempty" description:"受控稳定目标Key"`
-	Available  bool   `json:"available" description:"当前账号是否仍可访问目标"`
+	TargetType string `json:"target_type" description:"前端白名单目标类型；空表示不支持跳转。可选值：refund_detail、agent_recharge_detail、wecom_approval_detail、iot_card_detail、device_detail、expiring_asset_list、shop_fund_summary、integration_log、system_config"`
+	TargetID   *uint  `json:"target_id,omitempty" description:"ID型目标的业务主键；前端按 target_type 映射受控页面，不得自行拼接任意URL"`
+	TargetKey  string `json:"target_key,omitempty" description:"Key型目标的稳定定位值；仅用于 integration_log 或 system_config 等白名单目标"`
+	Available  bool   `json:"available" description:"当前账号是否仍可访问目标；false 时只展示通知正文，不执行跳转"`
 }
 
 // NotificationUnreadSummaryResponse 是后台账号未读通知的固定分类汇总。
@@ -81,8 +81,9 @@ type NotificationReadAllResponse struct {
 
 // PersonalNotificationListRequest 是个人客户通知的简化分页参数。
 type PersonalNotificationListRequest struct {
-	Page     int `json:"page" query:"page" validate:"omitempty,min=1,max=10000" minimum:"1" maximum:"10000" description:"页码，默认 1，最大 10000"`
-	PageSize int `json:"page_size" query:"page_size" validate:"omitempty,min=1,max=50" minimum:"1" maximum:"50" description:"每页数量，默认 20，最大 50"`
+	IsRead   *bool `json:"is_read" query:"is_read" description:"已读状态；false 仅查询未读，true 仅查询已读，不传时查询全部"`
+	Page     int   `json:"page" query:"page" validate:"omitempty,min=1,max=10000" minimum:"1" maximum:"10000" description:"页码，默认 1，最大 10000"`
+	PageSize int   `json:"page_size" query:"page_size" validate:"omitempty,min=1,max=50" minimum:"1" maximum:"50" description:"每页数量，默认 20，最大 50"`
 }
 
 // PersonalNotificationListResponse 是个人客户通知的简化分页结果。