feat: new chain

app/Support/AgentScope.php

@@ -8,6 +8,32 @@ use Illuminate\Database\Eloquent\Builder;
 
 final class AgentScope
 {
+    /**
+     * Parse admin 「代理用户」filter.
+     * null = 全部; 0 = 官方渠道 (channels.user_id = 0); >0 = that agent.
+     */
+    public static function parseAgentUserIdFilter(mixed $raw): ?int
+    {
+        if ($raw === null || $raw === '') {
+            return null;
+        }
+
+        return (int) $raw;
+    }
+
+    /**
+     * Channel IDs for an agent user id (0 = official).
+     *
+     * @return list<string>
+     */
+    public static function channelIdsForUserId(int $userId): array
+    {
+        return Channel::query()
+            ->where('user_id', $userId)
+            ->pluck('channel_id')
+            ->all();
+    }
+
     /**
      * Channel IDs owned by the agent (empty list means no access).
      *
@@ -19,10 +45,7 @@ final class AgentScope
             return [];
         }
 
-        return Channel::query()
-            ->where('user_id', $agent->id)
-            ->pluck('channel_id')
-            ->all();
+        return self::channelIdsForUserId((int) $agent->id);
     }
 
     /**
@@ -43,17 +66,17 @@ final class AgentScope
         return $query->whereIn($channelColumn, $ids);
     }
 
+    /**
+     * Admin agent filter on queries that join/select devices.channel_id.
+     * null = no filter; 0 = official; >0 = agent id.
+     */
     public static function applyAgentUserFilter(Builder $devicesQuery, ?int $agentUserId): Builder
     {
-        if ($agentUserId === null || $agentUserId <= 0) {
+        if ($agentUserId === null) {
             return $devicesQuery;
         }
 
-        $ids = Channel::query()
-            ->where('user_id', $agentUserId)
-            ->pluck('channel_id')
-            ->all();
-
+        $ids = self::channelIdsForUserId($agentUserId);
         if ($ids === []) {
             return $devicesQuery->whereRaw('1 = 0');
         }
@@ -78,17 +101,17 @@ final class AgentScope
         return $query->whereIn($column, $ids);
     }
 
+    /**
+     * Admin agent filter on bare channel_id column.
+     * null = no filter; 0 = official; >0 = agent id.
+     */
     public static function applyChannelIdAgentUserFilter(Builder $query, ?int $agentUserId, string $column = 'channel_id'): Builder
     {
-        if ($agentUserId === null || $agentUserId <= 0) {
+        if ($agentUserId === null) {
             return $query;
         }
 
-        $ids = Channel::query()
-            ->where('user_id', $agentUserId)
-            ->pluck('channel_id')
-            ->all();
-
+        $ids = self::channelIdsForUserId($agentUserId);
         if ($ids === []) {
             return $query->whereRaw('1 = 0');
         }