feat: 完整游戏运维功能

2026-07-18 09:04:01 +08:00
parent f3b14b7945
commit 48b8ad8d6c
187 changed files with 16607 additions and 1140 deletions
@@ -0,0 +1,61 @@
+## ADDED Requirements
+
+### Requirement: Durable logs recover after restart
+
+The system SHALL persist accepted log batches, acknowledged sequence state, retention metadata, and bounded query indexes so a Platform restart does not duplicate or lose acknowledged ranges.
+
+#### Scenario: Restart preserves log cursor
+
+- **WHEN** a batch is acknowledged, Platform restarts, and a caller queries after a cursor
+- **THEN** the ordered entries and latest acknowledged sequence MUST be available from the persisted store
+
+#### Scenario: Retry remains idempotent
+
+- **WHEN** Run retries an acknowledged batch with the same stream, range, and checksum
+- **THEN** Platform MUST return an idempotent acknowledgement without duplicating entries
+
+### Requirement: Run log spool is restart-safe
+
+The Run log spool SHALL atomically persist unacknowledged batches, tolerate a process restart, and remove a batch only when an acknowledgement covers its full stream range.
+
+#### Scenario: Interrupted enqueue
+
+- **WHEN** a process restarts after an incomplete temporary spool write
+- **THEN** the next spool load MUST ignore temporary files and retain every committed unacknowledged batch
+
+### Requirement: Durable artifacts recover with checksum and chunk bounds
+
+The system SHALL persist artifact metadata, transfer manifests, received chunk indexes, chunk checksums, final checksums, and bounded content so uploads can resume after restart.
+
+#### Scenario: Resume missing chunk
+
+- **WHEN** a transfer has received some chunks and Platform restarts
+- **THEN** status MUST return the same received indexes and next missing index without exposing storage paths
+
+#### Scenario: Checksum conflict is rejected
+
+- **WHEN** a retry uses a different payload or checksum for an already received chunk
+- **THEN** Platform MUST reject it and leave the original chunk and transfer state unchanged
+
+### Requirement: Metrics and backups are durable and bounded
+
+The system SHALL persist metric samples and backup records, apply explicit age/count/byte retention, support recovery status, and expose only owner-authorized safe projections.
+
+#### Scenario: Retention prunes oldest records
+
+- **WHEN** a metric or backup append exceeds its configured bound
+- **THEN** the oldest records MUST be pruned deterministically and an audit event MUST record the retention result
+
+#### Scenario: Interrupted backup is recoverable
+
+- **WHEN** a backup remains in an incomplete state during restart
+- **THEN** it MUST be projected as failed/recoverable with an audit outcome and MUST NOT claim an available artifact
+
+### Requirement: Safe queries enforce ownership
+
+The system SHALL authorize log, artifact, metric, and backup queries by platform session and server ownership/admin scope, returning bounded pages/cursors and never returning host paths, credentials, sockets, Run tokens, leases, session hashes, or secret references.
+
+#### Scenario: Cross-owner query
+
+- **WHEN** a user queries another owner's resource
+- **THEN** the service MUST reject with the existing 403 behavior and MUST NOT reveal whether private body data exists
@@ -0,0 +1,47 @@
+## ADDED Requirements
+
+### Requirement: Remote adapters are declared and scoped
+
+The system SHALL accept only typed adapter kinds and logical target keys declared by the installed plugin/runtime profile and selected Run endpoint.
+
+#### Scenario: Undeclared adapter
+
+- **WHEN** a request names an adapter or target not declared for the server and endpoint
+- **THEN** Platform MUST reject it before creating a job
+
+#### Scenario: Unsafe target data
+
+- **WHEN** a request contains shell source, raw socket addresses, host paths, credentials, or unbounded inline query/command data
+- **THEN** validation MUST reject it and MUST NOT persist the unsafe fields
+
+### Requirement: Adapter lifecycle is bounded and fenced
+
+The system SHALL enforce timeout, cancellation, retry, endpoint/session, attempt, and lease fencing using the existing job channel.
+
+#### Scenario: Cancelled adapter
+
+- **WHEN** cancellation arrives before or during adapter execution
+- **THEN** Run MUST stop at a bounded checkpoint and return a cancelled safe result; Platform MUST not apply a stale terminal result
+
+#### Scenario: Stale attempt result
+
+- **WHEN** an older attempt reports success after a newer attempt owns the lease
+- **THEN** Platform MUST reject the result and retain the newer job state
+
+### Requirement: Adapter results are auditable projections
+
+The system SHALL persist an audit event for authorization, timeout, cancellation, success, and failure outcomes and expose only adapter kind, target key, status, bounded message, and safe result references.
+
+#### Scenario: Successful scoped adapter
+
+- **WHEN** a declared adapter completes within its deadline
+- **THEN** the operator MUST see a safe status and audit summary without raw host/credential/socket details
+
+### Requirement: Channel isolation is maintained
+
+Remote adapter work and artifact transfer SHALL use lower-priority independent work paths and MUST NOT delay control heartbeat, job ack/result, or log upload acknowledgement beyond their deadlines.
+
+#### Scenario: Slow adapter and artifact transfer
+
+- **WHEN** adapter or chunk work blocks or retries
+- **THEN** control, job lifecycle, and log acknowledgement calls MUST remain independently completable