# RCU Upgrade Backend Service Implementation Plan

This plan is based on the requirements in `project.md` and the development standards in `Promise.md`.

## Phase 1: Project Initialization & Specification (Spec-First)
**Goal**: Set up the environment and define specifications before coding.

1.  **Project Scaffolding**
    - Initialize Node.js project (v24.10.0 as per environment, satisfying v22+ requirement).
    - Configure `npm` as the package manager.
    - Create directory structure: `spec/`, `src/`, `tests/`, `scripts/`.
    - Install development dependencies: `@fission-ai/openspec`, `eslint` (or similar), testing framework (e.g., `jest` or `mocha`).
    - Create `README.md` with run/test/spec instructions.

2.  **OpenSpec Definition**
    - Create `spec/rcu-upgrade-flow.yaml` (using OpenAPI 3.1 or JSON Schema for non-API logical specification).
    - Define data structures:
        - `UpgradeConfig` (RoomType, HostList, FileNames).
        - `UpgradeLog` (DB Schema representation).
        - `APIResponse` schemas for external calls (`Upgrade_V2`, `QueryUpdateHostProgressBar`).
    - Define `npm` scripts: `npm run spec:lint`, `npm run spec:validate`.
    - **Checkpoint**: Pass `spec:validate`.

## Phase 2: Database & Configuration Design
**Goal**: Prepare data storage and configuration management.

3.  **Database Setup**
    - Design PostgreSQL schema for `test_upgrade` database.
    - Create SQL script for `upgrade_log` table with fields:
        - `start_time`, `roomtype_id`, `host_str`, `filename`, `status`, `end_time`, `file_type`, `config_version`, `firmware_version`, `uuid`.
    - **Clarification Needed**: Design a mechanism to track the "2 consecutive upgrades per version" state. (Will propose adding a `upgrade_state` table or using a local file if DB schema changes are restricted).

4.  **Configuration Module**
    - Implement `.env` parser.
    - Create a configuration loader to parse the complex JSON-like structure for `roomtype_id` arrays, `host_list_str` arrays, and `fileName` pairs.
    - Validate configuration against the Spec defined in Phase 1.

## Phase 3: Core Implementation
**Goal**: Implement business logic adhering to constraints.

5.  **External API Client**
    - Implement `UpgradeClient` to handle HTTP POST requests to `https://www.boonlive-rcu.com/api`.
    - Implement `Upgrade_V2` call.
    - Implement `QueryUpdateHostProgressBar` call.

6.  **Upgrade Logic Controller**
    - Implement the main workflow:
        1.  Determine current `fileName` based on rotation logic (2x A, 2x B).
        2.  Call `Upgrade_V2`.
        3.  Wait 45 seconds.
        4.  Poll `QueryUpdateHostProgressBar` (Interval: 30s, Timeout: 5m).
        5.  Process results and trigger DB logging.

7.  **Database Logger**
    - Implement `LoggerService` to write to `test_upgrade`.
    - Ensure UUID consistency between the initial call and the status result.
    - Implement the logic to only log the "Completed" status or final "Timeout/Fail" status as requested.

8.  **Scheduler**
    - Implement the 10-minute interval timer (configurable).
    - Ensure overlapping executions are handled or prevented (if applicable).

## Phase 4: Deployment & Quality Assurance
**Goal**: Prepare for production deployment on Windows Server.

9.  **PM2 Configuration**
    - Create `pm2.json` in the root directory.
    - Configure environment variables and log paths in PM2 config.

10. **Testing**
    - Implement unit tests in `tests/`.
    - Mock external API responses for success/failure/timeout scenarios.
    - **Checkpoint**: `npm run test` passes.

11. **Final Verification**
    - Verify against `Promise.md` checklist (Lint, Spec consistency, No extra features).
    - Verify against `project.md` functional requirements.

## Clarifications & Risks
The following points require attention or assumption confirmation:
1.  **State Persistence**: The requirement "each version needs to be upgraded 2 times consecutively, then switch" implies persistent state across the 10-minute intervals. *Assumption*: I will implement a lightweight persistence mechanism (e.g., a small JSON file or a dedicated DB table `upgrade_state`) to track the current version and iteration count, as `upgrade_log` is for historical logging only.
2.  **Concurrency**: If a single upgrade process takes > 10 minutes (e.g., 5 min timeout + retries), should the next scheduled job start? *Assumption*: Overlap is allowed, but we should handle it carefully.