# Copilot Instructions

This repository is a BI and LiveOps system for a coloring game. Optimize for data correctness, operational safety, and low-risk incremental changes.

## Core Priorities

- Prefer small, reversible changes over broad rewrites.
- Preserve production behavior unless a task explicitly requires behavior changes.
- Treat analytics ingestion, cron jobs, ClickHouse schema, MongoDB aggregation, and PM2 cutover scripts as high-risk areas.
- Fix the narrowest correct slice first.
- Do not refactor unrelated code while touching critical data paths.

## Repository Guidance

- `oms/` contains the Node.js + TypeScript backend, services, cron jobs, scripts, and admin APIs.
- `omsapp/` contains the Angular admin dashboard source.
- `oms/services/event-api-service.ts` receives analytics events and publishes to RabbitMQ.
- `oms/services/log-service.ts` writes raw logs to rotating files.
- `oms/services/ingestor-service.ts` consumes analytics events and writes to ClickHouse and MongoDB.
- `oms/services/cron-jobs/done-rate.ts` is a known hotspot.
- `oms/public/app/` contains built frontend assets. Prefer editing `omsapp/src/` instead of generated files.

## Analytics and Data Rules

- Prefer query-shape optimization before changing analytics semantics.
- For ClickHouse changes, consider partition pruning, scanned time range, aggregation fanout, and whether multiple scans can be merged into one.
- Use half-open time ranges: `[start, nextStart)`.
- Add execution timing and result-size logs for long-running queries or cron jobs when useful.
- The `events` table is partitioned monthly by `toYYYYMM(time)`. Preserve partition-aware query patterns.
- `oms/services/ingestor-service.ts` currently accepts a small amount of analytics loss as a tradeoff. Do not change ack semantics unless the task explicitly targets ingestion reliability.

## Operational Script Rules

- Default scripts to safe behavior.
- Prefer dry-run by default for destructive, migration, or cutover operations.
- Print exact SQL or command plans before executing cutovers.
- Prefer idempotent reconciliation logic keyed by stable identifiers such as `log_id`.
- Prefer Dockerized database tooling when available. In this repo, use `docker exec ... clickhouse-client ...` rather than assuming `clickhouse-client` exists on the host.
- Be careful not to restart unrelated PM2 services during operational changes.

## Validation Expectations

Prefer the narrowest useful validation in this order:

1. File-level syntax or type validation
2. Targeted script execution or query validation
3. Focused runtime validation of the changed service or cron job
4. Broader build only if needed

For database or migration work:

1. Validate counts before and after
2. Validate per-month or per-partition distribution when relevant
3. Keep an explicit rollback path

## Tracking

- Use `oms/OPTIMIZATION_TRACKER.md` as the source of truth for completed and pending optimization items.
- When finishing a meaningful optimization, update that tracker.

## When Unsure

- Choose the safer operational path.
- Prefer observability over speculation.
- Add logs and narrow validation before making a larger follow-up change.