# webpop

**Repository Path**: validate/webpop

## Basic Information

- **Project Name**: webpop
- **Description**: webPOP Remote Web Control 
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: https://www.webpop.cn
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2015-01-26
- **Last Updated**: 2026-07-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# webpop

Android TV 14 fullscreen web playback terminal system.

`webpop` is organized as a monorepo matching the latest executable plan:

- `apps/android-tv-agent`: Android TV APK skeleton.
- `apps/h5-user`: mobile H5 user control client.
- `apps/admin-web`: LayUI-style admin web skeleton.
- `apps/control-server`: Control Server prototype with REST and event model stubs.
- `workers/browser-worker`: Browser Worker prototype.
- `packages/shared-types`: shared DTOs, enums, command actions, and protocol types.
- `infra`: local deployment notes and docker-compose placeholder.
- `docs`: implementation notes copied from the plan into engineering checklists.

## Project Name

The product and project name is `webpop`. Package names, app titles, npm package names, and documentation should use `webpop` going forward.

## Quick Start

### Git + Docker Compose 安装

服务器只需要 Git、Docker Engine 和 Docker Compose v2，不需要安装 Node.js：

```bash
git clone https://gitee.com/validate/webpop.git
cd webpop
cp .env.production.example .env.production
```

修改 `.env.production` 中的数据库密码、三个服务令牌、对象签名密钥和服务器公开地址，然后执行：

```bash
docker compose --env-file .env.production up -d --build
```

查看状态：

```bash
docker compose --env-file .env.production ps
curl http://127.0.0.1:8081/ready
```

更新版本：

```bash
git pull
docker compose --env-file .env.production up -d --build
```

正式部署说明见 [Docker生产部署方案](docs/Docker生产部署方案.md)。

只下载 Compose 文件在线安装：

```bash
mkdir webpop && cd webpop
curl -L -o docker-compose.yml https://gitee.com/validate/webpop/raw/master/docker-compose.yml
curl -L -o .env.production https://gitee.com/validate/webpop/raw/master/.env.production.example
vi .env.production
docker compose --env-file .env.production up -d --build
```

该方式由 Docker BuildKit 直接从 Gitee 拉取源码，不需要本地 Git 仓库。

在 Docker 管理面板中可直接导入根目录 `docker-compose.yml`。Compose 已提供启动默认值；正式公网使用时请通过面板环境变量覆盖所有带 `change-me` 或 `change-this-secret` 的默认配置。

The initial server uses Node built-in modules so it can run before dependency installation:

```bash
cd webpop
npm run dev:server
```

Then open:

- API health: `http://localhost:8080/health`
- API readiness: `http://localhost:8080/ready`
- API metrics: `http://localhost:8080/metrics`
- H5 static prototype: `apps/h5-user/src/index.html`
- Admin static prototype: `apps/admin-web/src/index.html`

Start the server-side services through Docker Compose:

```bash
npm run services:up
npm run services:status
```

If Docker Hub image pulls are slow or blocked, the same command falls back to a local Node Control Server. You can also force the local mode:

```bash
npm run services:local-up
```

Stop them when needed:

```bash
npm run services:down
```

Runtime state is persisted to `.data/control-state.json` by default. Override it when needed:

```bash
WEBPOP_DATA_FILE=/tmp/webpop-state.json npm run dev:server
```

Storage provider selection:

```bash
WEBPOP_STATE_STORE=json npm run dev:server

WEBPOP_STATE_STORE=postgres \
WEBPOP_DATABASE_URL=postgres://user:pass@localhost:5432/webpop \
WEBPOP_POSTGRES_READ_MODEL=bridge \
WEBPOP_POSTGRES_REQUEST_READS=state \
npm run dev:server
```

The PostgreSQL provider uses the optional `pg` package, writes per-table rows, and keeps a `webpop_state_snapshots` bridge row. `WEBPOP_POSTGRES_READ_MODEL` supports `bridge`, `auto`, and `tables`; use `auto` after consistency checks pass, then `tables` only after table-read verification is explicitly approved. `WEBPOP_POSTGRES_REQUEST_READS=state|tables` controls selected request-level reads for device lists/details, group lists/details, command lists/details/events, batch detail summaries, screenshot/audit evidence lists, URL templates/policies, security governance lists/context, app version/update job reads, and Admin dashboard/operations reports.

