planet/docs/technical/en/manual.md

# Planet Manual

This manual is for daily use, demos, development integration, and local operations. It covers four core entry points:

- `planet.sh`: local start, stop, restart, health check, and log access
- Earth: public 3D situational awareness page
- Console: admin backend (login required)
- Docs: backend Gatekeeper-controlled documentation; basic usage docs are public, while developer and operations docs require permission groups

For the shortest path to getting started, see [Quickstart](/home/ray/dev/linkong/planet/docs/technical/en/quickstart.md). For common troubleshooting, see the [FAQ](/home/ray/dev/linkong/planet/docs/technical/en/faq.md).

## Entry Overview

After a default startup, the common URLs are:

| Name | URL | Login Required | Description |
| --- | --- | --- | --- |
| Earth | `http://localhost:3000/earth` | No | 3D globe, layers, BGP, satellites, cables, news situational awareness |
| Docs | `http://localhost:3000/docs` | Partly | Usage docs are public; developer, backend, and operations docs require Gatekeeper groups |
| FAQ | `http://localhost:3000/docs/faq` | No | Windows / WSL, ports, dependencies, motion capture, credentials, and permission troubleshooting |
| Console | `http://localhost:3000/admin` | Yes | Data, config, alerts, logs, and situational observation |
| AI Playground | `http://localhost:3000/playground` | Yes | AI Provider status and debugging |
| Backend API Docs | `http://localhost:8000/docs` | Depends on endpoint | FastAPI / OpenAPI documentation |

## planet.sh

`planet.sh` is the main control script for local development and demos. Use it to manage services rather than manually starting frontend, backend, database, and AI Provider separately.

### Start

```bash
./planet.sh start
```

Default behavior:

- Starts PostgreSQL and Redis
- Starts AI Provider
- Starts the backend API
- Starts the frontend Vite dev server
- Outputs Earth, console, Playground, and backend API doc URLs

Specify custom ports:

```bash
./planet.sh start -b 8001 -f 3001 -a 8101
```

Parameters:

| Flag | Meaning |
| --- | --- |
| `-b <port>` | Backend port |
| `-f <port>` | Frontend port |
| `-a <port>` | AI Provider port |
| `--allow-lan` | Enable LAN access |
| `--verbose` | Show more command output during execution |

### AI Provider Environment and Builds

AI Provider runtime configuration can live in `aiprovider/.env` or in matching variables in `~/.zshrc`. `planet.sh` reads simple `export AI_...=...` / `AI_...=...` lines and passes them to the container at startup.

Changing model, API key, or base URL does not rebuild the image. Restart only AI Provider to pick up runtime configuration changes:

```bash
./planet.sh restart -a
```

For complex shell expansion in `~/.zshrc`, opt in explicitly:

```bash
PLANET_LOAD_ZSHRC_ENV=source ./planet.sh start -a
```

To ignore `~/.zshrc` during troubleshooting:

```bash
PLANET_LOAD_ZSHRC_ENV=0 ./planet.sh start -a
```

The AI Provider Docker build context is intentionally limited to the files required by the service, and `uv sync` uses a BuildKit cache mount so dependency downloads are reused after the first build.

### Stop

```bash
./planet.sh stop
```

Stops:

- Backend
- AI Provider
- Frontend
- PostgreSQL
- Redis

### Restart

Full restart:

```bash
./planet.sh restart
```

Per-module restart:

```bash
./planet.sh restart -b
./planet.sh restart -f
./planet.sh restart -a
./planet.sh restart -d
```

| Flag | Effect |
| --- | --- |
| `-b` | Backend only |
| `-f` | Frontend only |
| `-a` | AI Provider only |
| `-d` | Database only |

Per-module restarts are preferred during development — they avoid interrupting unrelated services.

### Create User

```bash
./planet.sh createuser
```

Used to create a console login account before first use. The script interactively prompts for username, password, and role.

### Health Check

```bash
./planet.sh health
```

Checks:

- `planet_*` container status
- Backend `/health`
- AI Provider `/health`
- Frontend reachability

If something shows offline, check the corresponding logs first.

### Logs

Recent logs:

```bash
./planet.sh log
```

Follow logs:

```bash
./planet.sh log -f
./planet.sh log -b
./planet.sh log -a
```

| Flag | Log source |
| --- | --- |
| `-f` / `--frontend` | `/tmp/planet_frontend.log` |
| `-b` / `--backend` | `/tmp/planet_backend.log` |
| `-a` / `--ai-provider` | `planet_aiprovider` container logs |

### LAN Access

```bash
./planet.sh start --allow-lan
```

Useful for:

- Starting in WSL, accessing from Windows browser
- Demos on phone or tablet
- Another machine on the same LAN accessing the same dev instance

`--allow-lan` only makes the frontend and backend listen on `0.0.0.0`. When Planet runs in WSL, Windows can usually reach it through `localhost`, but access from a phone or another computer through `http://<Windows LAN IP>:3000` still depends on Windows port forwarding and firewall rules.

Use this order to diagnose:

```bash
# From WSL or the shell running Planet
curl http://localhost:3000
curl http://localhost:8000/health
ss -ltnp | grep -E ':3000|:8000'
```

If this shows `0.0.0.0:3000` and `0.0.0.0:8000`, but the LAN IP still fails, configure Windows from an elevated PowerShell:

```powershell
netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=3000 connectaddress=127.0.0.1 connectport=3000
netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=8000 connectaddress=127.0.0.1 connectport=8000

New-NetFirewallRule -DisplayName "WSL Planet 3000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 3000
New-NetFirewallRule -DisplayName "WSL Planet 8000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 8000
```

## Earth

Earth is the public 3D situational awareness page, accessed at:

```text
http://localhost:3000/earth
```

It is a standalone frontend. The actual page lives at:

- `frontend/public/earth/index.html`
- `frontend/public/earth/js/`
- `frontend/public/earth/css/`

The React route `/earth` simply hosts it in an iframe.

### Main Uses

Earth is used to observe in a single globe view:

- BGP events, anomalies, and situational posture
- Satellites and orbital trails
- Submarine cables and landing points
- Compute centers
- AIS vessels
- Border lines, grid lines, HD texture, cloud layer, terrain
- Live news streams and situational news
- Search and focused object details

### Layer Control

The right-side layer panel toggles visualization layers on or off.

Common layers include:

- Grid lines
- Border lines
- HD texture
- Atmospheric cloud layer
- Submarine cables
- Compute centers
- BGP observation
- AIS vessels
- Satellites
- Orbital trails
- Terrain

Some layers have dependencies:

- Terrain requires HD texture
- Trails require Satellites
- When HD texture is off, the globe shows the base map and edge glow effect

### Legend

The lower-left legend follows the currently focused or enabled layer.

Current legend modes include:

- Cables
- Satellites
- Border lines
- Compute centers
- BGP
- AIS vessels

AIS vessel legend entries are grouped by vessel type: cargo, tanker, passenger, fishing, military, anchored/slow, and other. Triangle markers represent moving vessels; dots represent anchored or slow vessels.

### Search

Earth search finds current globe objects, such as:

- Submarine cables
- Landing points
- Satellites
- Compute centers
- BGP events
- BGP collectors

Search results can be used to quickly locate objects and open their details.

### Location Candidate Collection

Compute-center and BGP collector detail cards can collect candidate coordinates automatically. After clicking an object, use `自动采集坐标候选` or `重新自动采集坐标`; the backend ranks source coordinates, open organization lookups, and Nominatim online search results. If those regular sources return no candidates, the current default AI Provider is used once as an LLM factcheck fallback. Stored BGP collector locations are used as query context only and are not emitted as candidates.

Candidates can be previewed directly on Earth. Compute-center candidates can be saved into the `compute_center_locations` dimension table from the detail card, then the layer refreshes immediately. The notification badge on the compute-center layer row shows unresolved records that cannot be rendered; clicking it opens the queue, where users can collect individual candidates or use `一键采用` to save the highest-confidence candidate top-to-bottom. Records without candidates stay in the queue and are not replaced by country centroids or hard-coded hints. See [Earth Location Candidate Collection User Guide](/home/ray/dev/linkong/planet/docs/technical/en/location-pipeline-user.md) for the full workflow.

### Settings

The settings panel contains:

- Rotation mode / cruise mode / motion mode
- Cruise modules: BGP, News, Compute Centers, Vessels, Cables, Satellites
- View settings: satellite display style, day/night mode, panel visibility
- Motion Debug Mode, Motion Input Source, skeleton-only debug view
- Globe default size
- Terrain opacity
- Reset settings

These settings are stored in browser local storage. They revert to defaults if you switch browsers or clear site data.

### View Controls

Earth supports mouse, touchpad, and touchscreen interaction.

Common controls:

| Action | Result |
| --- | --- |
| Left-button drag | Rotates the globe |
| One-finger drag | Rotates the globe on touch devices |
| Mouse wheel | Zooms the view in or out |
| Two-finger pinch | Zooms the view on touch devices |
| Zoom buttons | Adjust zoom in fixed steps |
| Click the zoom percent | Resets to the default zoom |

When zooming, the top capsule briefly shows the current zoom level, for example `Zoom 180%`. This indicates view zoom only, not data loading progress. Loading status takes priority and will not be interrupted by zoom feedback.

Drag sensitivity adjusts automatically based on the current zoom. Around the default view it keeps the normal rotation feel; when zoomed in, dragging becomes progressively finer for inspecting a region, vessel, satellite, or BGP event; when zoomed out, dragging is slightly faster for global browsing.

### Motion Capture Controls

Earth has a motion-capture control entry point for large-screen and future 3D displays. There are two realtime input sources: the default `Browser Camera` source uses webpage `getUserMedia` and recognizes gestures locally in the browser; the advanced `Motion Agent` source uses `camera/RTSP/HTTP -> local Agent -> local WebSocket -> Earth page`. Neither path sends camera frames or realtime gesture decisions to the cloud, and neither path reuses the news/RSS aggregation APIs.

It is disabled by default. Enable `Motion Debug Mode` in settings, open Earth with `?motion=1`, or set `planet-earth-motion-control-enabled=true` in browser local storage to start the selected source. The default source is `Browser Camera`; it requires HTTPS or localhost and a granted browser camera permission, but does not require installing an app. For dual cameras, USB indexes, phone/network camera streams, client integration, or edge devices, switch the setting to `Motion Agent`. The default Agent URL is `ws://127.0.0.1:8765/ws/gestures`; the `motionAgent` URL parameter can override it.

URL parameters can also force the source: `?motion=1&motionProvider=browser` uses the browser camera, `?motion=1&motionProvider=agent` uses Motion Agent, and providing `motionAgent=ws://...` automatically selects Motion Agent.

Current gesture semantics:

| Gesture event | Result |
| --- | --- |
| `rotate_left` | Rotates the globe left |
| `rotate_right` | Rotates the globe right |
| `rotate_up` | Rotates the globe upward |
| `rotate_down` | Rotates the globe downward |
| `zoom_in` | Zooms in |
| `zoom_out` | Zooms out |
| `focus_prev` / `focus_next` | Switches targets within the current motion layer |
| `layer_prev` / `layer_next` | Switches the motion candidate layer and cruises to the nearest target in that layer |
| `confirm` | Confirms the currently selected target; browser recognition currently keeps the two-hands-up confirm gesture disabled |

The settings panel also includes `Motion Debug Mode`, which opens the debug panel. With the Browser Camera source, the panel shows a local live preview and draws joints and bones over it. With the Motion Agent source, the Agent sends normalized skeleton events only and does not send raw video frames. The `Skeleton Only` switch hides the video preview and keeps the dark canvas plus skeleton; `Stop Matching Gestures` pauses gesture execution while preview and skeleton drawing can continue for debugging. Unmatched skeletons are red; once a gesture matches, the skeleton turns green and the matched gesture name is shown. Both this entry and the `Motion Input Source` control already carry Gatekeeper permission markers for future authorization control.

### Cruise Mode

Cruise mode makes Earth automatically cycle through focus targets.

Current cruise modules:

- BGP
- News
- Compute Centers
- Vessels
- Cables
- Satellites

Suitable for demos, monitoring displays, or unattended presentations.

### Mobile

Earth has a mobile drawer layout. On small screens:

- Layer controls open in a mobile drawer
- Search, settings, and details use mobile panels
- Main interactions remain centered on globe object clicks, search, and layer toggles

### Common Issues

#### Earth Won't Open

Check whether the frontend is online:

```bash
./planet.sh health
./planet.sh log -f
```

If the frontend port is not `3000`, use the actual port shown at startup.

#### Layer Has No Data

Check the backend and data sources:

```bash
./planet.sh health
./planet.sh log -b
```

Then open the console and check:

- `/datasources`
- `/data`
- `/bgp`

#### Satellites, BGP, or Cables Load Slowly

These layers may depend on backend APIs, external data sources, or first-run collection tasks. Wait for startup tasks to finish before checking logs and console data source status.

## Console

Console entry point:

```text
http://localhost:3000/admin
```

The console requires login. Create a user first if this is your first time:

```bash
./planet.sh createuser
```

### Page Structure

The console uses React + Ant Design, with a left-side menu organized by work domain.

Common pages:

| Page | Route | Purpose |
| --- | --- | --- |
| Dashboard | `/admin` | System overview |
| Earth | `/earth` | Opens the public Earth page |
| Data Sources | `/datasources` | View data sources and trigger collection |
| Collected Data | `/data` | View collected data |
| BGP Observation | `/bgp` | BGP situational data |
| System Alerts | `/alerts/system` | System-level alerts |
| BGP Alerts | `/alerts/bgp` | BGP-related alerts |
| Situational Alerts | `/alerts/situational` | Situational assessment alerts |
| AI Playground | `/playground` | AI Provider debugging |
| System Logs | `/logs` | View system logs (typically super admin only) |
| Users | `/users` | User management |
| Settings | `/settings` | System config and TV live stream sources |

### Data Sources

`/datasources` shows collection sources and triggers collection. It is now a data source directory that lists built-in and custom sources in one table.

Common operations:

- View data source status
- Trigger collection
- View recent collection tasks
- Open the read-only detail drawer for endpoint, headers, runtime config, and built-in/custom source type

If a category of objects is missing on Earth, start here to confirm the data source is available.

The data source name opens an information drawer only. Endpoint, credentials, headers, and custom source configuration are maintained under `/settings` collector settings.

When collection tasks are running, the progress area shows a clickable `Collecting N` pill. Clicking it opens a modal with each running task's phase, progress, and processed count.

### Collected Data

`/data` shows the collected data table.

Useful for diagnosing:

- Whether data has entered the system
- Whether data update times match expectations
- Whether a data source produced valid records

### BGP Observation

`/bgp` is the BGP-focused page.

It complements the BGP layer on Earth:

- Earth emphasizes spatial posture and visual focus
- The console BGP page emphasizes lists, status, details, and assessment

### Alerts

Alert entry points:

- `/alerts/system`
- `/alerts/bgp`
- `/alerts/situational`

Used to view system, network, and situational alerts.

### System Settings

`/settings` manages system-level configuration.

Current common uses:

- System settings
- TV live stream source configuration
- Collector settings
- External integrations and AI Provider configuration

Available configuration depends on the current user's role.

#### Collector Settings

`/settings?tab=collector_credentials` is currently displayed as Collector Settings. It manages connection settings for all collectors, not only credentials.

Use it to:

1. Select a collector from the dropdown.
2. Review tags such as `Requires credentials`, module, enabled state, and `Unchecked` / `Available` / `Unavailable`.
3. Click the plug icon next to the selector to run a health check.
4. Edit endpoint, request headers, timeout, and retry settings.
5. Save the collector settings.

Free collectors are checked by requesting their endpoint directly. Credentialed collectors use their credential provider. If endpoint or credential fingerprint changes after the last successful validation, the collector must be checked again.

The system treats a collector as connected when the current configuration has either collected data successfully or passed the manual connection check.

#### BarentsWatch AIS Credentials

