# Live Data Collector Plugin

Data-only live-room collector plugin for field validation.

This package extracts the collection part of Live Rush without gameplay:

- TikTok Webcast gift events
- public chat and lightweight P1 evidence
- member, follow, share, like, room metric, and system live facts when exposed by the upstream bridge
- primary route collection plus an independently provable backup route; a
  same-entry dual instance is treated only as hot connection redundancy
- MCA or guild backend CSV/JSON comparison reports
- local NDJSON raw backups and normalized fact logs
- manifests, replay summaries, and health gates for comparison with MCA or guild backend exports
- realtime operator feedback for standby, connection health, data freshness, route gap risk, and recent gifts

It must not import gameplay runtime modules or mutate live score. Use it for
shadow collection and reconciliation before enabling customer-facing formal
scoring.

## Field Installer

Build the Windows field installer from the repository root:

```text
npm run build:live-data-collector-installer
```

The installer starts a local sidecar UI at:

```text
http://127.0.0.1:18766
```

The collector runs beside TikTok Live Studio. Live Studio pushes the stream; this
tool listens to the same live room through managed TikTok Webcast URLs or signer
URLs and writes local evidence for comparison.

For guild operators, the Windows launcher hides the technical process in the
system tray. Operators only need to fill the TikTok live room link, room id, or
creator handle. Primary/backup collection channels can be preloaded by the
technical team, or entered from the collapsed advanced section when needed. The
control panel browser page can be closed; the tray process keeps running. The
automatically opened TikTok backup live page is different: it is the independent
local browser observer route, can be minimized, and should not be closed. If it
is closed, the collector relaunches it and records the backup-route gap window.
After the first successful start, the sidecar stores the last creator/link and
can auto-enter standby on the next launch. In normal guild use the operator
only clicks "开始驻守"; route setup, reconnect, raw backups, and gap warnings are
handled behind the simplified control panel. With a creator handle or live URL,
the default route pair is a programmatic TikTok Webcast/SDK primary route plus a
local real-browser backup route, so the two realtime ledgers are produced by
different capture techniques on the operator's machine.
If the control panel does not open, the Start menu entry now tries to start the
local service before opening the browser. Startup diagnostics are written to
`%LOCALAPPDATA%\LiveRushDataCollector\logs\launcher.log` and service diagnostics
to `%LOCALAPPDATA%\LiveRushDataCollector\logs\service.log`. If the desktop
shortcut appears to do nothing, run `Live Rush -> 诊断启动直播数据采集` from the
Start menu to see the startup error in a visible console.

## Realtime Field Feedback

The sidecar UI now shows plain-language live status instead of only raw JSON:

- `开播保障`: whether pre-live standby is active, when live was detected, and how
  long it took to receive the first event.
- `线路状态`: primary and backup health, reconnect count, last signal age, and
  whether the route is only waiting for the creator to go live.
- `实时礼物流`: recent gift rows with route, sender, count, value, and event time.
- `缺口风险`: primary/backup mismatch, stale live signal, route errors, or raw
  evidence blockers that require after-live reconciliation.

This feedback is advisory for operators. Formal settlement still comes from the
local line-item ledger plus after-live official/guild reconciliation; MCA remains
test-period comparison only. TikTok combo gift interim rows are retained as raw
evidence, while finalized combo rows drive settlement totals when present.

Formal backup means independent statistics and independent accounting evidence:
the backup must use a distinct managed route, signer/bridge, host, node, or
other provable failure domain. Running the same TikTok auto connector twice can
improve reconnect stability, but it is not accepted as disaster recovery and is
blocked from production settlement readiness.
