Network 层的迁移与强化已完成，TODO.md 与 MobaSyncMVP.md 给出后续方向

2026-03-27 22:14:33 +08:00
parent e361510100
commit 156d72bf4a
57 changed files with 2933 additions and 102 deletions
@@ -0,0 +1,14 @@
+## MODIFIED Requirements
+
+### Requirement: KCP is the sole reliable transport implementation
+The project SHALL expose `KcpTransport` as the only reliable `ITransport` implementation used by runtime networking paths. Reliable control-plane business messages, including login, logout, heartbeat, and other ordered session-management traffic, MUST continue to flow through KCP-backed sessions, while high-frequency `PlayerInput` and `PlayerState` synchronization MAY use a separate sync lane defined by the sync-strategy capability.
+
+#### Scenario: Runtime networking uses KCP for reliable control delivery
+- **WHEN** the application constructs the reliable transport used for login and session control traffic
+- **THEN** that transport instance is `KcpTransport`
+- **THEN** reliable control payloads are sent and received through KCP session state
+
+#### Scenario: High-frequency sync is allowed to bypass reliable ordered delivery
+- **WHEN** the runtime routes `PlayerInput` or `PlayerState` according to the high-frequency sync strategy
+- **THEN** those messages are not forced to use the reliable ordered KCP lane
+- **THEN** reliable KCP delivery remains available for control-plane traffic
@@ -0,0 +1,14 @@
+## MODIFIED Requirements
+
+### Requirement: Heartbeat is limited to liveness, RTT, and time sync
+The shared session lifecycle SHALL treat heartbeat traffic as infrastructure input for liveness detection and round-trip-time measurement only. Clock-synchronization samples MUST be forwarded to a separate sync-strategy component rather than being owned by `SessionManager`, and heartbeat processing MUST NOT itself own login success, login failure, or reconnect policy decisions.
+
+#### Scenario: Heartbeat updates liveness and RTT while forwarding clock samples
+- **WHEN** a heartbeat response is received for an active session
+- **THEN** the session manager updates last-seen or timeout bookkeeping and RTT data
+- **THEN** any server-tick sample is forwarded to the clock-sync strategy without making heartbeat the owner of login state
+
+#### Scenario: Missing heartbeat triggers timeout state
+- **WHEN** the configured heartbeat timeout elapses without a required heartbeat or other liveness signal
+- **THEN** the session lifecycle transitions the session into a timed-out state
+- **THEN** reconnect handling is delegated to the lifecycle reconnect policy rather than hidden inside the heartbeat handler itself
@@ -0,0 +1,53 @@
+# network-sync-strategy Specification
+
+## Purpose
+Define how client and server route high-frequency gameplay synchronization traffic, reject stale updates, reconcile authoritative state, and process clock-sync samples independently of session lifecycle.
+
+## ADDED Requirements
+
+### Requirement: Hosts assign delivery policies to synchronization message types
+The shared networking core SHALL allow hosts to map business message types to delivery policies. `PlayerInput` and `PlayerState` MUST be assignable to a high-frequency sync policy that is independent from the reliable ordered control policy used by login and lifecycle traffic.
+
+#### Scenario: High-frequency sync messages use a dedicated policy
+- **WHEN** the client or server sends `PlayerInput` or `PlayerState`
+- **THEN** the runtime resolves a high-frequency sync delivery policy for that message type
+- **THEN** the message is sent through the sync lane configured for that policy instead of defaulting to reliable ordered delivery
+
+#### Scenario: Control traffic keeps reliable delivery
+- **WHEN** the runtime sends login, logout, heartbeat, or other session-management messages
+- **THEN** the runtime resolves the reliable ordered control policy
+- **THEN** those messages continue to use the reliable transport path
+
+### Requirement: Sequenced sync receivers discard stale gameplay updates
+The high-frequency sync strategy SHALL tag gameplay synchronization messages with monotonic sequencing information and MUST discard stale `PlayerInput` or `PlayerState` updates that arrive older than the last accepted update for the same peer or entity stream.
+
+#### Scenario: Older player input is ignored
+- **WHEN** the server receives a `PlayerInput` update with a tick or sequence older than the latest accepted input for that player
+- **THEN** the server drops that stale input update
+- **THEN** the newer accepted input remains authoritative for simulation
+
+#### Scenario: Older player state does not rewind a client
+- **WHEN** the client receives a `PlayerState` update with a tick or sequence older than the latest applied authoritative state for that player
+- **THEN** the client ignores the stale state update
+- **THEN** visible movement continues from the newer authoritative state without rewinding to older data
+
+### Requirement: Authoritative correction prunes acknowledged prediction history
+The client sync strategy SHALL reconcile local prediction against authoritative player-state updates by pruning acknowledged inputs at or before the authoritative tick and only reapplying newer pending inputs.
+
+#### Scenario: Reconciliation removes already acknowledged inputs
+- **WHEN** the client accepts an authoritative `PlayerState` update for tick `N`
+- **THEN** locally buffered predicted inputs with tick less than or equal to `N` are removed from the replay buffer
+- **THEN** only inputs newer than `N` remain eligible for re-simulation
+
+### Requirement: Clock synchronization is a separate sync-policy concern
+The shared networking core SHALL process server-tick or clock-synchronization samples through a dedicated sync-policy component rather than storing clock-sync ownership inside `SessionManager`.
+
+#### Scenario: Heartbeat response contributes a clock sample without mutating lifecycle
+- **WHEN** a heartbeat or gameplay sync message carries a server-tick sample
+- **THEN** the runtime forwards that sample to the clock-sync strategy
+- **THEN** session lifecycle state remains unchanged except for liveness or RTT bookkeeping
+
+#### Scenario: Hosts can consume smoothed clock data for prediction
+- **WHEN** prediction or reconciliation code needs the current server-time estimate
+- **THEN** it reads that estimate from the clock-sync strategy or state object
+- **THEN** it does not query `SessionManager` for authoritative clock ownership
@@ -0,0 +1,14 @@
+## MODIFIED Requirements
+
+### Requirement: Shared core preserves current transport and message contracts
+The shared client/server foundation SHALL preserve the envelope-based business-message contract across client and server hosts while allowing delivery-policy selection behind the shared message-routing layer. Reliable control traffic MUST continue to use the existing `ITransport` contract, and high-frequency sync traffic MUST be composable through a host-agnostic sync strategy without introducing Unity-specific runtime types into the shared networking core.
+
+#### Scenario: Shared hosts exchange the same envelope format across delivery lanes
+- **WHEN** a client host sends a business message through either the reliable control path or the high-frequency sync path
+- **THEN** the payload is encoded with the same shared envelope and message-type contract
+- **THEN** the server host decodes and routes it through shared networking logic without a host-specific protocol fork
+
+#### Scenario: Hosts compose delivery-policy selection without Unity dependencies
+- **WHEN** a non-Unity server host constructs the runtime networking stack with reliable control traffic and a high-frequency sync lane
+- **THEN** it uses shared delivery-policy abstractions without depending on Unity frame-loop types
+- **THEN** the Unity client can use the same abstractions while still supplying its own host-specific dispatch behavior