# Training Event Simulator

Command line utility for pushing mock `training_stream_events` data into Supabase. Use it to drive the 体育课训练 dashboard with realistic telemetry while the real gateway is offline.

## Features

- Generates ACK + telemetry + summary events aligned with the new `training_stream_events` table.
- Supports JSON/CSV roster files or inline `student_id:device_id` lists.
- Adjustable intervals, cycle counts, ingest labels, and dry-run mode.
- Works with Supabase service-role or any key that passes RLS inserts.

## Prerequisites

- Node.js 18+
- An `.env` file containing:
  ```env
  SUPABASE_URL=https://your-project.supabase.co
  SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
  ```
  > The service-role key is recommended so that inserts bypass RLS issues in test environments.

- The `training_stream_events` table and RLS policies provisioned (see `create_training_stream_events.sql`).

## Install

```powershell
cd scripts/training-event-simulator
npm install
```

This generates a local `package-lock.json` and installs `@supabase/supabase-js` plus `dotenv`.

## Roster input formats

### JSON array

```json
[
  { "student_id": "d8f0f3b9-...", "device_id": "6f9f64f5-...", "name": "张三" },
  { "student_id": "9da97787-...", "device_id": "350f86fb-...", "name": "李四" }
]
```

### CSV / line-based (`student_id,device_id,name`)

```
d8f0f3b9-...,6f9f64f5-...,张三
9da97787-...,350f86fb-...,李四
```

### Inline CLI list (`student_id:device_id`)

```
node simulate-training-events.mjs --class-id 9c5d... --students d8f0f3b9-...:6f9f64f5-...,9da97787-...:350f86fb-...
```

## Usage

```powershell
node simulate-training-events.mjs --class-id 9c5d5e1d-... --roster ./roster.json --interval 5 --cycles 12
```

Key options:

- `--class-id <uuid>`: required class identifier.
- `--training-id <uuid>`: override the generated training session ID.
- `--roster <path>`: JSON/CSV roster file (required unless `--students` is used).
- `--students stu:dev,...`: inline roster string.
- `--interval <seconds>`: seconds between telemetry batches (default 5).
- `--cycles <n>`: number of telemetry batches (default 12).
- `--no-ack`: skip the initial ACK events.
- `--dry-run`: log payloads without inserting.
- `--source <label>` / `--note <text>`: annotate `ingest_source` & `ingest_note`.
- `--env <path>`: custom `.env` file.
- `--supabase-url` / `--supabase-key`: override env variables.

To install the utility globally (optional):

```powershell
npm install --global .
simulate-training-events --class-id ... --roster ...
```

## Typical workflow

1. Ensure the Supabase table & policies are deployed.
2. Prepare a roster JSON from your test dataset.
3. Run the simulator with the class ID & training ID you want to monitor.
4. Open the 体育课训练页面 (teacher dashboard) and subscribe to the generated training ID.

## Troubleshooting

- **RLS failures**: verify the key has insert rights. Service-role should always work.
- **Foreign key errors**: confirm `student_id`, `device_id`, and `class_id` exist in `ak_users`, `ak_devices`, and `ak_classes` respectively.
- **ETIMEDOUT / network**: check outbound access to `SUPABASE_URL` from your environment.

Happy simulating! 🎽