docs: Add project specs and existing feature documentation

2026-09-28 07:36:38 +08:00 · 2026-02-17 05:12:21 +00:00
parent a982c663d2
commit ba7e3c9893
11 changed files with 285 additions and 0 deletions
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-02-17
@@ -0,0 +1,29 @@
+## Context
+
+FLVX is a distributed system consisting of a central management panel (Backend + Frontend) and multiple forwarding agents (Nodes). The backend manages configuration, users, and billing, while agents handle the actual traffic forwarding using a modified GOST v3 stack. Communication between the panel and agents is secured and synchronized.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Document the high-level architecture of the system.
+- Describe the data model for users, tunnels, and nodes.
+- Explain the communication protocol between Panel and Agent.
+- Detail the authentication and authorization mechanisms.
+
+**Non-Goals:**
+- Refactoring the existing architecture.
+- Detailed code-level documentation of every function.
+- Changing the database schema.
+
+## Decisions
+
+- **Architecture**: The system follows a client-server model where the Panel acts as the server and Agents act as clients that pull configuration and push status.
+- **Data Model**: Core entities are Users, Nodes (Agents), Tunnels (Groups of rules), and Forwarding Rules.
+- **Communication**: Agents use a heartbeat mechanism to report status and fetch configuration updates. The protocol uses AES encryption with a pre-shared key (Node Secret).
+- **Authentication**: JWT for Frontend-Backend communication; API Key (Node Secret) for Agent-Backend communication.
+
+## Risks / Trade-offs
+
+- **Security**: The security of the agent communication relies heavily on the secrecy of the Node Secret.
+- **Scalability**: Centralized management might become a bottleneck with a very large number of agents.
+- **Complexity**: Synchronizing state across distributed agents introduces complexity in handling failures and inconsistencies.
@@ -0,0 +1,28 @@
+## Why
+
+The current system lacks formal specification documents describing its capabilities. This makes it difficult for new developers to understand the intended behavior and for existing developers to ensure consistency when adding new features. Documenting the existing functionality will serve as a baseline for future changes and help in identifying gaps or inconsistencies.
+
+## What Changes
+
+- Create formal specification documents for core system capabilities.
+- Document user management features (roles, limits).
+- Document tunnel and forwarding management (protocols, rules).
+- Document agent interactions and management.
+- Document system-level configurations.
+
+## Capabilities
+
+### New Capabilities
+- `user-management`: Authentication, user roles, and resource limits.
+- `tunnel-management`: Creation and management of traffic tunnels (TCP/UDP).
+- `forwarding-rules`: Configuration of port forwarding and tunnel forwarding rules, including rate limiting.
+- `agent-management`: Management of forwarding agents, including installation and configuration synchronization.
+- `system-config`: Global system settings and configurations.
+
+### Modified Capabilities
+<!-- None, as this is a documentation effort for existing features. -->
+
+## Impact
+
+- **Documentation**: New spec files in `openspec/specs/`.
+- **No Code Changes**: This change is purely documentation-focused.
@@ -0,0 +1,29 @@
+## ADDED Requirements
+
+### Requirement: Agent Registration
+The system SHALL require new agents (Nodes) to register using a unique node key/secret.
+
+#### Scenario: Node Connection
+- **WHEN** a new agent starts up with a valid configuration
+- **THEN** it connects to the backend and is registered as active.
+
+### Requirement: Heartbeat Monitoring
+The system SHALL monitor the status of all registered agents using periodic heartbeats.
+
+#### Scenario: Agent Status
+- **WHEN** an agent sends periodic heartbeats
+- **THEN** the system updates its last-seen timestamp and marks it as online.
+
+### Requirement: Configuration Sync
+The system MUST synchronize configuration changes (tunnels, rules) to agents securely and reliably.
+
+#### Scenario: Push Config
+- **WHEN** a configuration change is made in the panel
+- **THEN** the agent receives the updated configuration via the next heartbeat or push mechanism.
+
+### Requirement: Version Management
+The system SHOULD track the version of the agent software running on each node.
+
+#### Scenario: Version Reporting
+- **WHEN** an agent connects
+- **THEN** it reports its version number to the backend for tracking.
@@ -0,0 +1,22 @@
+## ADDED Requirements
+
+### Requirement: Port Forwarding Rules
+The system SHALL support configuring port forwarding rules, defining the listening port on the node and the destination IP/port.
+
+#### Scenario: Rule Configuration
+- **WHEN** an admin creates a port forwarding rule
+- **THEN** the rule is stored and synchronized to the assigned node.
+
+### Requirement: Rate Limiting
+The system SHALL support configuring bandwidth rate limits for tunnels and users.
+
+#### Scenario: Bandwidth Restriction
+- **WHEN** a rate limit is applied to a user
+- **THEN** their total bandwidth usage does not exceed the specified limit across all their tunnels.
+
+### Requirement: Traffic Accounting
+The system MUST track incoming and outgoing traffic volume for each tunnel and user for billing and quota enforcement.
+
+#### Scenario: Traffic Calculation
+- **WHEN** traffic flows through a tunnel
+- **THEN** the system increments the user's traffic usage counter accurately.
@@ -0,0 +1,22 @@
+## ADDED Requirements
+
+### Requirement: Site Settings
+The system SHALL allow customization of the site title, logo, and other branding elements.
+
+#### Scenario: Update Branding
+- **WHEN** an administrator changes the site logo
+- **THEN** the new logo is displayed across the interface.
+
+### Requirement: Notification Settings
+The system SHALL support configuring notifications for user registration, traffic limits, and other events.
+
+#### Scenario: User Limit Alert
+- **WHEN** a user approaches their traffic quota
+- **THEN** a notification is sent to the user/admin.
+
+### Requirement: Backup & Restore
+The system SHOULD provide a mechanism to backup and restore database configurations.
+
+#### Scenario: Restore Database
+- **WHEN** initiating a restore operation
+- **THEN** the system accepts a valid backup file and overwrites the current database state.
@@ -0,0 +1,22 @@
+## ADDED Requirements
+
+### Requirement: Tunnel Creation
+The system SHALL allow administrators to create tunnels, specifying protocols (TCP, UDP), listening ports, and destination endpoints.
+
+#### Scenario: Create TCP Tunnel
+- **WHEN** an admin creates a new TCP tunnel configuration
+- **THEN** the backend stores the tunnel definition and assigns it to a node.
+
+### Requirement: Tunnel Forwarding Configuration
+The system SHALL support both standard port forwarding (listening on a port and forwarding to a destination) and tunnel forwarding modes.
+
+#### Scenario: Configure Port Forwarding
+- **WHEN** configuring a tunnel for port forwarding
+- **THEN** traffic arriving at the specified port is forwarded to the destination IP:port.
+
+### Requirement: Tunnel Assignment
+The system SHALL allow tunnels to be assigned to specific users, tracking their usage against the user's quota.
+
+#### Scenario: User Tunnel Usage
+- **WHEN** a user is assigned a tunnel
+- **THEN** traffic passing through that tunnel is accounted for under the user's usage.
@@ -0,0 +1,29 @@
+## ADDED Requirements
+
+### Requirement: User Registration
+The system SHALL allow new users to register an account with a username and password.
+
+#### Scenario: Successful Registration
+- **WHEN** a user submits valid registration details
+- **THEN** a new user account is created and the user can log in.
+
+### Requirement: User Authentication
+The system MUST authenticate users using JWT tokens. The `Authorization` header MUST contain the raw token without a `Bearer` prefix.
+
+#### Scenario: Valid Login
+- **WHEN** a user provides correct credentials
+- **THEN** the system returns a valid JWT token.
+
+### Requirement: Role Management
+The system SHALL support different user roles, specifically Administrator and Regular User, with distinct permissions.
+
+#### Scenario: Admin Access
+- **WHEN** an administrator logs in
+- **THEN** they have access to system-wide settings and all user management functions.
+
+### Requirement: Resource Quotas
+The system SHALL allow administrators to set traffic limits and connection limits for individual users.
+
+#### Scenario: Traffic Limit Enforcement
+- **WHEN** a user exceeds their traffic quota
+- **THEN** the system prevents further traffic forwarding for that user.
@@ -0,0 +1,30 @@
+## 1. User Management Verification
+
+- [ ] 1.1 Verify User Registration logic in backend
+- [ ] 1.2 Verify JWT Authentication implementation
+- [ ] 1.3 Verify Role Management checks
+- [ ] 1.4 Verify Quota Enforcement logic
+
+## 2. Tunnel Management Verification
+
+- [ ] 2.1 Verify Tunnel Creation API
+- [ ] 2.2 Verify Forwarding Configuration parsing
+- [ ] 2.3 Verify Tunnel Assignment logic
+
+## 3. Forwarding Rules Verification
+
+- [ ] 3.1 Verify Port Forwarding rule processing
+- [ ] 3.2 Verify Rate Limiting implementation (token bucket/leaky bucket?)
+- [ ] 3.3 Verify Traffic Accounting mechanisms
+
+## 4. Agent Management Verification
+
+- [ ] 4.1 Verify Agent Registration handshake
+- [ ] 4.2 Verify Heartbeat processing
+- [ ] 4.3 Verify Config Sync protocol
+
+## 5. System Config Verification
+
+- [ ] 5.1 Verify Site Settings API
+- [ ] 5.2 Verify Notification triggers
+- [ ] 5.3 Verify Backup/Restore functionality
@@ -0,0 +1,20 @@
+schema: spec-driven
+
+# Project context (optional)
+# This is shown to AI when creating artifacts.
+# Add your tech stack, conventions, style guides, domain knowledge, etc.
+# Example:
+#   context: |
+#     Tech stack: TypeScript, React, Node.js
+#     We use conventional commits
+#     Domain: e-commerce platform
+
+# Per-artifact rules (optional)
+# Add custom rules for specific artifacts.
+# Example:
+#   rules:
+#     proposal:
+#       - Keep proposals under 500 words
+#       - Always include a "Non-goals" section
+#     tasks:
+#       - Break tasks into chunks of max 2 hours
@@ -0,0 +1,52 @@
+# Project Overview
+
+**Name**: FLVX (Flux Panel)
+**Description**: Traffic forwarding management system built on a forked GOST v3 stack. It provides a web-based panel for managing traffic tunnels, users, and forwarding rules.
+**Repository**: Monorepo containing Admin API, Web UI, and Forwarding Agent.
+
+## Tech Stack
+
+### Backend (`go-backend/`)
+- **Language**: Go
+- **Database**: SQLite (default), PostgreSQL (supported)
+- **Framework**: Standard library `net/http` (no heavy framework)
+- **ORM**: None (Raw SQL via `database/sql`)
+
+### Frontend (`vite-frontend/`)
+- **Framework**: React
+- **Build Tool**: Vite (using `rolldown-vite` experimental bundler)
+- **UI Library**: HeroUI
+- **Styling**: Tailwind CSS
+- **Mode**: Hybrid (Desktop + Mobile WebView support)
+
+### Agent (`go-gost/`)
+- **Language**: Go
+- **Base**: Fork of `gost` v3
+- **Extensions**: Custom extensions in `go-gost/x/`
+
+### Infrastructure
+- **Containerization**: Docker, Docker Compose (v4/v6)
+- **CI/CD**: GitHub Actions
+- **Installers**: Shell scripts (`panel_install.sh`, `install.sh`)
+
+## Architecture
+
+- **Panel**: Central management server (Go Backend + React Frontend).
+- **Agent**: Forwarding node running on remote servers.
+- **Communication**:
+    - Frontend -> Backend: REST API (JWT Auth, raw token in header).
+    - Agent -> Backend: AES-encrypted heartbeat/config sync.
+
+## Conventions
+
+- **Authentication**: `Authorization` header expects raw JWT token (do NOT add `Bearer ` prefix).
+- **API Response**: Standard envelope `{code, msg, data, ts}` (code 0 = success).
+- **Database**: Backend uses raw SQL queries. Do not introduce an ORM.
+- **File Structure**: Flat monorepo with language-prefixed directories (`go-backend`, `go-gost`).
+- **Protobuf**: Do not edit generated `.pb.go` files manually.
+
+## Development
+
+- **Backend Build**: `cd go-backend && make build`
+- **Frontend Dev**: `cd vite-frontend && npm run dev`
+- **Agent Run**: `cd go-gost && go run .`