Local object uploads for screenshots and APK packages are stored under `.data/objects` by default. Override the directory or public URL base when running behind a proxy:

```bash
WEBPOP_OBJECT_STORE_DIR=/tmp/webpop-objects \
WEBPOP_PUBLIC_BASE_URL=http://localhost:8080 \
npm run dev:server
```

Optional auth can be enabled for H5/Admin/TV protected APIs:

```bash
WEBPOP_AUTH_REQUIRED=true \
WEBPOP_H5_TOKEN=dev-h5-token \
WEBPOP_ADMIN_TOKEN=dev-admin-token \
WEBPOP_TV_TOKEN=dev-tv-token \
npm run dev:server
```

For static H5/Admin debugging with auth enabled, use the built-in login buttons. The scaffold logs in with `user_h5_dev` or `user_admin_dev`, stores access/refresh tokens in localStorage, refreshes expired access tokens through `/api/auth/refresh`, and logs out through `/api/auth/logout`.

## Verification

Run all local verification gates:

```bash
npm run check:all
```

Run the lightweight syntax check:

```bash
npm run check
```

Run the Admin LayUI static check:

```bash
npm run check:admin
```

Run the Android TV Agent static check:

```bash
npm run check:android
```

Run the Android build configuration check:

```bash
npm run check:android-build
```

Run a real Android TV Agent debug APK build on a machine with JDK 17 and Android SDK platform 35:

```bash
npm run compile:android
```

Install the generated debug APK to a connected Android TV / adb device:

```bash
npm run install:android
```

Install the local Android TV emulator image, create the `webpop_tv_api34` AVD, boot it, install the APK, and request app launch:

```bash
npm run android:emulator:setup
npm run android:test:apk
```

Run the storage boundary and migration check:

```bash
npm run check:storage
```

Run the environment configuration self-test:

```bash
npm run check:env
```

Validate a production environment before release:

```bash
WEBPOP_ENV=production \
WEBPOP_AUTH_REQUIRED=true \
WEBPOP_STATE_STORE=postgres \
WEBPOP_DATABASE_URL=postgres://user:pass@host:5432/webpop \
WEBPOP_POSTGRES_READ_MODEL=auto \
WEBPOP_POSTGRES_REQUEST_READS=state \
WEBPOP_OBJECT_SIGNING_SECRET=replace-with-long-random-secret \
WEBPOP_H5_TOKEN=replace-h5-token \
WEBPOP_ADMIN_TOKEN=replace-admin-token \
WEBPOP_TV_TOKEN=replace-tv-token \
WEBPOP_PUBLIC_BASE_URL=https://api.example.com \
node scripts/env-check.js
```

Run the production release gate after a verified backup exists:

```bash
WEBPOP_RELEASE_MODE=production \
WEBPOP_RELEASE_BACKUP_FILE=.data/backups/control-state.backup.json \
WEBPOP_RELEASE_REPORT_FILE=.data/release/release-gate-report.json \
WEBPOP_RELEASE_BASE_URL=https://api.example.com \
WEBPOP_ENV=production \
WEBPOP_AUTH_REQUIRED=true \
WEBPOP_STATE_STORE=postgres \
WEBPOP_DATABASE_URL=postgres://user:pass@host:5432/webpop \
WEBPOP_POSTGRES_READ_MODEL=auto \
WEBPOP_POSTGRES_REQUEST_READS=state \
WEBPOP_OBJECT_SIGNING_SECRET=replace-with-long-random-secret \
WEBPOP_H5_TOKEN=replace-h5-token \
WEBPOP_ADMIN_TOKEN=replace-admin-token \
WEBPOP_TV_TOKEN=replace-tv-token \
WEBPOP_PUBLIC_BASE_URL=https://api.example.com \
npm run release:gate
```

Validate an archived release report:

```bash
node scripts/release-report-check.js .data/release/release-gate-report.json
```

Run the PostgreSQL schema check:

```bash
npm run check:db-schema
```

Run the JSON to PostgreSQL migration exporter check:

```bash
npm run check:db-migration
```

Run a local JSON to PostgreSQL migration dry-run:

```bash
npm run migrate:postgres
```

Run the GitHub Actions workflow shape check:

```bash
npm run check:ci
```

Run the main-chain smoke test on an isolated port:

```bash
npm run smoke
```

Run the auth gate check:

```bash
npm run test:auth
```

Run the REST API contract check:

