From 58671e7bc3b1dde568fcff541e0fd5908240b7e2 Mon Sep 17 00:00:00 2001 From: rayd1o Date: Sun, 13 Sep 2026 10:27:00 +0800 Subject: [PATCH] release: bump version to 0.74.4 --- README.md | 2 +- VERSION | 2 +- aiprovider/Dockerfile | 10 +- backend/app/api/v1/settings.py | 47 +- backend/app/api/v1/tv.py | 7 +- backend/app/api/v1/visualization.py | 2 + backend/app/api/v1/websocket.py | 2 +- backend/app/core/websocket/broadcaster.py | 52 +- backend/app/core/websocket/manager.py | 28 +- .../services/collectors/news_live_streams.py | 4 +- .../app/services/earth_db_change_listener.py | 15 + backend/app/services/earth_layer_adapters.py | 1 + backend/app/services/llm_provider_catalog.py | 32 +- backend/app/services/tv_catalog.py | 148 ++++++ backend/app/services/tv_streams.py | 8 +- .../app/services/vessel_ais_aggregation.py | 12 + .../tests/test_earth_db_change_listener.py | 15 + backend/tests/test_llm_provider_catalog.py | 64 +++ backend/tests/test_settings_ai_provider.py | 67 +++ backend/tests/test_tv_catalog.py | 160 ++++++ backend/tests/test_websocket_manager.py | 74 ++- docs/CHANGELOG.md | 17 + ...earth-vessel-rendering-performance-plan.md | 2 + docs/technical/en/agents-aiprovider.md | 3 + docs/technical/en/backend-collectors.md | 12 +- .../en/data-job-earth-sync-architecture.md | 5 +- ...asource-collector-settings-connectivity.md | 2 +- docs/technical/en/earth-frontend-context.md | 20 +- .../en/earth-layer-style-reference.md | 2 + docs/technical/en/earth-render-layer-order.md | 10 +- docs/technical/en/manual.md | 11 + docs/technical/en/ops-planet-sh-startup.md | 32 +- docs/technical/en/ops-runbook.md | 4 +- docs/technical/en/quickstart.md | 5 +- docs/technical/zh/agents-aiprovider.md | 3 + docs/technical/zh/backend-collectors.md | 12 +- .../zh/data-job-earth-sync-architecture.md | 5 +- ...asource-collector-settings-connectivity.md | 2 +- docs/technical/zh/earth-frontend-context.md | 24 +- .../zh/earth-layer-style-reference.md | 2 + docs/technical/zh/earth-render-layer-order.md | 10 +- docs/technical/zh/manual.md | 11 + docs/technical/zh/ops-planet-sh-startup.md | 32 +- docs/technical/zh/ops-runbook.md | 4 +- docs/technical/zh/quickstart.md | 5 +- docs/version-history.md | 3 +- frontend/package.json | 2 +- frontend/public/earth/css/hud.css | 9 - frontend/public/earth/css/info-panel.css | 13 +- frontend/public/earth/css/tv-panel.css | 194 ++++++- frontend/public/earth/index.html | 4 +- frontend/public/earth/js/cable-batches.js | 176 +++++++ frontend/public/earth/js/cables.js | 19 + frontend/public/earth/js/constants.js | 1 + frontend/public/earth/js/i18n.js | 58 ++- frontend/public/earth/js/info-card.js | 223 ++++---- frontend/public/earth/js/interactable.js | 245 ++++++--- frontend/public/earth/js/main.js | 85 ++- .../earth/js/satellite-position-worker.js | 55 ++ .../public/earth/js/satellite-propagation.js | 290 +++++++++++ frontend/public/earth/js/satellites.js | 491 +++++------------- frontend/public/earth/js/tv-source-menu.js | 317 +++++++++++ frontend/public/earth/js/tv.js | 86 +-- frontend/public/earth/js/vessels.js | 133 ++++- .../src/admin/pages/PlainResourcePages.tsx | 17 +- frontend/src/i18n/legacy-ui.ts | 4 + planet.sh | 60 ++- pyproject.toml | 10 +- scripts/harness/frontend-smoke.mjs | 132 ++++- scripts/harness/test_database_startup.py | 158 ++++++ uv.lock | 18 +- 71 files changed, 2999 insertions(+), 791 deletions(-) create mode 100644 backend/app/services/tv_catalog.py create mode 100644 backend/tests/test_llm_provider_catalog.py create mode 100644 backend/tests/test_tv_catalog.py create mode 100644 frontend/public/earth/js/cable-batches.js create mode 100644 frontend/public/earth/js/satellite-position-worker.js create mode 100644 frontend/public/earth/js/satellite-propagation.js create mode 100644 frontend/public/earth/js/tv-source-menu.js diff --git a/README.md b/README.md index d1775aa1..97003d6b 100644 --- a/README.md +++ b/README.md @@ -324,7 +324,7 @@ ipconfig ## 启动容错参数 -`planet.sh` 现在为依赖安装、数据库、AI Provider 启动加入了有限次重试，并会在数据库与 `aiprovider` 启动后额外等待 Docker healthcheck。 +`planet.sh` 为依赖安装、数据库、AI Provider 启动提供有限次重试。数据库先检查容器健康，再验证后端实际连接；`aiprovider` 直接以宿主机 `/health` 就绪为准。后端进程退出或应用初始化失败时立即停止等待，避免重复消耗健康检查预算。 可通过环境变量临时调整: diff --git a/VERSION b/VERSION index a30a1640..7875aaed 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.74.3 +0.74.4 diff --git a/aiprovider/Dockerfile b/aiprovider/Dockerfile index 91ea40df..b0693425 100644 --- a/aiprovider/Dockerfile +++ b/aiprovider/Dockerfile @@ -7,9 +7,6 @@ ARG AI_PROVIDER_BUILD_FINGERPRINT=unknown FROM ${UV_IMAGE} AS uv FROM ${PYTHON_IMAGE} -ARG AI_PROVIDER_BUILD_FINGERPRINT -LABEL planet.aiprovider.build-fingerprint="${AI_PROVIDER_BUILD_FINGERPRINT}" - COPY --from=uv /uv /uvx /bin/ WORKDIR /app @@ -28,13 +25,16 @@ RUN apt-get update && apt-get install -y --no-install-recommends \ COPY pyproject.toml uv.lock /app/ RUN --mount=type=cache,target=/root/.cache/uv \ --mount=type=secret,id=planet_uv_config,target=/root/.config/uv/uv.toml,required=false \ - uv sync --frozen --no-dev + uv sync --frozen --only-group aiprovider COPY aiprovider /app/aiprovider +ARG AI_PROVIDER_BUILD_FINGERPRINT +LABEL planet.aiprovider.build-fingerprint="${AI_PROVIDER_BUILD_FINGERPRINT}" + EXPOSE 8010 HEALTHCHECK --interval=30s --timeout=5s --retries=3 \ CMD curl -fsS http://127.0.0.1:8010/health >/dev/null || exit 1 -CMD ["uv", "run", "--frozen", "--no-dev", "--project", "/app", "python", "-m", "uvicorn", "aiprovider.main:app", "--host", "0.0.0.0", "--port", "8010"] +CMD ["/app/.venv/bin/python", "-m", "uvicorn", "aiprovider.main:app", "--host", "0.0.0.0", "--port", "8010"] diff --git a/backend/app/api/v1/settings.py b/backend/app/api/v1/settings.py index c1dd55aa..8e768508 100644 --- a/backend/app/api/v1/settings.py +++ b/backend/app/api/v1/settings.py @@ -75,6 +75,7 @@ logger = get_logger(__name__, service="api") AI_PROVIDER_QUICK_CONNECT_TIMEOUT_SECONDS = 5 AI_CONNECTION_TEST_PROMPT_KEY = "ai.connection_test" SECRET_REVEAL_ROLES = {UserRole.ADMIN.value, UserRole.SUPER_ADMIN.value} +LLM_PROVIDER_PRESET_CATEGORY_PREFIX = "llm_provider_preset:" DEFAULT_SETTINGS = { "system": { @@ -2044,8 +2045,18 @@ async def reset_provider_credential_guide( @router.get("/integrations/ai-provider/presets") async def get_ai_provider_presets( current_user: User = Depends(get_current_user), + db: AsyncSession = Depends(get_db), ): - return {"data": list_fallback_llm_provider_presets()} + presets = list_fallback_llm_provider_presets() + saved = await get_setting_payloads( + db, [f"{LLM_PROVIDER_PRESET_CATEGORY_PREFIX}{preset['provider']}" for preset in presets] + ) + return { + "data": [ + {**preset, **saved[f"{LLM_PROVIDER_PRESET_CATEGORY_PREFIX}{preset['provider']}"]} + for preset in presets + ] + } @router.post("/integrations/ai-provider/presets/{provider}/refresh") @@ -2056,19 +2067,39 @@ async def refresh_ai_provider_preset( ): try: provider_id = _normalize_provider_id(provider) + get_fallback_llm_provider_preset(provider_id) + except ValueError as exc: + raise HTTPException(status_code=404, detail=str(exc)) from exc + + try: api_key = None if provider_id == "opencode-go": current_payload = await get_setting_payload(db, "external_integrations") ai_payload = _normalize_ai_provider_payload(current_payload.get("ai_provider") or {}) - provider_config = ai_payload["providers"].get(provider_id) or _provider_defaults(provider_id) + provider_config = ai_payload["providers"].get(provider_id) or _provider_defaults( + provider_id + ) api_key, _api_key_source = _resolve_provider_api_key(provider_id, provider_config) - return {"data": await refresh_llm_provider_preset(provider_id, api_key=api_key)} - except ValueError as exc: - raise HTTPException(status_code=404, detail=str(exc)) from exc + refreshed = await refresh_llm_provider_preset(provider_id, api_key=api_key) except Exception as exc: - fallback = get_fallback_llm_provider_preset(provider) - fallback["refresh_error"] = str(exc) - return {"data": fallback} + logger.warning( + "LLM provider catalog refresh failed", + extra={ + "event": "settings.ai_provider.catalog.failed", + "context": { + "provider": provider_id, + "error_type": type(exc).__name__, + }, + }, + ) + raise HTTPException( + status_code=502, + detail="模型列表刷新失败，已保留上次模型列表。", + ) from exc + + refreshed["refreshed_at"] = to_iso8601_utc(datetime.now(UTC)) + await save_setting_payload(db, f"{LLM_PROVIDER_PRESET_CATEGORY_PREFIX}{provider_id}", refreshed) + return {"data": refreshed} @router.put("/integrations") diff --git a/backend/app/api/v1/tv.py b/backend/app/api/v1/tv.py index 78687a5c..176ca426 100644 --- a/backend/app/api/v1/tv.py +++ b/backend/app/api/v1/tv.py @@ -7,6 +7,7 @@ from fastapi.responses import Response from sqlalchemy.ext.asyncio import AsyncSession from app.db.session import get_db +from app.services.tv_catalog import get_tv_catalog_page from app.services.tv_streams import get_public_tv_payload, is_allowed_tv_proxy_url router = APIRouter() @@ -34,9 +35,13 @@ def _should_strip_hls_metadata_line(line: str) -> bool: @router.get("/streams") async def list_public_tv_streams( + offset: int = Query(0, ge=0), + limit: int = Query(50, ge=1, le=100), + q: str = Query("", max_length=200), + selected_id: str | None = Query(None, max_length=200), db: AsyncSession = Depends(get_db), ): - return await get_public_tv_payload(db) + return await get_tv_catalog_page(db, offset=offset, limit=limit, q=q, selected_id=selected_id) @router.get("/proxy") diff --git a/backend/app/api/v1/visualization.py b/backend/app/api/v1/visualization.py index 12c2a4a8..732e606b 100644 --- a/backend/app/api/v1/visualization.py +++ b/backend/app/api/v1/visualization.py @@ -1121,6 +1121,7 @@ async def build_vessel_snapshot_response( safe_limit = _safe_vessel_limit(limit) safe_since_minutes = min(max(int(since_minutes or 60), 1), 1440) observed_since = datetime.now(UTC) - timedelta(minutes=safe_since_minutes) + snapshot_started_at = datetime.now(UTC) features, diagnostics = await _load_raw_vessel_snapshot_features( db, bbox=bbox, @@ -1137,6 +1138,7 @@ async def build_vessel_snapshot_response( "features": features, "count": len(features), "stats": _build_vessel_stats(features), + "generated_at": to_iso8601_utc(snapshot_started_at), "diagnostics": { **diagnostics, "filtered_count": len(features), diff --git a/backend/app/api/v1/websocket.py b/backend/app/api/v1/websocket.py index 4fa22eee..302a8073 100644 --- a/backend/app/api/v1/websocket.py +++ b/backend/app/api/v1/websocket.py @@ -161,7 +161,7 @@ async def websocket_endpoint( if is_anonymous: channels = [channel for channel in channels if channel in supported_channels] vessel_subscription = None - if "vessels" in channels and "bbox" in payload_data: + if "vessels" in channels: try: vessel_subscription = manager.subscribe_vessels(websocket, payload_data) except ValueError as exc: diff --git a/backend/app/core/websocket/broadcaster.py b/backend/app/core/websocket/broadcaster.py index 2e1f1cd8..d6d3bca5 100644 --- a/backend/app/core/websocket/broadcaster.py +++ b/backend/app/core/websocket/broadcaster.py @@ -4,11 +4,14 @@ import asyncio from datetime import UTC, datetime from typing import Dict, Any +from app.core.logging import get_logger from app.core.time import to_iso8601_utc from app.core.websocket.manager import manager EARTH_UPDATES_CHANNEL = "earth_updates" +VESSEL_STATE_QUERY_BATCH_SIZE = 1000 +logger = get_logger(__name__, service="websocket") class DataBroadcaster: @@ -114,16 +117,22 @@ class DataBroadcaster: return pending = self._pending_vessel_updates self._pending_vessel_updates = {} - vessels = [] - for item in pending.values(): - vessel = dict(item) - source = vessel.pop("_source", None) - action = vessel.pop("_action", "upsert") - created = vessel.pop("_created", None) - vessel["source"] = source - vessel["action"] = action - vessel["created"] = created - vessels.append(vessel) + try: + vessels = await self._load_current_vessel_updates(list(pending)) + except Exception: + # Preserve newer updates that arrived during the failed database read. + self._pending_vessel_updates = {**pending, **self._pending_vessel_updates} + raise + if not vessels: + return + vessels = [ + { + **vessel, + "action": vessel.get("action", "upsert"), + "created": pending.get(str(vessel["mmsi"]), {}).get("_created"), + } + for vessel in vessels + ] await manager.broadcast_vessels( { "action": "upsert", @@ -133,12 +142,31 @@ class DataBroadcaster: } ) + async def _load_current_vessel_updates(self, keys: list[str]) -> list[Dict[str, Any]]: + from app.db.session import async_session_factory + from app.services.vessel_ais_aggregation import get_current_vessels_by_mmsi + + mmsis = [int(key) for key in keys if key.isdigit()] + vessels = [] + async with async_session_factory() as db: + for offset in range(0, len(mmsis), VESSEL_STATE_QUERY_BATCH_SIZE): + vessels.extend(await get_current_vessels_by_mmsi( + db, mmsis[offset:offset + VESSEL_STATE_QUERY_BATCH_SIZE] + )) + present = {int(vessel["mmsi"]) for vessel in vessels} + vessels.extend({"mmsi": mmsi, "action": "remove"} for mmsi in mmsis if mmsi not in present) + return vessels + async def broadcast_vessels_periodically(self): while self.running: try: await self.flush_vessel_updates() - except Exception: - pass + except Exception as exc: + logger.exception_event( + "Failed to flush vessel updates", + event="vessels.broadcast.failed", + context={"error": str(exc)}, + ) await asyncio.sleep(self._vessel_flush_interval) async def broadcast_datasource_task_update(self, data: Dict[str, Any]): diff --git a/backend/app/core/websocket/manager.py b/backend/app/core/websocket/manager.py index 7d884f32..b0e72648 100644 --- a/backend/app/core/websocket/manager.py +++ b/backend/app/core/websocket/manager.py @@ -63,6 +63,8 @@ class ConnectionManager: def unsubscribe(self, websocket: WebSocket, channels: list[str]): for channel in {str(channel).strip() for channel in channels if str(channel).strip()}: + if channel == "vessels": + self.vessel_subscriptions.pop(websocket, None) subscribers = self.channel_subscriptions.get(channel) if subscribers is not None: subscribers.discard(websocket) @@ -88,7 +90,8 @@ class ConnectionManager: return subscription def _normalize_vessel_subscription(self, config: dict[str, Any]) -> dict[str, Any]: - bbox = config.get("bbox") + global_scope = config.get("scope") == "global" + bbox = [-180, -90, 180, 90] if global_scope else config.get("bbox") if not isinstance(bbox, (list, tuple)) or len(bbox) != 4: raise ValueError("vessels subscription requires bbox=[lon_min,lat_min,lon_max,lat_max]") try: @@ -103,7 +106,7 @@ class ConnectionManager: raise ValueError("bbox longitude values must be between -180 and 180") if not (-90 <= lat_min <= 90 and -90 <= lat_max <= 90): raise ValueError("bbox latitude values must be between -90 and 90") - if (lon_max - lon_min) * (lat_max - lat_min) > MAX_VESSEL_BBOX_AREA: + if not global_scope and (lon_max - lon_min) * (lat_max - lat_min) > MAX_VESSEL_BBOX_AREA: raise ValueError("bbox is too large; zoom in or request a smaller viewport") zoom = int(config.get("zoom") or 1) @@ -116,10 +119,11 @@ class ConnectionManager: if str(item).strip() } return { + "scope": "global" if global_scope else "viewport", "bbox": (lon_min, lat_min, lon_max, lat_max), "zoom": zoom, "limit": limit, - "type": vessel_types, + "type": sorted(vessel_types), "last_sent_at": None, } @@ -152,7 +156,9 @@ class ConnectionManager: vessel for vessel in vessels if self._vessel_matches_subscription(vessel, subscription) - ][: min(subscription["limit"], MAX_VESSEL_WS_MESSAGE_ITEMS)] + ] + if subscription.get("scope") != "global": + matched = matched[:subscription["limit"]] if not matched: continue subscription["last_sent_at"] = datetime.now(UTC) @@ -162,16 +168,24 @@ class ConnectionManager: "timestamp": subscription["last_sent_at"].isoformat(), "payload": { **data, - "vessels": matched, + "vessels": [], "subscription": { "bbox": list(subscription["bbox"]), "zoom": subscription["zoom"], "limit": subscription["limit"], + "scope": subscription.get("scope", "viewport"), }, }, } try: - await connection.send_json(message) + for offset in range(0, len(matched), MAX_VESSEL_WS_MESSAGE_ITEMS): + await connection.send_json({ + **message, + "payload": { + **message["payload"], + "vessels": matched[offset:offset + MAX_VESSEL_WS_MESSAGE_ITEMS], + }, + }) except Exception: self.unsubscribe_all(connection) @@ -180,6 +194,8 @@ class ConnectionManager: vessel: dict[str, Any], subscription: dict[str, Any], ) -> bool: + if vessel.get("action") == "remove" and subscription.get("scope") == "global": + return True try: lon = float(vessel.get("lon")) lat = float(vessel.get("lat")) diff --git a/backend/app/services/collectors/news_live_streams.py b/backend/app/services/collectors/news_live_streams.py index f3b89e99..81257c1a 100644 --- a/backend/app/services/collectors/news_live_streams.py +++ b/backend/app/services/collectors/news_live_streams.py @@ -35,7 +35,7 @@ class NewsLiveStreamsCollector(BaseCollector): DEFAULT_IPTV_ORG_LOGOS_URL = "https://iptv-org.github.io/api/logos.json" DEFAULT_IPTV_ORG_NEWS_CATEGORIES = ("news", "business", "weather") DEFAULT_IPTV_ORG_EXCLUDE_CATEGORIES = ("music", "sports", "kids", "entertainment") - DEFAULT_IPTV_ORG_MAX_SOURCES = 120 + DEFAULT_IPTV_ORG_MAX_SOURCES = 0 # Zero keeps the complete matching channel catalog. async def fetch(self) -> list[dict[str, Any]]: request_url = (self._resolved_url or "").strip() @@ -445,7 +445,7 @@ class NewsLiveStreamsCollector(BaseCollector): "reference_date": datetime.now(UTC).isoformat(), } ) - if len(normalized) >= max_sources: + if max_sources > 0 and len(normalized) >= max_sources: break return normalized diff --git a/backend/app/services/earth_db_change_listener.py b/backend/app/services/earth_db_change_listener.py index 4bd61946..82f3f20a 100644 --- a/backend/app/services/earth_db_change_listener.py +++ b/backend/app/services/earth_db_change_listener.py @@ -56,6 +56,8 @@ def build_earth_update_from_db_payload(payload: dict[str, Any]) -> dict[str, Any source_has_adapter = bool(get_earth_update_layers_for_source(source)) effective_source = source if source_has_adapter else (table_name if table_name else source) operation = payload.get("operation") + if "vessels" in layers and operation in {"DELETE", "TRUNCATE"}: + refresh_strategy = "reload" update: dict[str, Any] = { "event": "earth.layer.changed", "action": "database_changed", @@ -113,6 +115,8 @@ class PendingEarthDbChange: operation = payload.get("operation") if operation: self.operations.add(str(operation)) + if "vessels" in self.layers and operation in {"DELETE", "TRUNCATE"}: + self.refresh_strategy = "reload" entity_keys = payload.get("entity_keys") if not isinstance(entity_keys, list): entity_key = payload.get("entity_key") @@ -176,6 +180,17 @@ class EarthDbChangeDispatcher: if not update: return False + if payload.get("table") == "vessel_current_state" and payload.get("operation") == "DELETE": + from app.core.websocket.broadcaster import broadcaster + + keys = payload.get("entity_keys") + if not isinstance(keys, list): + keys = [payload.get("entity_key")] + broadcaster.enqueue_vessel_update({ + "action": "remove", + "vessels": [{"mmsi": key} for key in keys if key is not None], + }) + source = update["source"] pending = self._pending.get(source) if pending is None: diff --git a/backend/app/services/earth_layer_adapters.py b/backend/app/services/earth_layer_adapters.py index 078e6cd7..e48c69c5 100644 --- a/backend/app/services/earth_layer_adapters.py +++ b/backend/app/services/earth_layer_adapters.py @@ -25,6 +25,7 @@ EARTH_LAYER_ADAPTERS: tuple[EarthLayerAdapter, ...] = ( layers=("vessels",), cache_patterns=("vessels*", "summary*"), derived_models=("ais_raw_observations", "ais_conflict_records", "ais_source_health"), + refresh_strategy="delta", ), EarthLayerAdapter( sources=frozenset( diff --git a/backend/app/services/llm_provider_catalog.py b/backend/app/services/llm_provider_catalog.py index 0ef9e06f..96cd755c 100644 --- a/backend/app/services/llm_provider_catalog.py +++ b/backend/app/services/llm_provider_catalog.py @@ -9,6 +9,11 @@ import httpx MODELS_DEV_URL = "https://models.dev/api.json" OPENCODE_GO_MODELS_URL = "https://opencode.ai/zen/go/v1/models" + +class LLMProviderCatalogError(RuntimeError): + """The upstream catalog cannot supply a usable model list.""" + + OPENCODE_GO_MODEL_PROVIDER_APIS = { "minimax-m2.7": "anthropic-messages", "minimax-m2.5": "anthropic-messages", @@ -171,9 +176,9 @@ async def refresh_llm_provider_preset(provider: str, api_key: str | None = None) str(item.get("id")) for item in data if isinstance(item, dict) and item.get("id") - ][:120] + ] if not model_ids: - model_ids = fallback["models"] + raise LLMProviderCatalogError("The provider returned an empty model catalog") return { **fallback, "model": fallback["model"] if fallback["model"] in model_ids else model_ids[0], @@ -184,7 +189,7 @@ async def refresh_llm_provider_preset(provider: str, api_key: str | None = None) models_dev_key = MODELS_DEV_PROVIDER_KEYS.get(fallback["provider"]) if not models_dev_key: - return fallback + raise LLMProviderCatalogError("Live catalog refresh is unavailable for this provider") async with httpx.AsyncClient(timeout=15.0, follow_redirects=True) as client: response = await client.get( @@ -194,12 +199,23 @@ async def refresh_llm_provider_preset(provider: str, api_key: str | None = None) response.raise_for_status() catalog = response.json() - upstream = catalog.get(models_dev_key) + upstream = catalog.get(models_dev_key) if isinstance(catalog, dict) else None if not isinstance(upstream, dict): - return fallback + raise LLMProviderCatalogError("The provider is missing from the model catalog") upstream_models = upstream.get("models") if isinstance(upstream.get("models"), dict) else {} - model_ids = list(upstream_models.keys())[:80] + # Catalog insertion order is not release order; old entries can appear first. + model_ids = sorted( + ( + model_id + for model_id, model in upstream_models.items() + if model_id and isinstance(model, dict) + ), + key=lambda model_id: (str(upstream_models[model_id].get("release_date") or ""), model_id), + reverse=True, + ) + if not model_ids: + raise LLMProviderCatalogError("The provider returned an empty model catalog") base_url = upstream.get("api") or fallback["base_url"] if fallback["provider"] == "deepseek" and base_url == "https://api.deepseek.com": base_url = "https://api.deepseek.com/v1" @@ -208,8 +224,8 @@ async def refresh_llm_provider_preset(provider: str, api_key: str | None = None) **fallback, "label": upstream.get("name") or fallback["label"], "base_url": base_url, - "model": model_ids[0] if model_ids else fallback["model"], - "models": model_ids or fallback["models"], + "model": model_ids[0], + "models": model_ids, "api_key_env": (upstream.get("env") or [fallback["api_key_env"]])[0], "source": MODELS_DEV_URL, } diff --git a/backend/app/services/tv_catalog.py b/backend/app/services/tv_catalog.py new file mode 100644 index 00000000..53d18903 --- /dev/null +++ b/backend/app/services/tv_catalog.py @@ -0,0 +1,148 @@ +"""Search and paginate the public live TV catalog at the database boundary.""" + +from typing import Any + +from sqlalchemy import Select, func, select +from sqlalchemy.ext.asyncio import AsyncSession + +from app.core.time import to_iso8601_utc +from app.models.collected_data import CollectedData +from app.services.tv_streams import ( + TV_LIVE_SOURCE_COLLECTOR, + TV_LIVE_SOURCE_DATA_TYPE, + _build_collected_tv_source, + build_public_tv_payload, + get_tv_settings_payload, +) + + +def _source_key(): + return func.coalesce( + func.nullif(CollectedData.extra_data["id"].as_string(), ""), + func.nullif(CollectedData.source_id, ""), + CollectedData.entity_key, + ) + + +def _collected_catalog_query(configured_ids: list[str]) -> Select[tuple[CollectedData]]: + metadata = CollectedData.extra_data + source_id = _source_key() + enabled = func.lower(func.trim(func.coalesce(metadata["is_enabled"].as_string(), "true"))) + ranked = ( + select( + CollectedData.id, + func.row_number() + .over( + partition_by=source_id, + order_by=CollectedData.id.desc(), + ) + .label("source_rank"), + ) + .where( + CollectedData.source == TV_LIVE_SOURCE_COLLECTOR, + CollectedData.data_type == TV_LIVE_SOURCE_DATA_TYPE, + CollectedData.is_current.is_(True), + CollectedData.is_valid == 1, + CollectedData.deleted_at.is_(None), + enabled.notin_(("false", "0", "no", "off")), + source_id.notin_(configured_ids), + ) + .subquery() + ) + return ( + select(CollectedData) + .join(ranked, ranked.c.id == CollectedData.id) + .where(ranked.c.source_rank == 1) + ) + + +def _filter_catalog_query( + query: Select[tuple[CollectedData]], terms: list[str] +) -> Select[tuple[CollectedData]]: + metadata = CollectedData.extra_data + searchable = func.lower( + func.concat_ws( + " ", + CollectedData.name, + CollectedData.title, + CollectedData.source_id, + metadata["name"].as_string(), + metadata["provider"].as_string(), + metadata["region"].as_string(), + metadata["country"].as_string(), + metadata["language"].as_string(), + ) + ) + for term in terms: + query = query.where(searchable.contains(term, autoescape=True)) + return query + + +def _matches_source(source: dict[str, Any], terms: list[str]) -> bool: + searchable = " ".join( + str(source.get(key) or "") for key in ("id", "name", "provider", "region", "language") + ).lower() + return all(term in searchable for term in terms) + + +async def get_tv_catalog_page( + db: AsyncSession, + *, + offset: int = 0, + limit: int = 50, + q: str = "", + selected_id: str | None = None, +) -> dict[str, Any]: + settings = await get_tv_settings_payload(db) + payload = build_public_tv_payload(settings, []) + configured = payload["sources"] + query = _collected_catalog_query([source["id"] for source in settings["sources"]]) + if selected_id: + selected = next((source for source in configured if source["id"] == selected_id), None) + if selected is None: + record = await db.scalar(query.where(_source_key() == selected_id).limit(1)) + selected = _build_collected_tv_source(record, 0) if record else None + if selected: + payload["selected_source"] = selected + summary = ( + await db.execute( + select(func.count(), func.max(CollectedData.collected_at)) + .select_from(CollectedData) + .where(CollectedData.id.in_(query.with_only_columns(CollectedData.id))) + ) + ).one() + total_collected, latest_update = summary + terms = q.lower().split() + matched_configured = [source for source in configured if _matches_source(source, terms)] + filtered_query = _filter_catalog_query(query, terms) + matched_collected = ( + await db.scalar(select(func.count()).select_from(filtered_query.subquery())) + if terms + else total_collected + ) + sources = matched_configured[offset : offset + limit] + remaining = limit - len(sources) + if remaining: + rows = await db.scalars( + filtered_query.order_by(func.lower(CollectedData.name), CollectedData.id) + .offset(max(0, offset - len(matched_configured))) + .limit(remaining) + ) + sources.extend( + _build_collected_tv_source(record, index) for index, record in enumerate(rows) + ) + total = len(matched_configured) + matched_collected + next_offset = offset + len(sources) + return { + **payload, + "sources": sources, + "source_count": len(configured) + total_collected, + "latest_updated_at": ( + to_iso8601_utc(latest_update) if latest_update else payload["latest_updated_at"] + ), + "total": total, + "offset": offset, + "limit": limit, + "has_more": next_offset < total, + "next_offset": next_offset if next_offset < total else None, + } diff --git a/backend/app/services/tv_streams.py b/backend/app/services/tv_streams.py index 63e97f91..cdee7c32 100644 --- a/backend/app/services/tv_streams.py +++ b/backend/app/services/tv_streams.py @@ -11,7 +11,7 @@ from app.core.time import to_iso8601_utc from app.models.collected_data import CollectedData from app.models.system_setting import SystemSetting -DEFAULT_TV_SOURCE_ID = "cgtn-en" +DEFAULT_TV_SOURCE_ID = "aljazeera-mubasher" TV_SETTINGS_CATEGORY = "tv" TV_LIVE_SOURCE_COLLECTOR = "news_live_streams" TV_LIVE_SOURCE_DATA_TYPE = "news_live_stream" @@ -300,8 +300,12 @@ def normalize_tv_settings(payload: dict[str, Any] | None) -> dict[str, Any]: ] if not any(source["id"] == DEFAULT_TV_SOURCE_ID for source in normalized_sources): + default_source = next( + source for source in DEFAULT_TV_SETTINGS["sources"] + if source["id"] == DEFAULT_TV_SOURCE_ID + ) normalized_sources.append( - normalize_tv_source(DEFAULT_TV_SETTINGS["sources"][0], index=len(normalized_sources)) + normalize_tv_source(default_source, index=len(normalized_sources)) ) default_source_exists = any( diff --git a/backend/app/services/vessel_ais_aggregation.py b/backend/app/services/vessel_ais_aggregation.py index 3298fca2..ad45490c 100644 --- a/backend/app/services/vessel_ais_aggregation.py +++ b/backend/app/services/vessel_ais_aggregation.py @@ -614,6 +614,18 @@ async def get_current_vessels_snapshot( return [item.to_dict() for item in result.scalars().all()] +async def get_current_vessels_by_mmsi( + db: AsyncSession, mmsis: list[int] +) -> list[dict[str, Any]]: + """Read canonical render state for the vessels changed by a stream flush.""" + if not mmsis: + return [] + result = await db.execute( + select(VesselCurrentState).where(VesselCurrentState.mmsi.in_(mmsis)) + ) + return [_jsonable(item.to_dict()) for item in result.scalars().all()] + + async def aggregate_vessel_observations( db: AsyncSession, observations: Iterable[AISRawObservation], diff --git a/backend/tests/test_earth_db_change_listener.py b/backend/tests/test_earth_db_change_listener.py index 1100c90d..ab6a29d2 100644 --- a/backend/tests/test_earth_db_change_listener.py +++ b/backend/tests/test_earth_db_change_listener.py @@ -63,6 +63,21 @@ def test_build_earth_update_maps_derived_tables_to_layers(): assert vessel_update is not None assert vessel_update["source"] == "vessel_position" assert vessel_update["layers"] == ["vessels"] + assert vessel_update["refresh_strategy"] == "reload" + + +def test_vessel_stream_changes_do_not_request_full_layer_rebuilds(): + from app.services.earth_db_change_listener import PendingEarthDbChange + + for source in ("aisstream_vessels", "barentswatch_vessels"): + update = build_earth_update_from_db_payload({ + "source": source, "table": "vessel_current_state", "operation": "UPDATE", + }) + assert update["refresh_strategy"] == "delta" + pending = PendingEarthDbChange(source=source, layers=["vessels"], refresh_strategy="delta") + pending.add({"operation": "UPDATE"}) + pending.add({"operation": "DELETE"}) + assert pending.refresh_strategy == "reload" def test_build_earth_update_maps_interactable_delete_to_delta(): diff --git a/backend/tests/test_llm_provider_catalog.py b/backend/tests/test_llm_provider_catalog.py new file mode 100644 index 00000000..cb80f8f1 --- /dev/null +++ b/backend/tests/test_llm_provider_catalog.py @@ -0,0 +1,64 @@ +import httpx +import pytest + +from app.services import llm_provider_catalog as catalog + + +def mock_catalog(monkeypatch, payload): + client_type = httpx.AsyncClient + transport = httpx.MockTransport(lambda request: httpx.Response(200, json=payload)) + monkeypatch.setattr( + catalog.httpx, "AsyncClient", lambda **kwargs: client_type(transport=transport, **kwargs) + ) + + +@pytest.mark.asyncio +async def test_refresh_orders_by_release_date_before_choosing_default(monkeypatch): + mock_catalog( + monkeypatch, + { + "minimax": { + "models": { + "MiniMax-M2": {"release_date": "2025-10-27"}, + "MiniMax-M3": {"release_date": "2026-06-01"}, + "MiniMax-M2.7": {"release_date": "2026-03-18"}, + "undated-model": {}, + } + } + }, + ) + + refreshed = await catalog.refresh_llm_provider_preset("minimax") + + assert refreshed["model"] == "MiniMax-M3" + assert refreshed["models"] == ["MiniMax-M3", "MiniMax-M2.7", "MiniMax-M2", "undated-model"] + assert refreshed["source"] == catalog.MODELS_DEV_URL + + +@pytest.mark.asyncio +async def test_refresh_does_not_truncate_new_models(monkeypatch): + models = {f"older-{index}": {"release_date": "2025-01-01"} for index in range(85)} + models["latest"] = {"release_date": "2026-06-01"} + mock_catalog(monkeypatch, {"minimax": {"models": models}}) + + refreshed = await catalog.refresh_llm_provider_preset("minimax") + + assert refreshed["model"] == "latest" + assert len(refreshed["models"]) == 86 + + +@pytest.mark.asyncio +@pytest.mark.parametrize("payload", [{}, {"minimax": {"models": {}}}, {"minimax": []}]) +async def test_invalid_catalog_fails_instead_of_claiming_fallback_is_fresh(monkeypatch, payload): + mock_catalog(monkeypatch, payload) + + with pytest.raises(catalog.LLMProviderCatalogError): + await catalog.refresh_llm_provider_preset("minimax") + + +@pytest.mark.asyncio +async def test_empty_opencode_catalog_is_a_refresh_failure(monkeypatch): + mock_catalog(monkeypatch, {"data": []}) + + with pytest.raises(catalog.LLMProviderCatalogError): + await catalog.refresh_llm_provider_preset("opencode-go", api_key="test-key") diff --git a/backend/tests/test_settings_ai_provider.py b/backend/tests/test_settings_ai_provider.py index 4d5612c4..982e4056 100644 --- a/backend/tests/test_settings_ai_provider.py +++ b/backend/tests/test_settings_ai_provider.py @@ -1,5 +1,7 @@ +from copy import deepcopy from types import SimpleNamespace +import httpx import pytest from app.api.v1 import settings as settings_api @@ -24,6 +26,71 @@ from app.api.v1.settings import ( from app.services.llm_provider_catalog import get_fallback_llm_provider_preset +@pytest.mark.asyncio +async def test_refreshed_presets_survive_listing_without_changing_runtime_settings(monkeypatch): + stored = { + "external_integrations": { + "ai_provider": { + "default_provider": "minimax", + "service_token": "internal-token", + "providers": {"minimax": {"model": "custom-model", "api_key": "provider-key"}}, + } + } + } + runtime_before = deepcopy(stored["external_integrations"]) + + async def fake_save(_db, category, payload): + stored[category] = deepcopy(payload) + return stored[category] + + async def fake_get_many(_db, categories): + return {category: deepcopy(stored.get(category, {})) for category in categories} + + async def fake_refresh(provider, api_key=None): + return { + **get_fallback_llm_provider_preset(provider), + "model": "new-model", + "models": ["new-model", "older-model"], + "source": "https://models.dev/api.json", + } + + monkeypatch.setattr(settings_api, "save_setting_payload", fake_save) + monkeypatch.setattr(settings_api, "get_setting_payloads", fake_get_many) + monkeypatch.setattr(settings_api, "refresh_llm_provider_preset", fake_refresh) + user = SimpleNamespace(id=1, role="admin") + + await settings_api.refresh_ai_provider_preset("minimax", user, object()) + await settings_api.refresh_ai_provider_preset("openai", user, object()) + listed = await settings_api.get_ai_provider_presets(user, object()) + presets = {preset["provider"]: preset for preset in listed["data"]} + + assert presets["minimax"]["models"] == ["new-model", "older-model"] + assert presets["openai"]["model"] == "new-model" + assert presets["anthropic"]["source"] == "fallback" + assert presets["minimax"]["refreshed_at"] + assert stored["external_integrations"] == runtime_before + assert "provider-key" not in str(listed) + assert "internal-token" not in str(listed) + + +@pytest.mark.asyncio +async def test_failed_preset_refresh_is_an_error_and_does_not_save(monkeypatch): + async def fail_refresh(*args, **kwargs): + raise httpx.ConnectError("upstream error with secret-value") + + async def fail_save(*args, **kwargs): + pytest.fail("failed refresh must preserve the last saved preset") + + monkeypatch.setattr(settings_api, "refresh_llm_provider_preset", fail_refresh) + monkeypatch.setattr(settings_api, "save_setting_payload", fail_save) + + with pytest.raises(settings_api.HTTPException) as error: + await settings_api.refresh_ai_provider_preset("minimax", SimpleNamespace(id=1), object()) + + assert error.value.status_code == 502 + assert "secret-value" not in error.value.detail + + @pytest.fixture(autouse=True) def isolated_ai_provider_env_file(monkeypatch, tmp_path): env_file = tmp_path / ".env" diff --git a/backend/tests/test_tv_catalog.py b/backend/tests/test_tv_catalog.py new file mode 100644 index 00000000..3d5e7fe8 --- /dev/null +++ b/backend/tests/test_tv_catalog.py @@ -0,0 +1,160 @@ +from datetime import UTC, datetime +from unittest.mock import AsyncMock + +import pytest +from sqlalchemy import create_engine, event +from sqlalchemy.orm import Session + +from app.db.session import Base +from app.models.collected_data import CollectedData +from app.models.data_snapshot import DataSnapshot +from app.models.system_setting import SystemSetting +from app.models.task import CollectionTask +from app.services.collectors.news_live_streams import NewsLiveStreamsCollector +from app.services.tv_catalog import get_tv_catalog_page +from app.services.tv_streams import normalize_tv_settings + + +class CatalogSession: + """Execute the real catalog queries against an isolated SQLite database.""" + + def __init__(self, session): + self.session = session + + async def execute(self, query): + return self.session.execute(query) + + async def scalar(self, query): + return self.session.scalar(query) + + async def scalars(self, query): + return self.session.scalars(query) + + +@pytest.fixture +def catalog_db(): + engine = create_engine("sqlite:///:memory:") + + @event.listens_for(engine, "connect") + def register_functions(connection, _record): + connection.create_function( + "concat_ws", + -1, + lambda sep, *args: sep.join(str(arg) for arg in args if arg is not None), + ) + + Base.metadata.create_all( + engine, + tables=[ + CollectionTask.__table__, + DataSnapshot.__table__, + CollectedData.__table__, + SystemSetting.__table__, + ], + ) + with Session(engine) as session: + for index in range(135): + session.add( + CollectedData( + source="news_live_streams", + source_id=f"channel-{index:03}", + data_type="news_live_stream", + name=f"Channel {index:03}", + collected_at=datetime(2026, 9, 13, tzinfo=UTC), + is_current=True, + is_valid=1, + extra_data={ + "stream_url": "https://example.invalid/live.m3u8", + "region": "Canada", + }, + ) + ) + session.flush() + yield CatalogSession(session) + engine.dispose() + + +@pytest.mark.asyncio +async def test_pages_include_entire_catalog_without_overlap(catalog_db): + first = await get_tv_catalog_page(catalog_db, limit=50) + second = await get_tv_catalog_page(catalog_db, offset=first["next_offset"], limit=50) + third = await get_tv_catalog_page(catalog_db, offset=second["next_offset"], limit=50) + ids = [source["id"] for page in (first, second, third) for source in page["sources"]] + assert [len(page["sources"]) for page in (first, second, third)] == [50, 50, 45] + assert len(set(ids)) == first["source_count"] == 145 + assert ids[-1] == "channel-134" + assert third["next_offset"] is None and not third["has_more"] + beyond = await get_tv_catalog_page(catalog_db, offset=200) + assert beyond["sources"] == [] and not beyond["has_more"] + + +@pytest.mark.asyncio +async def test_search_finds_later_pages_and_treats_wildcards_literally(catalog_db): + payload = await get_tv_catalog_page(catalog_db, q="CANADA 134") + assert [source["id"] for source in payload["sources"]] == ["channel-134"] + assert payload["total"] == 1 and payload["source_count"] == 145 + assert (await get_tv_catalog_page(catalog_db, q="%"))["total"] == 0 + + +@pytest.mark.asyncio +async def test_selection_survives_refresh_when_outside_first_page(catalog_db): + payload = await get_tv_catalog_page(catalog_db, selected_id="channel-134") + assert payload["selected_source"]["id"] == "channel-134" + assert "channel-134" not in [source["id"] for source in payload["sources"]] + assert payload["default_source_id"] == "aljazeera-mubasher" + default = (await get_tv_catalog_page(catalog_db, selected_id="removed"))["selected_source"] + assert default["id"] == "aljazeera-mubasher" and default["source_type"] == "hls" + + +@pytest.mark.asyncio +async def test_catalog_hides_inactive_records_and_deduplicates_ids(catalog_db): + for name, values in [ + ("Disabled", {"extra_data": {"is_enabled": False}}), + ("Historical", {"is_current": False}), + ("Invalid", {"is_valid": 0}), + ("Deleted", {"deleted_at": datetime.now(UTC)}), + ("Replacement", {"source_id": "channel-134"}), + ]: + record = dict( + source="news_live_streams", + source_id=name, + name=name, + data_type="news_live_stream", + is_current=True, + is_valid=1, + ) + catalog_db.session.add(CollectedData(**{**record, **values})) + catalog_db.session.flush() + payload = await get_tv_catalog_page(catalog_db, q="replacement") + assert payload["source_count"] == 145 + assert [source["id"] for source in payload["sources"]] == ["channel-134"] + + +def test_missing_builtin_default_adds_aljazeera_without_losing_custom_source(): + settings = normalize_tv_settings({"sources": [{"id": "custom", "name": "Custom"}]}) + assert settings["default_source_id"] == "aljazeera-mubasher" + assert {source["id"] for source in settings["sources"]} == {"custom", "aljazeera-mubasher"} + + +@pytest.mark.asyncio +@pytest.mark.parametrize( + "config, expected", [({}, 135), ({"max_sources": 0}, 135), ({"max_sources": 7}, 7)] +) +async def test_collector_keeps_all_matching_channels_unless_explicitly_limited( + monkeypatch, config, expected +): + collector = NewsLiveStreamsCollector() + channels = [ + {"id": f"channel-{i}", "name": f"Channel {i}", "categories": ["news"]} for i in range(135) + ] + channels.append({"id": "sport", "name": "Sports", "categories": ["sports"]}) + streams = [ + {"channel": channel["id"], "url": "https://example.invalid/live.m3u8"} + for channel in channels + ] + monkeypatch.setattr( + collector, "_gather_iptv_org_payloads", AsyncMock(return_value=(channels, streams, [])) + ) + records = await collector._fetch_iptv_org("https://example.invalid/channels.json", config) + assert len(records) == expected + assert all(record["source_id"] != "sport" for record in records) diff --git a/backend/tests/test_websocket_manager.py b/backend/tests/test_websocket_manager.py index aa8ac02b..b4e06ed1 100644 --- a/backend/tests/test_websocket_manager.py +++ b/backend/tests/test_websocket_manager.py @@ -1,5 +1,9 @@ -import pytest import importlib +import json + +import pytest +from fastapi import FastAPI +from fastapi.testclient import TestClient from app.core.websocket.manager import ConnectionManager from app.core.websocket.broadcaster import DataBroadcaster @@ -113,6 +117,11 @@ async def test_vessel_broadcaster_keeps_latest_update_per_mmsi(monkeypatch): broadcaster_module = importlib.import_module("app.core.websocket.broadcaster") monkeypatch.setattr(broadcaster_module.manager, "broadcast_vessels", fake_broadcast_vessels) broadcaster = DataBroadcaster() + async def load_current(keys): + assert keys == ["1"] + return [{"mmsi": 1, "lat": 60.0, "lon": 11.0, "source": "barentswatch_vessels"}] + + monkeypatch.setattr(broadcaster, "_load_current_vessel_updates", load_current) broadcaster.enqueue_vessel_update( { "source": "aisstream_vessels", @@ -129,10 +138,67 @@ async def test_vessel_broadcaster_keeps_latest_update_per_mmsi(monkeypatch): assert sent[0]["vessels"] == [ { "mmsi": 1, - "lat": 59.1, - "lon": 10.1, - "source": "aisstream_vessels", + "lat": 60.0, + "lon": 11.0, + "source": "barentswatch_vessels", "action": "upsert", "created": None, } ] + + +@pytest.mark.asyncio +async def test_global_vessel_subscription_delivers_every_item_in_bounded_frames(): + manager = ConnectionManager() + socket = FakeWebSocket() + config = manager.subscribe_vessels(socket, {"scope": "global", "zoom": 4}) + json.dumps(config) + vessels = [{"mmsi": index, "lat": 60, "lon": 10} for index in range(2501)] + await manager.broadcast_vessels({"vessels": vessels}) + + assert [len(frame["payload"]["vessels"]) for frame in socket.sent] == [1000, 1000, 501] + assert [item for frame in socket.sent for item in frame["payload"]["vessels"]] == vessels + manager.unsubscribe(socket, ["vessels"]) + await manager.broadcast_vessels({"vessels": vessels}) + assert len(socket.sent) == 3 + + +@pytest.mark.asyncio +async def test_global_vessel_removal_does_not_require_coordinates(): + manager = ConnectionManager() + socket = FakeWebSocket() + manager.subscribe_vessels(socket, {"scope": "global", "zoom": 4}) + await manager.broadcast_vessels({"vessels": [{"mmsi": 123, "action": "remove"}]}) + assert socket.sent[0]["payload"]["vessels"] == [{"mmsi": 123, "action": "remove"}] + + +def test_anonymous_earth_can_confirm_global_vessel_subscription(monkeypatch): + websocket_module = importlib.import_module("app.api.v1.websocket") + monkeypatch.setattr(websocket_module, "manager", ConnectionManager()) + app = FastAPI() + app.include_router(websocket_module.router) + with TestClient(app) as client, client.websocket_connect("/ws") as socket: + assert socket.receive_json()["type"] == "connection_established" + socket.send_json({ + "type": "subscribe", + "data": {"channels": ["earth_updates", "vessels"], "scope": "global", "zoom": 4}, + }) + response = socket.receive_json() + assert response["type"] == "subscription_confirmed" + assert response["data"]["vessels"]["scope"] == "global" + assert response["data"]["vessels"]["type"] == [] + + +@pytest.mark.asyncio +async def test_vessel_flush_retries_without_overwriting_newer_queued_updates(monkeypatch): + broadcaster = DataBroadcaster() + broadcaster.enqueue_vessel_update({"vessels": [{"mmsi": 1, "lat": 59, "lon": 10}]}) + + async def fail_read(_keys): + broadcaster.enqueue_vessel_update({"vessels": [{"mmsi": 1, "lat": 61, "lon": 12}]}) + raise RuntimeError("database unavailable") + + monkeypatch.setattr(broadcaster, "_load_current_vessel_updates", fail_read) + with pytest.raises(RuntimeError, match="database unavailable"): + await broadcaster.flush_vessel_updates() + assert broadcaster._pending_vessel_updates["1"]["lat"] == 61 diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 720d9b98..6a20de18 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -8,6 +8,23 @@ This project follows the repository versioning rule: - `improvement` -> `+0.0.1`（bugfix + 小功能混合） - `bugfix` -> `+0.0.1` +## [0.74.4] — 2026-09-13 + +Released: 2026-09-13 + +### Highlights +- 保留 Earth 全量对象与交互，优化海缆、登陆点和卫星绘制，并让 AIS / BarentsWatch 船只通过确认状态增量更新。 +- 新闻直播支持完整频道目录搜索和无限滚动；模型目录刷新可保存结果，启动流程减少不必要的依赖安装与等待。 + +### Added / Fixed / Improved +- 海缆和登陆点合批绘制，卫星 SGP4 计算移入 Worker、呼吸动画移入 GPU，并缩小动态文本的翻译扫描范围。 +- 船舶全局订阅按 MMSI 合并、拆包和原位更新，保留选择状态，并处理删除、重连及旧快照覆盖。 +- 新闻直播取消默认 120 项采集截断，增加数据库分页、完整目录搜索和固定计数栏，默认源改为半岛电视台 HLS。 +- 算力中心定位队列在当前 Earth 页面内独立于详情面板继续运行；模型刷新保存新目录并保留当前模型、凭证草稿与失败前目录。 +- AI Provider 镜像使用独立依赖组，容器直接运行已安装环境；启动提前验证数据库、及时识别后端失败，并保留可复用容器。 + +--- + ## [0.74.3] — 2026-09-13 Released: 2026-09-13 diff --git a/docs/plans/earth-vessel-rendering-performance-plan.md b/docs/plans/earth-vessel-rendering-performance-plan.md index 37956069..e8597959 100644 --- a/docs/plans/earth-vessel-rendering-performance-plan.md +++ b/docs/plans/earth-vessel-rendering-performance-plan.md @@ -2,6 +2,8 @@ ## 当前状态 +最新实现继续保留分桶 `Points` 与全局数据范围，并已接通 `vessels` 全局实时订阅：后端读取确认状态后按 MMSI 拆包推送，前端原位修改缓冲；快照用于首次加载、重连和删除校准。旧快照不能覆盖较新的更新或删除，旋转与缩放仍不触发视口请求。下方 Sprite 问题分析和阶段方案保留为历史背景，当前约束以[地球前端上下文](../technical/zh/earth-frontend-context.md)为准。 + 该计划的前端核心部分已经在 `0.44.1` 落地，但最终实现不是原文设想的 `InstancedBufferGeometry` quad，而是更稳的分桶 `THREE.Points` 方案： - 普通船只按 moving / anchored 和 `VESSEL_COURSE_BINS` 航向分桶，使用 `PointsMaterial` 批量绘制。 diff --git a/docs/technical/en/agents-aiprovider.md b/docs/technical/en/agents-aiprovider.md index 9c864942..bfcbbd32 100644 --- a/docs/technical/en/agents-aiprovider.md +++ b/docs/technical/en/agents-aiprovider.md @@ -95,12 +95,15 @@ The AI settings page uses: - `POST /api/v1/settings/integrations/ai-provider/connect` - `GET /api/v1/settings/integrations/ai-provider/secrets` - `GET /api/v1/settings/integrations/ai-provider/presets` +- `POST /api/v1/settings/integrations/ai-provider/presets/{provider}/refresh` - `GET /api/v1/settings/ai-prompts` - `PUT /api/v1/settings/ai-prompts/{task_key}` - `POST /api/v1/settings/ai-prompts/{task_key}/reset` These endpoints require an authenticated user. The `secrets` endpoint is only used when the settings page reveals a key or token; hiding the field restores the masked preview. +`backend/app/services/llm_provider_catalog.py` refreshes catalogs from models.dev for most providers and from OpenCode Go's own models endpoint for that provider. Entries from models.dev are sorted by release date, newest first, with undated entries last. Successful results and `refreshed_at` are stored per provider in the `system_settings` category `llm_provider_preset:`. Listing prefers saved catalogs and uses bundled presets for providers that have not been refreshed. Refresh does not write the active model, protocol, URLs, or credentials in `external_integrations`. Failure returns 502 and preserves the previous catalog without exposing raw upstream errors. The frontend reloads catalog state while retaining the form draft. + Admin keeps the AI page aligned with the legacy information architecture: - `Model Providers` diff --git a/docs/technical/en/backend-collectors.md b/docs/technical/en/backend-collectors.md index ad805e91..82074691 100644 --- a/docs/technical/en/backend-collectors.md +++ b/docs/technical/en/backend-collectors.md @@ -111,6 +111,12 @@ Snapshot lists should not show every snapshot of the same collector as separate Credential guides are maintained by `backend/app/services/credential_guides.py`. The console uses read / generate / reset actions to load or create Markdown instructions. The frontend should render the guide Markdown for operators, not expose generation prompts or raw metadata. +### News Live Stream Catalog + +The IPTV-org adapter in `news_live_streams` retains its news-category filters. Its default `max_sources` is `0`, meaning all matching channels; an explicit positive value still limits collection. Existing configurations retaining the old `120` limit must change it to `0` and collect again to populate the complete catalog. + +`GET /api/v1/tv/streams` uses database pagination in `tv_catalog.py`: `offset` defaults to `0`, `limit` defaults to `50` with a maximum of `100`, and whitespace-separated `q` terms match channel names, providers, regions, and languages. Built-in and configured sources come first. Collected sources are deduplicated by channel ID, exclude configured overrides, and are filtered, counted, sorted, and paginated in SQL. The response's `total` counts matches, while `source_count` counts the complete available catalog; use `has_more` and `next_offset` for subsequent pages. `selected_id` can also return the selected channel outside the current page without consuming its quota. `tv_streams.py` remains the owner of default and fallback sources. + ## IV. Data Format (stored in CollectedData table) ```python @@ -352,7 +358,11 @@ GET /api/v1/visualization/vessels/{mmsi}/conflicts `/api/v1/vessels/snapshot` requires `bbox` and `zoom`, and caps `limit` at `5000`. The Earth frontend uses a global bbox for current state and does not refetch on camera viewport changes. The endpoint reads `vessel_current_state` and reports `diagnostics.source = "vessel_current_state"`. The old `/api/v1/visualization/geo/vessels` route has been removed. -High-frequency AIS updates must not become per-delta full-layer rebuilds. If Earth uses the `/ws` `vessels` channel, it should send low-frequency reload/dirty hints and let the frontend merge snapshot refreshes. Tracks and conflicts still read historical facts through the single-vessel APIs. +AISStream and BarentsWatch share the `/ws` `vessels` delta channel. Earth subscribes with `scope: "global"` on its existing WebSocket, without changing subscriptions as the camera moves. The backend coalesces notifications by MMSI for one second, then reads confirmed `vessel_current_state` rows. Frames contain at most 1000 items; further frames carry the remaining vessels rather than truncating them. Raw source messages must not overwrite confirmed client positions. Deleting current-state rows also produces MMSI-based remove notifications. + +The frontend coalesces short bursts per MMSI and uses `Interactable.updateItems()` to update position and color buffers in place. Heading-bucket changes touch only affected buckets, growing capacity when needed. Existing marker identities, selections, and materials survive. Initial entry, reconnects, deletion hints, and the minute reconciliation still use snapshots without first clearing the layer. A bounded snapshot must not treat truncated vessels as deleted, and older responses must not overwrite newer stream updates or removals received while the request was in flight. Snapshots include query-start `generated_at`; it is compared with stream frame time to prevent stale cached snapshots from rolling back new vessels or removals. + +Ordinary vessel writes use the `delta` strategy on `earth_updates`; while the dedicated channel is connected, they no longer request whole-layer reloads. Deletion or disconnected reconciliation uses `reload` while reusing existing objects. Hiding the layer unsubscribes and clears queued changes. Tracks, conflicts, and audit data continue through the single-vessel historical APIs. ### Layer APIs And Global Stats diff --git a/docs/technical/en/data-job-earth-sync-architecture.md b/docs/technical/en/data-job-earth-sync-architecture.md index 4ae340a3..fbec8d9b 100644 --- a/docs/technical/en/data-job-earth-sync-architecture.md +++ b/docs/technical/en/data-job-earth-sync-architecture.md @@ -70,7 +70,10 @@ The unified event model is `earth.layer.changed`: | --- | --- | | `clear_then_reload` | Clear local frontend layer objects first, then force a refetch. Prefer this for deletes. | | `reload` | Keep old objects until fresh data returns. Use it for location, metadata, or non-destructive updates. | -| `delta` | Used only for `earth_interactables`; upsert or remove objects by id. | +| `delta` | `earth_interactables` upserts/removes by id; ordinary vessel writes update confirmed state by MMSI through the dedicated `vessels` channel without clearing the layer. | + +Vessel deletion still emits a `reload` reconciliation hint; individual `vessel_current_state` deletions also enter the vessel remove channel. Source notifications identify changed MMSIs, while transmitted values come from current state. Global subscriptions use `scope: "global"`; message-size limits split frames instead of discarding remaining vessels. + APIs must return HTTP 200 with an empty collection for real zero-data states; 5xx is reserved for real endpoint failures. After a delete event, if refetch fails, the frontend should keep the cleared state and show a lightweight error instead of restoring stale objects. diff --git a/docs/technical/en/datasource-collector-settings-connectivity.md b/docs/technical/en/datasource-collector-settings-connectivity.md index d69ffd99..fb3f6083 100644 --- a/docs/technical/en/datasource-collector-settings-connectivity.md +++ b/docs/technical/en/datasource-collector-settings-connectivity.md @@ -321,7 +321,7 @@ The new vessel list entry point is no longer the legacy `/api/v1/visualization/g GET /api/v1/vessels/snapshot?bbox=-180,-85.05112878,180,85.05112878&zoom=12&limit=3000 ``` -That endpoint reads `vessel_current_state`, returning the latest point per MMSI inside the freshness window. Raw `ais_raw_observations` remain available for tracks, audit, and situational analysis, but the display endpoint no longer scans and aggregates history on the fly. Earth sends a global bbox rather than the current camera viewport. If the `/ws` `vessels` channel is connected, it should act as a reload/dirty hint for merged refreshes, not as a per-AIS-delta full-layer rebuild path. +That endpoint reads `vessel_current_state`, returning the latest point per MMSI inside the freshness window. Raw `ais_raw_observations` remain available for tracks, audit, and situational analysis, but the display endpoint no longer scans and aggregates history on the fly. Earth sends a global bbox rather than the current camera viewport. Realtime updates use the global `/ws` `vessels` subscription to deliver canonical state by MMSI and update existing markers in place. Larger updates are split across frames without dropping vessels. Initial load, reconnection, and deletion reconciliation still use snapshots; see [Collector Architecture](backend-collectors.md). ## Custom REST / WebSocket Mapping Runtime diff --git a/docs/technical/en/earth-frontend-context.md b/docs/technical/en/earth-frontend-context.md index a1e8531d..7598826b 100644 --- a/docs/technical/en/earth-frontend-context.md +++ b/docs/technical/en/earth-frontend-context.md @@ -159,6 +159,8 @@ Each module is responsible for its own: `tv.js` owns the live / aggregation-news tabs inside `media-panel`. Toolbar open and tab-switch actions write back through `earth:tv-visibility-change` and `earth:tv-tab-change`: panel visibility remains viewport-scoped at `views..panelVisibility.media-panel`, while the active tab is stored at `shared.mediaPanelActiveTab`. Refreshing the page therefore restores the user's last live/news state. Temporary hides from `closeTransientMobileOverlays()` carry `persist:false` and do not overwrite the preference. +`tv-source-menu.js` reuses HUD and legend-list styling in a popover with search, a scrolling list, and a fixed count footer. `tv.js` requests 50 entries from `/api/v1/tv/streams` and caches channel details; search runs against the complete backend catalog, and pagination uses `next_offset`. Cancellation and a request generation counter prevent stale results from replacing a newer search. Catalog refresh uses `selected_id` to restore a channel outside the first page. + `brand.js` manages Earth HUD brand resources. Static assets provide the default brand; runtime overrides come from `/api/v1/earth/brand`, and uploaded images are served from `/earth-brand-assets/...`. The frontend must treat logo/title images and text fallback separately: if an image fails, show the text title; if text fields are empty, rely on backend defaults so the HUD brand area never renders blank. The console Earth Content page owns saving and resetting brand configuration; the Earth frontend only consumes it. `about.js` manages the About card inside Earth settings. Frontend defaults remain as a fallback, while runtime content is loaded from `/api/v1/earth/about`. If the request fails or fields are missing, the renderer must fall back per field so the settings page never renders an empty card. Admin exposes an Earth Content `About` tab; saving uses `PUT /api/v1/earth/about`, and restoring defaults uses `DELETE /api/v1/earth/about`. @@ -179,6 +181,8 @@ The compute-center layer row has a notification badge for GeoJSON `unresolved` r Location candidate state in the details card is cached in [info-card.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/info-card.js) by `entityType:entityId`. If the user closes the details card or unresolved queue and reopens the same compute center / BGP collector, previously collected candidates and status text are restored. Header-level `一键采用` prefers cached candidates, avoiding repeated online geocoding or LLM factcheck calls. After a location is saved, that entity's candidate list is cleared to a "refreshing layer" status so stale candidates do not keep misleading the user. +`runUnresolvedComputeCenterBatch()` owns a queue of entity contexts rather than panel DOM. `locationCollectStateCache` retains candidates, progress, and save results so rebuilt cards can hydrate the current state. `earth:compute-center-location-batch-change` updates the badge, `savedCandidate` excludes completed entries, and a ✓ entry remains after completion. Queue state lives only in the current Earth page: refresh, close, or route navigation interrupts unfinished work, while saved coordinates remain authoritative in the backend. + The `预览 / 保存` buttons on each candidate row use a single delegated `click` handler per candidate root (the `[data-collect-cache-key]` block in the details card, or `[data-unresolved-item]` in the unresolved queue), guarded by a `data-candidate-actions-bound` flag so it cannot be double-bound. Direct `pointerup` / `click` listeners on individual buttons and overlapping delegated handlers were removed. Candidate objects are no longer JSON-stringified into an HTML attribute and parsed back; buttons only carry `data-candidate-index`, and the handler resolves the candidate object from a module-level `Map` keyed by cache-key. This removes the entire class of failures caused by HTML entity escaping of `&` / `<` / `"` in candidate fields. Clicking `预览` dispatches `earth:preview-location-candidate`; `main.js`'s `previewLocationCandidate()` calls `showComputeCenterLocationPreview()`, which attaches a hollow breathing-ring sprite pair at the candidate coordinates (visually mirroring the BGP event ring) and focuses the camera on the candidate. Previewing another candidate replaces the ring; saving clears it and `spawnSavedComputeCenterLocation()` immediately spawns the formal compute-center interactable. Note that `main.js` has no module-level `earth` variable — every location-save / preview handler must call `const earth = getEarth();` first, otherwise the event handler throws a `ReferenceError` that the surrounding `.catch` swallows, producing the failure mode where the button "does nothing". The `earth:compute-center-location-saved` reconciliation pipeline is deliberately silent on background-refresh failures. `spawnComputeCenterAfterLocationSave()` already presents the success toast and locked state; `refreshComputeCentersAfterLocationSave()` only reloads backend data when the scene is ready and no longer emits its own `已保存` toast. `handleComputeCenterLocationSaved()` runs refresh in the background after a successful spawn; only when spawn returns `null` (scene not ready) or throws does refresh take over the success toast. A refresh error is only `console.warn`'d — it must never surface as a `保存失败` message, because the save itself succeeded and the refresh is a follow-up sync. @@ -191,7 +195,11 @@ The backend snapshot endpoint still requires `bbox`, but the Earth runtime treat Vessel markers are rendered through `createInteractableLayer()` as batched `THREE.Points`, with `cluster` and `avoidance` explicitly disabled. Dense waterways may overlap. Dragging or inertial rotation skips hover picking; normal hover uses screen-space nearest-point picking. Do not reconnect vessels to dynamic screen clustering or per-frame Points rebuilds, because those interaction costs are what make a 3000-marker layer feel heavy. -If the `/ws` `vessels` channel is used by Earth, it should be a low-frequency reload/dirty hint only. Do not create multiple viewport subscriptions, and do not turn every AIS delta into a full layer rebuild. +AISStream and BarentsWatch share the `/ws` `vessels` delta channel. Earth subscribes with `scope: "global"` on its existing WebSocket, without changing subscriptions as the camera moves. The backend coalesces notifications by MMSI for one second, then reads confirmed `vessel_current_state` rows. Frames contain at most 1000 items; further frames carry the remaining vessels rather than truncating them. Raw source messages must not overwrite confirmed client positions. Deleting current-state rows also produces MMSI-based remove notifications. + +The frontend coalesces short bursts per MMSI and uses `Interactable.updateItems()` to update position and color buffers in place. Heading-bucket changes touch only affected buckets, growing capacity when needed. Existing marker identities, selections, and materials survive. Initial entry, reconnects, deletion hints, and the minute reconciliation still use snapshots without first clearing the layer. A bounded snapshot must not treat truncated vessels as deleted, and older responses must not overwrite newer stream updates or removals received while the request was in flight. Snapshots include query-start `generated_at`; it is compared with stream frame time to prevent stale cached snapshots from rolling back new vessels or removals. + +Ordinary vessel writes use the `delta` strategy on `earth_updates`; while the dedicated channel is connected, they no longer request whole-layer reloads. Deletion or disconnected reconciliation uses `reload` while reusing existing objects. Hiding the layer unsubscribes and clears queued changes. Tracks, conflicts, and audit data continue through the single-vessel historical APIs. The legacy `/api/v1/visualization/geo/vessels` route has been removed. Frontend code should keep using `PATHS.vesselsApi` and can verify the current-state path through `diagnostics.source == "vessel_current_state"`. @@ -221,6 +229,14 @@ The cruise sequencer handles generic logic: current target, queue order, camera All material, layer, satellite, BGP, cable, terrain, celestial, and other style parameters are maintained here. Do not scatter magic numbers in module files. +## Render hot paths + +`cable-batches.js` batches the complete cable and landing-point sets. `cables.js` still owns original business objects, picking, occlusion, and selection state. Do not make these interaction proxies draw individually again or return a render batch as the detail-card business object. + +Satellite breathing runs in vertex shaders. `satellite-position-worker.js` moves full SGP4 position and initial trail calculations off the main thread; the main thread applies snapshots to interaction coordinates and render buffers. `satellite-propagation.js` supplies the same mathematics to the Worker, predicted orbits, and synchronous fallback. Reload, clear, and altitude changes must terminate prior work so stale snapshots cannot resurrect cleared layers. + +The `i18n.js` MutationObserver translates only added subtrees, changed text, or changed attributes. Local clocks, status labels, and download progress must not synchronize all locale controls. Global locale synchronization belongs to initialization, locale changes, or subtrees containing new locale controls. + ## Current Style Layers CSS files in `frontend/public/earth/css/` each correspond to a specific component scope. Do not write global Earth styles into `base.css` unless they genuinely apply to everything. @@ -333,7 +349,7 @@ If future cable, satellite, or news cruise is added, do not copy a new set of `m [controls.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/controls.js) owns the Earth zoom state, and every zoom entry point must ultimately call `setZoomLevel()` to write the camera distance. Do not write `camera.position.z` from other modules, or the zoom percentage, drag sensitivity, and Interactable clustering thresholds will diverge again. -Interactable clustering is selected per layer through `cluster.strategy`. `stable-spherical` uses discrete zoom bands and local 3D bucket clustering, so BGP, compute centers, and Earth interactables do not regroup while the globe rotates inside the same band. `dynamic-screen` keeps the projection-based behavior for high-frequency realtime layers such as vessels, and `none` disables clustering. Stable cluster dots stay rigidly aligned to their 3D centroid projection and do not participate in 2D avoidance. See [Earth Interactable Clustering](/home/ray/dev/linkong/planet/docs/technical/en/earth-interactable-clustering.md) for strategy configuration and tuning. +Interactable clustering is selected per layer through `cluster.strategy`. `stable-spherical` uses discrete zoom bands and local 3D bucket clustering, so BGP, compute centers, and Earth interactables do not regroup while the globe rotates inside the same band. `dynamic-screen` keeps projection-based clustering, and `none` disables it. Vessels explicitly disable clustering and avoidance so incremental updates do not rebuild cluster topology. Stable cluster dots stay rigidly aligned to their 3D centroid projection and do not participate in 2D avoidance. See [Earth Interactable Clustering](/home/ray/dev/linkong/planet/docs/technical/en/earth-interactable-clustering.md) for strategy configuration and tuning. Wheel input has two paths. Traditional mouse wheels keep the 10% step and short animation, using `wheelZoomTarget` as the logical base for continuous wheel input. Trackpads and high-precision wheels use the pixel delta for continuous zoom and call `setZoomLevel()` directly instead of passing through the 10% stepped animation. The trackpad path also filters a short-window, old-direction residual delta after a real direction change so inertia tails do not pull a just-reversed zoom back in the previous direction. diff --git a/docs/technical/en/earth-layer-style-reference.md b/docs/technical/en/earth-layer-style-reference.md index 592ad7b1..93344d64 100644 --- a/docs/technical/en/earth-layer-style-reference.md +++ b/docs/technical/en/earth-layer-style-reference.md @@ -143,6 +143,8 @@ The land/ocean base is an Earth base-map asset and preloads at startup; the "Bor ## Submarine Cables and Landing Points +`cable-batches.js` batches cable lines and landing points separately. The Sprite material and size parameters below remain owned by picking and selection proxies in `cables.js`; their color, opacity, scale, and visibility update the style texture or instance attributes. Drawing uses `LineSegments` and instanced billboards with the existing textures, colors, render order, and globe occlusion rules. + | Name | Variable | Current Value | Location / Notes | | --- | --- | --- | --- | | Default cable color | `CABLE_COLORS.default` | `0xffff44` | Used when no data color available | diff --git a/docs/technical/en/earth-render-layer-order.md b/docs/technical/en/earth-render-layer-order.md index 5b542531..8dc7e3ca 100644 --- a/docs/technical/en/earth-render-layer-order.md +++ b/docs/technical/en/earth-render-layer-order.md @@ -20,7 +20,7 @@ Note: the layer control panel order and the registration / startup load order ar | 0.86 | Land/ocean base fill | `country-boundaries.js` | `landAltitudeOffset = 0.32`; ocean `#010609`, land `#080f1b` | Raycast disabled | Base map remains usable even when country borders are off; radius is separated from the base sphere to avoid far-zoom z-fighting. | | 0.96 | HD Earth texture | `earth.js` | `textureOverlayAltitudeOffset = EARTH_SURFACE_TEXTURE_ALTITUDE_OFFSET = 0.48` | Surface picking target when visible | HD texture always overlays the land/ocean base fill; radius must stay above the land/ocean base and far enough from the base sphere. | | 1 | Atmospheric glow and clouds | `earth.js` | Atmosphere / cloud spheres | Not in normal object selection path | Cloud layer controlled by the "Cloud Layer" toggle. | -| 1 | Submarine cables | `cables.js` | `CABLE_CONFIG.line.renderOrder` | Cable picking path | Preserves existing cable layer level. | +| 1 | Submarine cables / landing points | `cables.js`, `cable-batches.js` | All cable segments share one `LineSegments`; all landing points use instanced billboards; render order `1` and altitude offset `0.2` are unchanged | Original `Line` / `Sprite` objects retain per-item picking and selection state but no longer draw individually; landing-point sphere occlusion remains, with `depthTest: false` on the batch | Style textures and instance attributes preserve color, pulse, size, visibility, and click behavior. | | 1.2 | Real terrain | `earth.js`, `terrain.js` | `TERRAIN_CONFIG.baseRadiusOffset` plus terrain displacement | Raycast disabled | Terrain overlays HD texture; temporarily hidden when HD texture is off, restores to prior state when re-enabled. | | 2.05 | Grid lines | `earth.js` | `CONFIG.earthRadius + 0.14` | Raycast disabled | Low-opacity lines over HD texture. | | 2.2 | Country borders | `country-boundaries.js` | `lineAltitudeOffset = EARTH_SURFACE_TEXTURE_ALTITUDE_OFFSET = 0.48`; claim lines have no extra lift | Raycast disabled | Line geometry still has its own `renderOrder`, but it shares the exact same radius as the HD texture shell to avoid parallax while the globe rotates. | @@ -36,6 +36,14 @@ Note: the layer control panel order and the registration / startup load order ar | 12+ | Satellite locked ring, halo, predicted orbit | `satellites.js` | `SATELLITE_CONFIG.overlayRenderOrder` and offsets; predicted orbit follows the same real-altitude toggle and fixes the lock-time globe pose to draw a closed inertial orbit; returns to same-sphere mode when real altitude is disabled | Satellite overlay path | Used for selected/locked satellite emphasis. | | 98-100 | Sun / moon halo and sprite | `celestial.js` | Fixed renderOrder | Celestial picking disabled | Foreground celestial sprites. | +## Full-set rendering and updates + +- Batching changes GPU submission, not the number of satellites, cable segments, or landing points. It does not filter data by the visible hemisphere. Every adjacent cable vertex pair remains present, and picking still returns the original business object. +- Satellite foreground and backdrop remain two `Points` draws. Vertex shaders compute breathing from static per-point parameters and a shared frame-time uniform; existing hover/locked state still controls point masking. +- `satellite-position-worker.js` uses the same Three.js / SGP4 versions as the main thread. `satellite-propagation.js` owns shared orbit, display-altitude, and fallback calculations. Full positions and initial trail samples use transferable arrays; only one calculation is in flight. Reload, clear, and altitude-mode changes terminate the previous Worker. +- Worker startup failure or `SATELLITE_CONFIG.workerStartupTimeoutMs` expiry falls back to the shared synchronous calculation. Counts, APIs, the existing update interval, and trail length are unchanged. +- Verify full draw ranges, per-item picking, locked overlays, trails, rear-side occlusion, visibility toggles, and resource release after clearing. Frame-time comparisons require identical data, view, and resolution. + ## Toggle Behavior | Toggle | Behavior | diff --git a/docs/technical/en/manual.md b/docs/technical/en/manual.md index e3f6a39c..261cb609 100644 --- a/docs/technical/en/manual.md +++ b/docs/technical/en/manual.md @@ -123,6 +123,9 @@ The default guide follows the BarentsWatch official tutorial and reminds you to ### AISStream Realtime Vessels +Once the vessel layer is open, subsequent AISStream and BarentsWatch positions update automatically. Selected vessels stay selected during updates, and reconnecting automatically reconciles the display without repeatedly toggling the layer. + + `AISStream Realtime Vessels` is the global AIS WebSocket collector. A passing connection test only confirms API key + endpoint format. Actual global vessel data requires the backend `aisstream_vessels` collector to stay connected and write to `ais_raw_observations`. Steps: @@ -162,6 +165,8 @@ Providers and models accept presets or arbitrary custom IDs. Common fields: The plug icon at the end of the Base URL input runs a connection test. A passing test echoes the model's short reply. +Use the refresh icon at the top right to update the available models. A successful refresh saves the catalog for later visits; catalogs with release dates show newer models first. Refresh preserves the current model, credentials, URLs, and unsaved edits. Select a model and click Save to change the model used by the application. A failed refresh displays an error and keeps the previous catalog. + ### Tools - **WebSearch**: provider, API key, base URL, max results, timeout, advanced provider parameters. While disabled, all fields except the enable switch are greyed out @@ -282,6 +287,10 @@ AIS vessel legend colors by type: cargo, tanker, passenger, fishing, military, m Search finds cables, landing points, satellites, compute centers, BGP events, BGP observers. Results jump to and focus the object. +### Choosing a News Live Stream + +Open the live tab in the media panel and click the current channel to open the search menu. Search covers the complete catalog. The list loads 50 channels at a time and appends another page when you scroll to the bottom. A fixed footer shows the loaded and matching channel counts; a failed request can be retried below the list. The default source is Al Jazeera Mubasher, using its HLS playback URL. Other channels remain subject to availability of their playback service. + ### Coordinate Candidate Collection Compute center and BGP observer detail cards support automatic coordinate-candidate collection. Click the object then use "Collect Coordinate Candidates" or "Re-collect Coordinates". The backend assembles candidates from source coordinates, public-org registry APIs, and online geocoders. When regular sources have no candidate, the current default AI Provider runs one LLM factcheck fallback. BGP observers' stored coordinates only fill query context; they are not returned as candidates. @@ -298,6 +307,8 @@ Recommended single-object flow: Adopt All is for batch processing the compute-center unresolved queue. It starts from the top and adopts the highest-confidence candidate. Records without factual support remain in the queue. When WebSearch is disabled, single locate and Adopt All are disabled because location validation depends on factual lookup. +The batch continues within the current Earth page when you close the candidate panel, inspect another object, or switch browser tabs. Reopening the queue restores progress and results. Saved entries are not collected again, and a ✓ entry beside the layer remains available after completion. Refreshing, closing, or navigating away from Earth interrupts unfinished work; coordinates already saved remain stored. + ### Settings The settings panel is grouped into Runtime, Display, Panels, Motion, Shortcuts, and System. It covers rotate / cruise / motion mode, cruise modules (BGP/news/compute centers/vessels/cables/satellites), view (satellite display style, hover tooltip, satellite idle breathing, real satellite altitude, track display, compact dots, day-night mode, panel toggles), motion debug mode / input source / skeleton-only / recognized-gesture whitelist, shortcut enablement and remapping, default globe size, terrain opacity, reset. diff --git a/docs/technical/en/ops-planet-sh-startup.md b/docs/technical/en/ops-planet-sh-startup.md index 3aa13383..1016d6f8 100644 --- a/docs/technical/en/ops-planet-sh-startup.md +++ b/docs/technical/en/ops-planet-sh-startup.md @@ -2,6 +2,10 @@ ## Background +Use `zsh ./planet.sh start --non-motion-agent` for daily startup; use `init` when preparing a new environment. When investigating latency, distinguish initial dependency downloads, container readiness, and application initialization using the stage timestamps. + +Before preparing the AI Provider image, startup verifies the backend's actual database connection and recreates a missing port mapping once while preserving the volume. A terminated backend process or Uvicorn initialization, ASGI loading, import, or syntax failure stops waiting and identical retries immediately. Normally slow initialization keeps its existing timeout budget. AI Provider readiness probes the host `/health` endpoint directly, without waiting for Docker's first scheduled health check. + `planet.sh` manages start, stop, restart, health checks, and logs for all local services. The previous implementation had several startup issues: 1. AI Provider rebuilt every time, even when code had not changed. @@ -37,27 +41,9 @@ write_ai_provider_build_stamp() { } ``` -### Faster Fingerprint +### Fingerprint Scope -The previous implementation tarred the whole `aiprovider/` directory before hashing, which could take seconds in large trees. The new version uses `find + stat` and reads only file metadata: - -```bash -compute_ai_provider_build_fingerprint() { - find aiprovider \ - -type f \ - ! -path '*/__pycache__/*' \ - ! -name '.env' \ - ! -name '.env.*' \ - ! -name '*.pyc' \ - ! -name '*.pyo' \ - | LC_ALL=C sort \ - | xargs -r stat --format="%Y %s %n" 2>/dev/null - sha256sum docker-compose.yml docker-compose.simple.yml 2>/dev/null - python3 "$SCRIPT_DIR/scripts/compute_aiprovider_dependency_fingerprint.py" 2>/dev/null -} -``` - -This is roughly 10 times faster for many-small-file workloads while preserving the same practical rebuild signal. `.env` and `.env.*` are excluded because runtime model, key, and Base URL changes should not force an image rebuild. +The fingerprint hashes file contents from `aiprovider/`, the Dockerfile, the root manifest and lockfile, and the provider dependency information. It does not traverse frontend assets or downloaded data. `.env` and `.env.*` are excluded because they are runtime configuration. The Dockerfile applies its fingerprint label after dependency installation so a changed build marker alone does not invalidate dependency layers. ### Docker Build Context @@ -83,13 +69,15 @@ The Dockerfile copies only AI Provider inputs: ```dockerfile COPY pyproject.toml uv.lock /app/ RUN --mount=type=cache,target=/root/.cache/uv \ - uv sync --frozen --no-dev + uv sync --frozen --only-group aiprovider COPY aiprovider /app/aiprovider ``` `uv sync` uses a BuildKit cache mount. The first build may still depend on network speed, but later builds reuse `/root/.cache/uv`. +The `aiprovider` dependency group in the root `pyproject.toml` uses the same `uv.lock` and installs only the API, HTTP client, settings, and ASGI runtime dependencies. The image excludes backend collectors and OpenCV / MediaPipe motion dependencies. The build fingerprint label comes after dependency installation and code copying, so a fingerprint change alone does not invalidate dependency layers. The container starts the installed `.venv/bin/python` directly, without runtime dependency synchronization. Dependency changes must update this group and the lockfile and validate image imports and `/health`. + ### Runtime Configuration Before starting AI Provider, `planet.sh` generates a current-user runtime env-file and passes it to Compose or the manual `docker run` fallback. The default path is `${XDG_STATE_HOME:-$HOME/.local/state}/planet/aiprovider_runtime.env`. Configuration priority: @@ -117,7 +105,7 @@ When the fingerprint matches, the script skips `docker compose build` and starts docker start planet_aiprovider ``` -`docker stop` stops the container without deleting the image. `cleanup_exit_containers` removes exited containers but not images, so the next `docker start` can reuse the existing image. +`docker stop` stops the container without deleting the image. `start` and `restart` retain stopped containers instead of scanning and deleting all exited containers on the host. An unchanged AI Provider can be reused, while Compose still reconciles database configuration. Existing recreation paths remain responsible for image or configuration changes. ## Issue 2: Slow Port Cleanup diff --git a/docs/technical/en/ops-runbook.md b/docs/technical/en/ops-runbook.md index 37efd0b3..8ba7afab 100644 --- a/docs/technical/en/ops-runbook.md +++ b/docs/technical/en/ops-runbook.md @@ -33,9 +33,9 @@ docker buildx version ## Database Initialization and Connection Checks -`init` reconciles PostgreSQL / Redis containers through Compose, including port configuration on existing containers. A plain `docker start` cannot apply configuration changes. Compose failures retain their specific errors, such as an occupied port, instead of falling back to an old container and reporting success. +`init` and `start` reconcile PostgreSQL / Redis containers through Compose, including port configuration on existing containers. A plain `docker start` cannot apply configuration changes. Compose failures retain their specific errors, such as an occupied port, instead of falling back to an old container and reporting success. -The container's `pg_isready` check only establishes that the server accepts connections; it does not validate the host backend's address and credentials. Once containers are healthy, `init` runs `scripts/check_database_connection.py` using the backend's effective `DATABASE_URL`. It checks the local PostgreSQL published port and executes a read-only `SELECT 1` before reporting database readiness or creating tables and seed data. +The container's `pg_isready` check only establishes that the server accepts connections; it does not validate the host backend's address and credentials. Once containers are healthy, both initialization and backend startup run `scripts/check_database_connection.py` using the backend's effective `DATABASE_URL`. It checks the local PostgreSQL published port and executes a read-only `SELECT 1`. Startup performs this check before preparing the AI Provider image and stops immediately on failure. Initialization only creates tables and seed data after the check passes. - If the actual local port mapping is still missing or mismatched, the script recreates PostgreSQL once from Compose while preserving its data volume, then checks again. A second failure stops initialization. - Authentication, database-name, and network failures stop before schema changes. Diagnostics show the host, port, and database name without passwords, full connection strings, or raw driver exceptions. diff --git a/docs/technical/en/quickstart.md b/docs/technical/en/quickstart.md index 849f57e8..747e1ca9 100644 --- a/docs/technical/en/quickstart.md +++ b/docs/technical/en/quickstart.md @@ -33,7 +33,7 @@ The default role is `viewer`: you can sign in but only see public pages. For col After landing on the `/admin` dashboard, here's a recommended walk-through: 1. `/collection-management?section=collector_credentials`: pick a collector and click the plug icon to test connectivity. Free collectors (e.g. open BGP) usually work right away; credential-bearing ones like `AISStream` or `BarentsWatch` need an API key / client secret first -2. `/ai?section=integrations`: fill an LLM provider (e.g. `minimax` / `openai`), model, base URL, API key, and click the plug at the end of the base URL to test. WebSearch / OCR tools are optional +2. `/ai?section=integrations`: fill an LLM provider (e.g. `minimax` / `openai`), model, base URL, API key, and click the plug at the end of the base URL to test. The refresh icon updates and saves the available model catalog while preserving your form; select a model and click Save to apply it. WebSearch / OCR tools are optional 3. `/earth-content?section=brand`: maintain the Earth HUD logo and title image in Branding. The Upload button inside each URL field opens a file picker, and image files can also be dropped directly onto the matching field. Save the brand configuration after upload 4. `/datasources` or `/data`: check whether collectors have produced data. Use `/datasources -> Built-in Sources` for finite collectors: with no rows selected, click `Trigger All`; after selecting rows, the primary button becomes `Trigger Selected N`. The top-right queue button shows progress. Use `/datasources -> Realtime Sources` for AISStream / WebSocket health and counters 5. `/alerts/system`: verify system alerts look right @@ -50,6 +50,9 @@ Once in, verify: - The globe renders, and the right-side layer panel can toggle layers - Search finds cables, satellites, compute centers, BGP events - Compute-center and BGP collector detail cards can collect coordinate candidates and preview them on Earth +- Close the candidate panel or switch browser tabs during batch location, then return to see progress; refreshing or leaving Earth interrupts unfinished work +- The vessel layer receives ongoing AISStream / BarentsWatch positions and reconciles after reconnecting +- The live-stream menu searches the complete channel catalog and loads more on scroll; Al Jazeera Mubasher is the default - Mouse drag, wheel zoom, and the zoom percentage indicator work - The settings panel can switch rotate / cruise / motion modes; motion settings can select the input source and allowed gestures; view settings can switch hover tooltip content, and satellite settings can toggle real-altitude layering and track display diff --git a/docs/technical/zh/agents-aiprovider.md b/docs/technical/zh/agents-aiprovider.md index 461a7659..e897193b 100644 --- a/docs/technical/zh/agents-aiprovider.md +++ b/docs/technical/zh/agents-aiprovider.md @@ -95,12 +95,15 @@ AI 配置页使用的接口： - `POST /api/v1/settings/integrations/ai-provider/connect` - `GET /api/v1/settings/integrations/ai-provider/secrets` - `GET /api/v1/settings/integrations/ai-provider/presets` +- `POST /api/v1/settings/integrations/ai-provider/presets/{provider}/refresh` - `GET /api/v1/settings/ai-prompts` - `PUT /api/v1/settings/ai-prompts/{task_key}` - `POST /api/v1/settings/ai-prompts/{task_key}/reset` 这些接口都需要用户登录。`secrets` 接口只用于配置页点击显示 key/token 时取回明文，隐藏时前端恢复为脱敏预览。 +模型目录刷新由 `backend/app/services/llm_provider_catalog.py` 获取上游目录；多数供应商读取 models.dev，OpenCode Go 使用自己的模型接口。models.dev 条目按发布日期倒序排列，缺少日期的条目排在后面。成功结果和 `refreshed_at` 按供应商保存在 `system_settings` 的 `llm_provider_preset:` 分类中，列表接口优先返回已保存目录，未刷新过的供应商使用内置预设。刷新只更新目录，不写入 `external_integrations` 中的当前模型、协议、地址或凭证。失败返回 502 并保留上次目录；上游异常原文不返回客户端。前端重新加载目录，可选模型读取目录状态，表单草稿独立保留。 + Admin 的 AI 页面按业务信息架构组织为： - `模型供应商` diff --git a/docs/technical/zh/backend-collectors.md b/docs/technical/zh/backend-collectors.md index 44b87c66..d08c65e4 100644 --- a/docs/technical/zh/backend-collectors.md +++ b/docs/technical/zh/backend-collectors.md @@ -102,6 +102,12 @@ AIS 船只类采集器和其它 `CollectedData` 采集器的落库路径不同 TOP500 和 Epoch AI 算力数据的公开源不总是提供可用经纬度。Earth 统一算力中心接口在主地图启动链路中只使用源数据自带坐标或 `compute_center_locations` 维表坐标；缺少坐标的记录会进入 `unresolved`，不会通过本地注册表、国家质心或猜测城市自动渲染。用户手动采集候选时，后端会用源字段调用 ROR 组织注册 API 和 Nominatim/OpenStreetMap 在线搜索；候选经前端保存后写入 `compute_center_locations`，后续地图刷新再从维表渲染。 +### 新闻直播频道目录 + +`news_live_streams` 的 IPTV-org 适配器保留现有新闻分类筛选，`max_sources` 默认值为 `0`，表示不截断匹配频道；显式正数仍限制采集数量。已有配置若保留旧的 `120`，需要改为 `0` 并重新采集才能补齐目录。 + +`GET /api/v1/tv/streams` 由 `tv_catalog.py` 提供数据库分页：`offset` 默认 `0`，`limit` 默认 `50`、最大 `100`，`q` 按空白拆词并匹配频道名、来源、地区和语言。内置及配置源优先，采集源按频道标识去重并排除配置覆盖项，再在数据库中搜索、计数、排序和分页，避免全表读取后切片。响应的 `total` 是匹配总数，`source_count` 是完整可用目录数量；后续页使用 `next_offset` 和 `has_more`。`selected_id` 可额外取得不在当前页的已选频道，不占本页配额。默认和兜底源继续由 `tv_streams.py` 统一管理。 + ## 四、数据格式 (统一存储到 CollectedData 表) ```python @@ -382,7 +388,11 @@ GET /api/v1/visualization/vessels/{mmsi}/conflicts `/api/v1/vessels/snapshot` 必须携带 `bbox` 和 `zoom`，后端最大 `limit=5000`。Earth 前端使用全球 bbox 读取当前状态，不随相机视口变化反复请求。接口消费 `vessel_current_state`，并在 `diagnostics.source` 返回 `vessel_current_state`；旧 `/api/v1/visualization/geo/vessels` 路由已移除。 -高频 AIS 更新不要直接推送成每条 delta 的整层重建。`/ws` 的 `vessels` channel 如用于 Earth，应广播低频 reload/dirty 提示，由前端合并刷新 snapshot；轨迹和冲突详情仍按单船接口读取历史事实。 +AISStream 与 BarentsWatch 共用 `/ws` 的 `vessels` 增量通道。Earth 使用现有 WebSocket 连接订阅 `scope: "global"`，不跟随镜头改变订阅范围。后端按 MMSI 合并一秒内的通知，再读取 `vessel_current_state` 的已确认状态；单帧最多 1000 项，超过时继续发送后续帧，不截断不同船只。原始源消息不能直接覆盖客户端的确认位置。当前状态删除也会产生按 MMSI 的 remove 通知。 + +前端将短时间内同一 MMSI 的变更合并为最新值，通过 `Interactable.updateItems()` 原位修改位置和颜色缓冲。航向分桶变更只更新受影响的桶，容量不足才扩容；保留已有 marker 身份、锁定状态和材质。首次进入、重连、删除提示及每分钟巡检仍用 snapshot 校准，但不先清空整个图层。收到有数量上限的快照时，不能把被截断的船只当成删除；快照返回期间到达的较新更新和删除也不能被旧响应覆盖。快照携带查询开始时的 `generated_at`，与实时帧时间一起用于识别缓存旧快照，避免新船或删除状态被回滚。 + +`earth_updates` 中船舶普通写入的策略是 `delta`；专用通道连通时不再触发整层重拉。删除或断连后的校准使用 `reload`，并复用现有对象。关闭图层会取消船舶订阅并清空待应用变更。轨迹、冲突详情和审计继续按单船接口读取历史事实。 ### 图层接口与全量统计分离 diff --git a/docs/technical/zh/data-job-earth-sync-architecture.md b/docs/technical/zh/data-job-earth-sync-architecture.md index 12cc57db..08a351a6 100644 --- a/docs/technical/zh/data-job-earth-sync-architecture.md +++ b/docs/technical/zh/data-job-earth-sync-architecture.md @@ -70,7 +70,10 @@ DB 变化不再默认创建 `earth_refresh` 任务，因此不会被同 source | --- | --- | | `clear_then_reload` | 先清前端本地图层对象，再强制重拉接口。删除数据时优先使用。 | | `reload` | 保留旧对象直到新数据返回，适合定位、元数据或非破坏性更新。 | -| `delta` | 只用于 `earth_interactables`，按 id upsert 或 remove。 | +| `delta` | `earth_interactables` 按 id upsert/remove；船舶普通写入由专用 `vessels` 通道按 MMSI 更新确认状态，不触发整层清空。 | + +船舶删除仍发出 `reload` 校准提示，`vessel_current_state` 的逐项删除同时进入船舶 remove 通道。源通知只决定哪些 MMSI 需要更新，推送值以当前状态表为准。全局订阅使用 `scope: "global"`；消息大小上限用于拆包，不用于丢弃其余船只。 + 接口在真实 0 数据时必须返回 200 和空集合；只有真实接口异常才返回 5xx。前端收到删除事件后，如果重拉失败，应保持已清空状态并显示轻量错误，不恢复旧对象。 diff --git a/docs/technical/zh/datasource-collector-settings-connectivity.md b/docs/technical/zh/datasource-collector-settings-connectivity.md index 72bc549c..db2c7d21 100644 --- a/docs/technical/zh/datasource-collector-settings-connectivity.md +++ b/docs/technical/zh/datasource-collector-settings-connectivity.md @@ -323,7 +323,7 @@ AISStream 使用 WebSocket 实时流，采集器只写入 `ais_raw_observations` GET /api/v1/vessels/snapshot?bbox=-180,-85.05112878,180,85.05112878&zoom=12&limit=3000 ``` -该接口查询 `vessel_current_state` 当前状态表，只返回有效窗口内每个 MMSI 的最新点；原始 `ais_raw_observations` 继续保留给轨迹、审计和态势分析，但不再由展示接口临时扫描聚合。Earth 前端统一传全球 bbox，不随当前镜头视口反复请求。实时更新如接入 `/ws` 的 `vessels` channel，应作为 reload/dirty 提示触发合并刷新，不能把每条 AIS delta 直接变成整层重建。 +该接口查询 `vessel_current_state` 当前状态表，只返回有效窗口内每个 MMSI 的最新点；原始 `ais_raw_observations` 继续保留给轨迹、审计和态势分析，但不再由展示接口临时扫描聚合。Earth 前端统一传全球 bbox，不随当前镜头视口反复请求。实时更新使用 `/ws` 的 `vessels` 全局订阅，按 MMSI 推送确认状态并原位更新；超出单帧上限时拆包，保留所有更新。首次加载、重连和删除校准仍使用快照，详见[采集器架构](backend-collectors.md)。 ## 自定义 REST / WebSocket 映射运行时 diff --git a/docs/technical/zh/earth-frontend-context.md b/docs/technical/zh/earth-frontend-context.md index 3ba7d129..8db15645 100644 --- a/docs/technical/zh/earth-frontend-context.md +++ b/docs/technical/zh/earth-frontend-context.md @@ -56,7 +56,7 @@ React 路由入口： - 各图层集成 - Earth 级别状态同步 -Earth 收到 `/ws` 的 `earth_updates` 时只把它当作刷新提示，真实数据仍通过 `/api/v1/visualization/...` 接口重新 GET。数据库驱动的刷新由后端 listener 直接清理缓存再广播，不再默认经过 `earth_refresh` 作业队列；前端收到 `database_changed` 后会按 layer 读取 `clear_then_reload`、`reload` 或 `delta` 策略。`clear_then_reload` 必须先清 Three.js 对象再 no-store 重拉，summary 只做一致性校验，不能用 `0` 作为跳过图层重拉的理由。技术链路见 [数据作业与 Outbox 技术架构](/home/ray/dev/linkong/planet/docs/technical/zh/data-job-earth-sync-architecture.md)，业务数据流见 [业务架构与数据流转](/home/ray/dev/linkong/planet/docs/technical/zh/platform-data-flows.md)。 +Earth 收到 `/ws` 的 `earth_updates` 时只把它当作刷新提示，普通图层仍通过 `/api/v1/visualization/...` 接口重新 GET；船舶使用下文的 `vessels` 专用确认状态增量通道。数据库驱动的刷新由后端 listener 直接清理缓存再广播，不再默认经过 `earth_refresh` 作业队列；前端收到 `database_changed` 后会按 layer 读取 `clear_then_reload`、`reload` 或 `delta` 策略。`clear_then_reload` 必须先清 Three.js 对象再 no-store 重拉，summary 只做一致性校验，不能用 `0` 作为跳过图层重拉的理由。技术链路见 [数据作业与 Outbox 技术架构](/home/ray/dev/linkong/planet/docs/technical/zh/data-job-earth-sync-architecture.md)，业务数据流见 [业务架构与数据流转](/home/ray/dev/linkong/planet/docs/technical/zh/platform-data-flows.md)。 ### 3. 地球控制层 @@ -170,6 +170,8 @@ Browser Camera provider 的手势识别管线在 [motion-browser-provider.js](/h `tv.js` 管理 `media-panel` 里的直播 / 态势新闻 tab。toolbar 打开或切换 TV/新闻时，会通过 `earth:tv-visibility-change` 和 `earth:tv-tab-change` 回写 Earth 设置：面板可见性仍按 desktop/mobile viewport 存在 `views..panelVisibility.media-panel`，当前 tab 存在 `shared.mediaPanelActiveTab`，因此刷新页面后能恢复用户上次打开的直播或新闻状态。`closeTransientMobileOverlays()` 这类临时收起会带 `persist:false`，不会覆盖用户偏好。 +`tv-source-menu.js` 复用 HUD 面板与图例列表样式，使用 popover 显示搜索、滚动列表和固定计数栏。`tv.js` 按 50 条请求 `/api/v1/tv/streams`，维护当前频道缓存；搜索交给后端完整目录，翻页用 `next_offset`。菜单通过取消请求和请求代数屏蔽过期响应，不能让旧搜索覆盖新输入。刷新目录时通过 `selected_id` 恢复不在第一页的频道。 + `brand.js` 管理智能星球 HUD 品牌资源。默认品牌来自静态资源，运行时覆盖值来自 `/api/v1/earth/brand`，上传的图片通过 `/earth-brand-assets/...` 读取。前端必须把 logo/title 图片和文本 fallback 分开处理：图片加载失败时显示文本标题，文本字段为空时使用后端默认值，避免 HUD 品牌区空白。控制台的智能星球内容页负责保存和重置品牌配置，智能星球前端只消费结果。 `about.js` 管理智能星球设置里的“关于”卡片。默认内容仍保留在前端作为兜底，运行时优先读取 `/api/v1/earth/about`。接口失败或字段缺失时必须回退默认值，避免设置页出现空白。控制台的智能星球内容页提供“关于”tab，保存走 `PUT /api/v1/earth/about`，恢复默认走 `DELETE /api/v1/earth/about`。 @@ -209,6 +211,14 @@ TV 预览需要尽量复用 Earth 运行时的直播卡片结构和状态标签 新闻巡航摘要的未来计划保存在仓库路径 `docs/plans/earth-news-cruise-summary-plan.md`，不作为公开 Docs 页面入口。 +## 渲染热路径 + +`cable-batches.js` 将全部海缆线段与全部登陆点分别合批绘制；`cables.js` 继续拥有原始业务对象、拾取、遮挡和选择状态。避免在后续功能中把这些代理对象重新加入逐对象绘制，或把绘制批次当作业务对象返回给详情卡。 + +卫星的逐点呼吸在 GPU 中计算。全量 SGP4 位置和初始轨迹计算通过 `satellite-position-worker.js` 离开主线程；主线程只接收位置快照、更新共享交互坐标及绘制缓冲。轨道数学由 `satellite-propagation.js` 同时供 Worker、预测轨道和同步降级路径使用，避免多套公式漂移。数据重载、清空和高度切换必须同步终止旧计算，不能让旧快照恢复已清空的图层。 + +`i18n.js` 的 MutationObserver 只翻译新增子树、变动文本或变动属性。局部时钟、状态和下载进度更新不能触发整页语言控件同步；全局语言同步只属于初始化、语言切换或包含新语言控件的子树。 + ## 当前样式分层 Earth 的 CSS 不是一份大样式表，而是分层管理： @@ -344,7 +354,13 @@ AIS 船只图层入口： AISStream 的 `PositionReport` 常带实时位置和 `MetaData.ShipName`，但船型通常来自低频 `ShipStaticData.Type`。后端会把 `MetaData.ShipName` 补进船名，并将类型码映射为 Cargo / Tanker / Passenger / Fishing / Military；仍缺失的船型需要等待静态 AIS 消息或后续船舶资料 enrichment，不能在前端凭颜色之外的信息臆造细分类。 -旧 `/api/v1/visualization/geo/vessels` 路由已移除。前端打开船只图层时只应拉取一次全局 `/api/v1/vessels/snapshot`；API 参数里的 bbox 是后端接口约束，Earth 运行时传全球范围，不表示当前镜头视口。`/ws` 的 `vessels` channel 如启用，只作为低频 reload/dirty 提示，不能把每条 AIS delta 直接变成整层重建。后端通过 `diagnostics.source == "vessel_current_state"` 暴露当前状态链路。 +旧 `/api/v1/visualization/geo/vessels` 路由已移除；初始数据仍通过全球 bbox 的 `/api/v1/vessels/snapshot` 读取。 + +AISStream 与 BarentsWatch 共用 `/ws` 的 `vessels` 增量通道。Earth 使用现有 WebSocket 连接订阅 `scope: "global"`，不跟随镜头改变订阅范围。后端按 MMSI 合并一秒内的通知，再读取 `vessel_current_state` 的已确认状态；单帧最多 1000 项，超过时继续发送后续帧，不截断不同船只。原始源消息不能直接覆盖客户端的确认位置。当前状态删除也会产生按 MMSI 的 remove 通知。 + +前端将短时间内同一 MMSI 的变更合并为最新值，通过 `Interactable.updateItems()` 原位修改位置和颜色缓冲。航向分桶变更只更新受影响的桶，容量不足才扩容；保留已有 marker 身份、锁定状态和材质。首次进入、重连、删除提示及每分钟巡检仍用 snapshot 校准，但不先清空整个图层。收到有数量上限的快照时，不能把被截断的船只当成删除；快照返回期间到达的较新更新和删除也不能被旧响应覆盖。快照携带查询开始时的 `generated_at`，与实时帧时间一起用于识别缓存旧快照，避免新船或删除状态被回滚。 + +`earth_updates` 中船舶普通写入的策略是 `delta`；专用通道连通时不再触发整层重拉。删除或断连后的校准使用 `reload`，并复用现有对象。关闭图层会取消船舶订阅并清空待应用变更。轨迹、冲突详情和审计继续按单船接口读取历史事实。 新的图层接口族是 `/api/v1/layers/*`，用于把地图渲染数据和聚合面板统计分开。地图层请求必须带 `bbox`、`zoom` 和受控 `limit`，响应会返回 `visible_count`、`returned_count` 和 `diagnostics`，其中 `degraded/truncated/limit_clamped` 用于前端提示降级。右侧聚合统计不要从图层响应累加，应读取 `/api/v1/data-products` 或 `/api/v1/data-products/{product_id}/status`，因为这些统计保持全量/全局口径，不随当前视口变化。 @@ -380,6 +396,8 @@ AISStream 的 `PositionReport` 常带实时位置和 `MetaData.ShipName`，但 详情卡里的坐标候选状态由 [info-card.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/info-card.js) 按 `entityType:entityId` 缓存在模块内存中。用户关闭详情卡或待定位列表后再次打开同一个算力中心 / BGP 观测站，已经采集到的候选和状态文案会恢复；`一键采用` 会优先使用缓存候选，避免重复调用在线地理编码或 LLM factcheck。保存成功后该实体的候选列表会清空为“正在刷新图层”状态，避免旧候选在刷新后继续误导用户。 +批量定位由 `runUnresolvedComputeCenterBatch()` 持有实体上下文队列，不持有面板 DOM；`locationCollectStateCache` 保存候选、进度和保存结果，重建卡片时重新 hydrate。`earth:compute-center-location-batch-change` 同步任务状态与气泡入口，成功条目根据 `savedCandidate` 排除，全部完成后保留 ✓ 入口。状态只存在当前 Earth 页面内存中，刷新、关闭或路由离开会终止未完成队列；已保存坐标仍以后端为准。 + 候选行的 `预览 / 保存` 按钮采用单一的事件委托模型：每个候选根（详情卡里的 `[data-collect-cache-key]` 块，或待定位列表里的 `[data-unresolved-item]`）只挂一个 `click` 监听，由 `data-candidate-actions-bound` 幂等标记，不再混用 `pointerup` / `click` 直绑或重复委托。候选对象不再以 JSON 字符串塞进 HTML 属性后再 `JSON.parse`，按钮只携带 `data-candidate-index`，handler 通过 cache-key 在模块内存的 `Map` 里取出原对象，避开 HTML 实体转义对 `&` / `<` / `"` 的破坏。点击 `预览` 会派发 `earth:preview-location-candidate`，由 `main.js` 的 `previewLocationCandidate()` 调用 `showComputeCenterLocationPreview()`：在候选经纬度上挂双层空心呼吸 sprite（视觉参考 BGP 事件 ring），并把视角聚焦到候选坐标；切换到另一个候选会替换为新呼吸圈，保存时立即清除并由 `spawnSavedComputeCenterLocation()` 即时生成正式算力中心交互图标。注意 `main.js` 没有模块级 `earth` 变量，所有 location-save / preview 处理函数必须先 `const earth = getEarth();`，否则会在事件 handler 里抛 `ReferenceError` 被 `.catch` 静默掉，外观上等同于按钮“没有反应”。 `earth:compute-center-location-saved` 之后的图层校准链路对后台刷新失败保持沉默：`spawnComputeCenterAfterLocationSave()` 已经把 toast 和 locked 状态都给了用户，`refreshComputeCentersAfterLocationSave()` 只在场景就绪时重新拉取后端数据，本身不再吐 `已保存` toast；`handleComputeCenterLocationSaved()` 在 spawn 成功路径让 refresh 静默后台运行，只在 spawn 返回 `null`（场景未就绪）或抛错时才让 refresh 接管成功 toast，refresh 自身报错只走 `console.warn`，绝不冒泡成 `保存失败` 文案——保存请求本身已经成功，刷新失败属于后续同步问题。 @@ -392,7 +410,7 @@ asset 图标大小由 `Interactable` 的 `icon.fitSize` 控制。SVG / 图片文 跨 Interactable 的同坐标关系也在公共层记录，但真实位置必须始终以 `icon_base_position` 为准。缩放、避让、聚合和后续 spiderfy 展开都只能改变屏幕表现，不能写回 `marker.position` 或 `THREE.Points` 里的业务锚点；巡航定位、详情卡、搜索定位和 picking 返回对象都必须落回真实经纬度。多个图标归入同一个经纬度 key 时，公共层只写 `icon_avoidance_*` 元数据，供业务层弱化 halo 或显示聚合提示；真正的低缩放聚合应通过独立 cluster glyph / screen layout 层实现，而不是把对象沿地表切平面挪开。 -`Interactable` 的单点显示只由全局地图缩放决定：170% 及以下强制显示小圆点，超过 170% 显示原图标。cluster 现在由 `cluster.strategy` 决定：`stable-spherical` 使用离散 zoom band 和 3D 球面分桶，BGP、算力中心和 Earth interactable 在同一 band 内旋转或细微缩放时不会重新计算聚合拓扑；`dynamic-screen` 保留屏幕空间聚类，适合船只这类实时高频图层；`none` 关闭聚类。稳定球面聚类的 cluster 圆点刚性落在成员 3D 质心投影上，不参与 2D 避让，避免缩放时被推离真实地理位置。cluster 圆点大小随包含对象数量增长，数量过多时按稳定地理顺序拆成多个较小圆点；数量默认只在 hover tooltip 中显示。这个过程只设置 `icon_cluster_*` 展示元数据和重建渲染 Points，不改变每个 marker 的真实经纬度。 +`Interactable` 的单点显示只由全局地图缩放决定：170% 及以下强制显示小圆点，超过 170% 显示原图标。cluster 现在由 `cluster.strategy` 决定：`stable-spherical` 使用离散 zoom band 和 3D 球面分桶，BGP、算力中心和 Earth interactable 在同一 band 内旋转或细微缩放时不会重新计算聚合拓扑；`dynamic-screen` 保留屏幕空间聚类；`none` 关闭聚类。船只显式关闭聚类与避让，保证增量更新时不重建聚类拓扑。稳定球面聚类的 cluster 圆点刚性落在成员 3D 质心投影上，不参与 2D 避让，避免缩放时被推离真实地理位置。cluster 圆点大小随包含对象数量增长，数量过多时按稳定地理顺序拆成多个较小圆点；数量默认只在 hover tooltip 中显示。这个过程只设置 `icon_cluster_*` 展示元数据和重建渲染 Points，不改变每个 marker 的真实经纬度。 接口细节、生命周期和接入示例见： diff --git a/docs/technical/zh/earth-layer-style-reference.md b/docs/technical/zh/earth-layer-style-reference.md index 93dc06f9..973ea107 100644 --- a/docs/technical/zh/earth-layer-style-reference.md +++ b/docs/technical/zh/earth-layer-style-reference.md @@ -149,6 +149,8 @@ ## 海缆与登陆点 +`cable-batches.js` 将海缆线与登陆点分别合批绘制。下表的 Sprite 材质和尺寸仍属于 `cables.js` 中的拾取、选择代理；每帧把颜色、透明度、缩放和可见性同步到样式纹理或实例属性。实际绘制使用 `LineSegments` 和实例化 billboard，沿用原纹理、色彩、层级与球体遮挡规则。 + | 正式名称 | 变量名 | 当前值 | 使用位置 / 说明 | | --- | --- | --- | --- | | 默认海缆颜色 | `CABLE_COLORS.default` | `0xffff44` | 无数据颜色时使用 | diff --git a/docs/technical/zh/earth-render-layer-order.md b/docs/technical/zh/earth-render-layer-order.md index 9e703d9f..eb08eb03 100644 --- a/docs/technical/zh/earth-render-layer-order.md +++ b/docs/technical/zh/earth-render-layer-order.md @@ -21,7 +21,7 @@ | 0.86 | 海陆基座填充 | `country-boundaries.js` | `landAltitudeOffset = 0.32`; 海洋 `#010609`，陆地 `#080f1b` | 禁用 raycast | 即使国界线关闭，基座地图仍保持可用；半径与基座球拉开以避免远距 z-fighting。 | | 0.96 | 高清 Earth 材质 | `earth.js` | `textureOverlayAltitudeOffset = EARTH_SURFACE_TEXTURE_ALTITUDE_OFFSET = 0.48` | 可见时作为地表拾取目标 | 高清材质始终压过海陆基座填充；半径必须高于海陆基座并与基座球保持足够间距。 | | 1 | 大气辉光和云图 | `earth.js` | 大气 / 云层球 | 不走普通对象选择路径 | 云图由“大气云图”图层开关控制。 | -| 1 | 海缆 / 登陆点 | `cables.js` | 海缆线和登陆点都使用 `renderOrder = 1`；半径偏移都为 `0.2`；登陆点是专用 `THREE.Sprite` 黄色扁平球 | 海缆走海缆拾取路径；登陆点 `depthTest: false` 保持球体完整，并用相机到球心的球体遮挡判断避免背面穿透 | 登陆点和海缆同层贴地，避免地表设施层的凌空感。 | +| 1 | 海缆 / 登陆点 | `cables.js`, `cable-batches.js` | 海缆全量线段合并为一个 `LineSegments`；登陆点全量使用实例化 billboard；`renderOrder = 1`、半径偏移 `0.2` 保持不变 | 原始 `Line` / `Sprite` 仅作为逐项拾取和选择状态对象，材质不再单独绘制；登陆点仍按球体遮挡判断背面可见性，批量材质 `depthTest: false` | 样式通过线缆样式纹理和登陆点实例属性同步；保留颜色、脉冲、尺寸、显隐与点击语义。 | | 1.2 | 真实地形 | `earth.js`, `terrain.js` | `TERRAIN_CONFIG.baseRadiusOffset` 加地形位移 | 禁用 raycast | 地形压过高清材质；高清材质关闭时临时隐藏，重新开启后恢复原状态。 | | 2.05 | 经纬线 | `earth.js` | `CONFIG.earthRadius + 0.14` | 禁用 raycast | 低透明度显示在高清材质上。 | | 2.2 | 国界线 | `country-boundaries.js` | `lineAltitudeOffset = EARTH_SURFACE_TEXTURE_ALTITUDE_OFFSET = 0.48`；claim 线不再额外抬高 | `depthTest: true`，禁用 raycast | 线层使用独立 line geometry 与 `renderOrder` 控制，但半径与高清材质壳完全一致，避免转动地球时与高清贴图出现视差。 | @@ -37,6 +37,14 @@ | 12+ | 卫星锁定 ring、halo、预测轨道 | `satellites.js` | `SATELLITE_CONFIG.overlayRenderOrder` 及偏移；预测轨道使用同一真实高度开关，并固定锁定时刻的地球姿态来绘制闭合惯性轨道；关闭真实高度时回到同层球面 | 卫星覆盖层路径 | 用于选中 / 锁定卫星强调。 | | 98-100 | 太阳 / 月亮 halo 和 sprite | `celestial.js` | 固定 renderOrder | 天体拾取禁用 | 前景天体 sprite。 | +## 全量绘制与更新约束 + +- 合批只改变 GPU 提交方式，不减少卫星、线段或登陆点数量，也不按相机半球裁剪数据。海缆每对相邻顶点都保留，拾取仍返回原始业务对象。 +- 卫星普通点与背景点保持两个 `Points` 绘制；呼吸动画由顶点着色器使用静态逐点参数和每帧统一时间计算。hover / locked 的隐藏标记仍由原有选择状态控制。 +- `satellite-position-worker.js` 使用与主线程相同的 Three.js / SGP4 版本，通过 `satellite-propagation.js` 共享轨道、显示高度和 fallback 计算；全量位置及初始轨迹以可转移数组交给主线程。主线程维持一个在途计算，不堆积过期帧；重载、清空和高度模式变更会终止旧 Worker。 +- Worker 启动失败或超过 `SATELLITE_CONFIG.workerStartupTimeoutMs` 时退回共享的同步计算，避免图层无限等待。计数、数据接口、原有更新周期和轨迹长度不变。 +- 验证时同时检查全量 draw range、逐项拾取、锁定覆盖层、轨迹、背面遮挡、开关及清空后的资源释放；比较帧耗时必须使用相同数据、相同视角和分辨率。 + ## 开关联动 | 开关 | 行为 | diff --git a/docs/technical/zh/manual.md b/docs/technical/zh/manual.md index b1f22d31..87eec58e 100644 --- a/docs/technical/zh/manual.md +++ b/docs/technical/zh/manual.md @@ -126,6 +126,9 @@ ### AISStream 实时船舶 +在智能星球打开船只图层后，AISStream 与 BarentsWatch 的后续位置会自动更新。更新时会保留已选中的船只；短暂断线重连后会自动校准，无需反复关闭、开启图层。 + + `AISStream 实时船舶` 是全球 AIS WebSocket 采集器。连接测试通过只说明 API Key 和 endpoint 格式可用；真正的全球船只数据来自后台 `aisstream_vessels` collector 长连接运行并写入 `ais_raw_observations`。 操作步骤： @@ -165,6 +168,8 @@ provider 和模型既可选预设也可直接输入自定义 id/name。常用字 Base URL 输入框尾端的插头图标会触发连接测试。测试通过会显示当前模型返回的简短回复。 +点击右上角的刷新图标可更新“可选模型”。成功后目录会保存，重新打开页面仍可使用；有发布日期的目录按新到旧排列。刷新保留当前模型、密钥、地址和未保存的修改。点击一个可选模型后，再点“保存”才会改变实际使用的模型。刷新失败时会显示错误并保留上次目录。 + ### 工具 - **WebSearch**：provider、API Key、Base URL、最大结果数、超时、高级 provider 参数。未启用时除"启用"开关外其它配置项和连接测试都会置灰 @@ -281,6 +286,10 @@ AIS 船只图例按船型显示颜色：货轮、油轮、客船、渔船、军 支持查找海缆、登陆点、卫星、算力中心、BGP 事件、BGP 观测站。结果可快速定位并打开详情。 +### 新闻直播源选择 + +打开媒体面板的直播页，点击当前频道可展开搜索菜单。搜索会检索完整频道库；列表每次加载 50 个频道，滚动到底部自动追加。底部固定显示已加载数量和搜索结果总数，加载失败时可在列表下方重试。默认新闻直播源为 Al Jazeera Mubasher（半岛电视台），使用 HLS 播放地址；其他频道仍取决于各自的播放服务是否可用。 + ### 位置候选采集 算力中心和 BGP 观测站详情卡支持自动采集坐标候选。点击对象后用"自动采集坐标候选"或"重新自动采集坐标"按钮，后端会从源坐标、开放组织注册 API 和在线地理编码中整理候选；常规来源没有候选时使用当前默认 AI Provider 做 LLM factcheck 兜底。BGP 观测站的已存储位置只用于补齐查询上下文，不会作为候选直接返回。 @@ -297,6 +306,8 @@ AIS 船只图例按船型显示颜色：货轮、油轮、客船、渔船、军 一键定位用于批量处理算力中心待定位队列。它会从列表顶部开始采用最高置信候选；仍没有事实依据的记录会保留在队列中。未开启 WebSearch 时，单个定位和一键定位会置灰，因为位置核验依赖事实查询。 +在当前智能星球页面内，关闭候选面板、查看其他对象或切换浏览器标签页不会取消队列；返回候选列表后可继续查看进度和结果。已保存条目不会再次采集，全部完成后仍可通过图层旁的 ✓ 入口查看结果。刷新、关闭页面或跳转离开智能星球会中断尚未完成的队列，已经保存的坐标会保留。 + ### 设置 设置面板按分类组织：运行、显示、面板、动捕、快捷键、系统。里面包含旋转模式 / 巡航模式 / 动捕模式、巡航模块（BGP/新闻/算力中心/船只/海缆/卫星）、视图设置（卫星显示风格、悬停提示、卫星呼吸闪烁、真实卫星高度、轨迹显示、低缩放圆点、日夜模式、面板显示开关）、动捕调试模式 / 输入源 / 只显示骨骼 / 识别动作白名单、快捷键启用与改键、地球默认大小、地形透明度、重置设置。 diff --git a/docs/technical/zh/ops-planet-sh-startup.md b/docs/technical/zh/ops-planet-sh-startup.md index e3d5e751..968b319c 100644 --- a/docs/technical/zh/ops-planet-sh-startup.md +++ b/docs/technical/zh/ops-planet-sh-startup.md @@ -2,6 +2,10 @@ ## 背景 +日常启动使用 `zsh ./planet.sh start --non-motion-agent`；新环境首次准备才需要 `init`。排查耗时时，应区分首次依赖下载、容器就绪和应用初始化，结合阶段日志时间判断。 + +当前启动流程在准备 AI Provider 镜像前验证后端实际数据库连接，端口映射缺失时保留数据卷重建一次。后端进程退出，或 Uvicorn 日志出现应用初始化失败、ASGI 加载失败、导入或语法错误时，会立即停止等待和重复启动；正常的慢启动仍保留原有等待预算。AI Provider 直接探测宿主机 `/health`，无需再等待 Docker 周期性健康检查首次运行。 + `planet.sh` 管理所有服务的启动/停止/重启。原有实现存在以下问题： 1. AI Provider 每次都重新构建（即使代码未变） @@ -37,27 +41,9 @@ write_ai_provider_build_stamp() { } ``` -### fingerprint 计算提速 +### fingerprint 检查范围 -原实现对整个 `aiprovider/` 打 tar 包再算 SHA，大目录下耗时可达数秒。改为 `find + stat`（只读文件元信息，不读内容）： - -```bash -compute_ai_provider_build_fingerprint() { - find aiprovider \ - -type f \ - ! -path '*/__pycache__/*' \ - ! -name '.env' \ - ! -name '.env.*' \ - ! -name '*.pyc' \ - ! -name '*.pyo' \ - | LC_ALL=C sort \ - | xargs -r stat --format="%Y %s %n" 2>/dev/null - sha256sum docker-compose.yml docker-compose.simple.yml 2>/dev/null - python3 "$SCRIPT_DIR/scripts/compute_aiprovider_dependency_fingerprint.py" 2>/dev/null -} -``` - -速度提升约 10 倍（大量小文件场景），误报率相同（mtime+size 变化 ≡ 文件被修改）。 +当前指纹使用内容 SHA，覆盖 `aiprovider/`、Dockerfile、根依赖清单与锁文件，以及代理服务相关依赖信息；不会遍历前端资源或下载数据。`.env` 配置不参与镜像内容指纹。构建标记只用于判断是否需要构建，Dockerfile 中的指纹标签位于依赖安装之后，以保留前置依赖层缓存。 `.env` 和 `.env.*` 被排除在 fingerprint 外。它们属于运行期配置，不应该因为修改模型、密钥或 Base URL 触发镜像重建。 @@ -85,13 +71,15 @@ Dockerfile 也从全仓复制改为只复制 AI Provider 代码： ```dockerfile COPY pyproject.toml uv.lock /app/ RUN --mount=type=cache,target=/root/.cache/uv \ - uv sync --frozen --no-dev + uv sync --frozen --only-group aiprovider COPY aiprovider /app/aiprovider ``` `uv sync` 使用 BuildKit cache mount 后，首次构建仍可能受网络影响；后续构建会复用 `/root/.cache/uv`，依赖下载不再重复从零开始。 +`aiprovider` 依赖组在根 `pyproject.toml` 定义，并由同一份 `uv.lock` 锁定，只安装 FastAPI、HTTP 客户端、配置读取和 ASGI 服务所需依赖。镜像不安装后端采集或 OpenCV / MediaPipe 动捕依赖。构建指纹标签放在依赖安装和代码复制之后，指纹改变不会单独使依赖层缓存失效。容器直接启动已安装的 `.venv/bin/python`，运行时不再执行 `uv sync`。修改代理服务的依赖时，应同步更新该依赖组和锁文件，并验证镜像导入及 `/health`。 + ### 运行期配置来源 `planet.sh` 启动 AI Provider 前会生成受当前用户保护的运行期 env-file，并把它传给 Compose 或手动 `docker run` fallback。默认路径位于 `${XDG_STATE_HOME:-$HOME/.local/state}/planet/aiprovider_runtime.env`。配置优先来自： @@ -119,7 +107,7 @@ fingerprint 一致时不执行 `docker compose build`，而是： docker start planet_aiprovider # 启动已存在的容器，几秒内完成 ``` -`docker stop` 停容器，不删镜像；`cleanup_exit_containers` 删已退出容器，不删镜像。下次 `docker start` 会从现有镜像直接创建并启动容器。 +`docker stop` 停容器，不删镜像。`start` 和 `restart` 保留已停止的容器，不再扫描删除全机已退出容器；未变化的 AI Provider 可直接复用，数据库仍由 Compose 同步配置。只有需要更新镜像或容器配置时才按原有流程重建。 ## 问题二：杀端口速度慢 diff --git a/docs/technical/zh/ops-runbook.md b/docs/technical/zh/ops-runbook.md index 50e9b4a1..c5d47b4a 100644 --- a/docs/technical/zh/ops-runbook.md +++ b/docs/technical/zh/ops-runbook.md @@ -33,9 +33,9 @@ docker buildx version ## 数据库初始化与连接检查 -`init` 会先通过 Compose 同步 PostgreSQL / Redis 容器配置，包括已有容器的端口映射；仅执行 `docker start` 无法应用配置变化。Compose 同步失败时会保留具体错误，例如端口被占用，不会继续复用旧容器并报告成功。 +`init` 和 `start` 会先通过 Compose 同步 PostgreSQL / Redis 容器配置，包括已有容器的端口映射；仅执行 `docker start` 无法应用配置变化。Compose 同步失败时会保留具体错误，例如端口被占用，不会继续复用旧容器并报告成功。 -容器内部的 `pg_isready` 只检查服务是否接受连接，不能证明宿主机上的后端使用正确地址和密码。容器健康后，`init` 通过 `scripts/check_database_connection.py` 读取与后端相同的有效 `DATABASE_URL`，检查本地 PostgreSQL 的实际发布端口并执行只读 `SELECT 1`；通过后才显示“数据库服务已就绪”并创建表和默认数据。 +容器内部的 `pg_isready` 只检查服务是否接受连接，不能证明宿主机上的后端使用正确地址和密码。容器健康后，`init` 和后端启动流程通过 `scripts/check_database_connection.py` 读取与后端相同的有效 `DATABASE_URL`，检查本地 PostgreSQL 的实际发布端口并执行只读 `SELECT 1`。启动流程在准备 AI Provider 镜像之前完成此检查；失败会立即停止。`init` 通过检查后才创建表和默认数据。 - 如果本地实际端口映射仍缺失或不匹配，脚本会保留数据卷，按 Compose 配置重建一次 PostgreSQL 并重新检查；再次失败就停止。 - 认证、库名或网络错误会在建表前停止，诊断只显示目标主机、端口和库名，不输出密码、完整连接串或驱动异常原文。 diff --git a/docs/technical/zh/quickstart.md b/docs/technical/zh/quickstart.md index f54a28df..a0877698 100644 --- a/docs/technical/zh/quickstart.md +++ b/docs/technical/zh/quickstart.md @@ -33,7 +33,7 @@ 进入 `/admin` 仪表盘后，建议按这个顺序熟悉控制台： 1. `/collection-management?section=collector_credentials`：选一个采集器，点插头图标做连接测试。免费 collector（开源 BGP 等）通常直接可用；像 `AISStream`、`BarentsWatch` 这类需要凭证的，需要先填 API Key/Client Secret -2. `/ai?section=integrations`：填一个 LLM provider（例如 `minimax` / `openai`）、模型名、Base URL、API Key，点 Base URL 末端的插头测试连接。WebSearch / OCR 工具可选 +2. `/ai?section=integrations`：填一个 LLM provider（例如 `minimax` / `openai`）、模型名、Base URL、API Key，点 Base URL 末端的插头测试连接。右上角刷新图标会更新并保存可选模型目录，同时保留当前表单；选中新模型后点“保存”生效。WebSearch / OCR 工具可选 3. `/earth-content?section=brand`：在“品牌标识”里维护智能星球的 Logo 和标题图；对应地址字段内的“上传”按钮支持选择文件，也支持把图片直接拖到字段上，保存后会应用到智能星球 HUD 4. `/datasources` 或 `/data`：看采集器是否已经产出数据。有限采集器看 `/datasources -> 内置源`，不勾选时点“触发全部”，勾选后主按钮会变成“触发已选 N”；右上角队列按钮可查看进度。AISStream / WebSocket 长连接看 `/datasources -> 实时源` 的健康状态和计数 5. `/alerts/system`：看系统告警是否正常 @@ -50,6 +50,9 @@ - 地球正常显示，右侧图层面板可以打开/关闭 - 搜索可以查找海缆、卫星、算力中心、BGP 事件 - 算力中心和 BGP 观测站详情卡可以自动采集坐标候选，并能在智能星球上预览 +- 一键定位期间关闭候选面板或切换浏览器标签页，再返回可查看进度；刷新或离开智能星球页面会中断未完成队列 +- 船只图层持续接收 AISStream / BarentsWatch 位置，断线重连后自动校准 +- 直播菜单可搜索完整频道库，滚到底部继续加载；默认频道为半岛电视台 - 鼠标拖动、滚轮缩放、缩放百分比提示工作正常 - 设置面板的旋转 / 巡航 / 动捕模式可以切换；动捕设置可以选择输入源和允许识别的动作；视图设置里可以切换悬停提示，卫星相关设置里可以打开或关闭真实高度分层和轨迹显示 diff --git a/docs/version-history.md b/docs/version-history.md index 2dce617b..eb0b6f06 100644 --- a/docs/version-history.md +++ b/docs/version-history.md @@ -16,12 +16,13 @@ ## Current Version - `main` 当前主线历史推导到：`0.16.5` -- `dev` 当前开发分支历史推导到：`0.74.3` +- `dev` 当前开发分支历史推导到：`0.74.4` ## Timeline | Version | Type | Branch | Commit | Summary | | --- | --- | --- | --- | --- | +| `0.74.4` | improvement | `dev` | `v0.74.4` | Earth 全量渲染与船舶增量更新优化，直播目录搜索和分页，定位队列状态恢复、模型目录保存及启动提速 | | `0.74.3` | improvement | `dev` | `v0.74.3` | Ubuntu / WSL 初始化自动准备 Docker 及用户权限，修正启动诊断，并在建表前核对数据库端口、实际连接和认证 | | `0.74.2` | bugfix | `dev` | `pending` | 收敛 agent harness 到根规则和 Codex skills，删除旧 Claude command 重复入口，并强化视觉证据路径解析与 OCR fallback 规则 | | `0.74.1` | improvement | `dev` | `pending` | 将品牌标识上传收敛到 Logo/标题图字段内，新增字段级拖拽反馈和 Tactile UI primary 上传按钮，并同步中英文使用文档 | diff --git a/frontend/package.json b/frontend/package.json index 67af8620..2c1ae669 100644 --- a/frontend/package.json +++ b/frontend/package.json @@ -1,6 +1,6 @@ { "name": "planet-frontend", - "version": "0.74.3", + "version": "0.74.4", "private": true, "packageManager": "bun@1", "dependencies": { diff --git a/frontend/public/earth/css/hud.css b/frontend/public/earth/css/hud.css index 0f6e0e69..b5e6033f 100644 --- a/frontend/public/earth/css/hud.css +++ b/frontend/public/earth/css/hud.css @@ -1100,7 +1100,6 @@ display: none; } -.earth-mobile-tv-select, .earth-mobile-settings-slider { width: 100%; } @@ -1215,14 +1214,6 @@ margin-top: 0; } -.earth-mobile-tv-select { - border: 1px solid rgba(201, 225, 247, 0.14); - border-radius: 12px; - background: rgba(255, 255, 255, 0.04); - color: var(--hud-text); - padding: 10px 12px; -} - .earth-mobile-tv-player { position: relative; aspect-ratio: 16 / 9; diff --git a/frontend/public/earth/css/info-panel.css b/frontend/public/earth/css/info-panel.css index 61ca6d30..7c4f269e 100644 --- a/frontend/public/earth/css/info-panel.css +++ b/frontend/public/earth/css/info-panel.css @@ -669,14 +669,21 @@ .info-card-compute-candidate-preview.is-loading::before, .info-card-unresolved-item.is-locating .info-card-unresolved-index::before { content: ""; + display: inline-block; + flex-shrink: 0; width: calc(10px * var(--hud-scale)); height: calc(10px * var(--hud-scale)); + vertical-align: middle; border: 1.5px solid rgba(201, 220, 255, 0.35); border-top-color: #c9dcff; border-radius: 999px; animation: info-card-location-spin 0.8s linear infinite; } +.info-card-compute-candidate-preview.is-loading::before { + margin-inline-end: 4px; +} + .info-card-unresolved-item.is-locating .info-card-unresolved-index { color: transparent; } @@ -848,9 +855,3 @@ .info-card-unresolved-adopt:hover { background: rgba(255, 171, 81, 0.16); } - -.info-card-unresolved-empty { - padding: calc(10px * var(--hud-scale)) 0; - color: var(--hud-text-soft); - font-size: calc(0.74rem * var(--hud-scale)); -} diff --git a/frontend/public/earth/css/tv-panel.css b/frontend/public/earth/css/tv-panel.css index acda69b0..bf743603 100644 --- a/frontend/public/earth/css/tv-panel.css +++ b/frontend/public/earth/css/tv-panel.css @@ -109,10 +109,196 @@ font-size: calc(0.84rem * var(--hud-scale)); } -.tv-panel-select option, -.tv-panel-select optgroup { - background: #0a1422; - color: #eef5fc; +.tv-source-trigger { + display: inline-flex; + align-items: center; + justify-content: space-between; + gap: var(--hud-gap-xs); + text-align: left; + cursor: pointer; + font-family: inherit; + height: calc(36px * var(--hud-scale)); + padding-block: 0; + line-height: 1; +} + +.tv-source-trigger__label { + min-width: 0; + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; +} + +.tv-source-trigger > .material-symbols-rounded { + flex: 0 0 auto; + font-size: calc(16px * var(--hud-scale)); + color: var(--hud-text-soft); +} + +.tv-source-trigger[aria-expanded="true"] { + border-color: var(--hud-border-hover); + background: rgba(120, 180, 255, 0.12); +} + +.tv-source-trigger:focus-visible, +.tv-source-menu__more:focus-visible { + outline: 2px solid var(--hud-accent-strong); + outline-offset: 2px; +} + +.tv-source-menu { + position: fixed; + inset: auto; + margin: 0; + padding: 0; + border-radius: 0; + color: var(--hud-text); + font-family: inherit; +} + +.tv-source-menu:popover-open { + display: flex; + flex-direction: column; +} + +.tv-source-menu__search { + display: flex; + align-items: center; + gap: var(--hud-gap-xs); + flex: 0 0 auto; + padding: calc(10px * var(--hud-scale)); + border-bottom: 1px solid var(--hud-line); +} + +.tv-source-menu__search > .material-symbols-rounded { + color: var(--hud-text-soft); + font-size: calc(18px * var(--hud-scale)); +} + +.tv-source-menu__search input { + flex: 1 1 auto; + min-width: 0; + width: 100%; + border: 0; + outline: none; + background: transparent; + color: var(--hud-text); + font: inherit; + font-size: calc(0.78rem * var(--hud-scale)); +} + +.tv-source-menu__search:focus-within { + box-shadow: inset 0 -1px 0 var(--hud-accent-strong); +} + +.tv-source-menu__search input::placeholder { + color: var(--hud-text-soft); +} + +.tv-source-menu__body { + display: flex; + flex: 1 1 auto; + flex-direction: column; + min-height: 0; +} + +.tv-source-menu__list { + flex: 1 1 auto; + min-height: 0; + max-height: none; + overscroll-behavior: contain; +} + +.tv-source-menu__option { + width: 100%; + flex: 0 0 auto; + border: 0; + background: transparent; + color: var(--hud-text); + font: inherit; + text-align: left; + cursor: pointer; +} + +.tv-source-menu__option.is-active { + background: rgba(120, 180, 255, 0.1); +} + +.tv-source-menu__option[aria-selected="true"] { + background: rgba(120, 180, 255, 0.15); +} + +.tv-source-menu__option > .material-symbols-rounded { + flex: 0 0 auto; + font-size: calc(14px * var(--hud-scale)); +} + +.tv-source-menu__check { + color: var(--hud-accent-strong); + visibility: hidden; +} + +.tv-source-menu__option[aria-selected="true"] .tv-source-menu__check { + visibility: visible; +} + +.tv-source-menu__default, +.tv-source-menu__count, +.tv-source-menu__more { + color: var(--hud-text-soft); + font-size: calc(0.68rem * var(--hud-scale)); +} + +.tv-source-menu__default { + flex: 0 0 auto; + white-space: nowrap; +} + +.tv-source-menu__warning { + color: #ffd166; +} + +.tv-source-menu__count, +.tv-source-menu__empty, +.tv-source-menu__more { + flex: 0 0 auto; + padding: calc(8px * var(--hud-scale)) calc(10px * var(--hud-scale)); +} + +.tv-source-menu__count { + border-top: 1px solid var(--hud-line); +} + +.tv-source-menu__empty { + color: var(--hud-text-muted); + font-size: calc(0.78rem * var(--hud-scale)); +} + +.tv-source-menu__more { + border: 0; + background: rgba(120, 180, 255, 0.06); + font-family: inherit; + cursor: pointer; +} + +.tv-source-menu [hidden] { + display: none; +} + +.earth-mobile-page--tv > .tv-source-trigger { + flex: 0 0 auto; + width: 100%; + height: 40px; +} + +.layout-mode-mobile .tv-source-menu__search input, +.layout-mode-mobile .tv-source-menu__option .legend-label { + font-size: 14px; +} + +.layout-mode-mobile .tv-source-menu__search, +.layout-mode-mobile .tv-source-menu__option { + min-height: 40px; } .tv-panel-meta-wrap { diff --git a/frontend/public/earth/index.html b/frontend/public/earth/index.html index e957cbbd..bde8f83a 100644 --- a/frontend/public/earth/index.html +++ b/frontend/public/earth/index.html @@ -511,7 +511,7 @@ Live 新闻
- +
- +
暂无可播放直播源，请先在系统配置中添加频道。