98 lines
3.2 KiB
Markdown
98 lines
3.2 KiB
Markdown
# 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! 🎽
|