inliver233
diff --git a/‎backend/app/api/public/docs_page.py‎
Lines changed: 4 additions & 2 deletions b/‎backend/app/api/public/docs_page.py‎
Lines changed: 4 additions & 2 deletions
diff --git a/‎backend/app/api/public/random.py‎
Lines changed: 38 additions & 9 deletions b/‎backend/app/api/public/random.py‎
Lines changed: 38 additions & 9 deletions
@@ -49,6 +49,7 @@ def u(path: str) -> str:
 <head>
   <meta charset="utf-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <meta name="color-scheme" content="light" />
   <title>Random Mage Docs</title>
   <style>
     :root {{
@@ -70,6 +71,7 @@ def u(path: str) -> str:
     }}
 
     * {{ box-sizing: border-box; }}
+    html, body {{ height: 100%; }}
     body {{
       margin: 0;
       font-family: var(--sans);
@@ -336,8 +338,8 @@ def u(path: str) -> str:
           <tr>
             <td><code>included_tags</code></td>
             <td>
-              必须包含的标签（AND）。可重复传参：<code>included_tags=a&amp;included_tags=b</code>。<br/>
-              也支持用 <code>|</code> 分隔：<code>included_tags=a|b</code> 等价于同时包含 a 与 b。<br/>
+              必须包含的标签：参数之间是 <strong>AND</strong>，单个参数内用 <code>|</code> 表示 <strong>OR</strong>。<br/>
+              例：<code>included_tags=girl|boy&amp;included_tags=white|black</code> 表示 (girl OR boy) AND (white OR black)。<br/>
               示例：<a href="{examples["tag_loli"]}">{examples["tag_loli"]}</a>
             </td>
           </tr>
 
@@ -30,6 +30,8 @@
 router = APIRouter()
 
 _MAX_TAG_FILTERS = 50
+_MAX_TAG_OR_TERMS = 20
+_MAX_TAG_TOTAL_TERMS = 200
 
 
 def _as_nonneg_int(value: Any) -> int:
@@ -241,22 +243,49 @@ async def random_image(
         if not min_explicit and min_width_i == 0 and min_height_i == 0 and min_pixels_i == 0:
             min_pixels_i = 1_000_000 if is_mobile else 2_000_000
 
-    def _parse_tags(values: list[str] | None) -> list[str]:
+    def _parse_tag_filters(values: list[str] | None) -> list[str]:
+        """
+        Tag filters support "AND of groups" where each query param is one group.
+
+        Examples:
+        - included_tags=girl&included_tags=boy  -> girl AND boy
+        - included_tags=girl|boy               -> girl OR boy
+        - included_tags=girl|boy&included_tags=white|black -> (girl OR boy) AND (white OR black)
+        """
         out: list[str] = []
         seen: set[str] = set()
         for raw in values or []:
-            for part in str(raw).split("|"):
-                name = part.strip()
-                if not name or name in seen:
-                    continue
-                seen.add(name)
-                out.append(name)
+            expr = str(raw or "").strip()
+            if not expr or expr in seen:
+                continue
+            seen.add(expr)
+            out.append(expr)
         return out
 
-    included = _parse_tags(included_tags)
-    excluded = _parse_tags(excluded_tags)
+    included = _parse_tag_filters(included_tags)
+    excluded = _parse_tag_filters(excluded_tags)
+
+    def _validate_tag_filters(values: list[str]) -> None:
+        total_terms = 0
+        for expr in values:
+            parts: list[str] = []
+            seen_terms: set[str] = set()
+            for part in str(expr).split("|"):
+                term = part.strip()
+                if not term or term in seen_terms:
+                    continue
+                seen_terms.add(term)
+                parts.append(term)
+            if len(parts) > _MAX_TAG_OR_TERMS:
+                raise ApiError(code=ErrorCode.BAD_REQUEST, message="Too many tag terms in a group", status_code=400)
+            total_terms += len(parts)
+        if total_terms > _MAX_TAG_TOTAL_TERMS:
+            raise ApiError(code=ErrorCode.BAD_REQUEST, message="Too many tag terms", status_code=400)
+
     if len(included) > _MAX_TAG_FILTERS or len(excluded) > _MAX_TAG_FILTERS:
         raise ApiError(code=ErrorCode.BAD_REQUEST, message="Too many tag filters", status_code=400)
+    _validate_tag_filters(included)
+    _validate_tag_filters(excluded)
     if user_id is not None and int(user_id) <= 0:
         raise ApiError(code=ErrorCode.BAD_REQUEST, message="Unsupported user_id", status_code=400)
     if illust_id is not None and int(illust_id) <= 0: