From 324424741fe3530e5897436ee61191651126204e Mon Sep 17 00:00:00 2001
From: shark <mandoreshark@gmail.com>
Date: Sat, 9 May 2026 18:35:07 +0800
Subject: [PATCH 1/4] docs(admin): design remote entity select

---
 docs/designs/remote-entity-select.md | 597 +++++++++++++++++++++++++++
 1 file changed, 597 insertions(+)
 create mode 100644 docs/designs/remote-entity-select.md

diff --git a/docs/designs/remote-entity-select.md b/docs/designs/remote-entity-select.md
new file mode 100644
index 0000000..2f374da
--- /dev/null
+++ b/docs/designs/remote-entity-select.md
@@ -0,0 +1,597 @@
+<!--
+SPDX-FileCopyrightText: 2026 ArcheBase
+
+SPDX-License-Identifier: MulanPSL-2.0
+-->
+
+# Remote Entity Select Design
+
+**Scope:** Synapse Admin select controls and Keystone list APIs
+
+## 1. Purpose
+
+This document defines a staged development plan for replacing large static select
+option lists in Synapse Admin with remote searchable selects.
+
+The immediate problem is that many Admin pages load only the first paginated
+resource page, usually `limit=50`, and then build select options from that
+partial client-side list. Once resource tables contain more rows than the first
+page, users cannot find valid organizations, orders, scenes, SOPs, devices,
+collectors, or workstations in select controls.
+
+The proposed solution is to use a reusable remote select pattern similar to the
+robot device ID and collector operator ID selectors in the data production
+statistics page:
+
+- Search options by keyword on the server.
+- Page option results with `limit` and `offset`.
+- Load more options without requiring full-table preloading.
+- Preserve selected option labels even when the selected item is not in the
+  current result page.
+- Keep existing API pagination limits and avoid increasing all list calls to
+  very large limits.
+
+## 2. Background
+
+### 2.1 Current frontend behavior
+
+Synapse Admin currently uses two main select patterns:
+
+- `BaseSelect` with fully materialized `options`.
+- Page-local custom searchable selects in
+  `src/views/admin/statistics/DataProductionStatistics.vue` for robot device ID
+  and collector operator ID.
+
+Many pages call `fetchList()` without explicit large pagination. The generic
+`useEntityCrud()` composable defaults to `limit=50`, and API modules also
+default to `limit=50`. This means option lists frequently represent only the
+first page of a resource.
+
+The batch management page is the most visible example. It builds filters and
+form options from:
+
+- `organizations`
+- `orders`
+- `stations`
+- `robots`
+- `data_collectors`
+- `sops`
+- `scenes`
+- `subscenes`
+
+These resources can all exceed one page in realistic deployments.
+
+### 2.2 Current backend behavior
+
+Keystone list APIs already expose standardized pagination:
+
+```json
+{
+  "items": [],
+  "total": 0,
+  "limit": 50,
+  "offset": 0,
+  "hasNext": false,
+  "hasPrev": false
+}
+```
+
+`ParsePagination()` caps `limit` at `100`. This is acceptable and should stay in
+place. The missing piece is consistent keyword search across list endpoints.
+
+Search support is currently uneven:
+
+| Resource | Endpoint | Current useful filters | Current keyword search |
+|---|---|---|---|
+| Organization | `GET /organizations` | `factory_id` | No |
+| Scene | `GET /scenes` | `factory_id` | No |
+| Subscene | `GET /subscenes` | `scene_id` | No |
+| Skill | `GET /skills` | none | No |
+| SOP | `GET /sops` | none | No |
+| Robot type | `GET /robot_types` | none | No |
+| Robot | `GET /robots` | `factory_id`, `status`, `robot_type_id`, `connected` | Yes: `keyword`, `q`, `search`, `device_id` |
+| Data collector | `GET /data_collectors` | `organization_id`, `status` | Yes: `keyword`, `q`, `search`, `operator_id` |
+| Inspector | `GET /inspectors` | `organization_id`, `certification_level`, `status` | No |
+| Station | `GET /stations` | `factory_id`, `organization_id`, `robot_type_id`, `status` | No |
+| Order | `GET /orders` | `organization_id`, `scene_id`, `status`, `priority`, `ids` | No |
+| Batch | `GET /batches` | several list filters | Not the main select source |
+
+## 3. Goals
+
+- Provide one reusable remote select implementation for Admin pages.
+- Support single-select and multi-select use cases.
+- Support server-side keyword search and paginated option loading.
+- Preserve selected labels across pagination, refresh, and route state restore.
+- Keep static enum selects as simple `BaseSelect` controls.
+- Make option fetching explicit and resource-specific rather than relying on
+  page-wide preloading.
+- Improve large-data correctness without weakening backend pagination limits.
+
+## 4. Non-goals
+
+- Do not replace every select in one large refactor.
+- Do not build a generic backend `/options` endpoint in the first phase.
+- Do not remove `BaseSelect`; it remains appropriate for enum and small static
+  option sets.
+- Do not change table pagination behavior.
+- Do not change creation/update payload contracts for existing resources.
+
+## 5. UX Contract
+
+### 5.1 Single select
+
+Single-select controls should support:
+
+- Placeholder text.
+- Clear selection when the field is optional.
+- Keyword search with debounce.
+- Loading state while searching.
+- Empty state when no option matches.
+- "Load more" when `hasNext` is true.
+- Selected label display even if the selected option is not in the current
+  option page.
+
+### 5.2 Multi select
+
+Multi-select controls should support:
+
+- Search and page loading.
+- Checkbox-style options.
+- Selected chips.
+- Remove a selected item from its chip.
+- Clear all selected items.
+- Collapsed chip preview when many values are selected.
+
+### 5.3 Keyboard and focus behavior
+
+Remote selects replace native `<select>` behavior, so the component must provide
+basic keyboard and focus support:
+
+- `Enter` selects the active option.
+- `Escape` closes the dropdown without changing the current value.
+- `ArrowDown` and `ArrowUp` move the active option.
+- `Tab` leaves the control and closes the dropdown.
+- Clicking outside closes the dropdown.
+- Closing the dropdown returns focus to the search/input trigger.
+- The trigger and dropdown should expose meaningful ARIA labels, active option
+  state, selected state, and disabled state.
+
+### 5.4 Dependent selects
+
+Some select controls depend on another selected value:
+
+| Parent | Child | Required behavior |
+|---|---|---|
+| Factory | Organization | Clear child when parent changes unless selected child still belongs to parent |
+| Factory | Scene | Query scenes with `factory_id` |
+| Scene | Subscene | Query subscenes with `scene_id`; disable until scene is selected |
+| SOP slug | SOP version | Search/group by slug; version list is limited to selected slug |
+| Organization | Order | Query orders with `organization_id` |
+| Organization | Station | Query stations with `organization_id` |
+
+Dependent selects must clear stale values before submitting forms.
+
+## 6. Frontend Design
+
+### 6.1 New component
+
+Add a reusable component:
+
+```text
+synapse-worktree1/src/components/form/RemoteSelect.vue
+```
+
+Recommended props:
+
+| Prop | Type | Notes |
+|---|---|---|
+| `modelValue` | `String \| Number \| Array` | Bound value |
+| `multiple` | `Boolean` | Enables chip and checkbox behavior |
+| `label` | `String` | Optional field label |
+| `placeholder` | `String` | Search/input placeholder |
+| `disabled` | `Boolean` | Disable input and dropdown |
+| `required` | `Boolean` | Display required marker only |
+| `error` | `String` | Validation error |
+| `hint` | `String` | Helper text |
+| `options` | `Array<{ value, label, meta? }>` | Current loaded options |
+| `selectedOptions` | `Array<{ value, label, meta? }>` | Hydrated selected options; source of truth for displayed selected labels and chips |
+| `loading` | `Boolean` | Shows loading state |
+| `hasMore` | `Boolean` | Shows load-more row |
+| `search` | `String` | Controlled search text |
+| `clearable` | `Boolean` | Allow clearing optional fields |
+| `maxVisibleChips` | `Number` | Multi-select chip preview limit |
+
+Recommended emits:
+
+| Emit | Payload | Notes |
+|---|---|---|
+| `update:modelValue` | selected value(s) | Standard Vue model update |
+| `update:search` | search text | Enables debounced remote search |
+| `open` | none | Parent/composable can load first page |
+| `load-more` | none | Parent/composable loads next page |
+| `clear` | none | Optional convenience event |
+
+The component should focus only on rendering and interaction. It should not know
+about Keystone resource names or API modules.
+
+Rendering contract:
+
+- The component displays selected labels from `selectedOptions`, not by searching
+  only inside the current `options` page.
+- The dropdown list renders `displayOptions`, which is the de-duplicated merge of
+  `selectedOptions` and the current remote `options` page.
+- For multi-select controls, chips are rendered from `selectedOptions`.
+- If `selectedOptions` is empty for a non-empty value, the component may display
+  the raw value temporarily, but the composable must attempt hydration.
+
+### 6.2 New composable
+
+Add a resource-aware composable:
+
+```text
+synapse-worktree1/src/composables/useRemoteOptions.js
+```
+
+Recommended API:
+
+```js
+const {
+  options,
+  selectedOptions,
+  displayOptions,
+  loading,
+  hasMore,
+  search,
+  open,
+  reload,
+  loadMore,
+  setSelectedFromValues,
+  clear
+} = useRemoteOptions({
+  fetchPage,
+  fetchByValues,
+  mapOption,
+  pageSize: 50,
+  searchParam: 'keyword',
+  baseParams: () => ({ organization_id: selectedOrg.value || undefined })
+})
+```
+
+Responsibilities:
+
+- Own `limit`, `offset`, `hasMore`, and request sequence handling.
+- Debounce search input.
+- Merge loaded options with selected options without duplicates.
+- Keep selected labels after pagination changes.
+- Expose `displayOptions` as `mergeOptions(selectedOptions, options)`.
+- Hydrate selected values through `fetchByValues` or the resource-specific
+  fallback rules in section 6.4.
+- Reset options when `baseParams()` changes.
+- Ignore stale responses from earlier searches.
+
+### 6.3 Resource adapters
+
+Add small adapter helpers instead of duplicating mapping logic in each page:
+
+```text
+synapse-worktree1/src/composables/remoteOptionAdapters.js
+```
+
+Example adapters:
+
+| Adapter | Value | Label |
+|---|---|---|
+| `organizationOption` | `id` | `name || slug || id` |
+| `sceneOption` | `id` | `name || id` |
+| `subsceneOption` | `id` | `name || id` |
+| `orderOption` | `id` | `name || id`, optionally include scene name |
+| `stationOption` | `id` | station name + robot serial + collector operator ID |
+| `robotOption` | `device_id` or `id` depending on caller | device ID + robot type |
+| `collectorOption` | `operator_id` or `id` depending on caller | operator ID + name |
+| `sopOption` | `id` | slug + version |
+| `robotTypeOption` | `id` | name + model |
+| `inspectorOption` | `id` | inspector ID + name |
+
+Value choice must match the downstream filter or form payload. Adapters must be
+separate when the same resource is used with different value semantics:
+
+- `robotDeviceOption`: value is `device_id`, used by filters that submit
+  `device_id`.
+- `robotIdOption`: value is numeric `id`, used by forms that submit `robot_id`.
+- `collectorOperatorOption`: value is `operator_id`, used by filters that submit
+  `collector_operator_id`.
+- `collectorIdOption`: value is numeric `id`, used by forms that submit
+  `data_collector_id`.
+
+### 6.4 Selected label resolution
+
+Remote selects need a way to display labels for selected values that are not in
+the current page.
+
+MVP rule: selected label hydration is required for every remote select.
+
+Hydration order:
+
+1. If selected value exists in `options`, use that option.
+2. If selected option was restored from page state, use the persisted label.
+3. If the value is a numeric ID, call `fetchByValues(values)`.
+4. Fallback to `{ value, label: value }`.
+
+`fetchByValues(values)` has this required MVP behavior:
+
+- If the endpoint supports an `ids` filter, use one list request.
+- Otherwise, call `GET /:id` for each selected ID. This fallback is acceptable
+  because selected value counts are small in the initial rollout.
+- For multi-select controls, cap fallback hydration at 50 selected values and
+  display raw values for any overflow until a batch lookup is added.
+
+For resources selected by non-ID unique strings, such as robot `device_id` or
+collector `operator_id`, hydration uses keyword search with the selected value
+and then keeps only exact matches on the unique field. Persisted `{ value,
+label }` remains the fallback if the exact search returns no row.
+
+This MVP does not require every list API to support `ids`. A generic selected
+option lookup endpoint can be added later if per-ID hydration becomes too slow.
+
+### 6.5 Batch page value mapping
+
+`BatchList.vue` is the first page where value semantics must be fixed before
+implementation. The following mapping is the contract for Phase 3:
+
+| Area | Control | Value | Label | Query or payload field | Dependencies |
+|---|---|---|---|---|---|
+| Filter row | Organization | `organizations.id` | `organization.name || slug` | `organization_id` | none |
+| Filter row | Order | `orders.id` | `order.name`, optionally scene name | `order_id` | optional `organization_id` |
+| Filter row | Scene | `scenes.id` | `scene.name` | `scene_id` | optional factory context |
+| Filter row | Device ID | `robots.device_id` | `device_id`, optionally robot type | `device_id` | optional `robot_type_id` |
+| Filter row | Collector operator ID | `data_collectors.operator_id` | `operator_id + name` | `collector_operator_id` | optional `organization_id` |
+| Create/edit form | Order | `orders.id` | `order.name`, optionally scene name | `order_id` | optional `organization_id` |
+| Create/edit form | Workstation | `workstations.id` | station name + robot serial + collector operator ID | `workstation_id` | selected order organization when available |
+| Create/edit form | SOP slug | `sops.slug` | `slug` | local grouping only | none |
+| Create/edit form | SOP version | `sops.version` | `version` | resolves selected `sop_id` from slug + version | selected SOP slug |
+| Create/edit form | Scene | `scenes.id` | `scene.name` | local subscene filter only | selected order scene when order is chosen |
+| Create/edit form | Subscene | `subscenes.id` | `subscene.name` | `task_groups[].subscene_id` | selected scene |
+
+When an order is selected in create/edit forms, the form should derive the scene
+from that order and clear any task group subscene that does not belong to the
+derived scene.
+
+## 7. Backend API Design
+
+### 7.1 Standard query parameters
+
+All large resource list endpoints used by remote selects should accept:
+
+| Query | Meaning |
+|---|---|
+| `limit` | Page size, still capped by `ParsePagination()` |
+| `offset` | Page offset |
+| `keyword` | Canonical search term |
+| `q` | Alias of `keyword` |
+| `search` | Alias of `keyword` |
+
+Resource-specific aliases can remain for compatibility:
+
+- Robots: `device_id`
+- Data collectors: `operator_id`
+
+New code should use `keyword` unless there is a strong reason to use a
+resource-specific alias.
+
+### 7.2 Search fields by resource
+
+| Resource | Search fields |
+|---|---|
+| Organization | `name`, `slug`, `description` |
+| Factory | `name`, `slug`, `location` |
+| Scene | `name`, `description` |
+| Subscene | `name`, `description` |
+| Skill | `slug`, `description`, `version` |
+| SOP | `slug`, `description`, `version` |
+| Robot type | `name`, `model`, `manufacturer`, `end_effector` |
+| Robot | `device_id`, `asset_id` |
+| Data collector | `name`, `operator_id`, `email` |
+| Inspector | `name`, `inspector_id`, `email` |
+| Station | `name`, `robot_serial`, `collector_operator_id`, `robot_name`, `collector_name` |
+| Order | `name`, joined `scene.name`, joined `organization.name` |
+
+### 7.3 Backend implementation notes
+
+- Reuse `firstNonEmptyQuery(c, "keyword", "q", "search", "...")`.
+- Keep the count query and data query filters identical.
+- Always use parameterized `LIKE ?`; do not concatenate user input into SQL.
+- Escape user `%` and `_` if exact literal matching becomes important. For the
+  first phase, current `LIKE "%keyword%"` behavior is acceptable.
+- For keyword searches, order exact matches first, prefix matches second,
+  substring matches third, and then use `id DESC` as the final stable tie-breaker.
+  For non-search list requests, keep the existing `ORDER BY id DESC`.
+- Ensure joined search fields do not change tenant filtering semantics.
+- Regenerate Swagger docs after API query parameters are added.
+
+Recommended SQL ordering shape:
+
+```sql
+ORDER BY
+  CASE
+    WHEN primary_field = ? THEN 0
+    WHEN primary_field LIKE ? THEN 1
+    WHEN secondary_field = ? THEN 2
+    WHEN secondary_field LIKE ? THEN 3
+    ELSE 4
+  END,
+  id DESC
+```
+
+The concrete fields differ by resource. The important contract is that an exact
+or prefix match should not be buried below unrelated newer rows.
+
+## 8. Rollout Plan
+
+### Phase 1: Shared frontend primitive
+
+Deliver:
+
+- `RemoteSelect.vue`
+- `useRemoteOptions.js`
+- `remoteOptionAdapters.js`
+- Replace the custom robot and collector search-select logic in
+  `DataProductionStatistics.vue` with the shared primitive.
+
+Acceptance criteria:
+
+- Existing statistics page behavior is preserved.
+- Robot and collector selects still support search, load more, selected chips,
+  and restored labels.
+- No other Admin pages are changed in this phase.
+
+### Phase 2: Backend search consistency
+
+Deliver keyword search for endpoints that are needed by batch and common Admin
+filters:
+
+- `GET /factories`
+- `GET /organizations`
+- `GET /orders`
+- `GET /scenes`
+- `GET /subscenes`
+- `GET /skills`
+- `GET /sops`
+- `GET /robot_types`
+- `GET /stations`
+- `GET /inspectors`
+
+Acceptance criteria:
+
+- Each endpoint supports `keyword`, `q`, and `search`.
+- Existing filters still compose with keyword search.
+- Pagination metadata remains correct.
+- Keyword searches rank exact and prefix matches ahead of substring matches.
+- Tests cover at least one positive and one filtered-empty search case per
+  changed handler group where practical.
+
+### Phase 3: Batch page replacement
+
+Replace large-resource selects in:
+
+```text
+synapse-worktree1/src/views/admin/batches/BatchList.vue
+```
+
+Priority controls:
+
+- Filter row: organization, order, scene, device ID, collector operator ID.
+- Create/edit forms: order, workstation, SOP slug/version, scene, subscene.
+
+Acceptance criteria:
+
+- With more than 100 rows in each resource table, users can find rows outside
+  the first page.
+- Controls follow the value, label, payload, and dependency contract in section
+  6.5.
+- Changing a parent select clears stale dependent child values.
+- Batch creation still submits numeric IDs where required by Keystone.
+- Filter controls still submit the same query parameters as before.
+
+### Phase 4: Common Admin pages
+
+Replace high-risk large option selects in:
+
+- `admin/collectors`
+- `admin/inspectors`
+- `admin/orders`
+- `admin/robots`
+- `admin/sops`
+- `admin/workstations`
+- `admin/tasks`, if it uses large resource filters
+
+Acceptance criteria:
+
+- Static enum selects remain `BaseSelect`.
+- Large entity selects use `RemoteSelect`.
+- Pages do not preload full resource lists just to build select options.
+
+### Phase 5: Cleanup
+
+Deliver:
+
+- Remove duplicated custom search-select code from pages.
+- Remove obsolete page-wide option preload calls.
+- Document resource adapter conventions in component comments or `src/README.md`
+  if needed.
+
+## 9. Testing Strategy
+
+### 9.1 Backend
+
+Recommended Go tests:
+
+- List handlers still return default pagination.
+- `keyword` narrows results.
+- Existing filters compose with `keyword`.
+- Invalid numeric filters still return `400`.
+- `total`, `hasNext`, and `hasPrev` reflect the filtered result set.
+- Exact and prefix matches sort before substring-only matches.
+
+Recommended commands:
+
+```bash
+cd keystone-worktree1
+go test ./internal/api/handlers/... -run 'List|Search' -v
+go test ./internal/api/handlers/... -v
+```
+
+### 9.2 Frontend
+
+Synapse has no configured test runner. Manual verification should cover:
+
+- Search returns matching options after debounce.
+- Load-more appends options without duplicates.
+- Selected label persists after closing and reopening the dropdown.
+- Selected label displays correctly when the selected row is outside page 1.
+- Multi-select chips can be added and removed.
+- Dependent selects reset stale child values.
+- Forms submit the same payload shape as before.
+- Filter URLs/API params remain unchanged.
+- `Enter`, `Escape`, `ArrowUp`, `ArrowDown`, `Tab`, and click-outside behavior
+  match section 5.3.
+
+Recommended manual data setup:
+
+- At least 120 organizations, orders, scenes, robots, collectors, and stations.
+- At least 80 SOP rows with multiple versions.
+- At least 3 subscenes per test scene.
+
+## 10. Risks and Mitigations
+
+| Risk | Impact | Mitigation |
+|---|---|---|
+| Replacing all selects at once causes regressions | High | Roll out by page and preserve `BaseSelect` for static enums |
+| Selected label cannot be resolved after restore | Medium | Persist `{ value, label }`, pass `selectedOptions`, and hydrate through `fetchByValues` |
+| Backend search is inconsistent across endpoints | Medium | Standardize on `keyword/q/search` and document search fields |
+| Dependent selects submit stale child IDs | High | Clear child values when parent filter changes |
+| Remote select makes too many requests | Medium | Debounce search and ignore stale responses |
+| Large joins slow down search | Medium | Keep search fields indexed where practical; avoid unnecessary joins |
+
+## 11. Open Questions
+
+- Should all resource list APIs eventually support an `ids` filter for faster
+  selected-label hydration, or is per-ID fallback sufficient?
+- Should station labels include status, or only stable identity fields such as
+  station name, robot serial, and collector operator ID?
+- Should SOP remote selection expose slug/version as two coordinated controls,
+  or a single `slug@version` selector for forms?
+
+## 12. Recommended First Implementation Slice
+
+The recommended first slice is:
+
+1. Implement `RemoteSelect.vue` and `useRemoteOptions.js`.
+2. Migrate robot and collector selects in data production statistics to prove
+   compatibility with the existing behavior.
+3. Add keyword search to `organizations`, `orders`, `scenes`, `subscenes`,
+   `skills`, `sops`, and `stations`.
+4. Replace the batch page filter row with remote selects.
+5. Replace the batch create/edit form selects.
+
+This slice directly targets the current dropdown completeness problem while
+keeping the change set reviewable.

From 97fd22b28333279738c69d8f59dd3540dd8ea635 Mon Sep 17 00:00:00 2001
From: shark <mandoreshark@gmail.com>
Date: Sat, 9 May 2026 18:58:14 +0800
Subject: [PATCH 2/4] feat(api): add keyword search for admin selects

---
 internal/api/handlers/common.go         | 36 +++++++++++++++++++++++++
 internal/api/handlers/data_collector.go |  6 +++--
 internal/api/handlers/factory.go        | 21 +++++++++++----
 internal/api/handlers/inspector.go      | 13 ++++++---
 internal/api/handlers/order.go          | 26 +++++++++++++-----
 internal/api/handlers/organization.go   | 29 ++++++++++----------
 internal/api/handlers/robot.go          |  6 +++--
 internal/api/handlers/robot_type.go     | 21 +++++++++++----
 internal/api/handlers/scene.go          | 15 ++++++++---
 internal/api/handlers/skill.go          | 21 +++++++++++----
 internal/api/handlers/sop.go            | 21 +++++++++++----
 internal/api/handlers/station.go        | 11 +++++++-
 internal/api/handlers/subscene.go       | 35 ++++++++++++++----------
 13 files changed, 194 insertions(+), 67 deletions(-)

diff --git a/internal/api/handlers/common.go b/internal/api/handlers/common.go
index 8ba05d9..d981de3 100644
--- a/internal/api/handlers/common.go
+++ b/internal/api/handlers/common.go
@@ -7,6 +7,7 @@ package handlers
 import (
 	"database/sql"
 	"encoding/json"
+	"fmt"
 	"net/http"
 	"strconv"
 	"strings"
@@ -90,6 +91,41 @@ func firstNonEmptyQuery(c *gin.Context, keys ...string) string {
 	return ""
 }
 
+func appendKeywordSearch(whereClause string, args []any, keyword string, fields ...string) (string, []any) {
+	if keyword == "" || len(fields) == 0 {
+		return whereClause, args
+	}
+
+	conditions := make([]string, 0, len(fields))
+	likeKeyword := "%" + keyword + "%"
+	for _, field := range fields {
+		conditions = append(conditions, field+" LIKE ?")
+		args = append(args, likeKeyword)
+	}
+	return whereClause + " AND (" + strings.Join(conditions, " OR ") + ")", args
+}
+
+func keywordOrderBy(keyword string, fallback string, fields ...string) (string, []any) {
+	if keyword == "" || len(fields) == 0 {
+		return "ORDER BY " + fallback, nil
+	}
+
+	clauses := make([]string, 0, len(fields)*2)
+	args := make([]any, 0, len(fields)*2)
+	prefixKeyword := keyword + "%"
+	rank := 0
+	for _, field := range fields {
+		clauses = append(clauses, fmt.Sprintf("WHEN %s = ? THEN %d", field, rank))
+		args = append(args, keyword)
+		rank++
+		clauses = append(clauses, fmt.Sprintf("WHEN %s LIKE ? THEN %d", field, rank))
+		args = append(args, prefixKeyword)
+		rank++
+	}
+
+	return fmt.Sprintf("ORDER BY CASE %s ELSE %d END, %s", strings.Join(clauses, " "), rank, fallback), args
+}
+
 // isValidSlug checks non-empty slug, length <= maxSlugLength (in runes), and allows Unicode letters/digits plus hyphen.
 func isValidSlug(s string) bool {
 	if s == "" {
diff --git a/internal/api/handlers/data_collector.go b/internal/api/handlers/data_collector.go
index f30a29f..55760f3 100644
--- a/internal/api/handlers/data_collector.go
+++ b/internal/api/handlers/data_collector.go
@@ -212,6 +212,7 @@ func (h *DataCollectorHandler) ListDataCollectors(c *gin.Context) {
 		return
 	}
 
+	orderClause, orderArgs := keywordOrderBy(keyword, "dc.id DESC", "dc.operator_id", "dc.name", "dc.email")
 	query := `
 		SELECT 
 			dc.id,
@@ -228,11 +229,12 @@ func (h *DataCollectorHandler) ListDataCollectors(c *gin.Context) {
 		FROM data_collectors dc
 		INNER JOIN organizations o ON o.id = dc.organization_id AND o.deleted_at IS NULL
 		` + whereClause + `
-		ORDER BY dc.id DESC
+		` + orderClause + `
 		LIMIT ? OFFSET ?
 	`
 
-	queryArgs := append(args, pagination.Limit, pagination.Offset)
+	queryArgs := append(args, orderArgs...)
+	queryArgs = append(queryArgs, pagination.Limit, pagination.Offset)
 
 	var dbRows []dataCollectorRow
 	if err := h.db.Select(&dbRows, query, queryArgs...); err != nil {
diff --git a/internal/api/handlers/factory.go b/internal/api/handlers/factory.go
index aeca99c..e5397e7 100644
--- a/internal/api/handlers/factory.go
+++ b/internal/api/handlers/factory.go
@@ -143,6 +143,9 @@ func (h *FactoryHandler) allocateFactorySlug() (string, error) {
 // @Tags         factories
 // @Accept       json
 // @Produce      json
+// @Param        keyword query     string  false  "Search by name, slug, or location"
+// @Param        q       query     string  false  "Alias of keyword"
+// @Param        search  query     string  false  "Alias of keyword"
 // @Param        limit  query     int     false  "Max results (default 50, max 100)"
 // @Param        offset query     int     false  "Pagination offset (default 0)"
 // @Success      200    {object}  ListResponse
@@ -156,14 +159,20 @@ func (h *FactoryHandler) ListFactories(c *gin.Context) {
 		return
 	}
 
-	countQuery := "SELECT COUNT(*) FROM factories WHERE deleted_at IS NULL"
+	keyword := firstNonEmptyQuery(c, "keyword", "q", "search")
+	whereClause := "WHERE deleted_at IS NULL"
+	args := []any{}
+	whereClause, args = appendKeywordSearch(whereClause, args, keyword, "name", "slug", "location")
+
+	countQuery := "SELECT COUNT(*) FROM factories " + whereClause
 	var total int
-	if err := h.db.Get(&total, countQuery); err != nil {
+	if err := h.db.Get(&total, countQuery, args...); err != nil {
 		logger.Printf("[FACTORY] Failed to count factories: %v", err)
 		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to list factories"})
 		return
 	}
 
+	orderClause, orderArgs := keywordOrderBy(keyword, "id DESC", "name", "slug", "location")
 	query := `
 		SELECT 
 			id,
@@ -177,15 +186,17 @@ func (h *FactoryHandler) ListFactories(c *gin.Context) {
 			created_at,
 			updated_at
 		FROM factories
-		WHERE deleted_at IS NULL
-		ORDER BY id DESC
+		` + whereClause + `
+		` + orderClause + `
 		LIMIT ? OFFSET ?
 	`
+	queryArgs := append(args, orderArgs...)
+	queryArgs = append(queryArgs, pagination.Limit, pagination.Offset)
 
 	factories := []FactoryResponse{}
 
 	var dbRows []factoryRow
-	if err := h.db.Select(&dbRows, query, pagination.Limit, pagination.Offset); err != nil {
+	if err := h.db.Select(&dbRows, query, queryArgs...); err != nil {
 		logger.Printf("[FACTORY] Failed to query factories: %v", err)
 		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to list factories"})
 		return
diff --git a/internal/api/handlers/inspector.go b/internal/api/handlers/inspector.go
index 9ef3b33..a386ef8 100644
--- a/internal/api/handlers/inspector.go
+++ b/internal/api/handlers/inspector.go
@@ -120,6 +120,9 @@ type inspectorRow struct {
 // @Param        organization_id query string false "Filter by organization ID"
 // @Param        certification_level query string false "Filter by certification level (level_1, level_2, senior)"
 // @Param        status          query string false "Filter by status (active, inactive)"
+// @Param        keyword         query string false "Search by name, inspector ID, or email"
+// @Param        q               query string false "Alias of keyword"
+// @Param        search          query string false "Alias of keyword"
 // @Param        limit           query int    false "Max results (default 50, max 100)"
 // @Param        offset          query int    false "Pagination offset (default 0)"
 // @Success      200 {object} InspectorListResponse
@@ -136,9 +139,10 @@ func (h *InspectorHandler) ListInspectors(c *gin.Context) {
 	orgID := c.Query("organization_id")
 	certLevel := strings.TrimSpace(c.Query("certification_level"))
 	status := c.Query("status")
+	keyword := firstNonEmptyQuery(c, "keyword", "q", "search")
 
 	whereClause := "WHERE deleted_at IS NULL"
-	args := []interface{}{}
+	args := []any{}
 
 	if orgID != "" {
 		parsedOrgID, err := strconv.ParseInt(orgID, 10, 64)
@@ -164,6 +168,7 @@ func (h *InspectorHandler) ListInspectors(c *gin.Context) {
 		whereClause += " AND status = ?"
 		args = append(args, status)
 	}
+	whereClause, args = appendKeywordSearch(whereClause, args, keyword, "name", "inspector_id", "email")
 
 	countQuery := "SELECT COUNT(*) FROM inspectors " + whereClause
 	var total int
@@ -173,6 +178,7 @@ func (h *InspectorHandler) ListInspectors(c *gin.Context) {
 		return
 	}
 
+	orderClause, orderArgs := keywordOrderBy(keyword, "id DESC", "name", "inspector_id", "email")
 	query := `
 		SELECT 
 			id,
@@ -187,11 +193,12 @@ func (h *InspectorHandler) ListInspectors(c *gin.Context) {
 			updated_at
 		FROM inspectors
 		` + whereClause + `
-		ORDER BY id DESC
+		` + orderClause + `
 		LIMIT ? OFFSET ?
 	`
 
-	queryArgs := append(args, pagination.Limit, pagination.Offset)
+	queryArgs := append(args, orderArgs...)
+	queryArgs = append(queryArgs, pagination.Limit, pagination.Offset)
 
 	var dbRows []inspectorRow
 	if err := h.db.Select(&dbRows, query, queryArgs...); err != nil {
diff --git a/internal/api/handlers/order.go b/internal/api/handlers/order.go
index f69c219..817f821 100644
--- a/internal/api/handlers/order.go
+++ b/internal/api/handlers/order.go
@@ -184,6 +184,7 @@ func (h *OrderHandler) ListOrders(c *gin.Context) {
 	sceneIDStr := strings.TrimSpace(c.Query("scene_id"))
 	priority := strings.TrimSpace(c.Query("priority"))
 	status := strings.TrimSpace(c.Query("status"))
+	keyword := firstNonEmptyQuery(c, "keyword", "q", "search")
 	idsStr := strings.TrimSpace(c.Query("ids")) // comma-separated numeric IDs for batch lookup
 	if status != "" {
 		if _, ok := validOrderStatuses[status]; !ok {
@@ -215,7 +216,13 @@ func (h *OrderHandler) ListOrders(c *gin.Context) {
 		}
 	}
 
-	countQuery := "SELECT COUNT(*) FROM orders WHERE deleted_at IS NULL"
+	countQuery := `
+		SELECT COUNT(*)
+		FROM orders o
+		LEFT JOIN organizations org ON org.id = o.organization_id AND org.deleted_at IS NULL
+		LEFT JOIN scenes s ON s.id = o.scene_id AND s.deleted_at IS NULL
+		WHERE o.deleted_at IS NULL
+	`
 	countArgs := []any{}
 	if orgIDStr != "" {
 		parsedOrgID, err := strconv.ParseInt(orgIDStr, 10, 64)
@@ -223,7 +230,7 @@ func (h *OrderHandler) ListOrders(c *gin.Context) {
 			c.JSON(http.StatusBadRequest, gin.H{"error": "invalid organization_id format"})
 			return
 		}
-		countQuery += " AND organization_id = ?"
+		countQuery += " AND o.organization_id = ?"
 		countArgs = append(countArgs, parsedOrgID)
 	}
 	if sceneIDStr != "" {
@@ -232,19 +239,19 @@ func (h *OrderHandler) ListOrders(c *gin.Context) {
 			c.JSON(http.StatusBadRequest, gin.H{"error": "invalid scene_id format"})
 			return
 		}
-		countQuery += " AND scene_id = ?"
+		countQuery += " AND o.scene_id = ?"
 		countArgs = append(countArgs, parsedSceneID)
 	}
 	if status != "" {
-		countQuery += " AND status = ?"
+		countQuery += " AND o.status = ?"
 		countArgs = append(countArgs, status)
 	}
 	if priority != "" {
-		countQuery += " AND priority = ?"
+		countQuery += " AND o.priority = ?"
 		countArgs = append(countArgs, priority)
 	}
 	if len(filterIDs) > 0 {
-		inQ, inArgs, err := sqlx.In("AND id IN (?)", filterIDs)
+		inQ, inArgs, err := sqlx.In("AND o.id IN (?)", filterIDs)
 		if err != nil {
 			logger.Printf("[ORDER] Failed to build ids IN clause for count: %v", err)
 			c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to list orders"})
@@ -253,6 +260,8 @@ func (h *OrderHandler) ListOrders(c *gin.Context) {
 		countQuery += " " + inQ
 		countArgs = append(countArgs, inArgs...)
 	}
+	orderSearchFields := []string{"o.name", "s.name", "org.name"}
+	countQuery, countArgs = appendKeywordSearch(countQuery, countArgs, keyword, orderSearchFields...)
 	var total int
 	if err := h.db.Get(&total, h.db.Rebind(countQuery), countArgs...); err != nil {
 		logger.Printf("[ORDER] Failed to count orders: %v", err)
@@ -310,10 +319,13 @@ func (h *OrderHandler) ListOrders(c *gin.Context) {
 		query += " " + inQ + "\n"
 		args = append(args, inArgs...)
 	}
+	query, args = appendKeywordSearch(query, args, keyword, orderSearchFields...)
+	orderClause, orderArgs := keywordOrderBy(keyword, "o.id DESC", orderSearchFields...)
 	query += `
-		ORDER BY o.id DESC
+		` + orderClause + `
 		LIMIT ? OFFSET ?
 	`
+	args = append(args, orderArgs...)
 	args = append(args, pagination.Limit, pagination.Offset)
 	query = h.db.Rebind(query)
 
diff --git a/internal/api/handlers/organization.go b/internal/api/handlers/organization.go
index f061d52..bd1105d 100644
--- a/internal/api/handlers/organization.go
+++ b/internal/api/handlers/organization.go
@@ -164,6 +164,9 @@ type organizationRow struct {
 // @Accept       json
 // @Produce      json
 // @Param        factory_id query     string false "Filter by factory ID"
+// @Param        keyword    query     string false "Search by name, slug, or description"
+// @Param        q          query     string false "Alias of keyword"
+// @Param        search     query     string false "Alias of keyword"
 // @Param        limit  query     int  false  "Max results (default 50, max 100)"
 // @Param        offset query     int  false  "Pagination offset (default 0)"
 // @Success      200 {object} OrganizationListResponse
@@ -189,20 +192,24 @@ func (h *OrganizationHandler) ListOrganizations(c *gin.Context) {
 		}
 	}
 
-	countQuery := "SELECT COUNT(*) FROM organizations WHERE deleted_at IS NULL"
-	countArgs := []any{}
+	keyword := firstNonEmptyQuery(c, "keyword", "q", "search")
+	whereClause := "WHERE o.deleted_at IS NULL"
+	args := []any{}
 	if hasFactoryFilter {
-		countQuery += " AND factory_id = ?"
-		countArgs = append(countArgs, factoryID)
+		whereClause += " AND o.factory_id = ?"
+		args = append(args, factoryID)
 	}
+	whereClause, args = appendKeywordSearch(whereClause, args, keyword, "o.name", "o.slug", "o.description")
 
+	countQuery := "SELECT COUNT(*) FROM organizations o " + whereClause
 	var total int
-	if err := h.db.Get(&total, countQuery, countArgs...); err != nil {
+	if err := h.db.Get(&total, countQuery, args...); err != nil {
 		logger.Printf("[ORGANIZATION] Failed to count organizations: %v", err)
 		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to list organizations"})
 		return
 	}
 
+	orderClause, orderArgs := keywordOrderBy(keyword, "o.id DESC", "o.name", "o.slug", "o.description")
 	query := `
 		SELECT 
 			o.id,
@@ -214,17 +221,11 @@ func (h *OrganizationHandler) ListOrganizations(c *gin.Context) {
 			o.created_at,
 			o.updated_at
 		FROM organizations o
-		WHERE o.deleted_at IS NULL
-	`
-	args := []any{}
-	if hasFactoryFilter {
-		query += " AND o.factory_id = ?\n"
-		args = append(args, factoryID)
-	}
-	query += `
-		ORDER BY o.id DESC
+		` + whereClause + `
+		` + orderClause + `
 		LIMIT ? OFFSET ?
 	`
+	args = append(args, orderArgs...)
 	args = append(args, pagination.Limit, pagination.Offset)
 
 	var dbRows []organizationRow
diff --git a/internal/api/handlers/robot.go b/internal/api/handlers/robot.go
index b22e39e..ab1e6d6 100644
--- a/internal/api/handlers/robot.go
+++ b/internal/api/handlers/robot.go
@@ -267,6 +267,7 @@ func (h *RobotHandler) ListRobots(c *gin.Context) {
 		return
 	}
 
+	orderClause, orderArgs := keywordOrderBy(keyword, "r.id DESC", "r.device_id", "r.asset_id")
 	query := `
 		SELECT 
 			r.id,
@@ -280,11 +281,12 @@ func (h *RobotHandler) ListRobots(c *gin.Context) {
 			r.updated_at
 		FROM robots r
 		` + whereClause + `
-		ORDER BY r.id DESC
+		` + orderClause + `
 		LIMIT ? OFFSET ?
 	`
 
-	queryArgs := append(args, pagination.Limit, pagination.Offset)
+	queryArgs := append(args, orderArgs...)
+	queryArgs = append(queryArgs, pagination.Limit, pagination.Offset)
 
 	var dbRows []robotRow
 	if err := h.db.Select(&dbRows, query, queryArgs...); err != nil {
diff --git a/internal/api/handlers/robot_type.go b/internal/api/handlers/robot_type.go
index 1de6733..e8ad2e1 100644
--- a/internal/api/handlers/robot_type.go
+++ b/internal/api/handlers/robot_type.go
@@ -249,6 +249,9 @@ func (h *RobotTypeHandler) CreateRobotType(c *gin.Context) {
 // @Tags         robot_types
 // @Accept       json
 // @Produce      json
+// @Param        keyword query     string false "Search by name, model, manufacturer, or end effector"
+// @Param        q       query     string false "Alias of keyword"
+// @Param        search  query     string false "Alias of keyword"
 // @Param        limit  query     int  false  "Max results (default 50, max 100)"
 // @Param        offset query     int  false  "Pagination offset (default 0)"
 // @Success      200 {object} RobotTypeListResponse
@@ -262,24 +265,32 @@ func (h *RobotTypeHandler) ListRobotTypes(c *gin.Context) {
 		return
 	}
 
-	countQuery := "SELECT COUNT(*) FROM robot_types WHERE deleted_at IS NULL"
+	keyword := firstNonEmptyQuery(c, "keyword", "q", "search")
+	whereClause := "WHERE deleted_at IS NULL"
+	args := []any{}
+	whereClause, args = appendKeywordSearch(whereClause, args, keyword, "name", "model", "manufacturer", "end_effector")
+
+	countQuery := "SELECT COUNT(*) FROM robot_types " + whereClause
 	var total int
-	if err := h.db.Get(&total, countQuery); err != nil {
+	if err := h.db.Get(&total, countQuery, args...); err != nil {
 		logger.Printf("[ROBOT] Failed to count robot types: %v", err)
 		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to list robot types"})
 		return
 	}
 
+	orderClause, orderArgs := keywordOrderBy(keyword, "id DESC", "name", "model", "manufacturer", "end_effector")
 	query := `
 		SELECT ` + robotTypeSelectColumns + `
 		FROM robot_types
-		WHERE deleted_at IS NULL
-		ORDER BY id DESC
+		` + whereClause + `
+		` + orderClause + `
 		LIMIT ? OFFSET ?
 	`
+	queryArgs := append(args, orderArgs...)
+	queryArgs = append(queryArgs, pagination.Limit, pagination.Offset)
 
 	var dbRows []robotTypeRow
-	if err := h.db.Select(&dbRows, query, pagination.Limit, pagination.Offset); err != nil {
+	if err := h.db.Select(&dbRows, query, queryArgs...); err != nil {
 		logger.Printf("[ROBOT] Failed to query robot types: %v", err)
 		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to list robot types"})
 		return
diff --git a/internal/api/handlers/scene.go b/internal/api/handlers/scene.go
index f9921d7..f167b3c 100644
--- a/internal/api/handlers/scene.go
+++ b/internal/api/handlers/scene.go
@@ -102,6 +102,9 @@ type sceneRow struct {
 // @Accept       json
 // @Produce      json
 // @Param        factory_id query string false "Filter by factory ID"
+// @Param        keyword    query string false "Search by name or description"
+// @Param        q          query string false "Alias of keyword"
+// @Param        search     query string false "Alias of keyword"
 // @Param        limit      query int    false "Max results (default 50, max 100)"
 // @Param        offset     query int    false "Pagination offset (default 0)"
 // @Success      200 {object} SceneListResponse
@@ -116,9 +119,10 @@ func (h *SceneHandler) ListScenes(c *gin.Context) {
 	}
 
 	factoryID := c.Query("factory_id")
+	keyword := firstNonEmptyQuery(c, "keyword", "q", "search")
 
 	whereClause := "WHERE s.deleted_at IS NULL"
-	args := []interface{}{}
+	args := []any{}
 
 	if factoryID != "" {
 		parsedFactoryID, err := strconv.ParseInt(factoryID, 10, 64)
@@ -126,9 +130,10 @@ func (h *SceneHandler) ListScenes(c *gin.Context) {
 			c.JSON(http.StatusBadRequest, gin.H{"error": "invalid factory_id format"})
 			return
 		}
-		whereClause += " AND factory_id = ?"
+		whereClause += " AND s.factory_id = ?"
 		args = append(args, parsedFactoryID)
 	}
+	whereClause, args = appendKeywordSearch(whereClause, args, keyword, "s.name", "s.description")
 
 	countQuery := "SELECT COUNT(*) FROM scenes s " + whereClause
 	var total int
@@ -138,6 +143,7 @@ func (h *SceneHandler) ListScenes(c *gin.Context) {
 		return
 	}
 
+	orderClause, orderArgs := keywordOrderBy(keyword, "s.id DESC", "s.name", "s.description")
 	query := `
 		SELECT 
 			s.id,
@@ -150,11 +156,12 @@ func (h *SceneHandler) ListScenes(c *gin.Context) {
 			(SELECT COUNT(*) FROM subscenes sub WHERE sub.scene_id = s.id AND sub.deleted_at IS NULL) as subscene_count
 		FROM scenes s
 		` + whereClause + `
-		ORDER BY id DESC
+		` + orderClause + `
 		LIMIT ? OFFSET ?
 	`
 
-	queryArgs := append(args, pagination.Limit, pagination.Offset)
+	queryArgs := append(args, orderArgs...)
+	queryArgs = append(queryArgs, pagination.Limit, pagination.Offset)
 
 	var dbRows []sceneRow
 	if err := h.db.Select(&dbRows, query, queryArgs...); err != nil {
diff --git a/internal/api/handlers/skill.go b/internal/api/handlers/skill.go
index e3675f3..7d618b7 100644
--- a/internal/api/handlers/skill.go
+++ b/internal/api/handlers/skill.go
@@ -120,6 +120,9 @@ type skillRow struct {
 // @Tags         skills
 // @Accept       json
 // @Produce      json
+// @Param        keyword query string false "Search by slug, description, or version"
+// @Param        q       query string false "Alias of keyword"
+// @Param        search  query string false "Alias of keyword"
 // @Param        limit  query int false "Max results (default 50, max 100)"
 // @Param        offset query int false "Pagination offset (default 0)"
 // @Success      200 {object} SkillListResponse
@@ -133,14 +136,20 @@ func (h *SkillHandler) ListSkills(c *gin.Context) {
 		return
 	}
 
-	countQuery := "SELECT COUNT(*) FROM skills WHERE deleted_at IS NULL"
+	keyword := firstNonEmptyQuery(c, "keyword", "q", "search")
+	whereClause := "WHERE deleted_at IS NULL"
+	args := []any{}
+	whereClause, args = appendKeywordSearch(whereClause, args, keyword, "slug", "description", "version")
+
+	countQuery := "SELECT COUNT(*) FROM skills " + whereClause
 	var total int
-	if err := h.db.Get(&total, countQuery); err != nil {
+	if err := h.db.Get(&total, countQuery, args...); err != nil {
 		logger.Printf("[SKILL] Failed to count skills: %v", err)
 		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to list skills"})
 		return
 	}
 
+	orderClause, orderArgs := keywordOrderBy(keyword, "id DESC", "slug", "description", "version")
 	query := `
 		SELECT 
 			id,
@@ -151,13 +160,15 @@ func (h *SkillHandler) ListSkills(c *gin.Context) {
 			created_at,
 			updated_at
 		FROM skills
-		WHERE deleted_at IS NULL
-		ORDER BY id DESC
+		` + whereClause + `
+		` + orderClause + `
 		LIMIT ? OFFSET ?
 	`
+	queryArgs := append(args, orderArgs...)
+	queryArgs = append(queryArgs, pagination.Limit, pagination.Offset)
 
 	var dbRows []skillRow
-	if err := h.db.Select(&dbRows, query, pagination.Limit, pagination.Offset); err != nil {
+	if err := h.db.Select(&dbRows, query, queryArgs...); err != nil {
 		logger.Printf("[SKILL] Failed to query skills: %v", err)
 		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to list skills"})
 		return
diff --git a/internal/api/handlers/sop.go b/internal/api/handlers/sop.go
index 1698109..e188aa7 100644
--- a/internal/api/handlers/sop.go
+++ b/internal/api/handlers/sop.go
@@ -102,6 +102,9 @@ type sopRow struct {
 // @Tags         sops
 // @Accept       json
 // @Produce      json
+// @Param        keyword query string false "Search by slug, description, or version"
+// @Param        q       query string false "Alias of keyword"
+// @Param        search  query string false "Alias of keyword"
 // @Param        limit  query int false "Max results (default 50, max 100)"
 // @Param        offset query int false "Pagination offset (default 0)"
 // @Success      200 {object} SOPListResponse
@@ -115,14 +118,20 @@ func (h *SOPHandler) ListSOPs(c *gin.Context) {
 		return
 	}
 
-	countQuery := "SELECT COUNT(*) FROM sops WHERE deleted_at IS NULL"
+	keyword := firstNonEmptyQuery(c, "keyword", "q", "search")
+	whereClause := "WHERE deleted_at IS NULL"
+	args := []any{}
+	whereClause, args = appendKeywordSearch(whereClause, args, keyword, "slug", "description", "version")
+
+	countQuery := "SELECT COUNT(*) FROM sops " + whereClause
 	var total int
-	if err := h.db.Get(&total, countQuery); err != nil {
+	if err := h.db.Get(&total, countQuery, args...); err != nil {
 		logger.Printf("[SOP] Failed to count SOPs: %v", err)
 		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to list SOPs"})
 		return
 	}
 
+	orderClause, orderArgs := keywordOrderBy(keyword, "id DESC", "slug", "description", "version")
 	query := `
 		SELECT 
 			id,
@@ -133,13 +142,15 @@ func (h *SOPHandler) ListSOPs(c *gin.Context) {
 			created_at,
 			updated_at
 		FROM sops
-		WHERE deleted_at IS NULL
-		ORDER BY id DESC
+		` + whereClause + `
+		` + orderClause + `
 		LIMIT ? OFFSET ?
 	`
+	queryArgs := append(args, orderArgs...)
+	queryArgs = append(queryArgs, pagination.Limit, pagination.Offset)
 
 	var dbRows []sopRow
-	if err := h.db.Select(&dbRows, query, pagination.Limit, pagination.Offset); err != nil {
+	if err := h.db.Select(&dbRows, query, queryArgs...); err != nil {
 		logger.Printf("[SOP] Failed to query SOPs: %v", err)
 		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to list SOPs"})
 		return
diff --git a/internal/api/handlers/station.go b/internal/api/handlers/station.go
index 93a268b..a0a1468 100644
--- a/internal/api/handlers/station.go
+++ b/internal/api/handlers/station.go
@@ -476,6 +476,9 @@ func stationResponseFromRow(s stationListRow) StationResponse {
 // @Param        organization_id query int false "Filter by organization ID"
 // @Param        robot_type_id   query int false "Filter by robot type ID"
 // @Param        status          query string false "Filter by status (active, inactive, break, offline)"
+// @Param        keyword         query string false "Search by name, robot serial, robot name, collector operator ID, or collector name"
+// @Param        q               query string false "Alias of keyword"
+// @Param        search          query string false "Alias of keyword"
 // @Param        limit  query int false "Max results (default 50, max 100)"
 // @Param        offset query int false "Pagination offset (default 0)"
 // @Success      200 {object} ListResponse
@@ -493,6 +496,7 @@ func (h *StationHandler) ListStations(c *gin.Context) {
 	orgIDStr := strings.TrimSpace(c.Query("organization_id"))
 	robotTypeIDStr := strings.TrimSpace(c.Query("robot_type_id"))
 	statusStr := strings.TrimSpace(c.Query("status"))
+	keyword := firstNonEmptyQuery(c, "keyword", "q", "search")
 	var factoryID int64
 	var orgID int64
 	var robotTypeID int64
@@ -558,6 +562,8 @@ func (h *StationHandler) ListStations(c *gin.Context) {
 		countQuery += " AND ws.status = ?"
 		countArgs = append(countArgs, statusStr)
 	}
+	stationSearchFields := []string{"ws.name", "ws.robot_serial", "ws.collector_operator_id", "ws.robot_name", "ws.collector_name"}
+	countQuery, countArgs = appendKeywordSearch(countQuery, countArgs, keyword, stationSearchFields...)
 	var total int
 	if err := h.db.Get(&total, countQuery, countArgs...); err != nil {
 		logger.Printf("[STATION] Failed to count stations: %v", err)
@@ -598,10 +604,13 @@ func (h *StationHandler) ListStations(c *gin.Context) {
 		query += " AND ws.status = ?\n"
 		args = append(args, statusStr)
 	}
+	query, args = appendKeywordSearch(query, args, keyword, stationSearchFields...)
+	orderClause, orderArgs := keywordOrderBy(keyword, "ws.id DESC", stationSearchFields...)
 	query += `
-		ORDER BY ws.id DESC
+		` + orderClause + `
 		LIMIT ? OFFSET ?
 	`
+	args = append(args, orderArgs...)
 	args = append(args, pagination.Limit, pagination.Offset)
 
 	err = h.db.Select(&stations, query, args...)
diff --git a/internal/api/handlers/subscene.go b/internal/api/handlers/subscene.go
index 41358bc..281cbf6 100644
--- a/internal/api/handlers/subscene.go
+++ b/internal/api/handlers/subscene.go
@@ -110,6 +110,9 @@ func (h *SubsceneHandler) getSceneInitialLayoutTemplate(sceneID int64) (sql.Null
 // @Accept       json
 // @Produce      json
 // @Param        scene_id query string false "Filter by scene ID"
+// @Param        keyword  query string false "Search by name or description"
+// @Param        q        query string false "Alias of keyword"
+// @Param        search   query string false "Alias of keyword"
 // @Param        limit    query int    false "Max results (default 50, max 100)"
 // @Param        offset   query int    false "Pagination offset (default 0)"
 // @Success      200 {object} SubsceneListResponse
@@ -124,9 +127,10 @@ func (h *SubsceneHandler) ListSubscenes(c *gin.Context) {
 	}
 
 	sceneID := c.Query("scene_id")
+	keyword := firstNonEmptyQuery(c, "keyword", "q", "search")
 
-	whereClause := "WHERE deleted_at IS NULL"
-	args := []interface{}{}
+	whereClause := "WHERE ss.deleted_at IS NULL"
+	args := []any{}
 
 	if sceneID != "" {
 		parsedSceneID, err := strconv.ParseInt(sceneID, 10, 64)
@@ -134,11 +138,12 @@ func (h *SubsceneHandler) ListSubscenes(c *gin.Context) {
 			c.JSON(http.StatusBadRequest, gin.H{"error": "invalid scene_id format"})
 			return
 		}
-		whereClause += " AND scene_id = ?"
+		whereClause += " AND ss.scene_id = ?"
 		args = append(args, parsedSceneID)
 	}
+	whereClause, args = appendKeywordSearch(whereClause, args, keyword, "ss.name", "ss.description")
 
-	countQuery := "SELECT COUNT(*) FROM subscenes " + whereClause
+	countQuery := "SELECT COUNT(*) FROM subscenes ss " + whereClause
 	var total int
 	if err := h.db.Get(&total, countQuery, args...); err != nil {
 		logger.Printf("[SUBSCENE] Failed to count subscenes: %v", err)
@@ -146,22 +151,24 @@ func (h *SubsceneHandler) ListSubscenes(c *gin.Context) {
 		return
 	}
 
+	orderClause, orderArgs := keywordOrderBy(keyword, "ss.id DESC", "ss.name", "ss.description")
 	query := `
 		SELECT 
-			id,
-			scene_id,
-			name,
-			description,
-			initial_scene_layout,
-			created_at,
-			updated_at
-		FROM subscenes
+			ss.id,
+			ss.scene_id,
+			ss.name,
+			ss.description,
+			ss.initial_scene_layout,
+			ss.created_at,
+			ss.updated_at
+		FROM subscenes ss
 		` + whereClause + `
-		ORDER BY id DESC
+		` + orderClause + `
 		LIMIT ? OFFSET ?
 	`
 
-	queryArgs := append(args, pagination.Limit, pagination.Offset)
+	queryArgs := append(args, orderArgs...)
+	queryArgs = append(queryArgs, pagination.Limit, pagination.Offset)
 
 	var dbRows []subsceneRow
 	if err := h.db.Select(&dbRows, query, queryArgs...); err != nil {

From 5482dac67d5fb4fb48e18f8132469a4c706d5f23 Mon Sep 17 00:00:00 2001
From: shark <mandoreshark@gmail.com>
Date: Tue, 12 May 2026 02:07:42 +0800
Subject: [PATCH 3/4] fix(api): complete paginated lists and dashboard data

---
 .../paginated-list-completeness-fix.md        |  87 ++
 internal/api/handlers/batch.go                |   4 +-
 internal/api/handlers/batch_test.go           |  41 +
 internal/api/handlers/common.go               | 115 ++-
 internal/api/handlers/common_test.go          |  69 ++
 internal/api/handlers/data_collector.go       |  48 +-
 .../handlers/data_production_statistics.go    | 155 +--
 .../data_production_statistics_test.go        |  38 +-
 internal/api/handlers/factory.go              |   9 +
 internal/api/handlers/inspector.go            |  77 +-
 internal/api/handlers/order.go                | 138 +--
 internal/api/handlers/order_test.go           | 159 +++
 internal/api/handlers/organization.go         |  30 +-
 internal/api/handlers/production_dashboard.go | 940 ++++++++++++++++++
 .../api/handlers/production_dashboard_test.go | 138 +++
 internal/api/handlers/robot.go                | 319 ++++--
 internal/api/handlers/robot_test.go           | 338 +++++++
 internal/api/handlers/robot_type.go           |   9 +
 internal/api/handlers/scene.go                |  26 +-
 internal/api/handlers/skill.go                |   8 +
 internal/api/handlers/sop.go                  |  21 +-
 internal/api/handlers/station.go              | 146 ++-
 internal/api/handlers/station_test.go         | 156 +++
 internal/api/handlers/subscene.go             |  36 +-
 internal/server/server.go                     | 153 +--
 25 files changed, 2736 insertions(+), 524 deletions(-)
 create mode 100644 docs/designs/paginated-list-completeness-fix.md
 create mode 100644 internal/api/handlers/common_test.go
 create mode 100644 internal/api/handlers/order_test.go
 create mode 100644 internal/api/handlers/production_dashboard.go
 create mode 100644 internal/api/handlers/production_dashboard_test.go
 create mode 100644 internal/api/handlers/robot_test.go
 create mode 100644 internal/api/handlers/station_test.go

diff --git a/docs/designs/paginated-list-completeness-fix.md b/docs/designs/paginated-list-completeness-fix.md
new file mode 100644
index 0000000..7854d6d
--- /dev/null
+++ b/docs/designs/paginated-list-completeness-fix.md
@@ -0,0 +1,87 @@
+<!--
+SPDX-FileCopyrightText: 2026 ArcheBase
+
+SPDX-License-Identifier: MulanPSL-2.0
+-->
+
+# Paginated List Completeness Fix
+
+**Scope:** Synapse Admin/operator pages and Keystone paginated list APIs
+
+## 1. Problem
+
+Some Synapse pages assume a large `limit` returns all rows, or fetch only the
+first paginated page and then perform client-side grouping. Keystone
+`ParsePagination()` caps `limit` at `100`, so any request such as `limit=500` or
+`limit=2000` still returns at most 100 rows.
+
+The visible failure is that `SOP 管理` can omit existing SOPs such as
+`kitchen-move-water-bottle` when that SOP is not in the first `/sops` response
+page.
+
+## 2. Root Cause
+
+- `SOP 管理` and `技能管理` fetch one backend page, then group rows by `slug` on
+  the client and paginate the grouped result.
+- Several pages preload related entities with fixed large limits for label
+  maps, filter options, or dashboard summaries. These calls silently truncate at
+  the backend max limit.
+- `批次管理` has two post-action refresh paths that call the generic
+  `fetchList()` without current pagination/filter parameters.
+
+## 3. Fix Strategy
+
+Keep standard table pagination server-side. Only use full pagination loops where
+the page needs a complete local set:
+
+- Client-side grouped management pages:
+  - `src/views/admin/sops/SopList.vue`
+  - `src/views/admin/skills/SkillList.vue`
+- Local label/lookup caches:
+  - `src/views/admin/tasks/TaskList.vue`
+  - `src/views/admin/tasks/TaskDetail.vue`
+  - `src/views/admin/batches/BatchDetail.vue`
+  - `src/views/admin/orders/OrderDetail.vue`
+  - `src/features/production/useDashboardData.js`
+  - `src/views/admin/statistics/DataProductionStatistics.vue`
+- Form option preloads that previously used the backend max page size:
+  - `src/views/admin/collectors/CollectorForm.vue`
+  - `src/views/admin/inspectors/InspectorForm.vue`
+  - `src/views/admin/orders/OrderForm.vue`
+  - `src/views/admin/orders/OrderList.vue`
+  - `src/views/admin/organizations/OrganizationList.vue`
+  - `src/views/admin/organizations/OrganizationDetail.vue`
+- Operator batch selection:
+  - `src/views/RobotControl.vue`
+
+Use a reusable `fetchAllList()` helper in `useEntityCrud()` for entity CRUD
+pages, and a small `fetchAllPages()` utility for API modules that expose
+`list(params)`.
+
+## 4. Implementation Checklist
+
+- Add `fetchAllList(params)` to `useEntityCrud()`:
+  - request pages with `limit=100`;
+  - advance by the response `limit`;
+  - stop on `hasNext=false` or an empty page;
+  - update `items`, `totalCount`, `hasNext`, and `hasPrev`.
+- Add `fetchAllPages(listFn, params)` for direct API modules.
+- Change SOP and skill management to load all rows before client-side grouping.
+- Replace fixed large-limit preloads with `fetchAllList()` or
+  `fetchAllPages()`.
+- Change batch cancel/recall refreshes to `fetchBatchesPage()` so current
+  filters and pagination are preserved.
+- Replace fixed `limit=100/200/500/1000/2000` preload calls with full-page
+  loops where the UI needs complete local option or label maps.
+
+## 5. Non-goals
+
+- Do not raise Keystone's global `maxLimit`; the backend cap protects list APIs.
+- Do not rewrite normal list tables to client-side pagination.
+- Do not change API response shapes.
+
+## 6. Validation
+
+- Build Synapse with `npm run build`.
+- Manually verify that SOP/skill list counts are based on all pages.
+- Manually verify that filtered batch pages stay filtered after cancel/recall.
diff --git a/internal/api/handlers/batch.go b/internal/api/handlers/batch.go
index 016bb4d..e9bb637 100644
--- a/internal/api/handlers/batch.go
+++ b/internal/api/handlers/batch.go
@@ -323,7 +323,7 @@ func (h *BatchHandler) ListBatches(c *gin.Context) {
 	countQuery := fmt.Sprintf(`
 		SELECT COUNT(*)
 		FROM batches b
-		LEFT JOIN workstations ws ON ws.id = b.workstation_id AND ws.deleted_at IS NULL
+		LEFT JOIN workstations ws ON ws.id = b.workstation_id
 		LEFT JOIN orders o ON o.id = b.order_id AND o.deleted_at IS NULL
 		WHERE %s
 	`, whereClause)
@@ -355,7 +355,7 @@ func (h *BatchHandler) ListBatches(c *gin.Context) {
 			b.created_at,
 			b.updated_at
 		FROM batches b
-		LEFT JOIN workstations ws ON ws.id = b.workstation_id AND ws.deleted_at IS NULL
+		LEFT JOIN workstations ws ON ws.id = b.workstation_id
 		LEFT JOIN organizations org ON org.id = b.organization_id AND org.deleted_at IS NULL
 		LEFT JOIN orders o ON o.id = b.order_id AND o.deleted_at IS NULL
 		LEFT JOIN (
diff --git a/internal/api/handlers/batch_test.go b/internal/api/handlers/batch_test.go
index 8a3981b..ee1af9b 100644
--- a/internal/api/handlers/batch_test.go
+++ b/internal/api/handlers/batch_test.go
@@ -241,6 +241,45 @@ func TestBatchHandlerListBatches_DefaultPaginationAndFilter(t *testing.T) {
 	}
 }
 
+func TestBatchHandlerListBatches_DeviceIDMatchesSoftDeletedWorkstationSerial(t *testing.T) {
+	db := newTestBatchHandlerDB(t)
+	defer db.Close()
+	seedBatchListFixtures(t, db)
+
+	deletedAt := time.Now().UTC()
+	if _, err := db.Exec(
+		`INSERT INTO workstations (id, factory_id, organization_id, robot_serial, status, deleted_at) VALUES (20, 30, 60, 'wt1_robot_060', 'inactive', ?)`,
+		deletedAt,
+	); err != nil {
+		t.Fatalf("seed soft-deleted workstation failed: %v", err)
+	}
+	if _, err := db.Exec(
+		`INSERT INTO workstations (id, factory_id, organization_id, robot_serial, status) VALUES (21, 30, 60, 'wt1_robot_120', 'active')`,
+	); err != nil {
+		t.Fatalf("seed active workstation failed: %v", err)
+	}
+
+	r := newTestBatchRouter(t, db)
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/batches?device_id=wt1_robot_060", nil)
+	w := httptest.NewRecorder()
+	r.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status=%d want=%d body=%s", w.Code, http.StatusOK, w.Body.String())
+	}
+
+	var resp ListBatchesResponse
+	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("unmarshal response: %v body=%s", err, w.Body.String())
+	}
+	if resp.Total != 1 || len(resp.Items) != 1 {
+		t.Fatalf("unexpected filtered response: %#v", resp)
+	}
+	if resp.Items[0].BatchID != "B1" {
+		t.Fatalf("unexpected item: %#v", resp.Items[0])
+	}
+}
+
 func TestBatchHandlerCreateBatch_DuplicateTaskGroups(t *testing.T) {
 	db := newTestBatchHandlerDB(t)
 	defer db.Close()
@@ -507,6 +546,8 @@ func newTestBatchHandlerDB(t *testing.T) *sqlx.DB {
 			id INTEGER PRIMARY KEY,
 			factory_id INTEGER NOT NULL,
 			organization_id INTEGER NOT NULL DEFAULT 0,
+			robot_serial TEXT,
+			collector_operator_id TEXT,
 			status TEXT,
 			deleted_at TIMESTAMP NULL
 		)`,
diff --git a/internal/api/handlers/common.go b/internal/api/handlers/common.go
index d981de3..7f6540a 100644
--- a/internal/api/handlers/common.go
+++ b/internal/api/handlers/common.go
@@ -18,9 +18,13 @@ import (
 )
 
 const (
-	defaultLimit  = 50
-	maxLimit      = 100
-	maxSlugLength = 100
+	defaultLimit                         = 50
+	maxLimit                             = 100
+	maxSlugLength                        = 100
+	maxMultiValueFilterItems             = 100
+	maxMultiValueFilterRawLength         = 8192
+	maxMultiValueFilterStringItemLength  = 255
+	maxMultiValueFilterIntegerItemLength = 20
 )
 
 const invalidSlugUserMessage = "slug must be at most 100 characters and contain only letters, digits, and hyphens"
@@ -105,6 +109,111 @@ func appendKeywordSearch(whereClause string, args []any, keyword string, fields
 	return whereClause + " AND (" + strings.Join(conditions, " OR ") + ")", args
 }
 
+func parsePositiveInt64List(raw string, fieldName string) ([]int64, error) {
+	items, err := splitBoundedMultiValueItems([]string{raw}, fieldName, maxMultiValueFilterIntegerItemLength)
+	if err != nil {
+		return nil, err
+	}
+	if len(items) == 0 {
+		return nil, nil
+	}
+
+	seen := make(map[int64]struct{})
+	values := []int64{}
+	for _, item := range items {
+		parsed, err := strconv.ParseInt(item, 10, 64)
+		if err != nil || parsed <= 0 {
+			return nil, fmt.Errorf("invalid %s format", fieldName)
+		}
+		if _, ok := seen[parsed]; ok {
+			continue
+		}
+		seen[parsed] = struct{}{}
+		values = append(values, parsed)
+	}
+	return values, nil
+}
+
+func parseNonEmptyStringList(raw string, fieldName string) ([]string, error) {
+	return parseNonEmptyStringListValues([]string{raw}, fieldName)
+}
+
+func parseNonEmptyStringListValues(rawValues []string, fieldName string) ([]string, error) {
+	items, err := splitBoundedMultiValueItems(rawValues, fieldName, maxMultiValueFilterStringItemLength)
+	if err != nil {
+		return nil, err
+	}
+	if len(items) == 0 {
+		return nil, nil
+	}
+
+	seen := make(map[string]struct{})
+	values := []string{}
+	for _, item := range items {
+		if _, ok := seen[item]; ok {
+			continue
+		}
+		seen[item] = struct{}{}
+		values = append(values, item)
+	}
+	return values, nil
+}
+
+func splitBoundedMultiValueItems(rawValues []string, fieldName string, maxItemLength int) ([]string, error) {
+	totalRawLength := 0
+	items := []string{}
+	for _, raw := range rawValues {
+		raw = strings.TrimSpace(raw)
+		if raw == "" {
+			continue
+		}
+		totalRawLength += len(raw)
+		if totalRawLength > maxMultiValueFilterRawLength {
+			return nil, fmt.Errorf("%s query is too long", fieldName)
+		}
+		for _, item := range strings.Split(raw, ",") {
+			item = strings.TrimSpace(item)
+			if item == "" {
+				continue
+			}
+			if len(item) > maxItemLength {
+				return nil, fmt.Errorf("%s contains a value longer than %d characters", fieldName, maxItemLength)
+			}
+			items = append(items, item)
+			if len(items) > maxMultiValueFilterItems {
+				return nil, fmt.Errorf("%s contains too many values; maximum is %d", fieldName, maxMultiValueFilterItems)
+			}
+		}
+	}
+	return items, nil
+}
+
+func appendInt64InFilter(whereClause string, args []any, column string, values []int64) (string, []any) {
+	if len(values) == 0 {
+		return whereClause, args
+	}
+
+	placeholders := make([]string, 0, len(values))
+	for _, value := range values {
+		placeholders = append(placeholders, "?")
+		args = append(args, value)
+	}
+	return whereClause + " AND " + column + " IN (" + strings.Join(placeholders, ",") + ")", args
+}
+
+func appendStringInFilter(whereClause string, args []any, column string, values []string) (string, []any) {
+	if len(values) == 0 {
+		return whereClause, args
+	}
+
+	placeholders := make([]string, 0, len(values))
+	for _, value := range values {
+		placeholders = append(placeholders, "?")
+		args = append(args, value)
+	}
+	return whereClause + " AND " + column + " IN (" + strings.Join(placeholders, ",") + ")", args
+}
+
 func keywordOrderBy(keyword string, fallback string, fields ...string) (string, []any) {
 	if keyword == "" || len(fields) == 0 {
 		return "ORDER BY " + fallback, nil
diff --git a/internal/api/handlers/common_test.go b/internal/api/handlers/common_test.go
new file mode 100644
index 0000000..9a4abd2
--- /dev/null
+++ b/internal/api/handlers/common_test.go
@@ -0,0 +1,69 @@
+// SPDX-FileCopyrightText: 2026 ArcheBase
+//
+// SPDX-License-Identifier: MulanPSL-2.0
+
+package handlers
+
+import (
+	"strconv"
+	"strings"
+	"testing"
+)
+
+func TestParsePositiveInt64ListBoundsValues(t *testing.T) {
+	raw := joinedNumberList(maxMultiValueFilterItems)
+	values, err := parsePositiveInt64List(raw, "ids")
+	if err != nil {
+		t.Fatalf("parsePositiveInt64List returned error: %v", err)
+	}
+	if len(values) != maxMultiValueFilterItems {
+		t.Fatalf("value count = %d, want %d", len(values), maxMultiValueFilterItems)
+	}
+
+	if _, err := parsePositiveInt64List(joinedNumberList(maxMultiValueFilterItems+1), "ids"); err == nil {
+		t.Fatalf("expected too many values error")
+	}
+	if _, err := parsePositiveInt64List(strings.Repeat("1", maxMultiValueFilterIntegerItemLength+1), "ids"); err == nil {
+		t.Fatalf("expected oversized integer token error")
+	}
+	if _, err := parsePositiveInt64List(strings.Repeat(",", maxMultiValueFilterRawLength+1), "ids"); err == nil {
+		t.Fatalf("expected raw query length error")
+	}
+}
+
+func TestParseNonEmptyStringListBoundsValuesBeforeDedup(t *testing.T) {
+	raw := joinedStringList("device", maxMultiValueFilterItems)
+	values, err := parseNonEmptyStringList(raw, "device_id")
+	if err != nil {
+		t.Fatalf("parseNonEmptyStringList returned error: %v", err)
+	}
+	if len(values) != maxMultiValueFilterItems {
+		t.Fatalf("value count = %d, want %d", len(values), maxMultiValueFilterItems)
+	}
+
+	if _, err := parseNonEmptyStringList(joinedStringList("device", maxMultiValueFilterItems+1), "device_id"); err == nil {
+		t.Fatalf("expected too many values error")
+	}
+	if _, err := parseNonEmptyStringList(strings.Repeat("same,", maxMultiValueFilterItems+1), "device_id"); err == nil {
+		t.Fatalf("expected repeated values to count toward the limit")
+	}
+	if _, err := parseNonEmptyStringList(strings.Repeat("x", maxMultiValueFilterStringItemLength+1), "device_id"); err == nil {
+		t.Fatalf("expected oversized string item error")
+	}
+}
+
+func joinedNumberList(count int) string {
+	values := make([]string, 0, count)
+	for i := 1; i <= count; i++ {
+		values = append(values, strconv.Itoa(i))
+	}
+	return strings.Join(values, ",")
+}
+
+func joinedStringList(prefix string, count int) string {
+	values := make([]string, 0, count)
+	for i := 1; i <= count; i++ {
+		values = append(values, prefix+strconv.Itoa(i))
+	}
+	return strings.Join(values, ",")
+}
diff --git a/internal/api/handlers/data_collector.go b/internal/api/handlers/data_collector.go
index 55760f3..d930fc0 100644
--- a/internal/api/handlers/data_collector.go
+++ b/internal/api/handlers/data_collector.go
@@ -157,8 +157,11 @@ func dataCollectorResponseFromRow(dc dataCollectorRow) DataCollectorResponse {
 // @Tags         data_collectors
 // @Accept       json
 // @Produce      json
-// @Param        organization_id query     string  false  "Filter by organization ID"
-// @Param        status          query     string  false  "Filter by status (active, inactive, on_leave)"
+// @Param        organization_id       query     string  false  "Filter by organization ID(s), comma-separated"
+// @Param        status                query     string  false  "Filter by status(es), comma-separated (active, inactive, on_leave)"
+// @Param        collector_operator_id query     string  false  "Filter by collector operator ID(s), comma-separated"
+// @Param        collector_name        query     string  false  "Filter by collector name(s), comma-separated"
+// @Param        name                  query     string  false  "Alias of collector_name"
 // @Param        keyword         query     string  false  "Search by name, operator ID, or email"
 // @Param        q               query     string  false  "Alias of keyword"
 // @Param        search          query     string  false  "Alias of keyword"
@@ -176,27 +179,34 @@ func (h *DataCollectorHandler) ListDataCollectors(c *gin.Context) {
 		return
 	}
 
-	orgID := c.Query("organization_id")
-	status := c.Query("status")
+	orgIDs, err := parsePositiveInt64List(c.Query("organization_id"), "organization_id")
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	statuses, err := parseNonEmptyStringList(c.Query("status"), "status")
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	operatorIDs, err := parseNonEmptyStringList(c.Query("collector_operator_id"), "collector_operator_id")
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	names, err := parseNonEmptyStringList(firstNonEmptyQuery(c, "collector_name", "name"), "collector_name")
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
 	keyword := firstNonEmptyQuery(c, "keyword", "q", "search", "operator_id")
 
 	whereClause := "WHERE dc.deleted_at IS NULL"
 	args := []interface{}{}
-
-	if orgID != "" {
-		parsedOrgID, err := strconv.ParseInt(orgID, 10, 64)
-		if err != nil {
-			c.JSON(http.StatusBadRequest, gin.H{"error": "invalid organization_id format"})
-			return
-		}
-		whereClause += " AND dc.organization_id = ?"
-		args = append(args, parsedOrgID)
-	}
-
-	if status != "" {
-		whereClause += " AND dc.status = ?"
-		args = append(args, status)
-	}
+	whereClause, args = appendInt64InFilter(whereClause, args, "dc.organization_id", orgIDs)
+	whereClause, args = appendStringInFilter(whereClause, args, "dc.status", statuses)
+	whereClause, args = appendStringInFilter(whereClause, args, "dc.operator_id", operatorIDs)
+	whereClause, args = appendStringInFilter(whereClause, args, "dc.name", names)
 
 	if keyword != "" {
 		likeKeyword := "%" + keyword + "%"
diff --git a/internal/api/handlers/data_production_statistics.go b/internal/api/handlers/data_production_statistics.go
index 6fbb416..dc76b51 100644
--- a/internal/api/handlers/data_production_statistics.go
+++ b/internal/api/handlers/data_production_statistics.go
@@ -44,13 +44,13 @@ type dataProductionStatsQuery struct {
 	EndTime              time.Time
 	Granularity          string
 	SourceID             string
-	SceneID              int64
+	SceneIDs             []int64
 	RobotDeviceIDs       []string
-	RobotTypeID          string
+	RobotTypeIDs         []string
 	CollectorOperatorIDs []string
-	SOPID                string
-	QAStatus             string
-	CloudSynced          *bool
+	SOPIDs               []string
+	QAStatuses           []string
+	CloudSyncedValues    []bool
 	DataType             string
 	TaskID               string
 }
@@ -255,31 +255,40 @@ func parseDataProductionStatsQuery(c *gin.Context, requireGranularity bool) (dat
 		}
 	}
 
-	var sceneID int64
-	rawSceneID := strings.TrimSpace(c.Query("scene_id"))
-	if rawSceneID != "" {
-		parsedSceneID, err := strconv.ParseInt(rawSceneID, 10, 64)
-		if err != nil || parsedSceneID <= 0 {
-			return dataProductionStatsQuery{}, fmt.Errorf("scene_id must be a positive integer")
-		}
-		sceneID = parsedSceneID
+	sceneIDs, err := parsePositiveInt64List(c.Query("scene_id"), "scene_id")
+	if err != nil {
+		return dataProductionStatsQuery{}, err
 	}
 
-	qaStatus := strings.TrimSpace(c.Query("qa_status"))
-	if qaStatus != "" {
+	robotDeviceIDs, err := parseStatsStringListQuery(c, "robot_device_id")
+	if err != nil {
+		return dataProductionStatsQuery{}, err
+	}
+	robotTypeIDs, err := parseStatsStringListQuery(c, "robot_type_id")
+	if err != nil {
+		return dataProductionStatsQuery{}, err
+	}
+	collectorOperatorIDs, err := parseStatsStringListQuery(c, "collector_operator_id")
+	if err != nil {
+		return dataProductionStatsQuery{}, err
+	}
+	sopIDs, err := parseStatsStringListQuery(c, "sop_id")
+	if err != nil {
+		return dataProductionStatsQuery{}, err
+	}
+	qaStatuses, err := parseStatsStringListQuery(c, "qa_status")
+	if err != nil {
+		return dataProductionStatsQuery{}, err
+	}
+	for _, qaStatus := range qaStatuses {
 		if _, ok := validDataProductionQAStatuses[qaStatus]; !ok {
 			return dataProductionStatsQuery{}, fmt.Errorf("qa_status must be one of pending_qa, qa_running, approved, needs_inspection, inspector_approved, rejected, failed")
 		}
 	}
 
-	var cloudSynced *bool
-	rawCloudSynced := strings.TrimSpace(c.Query("cloud_synced"))
-	if rawCloudSynced != "" {
-		parsedCloudSynced, err := strconv.ParseBool(rawCloudSynced)
-		if err != nil {
-			return dataProductionStatsQuery{}, fmt.Errorf("cloud_synced must be true or false")
-		}
-		cloudSynced = &parsedCloudSynced
+	cloudSyncedValues, err := parseStatsBoolListQuery(c, "cloud_synced")
+	if err != nil {
+		return dataProductionStatsQuery{}, err
 	}
 
 	return dataProductionStatsQuery{
@@ -287,13 +296,13 @@ func parseDataProductionStatsQuery(c *gin.Context, requireGranularity bool) (dat
 		EndTime:              endTime,
 		Granularity:          granularity,
 		SourceID:             strings.TrimSpace(c.Query("source_id")),
-		SceneID:              sceneID,
-		RobotDeviceIDs:       parseStatsStringListQuery(c, "robot_device_id"),
-		RobotTypeID:          strings.TrimSpace(c.Query("robot_type_id")),
-		CollectorOperatorIDs: parseStatsStringListQuery(c, "collector_operator_id"),
-		SOPID:                strings.TrimSpace(c.Query("sop_id")),
-		QAStatus:             qaStatus,
-		CloudSynced:          cloudSynced,
+		SceneIDs:             sceneIDs,
+		RobotDeviceIDs:       robotDeviceIDs,
+		RobotTypeIDs:         robotTypeIDs,
+		CollectorOperatorIDs: collectorOperatorIDs,
+		SOPIDs:               sopIDs,
+		QAStatuses:           qaStatuses,
+		CloudSyncedValues:    cloudSyncedValues,
 		DataType:             strings.TrimSpace(c.Query("data_type")),
 		TaskID:               strings.TrimSpace(c.Query("task_id")),
 	}, nil
@@ -312,25 +321,30 @@ func parseStatsTime(raw string) (time.Time, error) {
 	return time.Time{}, fmt.Errorf("invalid timestamp")
 }
 
-func parseStatsStringListQuery(c *gin.Context, key string) []string {
-	seen := map[string]struct{}{}
-	values := []string{}
-
-	for _, rawValue := range c.QueryArray(key) {
-		for _, part := range strings.Split(rawValue, ",") {
-			value := strings.TrimSpace(part)
-			if value == "" {
-				continue
-			}
-			if _, ok := seen[value]; ok {
-				continue
-			}
-			seen[value] = struct{}{}
-			values = append(values, value)
+func parseStatsStringListQuery(c *gin.Context, key string) ([]string, error) {
+	return parseNonEmptyStringListValues(c.QueryArray(key), key)
+}
+
+func parseStatsBoolListQuery(c *gin.Context, key string) ([]bool, error) {
+	items, err := splitBoundedMultiValueItems(c.QueryArray(key), key, maxMultiValueFilterStringItemLength)
+	if err != nil {
+		return nil, err
+	}
+	seen := map[bool]struct{}{}
+	values := []bool{}
+	for _, item := range items {
+		parsed, err := strconv.ParseBool(item)
+		if err != nil {
+			return nil, fmt.Errorf("%s must contain true or false", key)
 		}
+		if _, ok := seen[parsed]; ok {
+			continue
+		}
+		seen[parsed] = struct{}{}
+		values = append(values, parsed)
 	}
 
-	return values
+	return values, nil
 }
 
 // GetSummary returns aggregate data production statistics for the requested filters.
@@ -775,28 +789,13 @@ func (h *DataProductionStatisticsHandler) filteredProductionRecordsSQL(q dataPro
 		conditions = append(conditions, "source_id = ?")
 		args = append(args, q.SourceID)
 	}
-	if q.SceneID > 0 {
-		conditions = append(conditions, "scene_id = ?")
-		args = append(args, q.SceneID)
-	}
+	conditions, args = appendStatsInt64InCondition(conditions, args, "scene_id", q.SceneIDs)
 	conditions, args = appendStatsInCondition(conditions, args, "robot_device_id", q.RobotDeviceIDs)
-	if q.RobotTypeID != "" {
-		conditions = append(conditions, "robot_type_id = ?")
-		args = append(args, q.RobotTypeID)
-	}
+	conditions, args = appendStatsInCondition(conditions, args, "robot_type_id", q.RobotTypeIDs)
 	conditions, args = appendStatsInCondition(conditions, args, "collector_operator_id", q.CollectorOperatorIDs)
-	if q.SOPID != "" {
-		conditions = append(conditions, "sop_id = ?")
-		args = append(args, q.SOPID)
-	}
-	if q.QAStatus != "" {
-		conditions = append(conditions, "qa_status = ?")
-		args = append(args, q.QAStatus)
-	}
-	if q.CloudSynced != nil {
-		conditions = append(conditions, "cloud_synced = ?")
-		args = append(args, *q.CloudSynced)
-	}
+	conditions, args = appendStatsInCondition(conditions, args, "sop_id", q.SOPIDs)
+	conditions, args = appendStatsInCondition(conditions, args, "qa_status", q.QAStatuses)
+	conditions, args = appendStatsBoolInCondition(conditions, args, "cloud_synced", q.CloudSyncedValues)
 	if q.DataType != "" {
 		conditions = append(conditions, "data_type = ?")
 		args = append(args, q.DataType)
@@ -824,6 +823,30 @@ func appendStatsInCondition(conditions []string, args []interface{}, column stri
 	return conditions, args
 }
 
+func appendStatsInt64InCondition(conditions []string, args []interface{}, column string, values []int64) ([]string, []interface{}) {
+	if len(values) == 0 {
+		return conditions, args
+	}
+
+	placeholders := make([]string, 0, len(values))
+	for _, value := range values {
+		placeholders = append(placeholders, "?")
+		args = append(args, value)
+	}
+	conditions = append(conditions, fmt.Sprintf("%s IN (%s)", column, strings.Join(placeholders, ",")))
+	return conditions, args
+}
+
+func appendStatsBoolInCondition(conditions []string, args []interface{}, column string, values []bool) ([]string, []interface{}) {
+	if len(values) == 0 || len(values) > 1 {
+		return conditions, args
+	}
+
+	conditions = append(conditions, column+" = ?")
+	args = append(args, values[0])
+	return conditions, args
+}
+
 func productionRecordsSQL() string {
 	return `
 		SELECT
diff --git a/internal/api/handlers/data_production_statistics_test.go b/internal/api/handlers/data_production_statistics_test.go
index e42548e..4614cf5 100644
--- a/internal/api/handlers/data_production_statistics_test.go
+++ b/internal/api/handlers/data_production_statistics_test.go
@@ -18,7 +18,7 @@ import (
 func TestParseDataProductionStatsQuery(t *testing.T) {
 	gin.SetMode(gin.TestMode)
 
-	req := httptest.NewRequest(http.MethodGet, "/stats?start_time=2026-05-01T00:00:00Z&end_time=2026-05-02T00:00:00Z&granularity=hour&source_id=12&scene_id=34&qa_status=approved&cloud_synced=false&data_type=episode&task_id=task_1", nil)
+	req := httptest.NewRequest(http.MethodGet, "/stats?start_time=2026-05-01T00:00:00Z&end_time=2026-05-02T00:00:00Z&granularity=hour&source_id=12&scene_id=34,35&robot_type_id=7,8&sop_id=9,10&qa_status=approved,rejected&cloud_synced=false&data_type=episode&task_id=task_1", nil)
 	c, _ := gin.CreateTestContext(httptest.NewRecorder())
 	c.Request = req
 
@@ -26,9 +26,18 @@ func TestParseDataProductionStatsQuery(t *testing.T) {
 	if err != nil {
 		t.Fatalf("parseDataProductionStatsQuery returned error: %v", err)
 	}
-	if got.Granularity != "hour" || got.SourceID != "12" || got.SceneID != 34 || got.QAStatus != "approved" || got.CloudSynced == nil || *got.CloudSynced || got.DataType != "episode" || got.TaskID != "task_1" {
+	if got.Granularity != "hour" || got.SourceID != "12" || got.DataType != "episode" || got.TaskID != "task_1" {
 		t.Fatalf("unexpected query: %+v", got)
 	}
+	if len(got.SceneIDs) != 2 || got.SceneIDs[0] != 34 || got.SceneIDs[1] != 35 {
+		t.Fatalf("unexpected scene ids: %#v", got.SceneIDs)
+	}
+	if strings.Join(got.RobotTypeIDs, ",") != "7,8" || strings.Join(got.SOPIDs, ",") != "9,10" || strings.Join(got.QAStatuses, ",") != "approved,rejected" {
+		t.Fatalf("unexpected list filters: %+v", got)
+	}
+	if len(got.CloudSyncedValues) != 1 || got.CloudSyncedValues[0] {
+		t.Fatalf("unexpected cloud synced values: %#v", got.CloudSyncedValues)
+	}
 }
 
 func TestProductionRecordsSQLUsesEpisodesOnly(t *testing.T) {
@@ -96,13 +105,13 @@ func TestFilteredProductionRecordsSQLIncludesEpisodeFilters(t *testing.T) {
 	cloudSynced := true
 	handler := &DataProductionStatisticsHandler{}
 	query, args := handler.filteredProductionRecordsSQL(dataProductionStatsQuery{
-		StartTime:   mustParseStatsTimeForTest(t, "2026-05-01T00:00:00Z"),
-		EndTime:     mustParseStatsTimeForTest(t, "2026-05-02T00:00:00Z"),
-		SceneID:     34,
-		QAStatus:    "rejected",
-		CloudSynced: &cloudSynced,
+		StartTime:         mustParseStatsTimeForTest(t, "2026-05-01T00:00:00Z"),
+		EndTime:           mustParseStatsTimeForTest(t, "2026-05-02T00:00:00Z"),
+		SceneIDs:          []int64{34},
+		QAStatuses:        []string{"rejected"},
+		CloudSyncedValues: []bool{cloudSynced},
 	})
-	for _, want := range []string{"scene_id = ?", "qa_status = ?", "cloud_synced = ?"} {
+	for _, want := range []string{"scene_id IN (?)", "qa_status IN (?)", "cloud_synced = ?"} {
 		if !strings.Contains(query, want) {
 			t.Fatalf("filtered SQL should include %q: %s", want, query)
 		}
@@ -203,6 +212,19 @@ func TestParseDataProductionStatsQueryRejectsInvalidInputs(t *testing.T) {
 	}
 }
 
+func TestParseDataProductionStatsQueryRejectsOversizedListFilters(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	target := "/stats?start_time=2026-05-01T00:00:00Z&end_time=2026-05-02T00:00:00Z&robot_device_id=" +
+		joinedStringList("robot", maxMultiValueFilterItems+1)
+	c, _ := gin.CreateTestContext(httptest.NewRecorder())
+	c.Request = httptest.NewRequest(http.MethodGet, target, nil)
+
+	if _, err := parseDataProductionStatsQuery(c, true); err == nil {
+		t.Fatalf("expected oversized list validation error")
+	}
+}
+
 func mustParseStatsTimeForTest(t *testing.T, raw string) time.Time {
 	t.Helper()
 	value, err := parseStatsTime(raw)
diff --git a/internal/api/handlers/factory.go b/internal/api/handlers/factory.go
index e5397e7..ae83860 100644
--- a/internal/api/handlers/factory.go
+++ b/internal/api/handlers/factory.go
@@ -143,6 +143,8 @@ func (h *FactoryHandler) allocateFactorySlug() (string, error) {
 // @Tags         factories
 // @Accept       json
 // @Produce      json
+// @Param        factory_id query     string  false  "Filter by factory ID(s), comma-separated"
+// @Param        id      query     string  false  "Alias of factory_id"
 // @Param        keyword query     string  false  "Search by name, slug, or location"
 // @Param        q       query     string  false  "Alias of keyword"
 // @Param        search  query     string  false  "Alias of keyword"
@@ -159,9 +161,16 @@ func (h *FactoryHandler) ListFactories(c *gin.Context) {
 		return
 	}
 
+	factoryIDs, err := parsePositiveInt64List(firstNonEmptyQuery(c, "factory_id", "id"), "factory_id")
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
 	keyword := firstNonEmptyQuery(c, "keyword", "q", "search")
 	whereClause := "WHERE deleted_at IS NULL"
 	args := []any{}
+	whereClause, args = appendInt64InFilter(whereClause, args, "id", factoryIDs)
 	whereClause, args = appendKeywordSearch(whereClause, args, keyword, "name", "slug", "location")
 
 	countQuery := "SELECT COUNT(*) FROM factories " + whereClause
diff --git a/internal/api/handlers/inspector.go b/internal/api/handlers/inspector.go
index a386ef8..d3b1a79 100644
--- a/internal/api/handlers/inspector.go
+++ b/internal/api/handlers/inspector.go
@@ -117,14 +117,17 @@ type inspectorRow struct {
 // @Tags         inspectors
 // @Accept       json
 // @Produce      json
-// @Param        organization_id query string false "Filter by organization ID"
-// @Param        certification_level query string false "Filter by certification level (level_1, level_2, senior)"
-// @Param        status          query string false "Filter by status (active, inactive)"
-// @Param        keyword         query string false "Search by name, inspector ID, or email"
-// @Param        q               query string false "Alias of keyword"
-// @Param        search          query string false "Alias of keyword"
-// @Param        limit           query int    false "Max results (default 50, max 100)"
-// @Param        offset          query int    false "Pagination offset (default 0)"
+// @Param        organization_id     query string false "Filter by organization ID(s), comma-separated"
+// @Param        certification_level query string false "Filter by certification level(s), comma-separated (level_1, level_2, senior)"
+// @Param        status              query string false "Filter by status(es), comma-separated (active, inactive)"
+// @Param        inspector_id        query string false "Filter by inspector ID(s), comma-separated"
+// @Param        inspector_name      query string false "Filter by inspector name(s), comma-separated"
+// @Param        name                query string false "Alias of inspector_name"
+// @Param        keyword             query string false "Search by name, inspector ID, or email"
+// @Param        q                   query string false "Alias of keyword"
+// @Param        search              query string false "Alias of keyword"
+// @Param        limit               query int    false "Max results (default 50, max 100)"
+// @Param        offset              query int    false "Pagination offset (default 0)"
 // @Success      200 {object} InspectorListResponse
 // @Failure      400 {object} map[string]string
 // @Failure      500 {object} map[string]string
@@ -136,38 +139,48 @@ func (h *InspectorHandler) ListInspectors(c *gin.Context) {
 		return
 	}
 
-	orgID := c.Query("organization_id")
-	certLevel := strings.TrimSpace(c.Query("certification_level"))
-	status := c.Query("status")
-	keyword := firstNonEmptyQuery(c, "keyword", "q", "search")
-
-	whereClause := "WHERE deleted_at IS NULL"
-	args := []any{}
-
-	if orgID != "" {
-		parsedOrgID, err := strconv.ParseInt(orgID, 10, 64)
-		if err != nil {
-			c.JSON(http.StatusBadRequest, gin.H{"error": "invalid organization_id format"})
-			return
-		}
-		whereClause += " AND organization_id = ?"
-		args = append(args, parsedOrgID)
+	orgIDs, err := parsePositiveInt64List(c.Query("organization_id"), "organization_id")
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
 	}
-
-	if certLevel != "" {
+	certLevels, err := parseNonEmptyStringList(c.Query("certification_level"), "certification_level")
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	for i, certLevel := range certLevels {
 		certLevel = strings.ToLower(certLevel)
 		if certLevel != "level_1" && certLevel != "level_2" && certLevel != "senior" {
 			c.JSON(http.StatusBadRequest, gin.H{"error": "invalid certification_level, must be one of: level_1, level_2, senior"})
 			return
 		}
-		whereClause += " AND certification_level = ?"
-		args = append(args, certLevel)
+		certLevels[i] = certLevel
 	}
-
-	if status != "" {
-		whereClause += " AND status = ?"
-		args = append(args, status)
+	statuses, err := parseNonEmptyStringList(c.Query("status"), "status")
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	inspectorIDs, err := parseNonEmptyStringList(c.Query("inspector_id"), "inspector_id")
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
 	}
+	names, err := parseNonEmptyStringList(firstNonEmptyQuery(c, "inspector_name", "name"), "inspector_name")
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	keyword := firstNonEmptyQuery(c, "keyword", "q", "search")
+
+	whereClause := "WHERE deleted_at IS NULL"
+	args := []any{}
+	whereClause, args = appendInt64InFilter(whereClause, args, "organization_id", orgIDs)
+	whereClause, args = appendStringInFilter(whereClause, args, "certification_level", certLevels)
+	whereClause, args = appendStringInFilter(whereClause, args, "status", statuses)
+	whereClause, args = appendStringInFilter(whereClause, args, "inspector_id", inspectorIDs)
+	whereClause, args = appendStringInFilter(whereClause, args, "name", names)
 	whereClause, args = appendKeywordSearch(whereClause, args, keyword, "name", "inspector_id", "email")
 
 	countQuery := "SELECT COUNT(*) FROM inspectors " + whereClause
diff --git a/internal/api/handlers/order.go b/internal/api/handlers/order.go
index 817f821..ae8112c 100644
--- a/internal/api/handlers/order.go
+++ b/internal/api/handlers/order.go
@@ -180,41 +180,49 @@ func (h *OrderHandler) ListOrders(c *gin.Context) {
 		return
 	}
 
-	orgIDStr := strings.TrimSpace(c.Query("organization_id"))
-	sceneIDStr := strings.TrimSpace(c.Query("scene_id"))
-	priority := strings.TrimSpace(c.Query("priority"))
-	status := strings.TrimSpace(c.Query("status"))
-	keyword := firstNonEmptyQuery(c, "keyword", "q", "search")
-	idsStr := strings.TrimSpace(c.Query("ids")) // comma-separated numeric IDs for batch lookup
-	if status != "" {
-		if _, ok := validOrderStatuses[status]; !ok {
-			c.JSON(http.StatusBadRequest, gin.H{"error": "invalid status"})
-			return
-		}
+	orgIDs, err := parsePositiveInt64List(c.Query("organization_id"), "organization_id")
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
 	}
-	if priority != "" {
+	sceneIDs, err := parsePositiveInt64List(c.Query("scene_id"), "scene_id")
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	priorities, err := parseNonEmptyStringList(c.Query("priority"), "priority")
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	for _, priority := range priorities {
 		if _, ok := validOrderPriorities[priority]; !ok {
 			c.JSON(http.StatusBadRequest, gin.H{"error": "invalid priority"})
 			return
 		}
 	}
-
-	// Parse and validate the ids filter (comma-separated numeric IDs).
-	var filterIDs []int64
-	if idsStr != "" {
-		for _, raw := range strings.Split(idsStr, ",") {
-			raw = strings.TrimSpace(raw)
-			if raw == "" {
-				continue
-			}
-			parsed, err := strconv.ParseInt(raw, 10, 64)
-			if err != nil {
-				c.JSON(http.StatusBadRequest, gin.H{"error": "invalid ids format: each id must be a number"})
-				return
-			}
-			filterIDs = append(filterIDs, parsed)
+	statuses, err := parseNonEmptyStringList(c.Query("status"), "status")
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	for _, status := range statuses {
+		if _, ok := validOrderStatuses[status]; !ok {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "invalid status"})
+			return
 		}
 	}
+	orderNames, err := parseNonEmptyStringList(firstNonEmptyQuery(c, "order_name", "name"), "order_name")
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	keyword := firstNonEmptyQuery(c, "keyword", "q", "search")
+	filterIDs, err := parsePositiveInt64List(c.Query("ids"), "ids") // comma-separated numeric IDs for batch lookup
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
 
 	countQuery := `
 		SELECT COUNT(*)
@@ -224,43 +232,13 @@ func (h *OrderHandler) ListOrders(c *gin.Context) {
 		WHERE o.deleted_at IS NULL
 	`
 	countArgs := []any{}
-	if orgIDStr != "" {
-		parsedOrgID, err := strconv.ParseInt(orgIDStr, 10, 64)
-		if err != nil {
-			c.JSON(http.StatusBadRequest, gin.H{"error": "invalid organization_id format"})
-			return
-		}
-		countQuery += " AND o.organization_id = ?"
-		countArgs = append(countArgs, parsedOrgID)
-	}
-	if sceneIDStr != "" {
-		parsedSceneID, err := strconv.ParseInt(sceneIDStr, 10, 64)
-		if err != nil {
-			c.JSON(http.StatusBadRequest, gin.H{"error": "invalid scene_id format"})
-			return
-		}
-		countQuery += " AND o.scene_id = ?"
-		countArgs = append(countArgs, parsedSceneID)
-	}
-	if status != "" {
-		countQuery += " AND o.status = ?"
-		countArgs = append(countArgs, status)
-	}
-	if priority != "" {
-		countQuery += " AND o.priority = ?"
-		countArgs = append(countArgs, priority)
-	}
-	if len(filterIDs) > 0 {
-		inQ, inArgs, err := sqlx.In("AND o.id IN (?)", filterIDs)
-		if err != nil {
-			logger.Printf("[ORDER] Failed to build ids IN clause for count: %v", err)
-			c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to list orders"})
-			return
-		}
-		countQuery += " " + inQ
-		countArgs = append(countArgs, inArgs...)
-	}
 	orderSearchFields := []string{"o.name", "s.name", "org.name"}
+	countQuery, countArgs = appendInt64InFilter(countQuery, countArgs, "o.organization_id", orgIDs)
+	countQuery, countArgs = appendInt64InFilter(countQuery, countArgs, "o.scene_id", sceneIDs)
+	countQuery, countArgs = appendStringInFilter(countQuery, countArgs, "o.status", statuses)
+	countQuery, countArgs = appendStringInFilter(countQuery, countArgs, "o.priority", priorities)
+	countQuery, countArgs = appendStringInFilter(countQuery, countArgs, "o.name", orderNames)
+	countQuery, countArgs = appendInt64InFilter(countQuery, countArgs, "o.id", filterIDs)
 	countQuery, countArgs = appendKeywordSearch(countQuery, countArgs, keyword, orderSearchFields...)
 	var total int
 	if err := h.db.Get(&total, h.db.Rebind(countQuery), countArgs...); err != nil {
@@ -291,34 +269,12 @@ func (h *OrderHandler) ListOrders(c *gin.Context) {
 		WHERE o.deleted_at IS NULL
 	`
 	args := []any{}
-	if orgIDStr != "" {
-		parsedOrgID, _ := strconv.ParseInt(orgIDStr, 10, 64)
-		query += " AND o.organization_id = ?\n"
-		args = append(args, parsedOrgID)
-	}
-	if sceneIDStr != "" {
-		parsedSceneID, _ := strconv.ParseInt(sceneIDStr, 10, 64)
-		query += " AND o.scene_id = ?\n"
-		args = append(args, parsedSceneID)
-	}
-	if status != "" {
-		query += " AND o.status = ?\n"
-		args = append(args, status)
-	}
-	if priority != "" {
-		query += " AND o.priority = ?\n"
-		args = append(args, priority)
-	}
-	if len(filterIDs) > 0 {
-		inQ, inArgs, err := sqlx.In("AND o.id IN (?)", filterIDs)
-		if err != nil {
-			logger.Printf("[ORDER] Failed to build ids IN clause: %v", err)
-			c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to list orders"})
-			return
-		}
-		query += " " + inQ + "\n"
-		args = append(args, inArgs...)
-	}
+	query, args = appendInt64InFilter(query, args, "o.organization_id", orgIDs)
+	query, args = appendInt64InFilter(query, args, "o.scene_id", sceneIDs)
+	query, args = appendStringInFilter(query, args, "o.status", statuses)
+	query, args = appendStringInFilter(query, args, "o.priority", priorities)
+	query, args = appendStringInFilter(query, args, "o.name", orderNames)
+	query, args = appendInt64InFilter(query, args, "o.id", filterIDs)
 	query, args = appendKeywordSearch(query, args, keyword, orderSearchFields...)
 	orderClause, orderArgs := keywordOrderBy(keyword, "o.id DESC", orderSearchFields...)
 	query += `
diff --git a/internal/api/handlers/order_test.go b/internal/api/handlers/order_test.go
new file mode 100644
index 0000000..cae4aeb
--- /dev/null
+++ b/internal/api/handlers/order_test.go
@@ -0,0 +1,159 @@
+// SPDX-FileCopyrightText: 2026 ArcheBase
+//
+// SPDX-License-Identifier: MulanPSL-2.0
+
+package handlers
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/jmoiron/sqlx"
+	_ "modernc.org/sqlite"
+)
+
+func TestOrderHandlerListOrdersFilters(t *testing.T) {
+	db := newTestOrderHandlerDB(t)
+	defer db.Close()
+	seedOrderListFixtures(t, db)
+
+	r := newTestOrderRouter(t, db)
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/orders?order_name=厨房取物&organization_id=1&scene_id=10&priority=normal&status=created", nil)
+	w := httptest.NewRecorder()
+	r.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status=%d want=%d body=%s", w.Code, http.StatusOK, w.Body.String())
+	}
+
+	var body OrderListResponse
+	if err := json.Unmarshal(w.Body.Bytes(), &body); err != nil {
+		t.Fatalf("unmarshal response: %v", err)
+	}
+	if body.Total != 1 || len(body.Items) != 1 {
+		t.Fatalf("got total=%d len=%d body=%s", body.Total, len(body.Items), w.Body.String())
+	}
+	got := body.Items[0]
+	if got.ID != "1" || got.Name != "厨房取物" || got.OrganizationID != "1" || got.SceneID != "10" || got.Priority != "normal" || got.Status != "created" {
+		t.Fatalf("unexpected order item: %+v", got)
+	}
+}
+
+func TestOrderHandlerListOrdersRejectsInvalidStatus(t *testing.T) {
+	db := newTestOrderHandlerDB(t)
+	defer db.Close()
+
+	r := newTestOrderRouter(t, db)
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/orders?status=created,bad", nil)
+	w := httptest.NewRecorder()
+	r.ServeHTTP(w, req)
+
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("status=%d want=%d body=%s", w.Code, http.StatusBadRequest, w.Body.String())
+	}
+}
+
+func newTestOrderRouter(t *testing.T, db *sqlx.DB) *gin.Engine {
+	t.Helper()
+	gin.SetMode(gin.TestMode)
+	r := gin.New()
+
+	h := NewOrderHandler(db, nil, 0)
+	v1 := r.Group("/api/v1")
+	h.RegisterRoutes(v1)
+
+	return r
+}
+
+func newTestOrderHandlerDB(t *testing.T) *sqlx.DB {
+	t.Helper()
+	db, err := sqlx.Open("sqlite", ":memory:")
+	if err != nil {
+		t.Fatalf("open sqlite db: %v", err)
+	}
+
+	schema := []string{
+		`CREATE TABLE organizations (
+			id INTEGER PRIMARY KEY,
+			name TEXT NOT NULL,
+			deleted_at TIMESTAMP NULL
+		)`,
+		`CREATE TABLE scenes (
+			id INTEGER PRIMARY KEY,
+			name TEXT NOT NULL,
+			deleted_at TIMESTAMP NULL
+		)`,
+		`CREATE TABLE orders (
+			id INTEGER PRIMARY KEY,
+			scene_id INTEGER NOT NULL,
+			organization_id INTEGER NOT NULL,
+			name TEXT NOT NULL,
+			target_count INTEGER NOT NULL,
+			status TEXT NOT NULL,
+			priority TEXT NOT NULL,
+			deadline TIMESTAMP NULL,
+			metadata TEXT,
+			created_at TIMESTAMP NOT NULL,
+			updated_at TIMESTAMP NOT NULL,
+			deleted_at TIMESTAMP NULL
+		)`,
+		`CREATE TABLE tasks (
+			id INTEGER PRIMARY KEY,
+			order_id INTEGER NOT NULL,
+			status TEXT NOT NULL,
+			deleted_at TIMESTAMP NULL
+		)`,
+	}
+	for _, stmt := range schema {
+		if _, err := db.Exec(stmt); err != nil {
+			t.Fatalf("create schema failed: %v", err)
+		}
+	}
+
+	return db
+}
+
+func seedOrderListFixtures(t *testing.T, db *sqlx.DB) {
+	t.Helper()
+	now := time.Now().UTC()
+	stmts := []string{
+		`INSERT INTO organizations (id, name) VALUES (1, '组织A')`,
+		`INSERT INTO organizations (id, name) VALUES (2, '组织B')`,
+		`INSERT INTO scenes (id, name) VALUES (10, '厨房')`,
+		`INSERT INTO scenes (id, name) VALUES (11, '卧室')`,
+	}
+	for _, stmt := range stmts {
+		if _, err := db.Exec(stmt); err != nil {
+			t.Fatalf("seed order lookup fixtures failed: %v", err)
+		}
+	}
+
+	rows := []struct {
+		id             int
+		sceneID        int
+		organizationID int
+		name           string
+		priority       string
+		status         string
+	}{
+		{id: 1, sceneID: 10, organizationID: 1, name: "厨房取物", priority: "normal", status: "created"},
+		{id: 2, sceneID: 11, organizationID: 2, name: "卧室整理", priority: "high", status: "in_progress"},
+		{id: 3, sceneID: 11, organizationID: 1, name: "厨房移动水瓶", priority: "urgent", status: "completed"},
+	}
+	for _, row := range rows {
+		if _, err := db.Exec(
+			`INSERT INTO orders (id, scene_id, organization_id, name, target_count, status, priority, metadata, created_at, updated_at)
+			 VALUES (?, ?, ?, ?, 10, ?, ?, '{}', ?, ?)`,
+			row.id, row.sceneID, row.organizationID, row.name, row.status, row.priority, now, now,
+		); err != nil {
+			t.Fatalf("seed orders failed: %v", err)
+		}
+	}
+	if _, err := db.Exec(`INSERT INTO tasks (order_id, status) VALUES (1, 'completed')`); err != nil {
+		t.Fatalf("seed order tasks failed: %v", err)
+	}
+}
diff --git a/internal/api/handlers/organization.go b/internal/api/handlers/organization.go
index bd1105d..0544fad 100644
--- a/internal/api/handlers/organization.go
+++ b/internal/api/handlers/organization.go
@@ -163,7 +163,9 @@ type organizationRow struct {
 // @Tags         organizations
 // @Accept       json
 // @Produce      json
-// @Param        factory_id query     string false "Filter by factory ID"
+// @Param        factory_id query     string false "Filter by factory ID(s), comma-separated"
+// @Param        organization_id query string false "Filter by organization ID(s), comma-separated"
+// @Param        id         query     string false "Alias of organization_id"
 // @Param        keyword    query     string false "Search by name, slug, or description"
 // @Param        q          query     string false "Alias of keyword"
 // @Param        search     query     string false "Alias of keyword"
@@ -180,25 +182,23 @@ func (h *OrganizationHandler) ListOrganizations(c *gin.Context) {
 		return
 	}
 
-	factoryIDStr := strings.TrimSpace(c.Query("factory_id"))
-	var factoryID int64
-	hasFactoryFilter := factoryIDStr != ""
-	if hasFactoryFilter {
-		var err error
-		factoryID, err = strconv.ParseInt(factoryIDStr, 10, 64)
-		if err != nil || factoryID <= 0 {
-			c.JSON(http.StatusBadRequest, gin.H{"error": "invalid factory_id format"})
-			return
-		}
+	factoryIDs, err := parsePositiveInt64List(c.Query("factory_id"), "factory_id")
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	organizationIDs, err := parsePositiveInt64List(firstNonEmptyQuery(c, "organization_id", "id"), "organization_id")
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
 	}
 
 	keyword := firstNonEmptyQuery(c, "keyword", "q", "search")
 	whereClause := "WHERE o.deleted_at IS NULL"
 	args := []any{}
-	if hasFactoryFilter {
-		whereClause += " AND o.factory_id = ?"
-		args = append(args, factoryID)
-	}
+	whereClause, args = appendInt64InFilter(whereClause, args, "o.factory_id", factoryIDs)
+	whereClause, args = appendInt64InFilter(whereClause, args, "o.id", organizationIDs)
 	whereClause, args = appendKeywordSearch(whereClause, args, keyword, "o.name", "o.slug", "o.description")
 
 	countQuery := "SELECT COUNT(*) FROM organizations o " + whereClause
diff --git a/internal/api/handlers/production_dashboard.go b/internal/api/handlers/production_dashboard.go
new file mode 100644
index 0000000..f887c28
--- /dev/null
+++ b/internal/api/handlers/production_dashboard.go
@@ -0,0 +1,940 @@
+// SPDX-FileCopyrightText: 2026 ArcheBase
+//
+// SPDX-License-Identifier: MulanPSL-2.0
+
+package handlers
+
+import (
+	"database/sql"
+	"fmt"
+	"math"
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/jmoiron/sqlx"
+
+	"archebase.com/keystone-edge/internal/auth"
+	"archebase.com/keystone-edge/internal/logger"
+	"archebase.com/keystone-edge/internal/middleware"
+)
+
+const (
+	defaultDashboardTrendDays         = 7
+	maxDashboardTrendDays             = 31
+	defaultDashboardDistributionLimit = 100
+	maxDashboardDistributionLimit     = 100
+	defaultDashboardActiveLimit       = 20
+	maxDashboardActiveLimit           = 100
+)
+
+// ProductionDashboardHandler serves aggregate data for production dashboard pages.
+type ProductionDashboardHandler struct {
+	db *sqlx.DB
+}
+
+// NewProductionDashboardHandler creates a production dashboard aggregate handler.
+func NewProductionDashboardHandler(db *sqlx.DB) *ProductionDashboardHandler {
+	return &ProductionDashboardHandler{db: db}
+}
+
+// RegisterRoutes registers production dashboard aggregate routes.
+func (h *ProductionDashboardHandler) RegisterRoutes(apiV1 *gin.RouterGroup) {
+	apiV1.GET("/snapshot", h.GetSnapshot)
+	apiV1.GET("/batches/:id/task-summary", h.GetBatchTaskSummary)
+}
+
+type productionDashboardQuery struct {
+	WorkstationID     string
+	FactoryID         string
+	OrganizationID    string
+	TrendDays         int
+	DistributionLimit int
+	ActiveLimit       int
+	TimezoneOffset    string
+}
+
+type productionDashboardScope struct {
+	Role           string `json:"role"`
+	WorkstationID  string `json:"workstation_id,omitempty"`
+	FactoryID      string `json:"factory_id,omitempty"`
+	OrganizationID string `json:"organization_id,omitempty"`
+	Warning        string `json:"warning,omitempty"`
+	collectorID    int64
+	empty          bool
+}
+
+type productionDashboardSnapshotResponse struct {
+	GeneratedAt   string                     `json:"generated_at"`
+	Scope         productionDashboardScope   `json:"scope"`
+	Tasks         dashboardTaskCounts        `json:"tasks"`
+	Trend         []dashboardTrendItem       `json:"trend"`
+	Distributions dashboardDistributions     `json:"distributions"`
+	Quality       dashboardQuality           `json:"quality"`
+	System        dashboardSystemStatus      `json:"system"`
+	Stations      []dashboardStationItem     `json:"stations"`
+	ActiveBatches []dashboardActiveBatchItem `json:"active_batches"`
+	ActiveTasks   []dashboardActiveTaskItem  `json:"active_tasks"`
+}
+
+type dashboardTaskCounts struct {
+	Total      int64 `json:"total" db:"total"`
+	Completed  int64 `json:"completed" db:"completed"`
+	InProgress int64 `json:"in_progress" db:"in_progress"`
+	Pending    int64 `json:"pending" db:"pending"`
+	Ready      int64 `json:"ready" db:"ready"`
+	Failed     int64 `json:"failed" db:"failed"`
+	Cancelled  int64 `json:"cancelled" db:"cancelled"`
+}
+
+type dashboardTrendItem struct {
+	Date       string `json:"date" db:"date"`
+	Completed  int64  `json:"completed" db:"completed"`
+	InProgress int64  `json:"in_progress" db:"in_progress"`
+	Pending    int64  `json:"pending" db:"pending"`
+}
+
+type dashboardDistributionItem struct {
+	ID    string `json:"id" db:"id"`
+	Name  string `json:"name" db:"name"`
+	Value int64  `json:"value" db:"value"`
+}
+
+type dashboardDistributions struct {
+	Scene []dashboardDistributionItem `json:"scene"`
+	SOP   []dashboardDistributionItem `json:"sop"`
+}
+
+type dashboardQuality struct {
+	PassRate       float64 `json:"pass_rate"`
+	TotalInspected int64   `json:"total_inspected" db:"total_inspected"`
+	Passed         int64   `json:"passed" db:"passed"`
+	Failed         int64   `json:"failed" db:"failed"`
+	Inspecting     int64   `json:"inspecting" db:"inspecting"`
+	PendingQA      int64   `json:"pending_qa" db:"pending_qa"`
+}
+
+type dashboardQualityRow struct {
+	TotalInspected   sql.NullInt64   `db:"total_inspected"`
+	Passed           sql.NullInt64   `db:"passed"`
+	Failed           sql.NullInt64   `db:"failed"`
+	Inspecting       sql.NullInt64   `db:"inspecting"`
+	PendingQA        sql.NullInt64   `db:"pending_qa"`
+	TotalDurationSec sql.NullFloat64 `db:"total_duration_sec"`
+}
+
+type dashboardSystemStatus struct {
+	OperatingDays        int64   `json:"operating_days"`
+	TotalDataDurationSec float64 `json:"total_data_duration_sec"`
+	OnlineStations       int64   `json:"online_stations"`
+}
+
+type dashboardStationItem struct {
+	ID                  string `json:"id" db:"id"`
+	Status              string `json:"status" db:"status"`
+	StatusText          string `json:"status_text"`
+	CollectorOperatorID string `json:"collector_operator_id" db:"collector_operator_id"`
+	CollectorName       string `json:"collector_name" db:"collector_name"`
+	DeviceID            string `json:"device_id" db:"device_id"`
+	DeviceModel         string `json:"device_model" db:"device_model"`
+}
+
+type dashboardActiveBatchItem struct {
+	ID                  string `json:"id" db:"id"`
+	BatchID             string `json:"batch_id" db:"batch_id"`
+	OrderID             string `json:"order_id" db:"order_id"`
+	OrderName           string `json:"order_name" db:"order_name"`
+	SceneName           string `json:"scene_name" db:"scene_name"`
+	WorkstationID       string `json:"workstation_id" db:"workstation_id"`
+	DeviceID            string `json:"device_id" db:"device_id"`
+	CollectorOperatorID string `json:"collector_operator_id" db:"collector_operator_id"`
+	CollectorName       string `json:"collector_name" db:"collector_name"`
+	TaskCount           int64  `json:"task_count" db:"task_count"`
+	CompletedCount      int64  `json:"completed_count" db:"completed_count"`
+	FailedCount         int64  `json:"failed_count" db:"failed_count"`
+	CancelledCount      int64  `json:"cancelled_count" db:"cancelled_count"`
+}
+
+type dashboardActiveTaskItem struct {
+	ID                  string `json:"id" db:"id"`
+	SOPID               string `json:"sop_id" db:"sop_id"`
+	SOPLabel            string `json:"sop_label" db:"sop_label"`
+	SceneFull           string `json:"scene_full" db:"scene_full"`
+	DeviceID            string `json:"device_id" db:"device_id"`
+	CollectorOperatorID string `json:"collector_operator_id" db:"collector_operator_id"`
+	CollectorName       string `json:"collector_name" db:"collector_name"`
+}
+
+type dashboardBatchTaskSummaryResponse struct {
+	BatchID string                          `json:"batch_id"`
+	Items   []dashboardBatchTaskSummaryItem `json:"items"`
+}
+
+type dashboardBatchTaskSummaryItem struct {
+	SOPID        string           `json:"sop_id" db:"sop_id"`
+	SOPLabel     string           `json:"sop_label" db:"sop_label"`
+	SceneName    string           `json:"scene_name" db:"scene_name"`
+	SubsceneName string           `json:"subscene_name" db:"subscene_name"`
+	Total        int64            `json:"total" db:"total"`
+	Statuses     map[string]int64 `json:"statuses,omitempty"`
+	Pending      int64            `json:"-" db:"pending"`
+	Ready        int64            `json:"-" db:"ready"`
+	InProgress   int64            `json:"-" db:"in_progress"`
+	Completed    int64            `json:"-" db:"completed"`
+	Failed       int64            `json:"-" db:"failed"`
+	Cancelled    int64            `json:"-" db:"cancelled"`
+}
+
+type dashboardDB interface {
+	Get(dest interface{}, query string, args ...interface{}) error
+	Select(dest interface{}, query string, args ...interface{}) error
+}
+
+// GetSnapshot returns one aggregate snapshot for the production dashboard.
+func (h *ProductionDashboardHandler) GetSnapshot(c *gin.Context) {
+	claims := middleware.GetClaims(c)
+	if claims == nil {
+		c.JSON(http.StatusUnauthorized, gin.H{"error": "authentication required"})
+		return
+	}
+
+	q, err := parseProductionDashboardQuery(c)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	scope, err := h.resolveProductionDashboardScope(c, claims, q)
+	if err != nil {
+		logger.Printf("[DASHBOARD] scope query failed: %v", err)
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to get production dashboard"})
+		return
+	}
+	if scope.empty {
+		c.JSON(http.StatusOK, emptyProductionDashboardSnapshot(scope))
+		return
+	}
+
+	tx, err := h.db.BeginTxx(c.Request.Context(), &sql.TxOptions{ReadOnly: true})
+	if err != nil {
+		logger.Printf("[DASHBOARD] begin read transaction failed: %v", err)
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to get production dashboard"})
+		return
+	}
+	defer func() { _ = tx.Rollback() }()
+
+	tasks, err := h.dashboardTaskCounts(tx, scope)
+	if err != nil {
+		logger.Printf("[DASHBOARD] task count query failed: %v", err)
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to get production dashboard"})
+		return
+	}
+	trend, err := h.dashboardTaskTrend(tx, scope, q)
+	if err != nil {
+		logger.Printf("[DASHBOARD] task trend query failed: %v", err)
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to get production dashboard"})
+		return
+	}
+	sceneDistribution, err := h.dashboardTaskDistribution(tx, scope, "scene", q.DistributionLimit)
+	if err != nil {
+		logger.Printf("[DASHBOARD] scene distribution query failed: %v", err)
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to get production dashboard"})
+		return
+	}
+	sopDistribution, err := h.dashboardTaskDistribution(tx, scope, "sop", q.DistributionLimit)
+	if err != nil {
+		logger.Printf("[DASHBOARD] sop distribution query failed: %v", err)
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to get production dashboard"})
+		return
+	}
+	quality, totalDurationSec, err := h.dashboardQuality(tx, scope)
+	if err != nil {
+		logger.Printf("[DASHBOARD] quality query failed: %v", err)
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to get production dashboard"})
+		return
+	}
+	stations, err := h.dashboardStations(tx, scope)
+	if err != nil {
+		logger.Printf("[DASHBOARD] stations query failed: %v", err)
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to get production dashboard"})
+		return
+	}
+	operatingDays, err := h.dashboardOperatingDays(tx, scope)
+	if err != nil {
+		logger.Printf("[DASHBOARD] operating days query failed: %v", err)
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to get production dashboard"})
+		return
+	}
+	activeBatches, err := h.dashboardActiveBatches(tx, scope, q.ActiveLimit)
+	if err != nil {
+		logger.Printf("[DASHBOARD] active batches query failed: %v", err)
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to get production dashboard"})
+		return
+	}
+	activeTasks, err := h.dashboardActiveTasks(tx, scope, q.ActiveLimit)
+	if err != nil {
+		logger.Printf("[DASHBOARD] active tasks query failed: %v", err)
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to get production dashboard"})
+		return
+	}
+
+	if err := tx.Commit(); err != nil {
+		logger.Printf("[DASHBOARD] commit read transaction failed: %v", err)
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to get production dashboard"})
+		return
+	}
+
+	c.JSON(http.StatusOK, productionDashboardSnapshotResponse{
+		GeneratedAt: time.Now().UTC().Format(time.RFC3339),
+		Scope:       scope,
+		Tasks:       tasks,
+		Trend:       trend,
+		Distributions: dashboardDistributions{
+			Scene: sceneDistribution,
+			SOP:   sopDistribution,
+		},
+		Quality: quality,
+		System: dashboardSystemStatus{
+			OperatingDays:        operatingDays,
+			TotalDataDurationSec: totalDurationSec,
+			OnlineStations:       countOnlineDashboardStations(stations),
+		},
+		Stations:      stations,
+		ActiveBatches: activeBatches,
+		ActiveTasks:   activeTasks,
+	})
+}
+
+// GetBatchTaskSummary returns task status counts grouped by SOP/scene/subscene for one batch.
+func (h *ProductionDashboardHandler) GetBatchTaskSummary(c *gin.Context) {
+	claims := middleware.GetClaims(c)
+	if claims == nil {
+		c.JSON(http.StatusUnauthorized, gin.H{"error": "authentication required"})
+		return
+	}
+
+	id, err := strconv.ParseInt(strings.TrimSpace(c.Param("id")), 10, 64)
+	if err != nil || id <= 0 {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "invalid batch id"})
+		return
+	}
+
+	scope, err := h.resolveProductionDashboardScope(c, claims, productionDashboardQuery{})
+	if err != nil {
+		logger.Printf("[DASHBOARD] scope query failed: %v", err)
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to get batch task summary"})
+		return
+	}
+	if scope.empty {
+		c.JSON(http.StatusOK, dashboardBatchTaskSummaryResponse{BatchID: strconv.FormatInt(id, 10), Items: []dashboardBatchTaskSummaryItem{}})
+		return
+	}
+
+	conditions := []string{"b.id = ?", "b.deleted_at IS NULL"}
+	args := []interface{}{id}
+	conditions, args = appendDashboardBatchScope(conditions, args, scope)
+
+	var exists int
+	if err := h.db.Get(&exists, `
+		SELECT 1
+		FROM batches b
+		LEFT JOIN workstations ws ON ws.id = b.workstation_id AND ws.deleted_at IS NULL
+		WHERE `+strings.Join(conditions, " AND ")+`
+		LIMIT 1
+	`, args...); err != nil {
+		if err == sql.ErrNoRows {
+			c.JSON(http.StatusNotFound, gin.H{"error": "batch not found"})
+			return
+		}
+		logger.Printf("[DASHBOARD] batch scope query failed: %v", err)
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to get batch task summary"})
+		return
+	}
+
+	query := `
+		SELECT
+			COALESCE(CAST(t.sop_id AS CHAR), '') AS sop_id,
+			` + dashboardSOPLabelSQL("t.sop_id", "s.slug", "s.version") + ` AS sop_label,
+			COALESCE(t.scene_name, '') AS scene_name,
+			COALESCE(t.subscene_name, '') AS subscene_name,
+			COUNT(1) AS total,
+			COALESCE(SUM(CASE WHEN t.status = 'pending' THEN 1 ELSE 0 END), 0) AS pending,
+			COALESCE(SUM(CASE WHEN t.status = 'ready' THEN 1 ELSE 0 END), 0) AS ready,
+			COALESCE(SUM(CASE WHEN t.status = 'in_progress' THEN 1 ELSE 0 END), 0) AS in_progress,
+			COALESCE(SUM(CASE WHEN t.status = 'completed' THEN 1 ELSE 0 END), 0) AS completed,
+			COALESCE(SUM(CASE WHEN t.status = 'failed' THEN 1 ELSE 0 END), 0) AS failed,
+			COALESCE(SUM(CASE WHEN t.status = 'cancelled' THEN 1 ELSE 0 END), 0) AS cancelled
+		FROM tasks t
+		LEFT JOIN sops s ON s.id = t.sop_id AND s.deleted_at IS NULL
+		WHERE t.batch_id = ? AND t.deleted_at IS NULL
+		GROUP BY t.sop_id, t.scene_name, t.subscene_name, s.slug, s.version
+		ORDER BY sop_label ASC, scene_name ASC, subscene_name ASC
+	`
+	items := []dashboardBatchTaskSummaryItem{}
+	if err := h.db.Select(&items, query, id); err != nil {
+		logger.Printf("[DASHBOARD] batch task summary query failed: %v", err)
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to get batch task summary"})
+		return
+	}
+	for i := range items {
+		items[i].Statuses = map[string]int64{
+			"pending":     items[i].Pending,
+			"ready":       items[i].Ready,
+			"in_progress": items[i].InProgress,
+			"completed":   items[i].Completed,
+			"failed":      items[i].Failed,
+			"cancelled":   items[i].Cancelled,
+		}
+	}
+
+	c.JSON(http.StatusOK, dashboardBatchTaskSummaryResponse{
+		BatchID: strconv.FormatInt(id, 10),
+		Items:   items,
+	})
+}
+
+func parseProductionDashboardQuery(c *gin.Context) (productionDashboardQuery, error) {
+	workstationID, err := parseOptionalPositiveIDQuery(c, "workstation_id")
+	if err != nil {
+		return productionDashboardQuery{}, err
+	}
+	factoryID, err := parseOptionalPositiveIDQuery(c, "factory_id")
+	if err != nil {
+		return productionDashboardQuery{}, err
+	}
+	orgID, err := parseOptionalPositiveIDQuery(c, "organization_id")
+	if err != nil {
+		return productionDashboardQuery{}, err
+	}
+	trendDays, err := parseBoundedIntQuery(c, "trend_days", defaultDashboardTrendDays, 1, maxDashboardTrendDays)
+	if err != nil {
+		return productionDashboardQuery{}, err
+	}
+	distributionLimit, err := parseBoundedIntQuery(c, "distribution_limit", defaultDashboardDistributionLimit, 1, maxDashboardDistributionLimit)
+	if err != nil {
+		return productionDashboardQuery{}, err
+	}
+	activeLimit, err := parseBoundedIntQuery(c, "active_limit", defaultDashboardActiveLimit, 1, maxDashboardActiveLimit)
+	if err != nil {
+		return productionDashboardQuery{}, err
+	}
+	timezoneOffset, err := parseStatsTimezoneOffset(c.Query("timezone_offset"))
+	if err != nil {
+		return productionDashboardQuery{}, err
+	}
+
+	return productionDashboardQuery{
+		WorkstationID:     workstationID,
+		FactoryID:         factoryID,
+		OrganizationID:    orgID,
+		TrendDays:         trendDays,
+		DistributionLimit: distributionLimit,
+		ActiveLimit:       activeLimit,
+		TimezoneOffset:    timezoneOffset,
+	}, nil
+}
+
+func parseOptionalPositiveIDQuery(c *gin.Context, key string) (string, error) {
+	raw := strings.TrimSpace(c.Query(key))
+	if raw == "" {
+		return "", nil
+	}
+	id, err := strconv.ParseInt(raw, 10, 64)
+	if err != nil || id <= 0 {
+		return "", fmt.Errorf("%s must be a positive integer", key)
+	}
+	return strconv.FormatInt(id, 10), nil
+}
+
+func parseBoundedIntQuery(c *gin.Context, key string, fallback int, minValue int, maxValue int) (int, error) {
+	raw := strings.TrimSpace(c.Query(key))
+	if raw == "" {
+		return fallback, nil
+	}
+	value, err := strconv.Atoi(raw)
+	if err != nil || value < minValue {
+		return 0, fmt.Errorf("%s must be a positive integer", key)
+	}
+	if value > maxValue {
+		value = maxValue
+	}
+	return value, nil
+}
+
+func (h *ProductionDashboardHandler) resolveProductionDashboardScope(c *gin.Context, claims *auth.Claims, q productionDashboardQuery) (productionDashboardScope, error) {
+	scope := productionDashboardScope{
+		Role:           claims.Role,
+		WorkstationID:  q.WorkstationID,
+		FactoryID:      q.FactoryID,
+		OrganizationID: q.OrganizationID,
+		collectorID:    claims.CollectorID,
+	}
+
+	switch claims.Role {
+	case "admin":
+		return scope, nil
+	case "data_collector":
+		var workstationID string
+		err := h.db.GetContext(c.Request.Context(), &workstationID, `
+			SELECT CAST(id AS CHAR)
+			FROM workstations
+			WHERE data_collector_id = ? AND deleted_at IS NULL
+			LIMIT 1
+		`, claims.CollectorID)
+		if err == sql.ErrNoRows {
+			scope.WorkstationID = ""
+			scope.Warning = "workstation not assigned"
+			scope.empty = true
+			return scope, nil
+		}
+		if err != nil {
+			return productionDashboardScope{}, err
+		}
+		scope.WorkstationID = workstationID
+		scope.FactoryID = ""
+		scope.OrganizationID = ""
+		return scope, nil
+	default:
+		return productionDashboardScope{}, fmt.Errorf("unsupported role")
+	}
+}
+
+func emptyProductionDashboardSnapshot(scope productionDashboardScope) productionDashboardSnapshotResponse {
+	return productionDashboardSnapshotResponse{
+		GeneratedAt: time.Now().UTC().Format(time.RFC3339),
+		Scope:       scope,
+		Trend:       []dashboardTrendItem{},
+		Distributions: dashboardDistributions{
+			Scene: []dashboardDistributionItem{},
+			SOP:   []dashboardDistributionItem{},
+		},
+		Stations:      []dashboardStationItem{},
+		ActiveBatches: []dashboardActiveBatchItem{},
+		ActiveTasks:   []dashboardActiveTaskItem{},
+	}
+}
+
+func (h *ProductionDashboardHandler) dashboardTaskCounts(db dashboardDB, scope productionDashboardScope) (dashboardTaskCounts, error) {
+	conditions := []string{"t.deleted_at IS NULL"}
+	args := []interface{}{}
+	conditions, args = appendDashboardTaskScope(conditions, args, scope)
+	query := `
+		SELECT
+			COUNT(1) AS total,
+			COALESCE(SUM(CASE WHEN t.status = 'completed' THEN 1 ELSE 0 END), 0) AS completed,
+			COALESCE(SUM(CASE WHEN t.status = 'in_progress' THEN 1 ELSE 0 END), 0) AS in_progress,
+			COALESCE(SUM(CASE WHEN t.status = 'pending' THEN 1 ELSE 0 END), 0) AS pending,
+			COALESCE(SUM(CASE WHEN t.status = 'ready' THEN 1 ELSE 0 END), 0) AS ready,
+			COALESCE(SUM(CASE WHEN t.status = 'failed' THEN 1 ELSE 0 END), 0) AS failed,
+			COALESCE(SUM(CASE WHEN t.status = 'cancelled' THEN 1 ELSE 0 END), 0) AS cancelled
+		FROM tasks t
+		WHERE ` + strings.Join(conditions, " AND ")
+
+	var row dashboardTaskCounts
+	return row, db.Get(&row, query, args...)
+}
+
+func (h *ProductionDashboardHandler) dashboardTaskTrend(db dashboardDB, scope productionDashboardScope, q productionDashboardQuery) ([]dashboardTrendItem, error) {
+	location := fixedZoneFromOffset(q.TimezoneOffset)
+	endLocal := time.Now().In(location).AddDate(0, 0, 1)
+	endLocal = time.Date(endLocal.Year(), endLocal.Month(), endLocal.Day(), 0, 0, 0, 0, location)
+	startLocal := endLocal.AddDate(0, 0, -q.TrendDays)
+	startUTC := startLocal.UTC()
+	endUTC := endLocal.UTC()
+
+	eventTimeExpr := "COALESCE(t.assigned_at, t.started_at, t.completed_at, t.created_at)"
+	localEventExpr := "COALESCE(CONVERT_TZ(" + eventTimeExpr + ", @@session.time_zone, ?), " + eventTimeExpr + ")"
+	conditions := []string{"t.deleted_at IS NULL", eventTimeExpr + " >= ?", eventTimeExpr + " < ?"}
+	args := []interface{}{q.TimezoneOffset, startUTC, endUTC}
+	conditions, args = appendDashboardTaskScope(conditions, args, scope)
+
+	query := `
+		SELECT
+			DATE_FORMAT(` + localEventExpr + `, '%m-%d') AS date,
+			COALESCE(SUM(CASE WHEN t.status = 'completed' THEN 1 ELSE 0 END), 0) AS completed,
+			COALESCE(SUM(CASE WHEN t.status = 'in_progress' THEN 1 ELSE 0 END), 0) AS in_progress,
+			COALESCE(SUM(CASE WHEN t.status IN ('pending', 'ready') THEN 1 ELSE 0 END), 0) AS pending
+		FROM tasks t
+		WHERE ` + strings.Join(conditions, " AND ") + `
+		GROUP BY date
+		ORDER BY MIN(` + eventTimeExpr + `) ASC
+	`
+	rows := []dashboardTrendItem{}
+	if err := db.Select(&rows, query, args...); err != nil {
+		return nil, err
+	}
+
+	byDate := make(map[string]dashboardTrendItem, len(rows))
+	for _, row := range rows {
+		byDate[row.Date] = row
+	}
+	items := make([]dashboardTrendItem, 0, q.TrendDays)
+	for day := startLocal; day.Before(endLocal); day = day.AddDate(0, 0, 1) {
+		label := day.Format("01-02")
+		item, ok := byDate[label]
+		if !ok {
+			item = dashboardTrendItem{Date: label}
+		}
+		items = append(items, item)
+	}
+	return items, nil
+}
+
+func (h *ProductionDashboardHandler) dashboardTaskDistribution(db dashboardDB, scope productionDashboardScope, dimension string, limit int) ([]dashboardDistributionItem, error) {
+	idExpr := "COALESCE(CAST(t.scene_id AS CHAR), '')"
+	nameExpr := "COALESCE(NULLIF(TRIM(t.scene_name), ''), '未分类')"
+	joinSQL := ""
+	if dimension == "sop" {
+		idExpr = "COALESCE(CAST(t.sop_id AS CHAR), '')"
+		nameExpr = dashboardSOPLabelSQL("t.sop_id", "s.slug", "s.version")
+		joinSQL = "LEFT JOIN sops s ON s.id = t.sop_id AND s.deleted_at IS NULL"
+	}
+
+	conditions := []string{"t.deleted_at IS NULL"}
+	args := []interface{}{}
+	conditions, args = appendDashboardTaskScope(conditions, args, scope)
+	query := `
+		SELECT
+			` + idExpr + ` AS id,
+			COALESCE(NULLIF(MAX(` + nameExpr + `), ''), '未分类') AS name,
+			COUNT(1) AS value
+		FROM tasks t
+		` + joinSQL + `
+		WHERE ` + strings.Join(conditions, " AND ") + `
+		GROUP BY ` + idExpr + `
+		ORDER BY value DESC, name ASC
+		LIMIT ?
+	`
+	args = append(args, limit)
+	items := []dashboardDistributionItem{}
+	return items, db.Select(&items, query, args...)
+}
+
+func (h *ProductionDashboardHandler) dashboardQuality(db dashboardDB, scope productionDashboardScope) (dashboardQuality, float64, error) {
+	conditions := []string{"e.deleted_at IS NULL"}
+	args := []interface{}{}
+	conditions, args = appendDashboardEpisodeScope(conditions, args, scope)
+	query := `
+		SELECT
+			COALESCE(SUM(CASE WHEN e.qa_status <> 'pending_qa' THEN 1 ELSE 0 END), 0) AS total_inspected,
+			COALESCE(SUM(CASE WHEN e.qa_status IN ('approved', 'inspector_approved') THEN 1 ELSE 0 END), 0) AS passed,
+			COALESCE(SUM(CASE WHEN e.qa_status = 'rejected' THEN 1 ELSE 0 END), 0) AS failed,
+			COALESCE(SUM(CASE WHEN e.qa_status = 'needs_inspection' THEN 1 ELSE 0 END), 0) AS inspecting,
+			COALESCE(SUM(CASE WHEN e.qa_status = 'pending_qa' THEN 1 ELSE 0 END), 0) AS pending_qa,
+			COALESCE(SUM(COALESCE(e.duration_sec, 0)), 0) AS total_duration_sec
+		FROM episodes e
+		WHERE ` + strings.Join(conditions, " AND ")
+
+	var row dashboardQualityRow
+	if err := db.Get(&row, query, args...); err != nil {
+		return dashboardQuality{}, 0, err
+	}
+	inspected := nullInt64(row.TotalInspected)
+	passed := nullInt64(row.Passed)
+	passRate := 0.0
+	if inspected > 0 {
+		passRate = math.Round((float64(passed)/float64(inspected))*1000) / 10
+	}
+	return dashboardQuality{
+		PassRate:       passRate,
+		TotalInspected: inspected,
+		Passed:         passed,
+		Failed:         nullInt64(row.Failed),
+		Inspecting:     nullInt64(row.Inspecting),
+		PendingQA:      nullInt64(row.PendingQA),
+	}, nullFloat64(row.TotalDurationSec), nil
+}
+
+func (h *ProductionDashboardHandler) dashboardStations(db dashboardDB, scope productionDashboardScope) ([]dashboardStationItem, error) {
+	conditions := []string{"ws.deleted_at IS NULL"}
+	args := []interface{}{}
+	conditions, args = appendDashboardStationScope(conditions, args, scope)
+	query := `
+		SELECT
+			CAST(ws.id AS CHAR) AS id,
+			COALESCE(ws.status, '') AS status,
+			COALESCE(ws.collector_operator_id, '') AS collector_operator_id,
+			COALESCE(ws.collector_name, '') AS collector_name,
+			COALESCE(ws.robot_serial, '') AS device_id,
+			COALESCE(ws.robot_name, '') AS device_model
+		FROM workstations ws
+		WHERE ` + strings.Join(conditions, " AND ") + `
+		ORDER BY
+			CASE ws.status
+				WHEN 'active' THEN 0
+				WHEN 'inactive' THEN 1
+				WHEN 'break' THEN 2
+				WHEN 'offline' THEN 3
+				ELSE 9
+			END ASC,
+			ws.id ASC
+	`
+	items := []dashboardStationItem{}
+	if err := db.Select(&items, query, args...); err != nil {
+		return nil, err
+	}
+	for i := range items {
+		items[i].StatusText = dashboardStationStatusText(items[i].Status)
+	}
+	return items, nil
+}
+
+func (h *ProductionDashboardHandler) dashboardOperatingDays(db dashboardDB, scope productionDashboardScope) (int64, error) {
+	conditions := []string{"t.deleted_at IS NULL"}
+	args := []interface{}{}
+	conditions, args = appendDashboardTaskScope(conditions, args, scope)
+	query := `
+		SELECT COALESCE(TIMESTAMPDIFF(DAY, MIN(t.created_at), UTC_TIMESTAMP()) + 1, 0)
+		FROM tasks t
+		WHERE ` + strings.Join(conditions, " AND ")
+	var days sql.NullInt64
+	if err := db.Get(&days, query, args...); err != nil {
+		return 0, err
+	}
+	value := nullInt64(days)
+	if value < 0 {
+		return 0, nil
+	}
+	return value, nil
+}
+
+func (h *ProductionDashboardHandler) dashboardActiveBatches(db dashboardDB, scope productionDashboardScope, limit int) ([]dashboardActiveBatchItem, error) {
+	query, args := buildDashboardActiveBatchesQuery(scope, limit)
+	items := []dashboardActiveBatchItem{}
+	return items, db.Select(&items, query, args...)
+}
+
+func buildDashboardActiveBatchesQuery(scope productionDashboardScope, limit int) (string, []interface{}) {
+	conditions := []string{"b.deleted_at IS NULL", "b.status = 'active'"}
+	args := []interface{}{}
+	conditions, args = appendDashboardBatchScope(conditions, args, scope)
+	query := `
+		WITH active_batches AS (
+			SELECT
+				b.id,
+				b.batch_id,
+				b.order_id,
+				b.workstation_id,
+				b.started_at,
+				b.updated_at,
+				b.created_at
+			FROM batches b
+			LEFT JOIN workstations ws ON ws.id = b.workstation_id AND ws.deleted_at IS NULL
+			WHERE ` + strings.Join(conditions, " AND ") + `
+			ORDER BY COALESCE(b.started_at, b.updated_at, b.created_at) DESC, b.id DESC
+			LIMIT ?
+		)
+		SELECT
+			CAST(b.id AS CHAR) AS id,
+			COALESCE(b.batch_id, '') AS batch_id,
+			COALESCE(CAST(b.order_id AS CHAR), '') AS order_id,
+			COALESCE(o.name, '') AS order_name,
+			COALESCE(sc.name, '') AS scene_name,
+			COALESCE(CAST(b.workstation_id AS CHAR), '') AS workstation_id,
+			COALESCE(ws.robot_serial, '') AS device_id,
+			COALESCE(ws.collector_operator_id, '') AS collector_operator_id,
+			COALESCE(ws.collector_name, '') AS collector_name,
+			COALESCE(tc.task_count, 0) AS task_count,
+			COALESCE(tc.completed_count, 0) AS completed_count,
+			COALESCE(tc.failed_count, 0) AS failed_count,
+			COALESCE(tc.cancelled_count, 0) AS cancelled_count
+		FROM active_batches b
+		LEFT JOIN orders o ON o.id = b.order_id AND o.deleted_at IS NULL
+		LEFT JOIN scenes sc ON sc.id = o.scene_id AND sc.deleted_at IS NULL
+		LEFT JOIN workstations ws ON ws.id = b.workstation_id AND ws.deleted_at IS NULL
+		LEFT JOIN (
+			SELECT
+				ab.id AS batch_id,
+				COUNT(t.id) AS task_count,
+				COALESCE(SUM(CASE WHEN t.status = 'completed' THEN 1 ELSE 0 END), 0) AS completed_count,
+				COALESCE(SUM(CASE WHEN t.status = 'failed' THEN 1 ELSE 0 END), 0) AS failed_count,
+				COALESCE(SUM(CASE WHEN t.status = 'cancelled' THEN 1 ELSE 0 END), 0) AS cancelled_count
+			FROM active_batches ab
+			LEFT JOIN tasks t ON t.batch_id = ab.id AND t.deleted_at IS NULL
+			GROUP BY ab.id
+		) tc ON tc.batch_id = b.id
+		ORDER BY COALESCE(b.started_at, b.updated_at, b.created_at) DESC, b.id DESC
+	`
+	args = append(args, limit)
+	return query, args
+}
+
+func (h *ProductionDashboardHandler) dashboardActiveTasks(db dashboardDB, scope productionDashboardScope, limit int) ([]dashboardActiveTaskItem, error) {
+	conditions := []string{"t.deleted_at IS NULL", "t.status = 'in_progress'"}
+	args := []interface{}{}
+	conditions, args = appendDashboardTaskScope(conditions, args, scope)
+	query := `
+		SELECT
+			COALESCE(t.task_id, CAST(t.id AS CHAR)) AS id,
+			COALESCE(CAST(t.sop_id AS CHAR), '') AS sop_id,
+			` + dashboardSOPLabelSQL("t.sop_id", "s.slug", "s.version") + ` AS sop_label,
+			CASE
+				WHEN NULLIF(TRIM(COALESCE(t.scene_name, '')), '') IS NOT NULL
+					AND NULLIF(TRIM(COALESCE(t.subscene_name, '')), '') IS NOT NULL
+					THEN CONCAT(t.scene_name, '@', t.subscene_name)
+				ELSE COALESCE(NULLIF(TRIM(t.scene_name), ''), NULLIF(TRIM(t.subscene_name), ''), '-')
+			END AS scene_full,
+			COALESCE(ws.robot_serial, '') AS device_id,
+			COALESCE(ws.collector_operator_id, '') AS collector_operator_id,
+			COALESCE(ws.collector_name, '') AS collector_name
+		FROM tasks t
+		LEFT JOIN sops s ON s.id = t.sop_id AND s.deleted_at IS NULL
+		LEFT JOIN workstations ws ON ws.id = t.workstation_id AND ws.deleted_at IS NULL
+		WHERE ` + strings.Join(conditions, " AND ") + `
+		ORDER BY COALESCE(t.started_at, t.assigned_at, t.updated_at, t.created_at) DESC, t.id DESC
+		LIMIT ?
+	`
+	args = append(args, limit)
+	items := []dashboardActiveTaskItem{}
+	return items, db.Select(&items, query, args...)
+}
+
+func appendDashboardTaskScope(conditions []string, args []interface{}, scope productionDashboardScope) ([]string, []interface{}) {
+	if scope.Role == "data_collector" {
+		conditions = append(conditions, `EXISTS (
+			SELECT 1 FROM workstations ws_scope
+			WHERE ws_scope.id = t.workstation_id
+				AND ws_scope.data_collector_id = ?
+				AND ws_scope.deleted_at IS NULL
+		)`)
+		args = append(args, scope.collectorID)
+		return conditions, args
+	}
+	if scope.WorkstationID != "" {
+		conditions = append(conditions, "CAST(t.workstation_id AS CHAR) = ?")
+		args = append(args, scope.WorkstationID)
+	}
+	if scope.FactoryID != "" {
+		conditions = append(conditions, "CAST(t.factory_id AS CHAR) = ?")
+		args = append(args, scope.FactoryID)
+	}
+	if scope.OrganizationID != "" {
+		conditions = append(conditions, "CAST(t.organization_id AS CHAR) = ?")
+		args = append(args, scope.OrganizationID)
+	}
+	return conditions, args
+}
+
+func appendDashboardEpisodeScope(conditions []string, args []interface{}, scope productionDashboardScope) ([]string, []interface{}) {
+	if scope.Role == "data_collector" {
+		conditions = append(conditions, `EXISTS (
+			SELECT 1 FROM workstations ws_scope
+			WHERE ws_scope.id = e.workstation_id
+				AND ws_scope.data_collector_id = ?
+				AND ws_scope.deleted_at IS NULL
+		)`)
+		args = append(args, scope.collectorID)
+		return conditions, args
+	}
+	if scope.WorkstationID != "" {
+		conditions = append(conditions, "CAST(e.workstation_id AS CHAR) = ?")
+		args = append(args, scope.WorkstationID)
+	}
+	if scope.FactoryID != "" {
+		conditions = append(conditions, "CAST(e.factory_id AS CHAR) = ?")
+		args = append(args, scope.FactoryID)
+	}
+	if scope.OrganizationID != "" {
+		conditions = append(conditions, "CAST(e.organization_id AS CHAR) = ?")
+		args = append(args, scope.OrganizationID)
+	}
+	return conditions, args
+}
+
+func appendDashboardStationScope(conditions []string, args []interface{}, scope productionDashboardScope) ([]string, []interface{}) {
+	if scope.Role == "data_collector" {
+		conditions = append(conditions, "ws.data_collector_id = ?")
+		args = append(args, scope.collectorID)
+		return conditions, args
+	}
+	if scope.WorkstationID != "" {
+		conditions = append(conditions, "CAST(ws.id AS CHAR) = ?")
+		args = append(args, scope.WorkstationID)
+	}
+	if scope.FactoryID != "" {
+		conditions = append(conditions, "CAST(ws.factory_id AS CHAR) = ?")
+		args = append(args, scope.FactoryID)
+	}
+	if scope.OrganizationID != "" {
+		conditions = append(conditions, "CAST(ws.organization_id AS CHAR) = ?")
+		args = append(args, scope.OrganizationID)
+	}
+	return conditions, args
+}
+
+func appendDashboardBatchScope(conditions []string, args []interface{}, scope productionDashboardScope) ([]string, []interface{}) {
+	if scope.Role == "data_collector" {
+		conditions = append(conditions, "ws.data_collector_id = ?")
+		args = append(args, scope.collectorID)
+		return conditions, args
+	}
+	if scope.WorkstationID != "" {
+		conditions = append(conditions, "CAST(b.workstation_id AS CHAR) = ?")
+		args = append(args, scope.WorkstationID)
+	}
+	if scope.FactoryID != "" {
+		conditions = append(conditions, "CAST(ws.factory_id AS CHAR) = ?")
+		args = append(args, scope.FactoryID)
+	}
+	if scope.OrganizationID != "" {
+		conditions = append(conditions, "CAST(b.organization_id AS CHAR) = ?")
+		args = append(args, scope.OrganizationID)
+	}
+	return conditions, args
+}
+
+func dashboardSOPLabelSQL(sopIDExpr string, slugExpr string, versionExpr string) string {
+	return `CASE
+		WHEN ` + sopIDExpr + ` IS NULL THEN '未分类'
+		WHEN NULLIF(` + slugExpr + `, '') IS NULL THEN CONCAT('SOP #', CAST(` + sopIDExpr + ` AS CHAR))
+		WHEN NULLIF(` + versionExpr + `, '') IS NULL THEN ` + slugExpr + `
+		ELSE CONCAT(` + slugExpr + `, '@', ` + versionExpr + `)
+	END`
+}
+
+func dashboardStationStatusText(status string) string {
+	switch status {
+	case "active":
+		return "在线"
+	case "inactive":
+		return "待命中"
+	case "break":
+		return "休息中"
+	case "offline":
+		return "离线"
+	default:
+		return status
+	}
+}
+
+func countOnlineDashboardStations(stations []dashboardStationItem) int64 {
+	var count int64
+	for _, station := range stations {
+		if station.Status == "active" {
+			count++
+		}
+	}
+	return count
+}
+
+func fixedZoneFromOffset(offset string) *time.Location {
+	if len(offset) != 6 {
+		return time.UTC
+	}
+	sign := 1
+	if offset[0] == '-' {
+		sign = -1
+	}
+	hours, _ := strconv.Atoi(offset[1:3])
+	minutes, _ := strconv.Atoi(offset[4:6])
+	return time.FixedZone(offset, sign*((hours*60+minutes)*60))
+}
+
+func nullFloat64(v sql.NullFloat64) float64 {
+	if !v.Valid {
+		return 0
+	}
+	return v.Float64
+}
diff --git a/internal/api/handlers/production_dashboard_test.go b/internal/api/handlers/production_dashboard_test.go
new file mode 100644
index 0000000..545794d
--- /dev/null
+++ b/internal/api/handlers/production_dashboard_test.go
@@ -0,0 +1,138 @@
+// SPDX-FileCopyrightText: 2026 ArcheBase
+//
+// SPDX-License-Identifier: MulanPSL-2.0
+
+package handlers
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+)
+
+func TestParseProductionDashboardQueryDefaultsAndBounds(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	req := httptest.NewRequest(http.MethodGet, "/dashboard/snapshot?workstation_id=12&factory_id=34&organization_id=56&trend_days=99&distribution_limit=999&active_limit=999&timezone_offset=%2B08:00", nil)
+	c, _ := gin.CreateTestContext(httptest.NewRecorder())
+	c.Request = req
+
+	got, err := parseProductionDashboardQuery(c)
+	if err != nil {
+		t.Fatalf("parseProductionDashboardQuery returned error: %v", err)
+	}
+	if got.WorkstationID != "12" || got.FactoryID != "34" || got.OrganizationID != "56" {
+		t.Fatalf("unexpected scope filters: %+v", got)
+	}
+	if got.TrendDays != maxDashboardTrendDays {
+		t.Fatalf("trend days = %d, want %d", got.TrendDays, maxDashboardTrendDays)
+	}
+	if got.DistributionLimit != maxDashboardDistributionLimit {
+		t.Fatalf("distribution limit = %d, want %d", got.DistributionLimit, maxDashboardDistributionLimit)
+	}
+	if got.ActiveLimit != maxDashboardActiveLimit {
+		t.Fatalf("active limit = %d, want %d", got.ActiveLimit, maxDashboardActiveLimit)
+	}
+	if got.TimezoneOffset != "+08:00" {
+		t.Fatalf("timezone offset = %q, want +08:00", got.TimezoneOffset)
+	}
+}
+
+func TestParseProductionDashboardQueryValidation(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	tests := []string{
+		"/dashboard/snapshot?workstation_id=0",
+		"/dashboard/snapshot?trend_days=0",
+		"/dashboard/snapshot?timezone_offset=08:00",
+	}
+
+	for _, target := range tests {
+		t.Run(target, func(t *testing.T) {
+			c, _ := gin.CreateTestContext(httptest.NewRecorder())
+			c.Request = httptest.NewRequest(http.MethodGet, target, nil)
+			if _, err := parseProductionDashboardQuery(c); err == nil {
+				t.Fatalf("expected validation error")
+			}
+		})
+	}
+}
+
+func TestDashboardSOPLabelSQL(t *testing.T) {
+	got := dashboardSOPLabelSQL("t.sop_id", "s.slug", "s.version")
+	for _, want := range []string{
+		"WHEN t.sop_id IS NULL THEN '未分类'",
+		"CONCAT('SOP #', CAST(t.sop_id AS CHAR))",
+		"ELSE CONCAT(s.slug, '@', s.version)",
+	} {
+		if !strings.Contains(got, want) {
+			t.Fatalf("SOP label SQL should contain %q: %s", want, got)
+		}
+	}
+}
+
+func TestDashboardTaskScopeUsesCollectorAssignment(t *testing.T) {
+	conditions, args := appendDashboardTaskScope(
+		[]string{"t.deleted_at IS NULL"},
+		nil,
+		productionDashboardScope{
+			Role:           "data_collector",
+			WorkstationID:  "99",
+			FactoryID:      "88",
+			OrganizationID: "77",
+			collectorID:    42,
+		},
+	)
+
+	joined := strings.Join(conditions, " AND ")
+	if !strings.Contains(joined, "ws_scope.data_collector_id = ?") {
+		t.Fatalf("collector task scope should filter by collector assignment: %s", joined)
+	}
+	if strings.Contains(joined, "CAST(t.workstation_id AS CHAR)") || strings.Contains(joined, "CAST(t.factory_id AS CHAR)") {
+		t.Fatalf("collector task scope should ignore caller-supplied admin filters: %s", joined)
+	}
+	if len(args) != 1 || args[0] != int64(42) {
+		t.Fatalf("args = %#v, want collector id 42", args)
+	}
+}
+
+func TestDashboardActiveBatchesQueryLimitsBeforeTaskAggregation(t *testing.T) {
+	query, args := buildDashboardActiveBatchesQuery(
+		productionDashboardScope{
+			Role:        "data_collector",
+			collectorID: 42,
+		},
+		20,
+	)
+	compact := strings.Join(strings.Fields(query), " ")
+
+	for _, want := range []string{
+		"WITH active_batches AS",
+		"WHERE b.deleted_at IS NULL AND b.status = 'active' AND ws.data_collector_id = ?",
+		"ORDER BY COALESCE(b.started_at, b.updated_at, b.created_at) DESC, b.id DESC LIMIT ?",
+		"FROM active_batches ab LEFT JOIN tasks t ON t.batch_id = ab.id AND t.deleted_at IS NULL GROUP BY ab.id",
+	} {
+		if !strings.Contains(compact, want) {
+			t.Fatalf("active batch SQL should contain %q: %s", want, compact)
+		}
+	}
+	if strings.Contains(compact, "FROM tasks WHERE deleted_at IS NULL GROUP BY batch_id") {
+		t.Fatalf("active batch SQL should not globally aggregate tasks first: %s", compact)
+	}
+	if len(args) != 2 || args[0] != int64(42) || args[1] != 20 {
+		t.Fatalf("args = %#v, want collector id then limit", args)
+	}
+}
+
+func TestProductionDashboardRoutesCanRegister(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	router := gin.New()
+	group := router.Group("/production/dashboard")
+	handler := &ProductionDashboardHandler{}
+
+	handler.RegisterRoutes(group)
+}
diff --git a/internal/api/handlers/robot.go b/internal/api/handlers/robot.go
index ab1e6d6..a497a96 100644
--- a/internal/api/handlers/robot.go
+++ b/internal/api/handlers/robot.go
@@ -11,6 +11,7 @@ import (
 	"encoding/json"
 	"fmt"
 	"net/http"
+	"sort"
 	"strconv"
 	"strings"
 	"time"
@@ -39,17 +40,21 @@ func NewRobotHandler(db *sqlx.DB, recorderHub *services.RecorderHub, transferHub
 
 // RobotResponse represents a robot in the response.
 type RobotResponse struct {
-	ID          string      `json:"id"`
-	RobotTypeID string      `json:"robot_type_id"`
-	DeviceID    string      `json:"device_id"`
-	FactoryID   string      `json:"factory_id"`
-	AssetID     string      `json:"asset_id,omitempty"`
-	Status      string      `json:"status"`
-	Metadata    interface{} `json:"metadata,omitempty"`
-	CreatedAt   string      `json:"created_at,omitempty"`
-	UpdatedAt   string      `json:"updated_at,omitempty"`
-	Connected   bool        `json:"connected"`
-	ConnectedAt string      `json:"connected_at,omitempty"`
+	ID             string      `json:"id"`
+	RobotTypeID    string      `json:"robot_type_id"`
+	RobotTypeName  string      `json:"robot_type_name,omitempty"`
+	RobotTypeModel string      `json:"robot_type_model,omitempty"`
+	DeviceID       string      `json:"device_id"`
+	FactoryID      string      `json:"factory_id"`
+	FactoryName    string      `json:"factory_name,omitempty"`
+	FactorySlug    string      `json:"factory_slug,omitempty"`
+	AssetID        string      `json:"asset_id,omitempty"`
+	Status         string      `json:"status"`
+	Metadata       interface{} `json:"metadata,omitempty"`
+	CreatedAt      string      `json:"created_at,omitempty"`
+	UpdatedAt      string      `json:"updated_at,omitempty"`
+	Connected      bool        `json:"connected"`
+	ConnectedAt    string      `json:"connected_at,omitempty"`
 }
 
 // RobotListResponse represents the response for listing robots.
@@ -71,6 +76,8 @@ type DeviceConnectionResponse struct {
 	TransferConnected bool   `json:"transfer_connected"`
 }
 
+type robotConnectionSnapshot map[string]string
+
 // CreateRobotRequest represents the request body for creating a robot.
 type CreateRobotRequest struct {
 	RobotTypeID string      `json:"robot_type_id"`
@@ -105,15 +112,19 @@ func (h *RobotHandler) RegisterRoutes(apiV1 *gin.RouterGroup) {
 
 // robotRow represents a robot in the database
 type robotRow struct {
-	ID          int64          `db:"id"`
-	RobotTypeID int64          `db:"robot_type_id"`
-	DeviceID    string         `db:"device_id"`
-	FactoryID   int64          `db:"factory_id"`
-	AssetID     sql.NullString `db:"asset_id"`
-	Status      string         `db:"status"`
-	Metadata    sql.NullString `db:"metadata"`
-	CreatedAt   sql.NullTime   `db:"created_at"`
-	UpdatedAt   sql.NullTime   `db:"updated_at"`
+	ID             int64          `db:"id"`
+	RobotTypeID    int64          `db:"robot_type_id"`
+	RobotTypeName  sql.NullString `db:"robot_type_name"`
+	RobotTypeModel sql.NullString `db:"robot_type_model"`
+	DeviceID       string         `db:"device_id"`
+	FactoryID      int64          `db:"factory_id"`
+	FactoryName    sql.NullString `db:"factory_name"`
+	FactorySlug    sql.NullString `db:"factory_slug"`
+	AssetID        sql.NullString `db:"asset_id"`
+	Status         string         `db:"status"`
+	Metadata       sql.NullString `db:"metadata"`
+	CreatedAt      sql.NullTime   `db:"created_at"`
+	UpdatedAt      sql.NullTime   `db:"updated_at"`
 }
 
 func robotMetadataFromDB(ns sql.NullString) interface{} {
@@ -152,7 +163,70 @@ func (h *RobotHandler) connectionStateDetailed(deviceID string) (connected bool,
 	return true, t.UTC().Format(time.RFC3339), recorderConnected, transferConnected
 }
 
-func (h *RobotHandler) responseFromRow(r robotRow) RobotResponse {
+func (h *RobotHandler) connectionSnapshot() robotConnectionSnapshot {
+	snapshot := robotConnectionSnapshot{}
+	if h.recorderHub == nil || h.transferHub == nil {
+		return snapshot
+	}
+
+	transferByDeviceID := make(map[string]time.Time)
+	for _, device := range h.transferHub.ListDevices() {
+		deviceID := strings.TrimSpace(device.DeviceID)
+		if deviceID == "" {
+			continue
+		}
+		transferByDeviceID[deviceID] = device.ConnectedAt
+	}
+	if len(transferByDeviceID) == 0 {
+		return snapshot
+	}
+
+	for _, recorder := range h.recorderHub.ListDevices() {
+		deviceID := strings.TrimSpace(recorder.DeviceID)
+		if deviceID == "" {
+			continue
+		}
+		transferConnectedAt, ok := transferByDeviceID[deviceID]
+		if !ok {
+			continue
+		}
+		connectedAt := recorder.ConnectedAt
+		if transferConnectedAt.After(connectedAt) {
+			connectedAt = transferConnectedAt
+		}
+		snapshot[deviceID] = connectedAt.UTC().Format(time.RFC3339)
+	}
+	return snapshot
+}
+
+func (s robotConnectionSnapshot) deviceIDs() []string {
+	ids := make([]string, 0, len(s))
+	for deviceID := range s {
+		ids = append(ids, deviceID)
+	}
+	sort.Strings(ids)
+	return ids
+}
+
+func appendRobotDeviceConnectionFilter(whereClause string, args []interface{}, connected bool, connectedDeviceIDs []string) (string, []interface{}) {
+	if len(connectedDeviceIDs) == 0 {
+		return whereClause, args
+	}
+
+	placeholders := make([]string, 0, len(connectedDeviceIDs))
+	for _, deviceID := range connectedDeviceIDs {
+		placeholders = append(placeholders, "?")
+		args = append(args, deviceID)
+	}
+
+	operator := "NOT IN"
+	if connected {
+		operator = "IN"
+	}
+	return whereClause + " AND r.device_id " + operator + " (" + strings.Join(placeholders, ",") + ")", args
+}
+
+func robotResponseFromRow(r robotRow, connected bool, connectedAt string) RobotResponse {
 	createdAt := ""
 	if r.CreatedAt.Valid {
 		createdAt = r.CreatedAt.Time.UTC().Format(time.RFC3339)
@@ -165,20 +239,61 @@ func (h *RobotHandler) responseFromRow(r robotRow) RobotResponse {
 	if r.AssetID.Valid {
 		assetID = r.AssetID.String
 	}
-	connected, connectedAt := h.connectionState(r.DeviceID)
 	return RobotResponse{
-		ID:          fmt.Sprintf("%d", r.ID),
-		RobotTypeID: fmt.Sprintf("%d", r.RobotTypeID),
-		DeviceID:    r.DeviceID,
-		FactoryID:   fmt.Sprintf("%d", r.FactoryID),
-		AssetID:     assetID,
-		Status:      r.Status,
-		Metadata:    robotMetadataFromDB(r.Metadata),
-		CreatedAt:   createdAt,
-		UpdatedAt:   updatedAt,
-		Connected:   connected,
-		ConnectedAt: connectedAt,
+		ID:             fmt.Sprintf("%d", r.ID),
+		RobotTypeID:    fmt.Sprintf("%d", r.RobotTypeID),
+		RobotTypeName:  nullString(r.RobotTypeName),
+		RobotTypeModel: nullString(r.RobotTypeModel),
+		DeviceID:       r.DeviceID,
+		FactoryID:      fmt.Sprintf("%d", r.FactoryID),
+		FactoryName:    nullString(r.FactoryName),
+		FactorySlug:    nullString(r.FactorySlug),
+		AssetID:        assetID,
+		Status:         r.Status,
+		Metadata:       robotMetadataFromDB(r.Metadata),
+		CreatedAt:      createdAt,
+		UpdatedAt:      updatedAt,
+		Connected:      connected,
+		ConnectedAt:    connectedAt,
+	}
+}
+
+func (h *RobotHandler) responseFromRow(r robotRow) RobotResponse {
+	connected, connectedAt := h.connectionState(r.DeviceID)
+	return robotResponseFromRow(r, connected, connectedAt)
+}
+
+func responseFromRowWithConnectionSnapshot(r robotRow, snapshot robotConnectionSnapshot) RobotResponse {
+	connectedAt, connected := snapshot[strings.TrimSpace(r.DeviceID)]
+	return robotResponseFromRow(r, connected, connectedAt)
+}
+
+func parseConnectedFilter(raw string) (*bool, error) {
+	values, err := parseNonEmptyStringList(raw, "connected")
+	if err != nil {
+		return nil, err
+	}
+	if len(values) == 0 {
+		return nil, nil
+	}
+
+	seen := make(map[bool]struct{})
+	for _, value := range values {
+		connected, err := strconv.ParseBool(value)
+		if err != nil {
+			return nil, fmt.Errorf("invalid connected format")
+		}
+		seen[connected] = struct{}{}
+	}
+	if len(seen) != 1 {
+		return nil, nil
 	}
+
+	result := false
+	for connected := range seen {
+		result = connected
+	}
+	return &result, nil
 }
 
 // ListRobots handles robot listing requests with filtering.
@@ -188,14 +303,14 @@ func (h *RobotHandler) responseFromRow(r robotRow) RobotResponse {
 // @Tags         robots
 // @Accept       json
 // @Produce      json
-// @Param        factory_id    query     string  false  "Filter by factory id"
-// @Param        status        query     string  false  "Filter by status (active, maintenance, retired)"
-// @Param        robot_type_id query     string  false  "Filter by robot type id"
-// @Param        connected     query     string  false  "Filter by connection status (true/false)"
+// @Param        factory_id    query     string  false  "Filter by factory ID(s), comma-separated"
+// @Param        status        query     string  false  "Filter by status(es), comma-separated (active, maintenance, retired)"
+// @Param        robot_type_id query     string  false  "Filter by robot type ID(s), comma-separated"
+// @Param        connected     query     string  false  "Filter by connection status(es), comma-separated (true/false)"
+// @Param        device_id     query     string  false  "Filter by device ID(s), comma-separated"
 // @Param        keyword       query     string  false  "Search by device ID or asset ID"
 // @Param        q             query     string  false  "Alias of keyword"
 // @Param        search        query     string  false  "Alias of keyword"
-// @Param        device_id     query     string  false  "Alias of keyword for device ID search"
 // @Param        limit         query     int     false  "Max results (default 50, max 100)"
 // @Param        offset        query     int     false  "Pagination offset (default 0)"
 // @Success      200           {object}  RobotListResponse
@@ -209,49 +324,39 @@ func (h *RobotHandler) ListRobots(c *gin.Context) {
 		return
 	}
 
-	factoryID := c.Query("factory_id")
-	status := c.Query("status")
-	robotTypeID := c.Query("robot_type_id")
-	connectedParam := c.Query("connected")
-	keyword := firstNonEmptyQuery(c, "keyword", "q", "search", "device_id")
-
-	var connectedFilter *bool
-	if connectedParam != "" {
-		connected, err := strconv.ParseBool(connectedParam)
-		if err != nil {
-			c.JSON(http.StatusBadRequest, gin.H{"error": "invalid connected format"})
-			return
-		}
-		connectedFilter = &connected
+	factoryIDs, err := parsePositiveInt64List(c.Query("factory_id"), "factory_id")
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
 	}
-
-	whereClause := "WHERE r.deleted_at IS NULL"
-	args := []interface{}{}
-
-	if factoryID != "" {
-		parsedFactoryID, err := strconv.ParseInt(factoryID, 10, 64)
-		if err != nil {
-			c.JSON(http.StatusBadRequest, gin.H{"error": "invalid factory_id format"})
-			return
-		}
-		whereClause += " AND r.factory_id = ?"
-		args = append(args, parsedFactoryID)
+	robotTypeIDs, err := parsePositiveInt64List(c.Query("robot_type_id"), "robot_type_id")
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
 	}
-
-	if status != "" {
-		whereClause += " AND r.status = ?"
-		args = append(args, status)
+	connectedFilter, err := parseConnectedFilter(c.Query("connected"))
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
 	}
-
-	if robotTypeID != "" {
-		parsedRobotTypeID, err := strconv.ParseInt(robotTypeID, 10, 64)
-		if err != nil {
-			c.JSON(http.StatusBadRequest, gin.H{"error": "invalid robot_type_id format"})
-			return
-		}
-		whereClause += " AND r.robot_type_id = ?"
-		args = append(args, parsedRobotTypeID)
+	deviceIDs, err := parseNonEmptyStringList(c.Query("device_id"), "device_id")
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
 	}
+	statuses, err := parseNonEmptyStringList(c.Query("status"), "status")
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	keyword := firstNonEmptyQuery(c, "keyword", "q", "search")
+
+	whereClause := "WHERE r.deleted_at IS NULL"
+	args := []interface{}{}
+	whereClause, args = appendInt64InFilter(whereClause, args, "r.factory_id", factoryIDs)
+	whereClause, args = appendStringInFilter(whereClause, args, "r.device_id", deviceIDs)
+	whereClause, args = appendStringInFilter(whereClause, args, "r.status", statuses)
+	whereClause, args = appendInt64InFilter(whereClause, args, "r.robot_type_id", robotTypeIDs)
 
 	if keyword != "" {
 		likeKeyword := "%" + keyword + "%"
@@ -259,8 +364,25 @@ func (h *RobotHandler) ListRobots(c *gin.Context) {
 		args = append(args, likeKeyword, likeKeyword)
 	}
 
-	countQuery := "SELECT COUNT(*) FROM robots r " + whereClause
+	connectionSnapshot := h.connectionSnapshot()
+	if connectedFilter != nil {
+		connectedDeviceIDs := connectionSnapshot.deviceIDs()
+		if *connectedFilter && len(connectedDeviceIDs) == 0 {
+			c.JSON(http.StatusOK, RobotListResponse{
+				Items:   []RobotResponse{},
+				Total:   0,
+				Limit:   pagination.Limit,
+				Offset:  pagination.Offset,
+				HasNext: false,
+				HasPrev: pagination.Offset > 0,
+			})
+			return
+		}
+		whereClause, args = appendRobotDeviceConnectionFilter(whereClause, args, *connectedFilter, connectedDeviceIDs)
+	}
+
 	var total int
+	countQuery := "SELECT COUNT(*) FROM robots r " + whereClause
 	if err := h.db.Get(&total, countQuery, args...); err != nil {
 		logger.Printf("[ROBOT] Failed to count robots: %v", err)
 		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to list robots"})
@@ -270,21 +392,26 @@ func (h *RobotHandler) ListRobots(c *gin.Context) {
 	orderClause, orderArgs := keywordOrderBy(keyword, "r.id DESC", "r.device_id", "r.asset_id")
 	query := `
 		SELECT 
-			r.id,
-			r.robot_type_id,
-			r.device_id,
-			r.factory_id,
-			r.asset_id,
-			r.status,
-			r.metadata,
-			r.created_at,
-			r.updated_at
-		FROM robots r
-		` + whereClause + `
-		` + orderClause + `
-		LIMIT ? OFFSET ?
+				r.id,
+				r.robot_type_id,
+				rt.name AS robot_type_name,
+				rt.model AS robot_type_model,
+				r.device_id,
+				r.factory_id,
+				f.name AS factory_name,
+				f.slug AS factory_slug,
+				r.asset_id,
+				r.status,
+				r.metadata,
+				r.created_at,
+				r.updated_at
+			FROM robots r
+			LEFT JOIN robot_types rt ON rt.id = r.robot_type_id AND rt.deleted_at IS NULL
+			LEFT JOIN factories f ON f.id = r.factory_id AND f.deleted_at IS NULL
+				` + whereClause + `
+				` + orderClause + `
+				LIMIT ? OFFSET ?
 	`
-
 	queryArgs := append(args, orderArgs...)
 	queryArgs = append(queryArgs, pagination.Limit, pagination.Offset)
 
@@ -295,13 +422,9 @@ func (h *RobotHandler) ListRobots(c *gin.Context) {
 		return
 	}
 
-	robots := []RobotResponse{}
+	robots := make([]RobotResponse, 0, len(dbRows))
 	for _, r := range dbRows {
-		resp := h.responseFromRow(r)
-		if connectedFilter != nil && resp.Connected != *connectedFilter {
-			continue
-		}
-		robots = append(robots, resp)
+		robots = append(robots, responseFromRowWithConnectionSnapshot(r, connectionSnapshot))
 	}
 
 	hasNext := (pagination.Offset + pagination.Limit) < total
diff --git a/internal/api/handlers/robot_test.go b/internal/api/handlers/robot_test.go
new file mode 100644
index 0000000..02777b1
--- /dev/null
+++ b/internal/api/handlers/robot_test.go
@@ -0,0 +1,338 @@
+// SPDX-FileCopyrightText: 2026 ArcheBase
+//
+// SPDX-License-Identifier: MulanPSL-2.0
+
+package handlers
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"archebase.com/keystone-edge/internal/services"
+	"github.com/gin-gonic/gin"
+	"github.com/jmoiron/sqlx"
+	_ "modernc.org/sqlite"
+)
+
+func TestRobotHandlerListRobots_DeviceIDSearchSemantics(t *testing.T) {
+	db := newTestRobotHandlerDB(t)
+	defer db.Close()
+
+	now := time.Now().UTC()
+	stmts := []struct {
+		sql  string
+		args []any
+	}{
+		{sql: `INSERT INTO robots (id, robot_type_id, device_id, factory_id, asset_id, status, created_at, updated_at) VALUES (1, 10, 'wt1_robot_060', 30, 'asset-060', 'active', ?, ?)`, args: []any{now, now}},
+		{sql: `INSERT INTO robots (id, robot_type_id, device_id, factory_id, asset_id, status, created_at, updated_at) VALUES (2, 10, 'wt1_robot_120', 30, 'asset-120', 'active', ?, ?)`, args: []any{now, now}},
+	}
+	for _, stmt := range stmts {
+		if _, err := db.Exec(stmt.sql, stmt.args...); err != nil {
+			t.Fatalf("seed robot fixture failed: %v", err)
+		}
+	}
+
+	r := newTestRobotRouter(t, db)
+
+	tests := []struct {
+		name          string
+		path          string
+		wantDeviceIDs []string
+	}{
+		{
+			name:          "q partially matches device_id",
+			path:          "/api/v1/robots?q=060",
+			wantDeviceIDs: []string{"wt1_robot_060"},
+		},
+		{
+			name:          "device_id requires exact match",
+			path:          "/api/v1/robots?device_id=wt1_robot_060",
+			wantDeviceIDs: []string{"wt1_robot_060"},
+		},
+		{
+			name:          "partial device_id does not match",
+			path:          "/api/v1/robots?device_id=060",
+			wantDeviceIDs: nil,
+		},
+		{
+			name:          "device_id exact filter is combined with keyword search",
+			path:          "/api/v1/robots?q=060&search=060&device_id=060",
+			wantDeviceIDs: nil,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			req := httptest.NewRequest(http.MethodGet, tt.path, nil)
+			w := httptest.NewRecorder()
+			r.ServeHTTP(w, req)
+
+			if w.Code != http.StatusOK {
+				t.Fatalf("status=%d want=%d body=%s", w.Code, http.StatusOK, w.Body.String())
+			}
+
+			var resp RobotListResponse
+			if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+				t.Fatalf("unmarshal response: %v body=%s", err, w.Body.String())
+			}
+			if resp.Total != len(tt.wantDeviceIDs) || len(resp.Items) != len(tt.wantDeviceIDs) {
+				t.Fatalf("unexpected filtered response: %#v", resp)
+			}
+			for i, wantDeviceID := range tt.wantDeviceIDs {
+				if resp.Items[i].DeviceID != wantDeviceID {
+					t.Fatalf("item[%d].DeviceID=%q want=%q item=%#v", i, resp.Items[i].DeviceID, wantDeviceID, resp.Items[i])
+				}
+			}
+		})
+	}
+}
+
+func TestRobotHandlerListRobotsIncludesDisplayLabels(t *testing.T) {
+	db := newTestRobotHandlerDB(t)
+	defer db.Close()
+
+	if _, err := db.Exec(`INSERT INTO robot_types (id, name, model, deleted_at) VALUES (51, 'Arm Type 51', 'Model-51', NULL)`); err != nil {
+		t.Fatalf("seed robot type fixture failed: %v", err)
+	}
+	if _, err := db.Exec(`INSERT INTO factories (id, name, slug, deleted_at) VALUES (81, 'Factory 81', 'fac-81', NULL)`); err != nil {
+		t.Fatalf("seed factory fixture failed: %v", err)
+	}
+	if _, err := db.Exec(`INSERT INTO robots (id, robot_type_id, device_id, factory_id, status) VALUES (1, 51, 'label_robot', 81, 'active')`); err != nil {
+		t.Fatalf("seed robot fixture failed: %v", err)
+	}
+
+	r := newTestRobotRouter(t, db)
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/robots", nil)
+	w := httptest.NewRecorder()
+	r.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status=%d want=%d body=%s", w.Code, http.StatusOK, w.Body.String())
+	}
+
+	var resp RobotListResponse
+	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("unmarshal response: %v body=%s", err, w.Body.String())
+	}
+	if len(resp.Items) != 1 {
+		t.Fatalf("items=%#v, want one item", resp.Items)
+	}
+	got := resp.Items[0]
+	if got.RobotTypeModel != "Model-51" || got.RobotTypeName != "Arm Type 51" {
+		t.Fatalf("unexpected robot type labels: %#v", got)
+	}
+	if got.FactoryName != "Factory 81" || got.FactorySlug != "fac-81" {
+		t.Fatalf("unexpected factory labels: %#v", got)
+	}
+}
+
+func TestRobotHandlerListRobotsRejectsOversizedMultiValueFilter(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	r := gin.New()
+	NewRobotHandler(nil, nil, nil).RegisterRoutes(r.Group("/api/v1"))
+
+	req := httptest.NewRequest(
+		http.MethodGet,
+		"/api/v1/robots?device_id="+joinedStringList("robot", maxMultiValueFilterItems+1),
+		nil,
+	)
+	w := httptest.NewRecorder()
+	r.ServeHTTP(w, req)
+
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("status=%d want=%d body=%s", w.Code, http.StatusBadRequest, w.Body.String())
+	}
+}
+
+func TestRobotHandlerListRobots_ConnectedFilterUsesSQLLimit(t *testing.T) {
+	db := newTestRobotHandlerDB(t)
+	defer db.Close()
+
+	now := time.Now().UTC()
+	stmts := []struct {
+		sql  string
+		args []any
+	}{
+		{sql: `INSERT INTO robots (id, robot_type_id, device_id, factory_id, status, created_at, updated_at) VALUES (1, 10, 'older_robot', 30, 'active', ?, ?)`, args: []any{now, now}},
+		{sql: `INSERT INTO robots (id, robot_type_id, device_id, factory_id, status, created_at, updated_at) VALUES (2, 10, 'page_external_robot', 30, 'active', 'not-a-time', 'not-a-time')`},
+		{sql: `INSERT INTO robots (id, robot_type_id, device_id, factory_id, status, created_at, updated_at) VALUES (3, 10, 'newest_robot', 30, 'active', ?, ?)`, args: []any{now, now}},
+	}
+	for _, stmt := range stmts {
+		if _, err := db.Exec(stmt.sql, stmt.args...); err != nil {
+			t.Fatalf("seed robot fixture failed: %v", err)
+		}
+	}
+
+	r := newTestRobotRouter(t, db)
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/robots?connected=false&limit=1", nil)
+	w := httptest.NewRecorder()
+	r.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status=%d want=%d body=%s", w.Code, http.StatusOK, w.Body.String())
+	}
+
+	var resp RobotListResponse
+	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("unmarshal response: %v body=%s", err, w.Body.String())
+	}
+	if resp.Total != 3 || len(resp.Items) != 1 {
+		t.Fatalf("unexpected paginated response: %#v", resp)
+	}
+	if resp.Items[0].DeviceID != "newest_robot" {
+		t.Fatalf("item[0].DeviceID=%q want newest_robot", resp.Items[0].DeviceID)
+	}
+	if !resp.HasNext {
+		t.Fatalf("HasNext=false want true response=%#v", resp)
+	}
+}
+
+func TestRobotHandlerListRobots_ConnectedFilterUsesHubIntersection(t *testing.T) {
+	db := newTestRobotHandlerDB(t)
+	defer db.Close()
+
+	now := time.Now().UTC()
+	stmts := []struct {
+		sql  string
+		args []any
+	}{
+		{sql: `INSERT INTO robots (id, robot_type_id, device_id, factory_id, status, created_at, updated_at) VALUES (1, 10, 'recorder_only_robot', 30, 'active', ?, ?)`, args: []any{now, now}},
+		{sql: `INSERT INTO robots (id, robot_type_id, device_id, factory_id, status, created_at, updated_at) VALUES (2, 10, 'connected_robot', 30, 'active', ?, ?)`, args: []any{now, now}},
+		{sql: `INSERT INTO robots (id, robot_type_id, device_id, factory_id, status, created_at, updated_at) VALUES (3, 10, 'offline_robot', 30, 'active', ?, ?)`, args: []any{now, now}},
+	}
+	for _, stmt := range stmts {
+		if _, err := db.Exec(stmt.sql, stmt.args...); err != nil {
+			t.Fatalf("seed robot fixture failed: %v", err)
+		}
+	}
+
+	recorderHub := services.NewRecorderHub()
+	transferHub := services.NewTransferHub(10)
+	connectRecorderForTest(t, recorderHub, "connected_robot", now)
+	connectTransferForTest(t, transferHub, "connected_robot", now.Add(time.Second))
+	connectRecorderForTest(t, recorderHub, "recorder_only_robot", now)
+
+	r := newTestRobotRouterWithHubs(t, db, recorderHub, transferHub)
+
+	t.Run("connected true returns only fully connected devices", func(t *testing.T) {
+		req := httptest.NewRequest(http.MethodGet, "/api/v1/robots?connected=true&limit=10", nil)
+		w := httptest.NewRecorder()
+		r.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Fatalf("status=%d want=%d body=%s", w.Code, http.StatusOK, w.Body.String())
+		}
+		var resp RobotListResponse
+		if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+			t.Fatalf("unmarshal response: %v body=%s", err, w.Body.String())
+		}
+		if resp.Total != 1 || len(resp.Items) != 1 {
+			t.Fatalf("unexpected connected response: %#v", resp)
+		}
+		if resp.Items[0].DeviceID != "connected_robot" || !resp.Items[0].Connected || resp.Items[0].ConnectedAt == "" {
+			t.Fatalf("unexpected connected item: %#v", resp.Items[0])
+		}
+	})
+
+	t.Run("connected false excludes fully connected devices", func(t *testing.T) {
+		req := httptest.NewRequest(http.MethodGet, "/api/v1/robots?connected=false&limit=10", nil)
+		w := httptest.NewRecorder()
+		r.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Fatalf("status=%d want=%d body=%s", w.Code, http.StatusOK, w.Body.String())
+		}
+		var resp RobotListResponse
+		if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+			t.Fatalf("unmarshal response: %v body=%s", err, w.Body.String())
+		}
+		wantDeviceIDs := []string{"offline_robot", "recorder_only_robot"}
+		if resp.Total != len(wantDeviceIDs) || len(resp.Items) != len(wantDeviceIDs) {
+			t.Fatalf("unexpected disconnected response: %#v", resp)
+		}
+		for i, wantDeviceID := range wantDeviceIDs {
+			if resp.Items[i].DeviceID != wantDeviceID || resp.Items[i].Connected {
+				t.Fatalf("item[%d]=%#v want device_id=%q connected=false", i, resp.Items[i], wantDeviceID)
+			}
+		}
+	})
+}
+
+func newTestRobotRouter(t *testing.T, db *sqlx.DB) *gin.Engine {
+	t.Helper()
+	return newTestRobotRouterWithHubs(t, db, nil, nil)
+}
+
+func newTestRobotRouterWithHubs(t *testing.T, db *sqlx.DB, recorderHub *services.RecorderHub, transferHub *services.TransferHub) *gin.Engine {
+	t.Helper()
+	gin.SetMode(gin.TestMode)
+	r := gin.New()
+	NewRobotHandler(db, recorderHub, transferHub).RegisterRoutes(r.Group("/api/v1"))
+	return r
+}
+
+func connectRecorderForTest(t *testing.T, hub *services.RecorderHub, deviceID string, connectedAt time.Time) {
+	t.Helper()
+	conn := hub.NewRecorderConn(nil, deviceID, "127.0.0.1")
+	conn.ConnectedAt = connectedAt
+	conn.LastSeenAt = connectedAt
+	if !hub.Connect(deviceID, conn) {
+		t.Fatalf("connect recorder %q failed", deviceID)
+	}
+}
+
+func connectTransferForTest(t *testing.T, hub *services.TransferHub, deviceID string, connectedAt time.Time) {
+	t.Helper()
+	conn := hub.NewTransferConn(nil, deviceID, "127.0.0.1")
+	conn.ConnectedAt = connectedAt
+	conn.LastSeenAt = connectedAt
+	if !hub.Connect(deviceID, conn) {
+		t.Fatalf("connect transfer %q failed", deviceID)
+	}
+}
+
+func newTestRobotHandlerDB(t *testing.T) *sqlx.DB {
+	t.Helper()
+	db, err := sqlx.Open("sqlite", ":memory:")
+	if err != nil {
+		t.Fatalf("open sqlite db: %v", err)
+	}
+
+	schema := `CREATE TABLE robots (
+			id INTEGER PRIMARY KEY,
+			robot_type_id INTEGER NOT NULL,
+		device_id TEXT NOT NULL,
+		factory_id INTEGER NOT NULL,
+		asset_id TEXT,
+		status TEXT NOT NULL,
+		metadata TEXT,
+		created_at TIMESTAMP,
+			updated_at TIMESTAMP,
+			deleted_at TIMESTAMP NULL
+		)`
+	if _, err := db.Exec(schema); err != nil {
+		t.Fatalf("create robot schema failed: %v", err)
+	}
+	if _, err := db.Exec(`CREATE TABLE robot_types (
+			id INTEGER PRIMARY KEY,
+			name TEXT NOT NULL,
+			model TEXT NOT NULL,
+			deleted_at TIMESTAMP NULL
+		)`); err != nil {
+		t.Fatalf("create robot type schema failed: %v", err)
+	}
+	if _, err := db.Exec(`CREATE TABLE factories (
+			id INTEGER PRIMARY KEY,
+			name TEXT NOT NULL,
+			slug TEXT NOT NULL,
+			deleted_at TIMESTAMP NULL
+		)`); err != nil {
+		t.Fatalf("create factory schema failed: %v", err)
+	}
+
+	return db
+}
diff --git a/internal/api/handlers/robot_type.go b/internal/api/handlers/robot_type.go
index e8ad2e1..af1d86d 100644
--- a/internal/api/handlers/robot_type.go
+++ b/internal/api/handlers/robot_type.go
@@ -249,6 +249,8 @@ func (h *RobotTypeHandler) CreateRobotType(c *gin.Context) {
 // @Tags         robot_types
 // @Accept       json
 // @Produce      json
+// @Param        robot_type_id query string false "Filter by robot type ID(s), comma-separated"
+// @Param        id      query     string false "Alias of robot_type_id"
 // @Param        keyword query     string false "Search by name, model, manufacturer, or end effector"
 // @Param        q       query     string false "Alias of keyword"
 // @Param        search  query     string false "Alias of keyword"
@@ -265,9 +267,16 @@ func (h *RobotTypeHandler) ListRobotTypes(c *gin.Context) {
 		return
 	}
 
+	robotTypeIDs, err := parsePositiveInt64List(firstNonEmptyQuery(c, "robot_type_id", "id"), "robot_type_id")
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
 	keyword := firstNonEmptyQuery(c, "keyword", "q", "search")
 	whereClause := "WHERE deleted_at IS NULL"
 	args := []any{}
+	whereClause, args = appendInt64InFilter(whereClause, args, "id", robotTypeIDs)
 	whereClause, args = appendKeywordSearch(whereClause, args, keyword, "name", "model", "manufacturer", "end_effector")
 
 	countQuery := "SELECT COUNT(*) FROM robot_types " + whereClause
diff --git a/internal/api/handlers/scene.go b/internal/api/handlers/scene.go
index f167b3c..b1b5283 100644
--- a/internal/api/handlers/scene.go
+++ b/internal/api/handlers/scene.go
@@ -101,7 +101,9 @@ type sceneRow struct {
 // @Tags         scenes
 // @Accept       json
 // @Produce      json
-// @Param        factory_id query string false "Filter by factory ID"
+// @Param        factory_id query string false "Filter by factory ID(s), comma-separated"
+// @Param        scene_id   query string false "Filter by scene ID(s), comma-separated"
+// @Param        id         query string false "Alias of scene_id"
 // @Param        keyword    query string false "Search by name or description"
 // @Param        q          query string false "Alias of keyword"
 // @Param        search     query string false "Alias of keyword"
@@ -118,21 +120,23 @@ func (h *SceneHandler) ListScenes(c *gin.Context) {
 		return
 	}
 
-	factoryID := c.Query("factory_id")
+	factoryIDs, err := parsePositiveInt64List(c.Query("factory_id"), "factory_id")
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	sceneIDs, err := parsePositiveInt64List(firstNonEmptyQuery(c, "scene_id", "id"), "scene_id")
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
 	keyword := firstNonEmptyQuery(c, "keyword", "q", "search")
 
 	whereClause := "WHERE s.deleted_at IS NULL"
 	args := []any{}
 
-	if factoryID != "" {
-		parsedFactoryID, err := strconv.ParseInt(factoryID, 10, 64)
-		if err != nil {
-			c.JSON(http.StatusBadRequest, gin.H{"error": "invalid factory_id format"})
-			return
-		}
-		whereClause += " AND s.factory_id = ?"
-		args = append(args, parsedFactoryID)
-	}
+	whereClause, args = appendInt64InFilter(whereClause, args, "s.factory_id", factoryIDs)
+	whereClause, args = appendInt64InFilter(whereClause, args, "s.id", sceneIDs)
 	whereClause, args = appendKeywordSearch(whereClause, args, keyword, "s.name", "s.description")
 
 	countQuery := "SELECT COUNT(*) FROM scenes s " + whereClause
diff --git a/internal/api/handlers/skill.go b/internal/api/handlers/skill.go
index 7d618b7..45ee122 100644
--- a/internal/api/handlers/skill.go
+++ b/internal/api/handlers/skill.go
@@ -120,6 +120,8 @@ type skillRow struct {
 // @Tags         skills
 // @Accept       json
 // @Produce      json
+// @Param        slug    query string false "Filter by skill slug(s), comma-separated"
+// @Param        skill_slug query string false "Alias of slug"
 // @Param        keyword query string false "Search by slug, description, or version"
 // @Param        q       query string false "Alias of keyword"
 // @Param        search  query string false "Alias of keyword"
@@ -136,9 +138,15 @@ func (h *SkillHandler) ListSkills(c *gin.Context) {
 		return
 	}
 
+	slugs, err := parseNonEmptyStringList(firstNonEmptyQuery(c, "slug", "skill_slug"), "slug")
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
 	keyword := firstNonEmptyQuery(c, "keyword", "q", "search")
 	whereClause := "WHERE deleted_at IS NULL"
 	args := []any{}
+	whereClause, args = appendStringInFilter(whereClause, args, "slug", slugs)
 	whereClause, args = appendKeywordSearch(whereClause, args, keyword, "slug", "description", "version")
 
 	countQuery := "SELECT COUNT(*) FROM skills " + whereClause
diff --git a/internal/api/handlers/sop.go b/internal/api/handlers/sop.go
index e188aa7..23d0704 100644
--- a/internal/api/handlers/sop.go
+++ b/internal/api/handlers/sop.go
@@ -102,6 +102,8 @@ type sopRow struct {
 // @Tags         sops
 // @Accept       json
 // @Produce      json
+// @Param        slug    query string false "Filter by SOP slug(s), comma-separated"
+// @Param        sop_slug query string false "Alias of slug"
 // @Param        keyword query string false "Search by slug, description, or version"
 // @Param        q       query string false "Alias of keyword"
 // @Param        search  query string false "Alias of keyword"
@@ -118,9 +120,15 @@ func (h *SOPHandler) ListSOPs(c *gin.Context) {
 		return
 	}
 
+	slugs, err := parseNonEmptyStringList(firstNonEmptyQuery(c, "slug", "sop_slug"), "slug")
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
 	keyword := firstNonEmptyQuery(c, "keyword", "q", "search")
 	whereClause := "WHERE deleted_at IS NULL"
 	args := []any{}
+	whereClause, args = appendStringInFilter(whereClause, args, "slug", slugs)
 	whereClause, args = appendKeywordSearch(whereClause, args, keyword, "slug", "description", "version")
 
 	countQuery := "SELECT COUNT(*) FROM sops " + whereClause
@@ -131,7 +139,7 @@ func (h *SOPHandler) ListSOPs(c *gin.Context) {
 		return
 	}
 
-	orderClause, orderArgs := keywordOrderBy(keyword, "id DESC", "slug", "description", "version")
+	orderClause, orderArgs := keywordOrderBy(keyword, "updated_at DESC, id DESC", "slug", "description", "version")
 	query := `
 		SELECT 
 			id,
@@ -318,14 +326,13 @@ func (h *SOPHandler) CreateSOP(c *gin.Context) {
 		return
 	}
 
-	// Validate skill_sequence
-	if len(req.SkillSequence) == 0 {
-		c.JSON(http.StatusBadRequest, gin.H{"error": "skill_sequence is required and must not be empty"})
-		return
+	skillSequence := req.SkillSequence
+	if skillSequence == nil {
+		skillSequence = []string{}
 	}
 
 	// Convert skill_sequence to JSON string
-	skillSeqJSON, err := json.Marshal(req.SkillSequence)
+	skillSeqJSON, err := json.Marshal(skillSequence)
 	if err != nil {
 		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to process skill_sequence"})
 		return
@@ -370,7 +377,7 @@ func (h *SOPHandler) CreateSOP(c *gin.Context) {
 	c.JSON(http.StatusCreated, CreateSOPResponse{
 		ID:            fmt.Sprintf("%d", id),
 		Slug:          req.Slug,
-		SkillSequence: req.SkillSequence,
+		SkillSequence: skillSequence,
 		Version:       version,
 		CreatedAt:     now.Format(time.RFC3339),
 	})
diff --git a/internal/api/handlers/station.go b/internal/api/handlers/station.go
index a0a1468..8c31c66 100644
--- a/internal/api/handlers/station.go
+++ b/internal/api/handlers/station.go
@@ -472,10 +472,13 @@ func stationResponseFromRow(s stationListRow) StationResponse {
 // @Description  Returns a list of all workstations with pagination
 // @Tags         stations
 // @Produce      json
-// @Param        factory_id      query int false "Filter by factory ID"
-// @Param        organization_id query int false "Filter by organization ID"
-// @Param        robot_type_id   query int false "Filter by robot type ID"
-// @Param        status          query string false "Filter by status (active, inactive, break, offline)"
+// @Param        factory_id            query string false "Filter by factory ID(s), comma-separated"
+// @Param        organization_id       query string false "Filter by organization ID(s), comma-separated"
+// @Param        robot_type_id         query string false "Filter by robot type ID(s), comma-separated"
+// @Param        device_id             query string false "Filter by robot device ID(s), comma-separated"
+// @Param        collector_name        query string false "Filter by collector name(s), comma-separated"
+// @Param        collector_operator_id query string false "Filter by collector operator ID(s), comma-separated"
+// @Param        status                query string false "Filter by status(es), comma-separated (active, inactive, break, offline)"
 // @Param        keyword         query string false "Search by name, robot serial, robot name, collector operator ID, or collector name"
 // @Param        q               query string false "Alias of keyword"
 // @Param        search          query string false "Alias of keyword"
@@ -492,49 +495,62 @@ func (h *StationHandler) ListStations(c *gin.Context) {
 		return
 	}
 
-	factoryIDStr := strings.TrimSpace(c.Query("factory_id"))
-	orgIDStr := strings.TrimSpace(c.Query("organization_id"))
-	robotTypeIDStr := strings.TrimSpace(c.Query("robot_type_id"))
-	statusStr := strings.TrimSpace(c.Query("status"))
-	keyword := firstNonEmptyQuery(c, "keyword", "q", "search")
-	var factoryID int64
-	var orgID int64
-	var robotTypeID int64
-	hasFactory := factoryIDStr != ""
-	hasOrg := orgIDStr != ""
-	hasRobotType := robotTypeIDStr != ""
-	hasStatus := statusStr != ""
-	if hasFactory {
-		var err error
-		factoryID, err = strconv.ParseInt(factoryIDStr, 10, 64)
-		if err != nil || factoryID <= 0 {
-			c.JSON(http.StatusBadRequest, gin.H{"error": "invalid factory_id format"})
-			return
-		}
+	factoryIDs, err := parsePositiveInt64List(c.Query("factory_id"), "factory_id")
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
 	}
-	if hasOrg {
-		var err error
-		orgID, err = strconv.ParseInt(orgIDStr, 10, 64)
-		if err != nil || orgID <= 0 {
-			c.JSON(http.StatusBadRequest, gin.H{"error": "invalid organization_id format"})
-			return
-		}
+	orgIDs, err := parsePositiveInt64List(c.Query("organization_id"), "organization_id")
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
 	}
-	if hasRobotType {
-		var err error
-		robotTypeID, err = strconv.ParseInt(robotTypeIDStr, 10, 64)
-		if err != nil || robotTypeID <= 0 {
-			c.JSON(http.StatusBadRequest, gin.H{"error": "invalid robot_type_id format"})
-			return
-		}
+	robotTypeIDs, err := parsePositiveInt64List(c.Query("robot_type_id"), "robot_type_id")
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
 	}
-	if hasStatus {
-		statusStr = strings.ToLower(statusStr)
-		if _, ok := validStationStatuses[statusStr]; !ok {
+	statuses, err := parseNonEmptyStringList(c.Query("status"), "status")
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	for i, status := range statuses {
+		status = strings.ToLower(status)
+		if _, ok := validStationStatuses[status]; !ok {
 			c.JSON(http.StatusBadRequest, gin.H{"error": "invalid status"})
 			return
 		}
+		statuses[i] = status
 	}
+	deviceIDs, err := parseNonEmptyStringList(firstNonEmptyQuery(c, "device_id", "robot_serial"), "device_id")
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	collectorNames, err := parseNonEmptyStringList(c.Query("collector_name"), "collector_name")
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	collectorOperatorIDs, err := parseNonEmptyStringList(c.Query("collector_operator_id"), "collector_operator_id")
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	keyword := firstNonEmptyQuery(c, "keyword", "q", "search")
+	stationSearchFields := []string{"ws.name", "ws.robot_serial", "ws.collector_operator_id", "ws.robot_name", "ws.collector_name"}
+
+	whereClause := "WHERE ws.deleted_at IS NULL"
+	args := []any{}
+	whereClause, args = appendInt64InFilter(whereClause, args, "ws.factory_id", factoryIDs)
+	whereClause, args = appendInt64InFilter(whereClause, args, "ws.organization_id", orgIDs)
+	whereClause, args = appendInt64InFilter(whereClause, args, "r.robot_type_id", robotTypeIDs)
+	whereClause, args = appendStringInFilter(whereClause, args, "ws.status", statuses)
+	whereClause, args = appendStringInFilter(whereClause, args, "ws.robot_serial", deviceIDs)
+	whereClause, args = appendStringInFilter(whereClause, args, "ws.collector_name", collectorNames)
+	whereClause, args = appendStringInFilter(whereClause, args, "ws.collector_operator_id", collectorOperatorIDs)
+	whereClause, args = appendKeywordSearch(whereClause, args, keyword, stationSearchFields...)
 
 	countQuery := `
 		SELECT COUNT(*)
@@ -543,29 +559,9 @@ func (h *StationHandler) ListStations(c *gin.Context) {
 		INNER JOIN robot_types rt ON rt.id = r.robot_type_id AND rt.deleted_at IS NULL
 		INNER JOIN factories f ON f.id = ws.factory_id AND f.deleted_at IS NULL
 		INNER JOIN organizations o ON o.id = ws.organization_id AND o.deleted_at IS NULL
-		WHERE ws.deleted_at IS NULL
-	`
-	countArgs := []any{}
-	if hasFactory {
-		countQuery += " AND ws.factory_id = ?"
-		countArgs = append(countArgs, factoryID)
-	}
-	if hasOrg {
-		countQuery += " AND ws.organization_id = ?"
-		countArgs = append(countArgs, orgID)
-	}
-	if hasRobotType {
-		countQuery += " AND r.robot_type_id = ?"
-		countArgs = append(countArgs, robotTypeID)
-	}
-	if hasStatus {
-		countQuery += " AND ws.status = ?"
-		countArgs = append(countArgs, statusStr)
-	}
-	stationSearchFields := []string{"ws.name", "ws.robot_serial", "ws.collector_operator_id", "ws.robot_name", "ws.collector_name"}
-	countQuery, countArgs = appendKeywordSearch(countQuery, countArgs, keyword, stationSearchFields...)
+		` + whereClause
 	var total int
-	if err := h.db.Get(&total, countQuery, countArgs...); err != nil {
+	if err := h.db.Get(&total, countQuery, args...); err != nil {
 		logger.Printf("[STATION] Failed to count stations: %v", err)
 		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to list stations"})
 		return
@@ -585,35 +581,17 @@ func (h *StationHandler) ListStations(c *gin.Context) {
 		INNER JOIN robot_types rt ON rt.id = r.robot_type_id AND rt.deleted_at IS NULL
 		INNER JOIN factories f ON f.id = ws.factory_id AND f.deleted_at IS NULL
 		INNER JOIN organizations o ON o.id = ws.organization_id AND o.deleted_at IS NULL
-		WHERE ws.deleted_at IS NULL
+		` + whereClause + `
 	`
-	args := []any{}
-	if hasFactory {
-		query += " AND ws.factory_id = ?\n"
-		args = append(args, factoryID)
-	}
-	if hasOrg {
-		query += " AND ws.organization_id = ?\n"
-		args = append(args, orgID)
-	}
-	if hasRobotType {
-		query += " AND r.robot_type_id = ?\n"
-		args = append(args, robotTypeID)
-	}
-	if hasStatus {
-		query += " AND ws.status = ?\n"
-		args = append(args, statusStr)
-	}
-	query, args = appendKeywordSearch(query, args, keyword, stationSearchFields...)
 	orderClause, orderArgs := keywordOrderBy(keyword, "ws.id DESC", stationSearchFields...)
 	query += `
 		` + orderClause + `
 		LIMIT ? OFFSET ?
 	`
-	args = append(args, orderArgs...)
-	args = append(args, pagination.Limit, pagination.Offset)
+	queryArgs := append(args, orderArgs...)
+	queryArgs = append(queryArgs, pagination.Limit, pagination.Offset)
 
-	err = h.db.Select(&stations, query, args...)
+	err = h.db.Select(&stations, query, queryArgs...)
 	if err != nil && err != sql.ErrNoRows {
 		logger.Printf("[STATION] Failed to query stations: %v", err)
 		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to list stations"})
diff --git a/internal/api/handlers/station_test.go b/internal/api/handlers/station_test.go
new file mode 100644
index 0000000..d51230a
--- /dev/null
+++ b/internal/api/handlers/station_test.go
@@ -0,0 +1,156 @@
+// SPDX-FileCopyrightText: 2026 ArcheBase
+//
+// SPDX-License-Identifier: MulanPSL-2.0
+
+package handlers
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/jmoiron/sqlx"
+	_ "modernc.org/sqlite"
+)
+
+func TestStationHandlerListStations_FilterByWorkstationFields(t *testing.T) {
+	db := newTestStationHandlerDB(t)
+	defer db.Close()
+
+	now := time.Now().UTC()
+	stmts := []struct {
+		sql  string
+		args []any
+	}{
+		{sql: `INSERT INTO robot_types (id, model, deleted_at) VALUES (10, 'arm-v1', NULL)`},
+		{sql: `INSERT INTO robot_types (id, model, deleted_at) VALUES (11, 'arm-v2', NULL)`},
+		{sql: `INSERT INTO factories (id, name, deleted_at) VALUES (30, 'F1', NULL)`},
+		{sql: `INSERT INTO factories (id, name, deleted_at) VALUES (31, 'F2', NULL)`},
+		{sql: `INSERT INTO organizations (id, name, deleted_at) VALUES (60, 'Org A', NULL)`},
+		{sql: `INSERT INTO organizations (id, name, deleted_at) VALUES (61, 'Org B', NULL)`},
+		{sql: `INSERT INTO robots (id, robot_type_id, device_id, factory_id, deleted_at) VALUES (1, 10, 'device-a', 30, NULL)`},
+		{sql: `INSERT INTO robots (id, robot_type_id, device_id, factory_id, deleted_at) VALUES (2, 10, 'device-b', 30, NULL)`},
+		{sql: `INSERT INTO robots (id, robot_type_id, device_id, factory_id, deleted_at) VALUES (3, 11, 'device-c', 31, NULL)`},
+		{
+			sql: `INSERT INTO workstations (
+				id, robot_id, robot_name, robot_serial, data_collector_id,
+				collector_name, collector_operator_id, factory_id, organization_id,
+				name, status, metadata, created_at, updated_at, deleted_at
+			) VALUES (1, 1, 'arm-v1', 'device-a', 100, 'Alice', 'C001', 30, 60, 'ws-a', 'active', '{}', ?, ?, NULL)`,
+			args: []any{now, now},
+		},
+		{
+			sql: `INSERT INTO workstations (
+				id, robot_id, robot_name, robot_serial, data_collector_id,
+				collector_name, collector_operator_id, factory_id, organization_id,
+				name, status, metadata, created_at, updated_at, deleted_at
+			) VALUES (2, 2, 'arm-v1', 'device-b', 101, 'Bob', 'C002', 30, 61, 'ws-b', 'inactive', '{}', ?, ?, NULL)`,
+			args: []any{now, now},
+		},
+		{
+			sql: `INSERT INTO workstations (
+				id, robot_id, robot_name, robot_serial, data_collector_id,
+				collector_name, collector_operator_id, factory_id, organization_id,
+				name, status, metadata, created_at, updated_at, deleted_at
+			) VALUES (3, 3, 'arm-v2', 'device-c', 102, 'Alice', 'C003', 31, 60, 'ws-c', 'offline', '{}', ?, ?, NULL)`,
+			args: []any{now, now},
+		},
+	}
+	for _, stmt := range stmts {
+		if _, err := db.Exec(stmt.sql, stmt.args...); err != nil {
+			t.Fatalf("seed station fixture failed: %v", err)
+		}
+	}
+
+	r := newTestStationRouter(t, db)
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/stations?device_id=device-a,device-c&collector_name=Alice&collector_operator_id=C003&factory_id=31&organization_id=60&robot_type_id=11&status=offline", nil)
+	w := httptest.NewRecorder()
+	r.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status=%d want=%d body=%s", w.Code, http.StatusOK, w.Body.String())
+	}
+
+	var resp struct {
+		Items []StationResponse `json:"items"`
+		Total int               `json:"total"`
+	}
+	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("unmarshal response: %v body=%s", err, w.Body.String())
+	}
+	if resp.Total != 1 || len(resp.Items) != 1 {
+		t.Fatalf("unexpected filtered response: %#v", resp)
+	}
+	got := resp.Items[0]
+	if got.ID != "3" || got.RobotSerial != "device-c" || got.CollectorName != "Alice" || got.CollectorOperatorID != "C003" {
+		t.Fatalf("unexpected station item: %#v", got)
+	}
+}
+
+func newTestStationRouter(t *testing.T, db *sqlx.DB) *gin.Engine {
+	t.Helper()
+	gin.SetMode(gin.TestMode)
+	r := gin.New()
+	NewStationHandler(db).RegisterRoutes(r.Group("/api/v1"))
+	return r
+}
+
+func newTestStationHandlerDB(t *testing.T) *sqlx.DB {
+	t.Helper()
+	db, err := sqlx.Open("sqlite", ":memory:")
+	if err != nil {
+		t.Fatalf("open sqlite db: %v", err)
+	}
+
+	schema := []string{
+		`CREATE TABLE robot_types (
+			id INTEGER PRIMARY KEY,
+			model TEXT NOT NULL,
+			deleted_at TIMESTAMP NULL
+		)`,
+		`CREATE TABLE factories (
+			id INTEGER PRIMARY KEY,
+			name TEXT NOT NULL,
+			deleted_at TIMESTAMP NULL
+		)`,
+		`CREATE TABLE organizations (
+			id INTEGER PRIMARY KEY,
+			name TEXT NOT NULL,
+			deleted_at TIMESTAMP NULL
+		)`,
+		`CREATE TABLE robots (
+			id INTEGER PRIMARY KEY,
+			robot_type_id INTEGER NOT NULL,
+			device_id TEXT NOT NULL,
+			factory_id INTEGER NOT NULL,
+			deleted_at TIMESTAMP NULL
+		)`,
+		`CREATE TABLE workstations (
+			id INTEGER PRIMARY KEY,
+			robot_id INTEGER NOT NULL,
+			robot_name TEXT,
+			robot_serial TEXT,
+			data_collector_id INTEGER NOT NULL,
+			collector_name TEXT,
+			collector_operator_id TEXT,
+			factory_id INTEGER NOT NULL,
+			organization_id INTEGER NOT NULL,
+			name TEXT,
+			status TEXT NOT NULL,
+			metadata TEXT,
+			created_at TIMESTAMP,
+			updated_at TIMESTAMP,
+			deleted_at TIMESTAMP NULL
+		)`,
+	}
+	for _, stmt := range schema {
+		if _, err := db.Exec(stmt); err != nil {
+			t.Fatalf("create station schema failed: %v", err)
+		}
+	}
+
+	return db
+}
diff --git a/internal/api/handlers/subscene.go b/internal/api/handlers/subscene.go
index 281cbf6..e36d3fe 100644
--- a/internal/api/handlers/subscene.go
+++ b/internal/api/handlers/subscene.go
@@ -109,12 +109,14 @@ func (h *SubsceneHandler) getSceneInitialLayoutTemplate(sceneID int64) (sql.Null
 // @Tags         subscenes
 // @Accept       json
 // @Produce      json
-// @Param        scene_id query string false "Filter by scene ID"
-// @Param        keyword  query string false "Search by name or description"
-// @Param        q        query string false "Alias of keyword"
-// @Param        search   query string false "Alias of keyword"
-// @Param        limit    query int    false "Max results (default 50, max 100)"
-// @Param        offset   query int    false "Pagination offset (default 0)"
+// @Param        scene_id    query string false "Filter by scene ID(s), comma-separated"
+// @Param        subscene_id query string false "Filter by subscene ID(s), comma-separated"
+// @Param        id          query string false "Alias of subscene_id"
+// @Param        keyword     query string false "Search by name or description"
+// @Param        q           query string false "Alias of keyword"
+// @Param        search      query string false "Alias of keyword"
+// @Param        limit       query int    false "Max results (default 50, max 100)"
+// @Param        offset      query int    false "Pagination offset (default 0)"
 // @Success      200 {object} SubsceneListResponse
 // @Failure      400 {object} map[string]string
 // @Failure      500 {object} map[string]string
@@ -126,21 +128,23 @@ func (h *SubsceneHandler) ListSubscenes(c *gin.Context) {
 		return
 	}
 
-	sceneID := c.Query("scene_id")
+	sceneIDs, err := parsePositiveInt64List(c.Query("scene_id"), "scene_id")
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	subsceneIDs, err := parsePositiveInt64List(firstNonEmptyQuery(c, "subscene_id", "id"), "subscene_id")
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
 	keyword := firstNonEmptyQuery(c, "keyword", "q", "search")
 
 	whereClause := "WHERE ss.deleted_at IS NULL"
 	args := []any{}
 
-	if sceneID != "" {
-		parsedSceneID, err := strconv.ParseInt(sceneID, 10, 64)
-		if err != nil {
-			c.JSON(http.StatusBadRequest, gin.H{"error": "invalid scene_id format"})
-			return
-		}
-		whereClause += " AND ss.scene_id = ?"
-		args = append(args, parsedSceneID)
-	}
+	whereClause, args = appendInt64InFilter(whereClause, args, "ss.scene_id", sceneIDs)
+	whereClause, args = appendInt64InFilter(whereClause, args, "ss.id", subsceneIDs)
 	whereClause, args = appendKeywordSearch(whereClause, args, keyword, "ss.name", "ss.description")
 
 	countQuery := "SELECT COUNT(*) FROM subscenes ss " + whereClause
diff --git a/internal/server/server.go b/internal/server/server.go
index dcbfd2a..3401cc7 100644
--- a/internal/server/server.go
+++ b/internal/server/server.go
@@ -31,37 +31,38 @@ import (
 
 // Server represents the HTTP server
 type Server struct {
-	cfg                *config.Config
-	health             *handlers.HealthHandler
-	auth               *handlers.AuthHandler
-	storage            *handlers.StorageHandler
-	transfer           *handlers.TransferHandler
-	recorder           *handlers.RecorderHandler
-	episode            *handlers.EpisodeHandler
-	task               *handlers.TaskHandler
-	batch              *handlers.BatchHandler
-	robotType          *handlers.RobotTypeHandler
-	robot              *handlers.RobotHandler
-	deviceRegistration *handlers.DeviceRegistrationHandler
-	factory            *handlers.FactoryHandler
-	dataCollector      *handlers.DataCollectorHandler
-	station            *handlers.StationHandler
-	organization       *handlers.OrganizationHandler
-	skill              *handlers.SkillHandler
-	inspector          *handlers.InspectorHandler
-	sop                *handlers.SOPHandler
-	scene              *handlers.SceneHandler
-	subscene           *handlers.SubsceneHandler
-	order              *handlers.OrderHandler
-	dataStats          *handlers.DataProductionStatisticsHandler
-	syncHandler        *handlers.SyncHandler
-	syncWorker         *services.SyncWorker
-	httpServer         *http.Server
-	transferWSServer   *http.Server
-	recorderWSServer   *http.Server
-	shutdownMu         sync.RWMutex
-	isRunning          bool
-	engine             *gin.Engine
+	cfg                 *config.Config
+	health              *handlers.HealthHandler
+	auth                *handlers.AuthHandler
+	storage             *handlers.StorageHandler
+	transfer            *handlers.TransferHandler
+	recorder            *handlers.RecorderHandler
+	episode             *handlers.EpisodeHandler
+	task                *handlers.TaskHandler
+	batch               *handlers.BatchHandler
+	robotType           *handlers.RobotTypeHandler
+	robot               *handlers.RobotHandler
+	deviceRegistration  *handlers.DeviceRegistrationHandler
+	factory             *handlers.FactoryHandler
+	dataCollector       *handlers.DataCollectorHandler
+	station             *handlers.StationHandler
+	organization        *handlers.OrganizationHandler
+	skill               *handlers.SkillHandler
+	inspector           *handlers.InspectorHandler
+	sop                 *handlers.SOPHandler
+	scene               *handlers.SceneHandler
+	subscene            *handlers.SubsceneHandler
+	order               *handlers.OrderHandler
+	dataStats           *handlers.DataProductionStatisticsHandler
+	productionDashboard *handlers.ProductionDashboardHandler
+	syncHandler         *handlers.SyncHandler
+	syncWorker          *services.SyncWorker
+	httpServer          *http.Server
+	transferWSServer    *http.Server
+	recorderWSServer    *http.Server
+	shutdownMu          sync.RWMutex
+	isRunning           bool
+	engine              *gin.Engine
 }
 
 // New creates a new server instance.
@@ -102,21 +103,22 @@ func New(cfg *config.Config, db *sqlx.DB, s3Client *s3.Client, syncWorker *servi
 
 	// Create database-dependent handlers only when DB is available
 	var (
-		batchHandler              *handlers.BatchHandler
-		robotTypeHandler          *handlers.RobotTypeHandler
-		robotHandler              *handlers.RobotHandler
-		deviceRegistrationHandler *handlers.DeviceRegistrationHandler
-		factoryHandler            *handlers.FactoryHandler
-		dataCollectorHandler      *handlers.DataCollectorHandler
-		stationHandler            *handlers.StationHandler
-		organizationHandler       *handlers.OrganizationHandler
-		skillHandler              *handlers.SkillHandler
-		inspectorHandler          *handlers.InspectorHandler
-		sopHandler                *handlers.SOPHandler
-		sceneHandler              *handlers.SceneHandler
-		subsceneHandler           *handlers.SubsceneHandler
-		orderHandler              *handlers.OrderHandler
-		dataStatsHandler          *handlers.DataProductionStatisticsHandler
+		batchHandler               *handlers.BatchHandler
+		robotTypeHandler           *handlers.RobotTypeHandler
+		robotHandler               *handlers.RobotHandler
+		deviceRegistrationHandler  *handlers.DeviceRegistrationHandler
+		factoryHandler             *handlers.FactoryHandler
+		dataCollectorHandler       *handlers.DataCollectorHandler
+		stationHandler             *handlers.StationHandler
+		organizationHandler        *handlers.OrganizationHandler
+		skillHandler               *handlers.SkillHandler
+		inspectorHandler           *handlers.InspectorHandler
+		sopHandler                 *handlers.SOPHandler
+		sceneHandler               *handlers.SceneHandler
+		subsceneHandler            *handlers.SubsceneHandler
+		orderHandler               *handlers.OrderHandler
+		dataStatsHandler           *handlers.DataProductionStatisticsHandler
+		productionDashboardHandler *handlers.ProductionDashboardHandler
 	)
 	if db != nil {
 		batchHandler = handlers.NewBatchHandler(db, recorderHub, recorderRPCTimeout)
@@ -134,6 +136,7 @@ func New(cfg *config.Config, db *sqlx.DB, s3Client *s3.Client, syncWorker *servi
 		subsceneHandler = handlers.NewSubsceneHandler(db)
 		orderHandler = handlers.NewOrderHandler(db, recorderHub, recorderRPCTimeout)
 		dataStatsHandler = handlers.NewDataProductionStatisticsHandler(db)
+		productionDashboardHandler = handlers.NewProductionDashboardHandler(db)
 	}
 
 	// Create SyncHandler for cloud sync API
@@ -143,32 +146,33 @@ func New(cfg *config.Config, db *sqlx.DB, s3Client *s3.Client, syncWorker *servi
 	}
 
 	s := &Server{
-		cfg:                cfg,
-		health:             healthHandler,
-		auth:               authHandler,
-		storage:            storageHandler,
-		transfer:           transferHandler,
-		recorder:           recorderHandler,
-		episode:            episodeHandler,
-		task:               taskHandler,
-		batch:              batchHandler,
-		robotType:          robotTypeHandler,
-		robot:              robotHandler,
-		deviceRegistration: deviceRegistrationHandler,
-		factory:            factoryHandler,
-		dataCollector:      dataCollectorHandler,
-		station:            stationHandler,
-		organization:       organizationHandler,
-		skill:              skillHandler,
-		inspector:          inspectorHandler,
-		sop:                sopHandler,
-		scene:              sceneHandler,
-		subscene:           subsceneHandler,
-		order:              orderHandler,
-		dataStats:          dataStatsHandler,
-		syncHandler:        syncHandler,
-		syncWorker:         syncWorker,
-		engine:             engine,
+		cfg:                 cfg,
+		health:              healthHandler,
+		auth:                authHandler,
+		storage:             storageHandler,
+		transfer:            transferHandler,
+		recorder:            recorderHandler,
+		episode:             episodeHandler,
+		task:                taskHandler,
+		batch:               batchHandler,
+		robotType:           robotTypeHandler,
+		robot:               robotHandler,
+		deviceRegistration:  deviceRegistrationHandler,
+		factory:             factoryHandler,
+		dataCollector:       dataCollectorHandler,
+		station:             stationHandler,
+		organization:        organizationHandler,
+		skill:               skillHandler,
+		inspector:           inspectorHandler,
+		sop:                 sopHandler,
+		scene:               sceneHandler,
+		subscene:            subsceneHandler,
+		order:               orderHandler,
+		dataStats:           dataStatsHandler,
+		productionDashboard: productionDashboardHandler,
+		syncHandler:         syncHandler,
+		syncWorker:          syncWorker,
+		engine:              engine,
 	}
 
 	s.httpServer = &http.Server{
@@ -292,6 +296,11 @@ func (s *Server) buildRoutes() http.Handler {
 		adminStats := v1Routes.Group("/admin/statistics/data-production", jwtMw, middleware.RequireRole("admin"))
 		s.dataStats.RegisterRoutes(adminStats)
 	}
+	if s.productionDashboard != nil {
+		jwtMw := middleware.JWTAuth(&s.cfg.Auth)
+		dashboard := v1Routes.Group("/production/dashboard", jwtMw, middleware.RequireAnyRole("admin", "data_collector"))
+		s.productionDashboard.RegisterRoutes(dashboard)
+	}
 
 	// Cloud Sync API
 	if s.syncHandler != nil {

From 620ed5c381da88cce5c8b69e39d613da706e4011 Mon Sep 17 00:00:00 2001
From: shark <mandoreshark@gmail.com>
Date: Tue, 12 May 2026 03:22:54 +0800
Subject: [PATCH 4/4] perf(batch): paginate batch tasks

---
 internal/api/handlers/batch.go      | 78 +++++++++++++++++++++++----
 internal/api/handlers/batch_test.go | 81 ++++++++++++++++++++++++++++-
 2 files changed, 146 insertions(+), 13 deletions(-)

diff --git a/internal/api/handlers/batch.go b/internal/api/handlers/batch.go
index e9bb637..a596d59 100644
--- a/internal/api/handlers/batch.go
+++ b/internal/api/handlers/batch.go
@@ -1640,13 +1640,15 @@ func (h *BatchHandler) RecallBatch(c *gin.Context) {
 	})
 }
 
-// ListBatchTasks lists all tasks belonging to a batch.
+// ListBatchTasks lists tasks belonging to a batch.
 //
 // @Summary      List batch tasks
-// @Description  Returns all tasks belonging to the specified batch
+// @Description  Returns tasks belonging to the specified batch. Passing limit/offset enables pagination; omitting both keeps the legacy full response.
 // @Tags         batches
 // @Produce      json
-// @Param        id path int true "Batch ID"
+// @Param        id     path  int true  "Batch ID"
+// @Param        limit  query int false "Max results"
+// @Param        offset query int false "Pagination offset"
 // @Success      200 {object} ListTasksResponse
 // @Failure      400 {object} map[string]string
 // @Failure      404 {object} map[string]string
@@ -1660,6 +1662,31 @@ func (h *BatchHandler) ListBatchTasks(c *gin.Context) {
 		return
 	}
 
+	const defaultLimit = 50
+	rawLimit := strings.TrimSpace(c.Query("limit"))
+	rawOffset := strings.TrimSpace(c.Query("offset"))
+	paginated := rawLimit != "" || rawOffset != ""
+
+	limit := defaultLimit
+	if rawLimit != "" {
+		parsedLimit, err := strconv.Atoi(rawLimit)
+		if err != nil || parsedLimit <= 0 {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "limit must be a positive integer"})
+			return
+		}
+		limit = parsedLimit
+	}
+
+	offset := 0
+	if rawOffset != "" {
+		parsedOffset, err := strconv.Atoi(rawOffset)
+		if err != nil || parsedOffset < 0 {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "offset must be a non-negative integer"})
+			return
+		}
+		offset = parsedOffset
+	}
+
 	// Verify batch exists
 	var exists int
 	if err := h.db.Get(&exists, "SELECT 1 FROM batches WHERE id = ? AND deleted_at IS NULL LIMIT 1", id); err != nil {
@@ -1672,8 +1699,21 @@ func (h *BatchHandler) ListBatchTasks(c *gin.Context) {
 		return
 	}
 
-	items := make([]TaskListItem, 0)
-	if err := h.db.Select(&items, `
+	total := 0
+	if paginated {
+		if err := h.db.Get(&total, "SELECT COUNT(*) FROM tasks WHERE batch_id = ? AND deleted_at IS NULL", id); err != nil {
+			logger.Printf("[BATCH] Failed to count batch tasks: %v", err)
+			c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to list batch tasks"})
+			return
+		}
+	}
+
+	assignedAtExpr := "CASE WHEN assigned_at IS NULL THEN NULL ELSE DATE_FORMAT(CONVERT_TZ(assigned_at, @@session.time_zone, '+00:00'), '%Y-%m-%dT%H:%i:%sZ') END AS assigned_at"
+	if h.db.DriverName() == "sqlite" {
+		assignedAtExpr = "CASE WHEN assigned_at IS NULL THEN NULL ELSE strftime('%Y-%m-%dT%H:%M:%SZ', assigned_at) END AS assigned_at"
+	}
+
+	query := `
 		SELECT
 			CAST(id AS CHAR) AS id,
 			task_id AS task_id,
@@ -1686,20 +1726,36 @@ func (h *BatchHandler) ListBatchTasks(c *gin.Context) {
 			CAST(subscene_id AS CHAR) AS subscene_id,
 			COALESCE(subscene_name, '') AS subscene_name,
 			status,
-			CASE WHEN assigned_at IS NULL THEN NULL ELSE DATE_FORMAT(CONVERT_TZ(assigned_at, @@session.time_zone, '+00:00'), '%Y-%m-%dT%H:%i:%sZ') END AS assigned_at
+			` + assignedAtExpr + `
 		FROM tasks
 		WHERE batch_id = ? AND deleted_at IS NULL
-		ORDER BY created_at ASC, id ASC`, id); err != nil {
+		ORDER BY created_at ASC, id ASC`
+	args := []interface{}{id}
+	if paginated {
+		query += " LIMIT ? OFFSET ?"
+		args = append(args, limit, offset)
+	}
+
+	items := make([]TaskListItem, 0)
+	if err := h.db.Select(&items, query, args...); err != nil {
 		logger.Printf("[BATCH] Failed to query batch tasks: %v", err)
 		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to list batch tasks"})
 		return
 	}
 
+	if !paginated {
+		limit = len(items)
+		offset = 0
+		total = len(items)
+	}
+
 	c.JSON(http.StatusOK, ListTasksResponse{
-		Items:  items,
-		Total:  len(items),
-		Limit:  len(items),
-		Offset: 0,
+		Items:   items,
+		Total:   total,
+		Limit:   limit,
+		Offset:  offset,
+		HasNext: paginated && offset+limit < total,
+		HasPrev: paginated && offset > 0,
 	})
 }
 
diff --git a/internal/api/handlers/batch_test.go b/internal/api/handlers/batch_test.go
index ee1af9b..4e9684d 100644
--- a/internal/api/handlers/batch_test.go
+++ b/internal/api/handlers/batch_test.go
@@ -338,6 +338,83 @@ func TestBatchHandlerListBatches_PaginationFlags(t *testing.T) {
 	}
 }
 
+func TestBatchHandlerListBatchTasks_LegacyFullResponse(t *testing.T) {
+	db := newTestBatchHandlerDB(t)
+	defer db.Close()
+	seedBatchListFixtures(t, db)
+
+	r := newTestBatchRouter(t, db)
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/batches/1/tasks", nil)
+	w := httptest.NewRecorder()
+	r.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status=%d want=%d body=%s", w.Code, http.StatusOK, w.Body.String())
+	}
+
+	var resp ListTasksResponse
+	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("unmarshal response: %v body=%s", err, w.Body.String())
+	}
+
+	if resp.Total != 2 || resp.Limit != 2 || resp.Offset != 0 {
+		t.Fatalf("unexpected legacy paging fields: %#v", resp)
+	}
+	if resp.HasNext || resp.HasPrev {
+		t.Fatalf("legacy response should not set pagination flags: %#v", resp)
+	}
+	if len(resp.Items) != 2 || resp.Items[0].TaskID != "T1" || resp.Items[1].TaskID != "T2" {
+		t.Fatalf("unexpected tasks: %#v", resp.Items)
+	}
+}
+
+func TestBatchHandlerListBatchTasks_PaginationFlags(t *testing.T) {
+	db := newTestBatchHandlerDB(t)
+	defer db.Close()
+	seedBatchListFixtures(t, db)
+
+	r := newTestBatchRouter(t, db)
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/batches/1/tasks?limit=1&offset=1", nil)
+	w := httptest.NewRecorder()
+	r.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status=%d want=%d body=%s", w.Code, http.StatusOK, w.Body.String())
+	}
+
+	var resp ListTasksResponse
+	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("unmarshal response: %v body=%s", err, w.Body.String())
+	}
+
+	if resp.Total != 2 || resp.Limit != 1 || resp.Offset != 1 {
+		t.Fatalf("unexpected paging fields: %#v", resp)
+	}
+	if resp.HasNext || !resp.HasPrev {
+		t.Fatalf("expected hasNext=false and hasPrev=true, got hasNext=%v hasPrev=%v", resp.HasNext, resp.HasPrev)
+	}
+	if len(resp.Items) != 1 || resp.Items[0].TaskID != "T2" {
+		t.Fatalf("unexpected page items: %#v", resp.Items)
+	}
+}
+
+func TestBatchHandlerListBatchTasks_InvalidPagination(t *testing.T) {
+	db := newTestBatchHandlerDB(t)
+	defer db.Close()
+
+	r := newTestBatchRouter(t, db)
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/batches/1/tasks?limit=0", nil)
+	w := httptest.NewRecorder()
+	r.ServeHTTP(w, req)
+
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("status=%d want=%d body=%s", w.Code, http.StatusBadRequest, w.Body.String())
+	}
+	if !strings.Contains(w.Body.String(), "limit must be a positive integer") {
+		t.Fatalf("unexpected error response: %s", w.Body.String())
+	}
+}
+
 func TestBatchHandlerCreateBatch_InvalidQuantity(t *testing.T) {
 	db := newTestBatchHandlerDB(t)
 	defer db.Close()
@@ -592,8 +669,8 @@ func seedBatchListFixtures(t *testing.T, db *sqlx.DB) {
 	stmts := []string{
 		`INSERT INTO batches (id, batch_id, order_id, workstation_id, organization_id, name, status, episode_count, created_at, updated_at) VALUES (1, 'B1', 10, 20, 60, 'A', 'active', 0, ?, ?)`,
 		`INSERT INTO batches (id, batch_id, order_id, workstation_id, organization_id, name, status, episode_count, created_at, updated_at) VALUES (2, 'B2', 11, 21, 60, 'B', 'pending', 0, ?, ?)`,
-		`INSERT INTO tasks (task_id, batch_id, order_id, sop_id, workstation_id, status, created_at, updated_at) VALUES ('T1', 1, 10, 40, 20, 'completed', ?, ?)`,
-		`INSERT INTO tasks (task_id, batch_id, order_id, sop_id, workstation_id, status, created_at, updated_at) VALUES ('T2', 1, 10, 41, 20, 'failed', ?, ?)`,
+		`INSERT INTO tasks (task_id, batch_id, order_id, sop_id, workstation_id, scene_id, subscene_id, scene_name, subscene_name, status, created_at, updated_at) VALUES ('T1', 1, 10, 40, 20, 70, 50, 'scene-a', 'sub-a', 'completed', ?, ?)`,
+		`INSERT INTO tasks (task_id, batch_id, order_id, sop_id, workstation_id, scene_id, subscene_id, scene_name, subscene_name, status, created_at, updated_at) VALUES ('T2', 1, 10, 41, 20, 70, 51, 'scene-a', 'sub-b', 'failed', ?, ?)`,
 	}
 	for i, stmt := range stmts {
 		if i < 2 {