docs: Add project specs and existing feature documentation

2026-10-03 09:06:36 +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,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.