83 lines
4.4 KiB
Markdown
83 lines
4.4 KiB
Markdown
|
# 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.
|