```bash
npm run test:api-contract
```

The smoke test covers:

1. TV device registration.
2. QR ticket creation.
3. H5 scanned + approve.
4. TV exchange.
5. TV WebSocket simulator connection.
6. H5 `page.open` command creation.
7. WSS command delivery to TV simulator.
8. TV simulator `ack -> page.started -> page.loading -> result success`.
9. TV simulator `page.screenshot` event.
10. Admin screenshot query and command event query.
11. H5 group creation.
12. Group `page.open` batch dispatch and Admin batch summary.
13. Offline command timeout scanning.
14. Batch retry creation for timeout commands.

Run the TV simulator manually against a running server:

```bash
PORT=8080 DEVICE_ID=tv_demo01 npm run dev:tv-sim
```

## Current Scope

This is the first development scaffold. It freezes the initial architecture, shared types, command model, API shape, and app directories so feature work can continue module by module.

Implemented in the scaffold:

- REST device registration, QR binding, exchange, H5 devices, URL policy test, commands, Admin devices, Admin dashboard, audit logs.
- Lightweight WSS Gateway for TV command delivery.
- Command event timeline.
- In-memory screenshot index and screenshot query APIs.
- Device group APIs for H5/Admin.
- Batch open-url dispatch, batch status summary, and grouped command fan-out.
- H5 prototype for single-device commands, screenshot queries, group creation, and group dispatch.
- Admin prototype for dashboard metrics, device/group/command/screenshot tables, online-device batch dispatch, and group dispatch.
- LayUI-style Admin shell with module tabs for dashboard, devices, groups, commands, screenshots, and audit logs.
- Android TV Agent Java skeleton with device registration, QR binding polling, WSS command handling, WebView execution, screenshot completion reporting, settings screen, diagnostics panel, reconnect backoff, boot receiver, foreground service, and lock-task hook.
- Android TV Agent build configuration for debug/release variants, release signing through environment variables, ProGuard rules, and build documentation.
- JSON-file persistence for local runtime state.
- Optional token auth gate for protected H5/Admin/TV APIs.
- User login sessions for H5/Admin with access token, refresh token, current user, logout, persisted session storage, and role isolation.
- Command timeout scanner with configurable timeout and scan interval.
- H5/Admin single-command retry APIs.
- Admin batch retry API for failed, timeout, and cancelled commands.
- API contract test for URL policy rejection, group membership, batch fan-out, timeout, command retry, batch retry, and persistence metadata.
- Control Server storage boundary with `JsonStateStore` and database migration design.
- Storage provider factory with default JSON store and optional PostgreSQL snapshot-backed provider.
- PostgreSQL schema in `infra/postgres/schema.sql`, local Postgres service in `infra/docker-compose.yml`, and schema consistency check.
- JSON snapshot to PostgreSQL SQL exporter with migration report, post-import verification SQL, and coverage check.
- PostgreSQL migration runner with JSON backup, dry-run, optional `psql` apply, and verification execution.
- GitHub Actions CI workflow for server, API, auth, smoke, Admin, storage, Android static checks, and required Gradle debug APK build through `apps/android-tv-agent/gradlew`.
- Local `check:all` orchestration for the full verification gate.
- Default tenant, organization, user role context, scoped resources, scoped Admin/H5 reads, and scoped audit logs.
- Admin tenant/organization module for viewing current security context, tenants, organizations, and users.
- Admin security management actions for creating, editing, and disabling tenants, organizations, and users with organization-scope permission checks.
- Admin URL operations module for URL templates, template edit/version history, URL policies, policy tests, advanced domain/path/regex matching, and template/policy disable actions.
- Server-side URL template variable rendering, template target authorization checks, and H5 template-based command creation.
- Admin app version management, APK release metadata, signed object upload/download URLs, published-version dispatch, rollback dispatch, update job tracking, and Android `device.update` download/checksum/install-intent plus Device Owner PackageInstaller handling.
- Local object-store adapter for screenshot and APK package upload URLs, backed by `.data/objects` with HMAC signed `PUT /objects/upload/{token}` and `GET /objects/read/{token}` links.
- Admin web uses vendored LayUI-compatible local assets instead of CDN dependencies for offline deployment.

Useful runtime knobs:

```bash
WEBPOP_COMMAND_TIMEOUT_MS=120000
WEBPOP_COMMAND_SCAN_INTERVAL_MS=5000
```