Files

XuJiacheng d04205ddba feat: 实现RCU固件升级服务核心功能

- 添加升级服务主逻辑，包括定时触发升级、状态查询和日志记录
- 实现数据库初始化脚本和日志表结构
- 添加PM2部署配置文件
- 实现环境变量配置系统
- 添加API客户端模块处理外部接口调用
- 实现升级状态轮询和超时处理机制
- 添加测试用例验证核心功能

2026-01-21 13:34:42 +08:00

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.

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.
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.

Goal: Prepare data storage and configuration management.

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).
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.

Goal: Implement business logic adhering to constraints.

External API Client
- Implement UpgradeClient to handle HTTP POST requests to https://www.boonlive-rcu.com/api.
- Implement Upgrade_V2 call.
- Implement QueryUpdateHostProgressBar call.
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.
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.
Scheduler
- Implement the 10-minute interval timer (configurable).
- Ensure overlapping executions are handled or prevented (if applicable).

Goal: Prepare for production deployment on Windows Server.

PM2 Configuration
- Create pm2.json in the root directory.
- Configure environment variables and log paths in PM2 config.
Testing
- Implement unit tests in tests/.
- Mock external API responses for success/failure/timeout scenarios.
- Checkpoint: npm run test passes.
Final Verification
- Verify against Promise.md checklist (Lint, Spec consistency, No extra features).
- Verify against project.md functional requirements.

The following points require attention or assumption confirmation:

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.
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.