收口七月卡状态回调与系列授权兼容契约

完成运营商实名回调、业务事件观测序列与受控配置装配，同时恢复 UR43 已交付的 packages[].remove 字段及旧响应兼容，统一更新 OpenSpec、OpenAPI 和交付文档。

Constraint: 七月测试环境里程碑不新增或运行自动化测试

Rejected: 以必填 operation_type 替换 packages[].remove | 会破坏已交付前端契约

Confidence: high

Scope-risk: broad

Directive: 后续修改系列套餐管理接口必须保持 packages[].remove 和 ShopSeriesGrantResponse 兼容

Tested: go run ./cmd/gendocs；go build -buildvcs=false ./...；openspec validate complete-july-iteration-test-release --strict；git diff --check

Not-tested: 按本 Change 约定未运行 go test，真实运营商与 Gateway 联调延期

pkg/constants/card_observation.go

@@ -30,7 +30,7 @@ const (
 	CardObservationSeriesAttemptCount = 3                // 每个序列固定尝试次数
 	CardObservationSeriesTTL          = 7 * time.Minute  // 活跃序列覆盖最后一次任务及缓冲
 	CardObservationSeriesResultTTL    = 24 * time.Hour   // 尝试幂等与提前完成结果保留时间
-	CardObservationGatewayLockTTL     = 70 * time.Second // Gateway 请求互斥超时加安全余量
+	CardObservationGatewayLockTTL     = 16 * time.Minute // 覆盖 300 秒超时、两次网络重试及安全余量
 	CardObservationGatewayMinInterval = 10 * time.Second // 未配置时的运营商最小请求间隔
 )
 
