'inspect', 'pool_id' => self::positiveInteger( $options['pool-id'] ?? null, 'pool-id' ), ]; } if ($action === 'resolve') { $options = self::options(array_slice($argv, 3), [ 'pool-id', 'expected-version', 'resolution-key', 'apply', 'confirm', ]); $poolId = self::positiveInteger( $options['pool-id'] ?? null, 'pool-id' ); $expectedVersion = self::positiveInteger( $options['expected-version'] ?? null, 'expected-version' ); $resolutionKey = self::resolutionKey( $options['resolution-key'] ?? null ); if (($options['apply'] ?? null) !== true) { throw new \InvalidArgumentException( '解除 attention 必须显式提供 --apply' ); } $confirmation = self::confirmation( $poolId, $expectedVersion, $resolutionKey ); if (!is_string($options['confirm'] ?? null) || !hash_equals($confirmation, $options['confirm'])) { throw new \InvalidArgumentException( '确认词不匹配,请先执行 inspect 并绑定精确池版本' ); } return [ 'action' => 'resolve', 'pool_id' => $poolId, 'expected_version' => $expectedVersion, 'resolution_key' => $resolutionKey, ]; } if ($action === 'inspect-resolution') { $options = self::options( array_slice($argv, 3), ['resolution-key'] ); return [ 'action' => 'inspect-resolution', 'resolution_key' => self::resolutionKey( $options['resolution-key'] ?? null ), ]; } throw new \InvalidArgumentException( '用法:php xcat cloudTrafficPoolAttention inspect --pool-id=N;' . '或 inspect-resolution --resolution-key=UUID;' . '或 resolve --pool-id=N --expected-version=V ' . '--resolution-key=UUID --apply ' . '--confirm=RESOLVE_TRAFFIC_POOL:N:V:UUID' ); } private static function inspectPool(int $poolId): array { $pool = CloudTrafficPool::find($poolId); if ($pool === null) { throw new \RuntimeException('流量池不存在'); } $observedState = (string) $pool->state; $observedVersion = (int) $pool->version; $verification = CloudTrafficPoolAccounting::verifyProjection($poolId); $latestResolution = (int) (CloudTrafficLedgerEvent::where( 'pool_id', $poolId )->where('event_type', 'attention_resolved')->max('id') ?? 0); $eventCounts = CloudTrafficLedgerEvent::where('pool_id', $poolId) ->where('id', '>', $latestResolution) ->whereIn('event_type', [ 'accounting_attention', 'counter_attention', ])->selectRaw('event_type, COUNT(*) AS aggregate') ->groupBy('event_type')->pluck('aggregate', 'event_type'); $cursorCount = CloudTrafficInstanceCursor::where( 'pool_id', $poolId )->where('state', 'attention')->count(); $fresh = CloudTrafficPool::find($poolId); if ($fresh === null || (string) $fresh->state !== $observedState || (int) $fresh->version !== $observedVersion) { throw new \RuntimeException( '流量池在核对期间已变化,请重新执行 inspect' ); } $issueCounts = []; foreach (is_array($verification['errors'] ?? null) ? $verification['errors'] : [] as $error) { $code = match (true) { str_starts_with((string) $error, 'entitlement:') => 'entitlement_projection_mismatch', (string) $error === 'pool:overage' => 'pool_overage_mismatch', (string) $error === 'pool:available' => 'pool_available_mismatch', default => 'projection_mismatch', }; $issueCounts[$code] = ($issueCounts[$code] ?? 0) + 1; } ksort($issueCounts, SORT_STRING); $issues = []; foreach ($issueCounts as $code => $count) { $issues[] = ['code' => $code, 'count' => $count]; } return [ 'action' => 'inspect', 'pool_id' => (int) $pool->id, 'traffic_pool_group_id' => (int) $pool->traffic_pool_group_id, 'state' => (string) $fresh->state, 'version' => (int) $fresh->version, 'available_bytes' => (int) $fresh->available_bytes, 'overage_bytes' => (int) $fresh->overage_bytes, 'projection_valid' => (bool) ($verification['valid'] ?? false), 'projection_issues' => $issues, 'attention_cursor_count' => $cursorCount, 'unresolved_attention_event_count' => (int) ($eventCounts['accounting_attention'] ?? 0) + (int) ($eventCounts['counter_attention'] ?? 0), 'attention_categories' => [ 'accounting_attention' => (int) ($eventCounts['accounting_attention'] ?? 0), 'counter_attention' => (int) ($eventCounts['counter_attention'] ?? 0), ], 'confirmation_prefix' => self::CONFIRM_PREFIX . ':' . $poolId . ':' . (int) $fresh->version . ':', ]; } private static function resolvePool( int $poolId, int $expectedVersion, string $resolutionKey ): array { $eventKey = self::resolutionEventKey($resolutionKey); if (CloudTrafficLedgerEvent::where('event_key', $eventKey)->exists() || CloudTrafficLedgerEvent::where( 'source_type', 'admin_reconciliation' )->where('source_id', $resolutionKey)->exists()) { throw new \RuntimeException( 'resolution-key 已使用;请执行 inspect-resolution ' . '--resolution-key=<原 UUID> 核对,不要盲目重试' ); } $before = CloudTrafficPool::find($poolId); if ($before === null) { throw new \RuntimeException('流量池不存在'); } if ((string) $before->state !== 'attention') { throw new \RuntimeException('流量池当前不处于 attention 状态'); } $result = CloudTrafficPoolAccounting::resolveAttention( $poolId, $expectedVersion, $resolutionKey ); if (($result['changed'] ?? false) !== true) { throw new \RuntimeException('attention 未被解除,请重新 inspect'); } $event = CloudTrafficLedgerEvent::where('event_key', $eventKey) ->where('pool_id', $poolId) ->where('event_type', 'attention_resolved') ->where('source_type', 'admin_reconciliation') ->where('source_id', $resolutionKey)->first(); $payload = $event === null ? null : json_decode((string) $event->payload_json, true); if ($event === null || !is_array($payload) || (int) ($payload['expected_version'] ?? -1) !== $expectedVersion) { throw new \RuntimeException( 'attention 已处理但审计事件核对失败;请执行 ' . 'inspect-resolution --resolution-key=<原 UUID> 并保留现场' ); } return [ 'action' => 'resolve', 'pool_id' => $poolId, 'resolution_key' => $resolutionKey, 'before_version' => $expectedVersion, 'after_version' => (int) ($result['version'] ?? 0), 'state' => (string) ($result['state'] ?? ''), 'available_bytes' => (int) ($result['available_bytes'] ?? 0), 'overage_bytes' => (int) ($result['overage_bytes'] ?? 0), 'attention_resolved_event_id' => (int) $event->id, ]; } private static function inspectResolution(string $resolutionKey): array { $event = CloudTrafficLedgerEvent::where( 'event_key', self::resolutionEventKey($resolutionKey) )->first(); if ($event === null) { return [ 'action' => 'inspect-resolution', 'resolution_key' => $resolutionKey, 'committed' => false, ]; } if ((string) $event->event_type !== 'attention_resolved' || (string) $event->source_type !== 'admin_reconciliation' || !hash_equals((string) $event->source_id, $resolutionKey)) { throw new \RuntimeException( 'resolution-key 的不可变账本身份冲突,请保留现场' ); } $payload = json_decode((string) $event->payload_json, true); $expectedVersion = is_array($payload) ? ($payload['expected_version'] ?? null) : null; if (!is_int($expectedVersion) || $expectedVersion < 1) { throw new \RuntimeException( 'resolution-key 的审计载荷无效,请保留现场' ); } $pool = CloudTrafficPool::find((int) $event->pool_id); return [ 'action' => 'inspect-resolution', 'resolution_key' => $resolutionKey, 'committed' => true, 'pool_id' => (int) $event->pool_id, 'expected_version' => $expectedVersion, 'resolved_at' => (int) $event->created_at, 'current_pool_exists' => $pool !== null, 'current_pool_state' => $pool === null ? null : (string) $pool->state, 'current_pool_version' => $pool === null ? null : (int) $pool->version, ]; } /** @return array */ private static function options(array $arguments, array $allowed): array { $result = []; foreach ($arguments as $argument) { if (!is_string($argument) || $argument === '') { throw new \InvalidArgumentException('命令参数无效'); } if ($argument === '--apply') { $name = 'apply'; $value = true; } elseif (preg_match('/^--([a-z][a-z-]*)=(.*)$/D', $argument, $match) === 1) { $name = $match[1]; $value = $match[2]; } else { throw new \InvalidArgumentException( '存在未知或格式无效的命令参数' ); } if (!in_array($name, $allowed, true) || array_key_exists($name, $result)) { throw new \InvalidArgumentException( '存在未知或重复的命令参数:' . $name ); } $result[$name] = $value; } if (count($result) !== count($allowed)) { throw new \InvalidArgumentException('命令参数不完整'); } return $result; } private static function positiveInteger(mixed $value, string $name): int { if (!is_string($value) || preg_match('/^[1-9][0-9]{0,18}$/D', $value) !== 1) { throw new \InvalidArgumentException($name . ' 必须是正整数'); } $integer = (int) $value; if ($integer < 1 || (string) $integer !== $value) { throw new \InvalidArgumentException($name . ' 超出有效范围'); } return $integer; } private static function resolutionKey(mixed $value): string { if (!is_string($value) || preg_match( '/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/D', $value ) !== 1) { throw new \InvalidArgumentException( 'resolution-key 必须是小写规范 UUIDv4' ); } return $value; } private static function confirmation( int $poolId, int $expectedVersion, string $resolutionKey ): string { return self::CONFIRM_PREFIX . ':' . $poolId . ':' . $expectedVersion . ':' . $resolutionKey; } private static function resolutionEventKey(string $resolutionKey): string { return 'attention-resolution:' . $resolutionKey; } private static function output(array $value): void { echo json_encode($value, JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE) . PHP_EOL; } }