Initial commit of akmon project

scripts/training-event-simulator/README.md

@@ -0,0 +1,97 @@
+# 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! 🎽