@@ -64,27 +64,46 @@ const (
 
 // Gateway 轮询 Integration Log 操作编码。
 const (
-	IntegrationProviderGateway          = "gateway"               // Gateway 外部系统
-	IntegrationOperationGatewayRealname = "query_realname_status" // 查询实名状态
-	IntegrationOperationGatewayTraffic  = "query_flow"            // 查询流量
-	IntegrationOperationGatewayNetwork  = "query_card_status"     // 查询网络状态
+	IntegrationProviderGateway            = "gateway"               // Gateway 外部系统
+	IntegrationOperationGatewayRealname   = "query_realname_status" // 查询实名状态
+	IntegrationOperationGatewayTraffic    = "query_flow"            // 查询流量
+	IntegrationOperationGatewayNetwork    = "query_card_status"     // 查询网络状态
+	IntegrationOperationGatewayDeviceInfo = "query_device_info"     // 查询设备信息
 )
 
 // 卡实名观测场景
 const (
-	CardObservationSceneRealnamePolling = "realname_polling"          // 实名轮询
-	CardObservationSceneTrafficPolling  = "traffic_polling"           // 流量轮询
-	CardObservationSceneNetworkPolling  = "network_polling"           // 网络状态轮询
-	CardObservationSceneManualRefresh   = "manual_refresh"            // 手动刷新
-	CardObservationSceneCarrierCallback = "carrier_realname_callback" // 运营商实名回调
+	CardObservationSceneRealnamePolling    = "realname_polling"          // 实名轮询
+	CardObservationSceneTrafficPolling     = "traffic_polling"           // 流量轮询
+	CardObservationSceneNetworkPolling     = "network_polling"           // 网络状态轮询
+	CardObservationSceneManualRefresh      = "manual_refresh"            // 手动刷新
+	CardObservationSceneCarrierCallback    = "carrier_realname_callback" // 运营商实名回调
+	CardObservationSceneClientAssetRead    = "client_asset_read"         // C 端资产详情读取
+	CardObservationSceneAdminAssetRead     = "admin_asset_realtime"      // 后台资产实时状态读取
+	CardObservationSceneOpenCardTraffic    = "openapi_card_traffic"      // OpenAPI 卡流量读取
+	CardObservationSceneOpenCardNetwork    = "openapi_card_network"      // OpenAPI 卡网络读取
+	CardObservationSceneOpenCardRealname   = "openapi_card_realname"     // OpenAPI 卡实名读取
+	CardObservationSceneOpenDeviceTraffic  = "openapi_device_traffic"    // OpenAPI 设备流量读取
+	CardObservationSceneClientRealnameLink = "client_realname_link"      // C 端获取实名链接
+	CardObservationSceneAdminRealnameLink  = "admin_realname_link"       // 后台获取实名链接
+	CardObservationSceneBusinessStop       = "business_stop"             // 业务停机成功
+	CardObservationSceneBusinessResume     = "business_resume"           // 业务复机成功
+	CardObservationScenePackageChanged     = "package_changed"           // 购包或套餐激活成功
+	CardObservationSceneDeviceSwitchCard   = "device_switch_card"        // 设备切卡成功
+	CardObservationSceneDeviceSwitchMode   = "device_switch_mode"        // 设备切卡模式成功
+	CardObservationSceneDeviceReboot       = "device_reboot"             // 设备重启成功
+	CardObservationSceneDeviceReset        = "device_reset"              // 设备恢复出厂成功
+	CardObservationSceneDeviceSetWiFi      = "device_set_wifi"           // 设备 WiFi 设置成功
 )
 
 // 卡实名状态变更 Outbox 事件
 const (
-	OutboxEventTypeCardRealnameChanged     = "card.realname.changed"    // 卡实名状态变化
-	CardRealnameChangedPayloadVersionV1    = 1                          // 卡实名状态变化载荷版本
-	OutboxEventTypeCardTrafficIncremented  = "card.traffic.incremented" // 卡流量正增量
-	CardTrafficIncrementedPayloadVersionV1 = 1                          // 卡流量正增量载荷版本
-	OutboxEventTypeCardNetworkChanged      = "card.network.changed"     // 卡网络状态变化
-	CardNetworkChangedPayloadVersionV1     = 1                          // 卡网络状态变化载荷版本
+	OutboxEventTypeCardRealnameChanged     = "card.realname.changed"             // 卡实名状态变化
+	CardRealnameChangedPayloadVersionV1    = 1                                   // 卡实名状态变化载荷版本
+	OutboxEventTypeCardTrafficIncremented  = "card.traffic.incremented"          // 卡流量正增量
+	CardTrafficIncrementedPayloadVersionV1 = 1                                   // 卡流量正增量载荷版本
+	OutboxEventTypeCardNetworkChanged      = "card.network.changed"              // 卡网络状态变化
+	CardNetworkChangedPayloadVersionV1     = 1                                   // 卡网络状态变化载荷版本
+	OutboxEventTypeCardSeriesRequested     = "card.observation.series.requested" // 业务成功请求卡观测序列
+	CardSeriesRequestedPayloadVersionV1    = 1                                   // 业务成功观测序列载荷版本
 )

pkg/constants/integration_log.go

@@ -1,5 +1,7 @@
 package constants
 
+import "time"
+
 const (
 	// IntegrationDirectionInbound 表示外部系统调用本系统。
 	IntegrationDirectionInbound = "inbound"
@@ -7,6 +9,25 @@ const (
 	IntegrationDirectionOutbound = "outbound"
 )
 
+const (
+	// IntegrationProviderCTCC 表示中国电信回调提供方。
+	IntegrationProviderCTCC = "ctcc"
+	// IntegrationOperationCTCCRealnameCallback 表示中国电信实名结果回调。
+	IntegrationOperationCTCCRealnameCallback = "realname_callback"
+	// IntegrationProviderCMCC 表示中国移动回调提供方。
+	IntegrationProviderCMCC = "cmcc"
+	// IntegrationOperationCMCCRealnameCallback 表示中国移动实名结果回调。
+	IntegrationOperationCMCCRealnameCallback = "realname_callback"
+	// IntegrationProviderCUCC 表示中国联通回调提供方。
+	IntegrationProviderCUCC = "cucc"
+	// IntegrationOperationCUCCRealnameRemovalCallback 表示中国联通解除实名回调。
+	IntegrationOperationCUCCRealnameRemovalCallback = "realname_removal_callback"
+	// IntegrationOperationCUCCRealnameCallback 表示中国联通实名成功回调。
+	IntegrationOperationCUCCRealnameCallback = "realname_callback"
+	// IntegrationInboundProcessingLease 表示入站回调 pending 记录允许恢复前的处理租约。
+	IntegrationInboundProcessingLease = time.Minute
+)
+
 const (
 	// IntegrationResultPending 表示外部尝试已建立但尚未终结。
 	IntegrationResultPending = "pending"
@@ -20,6 +41,8 @@ const (
 	IntegrationResultNotFound = "not_found"
 	// IntegrationResultInvalidPayload 表示入站载荷无效。
 	IntegrationResultInvalidPayload = "invalid_payload"
+	// IntegrationResultConflict 表示入站事实存在唯一性或幂等冲突。
+	IntegrationResultConflict = "conflict"
 	// IntegrationResultIgnored 表示外部尝试被安全忽略。
 	IntegrationResultIgnored = "ignored"
 	// IntegrationResultMerged 表示尝试被合并且未发送请求。
@@ -41,6 +64,7 @@ func IntegrationResultName(result string) string {
 		IntegrationResultUnknown:        "结果未知",
 		IntegrationResultNotFound:       "未找到",
 		IntegrationResultInvalidPayload: "无效载荷",
+		IntegrationResultConflict:       "冲突",
 		IntegrationResultIgnored:        "已忽略",
 		IntegrationResultMerged:         "已合并",
 		IntegrationResultRateLimited:    "已限频",

pkg/constants/redis.go

@@ -494,6 +494,11 @@ func RedisCardObservationAttemptKey(seriesID string, attempt int) string {
 	return fmt.Sprintf("cardsync:attempt:%s:%d", seriesID, attempt)
 }
 
+// RedisCardObservationScheduleKey 返回固定阶梯任务的入队幂等键。
+func RedisCardObservationScheduleKey(seriesID string, attempt int) string {
+	return fmt.Sprintf("cardsync:schedule:%s:%d", seriesID, attempt)
+}
+
 // RedisCardObservationInflightKey 返回一次实际 Gateway 请求的互斥键。
 func RedisCardObservationInflightKey(provider, syncType, resourceID string) string {
 	return fmt.Sprintf("cardsync:inflight:%s:%s:%s", provider, syncType, resourceID)

pkg/constants/shop_series_grant.go

@@ -0,0 +1,6 @@
+package constants
+
+const (
+	// ShopSeriesGrantMaxPackages 系列授权单次最多处理的套餐数量。
+	ShopSeriesGrantMaxPackages = 100
+)

pkg/constants/system_config.go

@@ -16,6 +16,16 @@ const (
 	SystemConfigTypeJSON = "json"
 	// SystemConfigCacheTTL 是系统配置默认缓存时长。
 	SystemConfigCacheTTL = 5 * time.Minute
+	// SystemConfigModuleCarrierCallback 是运营商回调配置模块。
+	SystemConfigModuleCarrierCallback = "carrier_callback"
+	// SystemConfigCarrierCallbackCTCCRealnameEnabled 控制电信实名回调是否执行业务处理。
+	SystemConfigCarrierCallbackCTCCRealnameEnabled = "carrier_callback.ctcc_realname.enabled"
+	// SystemConfigCarrierCallbackCMCCRealnameEnabled 控制移动实名回调是否执行业务处理。
+	SystemConfigCarrierCallbackCMCCRealnameEnabled = "carrier_callback.cmcc_realname.enabled"
+	// SystemConfigCarrierCallbackCUCCRealnameEnabled 控制联通实名成功回调是否执行业务处理。
+	SystemConfigCarrierCallbackCUCCRealnameEnabled = "carrier_callback.cucc_realname.enabled"
+	// SystemConfigCarrierCallbackCUCCRealnameRemovalEnabled 控制联通解除实名回调是否执行业务处理。
+	SystemConfigCarrierCallbackCUCCRealnameRemovalEnabled = "carrier_callback.cucc_realname_removal.enabled"
 )
 
 // RedisSystemConfigKey 生成单个系统配置的 Redis 缓存键。