`BarentsWatch AIS` is a credentialed built-in collector. Its credential card appears above the basic configuration card.

Configured fields:

- `Client ID`
- `Client Secret`
- `Endpoint`

If a secret is already configured, the input shows a masked preview. Keeping that preview unchanged preserves the stored secret; entering a new value replaces it.

BarentsWatch AIS credentials can be read from:

1. Collector settings saved in the console.
2. Backend environment variables:
   - `BARENTSWATCH_CLIENT_ID`
   - `BARENTSWATCH_CLIENT_SECRET`
   - historical spellings: `BARRENTSWATCH_CLIENT_ID`, `BARRENTSWATCH_CLIENT_SECRET`
3. matching `export` lines in `~/.zshrc`.

If connection fails, the page opens the credential guide. The guide can be regenerated through AI Provider or reset to the default guide. The default guide points users to the official BarentsWatch tutorial and emphasizes selecting `AIS - API`, not the regular `BarentsWatch - API`.

### System Logs

`/logs` views system logs. If the menu item is not visible, the current user likely lacks the required role.

Common troubleshooting sequence:

```bash
./planet.sh health
./planet.sh log
```

Then open `/logs` for more structured runtime information.

## Docs

Documentation site:

```text
http://localhost:3000/docs
```

Docs content is read through backend APIs by permission. The frontend no longer bundles all Markdown files directly. Source files still live in:

```text
docs/technical/zh/   (Chinese)
docs/technical/en/   (English)
```

Anonymous visitors only see `public` docs such as the overview, quickstart, and manual. Logged-in users can see more technical docs when assigned Gatekeeper groups:

- `docs_user`: user-operation docs.
- `docs_developer`: Earth, frontend, backend, collector, and AI Provider development docs.
- `docs_admin`: service control, operations, environment variable, and sensitive-operation docs.

`admin` receives admin-doc access by default, and `super_admin` can read all Docs content. Gatekeeper groups are configured in the console Users page.

Docs supports:

- Category navigation
- Markdown rendering
- Tables and code blocks
- In-document table of contents
- Search across currently visible docs
- Internal links between technical documents

When adding a new technical document, check:

- Does it have a clear top-level heading
- Does it need to be added to backend Docs metadata for category and ordering
- Should it be classified as `public`, `docs_user`, `docs_developer`, or `docs_admin`

## Development Command Conventions

Frontend commands must use Bun:

```bash
cd frontend
bun install
bun run dev
bun run build
```

Do not use `npm run ...`. The project uses Bun in WSL / Windows mixed environments to avoid Node/npm path compatibility issues.

Verify the frontend build:

```bash
source ~/.zshrc && bun run build
```

## Troubleshooting Order

When something goes wrong, follow this sequence:

1. Check service status:

```bash
./planet.sh health
```

2. Check recent logs:

```bash
./planet.sh log
```

3. Check per-module logs:

```bash
./planet.sh log -f
./planet.sh log -b
./planet.sh log -a
```

4. Restart only the affected module:

```bash
./planet.sh restart -f
./planet.sh restart -b
./planet.sh restart -a
```

5. If database or cache is abnormal, restart the database:

```bash
./planet.sh restart -d
```

6. If still unrecovered, do a full restart:

```bash
./planet.sh restart
```

## Related Docs

- [Quickstart](/home/ray/dev/linkong/planet/docs/technical/en/quickstart.md)
- [Admin Frontend Context](/home/ray/dev/linkong/planet/docs/technical/en/frontend-admin-frontend-context.md)
- [Earth Frontend Context](/home/ray/dev/linkong/planet/docs/technical/en/earth-frontend-context.md)
- [Earth Layer Style Reference](/home/ray/dev/linkong/planet/docs/technical/en/earth-layer-style-reference.md)
- [Earth Location Candidate Collection User Guide](/home/ray/dev/linkong/planet/docs/technical/en/location-pipeline-user.md)
- [System Service Control](/home/ray/dev/linkong/planet/docs/technical/en/backend-system-service-control.md)
- [Backend Collectors](/home/ray/dev/linkong/planet/docs/technical/en/backend-collectors.md)