chore: release packages (#418)

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

.github/workflows/release-changesets.yml

@@ -57,6 +57,9 @@ jobs:
           pnpm --filter "@esengine/rpc" build
           pnpm --filter "@esengine/network" build
           pnpm --filter "@esengine/server" build
+          pnpm --filter "@esengine/database-drivers" build
+          pnpm --filter "@esengine/database" build
+          pnpm --filter "@esengine/transaction" build
           pnpm --filter "@esengine/cli" build
           pnpm --filter "create-esengine-server" build
 

docs/astro.config.mjs

@@ -267,6 +267,7 @@ export default defineConfig({
                 { label: '概述', slug: 'modules/network', translations: { en: 'Overview' } },
                 { label: '客户端', slug: 'modules/network/client', translations: { en: 'Client' } },
                 { label: '服务器', slug: 'modules/network/server', translations: { en: 'Server' } },
+                { label: 'HTTP 路由', slug: 'modules/network/http', translations: { en: 'HTTP Routing' } },
                 { label: '认证系统', slug: 'modules/network/auth', translations: { en: 'Authentication' } },
                 { label: '速率限制', slug: 'modules/network/rate-limit', translations: { en: 'Rate Limiting' } },
                 { label: '状态同步', slug: 'modules/network/sync', translations: { en: 'State Sync' } },
@@ -287,6 +288,25 @@ export default defineConfig({
                 { label: '分布式事务', slug: 'modules/transaction/distributed', translations: { en: 'Distributed' } },
               ],
             },
+            {
+              label: '数据库',
+              translations: { en: 'Database' },
+              items: [
+                { label: '概述', slug: 'modules/database', translations: { en: 'Overview' } },
+                { label: '仓储模式', slug: 'modules/database/repository', translations: { en: 'Repository' } },
+                { label: '用户仓储', slug: 'modules/database/user', translations: { en: 'User Repository' } },
+                { label: '查询构建器', slug: 'modules/database/query', translations: { en: 'Query Builder' } },
+              ],
+            },
+            {
+              label: '数据库驱动',
+              translations: { en: 'Database Drivers' },
+              items: [
+                { label: '概述', slug: 'modules/database-drivers', translations: { en: 'Overview' } },
+                { label: 'MongoDB', slug: 'modules/database-drivers/mongo', translations: { en: 'MongoDB' } },
+                { label: 'Redis', slug: 'modules/database-drivers/redis', translations: { en: 'Redis' } },
+              ],
+            },
             {
               label: '世界流式加载',
               translations: { en: 'World Streaming' },

docs/src/content/docs/en/modules/behavior-tree/custom-actions.md

@@ -182,6 +182,70 @@ export class IsHealthLow implements INodeExecutor {
 }
 ```
 
+## Using Custom Executors in BehaviorTreeBuilder
+
+After defining a custom executor with `@NodeExecutorMetadata`, use the `.action()` method in the builder:
+
+```typescript
+import { BehaviorTreeBuilder, BehaviorTreeStarter } from '@esengine/behavior-tree';
+
+// Use custom executor in behavior tree
+const tree = BehaviorTreeBuilder.create('CombatAI')
+    .defineBlackboardVariable('health', 100)
+    .defineBlackboardVariable('target', null)
+    .selector('Root')
+        .sequence('AttackSequence')
+            // Use custom action - matches implementationType in decorator
+            .action('AttackAction', 'Attack', { damage: 25 })
+            .action('MoveToTarget', 'Chase')
+        .end()
+        .action('WaitAction', 'Idle', { duration: 1000 })
+    .end()
+    .build();
+
+// Start the behavior tree
+const entity = scene.createEntity('Enemy');
+BehaviorTreeStarter.start(entity, tree);
+```
+
+### Builder Methods for Custom Nodes
+
+| Method | Description |
+|--------|-------------|
+| `.action(type, name?, config?)` | Add custom action node |
+| `.condition(type, name?, config?)` | Add custom condition node |
+| `.executeAction(name)` | Use blackboard function `action_{name}` |
+| `.executeCondition(name)` | Use blackboard function `condition_{name}` |
+
+### Complete Example
+
+```typescript
+// 1. Define custom executor
+@NodeExecutorMetadata({
+    implementationType: 'AttackAction',
+    nodeType: NodeType.Action,
+    displayName: 'Attack',
+    category: 'Combat',
+    configSchema: {
+        damage: { type: 'number', default: 10, supportBinding: true }
+    }
+})
+class AttackAction implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus {
+        const damage = BindingHelper.getValue<number>(context, 'damage', 10);
+        console.log(`Attacking with ${damage} damage!`);
+        return TaskStatus.Success;
+    }
+}
+
+// 2. Build and use
+const tree = BehaviorTreeBuilder.create('AI')
+    .selector('Root')
+        .action('AttackAction', 'Attack', { damage: 50 })
+    .end()
+    .build();
+```
+
 ## Registering Custom Executors
 
 Executors are auto-registered via the decorator. To manually register:

docs/src/content/docs/en/modules/database-drivers/index.md

@@ -0,0 +1,136 @@
+---
+title: "Database Drivers"
+description: "MongoDB, Redis connection management and driver abstraction"
+---
+
+`@esengine/database-drivers` is ESEngine's database connection management layer, providing unified connection management for MongoDB, Redis, and more.
+
+## Features
+
+- **Connection Pool** - Automatic connection pool management
+- **Auto Reconnect** - Automatic reconnection on disconnect
+- **Event Notification** - Connection state change events
+- **Type Decoupling** - Simplified interfaces, no dependency on native driver types
+- **Shared Connections** - Single connection shared across modules
+
+## Installation
+
+```bash
+npm install @esengine/database-drivers
+```
+
+**Peer Dependencies:**
+```bash
+npm install mongodb    # For MongoDB support
+npm install ioredis    # For Redis support
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  @esengine/database-drivers (Layer 1)                           │
+│  ┌─────────────────────┐  ┌─────────────────────┐               │
+│  │   MongoConnection   │  │   RedisConnection   │               │
+│  │   - Pool management │  │   - Auto-reconnect  │               │
+│  │   - Auto-reconnect  │  │   - Key prefix      │               │
+│  │   - Event emitter   │  │   - Event emitter   │               │
+│  └──────────┬──────────┘  └─────────────────────┘               │
+│             │                                                    │
+│  ┌──────────▼──────────┐                                        │
+│  │ IMongoCollection<T> │  ← Type-safe interface                 │
+│  │ (Adapter pattern)   │    decoupled from mongodb types        │
+│  └─────────────────────┘                                        │
+└─────────────────────────────────────────────────────────────────┘
+            │
+            ▼
+┌───────────────────────┐  ┌───────────────────────┐
+│  @esengine/database   │  │ @esengine/transaction │
+│  (Repository pattern) │  │ (Distributed tx)      │
+└───────────────────────┘  └───────────────────────┘
+```
+
+## Quick Start
+
+### MongoDB Connection
+
+```typescript
+import { createMongoConnection } from '@esengine/database-drivers'
+
+// Create connection
+const mongo = createMongoConnection({
+    uri: 'mongodb://localhost:27017',
+    database: 'game',
+    pool: {
+        minSize: 5,
+        maxSize: 20
+    },
+    autoReconnect: true
+})
+
+// Listen to events
+mongo.on('connected', () => console.log('MongoDB connected'))
+mongo.on('disconnected', () => console.log('MongoDB disconnected'))
+mongo.on('error', (e) => console.error('Error:', e.error))
+
+// Connect
+await mongo.connect()
+
+// Use collections
+const users = mongo.collection<User>('users')
+await users.insertOne({ name: 'John', score: 100 })
+
+const user = await users.findOne({ name: 'John' })
+
+// Disconnect when done
+await mongo.disconnect()
+```
+
+### Redis Connection
+
+```typescript
+import { createRedisConnection } from '@esengine/database-drivers'
+
+const redis = createRedisConnection({
+    host: 'localhost',
+    port: 6379,
+    keyPrefix: 'game:',
+    autoReconnect: true
+})
+
+await redis.connect()
+
+// Basic operations
+await redis.set('session:123', 'data', 3600)  // With TTL
+const value = await redis.get('session:123')
+
+await redis.disconnect()
+```
+
+## Service Container Integration
+
+```typescript
+import { ServiceContainer } from '@esengine/ecs-framework'
+import {
+    createMongoConnection,
+    MongoConnectionToken,
+    RedisConnectionToken
+} from '@esengine/database-drivers'
+
+const services = new ServiceContainer()
+
+// Register connections
+const mongo = createMongoConnection({ uri: '...', database: 'game' })
+await mongo.connect()
+services.register(MongoConnectionToken, mongo)
+
+// Retrieve in other modules
+const connection = services.get(MongoConnectionToken)
+const users = connection.collection('users')
+```
+
+## Documentation
+
+- [MongoDB Connection](/en/modules/database-drivers/mongo/) - MongoDB configuration details
+- [Redis Connection](/en/modules/database-drivers/redis/) - Redis configuration details
+- [Service Tokens](/en/modules/database-drivers/tokens/) - Dependency injection integration

docs/src/content/docs/en/modules/database-drivers/mongo.md

@@ -0,0 +1,265 @@
+---
+title: "MongoDB Connection"
+description: "MongoDB connection management, connection pooling, auto-reconnect"
+---
+
+## Configuration Options
+
+```typescript
+interface MongoConnectionConfig {
+    /** MongoDB connection URI */
+    uri: string
+
+    /** Database name */
+    database: string
+
+    /** Connection pool configuration */
+    pool?: {
+        minSize?: number      // Minimum connections
+        maxSize?: number      // Maximum connections
+        acquireTimeout?: number  // Connection acquire timeout (ms)
+        maxLifetime?: number     // Maximum connection lifetime (ms)
+    }
+
+    /** Auto-reconnect (default true) */
+    autoReconnect?: boolean
+
+    /** Reconnect interval (ms, default 5000) */
+    reconnectInterval?: number
+
+    /** Maximum reconnect attempts (default 10) */
+    maxReconnectAttempts?: number
+}
+```
+
+## Complete Example
+
+```typescript
+import { createMongoConnection, MongoConnectionToken } from '@esengine/database-drivers'
+
+const mongo = createMongoConnection({
+    uri: 'mongodb://localhost:27017',
+    database: 'game',
+    pool: {
+        minSize: 5,
+        maxSize: 20,
+        acquireTimeout: 5000,
+        maxLifetime: 300000
+    },
+    autoReconnect: true,
+    reconnectInterval: 5000,
+    maxReconnectAttempts: 10
+})
+
+// Event listeners
+mongo.on('connected', () => {
+    console.log('MongoDB connected')
+})
+
+mongo.on('disconnected', () => {
+    console.log('MongoDB disconnected')
+})
+
+mongo.on('reconnecting', () => {
+    console.log('MongoDB reconnecting...')
+})
+
+mongo.on('reconnected', () => {
+    console.log('MongoDB reconnected')
+})
+
+mongo.on('error', (event) => {
+    console.error('MongoDB error:', event.error)
+})
+
+// Connect
+await mongo.connect()
+
+// Check status
+console.log('Connected:', mongo.isConnected())
+console.log('Ping:', await mongo.ping())
+```
+
+## IMongoConnection Interface
+
+```typescript
+interface IMongoConnection {
+    /** Connection ID */
+    readonly id: string
+
+    /** Connection state */
+    readonly state: ConnectionState
+
+    /** Establish connection */
+    connect(): Promise<void>
+
+    /** Disconnect */
+    disconnect(): Promise<void>
+
+    /** Check if connected */
+    isConnected(): boolean
+
+    /** Test connection */
+    ping(): Promise<boolean>
+
+    /** Get typed collection */
+    collection<T extends object>(name: string): IMongoCollection<T>
+
+    /** Get database interface */
+    getDatabase(): IMongoDatabase
+
+    /** Get native client (advanced usage) */
+    getNativeClient(): MongoClientType
+
+    /** Get native database (advanced usage) */
+    getNativeDatabase(): Db
+}
+```
+
+## IMongoCollection Interface
+
+Type-safe collection interface, decoupled from native MongoDB types:
+
+```typescript
+interface IMongoCollection<T extends object> {
+    readonly name: string
+
+    // Query
+    findOne(filter: object, options?: FindOptions): Promise<T | null>
+    find(filter: object, options?: FindOptions): Promise<T[]>
+    countDocuments(filter?: object): Promise<number>
+
+    // Insert
+    insertOne(doc: T): Promise<InsertOneResult>
+    insertMany(docs: T[]): Promise<InsertManyResult>
+
+    // Update
+    updateOne(filter: object, update: object): Promise<UpdateResult>
+    updateMany(filter: object, update: object): Promise<UpdateResult>
+    findOneAndUpdate(
+        filter: object,
+        update: object,
+        options?: FindOneAndUpdateOptions
+    ): Promise<T | null>
+
+    // Delete
+    deleteOne(filter: object): Promise<DeleteResult>
+    deleteMany(filter: object): Promise<DeleteResult>
+
+    // Index
+    createIndex(
+        spec: Record<string, 1 | -1>,
+        options?: IndexOptions
+    ): Promise<string>
+}
+```
+
+## Usage Examples
+
+### Basic CRUD
+
+```typescript
+interface User {
+    id: string
+    name: string
+    email: string
+    score: number
+}
+
+const users = mongo.collection<User>('users')
+
+// Insert
+await users.insertOne({
+    id: '1',
+    name: 'John',
+    email: 'john@example.com',
+    score: 100
+})
+
+// Query
+const user = await users.findOne({ name: 'John' })
+
+const topUsers = await users.find(
+    { score: { $gte: 100 } },
+    { sort: { score: -1 }, limit: 10 }
+)
+
+// Update
+await users.updateOne(
+    { id: '1' },
+    { $inc: { score: 10 } }
+)
+
+// Delete
+await users.deleteOne({ id: '1' })
+```
+
+### Batch Operations
+
+```typescript
+// Batch insert
+await users.insertMany([
+    { id: '1', name: 'Alice', email: 'alice@example.com', score: 100 },
+    { id: '2', name: 'Bob', email: 'bob@example.com', score: 200 },
+    { id: '3', name: 'Carol', email: 'carol@example.com', score: 150 }
+])
+
+// Batch update
+await users.updateMany(
+    { score: { $lt: 100 } },
+    { $set: { status: 'inactive' } }
+)
+
+// Batch delete
+await users.deleteMany({ status: 'inactive' })
+```
+
+### Index Management
+
+```typescript
+// Create indexes
+await users.createIndex({ email: 1 }, { unique: true })
+await users.createIndex({ score: -1 })
+await users.createIndex({ name: 1, score: -1 })
+```
+
+## Integration with Other Modules
+
+### With @esengine/database
+
+```typescript
+import { createMongoConnection } from '@esengine/database-drivers'
+import { UserRepository, createRepository } from '@esengine/database'
+
+const mongo = createMongoConnection({
+    uri: 'mongodb://localhost:27017',
+    database: 'game'
+})
+await mongo.connect()
+
+// Use UserRepository
+const userRepo = new UserRepository(mongo)
+await userRepo.register({ username: 'john', password: '123456' })
+
+// Use generic repository
+const playerRepo = createRepository<Player>(mongo, 'players')
+```
+
+### With @esengine/transaction
+
+```typescript
+import { createMongoConnection } from '@esengine/database-drivers'
+import { createMongoStorage, TransactionManager } from '@esengine/transaction'
+
+const mongo = createMongoConnection({
+    uri: 'mongodb://localhost:27017',
+    database: 'game'
+})
+await mongo.connect()
+
+// Create transaction storage (shared connection)
+const storage = createMongoStorage(mongo)
+await storage.ensureIndexes()
+
+const txManager = new TransactionManager({ storage })
+```

docs/src/content/docs/en/modules/database-drivers/redis.md

@@ -0,0 +1,228 @@
+---
+title: "Redis Connection"
+description: "Redis connection management, auto-reconnect, key prefix"
+---
+
+## Configuration Options
+
+```typescript
+interface RedisConnectionConfig {
+    /** Redis host */
+    host?: string
+
+    /** Redis port */
+    port?: number
+
+    /** Authentication password */
+    password?: string
+
+    /** Database number */
+    db?: number
+
+    /** Key prefix */
+    keyPrefix?: string
+
+    /** Auto-reconnect (default true) */
+    autoReconnect?: boolean
+
+    /** Reconnect interval (ms, default 5000) */
+    reconnectInterval?: number
+
+    /** Maximum reconnect attempts (default 10) */
+    maxReconnectAttempts?: number
+}
+```
+
+## Complete Example
+
+```typescript
+import { createRedisConnection, RedisConnectionToken } from '@esengine/database-drivers'
+
+const redis = createRedisConnection({
+    host: 'localhost',
+    port: 6379,
+    password: 'your-password',
+    db: 0,
+    keyPrefix: 'game:',
+    autoReconnect: true,
+    reconnectInterval: 5000,
+    maxReconnectAttempts: 10
+})
+
+// Event listeners
+redis.on('connected', () => {
+    console.log('Redis connected')
+})
+
+redis.on('disconnected', () => {
+    console.log('Redis disconnected')
+})
+
+redis.on('error', (event) => {
+    console.error('Redis error:', event.error)
+})
+
+// Connect
+await redis.connect()
+
+// Check status
+console.log('Connected:', redis.isConnected())
+console.log('Ping:', await redis.ping())
+```
+
+## IRedisConnection Interface
+
+```typescript
+interface IRedisConnection {
+    /** Connection ID */
+    readonly id: string
+
+    /** Connection state */
+    readonly state: ConnectionState
+
+    /** Establish connection */
+    connect(): Promise<void>
+
+    /** Disconnect */
+    disconnect(): Promise<void>
+
+    /** Check if connected */
+    isConnected(): boolean
+
+    /** Test connection */
+    ping(): Promise<boolean>
+
+    /** Get value */
+    get(key: string): Promise<string | null>
+
+    /** Set value (optional TTL in seconds) */
+    set(key: string, value: string, ttl?: number): Promise<void>
+
+    /** Delete key */
+    del(key: string): Promise<boolean>
+
+    /** Check if key exists */
+    exists(key: string): Promise<boolean>
+
+    /** Set expiration (seconds) */
+    expire(key: string, seconds: number): Promise<boolean>
+
+    /** Get remaining TTL (seconds) */
+    ttl(key: string): Promise<number>
+
+    /** Get native client (advanced usage) */
+    getNativeClient(): Redis
+}
+```
+
+## Usage Examples
+
+### Basic Operations
+
+```typescript
+// Set value
+await redis.set('user:1:name', 'John')
+
+// Set value with expiration (1 hour)
+await redis.set('session:abc123', 'user-data', 3600)
+
+// Get value
+const name = await redis.get('user:1:name')
+
+// Check if key exists
+const exists = await redis.exists('user:1:name')
+
+// Delete key
+await redis.del('user:1:name')
+
+// Get remaining TTL
+const ttl = await redis.ttl('session:abc123')
+```
+
+### Key Prefix
+
+When `keyPrefix` is configured, all operations automatically add the prefix:
+
+```typescript
+const redis = createRedisConnection({
+    host: 'localhost',
+    keyPrefix: 'game:'
+})
+
+// Actual key is 'game:user:1'
+await redis.set('user:1', 'data')
+
+// Actual key queried is 'game:user:1'
+const data = await redis.get('user:1')
+```
+
+### Advanced Operations
+
+Use native client for advanced operations:
+
+```typescript
+const client = redis.getNativeClient()
+
+// Using Pipeline
+const pipeline = client.pipeline()
+pipeline.set('key1', 'value1')
+pipeline.set('key2', 'value2')
+pipeline.set('key3', 'value3')
+await pipeline.exec()
+
+// Using Transactions
+const multi = client.multi()
+multi.incr('counter')
+multi.get('counter')
+const results = await multi.exec()
+
+// Using Lua Scripts
+const result = await client.eval(
+    `return redis.call('get', KEYS[1])`,
+    1,
+    'mykey'
+)
+```
+
+## Integration with Transaction System
+
+```typescript
+import { createRedisConnection } from '@esengine/database-drivers'
+import { RedisStorage, TransactionManager } from '@esengine/transaction'
+
+const redis = createRedisConnection({
+    host: 'localhost',
+    port: 6379,
+    keyPrefix: 'tx:'
+})
+await redis.connect()
+
+// Create transaction storage
+const storage = new RedisStorage({
+    factory: () => redis.getNativeClient(),
+    prefix: 'tx:'
+})
+
+const txManager = new TransactionManager({ storage })
+```
+
+## Connection State
+
+```typescript
+type ConnectionState =
+    | 'disconnected'  // Not connected
+    | 'connecting'    // Connecting
+    | 'connected'     // Connected
+    | 'disconnecting' // Disconnecting
+    | 'error'         // Error state
+```
+
+## Events
+
+| Event | Description |
+|-------|-------------|
+| `connected` | Connection established |
+| `disconnected` | Connection closed |
+| `reconnecting` | Reconnecting |
+| `reconnected` | Reconnection successful |
+| `error` | Error occurred |

docs/src/content/docs/en/modules/database/index.md

@@ -0,0 +1,217 @@
+---
+title: "Database Repository"
+description: "Repository pattern database layer with CRUD, pagination, and soft delete"
+---
+
+`@esengine/database` is ESEngine's database operation layer, providing type-safe CRUD operations based on the Repository pattern.
+
+## Features
+
+- **Repository Pattern** - Generic CRUD operations with type safety
+- **Pagination** - Built-in pagination support
+- **Soft Delete** - Optional soft delete with restore
+- **User Management** - Ready-to-use UserRepository
+- **Password Security** - Secure password hashing with scrypt
+
+## Installation
+
+```bash
+npm install @esengine/database @esengine/database-drivers
+```
+
+## Quick Start
+
+### Basic Repository
+
+```typescript
+import { createMongoConnection } from '@esengine/database-drivers'
+import { Repository, createRepository } from '@esengine/database'
+
+// Define entity
+interface Player {
+    id: string
+    name: string
+    score: number
+    createdAt: Date
+    updatedAt: Date
+}
+
+// Create connection
+const mongo = createMongoConnection({
+    uri: 'mongodb://localhost:27017',
+    database: 'game'
+})
+await mongo.connect()
+
+// Create repository
+const playerRepo = createRepository<Player>(mongo, 'players')
+
+// CRUD operations
+const player = await playerRepo.create({
+    name: 'John',
+    score: 0
+})
+
+const found = await playerRepo.findById(player.id)
+
+await playerRepo.update(player.id, { score: 100 })
+
+await playerRepo.delete(player.id)
+```
+
+### Custom Repository
+
+```typescript
+import { Repository, BaseEntity } from '@esengine/database'
+import type { IMongoConnection } from '@esengine/database-drivers'
+
+interface Player extends BaseEntity {
+    name: string
+    score: number
+    rank?: string
+}
+
+class PlayerRepository extends Repository<Player> {
+    constructor(connection: IMongoConnection) {
+        super(connection, 'players')
+    }
+
+    async findTopPlayers(limit: number = 10): Promise<Player[]> {
+        return this.findMany({
+            sort: { score: 'desc' },
+            limit
+        })
+    }
+
+    async findByRank(rank: string): Promise<Player[]> {
+        return this.findMany({
+            where: { rank }
+        })
+    }
+}
+
+// Usage
+const playerRepo = new PlayerRepository(mongo)
+const topPlayers = await playerRepo.findTopPlayers(5)
+```
+
+### User Repository
+
+```typescript
+import { UserRepository } from '@esengine/database'
+
+const userRepo = new UserRepository(mongo)
+
+// Register new user
+const user = await userRepo.register({
+    username: 'john',
+    password: 'securePassword123',
+    email: 'john@example.com'
+})
+
+// Authenticate
+const authenticated = await userRepo.authenticate('john', 'securePassword123')
+if (authenticated) {
+    console.log('Login successful:', authenticated.username)
+}
+
+// Change password
+await userRepo.changePassword(user.id, 'securePassword123', 'newPassword456')
+
+// Role management
+await userRepo.addRole(user.id, 'admin')
+await userRepo.removeRole(user.id, 'admin')
+
+// Find users
+const admins = await userRepo.findByRole('admin')
+const john = await userRepo.findByUsername('john')
+```
+
+### Pagination
+
+```typescript
+const result = await playerRepo.findPaginated(
+    { page: 1, pageSize: 20 },
+    {
+        where: { rank: 'gold' },
+        sort: { score: 'desc' }
+    }
+)
+
+console.log(result.data)        // Player[]
+console.log(result.total)       // Total count
+console.log(result.totalPages)  // Total pages
+console.log(result.hasNext)     // Has next page
+console.log(result.hasPrev)     // Has previous page
+```
+
+### Soft Delete
+
+```typescript
+// Enable soft delete
+const playerRepo = createRepository<Player>(mongo, 'players', true)
+
+// Delete (marks as deleted)
+await playerRepo.delete(playerId)
+
+// Find excludes soft-deleted by default
+const players = await playerRepo.findMany()
+
+// Include soft-deleted records
+const allPlayers = await playerRepo.findMany({
+    includeSoftDeleted: true
+})
+
+// Restore soft-deleted record
+await playerRepo.restore(playerId)
+```
+
+### Query Options
+
+```typescript
+// Complex queries
+const players = await playerRepo.findMany({
+    where: {
+        score: { $gte: 100 },
+        rank: { $in: ['gold', 'platinum'] },
+        name: { $like: 'John%' }
+    },
+    sort: {
+        score: 'desc',
+        name: 'asc'
+    },
+    limit: 10,
+    offset: 0
+})
+
+// OR conditions
+const players = await playerRepo.findMany({
+    where: {
+        $or: [
+            { score: { $gte: 1000 } },
+            { rank: 'legendary' }
+        ]
+    }
+})
+```
+
+## Query Operators
+
+| Operator | Description | Example |
+|----------|-------------|---------|
+| `$eq` | Equal | `{ score: { $eq: 100 } }` |
+| `$ne` | Not equal | `{ status: { $ne: 'banned' } }` |
+| `$gt` | Greater than | `{ score: { $gt: 50 } }` |
+| `$gte` | Greater or equal | `{ level: { $gte: 10 } }` |
+| `$lt` | Less than | `{ age: { $lt: 18 } }` |
+| `$lte` | Less or equal | `{ price: { $lte: 100 } }` |
+| `$in` | In array | `{ rank: { $in: ['gold', 'platinum'] } }` |
+| `$nin` | Not in array | `{ status: { $nin: ['banned'] } }` |
+| `$like` | Pattern match | `{ name: { $like: '%john%' } }` |
+| `$regex` | Regex match | `{ email: { $regex: '@gmail.com$' } }` |
+
+## Documentation
+
+- [Repository API](/en/modules/database/repository/) - Repository detailed API
+- [User Management](/en/modules/database/user/) - UserRepository usage
+- [Query Syntax](/en/modules/database/query/) - Query condition syntax

docs/src/content/docs/en/modules/database/query.md

@@ -0,0 +1,185 @@
+---
+title: "Query Syntax"
+description: "Query condition operators and syntax"
+---
+
+## Basic Queries
+
+### Exact Match
+
+```typescript
+await repo.findMany({
+    where: {
+        name: 'John',
+        status: 'active'
+    }
+})
+```
+
+### Using Operators
+
+```typescript
+await repo.findMany({
+    where: {
+        score: { $gte: 100 },
+        rank: { $in: ['gold', 'platinum'] }
+    }
+})
+```
+
+## Query Operators
+
+| Operator | Description | Example |
+|----------|-------------|---------|
+| `$eq` | Equal | `{ score: { $eq: 100 } }` |
+| `$ne` | Not equal | `{ status: { $ne: 'banned' } }` |
+| `$gt` | Greater than | `{ score: { $gt: 50 } }` |
+| `$gte` | Greater than or equal | `{ level: { $gte: 10 } }` |
+| `$lt` | Less than | `{ age: { $lt: 18 } }` |
+| `$lte` | Less than or equal | `{ price: { $lte: 100 } }` |
+| `$in` | In array | `{ rank: { $in: ['gold', 'platinum'] } }` |
+| `$nin` | Not in array | `{ status: { $nin: ['banned', 'suspended'] } }` |
+| `$like` | Pattern match | `{ name: { $like: '%john%' } }` |
+| `$regex` | Regex match | `{ email: { $regex: '@gmail.com$' } }` |
+
+## Logical Operators
+
+### $or
+
+```typescript
+await repo.findMany({
+    where: {
+        $or: [
+            { score: { $gte: 1000 } },
+            { rank: 'legendary' }
+        ]
+    }
+})
+```
+
+### $and
+
+```typescript
+await repo.findMany({
+    where: {
+        $and: [
+            { score: { $gte: 100 } },
+            { score: { $lte: 500 } }
+        ]
+    }
+})
+```
+
+### Combined Usage
+
+```typescript
+await repo.findMany({
+    where: {
+        status: 'active',
+        $or: [
+            { rank: 'gold' },
+            { score: { $gte: 1000 } }
+        ]
+    }
+})
+```
+
+## Pattern Matching
+
+### $like Syntax
+
+- `%` - Matches any sequence of characters
+- `_` - Matches single character
+
+```typescript
+// Starts with 'John'
+{ name: { $like: 'John%' } }
+
+// Ends with 'son'
+{ name: { $like: '%son' } }
+
+// Contains 'oh'
+{ name: { $like: '%oh%' } }
+
+// Second character is 'o'
+{ name: { $like: '_o%' } }
+```
+
+### $regex Syntax
+
+Uses standard regular expressions:
+
+```typescript
+// Starts with 'John' (case insensitive)
+{ name: { $regex: '^john' } }
+
+// Gmail email
+{ email: { $regex: '@gmail\\.com$' } }
+
+// Contains numbers
+{ username: { $regex: '\\d+' } }
+```
+
+## Sorting
+
+```typescript
+await repo.findMany({
+    sort: {
+        score: 'desc',  // Descending
+        name: 'asc'     // Ascending
+    }
+})
+```
+
+## Pagination
+
+### Using limit/offset
+
+```typescript
+// First page
+await repo.findMany({
+    limit: 20,
+    offset: 0
+})
+
+// Second page
+await repo.findMany({
+    limit: 20,
+    offset: 20
+})
+```
+
+### Using findPaginated
+
+```typescript
+const result = await repo.findPaginated(
+    { page: 2, pageSize: 20 },
+    { sort: { createdAt: 'desc' } }
+)
+```
+
+## Complete Examples
+
+```typescript
+// Find active gold players with scores between 100-1000
+// Sort by score descending, get top 10
+const players = await repo.findMany({
+    where: {
+        status: 'active',
+        rank: 'gold',
+        score: { $gte: 100, $lte: 1000 }
+    },
+    sort: { score: 'desc' },
+    limit: 10
+})
+
+// Search for users with 'john' in username or gmail email
+const users = await repo.findMany({
+    where: {
+        $or: [
+            { username: { $like: '%john%' } },
+            { email: { $regex: '@gmail\\.com$' } }
+        ]
+    }
+})
+```

docs/src/content/docs/en/modules/database/repository.md

@@ -0,0 +1,244 @@
+---
+title: "Repository API"
+description: "Generic repository interface, CRUD operations, pagination, soft delete"
+---
+
+## Creating a Repository
+
+### Using Factory Function
+
+```typescript
+import { createRepository } from '@esengine/database'
+
+const playerRepo = createRepository<Player>(mongo, 'players')
+
+// Enable soft delete
+const playerRepo = createRepository<Player>(mongo, 'players', true)
+```
+
+### Extending Repository
+
+```typescript
+import { Repository, BaseEntity } from '@esengine/database'
+
+interface Player extends BaseEntity {
+    name: string
+    score: number
+}
+
+class PlayerRepository extends Repository<Player> {
+    constructor(connection: IMongoConnection) {
+        super(connection, 'players', false)  // Third param: enable soft delete
+    }
+
+    // Add custom methods
+    async findTopPlayers(limit: number): Promise<Player[]> {
+        return this.findMany({
+            sort: { score: 'desc' },
+            limit
+        })
+    }
+}
+```
+
+## BaseEntity Interface
+
+All entities must extend `BaseEntity`:
+
+```typescript
+interface BaseEntity {
+    id: string
+    createdAt: Date
+    updatedAt: Date
+    deletedAt?: Date  // Used for soft delete
+}
+```
+
+## Query Methods
+
+### findById
+
+```typescript
+const player = await repo.findById('player-123')
+```
+
+### findOne
+
+```typescript
+const player = await repo.findOne({
+    where: { name: 'John' }
+})
+
+const topPlayer = await repo.findOne({
+    sort: { score: 'desc' }
+})
+```
+
+### findMany
+
+```typescript
+// Simple query
+const players = await repo.findMany({
+    where: { rank: 'gold' }
+})
+
+// Complex query
+const players = await repo.findMany({
+    where: {
+        score: { $gte: 100 },
+        rank: { $in: ['gold', 'platinum'] }
+    },
+    sort: { score: 'desc', name: 'asc' },
+    limit: 10,
+    offset: 0
+})
+```
+
+### findPaginated
+
+```typescript
+const result = await repo.findPaginated(
+    { page: 1, pageSize: 20 },
+    {
+        where: { rank: 'gold' },
+        sort: { score: 'desc' }
+    }
+)
+
+console.log(result.data)        // Player[]
+console.log(result.total)       // Total count
+console.log(result.totalPages)  // Total pages
+console.log(result.hasNext)     // Has next page
+console.log(result.hasPrev)     // Has previous page
+```
+
+### count
+
+```typescript
+const count = await repo.count({
+    where: { rank: 'gold' }
+})
+```
+
+### exists
+
+```typescript
+const exists = await repo.exists({
+    where: { email: 'john@example.com' }
+})
+```
+
+## Create Methods
+
+### create
+
+```typescript
+const player = await repo.create({
+    name: 'John',
+    score: 0
+})
+// Automatically generates id, createdAt, updatedAt
+```
+
+### createMany
+
+```typescript
+const players = await repo.createMany([
+    { name: 'Alice', score: 100 },
+    { name: 'Bob', score: 200 },
+    { name: 'Carol', score: 150 }
+])
+```
+
+## Update Methods
+
+### update
+
+```typescript
+const updated = await repo.update('player-123', {
+    score: 200,
+    rank: 'gold'
+})
+// Automatically updates updatedAt
+```
+
+## Delete Methods
+
+### delete
+
+```typescript
+// Hard delete
+await repo.delete('player-123')
+
+// Soft delete (if enabled)
+// Actually sets the deletedAt field
+```
+
+### deleteMany
+
+```typescript
+const count = await repo.deleteMany({
+    where: { score: { $lt: 10 } }
+})
+```
+
+## Soft Delete
+
+### Enabling Soft Delete
+
+```typescript
+const repo = createRepository<Player>(mongo, 'players', true)
+```
+
+### Query Behavior
+
+```typescript
+// Excludes soft-deleted records by default
+const players = await repo.findMany()
+
+// Include soft-deleted records
+const allPlayers = await repo.findMany({
+    includeSoftDeleted: true
+})
+```
+
+### Restore Records
+
+```typescript
+await repo.restore('player-123')
+```
+
+## QueryOptions
+
+```typescript
+interface QueryOptions<T> {
+    /** Query conditions */
+    where?: WhereCondition<T>
+
+    /** Sorting */
+    sort?: Partial<Record<keyof T, 'asc' | 'desc'>>
+
+    /** Limit count */
+    limit?: number
+
+    /** Offset */
+    offset?: number
+
+    /** Include soft-deleted records (only when soft delete is enabled) */
+    includeSoftDeleted?: boolean
+}
+```
+
+## PaginatedResult
+
+```typescript
+interface PaginatedResult<T> {
+    data: T[]
+    total: number
+    page: number
+    pageSize: number
+    totalPages: number
+    hasNext: boolean
+    hasPrev: boolean
+}
+```

docs/src/content/docs/en/modules/database/user.md

@@ -0,0 +1,277 @@
+---
+title: "User Management"
+description: "UserRepository for user registration, authentication, and role management"
+---
+
+## Overview
+
+`UserRepository` provides out-of-the-box user management features:
+
+- User registration and authentication
+- Password hashing (using scrypt)
+- Role management
+- Account status management
+
+## Quick Start
+
+```typescript
+import { createMongoConnection } from '@esengine/database-drivers'
+import { UserRepository } from '@esengine/database'
+
+const mongo = createMongoConnection({
+    uri: 'mongodb://localhost:27017',
+    database: 'game'
+})
+await mongo.connect()
+
+const userRepo = new UserRepository(mongo)
+```
+
+## User Registration
+
+```typescript
+const user = await userRepo.register({
+    username: 'john',
+    password: 'securePassword123',
+    email: 'john@example.com',      // Optional
+    displayName: 'John Doe',         // Optional
+    roles: ['player']                // Optional, defaults to []
+})
+
+console.log(user)
+// {
+//   id: 'uuid-...',
+//   username: 'john',
+//   email: 'john@example.com',
+//   displayName: 'John Doe',
+//   roles: ['player'],
+//   status: 'active',
+//   createdAt: Date,
+//   updatedAt: Date
+// }
+```
+
+**Note**: `register` returns a `SafeUser` which excludes the password hash.
+
+## User Authentication
+
+```typescript
+const user = await userRepo.authenticate('john', 'securePassword123')
+
+if (user) {
+    console.log('Login successful:', user.username)
+} else {
+    console.log('Invalid username or password')
+}
+```
+
+## Password Management
+
+### Change Password
+
+```typescript
+const success = await userRepo.changePassword(
+    userId,
+    'oldPassword123',
+    'newPassword456'
+)
+
+if (success) {
+    console.log('Password changed successfully')
+} else {
+    console.log('Invalid current password')
+}
+```
+
+### Reset Password
+
+```typescript
+// Admin directly resets password
+const success = await userRepo.resetPassword(userId, 'newPassword123')
+```
+
+## Role Management
+
+### Add Role
+
+```typescript
+await userRepo.addRole(userId, 'admin')
+await userRepo.addRole(userId, 'moderator')
+```
+
+### Remove Role
+
+```typescript
+await userRepo.removeRole(userId, 'moderator')
+```
+
+### Query Roles
+
+```typescript
+// Find all admins
+const admins = await userRepo.findByRole('admin')
+
+// Check if user has a role
+const user = await userRepo.findById(userId)
+const isAdmin = user?.roles.includes('admin')
+```
+
+## Querying Users
+
+### Find by Username
+
+```typescript
+const user = await userRepo.findByUsername('john')
+```
+
+### Find by Email
+
+```typescript
+const user = await userRepo.findByEmail('john@example.com')
+```
+
+### Find by Role
+
+```typescript
+const admins = await userRepo.findByRole('admin')
+```
+
+### Using Inherited Methods
+
+```typescript
+// Paginated query
+const result = await userRepo.findPaginated(
+    { page: 1, pageSize: 20 },
+    {
+        where: { status: 'active' },
+        sort: { createdAt: 'desc' }
+    }
+)
+
+// Complex query
+const users = await userRepo.findMany({
+    where: {
+        status: 'active',
+        roles: { $in: ['admin', 'moderator'] }
+    }
+})
+```
+
+## Account Status
+
+```typescript
+type UserStatus = 'active' | 'inactive' | 'banned' | 'suspended'
+```
+
+### Update Status
+
+```typescript
+await userRepo.update(userId, { status: 'banned' })
+```
+
+### Query by Status
+
+```typescript
+const activeUsers = await userRepo.findMany({
+    where: { status: 'active' }
+})
+
+const bannedUsers = await userRepo.findMany({
+    where: { status: 'banned' }
+})
+```
+
+## Type Definitions
+
+### UserEntity
+
+```typescript
+interface UserEntity extends BaseEntity {
+    username: string
+    passwordHash: string
+    email?: string
+    displayName?: string
+    roles: string[]
+    status: UserStatus
+    lastLoginAt?: Date
+}
+```
+
+### SafeUser
+
+```typescript
+type SafeUser = Omit<UserEntity, 'passwordHash'>
+```
+
+### CreateUserParams
+
+```typescript
+interface CreateUserParams {
+    username: string
+    password: string
+    email?: string
+    displayName?: string
+    roles?: string[]
+}
+```
+
+## Password Utilities
+
+Standalone password utility functions:
+
+```typescript
+import { hashPassword, verifyPassword } from '@esengine/database'
+
+// Hash password
+const hash = await hashPassword('myPassword123')
+
+// Verify password
+const isValid = await verifyPassword('myPassword123', hash)
+```
+
+### Security Notes
+
+- Uses Node.js built-in `scrypt` algorithm
+- Automatically generates random salt
+- Uses secure iteration parameters by default
+- Hash format: `salt:hash` (both hex encoded)
+
+## Extending UserRepository
+
+```typescript
+import { UserRepository, UserEntity } from '@esengine/database'
+
+interface GameUser extends UserEntity {
+    level: number
+    experience: number
+    coins: number
+}
+
+class GameUserRepository extends UserRepository {
+    // Override collection name
+    constructor(connection: IMongoConnection) {
+        super(connection, 'game_users')
+    }
+
+    // Add game-related methods
+    async addExperience(userId: string, amount: number): Promise<GameUser | null> {
+        const user = await this.findById(userId) as GameUser | null
+        if (!user) return null
+
+        const newExp = user.experience + amount
+        const newLevel = Math.floor(newExp / 1000) + 1
+
+        return this.update(userId, {
+            experience: newExp,
+            level: newLevel
+        }) as Promise<GameUser | null>
+    }
+
+    async findTopPlayers(limit: number = 10): Promise<GameUser[]> {
+        return this.findMany({
+            sort: { level: 'desc', experience: 'desc' },
+            limit
+        }) as Promise<GameUser[]>
+    }
+}
+```

docs/src/content/docs/en/modules/index.md

@@ -36,6 +36,13 @@ ESEngine provides a rich set of modules that can be imported as needed.
 | [Network](/en/modules/network/) | `@esengine/network` | Multiplayer game networking |
 | [Transaction](/en/modules/transaction/) | `@esengine/transaction` | Game transactions with distributed support |
 
+### Database
+
+| Module | Package | Description |
+|--------|---------|-------------|
+| [Database Drivers](/en/modules/database-drivers/) | `@esengine/database-drivers` | MongoDB, Redis connection management |
+| [Database Repository](/en/modules/database/) | `@esengine/database` | Repository pattern data operations |
+
 ## Installation
 
 All modules can be installed independently:

docs/src/content/docs/en/modules/network/auth.md

@@ -92,6 +92,355 @@ const token = jwtProvider.sign({
 const payload = jwtProvider.decode(token)
 ```
 
+### Custom Provider
+
+You can create custom authentication providers by implementing the `IAuthProvider` interface to integrate with any authentication system (OAuth, LDAP, custom database auth, etc.).
+
+#### IAuthProvider Interface
+
+```typescript
+interface IAuthProvider<TUser = unknown, TCredentials = unknown> {
+    /** Provider name */
+    readonly name: string;
+
+    /** Verify credentials */
+    verify(credentials: TCredentials): Promise<AuthResult<TUser>>;
+
+    /** Refresh token (optional) */
+    refresh?(token: string): Promise<AuthResult<TUser>>;
+
+    /** Revoke token (optional) */
+    revoke?(token: string): Promise<boolean>;
+}
+
+interface AuthResult<TUser> {
+    success: boolean;
+    user?: TUser;
+    error?: string;
+    errorCode?: AuthErrorCode;
+    token?: string;
+    expiresAt?: number;
+}
+
+type AuthErrorCode =
+    | 'INVALID_CREDENTIALS'
+    | 'EXPIRED_TOKEN'
+    | 'INVALID_TOKEN'
+    | 'USER_NOT_FOUND'
+    | 'ACCOUNT_DISABLED'
+    | 'RATE_LIMITED'
+    | 'INSUFFICIENT_PERMISSIONS';
+```
+
+#### Custom Provider Examples
+
+**Example 1: Database Password Authentication**
+
+```typescript
+import type { IAuthProvider, AuthResult } from '@esengine/server/auth'
+
+interface User {
+    id: string
+    username: string
+    roles: string[]
+}
+
+interface PasswordCredentials {
+    username: string
+    password: string
+}
+
+class DatabaseAuthProvider implements IAuthProvider<User, PasswordCredentials> {
+    readonly name = 'database'
+
+    async verify(credentials: PasswordCredentials): Promise<AuthResult<User>> {
+        const { username, password } = credentials
+
+        // Query user from database
+        const user = await db.users.findByUsername(username)
+        if (!user) {
+            return {
+                success: false,
+                error: 'User not found',
+                errorCode: 'USER_NOT_FOUND'
+            }
+        }
+
+        // Verify password (using bcrypt or similar)
+        const isValid = await bcrypt.compare(password, user.passwordHash)
+        if (!isValid) {
+            return {
+                success: false,
+                error: 'Invalid password',
+                errorCode: 'INVALID_CREDENTIALS'
+            }
+        }
+
+        // Check account status
+        if (user.disabled) {
+            return {
+                success: false,
+                error: 'Account is disabled',
+                errorCode: 'ACCOUNT_DISABLED'
+            }
+        }
+
+        return {
+            success: true,
+            user: {
+                id: user.id,
+                username: user.username,
+                roles: user.roles
+            }
+        }
+    }
+}
+```
+
+**Example 2: OAuth/Third-party Authentication**
+
+```typescript
+import type { IAuthProvider, AuthResult } from '@esengine/server/auth'
+
+interface OAuthUser {
+    id: string
+    email: string
+    name: string
+    provider: string
+    roles: string[]
+}
+
+interface OAuthCredentials {
+    provider: 'google' | 'github' | 'discord'
+    accessToken: string
+}
+
+class OAuthProvider implements IAuthProvider<OAuthUser, OAuthCredentials> {
+    readonly name = 'oauth'
+
+    async verify(credentials: OAuthCredentials): Promise<AuthResult<OAuthUser>> {
+        const { provider, accessToken } = credentials
+
+        try {
+            // Verify token with provider
+            const profile = await this.fetchUserProfile(provider, accessToken)
+
+            // Find or create local user
+            let user = await db.users.findByOAuth(provider, profile.id)
+            if (!user) {
+                user = await db.users.create({
+                    oauthProvider: provider,
+                    oauthId: profile.id,
+                    email: profile.email,
+                    name: profile.name,
+                    roles: ['player']
+                })
+            }
+
+            return {
+                success: true,
+                user: {
+                    id: user.id,
+                    email: user.email,
+                    name: user.name,
+                    provider,
+                    roles: user.roles
+                }
+            }
+        } catch (error) {
+            return {
+                success: false,
+                error: 'OAuth verification failed',
+                errorCode: 'INVALID_TOKEN'
+            }
+        }
+    }
+
+    private async fetchUserProfile(provider: string, token: string) {
+        switch (provider) {
+            case 'google':
+                return fetch('https://www.googleapis.com/oauth2/v2/userinfo', {
+                    headers: { Authorization: `Bearer ${token}` }
+                }).then(r => r.json())
+            case 'github':
+                return fetch('https://api.github.com/user', {
+                    headers: { Authorization: `Bearer ${token}` }
+                }).then(r => r.json())
+            // Other providers...
+            default:
+                throw new Error(`Unsupported provider: ${provider}`)
+        }
+    }
+}
+```
+
+**Example 3: API Key Authentication**
+
+```typescript
+import type { IAuthProvider, AuthResult } from '@esengine/server/auth'
+
+interface ApiUser {
+    id: string
+    name: string
+    roles: string[]
+    rateLimit: number
+}
+
+class ApiKeyAuthProvider implements IAuthProvider<ApiUser, string> {
+    readonly name = 'api-key'
+
+    private revokedKeys = new Set<string>()
+
+    async verify(apiKey: string): Promise<AuthResult<ApiUser>> {
+        if (!apiKey || !apiKey.startsWith('sk_')) {
+            return {
+                success: false,
+                error: 'Invalid API Key format',
+                errorCode: 'INVALID_TOKEN'
+            }
+        }
+
+        if (this.revokedKeys.has(apiKey)) {
+            return {
+                success: false,
+                error: 'API Key has been revoked',
+                errorCode: 'INVALID_TOKEN'
+            }
+        }
+
+        // Query API Key from database
+        const keyData = await db.apiKeys.findByKey(apiKey)
+        if (!keyData) {
+            return {
+                success: false,
+                error: 'API Key not found',
+                errorCode: 'INVALID_CREDENTIALS'
+            }
+        }
+
+        // Check expiration
+        if (keyData.expiresAt && keyData.expiresAt < Date.now()) {
+            return {
+                success: false,
+                error: 'API Key has expired',
+                errorCode: 'EXPIRED_TOKEN'
+            }
+        }
+
+        return {
+            success: true,
+            user: {
+                id: keyData.userId,
+                name: keyData.name,
+                roles: keyData.roles,
+                rateLimit: keyData.rateLimit
+            },
+            expiresAt: keyData.expiresAt
+        }
+    }
+
+    async revoke(apiKey: string): Promise<boolean> {
+        this.revokedKeys.add(apiKey)
+        await db.apiKeys.revoke(apiKey)
+        return true
+    }
+}
+```
+
+#### Using Custom Providers
+
+```typescript
+import { createServer } from '@esengine/server'
+import { withAuth } from '@esengine/server/auth'
+
+// Create custom provider
+const dbAuthProvider = new DatabaseAuthProvider()
+
+// Or use OAuth provider
+const oauthProvider = new OAuthProvider()
+
+// Use custom provider
+const server = withAuth(await createServer({ port: 3000 }), {
+    provider: dbAuthProvider, // or oauthProvider
+
+    // Extract credentials from WebSocket connection request
+    extractCredentials: (req) => {
+        const url = new URL(req.url, 'http://localhost')
+
+        // For database auth: get from query params
+        const username = url.searchParams.get('username')
+        const password = url.searchParams.get('password')
+        if (username && password) {
+            return { username, password }
+        }
+
+        // For OAuth: get from token param
+        const provider = url.searchParams.get('provider')
+        const accessToken = url.searchParams.get('access_token')
+        if (provider && accessToken) {
+            return { provider, accessToken }
+        }
+
+        // For API Key: get from header
+        const apiKey = req.headers['x-api-key']
+        if (apiKey) {
+            return apiKey as string
+        }
+
+        return null
+    },
+
+    onAuthFailure: (conn, error) => {
+        console.log(`Auth failed: ${error.errorCode} - ${error.error}`)
+    }
+})
+
+await server.start()
+```
+
+#### Combining Multiple Providers
+
+You can create a composite provider to support multiple authentication methods:
+
+```typescript
+import type { IAuthProvider, AuthResult } from '@esengine/server/auth'
+
+interface MultiAuthCredentials {
+    type: 'jwt' | 'oauth' | 'apikey' | 'password'
+    data: unknown
+}
+
+class MultiAuthProvider implements IAuthProvider<User, MultiAuthCredentials> {
+    readonly name = 'multi'
+
+    constructor(
+        private jwtProvider: JwtAuthProvider<User>,
+        private oauthProvider: OAuthProvider,
+        private apiKeyProvider: ApiKeyAuthProvider,
+        private dbProvider: DatabaseAuthProvider
+    ) {}
+
+    async verify(credentials: MultiAuthCredentials): Promise<AuthResult<User>> {
+        switch (credentials.type) {
+            case 'jwt':
+                return this.jwtProvider.verify(credentials.data as string)
+            case 'oauth':
+                return this.oauthProvider.verify(credentials.data as OAuthCredentials)
+            case 'apikey':
+                return this.apiKeyProvider.verify(credentials.data as string)
+            case 'password':
+                return this.dbProvider.verify(credentials.data as PasswordCredentials)
+            default:
+                return {
+                    success: false,
+                    error: 'Unsupported authentication type',
+                    errorCode: 'INVALID_CREDENTIALS'
+                }
+        }
+    }
+}
+```
+
 ### Session Provider
 
 Use server-side sessions for stateful authentication:

docs/src/content/docs/en/modules/network/http.md

@@ -0,0 +1,679 @@
+---
+title: "HTTP Routing"
+description: "HTTP REST API routing with WebSocket port sharing support"
+---
+
+`@esengine/server` includes a lightweight HTTP routing feature that can share the same port with WebSocket services, making it easy to implement REST APIs.
+
+## Quick Start
+
+### Inline Route Definition
+
+The simplest way is to define HTTP routes directly when creating the server:
+
+```typescript
+import { createServer } from '@esengine/server'
+
+const server = await createServer({
+    port: 3000,
+    http: {
+        '/api/health': (req, res) => {
+            res.json({ status: 'ok', time: Date.now() })
+        },
+        '/api/users': {
+            GET: (req, res) => {
+                res.json({ users: [] })
+            },
+            POST: async (req, res) => {
+                const body = req.body as { name: string }
+                res.status(201).json({ id: '1', name: body.name })
+            }
+        }
+    },
+    cors: true  // Enable CORS
+})
+
+await server.start()
+```
+
+### File-based Routing
+
+For larger projects, file-based routing is recommended. Create a `src/http` directory where each file corresponds to a route:
+
+```typescript
+// src/http/login.ts
+import { defineHttp } from '@esengine/server'
+
+interface LoginBody {
+    username: string
+    password: string
+}
+
+export default defineHttp<LoginBody>({
+    method: 'POST',
+    handler(req, res) {
+        const { username, password } = req.body as LoginBody
+
+        // Validate user...
+        if (username === 'admin' && password === '123456') {
+            res.json({ token: 'jwt-token-here', userId: 'user-1' })
+        } else {
+            res.error(401, 'Invalid username or password')
+        }
+    }
+})
+```
+
+```typescript
+// server.ts
+import { createServer } from '@esengine/server'
+
+const server = await createServer({
+    port: 3000,
+    httpDir: './src/http',   // HTTP routes directory
+    httpPrefix: '/api',       // Route prefix
+    cors: true
+})
+
+await server.start()
+// Route: POST /api/login
+```
+
+## defineHttp Definition
+
+`defineHttp` is used to define type-safe HTTP handlers:
+
+```typescript
+import { defineHttp } from '@esengine/server'
+
+interface CreateUserBody {
+    username: string
+    email: string
+    password: string
+}
+
+export default defineHttp<CreateUserBody>({
+    // HTTP method (default POST)
+    method: 'POST',
+
+    // Handler function
+    handler(req, res) {
+        const body = req.body as CreateUserBody
+        // Handle request...
+        res.status(201).json({ id: 'new-user-id' })
+    }
+})
+```
+
+### Supported HTTP Methods
+
+```typescript
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS'
+```
+
+## HttpRequest Object
+
+The HTTP request object contains the following properties:
+
+```typescript
+interface HttpRequest {
+    /** Raw Node.js IncomingMessage */
+    raw: IncomingMessage
+
+    /** HTTP method */
+    method: string
+
+    /** Request path */
+    path: string
+
+    /** Route parameters (extracted from URL path, e.g., /users/:id) */
+    params: Record<string, string>
+
+    /** Query parameters */
+    query: Record<string, string>
+
+    /** Request headers */
+    headers: Record<string, string | string[] | undefined>
+
+    /** Parsed request body */
+    body: unknown
+
+    /** Client IP */
+    ip: string
+}
+```
+
+### Usage Examples
+
+```typescript
+export default defineHttp({
+    method: 'GET',
+    handler(req, res) {
+        // Get query parameters
+        const page = parseInt(req.query.page ?? '1')
+        const limit = parseInt(req.query.limit ?? '10')
+
+        // Get request headers
+        const authHeader = req.headers.authorization
+
+        // Get client IP
+        console.log('Request from:', req.ip)
+
+        res.json({ page, limit })
+    }
+})
+```
+
+### Body Parsing
+
+The request body is automatically parsed based on `Content-Type`:
+
+- `application/json` - Parsed as JSON object
+- `application/x-www-form-urlencoded` - Parsed as key-value object
+- Others - Kept as raw string
+
+```typescript
+export default defineHttp<{ name: string; age: number }>({
+    method: 'POST',
+    handler(req, res) {
+        // body is already parsed
+        const { name, age } = req.body as { name: string; age: number }
+        res.json({ received: { name, age } })
+    }
+})
+```
+
+## HttpResponse Object
+
+The HTTP response object provides a chainable API:
+
+```typescript
+interface HttpResponse {
+    /** Raw Node.js ServerResponse */
+    raw: ServerResponse
+
+    /** Set status code */
+    status(code: number): HttpResponse
+
+    /** Set response header */
+    header(name: string, value: string): HttpResponse
+
+    /** Send JSON response */
+    json(data: unknown): void
+
+    /** Send text response */
+    text(data: string): void
+
+    /** Send error response */
+    error(code: number, message: string): void
+}
+```
+
+### Usage Examples
+
+```typescript
+export default defineHttp({
+    method: 'POST',
+    handler(req, res) {
+        // Set status code and custom headers
+        res
+            .status(201)
+            .header('X-Custom-Header', 'value')
+            .json({ created: true })
+    }
+})
+```
+
+```typescript
+export default defineHttp({
+    method: 'GET',
+    handler(req, res) {
+        // Send error response
+        res.error(404, 'Resource not found')
+        // Equivalent to: res.status(404).json({ error: 'Resource not found' })
+    }
+})
+```
+
+```typescript
+export default defineHttp({
+    method: 'GET',
+    handler(req, res) {
+        // Send plain text
+        res.text('Hello, World!')
+    }
+})
+```
+
+## File Routing Conventions
+
+### Name Conversion
+
+File names are automatically converted to route paths:
+
+| File Path | Route Path (prefix=/api) |
+|-----------|-------------------------|
+| `login.ts` | `/api/login` |
+| `users/profile.ts` | `/api/users/profile` |
+| `users/[id].ts` | `/api/users/:id` |
+| `game/room/[roomId].ts` | `/api/game/room/:roomId` |
+
+### Dynamic Route Parameters
+
+Use `[param]` syntax to define dynamic parameters:
+
+```typescript
+// src/http/users/[id].ts
+import { defineHttp } from '@esengine/server'
+
+export default defineHttp({
+    method: 'GET',
+    handler(req, res) {
+        // Get route parameter directly from params
+        const { id } = req.params
+        res.json({ userId: id })
+    }
+})
+```
+
+Multiple parameters:
+
+```typescript
+// src/http/users/[userId]/posts/[postId].ts
+import { defineHttp } from '@esengine/server'
+
+export default defineHttp({
+    method: 'GET',
+    handler(req, res) {
+        const { userId, postId } = req.params
+        res.json({ userId, postId })
+    }
+})
+```
+
+### Skip Rules
+
+The following files are automatically skipped:
+
+- Files starting with `_` (e.g., `_helper.ts`)
+- `index.ts` / `index.js` files
+- Non `.ts` / `.js` / `.mts` / `.mjs` files
+
+### Directory Structure Example
+
+```
+src/
+└── http/
+    ├── _utils.ts        # Skipped (underscore prefix)
+    ├── index.ts         # Skipped (index file)
+    ├── health.ts        # GET /api/health
+    ├── login.ts         # POST /api/login
+    ├── register.ts      # POST /api/register
+    └── users/
+        ├── index.ts     # Skipped
+        ├── list.ts      # GET /api/users/list
+        └── [id].ts      # GET /api/users/:id
+```
+
+## CORS Configuration
+
+### Quick Enable
+
+```typescript
+const server = await createServer({
+    port: 3000,
+    cors: true  // Use default configuration
+})
+```
+
+### Custom Configuration
+
+```typescript
+const server = await createServer({
+    port: 3000,
+    cors: {
+        // Allowed origins
+        origin: ['http://localhost:5173', 'https://myapp.com'],
+        // Or use wildcard
+        // origin: '*',
+        // origin: true,  // Reflect request origin
+
+        // Allowed HTTP methods
+        methods: ['GET', 'POST', 'PUT', 'DELETE'],
+
+        // Allowed request headers
+        allowedHeaders: ['Content-Type', 'Authorization', 'X-Requested-With'],
+
+        // Allow credentials (cookies)
+        credentials: true,
+
+        // Preflight cache max age (seconds)
+        maxAge: 86400
+    }
+})
+```
+
+### CorsOptions Type
+
+```typescript
+interface CorsOptions {
+    /** Allowed origins: string, string array, true (reflect) or '*' */
+    origin?: string | string[] | boolean
+
+    /** Allowed HTTP methods */
+    methods?: string[]
+
+    /** Allowed request headers */
+    allowedHeaders?: string[]
+
+    /** Allow credentials */
+    credentials?: boolean
+
+    /** Preflight cache max age (seconds) */
+    maxAge?: number
+}
+```
+
+## Route Merging
+
+File routes and inline routes can be used together, with inline routes having higher priority:
+
+```typescript
+const server = await createServer({
+    port: 3000,
+    httpDir: './src/http',
+    httpPrefix: '/api',
+
+    // Inline routes merge with file routes
+    http: {
+        '/health': (req, res) => res.json({ status: 'ok' }),
+        '/api/special': (req, res) => res.json({ special: true })
+    }
+})
+```
+
+## Sharing Port with WebSocket
+
+HTTP routes automatically share the same port with WebSocket services:
+
+```typescript
+const server = await createServer({
+    port: 3000,
+    // WebSocket related config
+    apiDir: './src/api',
+    msgDir: './src/msg',
+
+    // HTTP related config
+    httpDir: './src/http',
+    httpPrefix: '/api',
+    cors: true
+})
+
+await server.start()
+
+// Same port 3000:
+// - WebSocket: ws://localhost:3000
+// - HTTP API:  http://localhost:3000/api/*
+```
+
+## Complete Examples
+
+### Game Server Login API
+
+```typescript
+// src/http/auth/login.ts
+import { defineHttp } from '@esengine/server'
+import { createJwtAuthProvider } from '@esengine/server/auth'
+
+interface LoginRequest {
+    username: string
+    password: string
+}
+
+interface LoginResponse {
+    token: string
+    userId: string
+    expiresAt: number
+}
+
+const jwtProvider = createJwtAuthProvider({
+    secret: process.env.JWT_SECRET!,
+    expiresIn: 3600
+})
+
+export default defineHttp<LoginRequest>({
+    method: 'POST',
+    async handler(req, res) {
+        const { username, password } = req.body as LoginRequest
+
+        // Validate user
+        const user = await db.users.findByUsername(username)
+        if (!user || !await verifyPassword(password, user.passwordHash)) {
+            res.error(401, 'Invalid username or password')
+            return
+        }
+
+        // Generate JWT
+        const token = jwtProvider.sign({
+            sub: user.id,
+            name: user.username,
+            roles: user.roles
+        })
+
+        const response: LoginResponse = {
+            token,
+            userId: user.id,
+            expiresAt: Date.now() + 3600 * 1000
+        }
+
+        res.json(response)
+    }
+})
+```
+
+### Game Data Query API
+
+```typescript
+// src/http/game/leaderboard.ts
+import { defineHttp } from '@esengine/server'
+
+export default defineHttp({
+    method: 'GET',
+    async handler(req, res) {
+        const limit = parseInt(req.query.limit ?? '10')
+        const offset = parseInt(req.query.offset ?? '0')
+
+        const players = await db.players.findMany({
+            sort: { score: 'desc' },
+            limit,
+            offset
+        })
+
+        res.json({
+            data: players,
+            pagination: { limit, offset }
+        })
+    }
+})
+```
+
+## Middleware
+
+### Middleware Type
+
+Middleware are functions that execute before and after route handlers:
+
+```typescript
+type HttpMiddleware = (
+    req: HttpRequest,
+    res: HttpResponse,
+    next: () => Promise<void>
+) => void | Promise<void>
+```
+
+### Built-in Middleware
+
+```typescript
+import {
+    requestLogger,
+    bodyLimit,
+    responseTime,
+    requestId,
+    securityHeaders
+} from '@esengine/server'
+
+const server = await createServer({
+    port: 3000,
+    http: { /* ... */ },
+    // Global middleware configured via createHttpRouter
+})
+```
+
+#### requestLogger - Request Logging
+
+```typescript
+import { requestLogger } from '@esengine/server'
+
+// Log request and response time
+requestLogger()
+
+// Also log request body
+requestLogger({ logBody: true })
+```
+
+#### bodyLimit - Request Body Size Limit
+
+```typescript
+import { bodyLimit } from '@esengine/server'
+
+// Limit request body to 1MB
+bodyLimit(1024 * 1024)
+```
+
+#### responseTime - Response Time Header
+
+```typescript
+import { responseTime } from '@esengine/server'
+
+// Automatically add X-Response-Time header
+responseTime()
+```
+
+#### requestId - Request ID
+
+```typescript
+import { requestId } from '@esengine/server'
+
+// Auto-generate and add X-Request-ID header
+requestId()
+
+// Custom header name
+requestId('X-Trace-ID')
+```
+
+#### securityHeaders - Security Headers
+
+```typescript
+import { securityHeaders } from '@esengine/server'
+
+// Add common security response headers
+securityHeaders()
+
+// Custom configuration
+securityHeaders({
+    hidePoweredBy: true,
+    frameOptions: 'DENY',
+    noSniff: true
+})
+```
+
+### Custom Middleware
+
+```typescript
+import type { HttpMiddleware } from '@esengine/server'
+
+// Authentication middleware
+const authMiddleware: HttpMiddleware = async (req, res, next) => {
+    const token = req.headers.authorization?.replace('Bearer ', '')
+
+    if (!token) {
+        res.error(401, 'Unauthorized')
+        return  // Don't call next(), terminate request
+    }
+
+    // Validate token...
+    (req as any).userId = 'decoded-user-id'
+
+    await next()  // Continue to next middleware and handler
+}
+```
+
+### Using Middleware
+
+#### With createHttpRouter
+
+```typescript
+import { createHttpRouter, requestLogger, bodyLimit } from '@esengine/server'
+
+const router = createHttpRouter({
+    '/api/users': (req, res) => res.json([]),
+    '/api/admin': {
+        GET: {
+            handler: (req, res) => res.json({ admin: true }),
+            middlewares: [adminAuthMiddleware]  // Route-level middleware
+        }
+    }
+}, {
+    middlewares: [requestLogger(), bodyLimit(1024 * 1024)],  // Global middleware
+    timeout: 30000  // Global timeout 30 seconds
+})
+```
+
+## Request Timeout
+
+### Global Timeout
+
+```typescript
+import { createHttpRouter } from '@esengine/server'
+
+const router = createHttpRouter({
+    '/api/data': async (req, res) => {
+        // If processing exceeds 30 seconds, auto-return 408 Request Timeout
+        await someSlowOperation()
+        res.json({ data: 'result' })
+    }
+}, {
+    timeout: 30000  // 30 seconds
+})
+```
+
+### Route-level Timeout
+
+```typescript
+const router = createHttpRouter({
+    '/api/quick': (req, res) => res.json({ fast: true }),
+
+    '/api/slow': {
+        POST: {
+            handler: async (req, res) => {
+                await verySlowOperation()
+                res.json({ done: true })
+            },
+            timeout: 120000  // This route allows 2 minutes
+        }
+    }
+}, {
+    timeout: 10000  // Global 10 seconds (overridden by route-level)
+})
+```
+
+## Best Practices
+
+1. **Use defineHttp** - Get better type hints and code organization
+2. **Unified Error Handling** - Use `res.error()` to return consistent error format
+3. **Enable CORS** - Required for frontend-backend separation
+4. **Directory Organization** - Organize HTTP route files by functional modules
+5. **Validate Input** - Always validate `req.body` and `req.query` content
+6. **Status Code Standards** - Follow HTTP status code conventions (200, 201, 400, 401, 404, 500, etc.)
+7. **Use Middleware** - Implement cross-cutting concerns like auth, logging, rate limiting via middleware
+8. **Set Timeouts** - Prevent slow requests from blocking the server

docs/src/content/docs/en/modules/network/server.md

@@ -79,10 +79,33 @@ await server.start()
 | `tickRate` | `number` | `20` | Global tick rate (Hz) |
 | `apiDir` | `string` | `'src/api'` | API handlers directory |
 | `msgDir` | `string` | `'src/msg'` | Message handlers directory |
+| `httpDir` | `string` | `'src/http'` | HTTP routes directory |
+| `httpPrefix` | `string` | `'/api'` | HTTP routes prefix |
+| `cors` | `boolean \| CorsOptions` | - | CORS configuration |
 | `onStart` | `(port) => void` | - | Start callback |
 | `onConnect` | `(conn) => void` | - | Connection callback |
 | `onDisconnect` | `(conn) => void` | - | Disconnect callback |
 
+## HTTP Routing
+
+Supports HTTP API sharing the same port with WebSocket, ideal for login, registration, and similar scenarios.
+
+```typescript
+const server = await createServer({
+    port: 3000,
+    httpDir: './src/http',   // HTTP routes directory
+    httpPrefix: '/api',       // Route prefix
+    cors: true,
+
+    // Or inline definition
+    http: {
+        '/health': (req, res) => res.json({ status: 'ok' })
+    }
+})
+```
+
+> For detailed documentation, see [HTTP Routing](/en/modules/network/http)
+
 ## Room System
 
 Room is the base class for game rooms, managing players and game state.

docs/src/content/docs/en/modules/transaction/storage.md

@@ -125,23 +125,24 @@ tx:data:{key}           - Business data
 
 ## MongoStorage
 
-MongoDB storage, suitable for scenarios requiring persistence and complex queries. Uses factory pattern with lazy connection.
+MongoDB storage, suitable for scenarios requiring persistence and complex queries. Uses shared connection from `@esengine/database-drivers`.
 
 ```typescript
-import { MongoClient } from 'mongodb';
-import { MongoStorage } from '@esengine/transaction';
+import { createMongoConnection } from '@esengine/database-drivers';
+import { createMongoStorage, TransactionManager } from '@esengine/transaction';
 
-// Factory pattern: lazy connection, connects on first operation
-const storage = new MongoStorage({
-    factory: async () => {
-        const client = new MongoClient('mongodb://localhost:27017');
-        await client.connect();
-        return client;
-    },
-    database: 'game',
-    transactionCollection: 'transactions',  // Transaction log collection
-    dataCollection: 'transaction_data',     // Business data collection
-    lockCollection: 'transaction_locks',    // Lock collection
+// Create shared connection
+const mongo = createMongoConnection({
+    uri: 'mongodb://localhost:27017',
+    database: 'game'
+});
+await mongo.connect();
+
+// Create storage using shared connection
+const storage = createMongoStorage(mongo, {
+    transactionCollection: 'transactions',  // Transaction log collection (optional)
+    dataCollection: 'transaction_data',     // Business data collection (optional)
+    lockCollection: 'transaction_locks',    // Lock collection (optional)
 });
 
 // Create indexes (run on first startup)
@@ -149,11 +150,14 @@ await storage.ensureIndexes();
 
 const manager = new TransactionManager({ storage });
 
-// Close connection when done
+// Close storage (does not close shared connection)
 await storage.close();
 
-// Or use await using for automatic cleanup (TypeScript 5.2+)
-await using storage = new MongoStorage({ ... });
+// Shared connection can continue to be used by other modules
+const userRepo = new UserRepository(mongo);  // @esengine/database
+
+// Finally close the shared connection
+await mongo.disconnect();
 ```
 
 ### Characteristics

docs/src/content/docs/modules/behavior-tree/custom-actions.md

@@ -606,6 +606,107 @@ export class RetryDecorator implements INodeExecutor {
 }
 ```
 
+## 在代码中使用自定义执行器
+
+定义了自定义执行器后，可以通过 `BehaviorTreeBuilder` 的 `.action()` 和 `.condition()` 方法在代码中使用：
+
+### 使用 action() 方法
+
+```typescript
+import { BehaviorTreeBuilder, BehaviorTreeStarter } from '@esengine/behavior-tree';
+
+// 使用自定义执行器构建行为树
+const tree = BehaviorTreeBuilder.create('CombatAI')
+    .defineBlackboardVariable('health', 100)
+    .defineBlackboardVariable('target', null)
+    .selector('Root')
+        .sequence('AttackSequence')
+            // 使用自定义动作 - implementationType 匹配装饰器中的定义
+            .action('AttackAction', 'Attack', { damage: 25 })
+            .action('MoveToPosition', 'Chase', { speed: 10 })
+        .end()
+        .action('DelayAction', 'Idle', { duration: 1.0 })
+    .end()
+    .build();
+
+// 启动行为树
+const entity = scene.createEntity('Enemy');
+BehaviorTreeStarter.start(entity, tree);
+```
+
+### 使用 condition() 方法
+
+```typescript
+const tree = BehaviorTreeBuilder.create('AI')
+    .selector('Root')
+        .sequence('AttackBranch')
+            // 使用自定义条件
+            .condition('CheckHealth', 'IsHealthy', { threshold: 50, operator: 'greater' })
+            .action('AttackAction', 'Attack')
+        .end()
+    .end()
+    .build();
+```
+
+### Builder 方法对照表
+
+| 方法 | 说明 | 使用场景 |
+|------|------|----------|
+| `.action(type, name?, config?)` | 使用自定义动作执行器 | 自定义 Action 类 |
+| `.condition(type, name?, config?)` | 使用自定义条件执行器 | 自定义 Condition 类 |
+| `.executeAction(name)` | 调用黑板函数 `action_{name}` | 简单逻辑、快速原型 |
+| `.executeCondition(name)` | 调用黑板函数 `condition_{name}` | 简单条件判断 |
+
+### 完整示例
+
+```typescript
+import {
+    BehaviorTreeBuilder,
+    BehaviorTreeStarter,
+    NodeExecutorMetadata,
+    INodeExecutor,
+    NodeExecutionContext,
+    TaskStatus,
+    NodeType,
+    BindingHelper
+} from '@esengine/behavior-tree';
+
+// 1. 定义自定义执行器
+@NodeExecutorMetadata({
+    implementationType: 'AttackAction',
+    nodeType: NodeType.Action,
+    displayName: '攻击',
+    category: 'Combat',
+    configSchema: {
+        damage: { type: 'number', default: 10, supportBinding: true }
+    }
+})
+class AttackAction implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus {
+        const damage = BindingHelper.getValue<number>(context, 'damage', 10);
+        console.log(`执行攻击，造成 ${damage} 点伤害！`);
+        return TaskStatus.Success;
+    }
+}
+
+// 2. 构建行为树
+const enemyAI = BehaviorTreeBuilder.create('EnemyAI')
+    .defineBlackboardVariable('health', 100)
+    .defineBlackboardVariable('target', null)
+    .selector('MainBehavior')
+        .sequence('AttackBranch')
+            .condition('CheckHealth', 'HasEnoughHealth', { threshold: 20, operator: 'greater' })
+            .action('AttackAction', 'Attack', { damage: 50 })
+        .end()
+        .log('逃跑', 'Flee')
+    .end()
+    .build();
+
+// 3. 启动行为树
+const entity = scene.createEntity('Enemy');
+BehaviorTreeStarter.start(entity, enemyAI);
+```
+
 ## 注册执行器
 
 ### 自动注册

docs/src/content/docs/modules/database-drivers/index.md

@@ -0,0 +1,136 @@
+---
+title: "数据库驱动"
+description: "MongoDB、Redis 等数据库的连接管理和驱动封装"
+---
+
+`@esengine/database-drivers` 是 ESEngine 的数据库连接管理层，提供 MongoDB、Redis 等数据库的统一连接管理。
+
+## 特性
+
+- **连接池管理** - 自动管理连接池，优化资源使用
+- **自动重连** - 连接断开时自动重连
+- **事件通知** - 连接状态变化事件
+- **类型解耦** - 简化接口，不依赖原生驱动类型
+- **共享连接** - 单一连接可供多个模块共享
+
+## 安装
+
+```bash
+npm install @esengine/database-drivers
+```
+
+**对等依赖：**
+```bash
+npm install mongodb    # MongoDB 支持
+npm install ioredis    # Redis 支持
+```
+
+## 架构
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  @esengine/database-drivers (Layer 1)                           │
+│  ┌─────────────────────┐  ┌─────────────────────┐               │
+│  │   MongoConnection   │  │   RedisConnection   │               │
+│  │   - 连接池管理      │  │   - 自动重连        │               │
+│  │   - 自动重连        │  │   - Key 前缀        │               │
+│  │   - 事件发射器      │  │   - 事件发射器      │               │
+│  └──────────┬──────────┘  └─────────────────────┘               │
+│             │                                                    │
+│  ┌──────────▼──────────┐                                        │
+│  │ IMongoCollection<T> │  ← 类型安全接口                         │
+│  │ (适配器模式)        │    与 mongodb 类型解耦                   │
+│  └─────────────────────┘                                        │
+└─────────────────────────────────────────────────────────────────┘
+            │
+            ▼
+┌───────────────────────┐  ┌───────────────────────┐
+│  @esengine/database   │  │ @esengine/transaction │
+│  (仓库模式)           │  │ (分布式事务)          │
+└───────────────────────┘  └───────────────────────┘
+```
+
+## 快速开始
+
+### MongoDB 连接
+
+```typescript
+import { createMongoConnection } from '@esengine/database-drivers'
+
+// 创建连接
+const mongo = createMongoConnection({
+    uri: 'mongodb://localhost:27017',
+    database: 'game',
+    pool: {
+        minSize: 5,
+        maxSize: 20
+    },
+    autoReconnect: true
+})
+
+// 监听事件
+mongo.on('connected', () => console.log('MongoDB 已连接'))
+mongo.on('disconnected', () => console.log('MongoDB 已断开'))
+mongo.on('error', (e) => console.error('错误:', e.error))
+
+// 建立连接
+await mongo.connect()
+
+// 使用集合
+const users = mongo.collection<User>('users')
+await users.insertOne({ name: 'John', score: 100 })
+
+const user = await users.findOne({ name: 'John' })
+
+// 完成后断开连接
+await mongo.disconnect()
+```
+
+### Redis 连接
+
+```typescript
+import { createRedisConnection } from '@esengine/database-drivers'
+
+const redis = createRedisConnection({
+    host: 'localhost',
+    port: 6379,
+    keyPrefix: 'game:',
+    autoReconnect: true
+})
+
+await redis.connect()
+
+// 基本操作
+await redis.set('session:123', 'data', 3600)  // 带 TTL
+const value = await redis.get('session:123')
+
+await redis.disconnect()
+```
+
+## 服务容器集成
+
+```typescript
+import { ServiceContainer } from '@esengine/ecs-framework'
+import {
+    createMongoConnection,
+    MongoConnectionToken,
+    RedisConnectionToken
+} from '@esengine/database-drivers'
+
+const services = new ServiceContainer()
+
+// 注册连接
+const mongo = createMongoConnection({ uri: '...', database: 'game' })
+await mongo.connect()
+services.register(MongoConnectionToken, mongo)
+
+// 在其他模块中获取
+const connection = services.get(MongoConnectionToken)
+const users = connection.collection('users')
+```
+
+## 文档
+
+- [MongoDB 连接](/modules/database-drivers/mongo/) - MongoDB 连接详细配置
+- [Redis 连接](/modules/database-drivers/redis/) - Redis 连接详细配置
+- [服务令牌](/modules/database-drivers/tokens/) - 依赖注入集成

docs/src/content/docs/modules/database-drivers/mongo.md

@@ -0,0 +1,265 @@
+---
+title: "MongoDB 连接"
+description: "MongoDB 连接管理、连接池、自动重连"
+---
+
+## 配置选项
+
+```typescript
+interface MongoConnectionConfig {
+    /** MongoDB 连接 URI */
+    uri: string
+
+    /** 数据库名称 */
+    database: string
+
+    /** 连接池配置 */
+    pool?: {
+        minSize?: number      // 最小连接数
+        maxSize?: number      // 最大连接数
+        acquireTimeout?: number  // 获取连接超时（毫秒）
+        maxLifetime?: number     // 连接最大生命周期（毫秒）
+    }
+
+    /** 是否自动重连（默认 true） */
+    autoReconnect?: boolean
+
+    /** 重连间隔（毫秒，默认 5000） */
+    reconnectInterval?: number
+
+    /** 最大重连次数（默认 10） */
+    maxReconnectAttempts?: number
+}
+```
+
+## 完整示例
+
+```typescript
+import { createMongoConnection, MongoConnectionToken } from '@esengine/database-drivers'
+
+const mongo = createMongoConnection({
+    uri: 'mongodb://localhost:27017',
+    database: 'game',
+    pool: {
+        minSize: 5,
+        maxSize: 20,
+        acquireTimeout: 5000,
+        maxLifetime: 300000
+    },
+    autoReconnect: true,
+    reconnectInterval: 5000,
+    maxReconnectAttempts: 10
+})
+
+// 事件监听
+mongo.on('connected', () => {
+    console.log('MongoDB 已连接')
+})
+
+mongo.on('disconnected', () => {
+    console.log('MongoDB 已断开')
+})
+
+mongo.on('reconnecting', () => {
+    console.log('MongoDB 正在重连...')
+})
+
+mongo.on('reconnected', () => {
+    console.log('MongoDB 重连成功')
+})
+
+mongo.on('error', (event) => {
+    console.error('MongoDB 错误:', event.error)
+})
+
+// 连接
+await mongo.connect()
+
+// 检查状态
+console.log('已连接:', mongo.isConnected())
+console.log('Ping:', await mongo.ping())
+```
+
+## IMongoConnection 接口
+
+```typescript
+interface IMongoConnection {
+    /** 连接 ID */
+    readonly id: string
+
+    /** 连接状态 */
+    readonly state: ConnectionState
+
+    /** 建立连接 */
+    connect(): Promise<void>
+
+    /** 断开连接 */
+    disconnect(): Promise<void>
+
+    /** 检查是否已连接 */
+    isConnected(): boolean
+
+    /** 测试连接 */
+    ping(): Promise<boolean>
+
+    /** 获取类型化集合 */
+    collection<T extends object>(name: string): IMongoCollection<T>
+
+    /** 获取数据库接口 */
+    getDatabase(): IMongoDatabase
+
+    /** 获取原生客户端（高级用法） */
+    getNativeClient(): MongoClientType
+
+    /** 获取原生数据库（高级用法） */
+    getNativeDatabase(): Db
+}
+```
+
+## IMongoCollection 接口
+
+类型安全的集合接口，与原生 MongoDB 类型解耦：
+
+```typescript
+interface IMongoCollection<T extends object> {
+    readonly name: string
+
+    // 查询
+    findOne(filter: object, options?: FindOptions): Promise<T | null>
+    find(filter: object, options?: FindOptions): Promise<T[]>
+    countDocuments(filter?: object): Promise<number>
+
+    // 插入
+    insertOne(doc: T): Promise<InsertOneResult>
+    insertMany(docs: T[]): Promise<InsertManyResult>
+
+    // 更新
+    updateOne(filter: object, update: object): Promise<UpdateResult>
+    updateMany(filter: object, update: object): Promise<UpdateResult>
+    findOneAndUpdate(
+        filter: object,
+        update: object,
+        options?: FindOneAndUpdateOptions
+    ): Promise<T | null>
+
+    // 删除
+    deleteOne(filter: object): Promise<DeleteResult>
+    deleteMany(filter: object): Promise<DeleteResult>
+
+    // 索引
+    createIndex(
+        spec: Record<string, 1 | -1>,
+        options?: IndexOptions
+    ): Promise<string>
+}
+```
+
+## 使用示例
+
+### 基本 CRUD
+
+```typescript
+interface User {
+    id: string
+    name: string
+    email: string
+    score: number
+}
+
+const users = mongo.collection<User>('users')
+
+// 插入
+await users.insertOne({
+    id: '1',
+    name: 'John',
+    email: 'john@example.com',
+    score: 100
+})
+
+// 查询
+const user = await users.findOne({ name: 'John' })
+
+const topUsers = await users.find(
+    { score: { $gte: 100 } },
+    { sort: { score: -1 }, limit: 10 }
+)
+
+// 更新
+await users.updateOne(
+    { id: '1' },
+    { $inc: { score: 10 } }
+)
+
+// 删除
+await users.deleteOne({ id: '1' })
+```
+
+### 批量操作
+
+```typescript
+// 批量插入
+await users.insertMany([
+    { id: '1', name: 'Alice', email: 'alice@example.com', score: 100 },
+    { id: '2', name: 'Bob', email: 'bob@example.com', score: 200 },
+    { id: '3', name: 'Carol', email: 'carol@example.com', score: 150 }
+])
+
+// 批量更新
+await users.updateMany(
+    { score: { $lt: 100 } },
+    { $set: { status: 'inactive' } }
+)
+
+// 批量删除
+await users.deleteMany({ status: 'inactive' })
+```
+
+### 索引管理
+
+```typescript
+// 创建索引
+await users.createIndex({ email: 1 }, { unique: true })
+await users.createIndex({ score: -1 })
+await users.createIndex({ name: 1, score: -1 })
+```
+
+## 与其他模块集成
+
+### 与 @esengine/database 集成
+
+```typescript
+import { createMongoConnection } from '@esengine/database-drivers'
+import { UserRepository, createRepository } from '@esengine/database'
+
+const mongo = createMongoConnection({
+    uri: 'mongodb://localhost:27017',
+    database: 'game'
+})
+await mongo.connect()
+
+// 使用 UserRepository
+const userRepo = new UserRepository(mongo)
+await userRepo.register({ username: 'john', password: '123456' })
+
+// 使用通用仓库
+const playerRepo = createRepository<Player>(mongo, 'players')
+```
+
+### 与 @esengine/transaction 集成
+
+```typescript
+import { createMongoConnection } from '@esengine/database-drivers'
+import { createMongoStorage, TransactionManager } from '@esengine/transaction'
+
+const mongo = createMongoConnection({
+    uri: 'mongodb://localhost:27017',
+    database: 'game'
+})
+await mongo.connect()
+
+// 创建事务存储（共享连接）
+const storage = createMongoStorage(mongo)
+await storage.ensureIndexes()
+
+const txManager = new TransactionManager({ storage })
+```

docs/src/content/docs/modules/database-drivers/redis.md

@@ -0,0 +1,228 @@
+---
+title: "Redis 连接"
+description: "Redis 连接管理、自动重连、键前缀"
+---
+
+## 配置选项
+
+```typescript
+interface RedisConnectionConfig {
+    /** Redis 主机 */
+    host?: string
+
+    /** Redis 端口 */
+    port?: number
+
+    /** 认证密码 */
+    password?: string
+
+    /** 数据库编号 */
+    db?: number
+
+    /** 键前缀 */
+    keyPrefix?: string
+
+    /** 是否自动重连（默认 true） */
+    autoReconnect?: boolean
+
+    /** 重连间隔（毫秒，默认 5000） */
+    reconnectInterval?: number
+
+    /** 最大重连次数（默认 10） */
+    maxReconnectAttempts?: number
+}
+```
+
+## 完整示例
+
+```typescript
+import { createRedisConnection, RedisConnectionToken } from '@esengine/database-drivers'
+
+const redis = createRedisConnection({
+    host: 'localhost',
+    port: 6379,
+    password: 'your-password',
+    db: 0,
+    keyPrefix: 'game:',
+    autoReconnect: true,
+    reconnectInterval: 5000,
+    maxReconnectAttempts: 10
+})
+
+// 事件监听
+redis.on('connected', () => {
+    console.log('Redis 已连接')
+})
+
+redis.on('disconnected', () => {
+    console.log('Redis 已断开')
+})
+
+redis.on('error', (event) => {
+    console.error('Redis 错误:', event.error)
+})
+
+// 连接
+await redis.connect()
+
+// 检查状态
+console.log('已连接:', redis.isConnected())
+console.log('Ping:', await redis.ping())
+```
+
+## IRedisConnection 接口
+
+```typescript
+interface IRedisConnection {
+    /** 连接 ID */
+    readonly id: string
+
+    /** 连接状态 */
+    readonly state: ConnectionState
+
+    /** 建立连接 */
+    connect(): Promise<void>
+
+    /** 断开连接 */
+    disconnect(): Promise<void>
+
+    /** 检查是否已连接 */
+    isConnected(): boolean
+
+    /** 测试连接 */
+    ping(): Promise<boolean>
+
+    /** 获取值 */
+    get(key: string): Promise<string | null>
+
+    /** 设置值（可选 TTL，单位秒） */
+    set(key: string, value: string, ttl?: number): Promise<void>
+
+    /** 删除键 */
+    del(key: string): Promise<boolean>
+
+    /** 检查键是否存在 */
+    exists(key: string): Promise<boolean>
+
+    /** 设置过期时间（秒） */
+    expire(key: string, seconds: number): Promise<boolean>
+
+    /** 获取剩余过期时间（秒） */
+    ttl(key: string): Promise<number>
+
+    /** 获取原生客户端（高级用法） */
+    getNativeClient(): Redis
+}
+```
+
+## 使用示例
+
+### 基本操作
+
+```typescript
+// 设置值
+await redis.set('user:1:name', 'John')
+
+// 设置带过期时间的值（1 小时）
+await redis.set('session:abc123', 'user-data', 3600)
+
+// 获取值
+const name = await redis.get('user:1:name')
+
+// 检查键是否存在
+const exists = await redis.exists('user:1:name')
+
+// 删除键
+await redis.del('user:1:name')
+
+// 获取剩余过期时间
+const ttl = await redis.ttl('session:abc123')
+```
+
+### 键前缀
+
+配置 `keyPrefix` 后，所有操作自动添加前缀：
+
+```typescript
+const redis = createRedisConnection({
+    host: 'localhost',
+    keyPrefix: 'game:'
+})
+
+// 实际操作的键是 'game:user:1'
+await redis.set('user:1', 'data')
+
+// 实际查询的键是 'game:user:1'
+const data = await redis.get('user:1')
+```
+
+### 高级操作
+
+使用原生客户端进行高级操作：
+
+```typescript
+const client = redis.getNativeClient()
+
+// 使用 Pipeline
+const pipeline = client.pipeline()
+pipeline.set('key1', 'value1')
+pipeline.set('key2', 'value2')
+pipeline.set('key3', 'value3')
+await pipeline.exec()
+
+// 使用事务
+const multi = client.multi()
+multi.incr('counter')
+multi.get('counter')
+const results = await multi.exec()
+
+// 使用 Lua 脚本
+const result = await client.eval(
+    `return redis.call('get', KEYS[1])`,
+    1,
+    'mykey'
+)
+```
+
+## 与事务系统集成
+
+```typescript
+import { createRedisConnection } from '@esengine/database-drivers'
+import { RedisStorage, TransactionManager } from '@esengine/transaction'
+
+const redis = createRedisConnection({
+    host: 'localhost',
+    port: 6379,
+    keyPrefix: 'tx:'
+})
+await redis.connect()
+
+// 创建事务存储
+const storage = new RedisStorage({
+    factory: () => redis.getNativeClient(),
+    prefix: 'tx:'
+})
+
+const txManager = new TransactionManager({ storage })
+```
+
+## 连接状态
+
+```typescript
+type ConnectionState =
+    | 'disconnected'  // 未连接
+    | 'connecting'    // 连接中
+    | 'connected'     // 已连接
+    | 'disconnecting' // 断开中
+    | 'error'         // 错误状态
+```
+
+## 事件
+
+| 事件 | 描述 |
+|------|------|
+| `connected` | 连接成功 |
+| `disconnected` | 连接断开 |
+| `reconnecting` | 正在重连 |
+| `reconnected` | 重连成功 |
+| `error` | 发生错误 |

docs/src/content/docs/modules/database/index.md

@@ -0,0 +1,140 @@
+---
+title: "数据库仓库"
+description: "Repository 模式的数据库操作层，支持 CRUD、分页、软删除"
+---
+
+`@esengine/database` 是 ESEngine 的数据库操作层，基于 Repository 模式提供类型安全的 CRUD 操作。
+
+## 特性
+
+- **Repository 模式** - 泛型 CRUD 操作，类型安全
+- **分页查询** - 内置分页支持
+- **软删除** - 可选的软删除与恢复
+- **用户管理** - 开箱即用的 UserRepository
+- **密码安全** - 使用 scrypt 的密码哈希工具
+
+## 安装
+
+```bash
+npm install @esengine/database @esengine/database-drivers
+```
+
+## 快速开始
+
+### 基本仓库
+
+```typescript
+import { createMongoConnection } from '@esengine/database-drivers'
+import { Repository, createRepository } from '@esengine/database'
+
+// 定义实体
+interface Player {
+    id: string
+    name: string
+    score: number
+    createdAt: Date
+    updatedAt: Date
+}
+
+// 创建连接
+const mongo = createMongoConnection({
+    uri: 'mongodb://localhost:27017',
+    database: 'game'
+})
+await mongo.connect()
+
+// 创建仓库
+const playerRepo = createRepository<Player>(mongo, 'players')
+
+// CRUD 操作
+const player = await playerRepo.create({
+    name: 'John',
+    score: 0
+})
+
+const found = await playerRepo.findById(player.id)
+
+await playerRepo.update(player.id, { score: 100 })
+
+await playerRepo.delete(player.id)
+```
+
+### 自定义仓库
+
+```typescript
+import { Repository, BaseEntity } from '@esengine/database'
+import type { IMongoConnection } from '@esengine/database-drivers'
+
+interface Player extends BaseEntity {
+    name: string
+    score: number
+    rank?: string
+}
+
+class PlayerRepository extends Repository<Player> {
+    constructor(connection: IMongoConnection) {
+        super(connection, 'players')
+    }
+
+    async findTopPlayers(limit: number = 10): Promise<Player[]> {
+        return this.findMany({
+            sort: { score: 'desc' },
+            limit
+        })
+    }
+
+    async findByRank(rank: string): Promise<Player[]> {
+        return this.findMany({
+            where: { rank }
+        })
+    }
+
+    async incrementScore(playerId: string, amount: number): Promise<Player | null> {
+        const player = await this.findById(playerId)
+        if (!player) return null
+        return this.update(playerId, { score: player.score + amount })
+    }
+}
+
+// 使用
+const playerRepo = new PlayerRepository(mongo)
+const topPlayers = await playerRepo.findTopPlayers(5)
+```
+
+### 用户仓库
+
+```typescript
+import { UserRepository } from '@esengine/database'
+
+const userRepo = new UserRepository(mongo)
+
+// 注册新用户
+const user = await userRepo.register({
+    username: 'john',
+    password: 'securePassword123',
+    email: 'john@example.com'
+})
+
+// 认证
+const authenticated = await userRepo.authenticate('john', 'securePassword123')
+if (authenticated) {
+    console.log('登录成功:', authenticated.username)
+}
+
+// 修改密码
+await userRepo.changePassword(user.id, 'securePassword123', 'newPassword456')
+
+// 角色管理
+await userRepo.addRole(user.id, 'admin')
+await userRepo.removeRole(user.id, 'admin')
+
+// 查询用户
+const admins = await userRepo.findByRole('admin')
+const john = await userRepo.findByUsername('john')
+```
+
+## 文档
+
+- [仓库 API](/modules/database/repository/) - Repository 详细 API
+- [用户管理](/modules/database/user/) - UserRepository 用法
+- [查询语法](/modules/database/query/) - 查询条件语法

docs/src/content/docs/modules/database/query.md

@@ -0,0 +1,185 @@
+---
+title: "查询语法"
+description: "查询条件操作符和语法"
+---
+
+## 基本查询
+
+### 精确匹配
+
+```typescript
+await repo.findMany({
+    where: {
+        name: 'John',
+        status: 'active'
+    }
+})
+```
+
+### 使用操作符
+
+```typescript
+await repo.findMany({
+    where: {
+        score: { $gte: 100 },
+        rank: { $in: ['gold', 'platinum'] }
+    }
+})
+```
+
+## 查询操作符
+
+| 操作符 | 描述 | 示例 |
+|--------|------|------|
+| `$eq` | 等于 | `{ score: { $eq: 100 } }` |
+| `$ne` | 不等于 | `{ status: { $ne: 'banned' } }` |
+| `$gt` | 大于 | `{ score: { $gt: 50 } }` |
+| `$gte` | 大于等于 | `{ level: { $gte: 10 } }` |
+| `$lt` | 小于 | `{ age: { $lt: 18 } }` |
+| `$lte` | 小于等于 | `{ price: { $lte: 100 } }` |
+| `$in` | 在数组中 | `{ rank: { $in: ['gold', 'platinum'] } }` |
+| `$nin` | 不在数组中 | `{ status: { $nin: ['banned', 'suspended'] } }` |
+| `$like` | 模式匹配 | `{ name: { $like: '%john%' } }` |
+| `$regex` | 正则匹配 | `{ email: { $regex: '@gmail.com$' } }` |
+
+## 逻辑操作符
+
+### $or
+
+```typescript
+await repo.findMany({
+    where: {
+        $or: [
+            { score: { $gte: 1000 } },
+            { rank: 'legendary' }
+        ]
+    }
+})
+```
+
+### $and
+
+```typescript
+await repo.findMany({
+    where: {
+        $and: [
+            { score: { $gte: 100 } },
+            { score: { $lte: 500 } }
+        ]
+    }
+})
+```
+
+### 组合使用
+
+```typescript
+await repo.findMany({
+    where: {
+        status: 'active',
+        $or: [
+            { rank: 'gold' },
+            { score: { $gte: 1000 } }
+        ]
+    }
+})
+```
+
+## 模式匹配
+
+### $like 语法
+
+- `%` - 匹配任意字符序列
+- `_` - 匹配单个字符
+
+```typescript
+// 以 'John' 开头
+{ name: { $like: 'John%' } }
+
+// 以 'son' 结尾
+{ name: { $like: '%son' } }
+
+// 包含 'oh'
+{ name: { $like: '%oh%' } }
+
+// 第二个字符是 'o'
+{ name: { $like: '_o%' } }
+```
+
+### $regex 语法
+
+使用标准正则表达式：
+
+```typescript
+// 以 'John' 开头（大小写不敏感）
+{ name: { $regex: '^john' } }
+
+// Gmail 邮箱
+{ email: { $regex: '@gmail\\.com$' } }
+
+// 包含数字
+{ username: { $regex: '\\d+' } }
+```
+
+## 排序
+
+```typescript
+await repo.findMany({
+    sort: {
+        score: 'desc',  // 降序
+        name: 'asc'     // 升序
+    }
+})
+```
+
+## 分页
+
+### 使用 limit/offset
+
+```typescript
+// 第一页
+await repo.findMany({
+    limit: 20,
+    offset: 0
+})
+
+// 第二页
+await repo.findMany({
+    limit: 20,
+    offset: 20
+})
+```
+
+### 使用 findPaginated
+
+```typescript
+const result = await repo.findPaginated(
+    { page: 2, pageSize: 20 },
+    { sort: { createdAt: 'desc' } }
+)
+```
+
+## 完整示例
+
+```typescript
+// 查找活跃的金牌玩家，分数在 100-1000 之间
+// 按分数降序排列，取前 10 个
+const players = await repo.findMany({
+    where: {
+        status: 'active',
+        rank: 'gold',
+        score: { $gte: 100, $lte: 1000 }
+    },
+    sort: { score: 'desc' },
+    limit: 10
+})
+
+// 搜索用户名包含 'john' 或邮箱是 gmail 的用户
+const users = await repo.findMany({
+    where: {
+        $or: [
+            { username: { $like: '%john%' } },
+            { email: { $regex: '@gmail\\.com$' } }
+        ]
+    }
+})
+```

docs/src/content/docs/modules/database/repository.md

@@ -0,0 +1,244 @@
+---
+title: "Repository API"
+description: "泛型仓库接口，CRUD 操作、分页、软删除"
+---
+
+## 创建仓库
+
+### 使用工厂函数
+
+```typescript
+import { createRepository } from '@esengine/database'
+
+const playerRepo = createRepository<Player>(mongo, 'players')
+
+// 启用软删除
+const playerRepo = createRepository<Player>(mongo, 'players', true)
+```
+
+### 继承 Repository
+
+```typescript
+import { Repository, BaseEntity } from '@esengine/database'
+
+interface Player extends BaseEntity {
+    name: string
+    score: number
+}
+
+class PlayerRepository extends Repository<Player> {
+    constructor(connection: IMongoConnection) {
+        super(connection, 'players', false)  // 第三个参数：启用软删除
+    }
+
+    // 添加自定义方法
+    async findTopPlayers(limit: number): Promise<Player[]> {
+        return this.findMany({
+            sort: { score: 'desc' },
+            limit
+        })
+    }
+}
+```
+
+## BaseEntity 接口
+
+所有实体必须继承 `BaseEntity`：
+
+```typescript
+interface BaseEntity {
+    id: string
+    createdAt: Date
+    updatedAt: Date
+    deletedAt?: Date  // 软删除时使用
+}
+```
+
+## 查询方法
+
+### findById
+
+```typescript
+const player = await repo.findById('player-123')
+```
+
+### findOne
+
+```typescript
+const player = await repo.findOne({
+    where: { name: 'John' }
+})
+
+const topPlayer = await repo.findOne({
+    sort: { score: 'desc' }
+})
+```
+
+### findMany
+
+```typescript
+// 简单查询
+const players = await repo.findMany({
+    where: { rank: 'gold' }
+})
+
+// 复杂查询
+const players = await repo.findMany({
+    where: {
+        score: { $gte: 100 },
+        rank: { $in: ['gold', 'platinum'] }
+    },
+    sort: { score: 'desc', name: 'asc' },
+    limit: 10,
+    offset: 0
+})
+```
+
+### findPaginated
+
+```typescript
+const result = await repo.findPaginated(
+    { page: 1, pageSize: 20 },
+    {
+        where: { rank: 'gold' },
+        sort: { score: 'desc' }
+    }
+)
+
+console.log(result.data)        // Player[]
+console.log(result.total)       // 总数量
+console.log(result.totalPages)  // 总页数
+console.log(result.hasNext)     // 是否有下一页
+console.log(result.hasPrev)     // 是否有上一页
+```
+
+### count
+
+```typescript
+const count = await repo.count({
+    where: { rank: 'gold' }
+})
+```
+
+### exists
+
+```typescript
+const exists = await repo.exists({
+    where: { email: 'john@example.com' }
+})
+```
+
+## 创建方法
+
+### create
+
+```typescript
+const player = await repo.create({
+    name: 'John',
+    score: 0
+})
+// 自动生成 id, createdAt, updatedAt
+```
+
+### createMany
+
+```typescript
+const players = await repo.createMany([
+    { name: 'Alice', score: 100 },
+    { name: 'Bob', score: 200 },
+    { name: 'Carol', score: 150 }
+])
+```
+
+## 更新方法
+
+### update
+
+```typescript
+const updated = await repo.update('player-123', {
+    score: 200,
+    rank: 'gold'
+})
+// 自动更新 updatedAt
+```
+
+## 删除方法
+
+### delete
+
+```typescript
+// 普通删除
+await repo.delete('player-123')
+
+// 软删除（如果启用）
+// 实际是设置 deletedAt 字段
+```
+
+### deleteMany
+
+```typescript
+const count = await repo.deleteMany({
+    where: { score: { $lt: 10 } }
+})
+```
+
+## 软删除
+
+### 启用软删除
+
+```typescript
+const repo = createRepository<Player>(mongo, 'players', true)
+```
+
+### 查询行为
+
+```typescript
+// 默认排除软删除记录
+const players = await repo.findMany()
+
+// 包含软删除记录
+const allPlayers = await repo.findMany({
+    includeSoftDeleted: true
+})
+```
+
+### 恢复记录
+
+```typescript
+await repo.restore('player-123')
+```
+
+## QueryOptions
+
+```typescript
+interface QueryOptions<T> {
+    /** 查询条件 */
+    where?: WhereCondition<T>
+
+    /** 排序 */
+    sort?: Partial<Record<keyof T, 'asc' | 'desc'>>
+
+    /** 限制数量 */
+    limit?: number
+
+    /** 偏移量 */
+    offset?: number
+
+    /** 包含软删除记录（仅在启用软删除时有效） */
+    includeSoftDeleted?: boolean
+}
+```
+
+## PaginatedResult
+
+```typescript
+interface PaginatedResult<T> {
+    data: T[]
+    total: number
+    page: number
+    pageSize: number
+    totalPages: number
+    hasNext: boolean
+    hasPrev: boolean
+}
+```

docs/src/content/docs/modules/database/user.md

@@ -0,0 +1,277 @@
+---
+title: "用户管理"
+description: "UserRepository 用户注册、认证、角色管理"
+---
+
+## 概述
+
+`UserRepository` 提供开箱即用的用户管理功能：
+
+- 用户注册与认证
+- 密码哈希（使用 scrypt）
+- 角色管理
+- 账户状态管理
+
+## 快速开始
+
+```typescript
+import { createMongoConnection } from '@esengine/database-drivers'
+import { UserRepository } from '@esengine/database'
+
+const mongo = createMongoConnection({
+    uri: 'mongodb://localhost:27017',
+    database: 'game'
+})
+await mongo.connect()
+
+const userRepo = new UserRepository(mongo)
+```
+
+## 用户注册
+
+```typescript
+const user = await userRepo.register({
+    username: 'john',
+    password: 'securePassword123',
+    email: 'john@example.com',      // 可选
+    displayName: 'John Doe',         // 可选
+    roles: ['player']                // 可选，默认 []
+})
+
+console.log(user)
+// {
+//   id: 'uuid-...',
+//   username: 'john',
+//   email: 'john@example.com',
+//   displayName: 'John Doe',
+//   roles: ['player'],
+//   status: 'active',
+//   createdAt: Date,
+//   updatedAt: Date
+// }
+```
+
+**注意**：`register` 返回的 `SafeUser` 不包含密码哈希。
+
+## 用户认证
+
+```typescript
+const user = await userRepo.authenticate('john', 'securePassword123')
+
+if (user) {
+    console.log('登录成功:', user.username)
+} else {
+    console.log('用户名或密码错误')
+}
+```
+
+## 密码管理
+
+### 修改密码
+
+```typescript
+const success = await userRepo.changePassword(
+    userId,
+    'oldPassword123',
+    'newPassword456'
+)
+
+if (success) {
+    console.log('密码修改成功')
+} else {
+    console.log('原密码错误')
+}
+```
+
+### 重置密码
+
+```typescript
+// 管理员直接重置密码
+const success = await userRepo.resetPassword(userId, 'newPassword123')
+```
+
+## 角色管理
+
+### 添加角色
+
+```typescript
+await userRepo.addRole(userId, 'admin')
+await userRepo.addRole(userId, 'moderator')
+```
+
+### 移除角色
+
+```typescript
+await userRepo.removeRole(userId, 'moderator')
+```
+
+### 查询角色
+
+```typescript
+// 查找所有管理员
+const admins = await userRepo.findByRole('admin')
+
+// 检查用户是否有某角色
+const user = await userRepo.findById(userId)
+const isAdmin = user?.roles.includes('admin')
+```
+
+## 查询用户
+
+### 按用户名查找
+
+```typescript
+const user = await userRepo.findByUsername('john')
+```
+
+### 按邮箱查找
+
+```typescript
+const user = await userRepo.findByEmail('john@example.com')
+```
+
+### 按角色查找
+
+```typescript
+const admins = await userRepo.findByRole('admin')
+```
+
+### 使用继承的方法
+
+```typescript
+// 分页查询
+const result = await userRepo.findPaginated(
+    { page: 1, pageSize: 20 },
+    {
+        where: { status: 'active' },
+        sort: { createdAt: 'desc' }
+    }
+)
+
+// 复杂查询
+const users = await userRepo.findMany({
+    where: {
+        status: 'active',
+        roles: { $in: ['admin', 'moderator'] }
+    }
+})
+```
+
+## 账户状态
+
+```typescript
+type UserStatus = 'active' | 'inactive' | 'banned' | 'suspended'
+```
+
+### 更新状态
+
+```typescript
+await userRepo.update(userId, { status: 'banned' })
+```
+
+### 查询特定状态
+
+```typescript
+const activeUsers = await userRepo.findMany({
+    where: { status: 'active' }
+})
+
+const bannedUsers = await userRepo.findMany({
+    where: { status: 'banned' }
+})
+```
+
+## 类型定义
+
+### UserEntity
+
+```typescript
+interface UserEntity extends BaseEntity {
+    username: string
+    passwordHash: string
+    email?: string
+    displayName?: string
+    roles: string[]
+    status: UserStatus
+    lastLoginAt?: Date
+}
+```
+
+### SafeUser
+
+```typescript
+type SafeUser = Omit<UserEntity, 'passwordHash'>
+```
+
+### CreateUserParams
+
+```typescript
+interface CreateUserParams {
+    username: string
+    password: string
+    email?: string
+    displayName?: string
+    roles?: string[]
+}
+```
+
+## 密码工具
+
+独立的密码工具函数：
+
+```typescript
+import { hashPassword, verifyPassword } from '@esengine/database'
+
+// 哈希密码
+const hash = await hashPassword('myPassword123')
+
+// 验证密码
+const isValid = await verifyPassword('myPassword123', hash)
+```
+
+### 安全说明
+
+- 使用 Node.js 内置的 `scrypt` 算法
+- 自动生成随机盐值
+- 默认使用安全的迭代参数
+- 哈希格式：`salt:hash`（均为 hex 编码）
+
+## 扩展 UserRepository
+
+```typescript
+import { UserRepository, UserEntity } from '@esengine/database'
+
+interface GameUser extends UserEntity {
+    level: number
+    experience: number
+    coins: number
+}
+
+class GameUserRepository extends UserRepository {
+    // 重写集合名
+    constructor(connection: IMongoConnection) {
+        super(connection, 'game_users')
+    }
+
+    // 添加游戏相关方法
+    async addExperience(userId: string, amount: number): Promise<GameUser | null> {
+        const user = await this.findById(userId) as GameUser | null
+        if (!user) return null
+
+        const newExp = user.experience + amount
+        const newLevel = Math.floor(newExp / 1000) + 1
+
+        return this.update(userId, {
+            experience: newExp,
+            level: newLevel
+        }) as Promise<GameUser | null>
+    }
+
+    async findTopPlayers(limit: number = 10): Promise<GameUser[]> {
+        return this.findMany({
+            sort: { level: 'desc', experience: 'desc' },
+            limit
+        }) as Promise<GameUser[]>
+    }
+}
+```

docs/src/content/docs/modules/index.md

@@ -37,6 +37,13 @@ ESEngine 提供了丰富的功能模块，可以按需引入到你的项目中
 | [网络同步](/modules/network/) | `@esengine/network` | 多人游戏网络同步 |
 | [事务系统](/modules/transaction/) | `@esengine/transaction` | 游戏事务处理，支持分布式事务 |
 
+### 数据库模块
+
+| 模块 | 包名 | 描述 |
+|------|------|------|
+| [数据库驱动](/modules/database-drivers/) | `@esengine/database-drivers` | MongoDB、Redis 连接管理 |
+| [数据库仓库](/modules/database/) | `@esengine/database` | Repository 模式数据操作 |
+
 ## 安装
 
 所有模块都可以独立安装：

docs/src/content/docs/modules/network/auth.md

@@ -92,6 +92,355 @@ const token = jwtProvider.sign({
 const payload = jwtProvider.decode(token)
 ```
 
+### 自定义提供者
+
+你可以通过实现 `IAuthProvider` 接口来创建自定义认证提供者，以集成任何认证系统（如 OAuth、LDAP、自定义数据库认证等）。
+
+#### IAuthProvider 接口
+
+```typescript
+interface IAuthProvider<TUser = unknown, TCredentials = unknown> {
+    /** 提供者名称 */
+    readonly name: string;
+
+    /** 验证凭证 */
+    verify(credentials: TCredentials): Promise<AuthResult<TUser>>;
+
+    /** 刷新令牌（可选） */
+    refresh?(token: string): Promise<AuthResult<TUser>>;
+
+    /** 撤销令牌（可选） */
+    revoke?(token: string): Promise<boolean>;
+}
+
+interface AuthResult<TUser> {
+    success: boolean;
+    user?: TUser;
+    error?: string;
+    errorCode?: AuthErrorCode;
+    token?: string;
+    expiresAt?: number;
+}
+
+type AuthErrorCode =
+    | 'INVALID_CREDENTIALS'
+    | 'EXPIRED_TOKEN'
+    | 'INVALID_TOKEN'
+    | 'USER_NOT_FOUND'
+    | 'ACCOUNT_DISABLED'
+    | 'RATE_LIMITED'
+    | 'INSUFFICIENT_PERMISSIONS';
+```
+
+#### 自定义提供者示例
+
+**示例 1：数据库密码认证**
+
+```typescript
+import type { IAuthProvider, AuthResult } from '@esengine/server/auth'
+
+interface User {
+    id: string
+    username: string
+    roles: string[]
+}
+
+interface PasswordCredentials {
+    username: string
+    password: string
+}
+
+class DatabaseAuthProvider implements IAuthProvider<User, PasswordCredentials> {
+    readonly name = 'database'
+
+    async verify(credentials: PasswordCredentials): Promise<AuthResult<User>> {
+        const { username, password } = credentials
+
+        // 从数据库查询用户
+        const user = await db.users.findByUsername(username)
+        if (!user) {
+            return {
+                success: false,
+                error: '用户不存在',
+                errorCode: 'USER_NOT_FOUND'
+            }
+        }
+
+        // 验证密码（使用 bcrypt 等库）
+        const isValid = await bcrypt.compare(password, user.passwordHash)
+        if (!isValid) {
+            return {
+                success: false,
+                error: '密码错误',
+                errorCode: 'INVALID_CREDENTIALS'
+            }
+        }
+
+        // 检查账号状态
+        if (user.disabled) {
+            return {
+                success: false,
+                error: '账号已禁用',
+                errorCode: 'ACCOUNT_DISABLED'
+            }
+        }
+
+        return {
+            success: true,
+            user: {
+                id: user.id,
+                username: user.username,
+                roles: user.roles
+            }
+        }
+    }
+}
+```
+
+**示例 2：OAuth/第三方认证**
+
+```typescript
+import type { IAuthProvider, AuthResult } from '@esengine/server/auth'
+
+interface OAuthUser {
+    id: string
+    email: string
+    name: string
+    provider: string
+    roles: string[]
+}
+
+interface OAuthCredentials {
+    provider: 'google' | 'github' | 'discord'
+    accessToken: string
+}
+
+class OAuthProvider implements IAuthProvider<OAuthUser, OAuthCredentials> {
+    readonly name = 'oauth'
+
+    async verify(credentials: OAuthCredentials): Promise<AuthResult<OAuthUser>> {
+        const { provider, accessToken } = credentials
+
+        try {
+            // 根据提供商验证 token
+            const profile = await this.fetchUserProfile(provider, accessToken)
+
+            // 查找或创建本地用户
+            let user = await db.users.findByOAuth(provider, profile.id)
+            if (!user) {
+                user = await db.users.create({
+                    oauthProvider: provider,
+                    oauthId: profile.id,
+                    email: profile.email,
+                    name: profile.name,
+                    roles: ['player']
+                })
+            }
+
+            return {
+                success: true,
+                user: {
+                    id: user.id,
+                    email: user.email,
+                    name: user.name,
+                    provider,
+                    roles: user.roles
+                }
+            }
+        } catch (error) {
+            return {
+                success: false,
+                error: 'OAuth 验证失败',
+                errorCode: 'INVALID_TOKEN'
+            }
+        }
+    }
+
+    private async fetchUserProfile(provider: string, token: string) {
+        switch (provider) {
+            case 'google':
+                return fetch('https://www.googleapis.com/oauth2/v2/userinfo', {
+                    headers: { Authorization: `Bearer ${token}` }
+                }).then(r => r.json())
+            case 'github':
+                return fetch('https://api.github.com/user', {
+                    headers: { Authorization: `Bearer ${token}` }
+                }).then(r => r.json())
+            // 其他提供商...
+            default:
+                throw new Error(`不支持的提供商: ${provider}`)
+        }
+    }
+}
+```
+
+**示例 3：API Key 认证**
+
+```typescript
+import type { IAuthProvider, AuthResult } from '@esengine/server/auth'
+
+interface ApiUser {
+    id: string
+    name: string
+    roles: string[]
+    rateLimit: number
+}
+
+class ApiKeyAuthProvider implements IAuthProvider<ApiUser, string> {
+    readonly name = 'api-key'
+
+    private revokedKeys = new Set<string>()
+
+    async verify(apiKey: string): Promise<AuthResult<ApiUser>> {
+        if (!apiKey || !apiKey.startsWith('sk_')) {
+            return {
+                success: false,
+                error: 'API Key 格式无效',
+                errorCode: 'INVALID_TOKEN'
+            }
+        }
+
+        if (this.revokedKeys.has(apiKey)) {
+            return {
+                success: false,
+                error: 'API Key 已被撤销',
+                errorCode: 'INVALID_TOKEN'
+            }
+        }
+
+        // 从数据库查询 API Key
+        const keyData = await db.apiKeys.findByKey(apiKey)
+        if (!keyData) {
+            return {
+                success: false,
+                error: 'API Key 不存在',
+                errorCode: 'INVALID_CREDENTIALS'
+            }
+        }
+
+        // 检查过期
+        if (keyData.expiresAt && keyData.expiresAt < Date.now()) {
+            return {
+                success: false,
+                error: 'API Key 已过期',
+                errorCode: 'EXPIRED_TOKEN'
+            }
+        }
+
+        return {
+            success: true,
+            user: {
+                id: keyData.userId,
+                name: keyData.name,
+                roles: keyData.roles,
+                rateLimit: keyData.rateLimit
+            },
+            expiresAt: keyData.expiresAt
+        }
+    }
+
+    async revoke(apiKey: string): Promise<boolean> {
+        this.revokedKeys.add(apiKey)
+        await db.apiKeys.revoke(apiKey)
+        return true
+    }
+}
+```
+
+#### 使用自定义提供者
+
+```typescript
+import { createServer } from '@esengine/server'
+import { withAuth } from '@esengine/server/auth'
+
+// 创建自定义提供者
+const dbAuthProvider = new DatabaseAuthProvider()
+
+// 或使用 OAuth 提供者
+const oauthProvider = new OAuthProvider()
+
+// 使用自定义提供者
+const server = withAuth(await createServer({ port: 3000 }), {
+    provider: dbAuthProvider, // 或 oauthProvider
+
+    // 从 WebSocket 连接请求中提取凭证
+    extractCredentials: (req) => {
+        const url = new URL(req.url, 'http://localhost')
+
+        // 对于数据库认证：从查询参数获取
+        const username = url.searchParams.get('username')
+        const password = url.searchParams.get('password')
+        if (username && password) {
+            return { username, password }
+        }
+
+        // 对于 OAuth：从 token 参数获取
+        const provider = url.searchParams.get('provider')
+        const accessToken = url.searchParams.get('access_token')
+        if (provider && accessToken) {
+            return { provider, accessToken }
+        }
+
+        // 对于 API Key：从请求头获取
+        const apiKey = req.headers['x-api-key']
+        if (apiKey) {
+            return apiKey as string
+        }
+
+        return null
+    },
+
+    onAuthFailure: (conn, error) => {
+        console.log(`认证失败: ${error.errorCode} - ${error.error}`)
+    }
+})
+
+await server.start()
+```
+
+#### 组合多个提供者
+
+你可以创建一个复合提供者来支持多种认证方式：
+
+```typescript
+import type { IAuthProvider, AuthResult } from '@esengine/server/auth'
+
+interface MultiAuthCredentials {
+    type: 'jwt' | 'oauth' | 'apikey' | 'password'
+    data: unknown
+}
+
+class MultiAuthProvider implements IAuthProvider<User, MultiAuthCredentials> {
+    readonly name = 'multi'
+
+    constructor(
+        private jwtProvider: JwtAuthProvider<User>,
+        private oauthProvider: OAuthProvider,
+        private apiKeyProvider: ApiKeyAuthProvider,
+        private dbProvider: DatabaseAuthProvider
+    ) {}
+
+    async verify(credentials: MultiAuthCredentials): Promise<AuthResult<User>> {
+        switch (credentials.type) {
+            case 'jwt':
+                return this.jwtProvider.verify(credentials.data as string)
+            case 'oauth':
+                return this.oauthProvider.verify(credentials.data as OAuthCredentials)
+            case 'apikey':
+                return this.apiKeyProvider.verify(credentials.data as string)
+            case 'password':
+                return this.dbProvider.verify(credentials.data as PasswordCredentials)
+            default:
+                return {
+                    success: false,
+                    error: '不支持的认证类型',
+                    errorCode: 'INVALID_CREDENTIALS'
+                }
+        }
+    }
+}
+```
+
 ### Session 提供者
 
 使用服务端会话实现有状态认证：

docs/src/content/docs/modules/network/http.md

@@ -0,0 +1,679 @@
+---
+title: "HTTP 路由"
+description: "HTTP REST API 路由功能，支持与 WebSocket 共用端口"
+---
+
+`@esengine/server` 内置了轻量级的 HTTP 路由功能，可以与 WebSocket 服务共用同一端口，方便实现 REST API。
+
+## 快速开始
+
+### 内联路由定义
+
+最简单的方式是在创建服务器时直接定义 HTTP 路由：
+
+```typescript
+import { createServer } from '@esengine/server'
+
+const server = await createServer({
+    port: 3000,
+    http: {
+        '/api/health': (req, res) => {
+            res.json({ status: 'ok', time: Date.now() })
+        },
+        '/api/users': {
+            GET: (req, res) => {
+                res.json({ users: [] })
+            },
+            POST: async (req, res) => {
+                const body = req.body as { name: string }
+                res.status(201).json({ id: '1', name: body.name })
+            }
+        }
+    },
+    cors: true  // 启用 CORS
+})
+
+await server.start()
+```
+
+### 文件路由
+
+对于较大的项目，推荐使用文件路由。创建 `src/http` 目录，每个文件对应一个路由：
+
+```typescript
+// src/http/login.ts
+import { defineHttp } from '@esengine/server'
+
+interface LoginBody {
+    username: string
+    password: string
+}
+
+export default defineHttp<LoginBody>({
+    method: 'POST',
+    handler(req, res) {
+        const { username, password } = req.body as LoginBody
+
+        // 验证用户...
+        if (username === 'admin' && password === '123456') {
+            res.json({ token: 'jwt-token-here', userId: 'user-1' })
+        } else {
+            res.error(401, '用户名或密码错误')
+        }
+    }
+})
+```
+
+```typescript
+// server.ts
+import { createServer } from '@esengine/server'
+
+const server = await createServer({
+    port: 3000,
+    httpDir: './src/http',   // HTTP 路由目录
+    httpPrefix: '/api',       // 路由前缀
+    cors: true
+})
+
+await server.start()
+// 路由: POST /api/login
+```
+
+## defineHttp 定义
+
+`defineHttp` 用于定义类型安全的 HTTP 处理器：
+
+```typescript
+import { defineHttp } from '@esengine/server'
+
+interface CreateUserBody {
+    username: string
+    email: string
+    password: string
+}
+
+export default defineHttp<CreateUserBody>({
+    // HTTP 方法（默认 POST）
+    method: 'POST',
+
+    // 处理函数
+    handler(req, res) {
+        const body = req.body as CreateUserBody
+        // 处理请求...
+        res.status(201).json({ id: 'new-user-id' })
+    }
+})
+```
+
+### 支持的 HTTP 方法
+
+```typescript
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS'
+```
+
+## HttpRequest 对象
+
+HTTP 请求对象包含以下属性：
+
+```typescript
+interface HttpRequest {
+    /** 原始 Node.js IncomingMessage */
+    raw: IncomingMessage
+
+    /** HTTP 方法 */
+    method: string
+
+    /** 请求路径 */
+    path: string
+
+    /** 路由参数（从 URL 路径提取，如 /users/:id） */
+    params: Record<string, string>
+
+    /** 查询参数 */
+    query: Record<string, string>
+
+    /** 请求头 */
+    headers: Record<string, string | string[] | undefined>
+
+    /** 解析后的请求体 */
+    body: unknown
+
+    /** 客户端 IP */
+    ip: string
+}
+```
+
+### 使用示例
+
+```typescript
+export default defineHttp({
+    method: 'GET',
+    handler(req, res) {
+        // 获取查询参数
+        const page = parseInt(req.query.page ?? '1')
+        const limit = parseInt(req.query.limit ?? '10')
+
+        // 获取请求头
+        const authHeader = req.headers.authorization
+
+        // 获取客户端 IP
+        console.log('Request from:', req.ip)
+
+        res.json({ page, limit })
+    }
+})
+```
+
+### 请求体解析
+
+请求体会根据 `Content-Type` 自动解析：
+
+- `application/json` - 解析为 JSON 对象
+- `application/x-www-form-urlencoded` - 解析为键值对对象
+- 其他 - 保持原始字符串
+
+```typescript
+export default defineHttp<{ name: string; age: number }>({
+    method: 'POST',
+    handler(req, res) {
+        // body 已自动解析
+        const { name, age } = req.body as { name: string; age: number }
+        res.json({ received: { name, age } })
+    }
+})
+```
+
+## HttpResponse 对象
+
+HTTP 响应对象提供链式 API：
+
+```typescript
+interface HttpResponse {
+    /** 原始 Node.js ServerResponse */
+    raw: ServerResponse
+
+    /** 设置状态码 */
+    status(code: number): HttpResponse
+
+    /** 设置响应头 */
+    header(name: string, value: string): HttpResponse
+
+    /** 发送 JSON 响应 */
+    json(data: unknown): void
+
+    /** 发送文本响应 */
+    text(data: string): void
+
+    /** 发送错误响应 */
+    error(code: number, message: string): void
+}
+```
+
+### 使用示例
+
+```typescript
+export default defineHttp({
+    method: 'POST',
+    handler(req, res) {
+        // 设置状态码和自定义头
+        res
+            .status(201)
+            .header('X-Custom-Header', 'value')
+            .json({ created: true })
+    }
+})
+```
+
+```typescript
+export default defineHttp({
+    method: 'GET',
+    handler(req, res) {
+        // 发送错误响应
+        res.error(404, '资源不存在')
+        // 等价于: res.status(404).json({ error: '资源不存在' })
+    }
+})
+```
+
+```typescript
+export default defineHttp({
+    method: 'GET',
+    handler(req, res) {
+        // 发送纯文本
+        res.text('Hello, World!')
+    }
+})
+```
+
+## 文件路由规范
+
+### 命名转换
+
+文件名会自动转换为路由路径：
+
+| 文件路径 | 路由路径（prefix=/api） |
+|---------|----------------------|
+| `login.ts` | `/api/login` |
+| `users/profile.ts` | `/api/users/profile` |
+| `users/[id].ts` | `/api/users/:id` |
+| `game/room/[roomId].ts` | `/api/game/room/:roomId` |
+
+### 动态路由参数
+
+使用 `[param]` 语法定义动态参数：
+
+```typescript
+// src/http/users/[id].ts
+import { defineHttp } from '@esengine/server'
+
+export default defineHttp({
+    method: 'GET',
+    handler(req, res) {
+        // 直接从 params 获取路由参数
+        const { id } = req.params
+        res.json({ userId: id })
+    }
+})
+```
+
+多个参数的情况：
+
+```typescript
+// src/http/users/[userId]/posts/[postId].ts
+import { defineHttp } from '@esengine/server'
+
+export default defineHttp({
+    method: 'GET',
+    handler(req, res) {
+        const { userId, postId } = req.params
+        res.json({ userId, postId })
+    }
+})
+```
+
+### 跳过规则
+
+以下文件会被自动跳过：
+
+- 以 `_` 开头的文件（如 `_helper.ts`）
+- `index.ts` / `index.js` 文件
+- 非 `.ts` / `.js` / `.mts` / `.mjs` 文件
+
+### 目录结构示例
+
+```
+src/
+└── http/
+    ├── _utils.ts        # 跳过（下划线开头）
+    ├── index.ts         # 跳过（index 文件）
+    ├── health.ts        # GET /api/health
+    ├── login.ts         # POST /api/login
+    ├── register.ts      # POST /api/register
+    └── users/
+        ├── index.ts     # 跳过
+        ├── list.ts      # GET /api/users/list
+        └── [id].ts      # GET /api/users/:id
+```
+
+## CORS 配置
+
+### 快速启用
+
+```typescript
+const server = await createServer({
+    port: 3000,
+    cors: true  // 使用默认配置
+})
+```
+
+### 自定义配置
+
+```typescript
+const server = await createServer({
+    port: 3000,
+    cors: {
+        // 允许的来源
+        origin: ['http://localhost:5173', 'https://myapp.com'],
+        // 或使用通配符
+        // origin: '*',
+        // origin: true,  // 反射请求来源
+
+        // 允许的 HTTP 方法
+        methods: ['GET', 'POST', 'PUT', 'DELETE'],
+
+        // 允许的请求头
+        allowedHeaders: ['Content-Type', 'Authorization', 'X-Requested-With'],
+
+        // 是否允许携带凭证（cookies）
+        credentials: true,
+
+        // 预检请求缓存时间（秒）
+        maxAge: 86400
+    }
+})
+```
+
+### CorsOptions 类型
+
+```typescript
+interface CorsOptions {
+    /** 允许的来源：字符串、字符串数组、true（反射）或 '*' */
+    origin?: string | string[] | boolean
+
+    /** 允许的 HTTP 方法 */
+    methods?: string[]
+
+    /** 允许的请求头 */
+    allowedHeaders?: string[]
+
+    /** 是否允许携带凭证 */
+    credentials?: boolean
+
+    /** 预检请求缓存时间（秒） */
+    maxAge?: number
+}
+```
+
+## 路由合并
+
+文件路由和内联路由可以同时使用，内联路由优先级更高：
+
+```typescript
+const server = await createServer({
+    port: 3000,
+    httpDir: './src/http',
+    httpPrefix: '/api',
+
+    // 内联路由会与文件路由合并
+    http: {
+        '/health': (req, res) => res.json({ status: 'ok' }),
+        '/api/special': (req, res) => res.json({ special: true })
+    }
+})
+```
+
+## 与 WebSocket 共用端口
+
+HTTP 路由与 WebSocket 服务自动共用同一端口：
+
+```typescript
+const server = await createServer({
+    port: 3000,
+    // WebSocket 相关配置
+    apiDir: './src/api',
+    msgDir: './src/msg',
+
+    // HTTP 相关配置
+    httpDir: './src/http',
+    httpPrefix: '/api',
+    cors: true
+})
+
+await server.start()
+
+// 同一端口 3000：
+// - WebSocket: ws://localhost:3000
+// - HTTP API:  http://localhost:3000/api/*
+```
+
+## 完整示例
+
+### 游戏服务器登录 API
+
+```typescript
+// src/http/auth/login.ts
+import { defineHttp } from '@esengine/server'
+import { createJwtAuthProvider } from '@esengine/server/auth'
+
+interface LoginRequest {
+    username: string
+    password: string
+}
+
+interface LoginResponse {
+    token: string
+    userId: string
+    expiresAt: number
+}
+
+const jwtProvider = createJwtAuthProvider({
+    secret: process.env.JWT_SECRET!,
+    expiresIn: 3600
+})
+
+export default defineHttp<LoginRequest>({
+    method: 'POST',
+    async handler(req, res) {
+        const { username, password } = req.body as LoginRequest
+
+        // 验证用户
+        const user = await db.users.findByUsername(username)
+        if (!user || !await verifyPassword(password, user.passwordHash)) {
+            res.error(401, '用户名或密码错误')
+            return
+        }
+
+        // 生成 JWT
+        const token = jwtProvider.sign({
+            sub: user.id,
+            name: user.username,
+            roles: user.roles
+        })
+
+        const response: LoginResponse = {
+            token,
+            userId: user.id,
+            expiresAt: Date.now() + 3600 * 1000
+        }
+
+        res.json(response)
+    }
+})
+```
+
+### 游戏数据查询 API
+
+```typescript
+// src/http/game/leaderboard.ts
+import { defineHttp } from '@esengine/server'
+
+export default defineHttp({
+    method: 'GET',
+    async handler(req, res) {
+        const limit = parseInt(req.query.limit ?? '10')
+        const offset = parseInt(req.query.offset ?? '0')
+
+        const players = await db.players.findMany({
+            sort: { score: 'desc' },
+            limit,
+            offset
+        })
+
+        res.json({
+            data: players,
+            pagination: { limit, offset }
+        })
+    }
+})
+```
+
+## 中间件
+
+### 中间件类型
+
+中间件是在路由处理前后执行的函数：
+
+```typescript
+type HttpMiddleware = (
+    req: HttpRequest,
+    res: HttpResponse,
+    next: () => Promise<void>
+) => void | Promise<void>
+```
+
+### 内置中间件
+
+```typescript
+import {
+    requestLogger,
+    bodyLimit,
+    responseTime,
+    requestId,
+    securityHeaders
+} from '@esengine/server'
+
+const server = await createServer({
+    port: 3000,
+    http: { /* ... */ },
+    // 全局中间件通过 createHttpRouter 配置
+})
+```
+
+#### requestLogger - 请求日志
+
+```typescript
+import { requestLogger } from '@esengine/server'
+
+// 记录请求和响应时间
+requestLogger()
+
+// 同时记录请求体
+requestLogger({ logBody: true })
+```
+
+#### bodyLimit - 请求体大小限制
+
+```typescript
+import { bodyLimit } from '@esengine/server'
+
+// 限制请求体为 1MB
+bodyLimit(1024 * 1024)
+```
+
+#### responseTime - 响应时间头
+
+```typescript
+import { responseTime } from '@esengine/server'
+
+// 自动添加 X-Response-Time 响应头
+responseTime()
+```
+
+#### requestId - 请求 ID
+
+```typescript
+import { requestId } from '@esengine/server'
+
+// 自动生成并添加 X-Request-ID 响应头
+requestId()
+
+// 自定义头名称
+requestId('X-Trace-ID')
+```
+
+#### securityHeaders - 安全头
+
+```typescript
+import { securityHeaders } from '@esengine/server'
+
+// 添加常用安全响应头
+securityHeaders()
+
+// 自定义配置
+securityHeaders({
+    hidePoweredBy: true,
+    frameOptions: 'DENY',
+    noSniff: true
+})
+```
+
+### 自定义中间件
+
+```typescript
+import type { HttpMiddleware } from '@esengine/server'
+
+// 认证中间件
+const authMiddleware: HttpMiddleware = async (req, res, next) => {
+    const token = req.headers.authorization?.replace('Bearer ', '')
+
+    if (!token) {
+        res.error(401, 'Unauthorized')
+        return  // 不调用 next()，终止请求
+    }
+
+    // 验证 token...
+    (req as any).userId = 'decoded-user-id'
+
+    await next()  // 继续执行后续中间件和处理器
+}
+```
+
+### 使用中间件
+
+#### 使用 createHttpRouter
+
+```typescript
+import { createHttpRouter, requestLogger, bodyLimit } from '@esengine/server'
+
+const router = createHttpRouter({
+    '/api/users': (req, res) => res.json([]),
+    '/api/admin': {
+        GET: {
+            handler: (req, res) => res.json({ admin: true }),
+            middlewares: [adminAuthMiddleware]  // 路由级中间件
+        }
+    }
+}, {
+    middlewares: [requestLogger(), bodyLimit(1024 * 1024)],  // 全局中间件
+    timeout: 30000  // 全局超时 30 秒
+})
+```
+
+## 请求超时
+
+### 全局超时
+
+```typescript
+import { createHttpRouter } from '@esengine/server'
+
+const router = createHttpRouter({
+    '/api/data': async (req, res) => {
+        // 如果处理超过 30 秒，自动返回 408 Request Timeout
+        await someSlowOperation()
+        res.json({ data: 'result' })
+    }
+}, {
+    timeout: 30000  // 30 秒
+})
+```
+
+### 路由级超时
+
+```typescript
+const router = createHttpRouter({
+    '/api/quick': (req, res) => res.json({ fast: true }),
+
+    '/api/slow': {
+        POST: {
+            handler: async (req, res) => {
+                await verySlowOperation()
+                res.json({ done: true })
+            },
+            timeout: 120000  // 这个路由允许 2 分钟
+        }
+    }
+}, {
+    timeout: 10000  // 全局 10 秒（被路由级覆盖）
+})
+```
+
+## 最佳实践
+
+1. **使用 defineHttp** - 获得更好的类型提示和代码组织
+2. **统一错误处理** - 使用 `res.error()` 返回一致的错误格式
+3. **启用 CORS** - 前后端分离时必须配置
+4. **目录组织** - 按功能模块组织 HTTP 路由文件
+5. **验证输入** - 始终验证 `req.body` 和 `req.query` 的内容
+6. **状态码规范** - 遵循 HTTP 状态码规范（200、201、400、401、404、500 等）
+7. **使用中间件** - 通过中间件实现认证、日志、限流等横切关注点
+8. **设置超时** - 避免慢请求阻塞服务器

docs/src/content/docs/modules/network/server.md

@@ -79,10 +79,47 @@ await server.start()
 | `tickRate` | `number` | `20` | 全局 Tick 频率 (Hz) |
 | `apiDir` | `string` | `'src/api'` | API 处理器目录 |
 | `msgDir` | `string` | `'src/msg'` | 消息处理器目录 |
+| `httpDir` | `string` | `'src/http'` | HTTP 路由目录 |
+| `httpPrefix` | `string` | `'/api'` | HTTP 路由前缀 |
+| `cors` | `boolean \| CorsOptions` | - | CORS 配置 |
 | `onStart` | `(port) => void` | - | 启动回调 |
 | `onConnect` | `(conn) => void` | - | 连接回调 |
 | `onDisconnect` | `(conn) => void` | - | 断开回调 |
 
+## HTTP 路由
+
+支持 HTTP API 与 WebSocket 共用端口，适用于登录、注册等场景。
+
+```typescript
+const server = await createServer({
+    port: 3000,
+    httpDir: './src/http',   // HTTP 路由目录
+    httpPrefix: '/api',       // 路由前缀
+    cors: true,
+
+    // 或内联定义
+    http: {
+        '/health': (req, res) => res.json({ status: 'ok' })
+    }
+})
+```
+
+```typescript
+// src/http/login.ts
+import { defineHttp } from '@esengine/server'
+
+export default defineHttp<{ username: string; password: string }>({
+    method: 'POST',
+    handler(req, res) {
+        const { username, password } = req.body
+        // 验证并返回 token...
+        res.json({ token: '...' })
+    }
+})
+```
+
+> 详细文档请参考 [HTTP 路由](/modules/network/http)
+
 ## Room 系统
 
 Room 是游戏房间的基类，管理玩家和游戏状态。

docs/src/content/docs/modules/transaction/storage.md

@@ -125,23 +125,24 @@ tx:data:{key}           - 业务数据
 
 ## MongoStorage
 
-MongoDB 存储，适用于需要持久化和复杂查询的场景。使用工厂模式实现惰性连接。
+MongoDB 存储，适用于需要持久化和复杂查询的场景。使用 `@esengine/database-drivers` 的共享连接。
 
 ```typescript
-import { MongoClient } from 'mongodb';
-import { MongoStorage } from '@esengine/transaction';
+import { createMongoConnection } from '@esengine/database-drivers';
+import { createMongoStorage, TransactionManager } from '@esengine/transaction';
 
-// 工厂模式：惰性连接，首次操作时才创建连接
-const storage = new MongoStorage({
-    factory: async () => {
-        const client = new MongoClient('mongodb://localhost:27017');
-        await client.connect();
-        return client;
-    },
-    database: 'game',
-    transactionCollection: 'transactions',  // 事务日志集合
-    dataCollection: 'transaction_data',     // 业务数据集合
-    lockCollection: 'transaction_locks',    // 锁集合
+// 创建共享连接
+const mongo = createMongoConnection({
+    uri: 'mongodb://localhost:27017',
+    database: 'game'
+});
+await mongo.connect();
+
+// 使用共享连接创建存储
+const storage = createMongoStorage(mongo, {
+    transactionCollection: 'transactions',  // 事务日志集合（可选）
+    dataCollection: 'transaction_data',     // 业务数据集合（可选）
+    lockCollection: 'transaction_locks',    // 锁集合（可选）
 });
 
 // 创建索引（首次运行时执行）
@@ -149,11 +150,14 @@ await storage.ensureIndexes();
 
 const manager = new TransactionManager({ storage });
 
-// 使用后关闭连接
+// 关闭存储（不会关闭共享连接）
 await storage.close();
 
-// 或使用 await using 自动关闭 (TypeScript 5.2+)
-await using storage = new MongoStorage({ ... });
+// 共享连接可继续用于其他模块
+const userRepo = new UserRepository(mongo);  // @esengine/database
+
+// 最后关闭共享连接
+await mongo.disconnect();
 ```
 
 ### 特点

package.json

@@ -74,6 +74,7 @@
     "lint:fix": "turbo run lint:fix",
     "build:wasm": "cd packages/rust/engine && wasm-pack build --dev --out-dir pkg",
     "build:wasm:release": "cd packages/rust/engine && wasm-pack build --release --out-dir pkg",
+    "build:rapier2d": "node scripts/build-rapier2d.mjs",
     "copy-modules": "node scripts/copy-engine-modules.mjs"
   },
   "author": "yhh",

packages/editor/editor-app/README.md

@@ -8,12 +8,23 @@ Before running the editor, ensure you have the following installed:
 
 - **Node.js** >= 18.x
 - **pnpm** >= 10.x
-- **Rust** >= 1.70 (for Tauri)
+- **Rust** >= 1.70 (for Tauri and WASM builds)
+- **wasm-pack** (for building Rapier2D physics engine)
 - **Platform-specific dependencies**:
   - **Windows**: Microsoft Visual Studio C++ Build Tools
   - **macOS**: Xcode Command Line Tools (`xcode-select --install`)
   - **Linux**: See [Tauri prerequisites](https://tauri.app/v1/guides/getting-started/prerequisites)
 
+### Installing wasm-pack
+
+```bash
+# Using cargo
+cargo install wasm-pack
+
+# Or using the official installer script (Linux/macOS)
+curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
+```
+
 ## Quick Start
 
 ### 1. Clone and Install
@@ -24,7 +35,23 @@ cd esengine
 pnpm install
 ```
 
-### 2. Build Dependencies
+### 2. Build Rapier2D WASM
+
+The editor depends on Rapier2D physics engine WASM artifacts. First-time setup only requires one command:
+
+```bash
+pnpm build:rapier2d
+```
+
+This command automatically:
+1. Prepares the Rust project
+2. Builds WASM
+3. Copies artifacts to `packages/physics/rapier2d/pkg`
+4. Generates TypeScript source code
+
+> **Note**: Requires Rust and wasm-pack to be installed.
+
+### 3. Build Editor
 
 From the project root:
 
@@ -32,7 +59,7 @@ From the project root:
 pnpm build:editor
 ```
 
-### 3. Run Editor
+### 4. Run Editor
 
 ```bash
 cd packages/editor/editor-app
@@ -43,6 +70,8 @@ pnpm tauri:dev
 
 | Script | Description |
 |--------|-------------|
+| `pnpm build:rapier2d` | Build Rapier2D WASM (required for first-time setup) |
+| `pnpm build:editor` | Build editor and all dependencies |
 | `pnpm tauri:dev` | Run editor in development mode with hot-reload |
 | `pnpm tauri:build` | Build production application |
 | `pnpm build:sdk` | Build editor-runtime SDK |
@@ -62,6 +91,17 @@ editor-app/
 
 ## Troubleshooting
 
+### Rapier2D WASM Build Failed
+
+**Error**: `Could not resolve "../pkg/rapier_wasm2d"`
+
+**Cause**: Missing Rapier2D WASM artifacts.
+
+**Solution**:
+1. Ensure `wasm-pack` is installed: `cargo install wasm-pack`
+2. Run `pnpm build:rapier2d`
+3. Verify `packages/physics/rapier2d/pkg/` directory exists and contains `rapier_wasm2d_bg.wasm` file
+
 ### Build Errors
 
 ```bash
@@ -76,6 +116,12 @@ pnpm build:editor
 rustup update
 ```
 
+### Windows Users Building WASM
+
+The `pnpm build:rapier2d` script works directly on Windows. If you encounter issues:
+1. Use Git Bash or WSL
+2. Or download pre-built WASM artifacts from [Releases](https://github.com/esengine/esengine/releases)
+
 ## Documentation
 
 - [ESEngine Documentation](https://esengine.cn/)

packages/editor/editor-app/README_CN.md

@@ -8,12 +8,23 @@
 
 - **Node.js** >= 18.x
 - **pnpm** >= 10.x
-- **Rust** >= 1.70 (Tauri 需要)
+- **Rust** >= 1.70 (Tauri 和 WASM 构建需要)
+- **wasm-pack** (构建 Rapier2D 物理引擎需要)
 - **平台相关依赖**：
   - **Windows**: Microsoft Visual Studio C++ Build Tools
   - **macOS**: Xcode Command Line Tools (`xcode-select --install`)
   - **Linux**: 参考 [Tauri 环境配置](https://tauri.app/v1/guides/getting-started/prerequisites)
 
+### 安装 wasm-pack
+
+```bash
+# 使用 cargo 安装
+cargo install wasm-pack
+
+# 或使用官方安装脚本 (Linux/macOS)
+curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
+```
+
 ## 快速开始
 
 ### 1. 克隆并安装
@@ -24,7 +35,23 @@ cd esengine
 pnpm install
 ```
 
-### 2. 构建依赖
+### 2. 构建 Rapier2D WASM
+
+编辑器依赖 Rapier2D 物理引擎的 WASM 产物。首次构建只需执行一条命令：
+
+```bash
+pnpm build:rapier2d
+```
+
+该命令会自动完成以下步骤：
+1. 准备 Rust 项目
+2. 构建 WASM
+3. 复制产物到 `packages/physics/rapier2d/pkg`
+4. 生成 TypeScript 源码
+
+> **注意**：需要已安装 Rust 和 wasm-pack。
+
+### 3. 构建编辑器
 
 在项目根目录执行：
 
@@ -32,7 +59,7 @@ pnpm install
 pnpm build:editor
 ```
 
-### 3. 启动编辑器
+### 4. 启动编辑器
 
 ```bash
 cd packages/editor/editor-app
@@ -43,6 +70,8 @@ pnpm tauri:dev
 
 | 脚本 | 说明 |
 |------|------|
+| `pnpm build:rapier2d` | 构建 Rapier2D WASM（首次构建必须执行）|
+| `pnpm build:editor` | 构建编辑器及所有依赖 |
 | `pnpm tauri:dev` | 开发模式运行编辑器（支持热重载）|
 | `pnpm tauri:build` | 构建生产版本应用 |
 | `pnpm build:sdk` | 构建 editor-runtime SDK |
@@ -62,6 +91,17 @@ editor-app/
 
 ## 常见问题
 
+### Rapier2D WASM 构建失败
+
+**错误**: `Could not resolve "../pkg/rapier_wasm2d"`
+
+**原因**: 缺少 Rapier2D 的 WASM 产物。
+
+**解决方案**:
+1. 确保已安装 `wasm-pack`：`cargo install wasm-pack`
+2. 执行 `pnpm build:rapier2d`
+3. 确认 `packages/physics/rapier2d/pkg/` 目录存在且包含 `rapier_wasm2d_bg.wasm` 文件
+
 ### 构建错误
 
 ```bash
@@ -76,6 +116,12 @@ pnpm build:editor
 rustup update
 ```
 
+### Windows 用户构建 WASM
+
+`pnpm build:rapier2d` 脚本在 Windows 上可以直接运行。如果遇到问题：
+1. 使用 Git Bash 或 WSL
+2. 或从 [Releases](https://github.com/esengine/esengine/releases) 下载预编译的 WASM 产物
+
 ## 文档
 
 - [ESEngine 文档](https://esengine.cn/)

packages/editor/plugins/behavior-tree-editor/tsconfig.build.json

@@ -8,7 +8,10 @@
         "rootDir": "./src",
         "jsx": "react-jsx",
         "skipLibCheck": true,
-        "moduleResolution": "bundler"
+        "moduleResolution": "bundler",
+        "paths": {
+            "@esengine/asset-system": ["../../../engine/asset-system/src"]
+        }
     },
     "include": ["src/**/*"],
     "exclude": ["node_modules", "dist", "**/*.test.ts"]

packages/editor/plugins/behavior-tree-editor/tsup.config.ts

@@ -2,8 +2,7 @@ import { defineConfig } from 'tsup';
 import { editorOnlyPreset } from '../../../tools/build-config/src/presets/plugin-tsup';
 
 export default defineConfig({
-    ...editorOnlyPreset({
-        external: ['@esengine/asset-system']
-    }),
-    tsconfig: 'tsconfig.build.json'
+    ...editorOnlyPreset({}),
+    tsconfig: 'tsconfig.build.json',
+    noExternal: ['@esengine/asset-system']
 });

packages/framework/behavior-tree/CHANGELOG.md

@@ -1,5 +1,54 @@
 # @esengine/behavior-tree
 
+## 4.2.0
+
+### Minor Changes
+
+- [#408](https://github.com/esengine/esengine/pull/408) [`b9ea8d1`](https://github.com/esengine/esengine/commit/b9ea8d14cf38e1480f638c229f9ee150b65f0c60) Thanks [@esengine](https://github.com/esengine)! - feat: add action() and condition() methods to BehaviorTreeBuilder
+
+    Added new methods to support custom executor types directly in the builder:
+    - `action(implementationType, name?, config?)` - Use custom action executors registered via `@NodeExecutorMetadata`
+    - `condition(implementationType, name?, config?)` - Use custom condition executors
+
+    This provides a cleaner API for using custom node executors compared to the existing `executeAction()` which only supports blackboard functions.
+
+    Example:
+
+    ```typescript
+    // Define custom executor
+    @NodeExecutorMetadata({
+        implementationType: 'AttackAction',
+        nodeType: NodeType.Action,
+        displayName: 'Attack',
+        category: 'Combat'
+    })
+    class AttackAction implements INodeExecutor {
+        execute(context: NodeExecutionContext): TaskStatus {
+            return TaskStatus.Success;
+        }
+    }
+
+    // Use in builder
+    const tree = BehaviorTreeBuilder.create('AI')
+        .selector('Root')
+        .action('AttackAction', 'Attack', { damage: 50 })
+        .end()
+        .build();
+    ```
+
+## 4.1.2
+
+### Patch Changes
+
+- [#406](https://github.com/esengine/esengine/pull/406) [`0de4527`](https://github.com/esengine/esengine/commit/0de45279e612c04ae9be7fbd65ce496e4797a43c) Thanks [@esengine](https://github.com/esengine)! - fix(behavior-tree): export NodeExecutorMetadata as value instead of type
+
+    Fixed the export of `NodeExecutorMetadata` decorator in `execution/index.ts`.
+    Previously it was exported as `export type { NodeExecutorMetadata }` which only
+    exported the type signature, not the actual function. This caused runtime errors
+    in Cocos Creator: "TypeError: (intermediate value) is not a function".
+
+    Changed to `export { NodeExecutorMetadata }` to properly export the decorator function.
+
 ## 4.1.1
 
 ### Patch Changes

packages/framework/behavior-tree/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@esengine/behavior-tree",
-    "version": "4.1.1",
+    "version": "4.2.0",
     "description": "ECS-based AI behavior tree system - works with any ECS framework (ESEngine, Cocos, Laya, etc.)",
     "main": "dist/index.js",
     "module": "dist/index.js",
@@ -29,7 +29,8 @@
         "clean": "rimraf dist tsconfig.tsbuildinfo",
         "build": "tsup",
         "build:watch": "tsup --watch",
-        "type-check": "tsc --noEmit"
+        "type-check": "tsc --noEmit",
+        "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js"
     },
     "author": "yhh",
     "license": "MIT",

packages/framework/behavior-tree/src/BehaviorTreeBuilder.ts

@@ -181,12 +181,73 @@ export class BehaviorTreeBuilder {
     }
 
     /**
-     * 添加执行动作
+     * 添加执行动作（通过黑板函数）
+     *
+     * @zh 使用黑板中的 action_{actionName} 函数执行动作
+     * @en Execute action using action_{actionName} function from blackboard
+     *
+     * @example
+     * ```typescript
+     * BehaviorTreeBuilder.create("AI")
+     *     .defineBlackboardVariable("action_Attack", (entity) => TaskStatus.Success)
+     *     .selector("Root")
+     *         .executeAction("Attack")
+     *     .end()
+     *     .build();
+     * ```
      */
     executeAction(actionName: string, name?: string): BehaviorTreeBuilder {
         return this.addActionNode('ExecuteAction', name || 'ExecuteAction', { actionName });
     }
 
+    /**
+     * 添加自定义动作节点
+     *
+     * @zh 直接使用注册的执行器类型（通过 @NodeExecutorMetadata 装饰器注册的类）
+     * @en Use a registered executor type directly (class registered via @NodeExecutorMetadata decorator)
+     *
+     * @param implementationType - 执行器类型名称（@NodeExecutorMetadata 中的 implementationType）
+     * @param name - 节点显示名称
+     * @param config - 节点配置参数
+     *
+     * @example
+     * ```typescript
+     * // 1. 定义自定义执行器
+     * @NodeExecutorMetadata({
+     *     implementationType: 'AttackAction',
+     *     nodeType: NodeType.Action,
+     *     displayName: '攻击动作',
+     *     category: 'Action'
+     * })
+     * class AttackAction implements INodeExecutor {
+     *     execute(context: NodeExecutionContext): TaskStatus {
+     *         console.log("执行攻击！");
+     *         return TaskStatus.Success;
+     *     }
+     * }
+     *
+     * // 2. 在行为树中使用
+     * BehaviorTreeBuilder.create("AI")
+     *     .selector("Root")
+     *         .action("AttackAction", "Attack")
+     *     .end()
+     *     .build();
+     * ```
+     */
+    action(implementationType: string, name?: string, config?: Record<string, any>): BehaviorTreeBuilder {
+        return this.addActionNode(implementationType, name || implementationType, config || {});
+    }
+
+    /**
+     * 添加自定义条件节点
+     *
+     * @zh 直接使用注册的条件执行器类型
+     * @en Use a registered condition executor type directly
+     */
+    condition(implementationType: string, name?: string, config?: Record<string, any>): BehaviorTreeBuilder {
+        return this.addConditionNode(implementationType, name || implementationType, config || {});
+    }
+
     /**
      * 添加黑板比较条件
      */

packages/framework/behavior-tree/src/execution/index.ts

@@ -5,7 +5,7 @@ export { BehaviorTreeAssetManager } from './BehaviorTreeAssetManager';
 export type { INodeExecutor, NodeExecutionContext } from './NodeExecutor';
 export { NodeExecutorRegistry, BindingHelper } from './NodeExecutor';
 export { BehaviorTreeExecutionSystem } from './BehaviorTreeExecutionSystem';
-export type { NodeMetadata, ConfigFieldDefinition, NodeExecutorMetadata } from './NodeMetadata';
-export { NodeMetadataRegistry } from './NodeMetadata';
+export type { NodeMetadata, ConfigFieldDefinition } from './NodeMetadata';
+export { NodeMetadataRegistry, NodeExecutorMetadata } from './NodeMetadata';
 
 export * from './Executors';

packages/framework/core/src/Core.ts

@@ -742,6 +742,7 @@ export class Core {
         if (!this._instance) return;
 
         this._instance._debugManager?.stop();
+        this._instance._sceneManager.destroy();
         this._instance._serviceContainer.clear();
         Core._logger.info('Core destroyed');
         this._instance = null;

packages/framework/database-drivers/CHANGELOG.md

@@ -0,0 +1,57 @@
+# @esengine/database-drivers
+
+## 1.1.1
+
+### Patch Changes
+
+- [#412](https://github.com/esengine/esengine/pull/412) [`85171a0`](https://github.com/esengine/esengine/commit/85171a0a5c073ef7883705ee4daaca8bb0218f20) Thanks [@esengine](https://github.com/esengine)! - fix: include dist directory in npm package
+
+    Previous 1.1.0 release was missing the compiled dist directory.
+
+## 1.1.0
+
+### Minor Changes
+
+- [#410](https://github.com/esengine/esengine/pull/410) [`71022ab`](https://github.com/esengine/esengine/commit/71022abc99ad4a1b349f19f4ccf1e0a2a0923dfa) Thanks [@esengine](https://github.com/esengine)! - feat: add database layer architecture
+
+    Added new database packages with layered architecture:
+
+    **@esengine/database-drivers (Layer 1)**
+    - MongoDB connection with pool management, auto-reconnect, events
+    - Redis connection with auto-reconnect, key prefix
+    - Type-safe `IMongoCollection<T>` interface decoupled from mongodb types
+    - Service tokens for dependency injection (`MongoConnectionToken`, `RedisConnectionToken`)
+
+    **@esengine/database (Layer 2)**
+    - Generic `Repository<T>` with CRUD, pagination, soft delete
+    - `UserRepository` with registration, authentication, role management
+    - Password hashing utilities using scrypt
+    - Query operators: `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$like`, `$regex`
+
+    **@esengine/transaction**
+    - Refactored `MongoStorage` to use shared connection from `@esengine/database-drivers`
+    - Removed factory pattern in favor of shared connection (breaking change)
+    - Simplified API: `createMongoStorage(connection, options?)`
+
+    Example usage:
+
+    ```typescript
+    import { createMongoConnection } from '@esengine/database-drivers';
+    import { UserRepository } from '@esengine/database';
+    import { createMongoStorage, TransactionManager } from '@esengine/transaction';
+
+    // Create shared connection
+    const mongo = createMongoConnection({
+        uri: 'mongodb://localhost:27017',
+        database: 'game'
+    });
+    await mongo.connect();
+
+    // Use for database operations
+    const userRepo = new UserRepository(mongo);
+    await userRepo.register({ username: 'john', password: '123456' });
+
+    // Use for transactions (same connection)
+    const storage = createMongoStorage(mongo);
+    const txManager = new TransactionManager({ storage });
+    ```

packages/framework/database-drivers/module.json

@@ -0,0 +1,23 @@
+{
+    "id": "database-drivers",
+    "name": "@esengine/database-drivers",
+    "globalKey": "database-drivers",
+    "displayName": "Database Drivers",
+    "description": "数据库连接驱动，提供 MongoDB、Redis 等数据库的连接管理 | Database connection drivers with connection pooling for MongoDB, Redis, etc.",
+    "version": "1.0.0",
+    "category": "Infrastructure",
+    "icon": "Database",
+    "tags": ["database", "mongodb", "redis", "connection"],
+    "isCore": false,
+    "defaultEnabled": true,
+    "isEngineModule": false,
+    "canContainContent": false,
+    "platforms": ["server"],
+    "dependencies": [],
+    "exports": {
+        "components": [],
+        "systems": []
+    },
+    "requiresWasm": false,
+    "outputPath": "dist/index.js"
+}

packages/framework/database-drivers/package.json

@@ -0,0 +1,48 @@
+{
+    "name": "@esengine/database-drivers",
+    "version": "1.1.1",
+    "description": "Database connection drivers for ESEngine | ESEngine 数据库连接驱动",
+    "type": "module",
+    "main": "./dist/index.js",
+    "module": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "import": "./dist/index.js",
+            "types": "./dist/index.d.ts"
+        }
+    },
+    "files": [
+        "dist",
+        "module.json"
+    ],
+    "scripts": {
+        "build": "tsup",
+        "build:watch": "tsup --watch",
+        "type-check": "tsc --noEmit",
+        "clean": "rimraf dist"
+    },
+    "peerDependencies": {
+        "mongodb": ">=6.0.0",
+        "ioredis": ">=5.0.0"
+    },
+    "peerDependenciesMeta": {
+        "mongodb": {
+            "optional": true
+        },
+        "ioredis": {
+            "optional": true
+        }
+    },
+    "devDependencies": {
+        "@types/node": "^20.0.0",
+        "mongodb": "^6.12.0",
+        "ioredis": "^5.3.0",
+        "tsup": "^8.0.0",
+        "typescript": "^5.8.0",
+        "rimraf": "^5.0.0"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}

packages/framework/database-drivers/src/adapters/MongoCollectionAdapter.ts

@@ -0,0 +1,238 @@
+/**
+ * @zh MongoDB 集合适配器
+ * @en MongoDB collection adapter
+ *
+ * @zh 将 MongoDB 原生 Collection 适配为简化接口
+ * @en Adapts native MongoDB Collection to simplified interface
+ */
+
+import type { Collection, Db } from 'mongodb'
+import type {
+    DeleteResult,
+    FindOneAndUpdateOptions,
+    FindOptions,
+    IMongoCollection,
+    IMongoDatabase,
+    IndexOptions,
+    InsertManyResult,
+    InsertOneResult,
+    UpdateResult
+} from '../interfaces/IMongoCollection.js'
+
+/**
+ * @zh MongoDB 集合适配器
+ * @en MongoDB collection adapter
+ */
+export class MongoCollectionAdapter<T extends object> implements IMongoCollection<T> {
+    readonly name: string
+
+    constructor(private readonly _collection: Collection<T>) {
+        this.name = _collection.collectionName
+    }
+
+    // =========================================================================
+    // 查询 | Query
+    // =========================================================================
+
+    async findOne(filter: object, options?: FindOptions): Promise<T | null> {
+        const doc = await this._collection.findOne(
+            filter as Parameters<typeof this._collection.findOne>[0],
+            {
+                sort: options?.sort as Parameters<typeof this._collection.findOne>[1] extends { sort?: infer S } ? S : never,
+                projection: options?.projection
+            }
+        )
+        return doc ? this._stripId(doc) : null
+    }
+
+    async find(filter: object, options?: FindOptions): Promise<T[]> {
+        let cursor = this._collection.find(
+            filter as Parameters<typeof this._collection.find>[0]
+        )
+
+        if (options?.sort) {
+            cursor = cursor.sort(options.sort as Parameters<typeof cursor.sort>[0])
+        }
+
+        if (options?.skip) {
+            cursor = cursor.skip(options.skip)
+        }
+
+        if (options?.limit) {
+            cursor = cursor.limit(options.limit)
+        }
+
+        if (options?.projection) {
+            cursor = cursor.project(options.projection)
+        }
+
+        const docs = await cursor.toArray()
+        return docs.map(doc => this._stripId(doc))
+    }
+
+    async countDocuments(filter?: object): Promise<number> {
+        return this._collection.countDocuments(
+            (filter ?? {}) as Parameters<typeof this._collection.countDocuments>[0]
+        )
+    }
+
+    // =========================================================================
+    // 创建 | Create
+    // =========================================================================
+
+    async insertOne(doc: T): Promise<InsertOneResult> {
+        const result = await this._collection.insertOne(
+            doc as Parameters<typeof this._collection.insertOne>[0]
+        )
+        return {
+            insertedId: result.insertedId,
+            acknowledged: result.acknowledged
+        }
+    }
+
+    async insertMany(docs: T[]): Promise<InsertManyResult> {
+        const result = await this._collection.insertMany(
+            docs as Parameters<typeof this._collection.insertMany>[0]
+        )
+        return {
+            insertedCount: result.insertedCount,
+            insertedIds: result.insertedIds as Record<number, unknown>,
+            acknowledged: result.acknowledged
+        }
+    }
+
+    // =========================================================================
+    // 更新 | Update
+    // =========================================================================
+
+    async updateOne(filter: object, update: object): Promise<UpdateResult> {
+        const result = await this._collection.updateOne(
+            filter as Parameters<typeof this._collection.updateOne>[0],
+            update as Parameters<typeof this._collection.updateOne>[1]
+        )
+        return {
+            matchedCount: result.matchedCount,
+            modifiedCount: result.modifiedCount,
+            upsertedCount: result.upsertedCount,
+            upsertedId: result.upsertedId,
+            acknowledged: result.acknowledged
+        }
+    }
+
+    async updateMany(filter: object, update: object): Promise<UpdateResult> {
+        const result = await this._collection.updateMany(
+            filter as Parameters<typeof this._collection.updateMany>[0],
+            update as Parameters<typeof this._collection.updateMany>[1]
+        )
+        return {
+            matchedCount: result.matchedCount,
+            modifiedCount: result.modifiedCount,
+            upsertedCount: result.upsertedCount,
+            upsertedId: result.upsertedId,
+            acknowledged: result.acknowledged
+        }
+    }
+
+    async findOneAndUpdate(
+        filter: object,
+        update: object,
+        options?: FindOneAndUpdateOptions
+    ): Promise<T | null> {
+        const result = await this._collection.findOneAndUpdate(
+            filter as Parameters<typeof this._collection.findOneAndUpdate>[0],
+            update as Parameters<typeof this._collection.findOneAndUpdate>[1],
+            {
+                returnDocument: options?.returnDocument ?? 'after',
+                upsert: options?.upsert
+            }
+        )
+        return result ? this._stripId(result) : null
+    }
+
+    // =========================================================================
+    // 删除 | Delete
+    // =========================================================================
+
+    async deleteOne(filter: object): Promise<DeleteResult> {
+        const result = await this._collection.deleteOne(
+            filter as Parameters<typeof this._collection.deleteOne>[0]
+        )
+        return {
+            deletedCount: result.deletedCount,
+            acknowledged: result.acknowledged
+        }
+    }
+
+    async deleteMany(filter: object): Promise<DeleteResult> {
+        const result = await this._collection.deleteMany(
+            filter as Parameters<typeof this._collection.deleteMany>[0]
+        )
+        return {
+            deletedCount: result.deletedCount,
+            acknowledged: result.acknowledged
+        }
+    }
+
+    // =========================================================================
+    // 索引 | Index
+    // =========================================================================
+
+    async createIndex(
+        spec: Record<string, 1 | -1>,
+        options?: IndexOptions
+    ): Promise<string> {
+        return this._collection.createIndex(spec, options)
+    }
+
+    // =========================================================================
+    // 内部方法 | Internal Methods
+    // =========================================================================
+
+    /**
+     * @zh 移除 MongoDB 的 _id 字段
+     * @en Remove MongoDB's _id field
+     */
+    private _stripId<D extends object>(doc: D): D {
+        const { _id, ...rest } = doc as { _id?: unknown } & Record<string, unknown>
+        return rest as D
+    }
+}
+
+/**
+ * @zh MongoDB 数据库适配器
+ * @en MongoDB database adapter
+ */
+export class MongoDatabaseAdapter implements IMongoDatabase {
+    readonly name: string
+    private _collections = new Map<string, MongoCollectionAdapter<object>>()
+
+    constructor(private readonly _db: Db) {
+        this.name = _db.databaseName
+    }
+
+    collection<T extends object = object>(name: string): IMongoCollection<T> {
+        if (!this._collections.has(name)) {
+            const nativeCollection = this._db.collection<T>(name)
+            this._collections.set(
+                name,
+                new MongoCollectionAdapter(nativeCollection) as MongoCollectionAdapter<object>
+            )
+        }
+        return this._collections.get(name) as IMongoCollection<T>
+    }
+
+    async listCollections(): Promise<string[]> {
+        const collections = await this._db.listCollections().toArray()
+        return collections.map(c => c.name)
+    }
+
+    async dropCollection(name: string): Promise<boolean> {
+        try {
+            await this._db.dropCollection(name)
+            this._collections.delete(name)
+            return true
+        } catch {
+            return false
+        }
+    }
+}

packages/framework/database-drivers/src/drivers/MongoConnection.ts

@@ -0,0 +1,343 @@
+/**
+ * @zh MongoDB 连接驱动
+ * @en MongoDB connection driver
+ *
+ * @zh 提供 MongoDB 数据库的连接管理、自动重连和事件通知
+ * @en Provides MongoDB connection management, auto-reconnect, and event notification
+ */
+
+import type { Db, MongoClient as MongoClientType, MongoClientOptions } from 'mongodb'
+import { randomUUID } from 'crypto'
+import {
+    ConnectionError,
+    type ConnectionEvent,
+    type ConnectionEventListener,
+    type ConnectionEventType,
+    type ConnectionState,
+    type IEventableConnection,
+    type MongoConnectionConfig
+} from '../types.js'
+import type { IMongoCollection, IMongoDatabase } from '../interfaces/IMongoCollection.js'
+import { MongoDatabaseAdapter } from '../adapters/MongoCollectionAdapter.js'
+
+/**
+ * @zh MongoDB 连接接口
+ * @en MongoDB connection interface
+ */
+export interface IMongoConnection extends IEventableConnection {
+    /**
+     * @zh 获取数据库接口
+     * @en Get database interface
+     */
+    getDatabase(): IMongoDatabase
+
+    /**
+     * @zh 获取原生客户端（高级用法）
+     * @en Get native client (advanced usage)
+     */
+    getNativeClient(): MongoClientType
+
+    /**
+     * @zh 获取原生数据库（高级用法）
+     * @en Get native database (advanced usage)
+     */
+    getNativeDatabase(): Db
+
+    /**
+     * @zh 获取集合
+     * @en Get collection
+     */
+    collection<T extends object = object>(name: string): IMongoCollection<T>
+}
+
+/**
+ * @zh MongoDB 连接实现
+ * @en MongoDB connection implementation
+ *
+ * @example
+ * ```typescript
+ * const mongo = new MongoConnection({
+ *     uri: 'mongodb://localhost:27017',
+ *     database: 'game',
+ *     autoReconnect: true,
+ * })
+ *
+ * mongo.on('connected', () => console.log('Connected!'))
+ * mongo.on('error', (e) => console.error('Error:', e.error))
+ *
+ * await mongo.connect()
+ *
+ * const users = mongo.collection('users')
+ * await users.insertOne({ name: 'test' })
+ *
+ * await mongo.disconnect()
+ * ```
+ */
+export class MongoConnection implements IMongoConnection {
+    readonly id: string
+    private _state: ConnectionState = 'disconnected'
+    private _client: MongoClientType | null = null
+    private _db: Db | null = null
+    private _config: MongoConnectionConfig
+    private _listeners = new Map<ConnectionEventType, Set<ConnectionEventListener>>()
+    private _reconnectAttempts = 0
+    private _reconnectTimer: ReturnType<typeof setTimeout> | null = null
+
+    constructor(config: MongoConnectionConfig) {
+        this.id = randomUUID()
+        this._config = {
+            autoReconnect: true,
+            reconnectInterval: 5000,
+            maxReconnectAttempts: 10,
+            ...config
+        }
+    }
+
+    // =========================================================================
+    // 状态 | State
+    // =========================================================================
+
+    get state(): ConnectionState {
+        return this._state
+    }
+
+    isConnected(): boolean {
+        return this._state === 'connected' && this._client !== null
+    }
+
+    // =========================================================================
+    // 连接管理 | Connection Management
+    // =========================================================================
+
+    async connect(): Promise<void> {
+        if (this._state === 'connected') {
+            return
+        }
+
+        if (this._state === 'connecting') {
+            throw new ConnectionError('Connection already in progress')
+        }
+
+        this._state = 'connecting'
+
+        try {
+            const { MongoClient } = await import('mongodb')
+
+            const options: MongoClientOptions = {}
+            if (this._config.pool) {
+                if (this._config.pool.minSize) {
+                    options.minPoolSize = this._config.pool.minSize
+                }
+                if (this._config.pool.maxSize) {
+                    options.maxPoolSize = this._config.pool.maxSize
+                }
+                if (this._config.pool.acquireTimeout) {
+                    options.waitQueueTimeoutMS = this._config.pool.acquireTimeout
+                }
+                if (this._config.pool.maxLifetime) {
+                    options.maxIdleTimeMS = this._config.pool.maxLifetime
+                }
+            }
+
+            this._client = new MongoClient(this._config.uri, options)
+            await this._client.connect()
+            this._db = this._client.db(this._config.database)
+
+            this._state = 'connected'
+            this._reconnectAttempts = 0
+            this._emit('connected')
+
+            this._setupClientEvents()
+        } catch (error) {
+            this._state = 'error'
+            const connError = new ConnectionError(
+                `Failed to connect to MongoDB: ${(error as Error).message}`,
+                'CONNECTION_FAILED',
+                error as Error
+            )
+            this._emit('error', connError)
+            throw connError
+        }
+    }
+
+    async disconnect(): Promise<void> {
+        if (this._state === 'disconnected') {
+            return
+        }
+
+        this._clearReconnectTimer()
+        this._state = 'disconnecting'
+
+        try {
+            if (this._client) {
+                await this._client.close()
+                this._client = null
+                this._db = null
+            }
+
+            this._state = 'disconnected'
+            this._emit('disconnected')
+        } catch (error) {
+            this._state = 'error'
+            throw new ConnectionError(
+                `Failed to disconnect: ${(error as Error).message}`,
+                'CONNECTION_FAILED',
+                error as Error
+            )
+        }
+    }
+
+    async ping(): Promise<boolean> {
+        if (!this._db) {
+            return false
+        }
+
+        try {
+            await this._db.command({ ping: 1 })
+            return true
+        } catch {
+            return false
+        }
+    }
+
+    // =========================================================================
+    // 数据库访问 | Database Access
+    // =========================================================================
+
+    private _dbAdapter: MongoDatabaseAdapter | null = null
+
+    getDatabase(): IMongoDatabase {
+        if (!this._db) {
+            throw new ConnectionError('Not connected to database', 'CONNECTION_CLOSED')
+        }
+        if (!this._dbAdapter) {
+            this._dbAdapter = new MongoDatabaseAdapter(this._db)
+        }
+        return this._dbAdapter
+    }
+
+    getNativeDatabase(): Db {
+        if (!this._db) {
+            throw new ConnectionError('Not connected to database', 'CONNECTION_CLOSED')
+        }
+        return this._db
+    }
+
+    getNativeClient(): MongoClientType {
+        if (!this._client) {
+            throw new ConnectionError('Not connected to database', 'CONNECTION_CLOSED')
+        }
+        return this._client
+    }
+
+    collection<T extends object = object>(name: string): IMongoCollection<T> {
+        return this.getDatabase().collection<T>(name)
+    }
+
+    // =========================================================================
+    // 事件 | Events
+    // =========================================================================
+
+    on(event: ConnectionEventType, listener: ConnectionEventListener): void {
+        if (!this._listeners.has(event)) {
+            this._listeners.set(event, new Set())
+        }
+        this._listeners.get(event)!.add(listener)
+    }
+
+    off(event: ConnectionEventType, listener: ConnectionEventListener): void {
+        this._listeners.get(event)?.delete(listener)
+    }
+
+    once(event: ConnectionEventType, listener: ConnectionEventListener): void {
+        const wrapper: ConnectionEventListener = (e) => {
+            this.off(event, wrapper)
+            listener(e)
+        }
+        this.on(event, wrapper)
+    }
+
+    private _emit(type: ConnectionEventType, error?: Error): void {
+        const event: ConnectionEvent = {
+            type,
+            connectionId: this.id,
+            timestamp: Date.now(),
+            error
+        }
+
+        const listeners = this._listeners.get(type)
+        if (listeners) {
+            for (const listener of listeners) {
+                try {
+                    listener(event)
+                } catch {
+                    // Ignore listener errors
+                }
+            }
+        }
+    }
+
+    // =========================================================================
+    // 内部方法 | Internal Methods
+    // =========================================================================
+
+    private _setupClientEvents(): void {
+        if (!this._client) return
+
+        this._client.on('close', () => {
+            if (this._state === 'connected') {
+                this._state = 'disconnected'
+                this._emit('disconnected')
+                this._scheduleReconnect()
+            }
+        })
+
+        this._client.on('error', (error) => {
+            this._emit('error', error)
+        })
+    }
+
+    private _scheduleReconnect(): void {
+        if (!this._config.autoReconnect) return
+        if (this._reconnectAttempts >= (this._config.maxReconnectAttempts ?? 10)) {
+            return
+        }
+
+        this._clearReconnectTimer()
+        this._emit('reconnecting')
+
+        this._reconnectTimer = setTimeout(async () => {
+            this._reconnectAttempts++
+            try {
+                await this.connect()
+                this._emit('reconnected')
+            } catch {
+                this._scheduleReconnect()
+            }
+        }, this._config.reconnectInterval ?? 5000)
+    }
+
+    private _clearReconnectTimer(): void {
+        if (this._reconnectTimer) {
+            clearTimeout(this._reconnectTimer)
+            this._reconnectTimer = null
+        }
+    }
+}
+
+/**
+ * @zh 创建 MongoDB 连接
+ * @en Create MongoDB connection
+ *
+ * @example
+ * ```typescript
+ * const mongo = createMongoConnection({
+ *     uri: process.env.MONGODB_URI!,
+ *     database: 'game',
+ * })
+ * await mongo.connect()
+ * ```
+ */
+export function createMongoConnection(config: MongoConnectionConfig): MongoConnection {
+    return new MongoConnection(config)
+}

packages/framework/database-drivers/src/drivers/RedisConnection.ts

@@ -0,0 +1,300 @@
+/**
+ * @zh Redis 连接驱动
+ * @en Redis connection driver
+ *
+ * @zh 提供 Redis 数据库的连接管理、自动重连和事件通知
+ * @en Provides Redis connection management, auto-reconnect, and event notification
+ */
+
+import type { Redis as RedisClientType, RedisOptions } from 'ioredis'
+import { randomUUID } from 'crypto'
+import {
+    ConnectionError,
+    type ConnectionEvent,
+    type ConnectionEventListener,
+    type ConnectionEventType,
+    type ConnectionState,
+    type IEventableConnection,
+    type RedisConnectionConfig
+} from '../types.js'
+
+/**
+ * @zh Redis 连接接口
+ * @en Redis connection interface
+ */
+export interface IRedisConnection extends IEventableConnection {
+    /**
+     * @zh 获取原生客户端
+     * @en Get native client
+     */
+    getClient(): RedisClientType
+
+    /**
+     * @zh 获取键值
+     * @en Get value by key
+     */
+    get(key: string): Promise<string | null>
+
+    /**
+     * @zh 设置键值
+     * @en Set key value
+     */
+    set(key: string, value: string, ttl?: number): Promise<void>
+
+    /**
+     * @zh 删除键
+     * @en Delete key
+     */
+    del(key: string): Promise<boolean>
+
+    /**
+     * @zh 检查键是否存在
+     * @en Check if key exists
+     */
+    exists(key: string): Promise<boolean>
+}
+
+/**
+ * @zh Redis 连接实现
+ * @en Redis connection implementation
+ *
+ * @example
+ * ```typescript
+ * const redis = new RedisConnection({
+ *     host: 'localhost',
+ *     port: 6379,
+ *     keyPrefix: 'game:',
+ * })
+ *
+ * await redis.connect()
+ *
+ * await redis.set('player:1:score', '100', 3600)
+ * const score = await redis.get('player:1:score')
+ *
+ * await redis.disconnect()
+ * ```
+ */
+export class RedisConnection implements IRedisConnection {
+    readonly id: string
+    private _state: ConnectionState = 'disconnected'
+    private _client: RedisClientType | null = null
+    private _config: RedisConnectionConfig
+    private _listeners = new Map<ConnectionEventType, Set<ConnectionEventListener>>()
+
+    constructor(config: RedisConnectionConfig) {
+        this.id = randomUUID()
+        this._config = {
+            host: 'localhost',
+            port: 6379,
+            autoReconnect: true,
+            ...config
+        }
+    }
+
+    // =========================================================================
+    // 状态 | State
+    // =========================================================================
+
+    get state(): ConnectionState {
+        return this._state
+    }
+
+    isConnected(): boolean {
+        return this._state === 'connected' && this._client !== null
+    }
+
+    // =========================================================================
+    // 连接管理 | Connection Management
+    // =========================================================================
+
+    async connect(): Promise<void> {
+        if (this._state === 'connected') {
+            return
+        }
+
+        if (this._state === 'connecting') {
+            throw new ConnectionError('Connection already in progress')
+        }
+
+        this._state = 'connecting'
+
+        try {
+            const Redis = (await import('ioredis')).default
+
+            const options: RedisOptions = {
+                host: this._config.host,
+                port: this._config.port,
+                password: this._config.password,
+                db: this._config.db,
+                keyPrefix: this._config.keyPrefix,
+                retryStrategy: this._config.autoReconnect
+                    ? (times) => Math.min(times * 100, 3000)
+                    : () => null,
+                lazyConnect: true
+            }
+
+            if (this._config.url) {
+                this._client = new Redis(this._config.url, options)
+            } else {
+                this._client = new Redis(options)
+            }
+
+            this._setupClientEvents()
+            await this._client.connect()
+
+            this._state = 'connected'
+            this._emit('connected')
+        } catch (error) {
+            this._state = 'error'
+            const connError = new ConnectionError(
+                `Failed to connect to Redis: ${(error as Error).message}`,
+                'CONNECTION_FAILED',
+                error as Error
+            )
+            this._emit('error', connError)
+            throw connError
+        }
+    }
+
+    async disconnect(): Promise<void> {
+        if (this._state === 'disconnected') {
+            return
+        }
+
+        this._state = 'disconnecting'
+
+        try {
+            if (this._client) {
+                await this._client.quit()
+                this._client = null
+            }
+
+            this._state = 'disconnected'
+            this._emit('disconnected')
+        } catch (error) {
+            this._state = 'error'
+            throw new ConnectionError(
+                `Failed to disconnect: ${(error as Error).message}`,
+                'CONNECTION_FAILED',
+                error as Error
+            )
+        }
+    }
+
+    async ping(): Promise<boolean> {
+        if (!this._client) {
+            return false
+        }
+
+        try {
+            const result = await this._client.ping()
+            return result === 'PONG'
+        } catch {
+            return false
+        }
+    }
+
+    // =========================================================================
+    // 数据操作 | Data Operations
+    // =========================================================================
+
+    getClient(): RedisClientType {
+        if (!this._client) {
+            throw new ConnectionError('Not connected to Redis', 'CONNECTION_CLOSED')
+        }
+        return this._client
+    }
+
+    async get(key: string): Promise<string | null> {
+        return this.getClient().get(key)
+    }
+
+    async set(key: string, value: string, ttl?: number): Promise<void> {
+        const client = this.getClient()
+        if (ttl) {
+            await client.setex(key, ttl, value)
+        } else {
+            await client.set(key, value)
+        }
+    }
+
+    async del(key: string): Promise<boolean> {
+        const result = await this.getClient().del(key)
+        return result > 0
+    }
+
+    async exists(key: string): Promise<boolean> {
+        const result = await this.getClient().exists(key)
+        return result > 0
+    }
+
+    // =========================================================================
+    // 事件 | Events
+    // =========================================================================
+
+    on(event: ConnectionEventType, listener: ConnectionEventListener): void {
+        if (!this._listeners.has(event)) {
+            this._listeners.set(event, new Set())
+        }
+        this._listeners.get(event)!.add(listener)
+    }
+
+    off(event: ConnectionEventType, listener: ConnectionEventListener): void {
+        this._listeners.get(event)?.delete(listener)
+    }
+
+    once(event: ConnectionEventType, listener: ConnectionEventListener): void {
+        const wrapper: ConnectionEventListener = (e) => {
+            this.off(event, wrapper)
+            listener(e)
+        }
+        this.on(event, wrapper)
+    }
+
+    private _emit(type: ConnectionEventType, error?: Error): void {
+        const event: ConnectionEvent = {
+            type,
+            connectionId: this.id,
+            timestamp: Date.now(),
+            error
+        }
+
+        const listeners = this._listeners.get(type)
+        if (listeners) {
+            for (const listener of listeners) {
+                try {
+                    listener(event)
+                } catch {
+                    // Ignore listener errors
+                }
+            }
+        }
+    }
+
+    private _setupClientEvents(): void {
+        if (!this._client) return
+
+        this._client.on('close', () => {
+            if (this._state === 'connected') {
+                this._state = 'disconnected'
+                this._emit('disconnected')
+            }
+        })
+
+        this._client.on('error', (error) => {
+            this._emit('error', error)
+        })
+
+        this._client.on('reconnecting', () => {
+            this._emit('reconnecting')
+        })
+    }
+}
+
+/**
+ * @zh 创建 Redis 连接
+ * @en Create Redis connection
+ */
+export function createRedisConnection(config: RedisConnectionConfig): RedisConnection {
+    return new RedisConnection(config)
+}

packages/framework/database-drivers/src/drivers/index.ts

@@ -0,0 +1,29 @@
+/**
+ * @zh 数据库驱动导出
+ * @en Database drivers export
+ */
+
+export {
+    MongoConnection,
+    createMongoConnection,
+    type IMongoConnection
+} from './MongoConnection.js'
+
+export {
+    RedisConnection,
+    createRedisConnection,
+    type IRedisConnection
+} from './RedisConnection.js'
+
+// Re-export interfaces
+export type {
+    IMongoCollection,
+    IMongoDatabase,
+    InsertOneResult,
+    InsertManyResult,
+    UpdateResult,
+    DeleteResult,
+    FindOptions,
+    FindOneAndUpdateOptions,
+    IndexOptions
+} from '../interfaces/IMongoCollection.js'

packages/framework/database-drivers/src/index.ts

@@ -0,0 +1,117 @@
+/**
+ * @zh @esengine/database-drivers 数据库连接驱动
+ * @en @esengine/database-drivers Database Connection Drivers
+ *
+ * @zh 提供 MongoDB、Redis 等数据库的连接管理，支持连接池、自动重连和事件通知
+ * @en Provides connection management for MongoDB, Redis, etc. with pooling, auto-reconnect, and events
+ *
+ * @example
+ * ```typescript
+ * import {
+ *     createMongoConnection,
+ *     createRedisConnection,
+ *     MongoConnectionToken,
+ *     RedisConnectionToken,
+ * } from '@esengine/database-drivers'
+ *
+ * // 创建 MongoDB 连接
+ * const mongo = createMongoConnection({
+ *     uri: 'mongodb://localhost:27017',
+ *     database: 'game',
+ *     pool: { minSize: 5, maxSize: 20 },
+ *     autoReconnect: true,
+ * })
+ *
+ * mongo.on('connected', () => console.log('MongoDB connected'))
+ * mongo.on('error', (e) => console.error('Error:', e.error))
+ *
+ * await mongo.connect()
+ *
+ * // 直接使用
+ * const users = mongo.collection('users')
+ * await users.insertOne({ name: 'test' })
+ *
+ * // 或注册到服务容器供其他模块使用
+ * services.register(MongoConnectionToken, mongo)
+ *
+ * // 创建 Redis 连接
+ * const redis = createRedisConnection({
+ *     host: 'localhost',
+ *     port: 6379,
+ *     keyPrefix: 'game:',
+ * })
+ *
+ * await redis.connect()
+ * await redis.set('session:123', 'data', 3600)
+ *
+ * // 断开连接
+ * await mongo.disconnect()
+ * await redis.disconnect()
+ * ```
+ */
+
+// =============================================================================
+// Types | 类型
+// =============================================================================
+
+export type {
+    ConnectionState,
+    IConnection,
+    IEventableConnection,
+    ConnectionEventType,
+    ConnectionEventListener,
+    ConnectionEvent,
+    PoolConfig,
+    MongoConnectionConfig,
+    RedisConnectionConfig,
+    DatabaseErrorCode
+} from './types.js'
+
+export {
+    DatabaseError,
+    ConnectionError,
+    DuplicateKeyError
+} from './types.js'
+
+// =============================================================================
+// Drivers | 驱动
+// =============================================================================
+
+export {
+    MongoConnection,
+    createMongoConnection,
+    type IMongoConnection
+} from './drivers/index.js'
+
+export {
+    RedisConnection,
+    createRedisConnection,
+    type IRedisConnection
+} from './drivers/index.js'
+
+// =============================================================================
+// Interfaces | 接口
+// =============================================================================
+
+export type {
+    IMongoCollection,
+    IMongoDatabase,
+    InsertOneResult,
+    InsertManyResult,
+    UpdateResult,
+    DeleteResult,
+    FindOptions,
+    FindOneAndUpdateOptions,
+    IndexOptions
+} from './drivers/index.js'
+
+// =============================================================================
+// Tokens | 服务令牌
+// =============================================================================
+
+export {
+    MongoConnectionToken,
+    RedisConnectionToken,
+    createServiceToken,
+    type ServiceToken
+} from './tokens.js'

packages/framework/database-drivers/src/interfaces/IMongoCollection.ts

@@ -0,0 +1,237 @@
+/**
+ * @zh MongoDB 集合简化接口
+ * @en MongoDB collection simplified interface
+ *
+ * @zh 提供与 MongoDB 解耦的类型安全接口
+ * @en Provides type-safe interface decoupled from MongoDB
+ */
+
+// =============================================================================
+// 查询结果 | Query Results
+// =============================================================================
+
+/**
+ * @zh 插入结果
+ * @en Insert result
+ */
+export interface InsertOneResult {
+    insertedId: unknown
+    acknowledged: boolean
+}
+
+/**
+ * @zh 批量插入结果
+ * @en Insert many result
+ */
+export interface InsertManyResult {
+    insertedCount: number
+    insertedIds: Record<number, unknown>
+    acknowledged: boolean
+}
+
+/**
+ * @zh 更新结果
+ * @en Update result
+ */
+export interface UpdateResult {
+    matchedCount: number
+    modifiedCount: number
+    upsertedCount: number
+    upsertedId?: unknown
+    acknowledged: boolean
+}
+
+/**
+ * @zh 删除结果
+ * @en Delete result
+ */
+export interface DeleteResult {
+    deletedCount: number
+    acknowledged: boolean
+}
+
+// =============================================================================
+// 查询选项 | Query Options
+// =============================================================================
+
+/**
+ * @zh 排序方向
+ * @en Sort direction
+ */
+export type SortDirection = 1 | -1 | 'asc' | 'desc'
+
+/**
+ * @zh 排序定义
+ * @en Sort definition
+ */
+export type Sort = Record<string, SortDirection>
+
+/**
+ * @zh 查找选项
+ * @en Find options
+ */
+export interface FindOptions {
+    sort?: Sort
+    limit?: number
+    skip?: number
+    projection?: Record<string, 0 | 1>
+}
+
+/**
+ * @zh 查找并更新选项
+ * @en Find and update options
+ */
+export interface FindOneAndUpdateOptions {
+    returnDocument?: 'before' | 'after'
+    upsert?: boolean
+}
+
+/**
+ * @zh 索引选项
+ * @en Index options
+ */
+export interface IndexOptions {
+    unique?: boolean
+    sparse?: boolean
+    expireAfterSeconds?: number
+    name?: string
+}
+
+// =============================================================================
+// 集合接口 | Collection Interface
+// =============================================================================
+
+/**
+ * @zh MongoDB 集合接口
+ * @en MongoDB collection interface
+ *
+ * @zh 简化的集合操作接口，与 MongoDB 原生类型解耦
+ * @en Simplified collection interface, decoupled from MongoDB native types
+ */
+export interface IMongoCollection<T extends object> {
+    /**
+     * @zh 集合名称
+     * @en Collection name
+     */
+    readonly name: string
+
+    // =========================================================================
+    // 查询 | Query
+    // =========================================================================
+
+    /**
+     * @zh 查找单条记录
+     * @en Find one document
+     */
+    findOne(filter: object, options?: FindOptions): Promise<T | null>
+
+    /**
+     * @zh 查找多条记录
+     * @en Find documents
+     */
+    find(filter: object, options?: FindOptions): Promise<T[]>
+
+    /**
+     * @zh 统计记录数
+     * @en Count documents
+     */
+    countDocuments(filter?: object): Promise<number>
+
+    // =========================================================================
+    // 创建 | Create
+    // =========================================================================
+
+    /**
+     * @zh 插入单条记录
+     * @en Insert one document
+     */
+    insertOne(doc: T): Promise<InsertOneResult>
+
+    /**
+     * @zh 批量插入
+     * @en Insert many documents
+     */
+    insertMany(docs: T[]): Promise<InsertManyResult>
+
+    // =========================================================================
+    // 更新 | Update
+    // =========================================================================
+
+    /**
+     * @zh 更新单条记录
+     * @en Update one document
+     */
+    updateOne(filter: object, update: object): Promise<UpdateResult>
+
+    /**
+     * @zh 批量更新
+     * @en Update many documents
+     */
+    updateMany(filter: object, update: object): Promise<UpdateResult>
+
+    /**
+     * @zh 查找并更新
+     * @en Find one and update
+     */
+    findOneAndUpdate(
+        filter: object,
+        update: object,
+        options?: FindOneAndUpdateOptions
+    ): Promise<T | null>
+
+    // =========================================================================
+    // 删除 | Delete
+    // =========================================================================
+
+    /**
+     * @zh 删除单条记录
+     * @en Delete one document
+     */
+    deleteOne(filter: object): Promise<DeleteResult>
+
+    /**
+     * @zh 批量删除
+     * @en Delete many documents
+     */
+    deleteMany(filter: object): Promise<DeleteResult>
+
+    // =========================================================================
+    // 索引 | Index
+    // =========================================================================
+
+    /**
+     * @zh 创建索引
+     * @en Create index
+     */
+    createIndex(spec: Record<string, 1 | -1>, options?: IndexOptions): Promise<string>
+}
+
+/**
+ * @zh MongoDB 数据库接口
+ * @en MongoDB database interface
+ */
+export interface IMongoDatabase {
+    /**
+     * @zh 数据库名称
+     * @en Database name
+     */
+    readonly name: string
+
+    /**
+     * @zh 获取集合
+     * @en Get collection
+     */
+    collection<T extends object = object>(name: string): IMongoCollection<T>
+
+    /**
+     * @zh 列出所有集合
+     * @en List all collections
+     */
+    listCollections(): Promise<string[]>
+
+    /**
+     * @zh 删除集合
+     * @en Drop collection
+     */
+    dropCollection(name: string): Promise<boolean>
+}

packages/framework/database-drivers/src/tokens.ts

@@ -0,0 +1,56 @@
+/**
+ * @zh 数据库驱动服务令牌
+ * @en Database driver service tokens
+ *
+ * @zh 用于依赖注入的服务令牌定义
+ * @en Service token definitions for dependency injection
+ */
+
+import type { IMongoConnection } from './drivers/MongoConnection.js'
+import type { IRedisConnection } from './drivers/RedisConnection.js'
+
+// =============================================================================
+// 服务令牌类型 | Service Token Type
+// =============================================================================
+
+/**
+ * @zh 服务令牌
+ * @en Service token
+ */
+export interface ServiceToken<T> {
+    readonly id: string
+    readonly _type?: T
+}
+
+/**
+ * @zh 创建服务令牌
+ * @en Create service token
+ */
+export function createServiceToken<T>(id: string): ServiceToken<T> {
+    return { id }
+}
+
+// =============================================================================
+// 连接令牌 | Connection Tokens
+// =============================================================================
+
+/**
+ * @zh MongoDB 连接令牌
+ * @en MongoDB connection token
+ *
+ * @example
+ * ```typescript
+ * // 注册
+ * services.register(MongoConnectionToken, mongoConnection)
+ *
+ * // 获取
+ * const mongo = services.get(MongoConnectionToken)
+ * ```
+ */
+export const MongoConnectionToken = createServiceToken<IMongoConnection>('database:mongo')
+
+/**
+ * @zh Redis 连接令牌
+ * @en Redis connection token
+ */
+export const RedisConnectionToken = createServiceToken<IRedisConnection>('database:redis')

packages/framework/database-drivers/src/types.ts

@@ -0,0 +1,338 @@
+/**
+ * @zh 数据库驱动核心类型定义
+ * @en Database driver core type definitions
+ */
+
+// =============================================================================
+// 连接状态 | Connection State
+// =============================================================================
+
+/**
+ * @zh 连接状态
+ * @en Connection state
+ */
+export type ConnectionState =
+    | 'disconnected'  // 未连接 | Not connected
+    | 'connecting'    // 连接中 | Connecting
+    | 'connected'     // 已连接 | Connected
+    | 'disconnecting' // 断开中 | Disconnecting
+    | 'error'         // 错误 | Error
+
+// =============================================================================
+// 基础连接接口 | Base Connection Interface
+// =============================================================================
+
+/**
+ * @zh 数据库连接基础接口
+ * @en Base database connection interface
+ */
+export interface IConnection {
+    /**
+     * @zh 连接唯一标识
+     * @en Connection unique identifier
+     */
+    readonly id: string
+
+    /**
+     * @zh 当前连接状态
+     * @en Current connection state
+     */
+    readonly state: ConnectionState
+
+    /**
+     * @zh 建立连接
+     * @en Establish connection
+     */
+    connect(): Promise<void>
+
+    /**
+     * @zh 断开连接
+     * @en Disconnect
+     */
+    disconnect(): Promise<void>
+
+    /**
+     * @zh 检查是否已连接
+     * @en Check if connected
+     */
+    isConnected(): boolean
+
+    /**
+     * @zh 健康检查
+     * @en Health check
+     */
+    ping(): Promise<boolean>
+}
+
+// =============================================================================
+// 连接事件 | Connection Events
+// =============================================================================
+
+/**
+ * @zh 连接事件类型
+ * @en Connection event types
+ */
+export type ConnectionEventType =
+    | 'connected'
+    | 'disconnected'
+    | 'error'
+    | 'reconnecting'
+    | 'reconnected'
+
+/**
+ * @zh 连接事件监听器
+ * @en Connection event listener
+ */
+export type ConnectionEventListener = (event: ConnectionEvent) => void
+
+/**
+ * @zh 连接事件
+ * @en Connection event
+ */
+export interface ConnectionEvent {
+    /**
+     * @zh 事件类型
+     * @en Event type
+     */
+    type: ConnectionEventType
+
+    /**
+     * @zh 连接 ID
+     * @en Connection ID
+     */
+    connectionId: string
+
+    /**
+     * @zh 时间戳
+     * @en Timestamp
+     */
+    timestamp: number
+
+    /**
+     * @zh 错误信息（如果有）
+     * @en Error message (if any)
+     */
+    error?: Error
+}
+
+/**
+ * @zh 可监听事件的连接接口
+ * @en Connection interface with event support
+ */
+export interface IEventableConnection extends IConnection {
+    /**
+     * @zh 添加事件监听
+     * @en Add event listener
+     */
+    on(event: ConnectionEventType, listener: ConnectionEventListener): void
+
+    /**
+     * @zh 移除事件监听
+     * @en Remove event listener
+     */
+    off(event: ConnectionEventType, listener: ConnectionEventListener): void
+
+    /**
+     * @zh 一次性事件监听
+     * @en One-time event listener
+     */
+    once(event: ConnectionEventType, listener: ConnectionEventListener): void
+}
+
+// =============================================================================
+// 连接池配置 | Connection Pool Configuration
+// =============================================================================
+
+/**
+ * @zh 连接池配置
+ * @en Connection pool configuration
+ */
+export interface PoolConfig {
+    /**
+     * @zh 最小连接数
+     * @en Minimum connections
+     */
+    minSize?: number
+
+    /**
+     * @zh 最大连接数
+     * @en Maximum connections
+     */
+    maxSize?: number
+
+    /**
+     * @zh 获取连接超时时间（毫秒）
+     * @en Acquire connection timeout in milliseconds
+     */
+    acquireTimeout?: number
+
+    /**
+     * @zh 空闲连接超时时间（毫秒）
+     * @en Idle connection timeout in milliseconds
+     */
+    idleTimeout?: number
+
+    /**
+     * @zh 连接最大生存时间（毫秒）
+     * @en Maximum connection lifetime in milliseconds
+     */
+    maxLifetime?: number
+}
+
+// =============================================================================
+// 数据库特定配置 | Database Specific Configuration
+// =============================================================================
+
+/**
+ * @zh MongoDB 连接配置
+ * @en MongoDB connection configuration
+ */
+export interface MongoConnectionConfig {
+    /**
+     * @zh 连接字符串
+     * @en Connection string
+     *
+     * @example "mongodb://localhost:27017"
+     * @example "mongodb+srv://user:pass@cluster.mongodb.net"
+     */
+    uri: string
+
+    /**
+     * @zh 数据库名称
+     * @en Database name
+     */
+    database: string
+
+    /**
+     * @zh 连接池配置
+     * @en Pool configuration
+     */
+    pool?: PoolConfig
+
+    /**
+     * @zh 自动重连
+     * @en Auto reconnect
+     */
+    autoReconnect?: boolean
+
+    /**
+     * @zh 重连间隔（毫秒）
+     * @en Reconnect interval in milliseconds
+     */
+    reconnectInterval?: number
+
+    /**
+     * @zh 最大重连次数
+     * @en Maximum reconnect attempts
+     */
+    maxReconnectAttempts?: number
+}
+
+/**
+ * @zh Redis 连接配置
+ * @en Redis connection configuration
+ */
+export interface RedisConnectionConfig {
+    /**
+     * @zh 主机地址
+     * @en Host address
+     */
+    host?: string
+
+    /**
+     * @zh 端口
+     * @en Port
+     */
+    port?: number
+
+    /**
+     * @zh 密码
+     * @en Password
+     */
+    password?: string
+
+    /**
+     * @zh 数据库索引
+     * @en Database index
+     */
+    db?: number
+
+    /**
+     * @zh 连接字符串（优先于其他配置）
+     * @en Connection URL (takes precedence over other options)
+     */
+    url?: string
+
+    /**
+     * @zh 键前缀
+     * @en Key prefix
+     */
+    keyPrefix?: string
+
+    /**
+     * @zh 自动重连
+     * @en Auto reconnect
+     */
+    autoReconnect?: boolean
+}
+
+// =============================================================================
+// 错误类型 | Error Types
+// =============================================================================
+
+/**
+ * @zh 数据库错误代码
+ * @en Database error codes
+ */
+export type DatabaseErrorCode =
+    | 'CONNECTION_FAILED'
+    | 'CONNECTION_TIMEOUT'
+    | 'CONNECTION_CLOSED'
+    | 'AUTHENTICATION_FAILED'
+    | 'POOL_EXHAUSTED'
+    | 'QUERY_FAILED'
+    | 'DUPLICATE_KEY'
+    | 'NOT_FOUND'
+    | 'VALIDATION_ERROR'
+    | 'UNKNOWN'
+
+/**
+ * @zh 数据库错误
+ * @en Database error
+ */
+export class DatabaseError extends Error {
+    constructor(
+        message: string,
+        public readonly code: DatabaseErrorCode,
+        public readonly cause?: Error
+    ) {
+        super(message)
+        this.name = 'DatabaseError'
+    }
+}
+
+/**
+ * @zh 连接错误
+ * @en Connection error
+ */
+export class ConnectionError extends DatabaseError {
+    constructor(message: string, code: DatabaseErrorCode = 'CONNECTION_FAILED', cause?: Error) {
+        super(message, code, cause)
+        this.name = 'ConnectionError'
+    }
+}
+
+/**
+ * @zh 重复键错误
+ * @en Duplicate key error
+ */
+export class DuplicateKeyError extends DatabaseError {
+    constructor(
+        message: string,
+        public readonly key: string,
+        cause?: Error
+    ) {
+        super(message, 'DUPLICATE_KEY', cause)
+        this.name = 'DuplicateKeyError'
+    }
+}

packages/framework/database-drivers/tsconfig.json

@@ -0,0 +1,10 @@
+{
+    "extends": "../../../tsconfig.base.json",
+    "compilerOptions": {
+        "outDir": "./dist",
+        "rootDir": "./src",
+        "declarationDir": "./dist"
+    },
+    "include": ["src/**/*"],
+    "exclude": ["node_modules", "dist"]
+}

packages/framework/database-drivers/tsup.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+    entry: ['src/index.ts'],
+    format: ['esm'],
+    dts: true,
+    clean: true,
+    sourcemap: true,
+    external: ['mongodb', 'ioredis'],
+    treeshake: true,
+});

packages/framework/database/CHANGELOG.md

@@ -0,0 +1,65 @@
+# @esengine/database
+
+## 1.1.1
+
+### Patch Changes
+
+- [#412](https://github.com/esengine/esengine/pull/412) [`85171a0`](https://github.com/esengine/esengine/commit/85171a0a5c073ef7883705ee4daaca8bb0218f20) Thanks [@esengine](https://github.com/esengine)! - fix: include dist directory in npm package
+
+    Previous 1.1.0 release was missing the compiled dist directory.
+
+- Updated dependencies [[`85171a0`](https://github.com/esengine/esengine/commit/85171a0a5c073ef7883705ee4daaca8bb0218f20)]:
+    - @esengine/database-drivers@1.1.1
+
+## 1.1.0
+
+### Minor Changes
+
+- [#410](https://github.com/esengine/esengine/pull/410) [`71022ab`](https://github.com/esengine/esengine/commit/71022abc99ad4a1b349f19f4ccf1e0a2a0923dfa) Thanks [@esengine](https://github.com/esengine)! - feat: add database layer architecture
+
+    Added new database packages with layered architecture:
+
+    **@esengine/database-drivers (Layer 1)**
+    - MongoDB connection with pool management, auto-reconnect, events
+    - Redis connection with auto-reconnect, key prefix
+    - Type-safe `IMongoCollection<T>` interface decoupled from mongodb types
+    - Service tokens for dependency injection (`MongoConnectionToken`, `RedisConnectionToken`)
+
+    **@esengine/database (Layer 2)**
+    - Generic `Repository<T>` with CRUD, pagination, soft delete
+    - `UserRepository` with registration, authentication, role management
+    - Password hashing utilities using scrypt
+    - Query operators: `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$like`, `$regex`
+
+    **@esengine/transaction**
+    - Refactored `MongoStorage` to use shared connection from `@esengine/database-drivers`
+    - Removed factory pattern in favor of shared connection (breaking change)
+    - Simplified API: `createMongoStorage(connection, options?)`
+
+    Example usage:
+
+    ```typescript
+    import { createMongoConnection } from '@esengine/database-drivers';
+    import { UserRepository } from '@esengine/database';
+    import { createMongoStorage, TransactionManager } from '@esengine/transaction';
+
+    // Create shared connection
+    const mongo = createMongoConnection({
+        uri: 'mongodb://localhost:27017',
+        database: 'game'
+    });
+    await mongo.connect();
+
+    // Use for database operations
+    const userRepo = new UserRepository(mongo);
+    await userRepo.register({ username: 'john', password: '123456' });
+
+    // Use for transactions (same connection)
+    const storage = createMongoStorage(mongo);
+    const txManager = new TransactionManager({ storage });
+    ```
+
+### Patch Changes
+
+- Updated dependencies [[`71022ab`](https://github.com/esengine/esengine/commit/71022abc99ad4a1b349f19f4ccf1e0a2a0923dfa)]:
+    - @esengine/database-drivers@1.1.0

packages/framework/database/module.json

@@ -0,0 +1,23 @@
+{
+    "id": "database",
+    "name": "@esengine/database",
+    "globalKey": "database",
+    "displayName": "Database",
+    "description": "数据库 CRUD 操作和仓库模式，支持用户管理、通用数据存储 | Database CRUD operations and repository pattern with user management and generic data storage",
+    "version": "1.0.0",
+    "category": "Infrastructure",
+    "icon": "Database",
+    "tags": ["database", "crud", "repository", "user"],
+    "isCore": false,
+    "defaultEnabled": true,
+    "isEngineModule": false,
+    "canContainContent": false,
+    "platforms": ["server"],
+    "dependencies": ["database-drivers"],
+    "exports": {
+        "components": [],
+        "systems": []
+    },
+    "requiresWasm": false,
+    "outputPath": "dist/index.js"
+}

packages/framework/database/package.json

@@ -0,0 +1,37 @@
+{
+    "name": "@esengine/database",
+    "version": "1.1.1",
+    "description": "Database CRUD operations and repositories for ESEngine | ESEngine 数据库 CRUD 操作和仓库",
+    "type": "module",
+    "main": "./dist/index.js",
+    "module": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "import": "./dist/index.js",
+            "types": "./dist/index.d.ts"
+        }
+    },
+    "files": [
+        "dist",
+        "module.json"
+    ],
+    "scripts": {
+        "build": "tsup",
+        "build:watch": "tsup --watch",
+        "type-check": "tsc --noEmit",
+        "clean": "rimraf dist"
+    },
+    "dependencies": {
+        "@esengine/database-drivers": "workspace:*"
+    },
+    "devDependencies": {
+        "@types/node": "^20.0.0",
+        "tsup": "^8.0.0",
+        "typescript": "^5.8.0",
+        "rimraf": "^5.0.0"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}

packages/framework/database/src/Repository.ts

@@ -0,0 +1,313 @@
+/**
+ * @zh MongoDB 仓库实现
+ * @en MongoDB repository implementation
+ *
+ * @zh 基于 MongoDB 的通用仓库，支持 CRUD、分页、软删除
+ * @en Generic MongoDB repository with CRUD, pagination, and soft delete support
+ */
+
+import { randomUUID } from 'crypto'
+import type { IMongoConnection, IMongoCollection } from '@esengine/database-drivers'
+import type {
+    BaseEntity,
+    IRepository,
+    PaginatedResult,
+    PaginationParams,
+    QueryOptions,
+    WhereCondition
+} from './types.js'
+
+/**
+ * @zh MongoDB 仓库基类
+ * @en MongoDB repository base class
+ *
+ * @example
+ * ```typescript
+ * interface Player extends BaseEntity {
+ *     name: string
+ *     score: number
+ * }
+ *
+ * class PlayerRepository extends Repository<Player> {
+ *     constructor(connection: IMongoConnection) {
+ *         super(connection, 'players')
+ *     }
+ *
+ *     async findTopPlayers(limit: number): Promise<Player[]> {
+ *         return this.findMany({
+ *             sort: { score: 'desc' },
+ *             limit,
+ *         })
+ *     }
+ * }
+ * ```
+ */
+export class Repository<T extends BaseEntity> implements IRepository<T> {
+    protected readonly _collection: IMongoCollection<T>
+
+    constructor(
+        protected readonly connection: IMongoConnection,
+        public readonly collectionName: string,
+        protected readonly enableSoftDelete: boolean = false
+    ) {
+        this._collection = connection.collection<T>(collectionName)
+    }
+
+    // =========================================================================
+    // 查询 | Query
+    // =========================================================================
+
+    async findById(id: string): Promise<T | null> {
+        const filter = this._buildFilter({ where: { id } as WhereCondition<T> })
+        return this._collection.findOne(filter)
+    }
+
+    async findOne(options?: QueryOptions<T>): Promise<T | null> {
+        const filter = this._buildFilter(options)
+        const sort = this._buildSort(options)
+        return this._collection.findOne(filter, { sort })
+    }
+
+    async findMany(options?: QueryOptions<T>): Promise<T[]> {
+        const filter = this._buildFilter(options)
+        const sort = this._buildSort(options)
+        return this._collection.find(filter, {
+            sort,
+            skip: options?.offset,
+            limit: options?.limit
+        })
+    }
+
+    async findPaginated(
+        pagination: PaginationParams,
+        options?: Omit<QueryOptions<T>, 'limit' | 'offset'>
+    ): Promise<PaginatedResult<T>> {
+        const { page, pageSize } = pagination
+        const offset = (page - 1) * pageSize
+
+        const [data, total] = await Promise.all([
+            this.findMany({ ...options, limit: pageSize, offset }),
+            this.count(options)
+        ])
+
+        const totalPages = Math.ceil(total / pageSize)
+
+        return {
+            data,
+            total,
+            page,
+            pageSize,
+            totalPages,
+            hasNext: page < totalPages,
+            hasPrev: page > 1
+        }
+    }
+
+    async count(options?: QueryOptions<T>): Promise<number> {
+        const filter = this._buildFilter(options)
+        return this._collection.countDocuments(filter)
+    }
+
+    async exists(options: QueryOptions<T>): Promise<boolean> {
+        const count = await this.count({ ...options, limit: 1 })
+        return count > 0
+    }
+
+    // =========================================================================
+    // 创建 | Create
+    // =========================================================================
+
+    async create(data: Omit<T, 'id' | 'createdAt' | 'updatedAt'> & { id?: string }): Promise<T> {
+        const now = new Date()
+        const entity = {
+            ...data,
+            id: data.id || randomUUID(),
+            createdAt: now,
+            updatedAt: now
+        } as T
+
+        await this._collection.insertOne(entity)
+        return entity
+    }
+
+    async createMany(
+        data: Array<Omit<T, 'id' | 'createdAt' | 'updatedAt'> & { id?: string }>
+    ): Promise<T[]> {
+        if (data.length === 0) return []
+
+        const now = new Date()
+        const entities = data.map(item => ({
+            ...item,
+            id: item.id || randomUUID(),
+            createdAt: now,
+            updatedAt: now
+        })) as T[]
+
+        await this._collection.insertMany(entities)
+        return entities
+    }
+
+    // =========================================================================
+    // 更新 | Update
+    // =========================================================================
+
+    async update(
+        id: string,
+        data: Partial<Omit<T, 'id' | 'createdAt' | 'updatedAt'>>
+    ): Promise<T | null> {
+        const filter = this._buildFilter({ where: { id } as WhereCondition<T> })
+        return this._collection.findOneAndUpdate(
+            filter,
+            { $set: { ...data, updatedAt: new Date() } },
+            { returnDocument: 'after' }
+        )
+    }
+
+    // =========================================================================
+    // 删除 | Delete
+    // =========================================================================
+
+    async delete(id: string): Promise<boolean> {
+        if (this.enableSoftDelete) {
+            const result = await this._collection.updateOne(
+                { id },
+                { $set: { deletedAt: new Date(), updatedAt: new Date() } }
+            )
+            return result.modifiedCount > 0
+        }
+
+        const result = await this._collection.deleteOne({ id })
+        return result.deletedCount > 0
+    }
+
+    async deleteMany(options: QueryOptions<T>): Promise<number> {
+        const filter = this._buildFilter(options)
+
+        if (this.enableSoftDelete) {
+            const result = await this._collection.updateMany(filter, {
+                $set: { deletedAt: new Date(), updatedAt: new Date() }
+            })
+            return result.modifiedCount
+        }
+
+        const result = await this._collection.deleteMany(filter)
+        return result.deletedCount
+    }
+
+    // =========================================================================
+    // 软删除恢复 | Soft Delete Recovery
+    // =========================================================================
+
+    /**
+     * @zh 恢复软删除的记录
+     * @en Restore soft deleted record
+     */
+    async restore(id: string): Promise<T | null> {
+        if (!this.enableSoftDelete) {
+            throw new Error('Soft delete is not enabled for this repository')
+        }
+
+        return this._collection.findOneAndUpdate(
+            { id, deletedAt: { $ne: null } },
+            { $set: { deletedAt: null, updatedAt: new Date() } },
+            { returnDocument: 'after' }
+        )
+    }
+
+    // =========================================================================
+    // 内部方法 | Internal Methods
+    // =========================================================================
+
+    /**
+     * @zh 构建过滤条件
+     * @en Build filter
+     */
+    protected _buildFilter(options?: QueryOptions<T>): object {
+        const filter: Record<string, unknown> = {}
+
+        if (this.enableSoftDelete && !options?.includeSoftDeleted) {
+            filter['deletedAt'] = null
+        }
+
+        if (!options?.where) {
+            return filter
+        }
+
+        return { ...filter, ...this._convertWhere(options.where) }
+    }
+
+    /**
+     * @zh 转换 where 条件
+     * @en Convert where condition
+     */
+    protected _convertWhere(where: WhereCondition<T>): object {
+        const result: Record<string, unknown> = {}
+
+        for (const [key, value] of Object.entries(where)) {
+            if (key === '$or' && Array.isArray(value)) {
+                result['$or'] = value.map(v => this._convertWhere(v as WhereCondition<T>))
+                continue
+            }
+
+            if (key === '$and' && Array.isArray(value)) {
+                result['$and'] = value.map(v => this._convertWhere(v as WhereCondition<T>))
+                continue
+            }
+
+            if (value === undefined) continue
+
+            if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+                const ops = value as Record<string, unknown>
+                const mongoOps: Record<string, unknown> = {}
+
+                if ('$eq' in ops) mongoOps['$eq'] = ops.$eq
+                if ('$ne' in ops) mongoOps['$ne'] = ops.$ne
+                if ('$gt' in ops) mongoOps['$gt'] = ops.$gt
+                if ('$gte' in ops) mongoOps['$gte'] = ops.$gte
+                if ('$lt' in ops) mongoOps['$lt'] = ops.$lt
+                if ('$lte' in ops) mongoOps['$lte'] = ops.$lte
+                if ('$in' in ops) mongoOps['$in'] = ops.$in
+                if ('$nin' in ops) mongoOps['$nin'] = ops.$nin
+                if ('$like' in ops) {
+                    const pattern = (ops.$like as string).replace(/%/g, '.*').replace(/_/g, '.')
+                    mongoOps['$regex'] = new RegExp(`^${pattern}$`, 'i')
+                }
+                if ('$regex' in ops) {
+                    mongoOps['$regex'] = new RegExp(ops.$regex as string, 'i')
+                }
+
+                result[key] = Object.keys(mongoOps).length > 0 ? mongoOps : value
+            } else {
+                result[key] = value
+            }
+        }
+
+        return result
+    }
+
+    /**
+     * @zh 构建排序条件
+     * @en Build sort condition
+     */
+    protected _buildSort(options?: QueryOptions<T>): Record<string, 1 | -1> | undefined {
+        if (!options?.sort) return undefined
+
+        const result: Record<string, 1 | -1> = {}
+        for (const [key, direction] of Object.entries(options.sort)) {
+            result[key] = direction === 'desc' ? -1 : 1
+        }
+        return result
+    }
+}
+
+/**
+ * @zh 创建仓库实例
+ * @en Create repository instance
+ */
+export function createRepository<T extends BaseEntity>(
+    connection: IMongoConnection,
+    collectionName: string,
+    enableSoftDelete = false
+): Repository<T> {
+    return new Repository<T>(connection, collectionName, enableSoftDelete)
+}

packages/framework/database/src/UserRepository.ts

@@ -0,0 +1,335 @@
+/**
+ * @zh 用户仓库
+ * @en User repository
+ *
+ * @zh 提供用户管理的常用方法，包括注册、登录、角色管理等
+ * @en Provides common user management methods including registration, login, role management
+ */
+
+import type { IMongoConnection } from '@esengine/database-drivers'
+import { Repository } from './Repository.js'
+import { hashPassword, verifyPassword } from './password.js'
+import type { UserEntity } from './types.js'
+
+/**
+ * @zh 创建用户参数
+ * @en Create user parameters
+ */
+export interface CreateUserParams {
+    /**
+     * @zh 用户名
+     * @en Username
+     */
+    username: string
+
+    /**
+     * @zh 明文密码
+     * @en Plain text password
+     */
+    password: string
+
+    /**
+     * @zh 邮箱
+     * @en Email
+     */
+    email?: string
+
+    /**
+     * @zh 角色列表
+     * @en Role list
+     */
+    roles?: string[]
+
+    /**
+     * @zh 额外数据
+     * @en Additional metadata
+     */
+    metadata?: Record<string, unknown>
+}
+
+/**
+ * @zh 用户信息（不含密码）
+ * @en User info (without password)
+ */
+export type SafeUser = Omit<UserEntity, 'passwordHash'>
+
+/**
+ * @zh 用户仓库
+ * @en User repository
+ *
+ * @example
+ * ```typescript
+ * const mongo = createMongoConnection({ uri: '...', database: 'game' })
+ * await mongo.connect()
+ *
+ * const userRepo = new UserRepository(mongo)
+ *
+ * // 注册用户
+ * const user = await userRepo.register({
+ *     username: 'player1',
+ *     password: 'securePassword123',
+ *     email: 'player1@example.com',
+ * })
+ *
+ * // 验证登录
+ * const result = await userRepo.authenticate('player1', 'securePassword123')
+ * if (result) {
+ *     console.log('登录成功:', result.username)
+ * }
+ * ```
+ */
+export class UserRepository extends Repository<UserEntity> {
+    constructor(connection: IMongoConnection, collectionName = 'users') {
+        super(connection, collectionName, true)
+    }
+
+    // =========================================================================
+    // 查询 | Query
+    // =========================================================================
+
+    /**
+     * @zh 根据用户名查找用户
+     * @en Find user by username
+     */
+    async findByUsername(username: string): Promise<UserEntity | null> {
+        return this.findOne({ where: { username } })
+    }
+
+    /**
+     * @zh 根据邮箱查找用户
+     * @en Find user by email
+     */
+    async findByEmail(email: string): Promise<UserEntity | null> {
+        return this.findOne({ where: { email } })
+    }
+
+    /**
+     * @zh 检查用户名是否存在
+     * @en Check if username exists
+     */
+    async usernameExists(username: string): Promise<boolean> {
+        return this.exists({ where: { username } })
+    }
+
+    /**
+     * @zh 检查邮箱是否存在
+     * @en Check if email exists
+     */
+    async emailExists(email: string): Promise<boolean> {
+        return this.exists({ where: { email } })
+    }
+
+    // =========================================================================
+    // 注册与认证 | Registration & Authentication
+    // =========================================================================
+
+    /**
+     * @zh 注册新用户
+     * @en Register new user
+     *
+     * @param params - @zh 创建用户参数 @en Create user parameters
+     * @returns @zh 创建的用户（不含密码哈希）@en Created user (without password hash)
+     * @throws @zh 如果用户名已存在 @en If username already exists
+     */
+    async register(params: CreateUserParams): Promise<SafeUser> {
+        const { username, password, email, roles, metadata } = params
+
+        if (await this.usernameExists(username)) {
+            throw new Error('Username already exists')
+        }
+
+        if (email && (await this.emailExists(email))) {
+            throw new Error('Email already exists')
+        }
+
+        const passwordHash = await hashPassword(password)
+
+        const user = await this.create({
+            username,
+            passwordHash,
+            email,
+            roles: roles ?? ['user'],
+            isActive: true,
+            metadata
+        })
+
+        return this.toSafeUser(user)
+    }
+
+    /**
+     * @zh 验证用户登录
+     * @en Authenticate user login
+     *
+     * @param username - @zh 用户名 @en Username
+     * @param password - @zh 明文密码 @en Plain text password
+     * @returns @zh 验证成功返回用户信息（不含密码），失败返回 null @en Returns user info on success, null on failure
+     */
+    async authenticate(username: string, password: string): Promise<SafeUser | null> {
+        const user = await this.findByUsername(username)
+        if (!user || !user.isActive) {
+            return null
+        }
+
+        const isValid = await verifyPassword(password, user.passwordHash)
+        if (!isValid) {
+            return null
+        }
+
+        await this.update(user.id, { lastLoginAt: new Date() })
+
+        return this.toSafeUser(user)
+    }
+
+    // =========================================================================
+    // 密码管理 | Password Management
+    // =========================================================================
+
+    /**
+     * @zh 修改密码
+     * @en Change password
+     *
+     * @param userId - @zh 用户 ID @en User ID
+     * @param oldPassword - @zh 旧密码 @en Old password
+     * @param newPassword - @zh 新密码 @en New password
+     * @returns @zh 是否修改成功 @en Whether change was successful
+     */
+    async changePassword(
+        userId: string,
+        oldPassword: string,
+        newPassword: string
+    ): Promise<boolean> {
+        const user = await this.findById(userId)
+        if (!user) {
+            return false
+        }
+
+        const isValid = await verifyPassword(oldPassword, user.passwordHash)
+        if (!isValid) {
+            return false
+        }
+
+        const newHash = await hashPassword(newPassword)
+        const result = await this.update(userId, { passwordHash: newHash })
+        return result !== null
+    }
+
+    /**
+     * @zh 重置密码（管理员操作）
+     * @en Reset password (admin operation)
+     *
+     * @param userId - @zh 用户 ID @en User ID
+     * @param newPassword - @zh 新密码 @en New password
+     */
+    async resetPassword(userId: string, newPassword: string): Promise<boolean> {
+        const user = await this.findById(userId)
+        if (!user) {
+            return false
+        }
+
+        const newHash = await hashPassword(newPassword)
+        const result = await this.update(userId, { passwordHash: newHash })
+        return result !== null
+    }
+
+    // =========================================================================
+    // 角色管理 | Role Management
+    // =========================================================================
+
+    /**
+     * @zh 添加角色
+     * @en Add role to user
+     */
+    async addRole(userId: string, role: string): Promise<boolean> {
+        const user = await this.findById(userId)
+        if (!user) {
+            return false
+        }
+
+        const roles = user.roles ?? []
+        if (!roles.includes(role)) {
+            roles.push(role)
+            await this.update(userId, { roles })
+        }
+        return true
+    }
+
+    /**
+     * @zh 移除角色
+     * @en Remove role from user
+     */
+    async removeRole(userId: string, role: string): Promise<boolean> {
+        const user = await this.findById(userId)
+        if (!user) {
+            return false
+        }
+
+        const roles = (user.roles ?? []).filter(r => r !== role)
+        await this.update(userId, { roles })
+        return true
+    }
+
+    /**
+     * @zh 检查用户是否拥有角色
+     * @en Check if user has role
+     */
+    async hasRole(userId: string, role: string): Promise<boolean> {
+        const user = await this.findById(userId)
+        return user?.roles?.includes(role) ?? false
+    }
+
+    /**
+     * @zh 检查用户是否拥有任一角色
+     * @en Check if user has any of the roles
+     */
+    async hasAnyRole(userId: string, roles: string[]): Promise<boolean> {
+        const user = await this.findById(userId)
+        if (!user?.roles) return false
+        return roles.some(role => user.roles.includes(role))
+    }
+
+    // =========================================================================
+    // 状态管理 | Status Management
+    // =========================================================================
+
+    /**
+     * @zh 禁用用户
+     * @en Deactivate user
+     */
+    async deactivate(userId: string): Promise<boolean> {
+        const result = await this.update(userId, { isActive: false })
+        return result !== null
+    }
+
+    /**
+     * @zh 启用用户
+     * @en Activate user
+     */
+    async activate(userId: string): Promise<boolean> {
+        const result = await this.update(userId, { isActive: true })
+        return result !== null
+    }
+
+    // =========================================================================
+    // 内部方法 | Internal Methods
+    // =========================================================================
+
+    /**
+     * @zh 移除密码哈希
+     * @en Remove password hash
+     */
+    private toSafeUser(user: UserEntity): SafeUser {
+        const { passwordHash, ...safeUser } = user
+        return safeUser
+    }
+}
+
+/**
+ * @zh 创建用户仓库
+ * @en Create user repository
+ */
+export function createUserRepository(
+    connection: IMongoConnection,
+    collectionName = 'users'
+): UserRepository {
+    return new UserRepository(connection, collectionName)
+}

packages/framework/database/src/index.ts

@@ -0,0 +1,152 @@
+/**
+ * @zh @esengine/database 数据库操作层
+ * @en @esengine/database Database Operations Layer
+ *
+ * @zh 提供通用的数据库 CRUD 操作、仓库模式、用户管理等功能
+ * @en Provides generic database CRUD operations, repository pattern, user management
+ *
+ * @example
+ * ```typescript
+ * import { createMongoConnection } from '@esengine/database-drivers'
+ * import {
+ *     Repository,
+ *     UserRepository,
+ *     createUserRepository,
+ *     hashPassword,
+ *     verifyPassword,
+ * } from '@esengine/database'
+ *
+ * // 1. 创建连接（来自 database-drivers）
+ * const mongo = createMongoConnection({
+ *     uri: 'mongodb://localhost:27017',
+ *     database: 'game',
+ * })
+ * await mongo.connect()
+ *
+ * // 2. 使用用户仓库
+ * const userRepo = createUserRepository(mongo)
+ *
+ * // 注册
+ * const user = await userRepo.register({
+ *     username: 'player1',
+ *     password: 'securePassword123',
+ * })
+ *
+ * // 登录
+ * const authUser = await userRepo.authenticate('player1', 'securePassword123')
+ *
+ * // 3. 自定义仓库
+ * interface Player extends BaseEntity {
+ *     name: string
+ *     score: number
+ *     level: number
+ * }
+ *
+ * class PlayerRepository extends Repository<Player> {
+ *     constructor(connection: IMongoConnection) {
+ *         super(connection, 'players')
+ *     }
+ *
+ *     async findTopPlayers(limit = 10): Promise<Player[]> {
+ *         return this.findMany({
+ *             sort: { score: 'desc' },
+ *             limit,
+ *         })
+ *     }
+ *
+ *     async addScore(playerId: string, points: number): Promise<Player | null> {
+ *         const player = await this.findById(playerId)
+ *         if (!player) return null
+ *         return this.update(playerId, { score: player.score + points })
+ *     }
+ * }
+ *
+ * // 4. 分页查询
+ * const result = await userRepo.findPaginated(
+ *     { page: 1, pageSize: 20 },
+ *     { where: { isActive: true }, sort: { createdAt: 'desc' } }
+ * )
+ * console.log(`第 ${result.page}/${result.totalPages} 页，共 ${result.total} 条`)
+ * ```
+ */
+
+// =============================================================================
+// Types | 类型
+// =============================================================================
+
+export type {
+    BaseEntity,
+    SoftDeleteEntity,
+    ComparisonOperators,
+    WhereCondition,
+    SortDirection,
+    SortCondition,
+    QueryOptions,
+    PaginationParams,
+    PaginatedResult,
+    IRepository,
+    UserEntity
+} from './types.js'
+
+// =============================================================================
+// Repository | 仓库
+// =============================================================================
+
+export { Repository, createRepository } from './Repository.js'
+
+// =============================================================================
+// User Repository | 用户仓库
+// =============================================================================
+
+export {
+    UserRepository,
+    createUserRepository,
+    type CreateUserParams,
+    type SafeUser
+} from './UserRepository.js'
+
+// =============================================================================
+// Password | 密码工具
+// =============================================================================
+
+export {
+    hashPassword,
+    verifyPassword,
+    checkPasswordStrength,
+    type PasswordHashConfig,
+    type PasswordStrength,
+    type PasswordStrengthResult
+} from './password.js'
+
+// =============================================================================
+// Tokens | 服务令牌
+// =============================================================================
+
+export {
+    MongoConnectionToken,
+    RedisConnectionToken,
+    UserRepositoryToken,
+    createServiceToken,
+    type ServiceToken
+} from './tokens.js'
+
+// =============================================================================
+// Re-exports from database-drivers | 从 database-drivers 重新导出
+// =============================================================================
+
+export type {
+    IMongoConnection,
+    IRedisConnection,
+    MongoConnectionConfig,
+    RedisConnectionConfig,
+    ConnectionState,
+    DatabaseErrorCode
+} from '@esengine/database-drivers'
+
+export {
+    createMongoConnection,
+    createRedisConnection,
+    DatabaseError,
+    ConnectionError,
+    DuplicateKeyError
+} from '@esengine/database-drivers'

packages/framework/database/src/password.ts

@@ -0,0 +1,189 @@
+/**
+ * @zh 密码加密工具
+ * @en Password hashing utilities
+ *
+ * @zh 使用 Node.js 内置的 crypto 模块实现安全的密码哈希
+ * @en Uses Node.js built-in crypto module for secure password hashing
+ */
+
+import { randomBytes, scrypt, timingSafeEqual } from 'crypto'
+import { promisify } from 'util'
+
+const scryptAsync = promisify(scrypt)
+
+/**
+ * @zh 密码哈希配置
+ * @en Password hash configuration
+ */
+export interface PasswordHashConfig {
+    /**
+     * @zh 盐的字节长度（默认 16）
+     * @en Salt length in bytes (default 16)
+     */
+    saltLength?: number
+
+    /**
+     * @zh scrypt 密钥长度（默认 64）
+     * @en scrypt key length (default 64)
+     */
+    keyLength?: number
+}
+
+const DEFAULT_CONFIG: Required<PasswordHashConfig> = {
+    saltLength: 16,
+    keyLength: 64
+}
+
+/**
+ * @zh 对密码进行哈希处理
+ * @en Hash a password
+ *
+ * @param password - @zh 明文密码 @en Plain text password
+ * @param config - @zh 哈希配置 @en Hash configuration
+ * @returns @zh 格式为 "salt:hash" 的哈希字符串 @en Hash string in "salt:hash" format
+ *
+ * @example
+ * ```typescript
+ * const hashedPassword = await hashPassword('myPassword123')
+ * // 存储 hashedPassword 到数据库
+ * ```
+ */
+export async function hashPassword(
+    password: string,
+    config?: PasswordHashConfig
+): Promise<string> {
+    const { saltLength, keyLength } = { ...DEFAULT_CONFIG, ...config }
+
+    const salt = randomBytes(saltLength).toString('hex')
+    const derivedKey = (await scryptAsync(password, salt, keyLength)) as Buffer
+
+    return `${salt}:${derivedKey.toString('hex')}`
+}
+
+/**
+ * @zh 验证密码是否正确
+ * @en Verify if a password is correct
+ *
+ * @param password - @zh 明文密码 @en Plain text password
+ * @param hashedPassword - @zh 存储的哈希密码 @en Stored hashed password
+ * @param config - @zh 哈希配置 @en Hash configuration
+ * @returns @zh 密码是否匹配 @en Whether the password matches
+ *
+ * @example
+ * ```typescript
+ * const isValid = await verifyPassword('myPassword123', storedHash)
+ * if (isValid) {
+ *     // 登录成功
+ * }
+ * ```
+ */
+export async function verifyPassword(
+    password: string,
+    hashedPassword: string,
+    config?: PasswordHashConfig
+): Promise<boolean> {
+    const { keyLength } = { ...DEFAULT_CONFIG, ...config }
+
+    const [salt, storedHash] = hashedPassword.split(':')
+    if (!salt || !storedHash) {
+        return false
+    }
+
+    try {
+        const derivedKey = (await scryptAsync(password, salt, keyLength)) as Buffer
+        const storedBuffer = Buffer.from(storedHash, 'hex')
+
+        return timingSafeEqual(derivedKey, storedBuffer)
+    } catch {
+        return false
+    }
+}
+
+/**
+ * @zh 密码强度等级
+ * @en Password strength level
+ */
+export type PasswordStrength = 'weak' | 'fair' | 'good' | 'strong'
+
+/**
+ * @zh 密码强度检查结果
+ * @en Password strength check result
+ */
+export interface PasswordStrengthResult {
+    /**
+     * @zh 强度分数 (0-6)
+     * @en Strength score (0-6)
+     */
+    score: number
+
+    /**
+     * @zh 强度等级
+     * @en Strength level
+     */
+    level: PasswordStrength
+
+    /**
+     * @zh 改进建议
+     * @en Improvement suggestions
+     */
+    feedback: string[]
+}
+
+/**
+ * @zh 检查密码强度
+ * @en Check password strength
+ *
+ * @param password - @zh 明文密码 @en Plain text password
+ * @returns @zh 密码强度信息 @en Password strength information
+ */
+export function checkPasswordStrength(password: string): PasswordStrengthResult {
+    const feedback: string[] = []
+    let score = 0
+
+    if (password.length >= 8) {
+        score += 1
+    } else {
+        feedback.push('Password should be at least 8 characters')
+    }
+
+    if (password.length >= 12) {
+        score += 1
+    }
+
+    if (/[a-z]/.test(password)) {
+        score += 1
+    } else {
+        feedback.push('Password should contain lowercase letters')
+    }
+
+    if (/[A-Z]/.test(password)) {
+        score += 1
+    } else {
+        feedback.push('Password should contain uppercase letters')
+    }
+
+    if (/[0-9]/.test(password)) {
+        score += 1
+    } else {
+        feedback.push('Password should contain numbers')
+    }
+
+    if (/[^a-zA-Z0-9]/.test(password)) {
+        score += 1
+    } else {
+        feedback.push('Password should contain special characters')
+    }
+
+    let level: PasswordStrength
+    if (score <= 2) {
+        level = 'weak'
+    } else if (score <= 3) {
+        level = 'fair'
+    } else if (score <= 4) {
+        level = 'good'
+    } else {
+        level = 'strong'
+    }
+
+    return { score, level, feedback }
+}

packages/framework/database/src/tokens.ts

@@ -0,0 +1,17 @@
+/**
+ * @zh 数据库服务令牌
+ * @en Database service tokens
+ */
+
+import type { ServiceToken, createServiceToken as createToken } from '@esengine/database-drivers'
+import type { UserRepository } from './UserRepository.js'
+
+// Re-export from database-drivers for convenience
+export { MongoConnectionToken, RedisConnectionToken, createServiceToken } from '@esengine/database-drivers'
+export type { ServiceToken } from '@esengine/database-drivers'
+
+/**
+ * @zh 用户仓库令牌
+ * @en User repository token
+ */
+export const UserRepositoryToken: ServiceToken<UserRepository> = { id: 'database:userRepository' }

packages/framework/database/src/types.ts

@@ -0,0 +1,333 @@
+/**
+ * @zh 数据库核心类型定义
+ * @en Database core type definitions
+ */
+
+// =============================================================================
+// 实体类型 | Entity Types
+// =============================================================================
+
+/**
+ * @zh 基础实体接口
+ * @en Base entity interface
+ */
+export interface BaseEntity {
+    /**
+     * @zh 实体唯一标识
+     * @en Entity unique identifier
+     */
+    id: string
+
+    /**
+     * @zh 创建时间
+     * @en Creation timestamp
+     */
+    createdAt?: Date
+
+    /**
+     * @zh 更新时间
+     * @en Update timestamp
+     */
+    updatedAt?: Date
+}
+
+/**
+ * @zh 软删除实体接口
+ * @en Soft delete entity interface
+ */
+export interface SoftDeleteEntity extends BaseEntity {
+    /**
+     * @zh 删除时间（null 表示未删除）
+     * @en Deletion timestamp (null means not deleted)
+     */
+    deletedAt?: Date | null
+}
+
+// =============================================================================
+// 查询类型 | Query Types
+// =============================================================================
+
+/**
+ * @zh 比较操作符
+ * @en Comparison operators
+ */
+export interface ComparisonOperators<T> {
+    $eq?: T
+    $ne?: T
+    $gt?: T
+    $gte?: T
+    $lt?: T
+    $lte?: T
+    $in?: T[]
+    $nin?: T[]
+    $like?: string
+    $regex?: string
+}
+
+/**
+ * @zh 查询条件
+ * @en Query condition
+ */
+export type WhereCondition<T> = {
+    [K in keyof T]?: T[K] | ComparisonOperators<T[K]>
+} & {
+    $or?: WhereCondition<T>[]
+    $and?: WhereCondition<T>[]
+}
+
+/**
+ * @zh 排序方向
+ * @en Sort direction
+ */
+export type SortDirection = 'asc' | 'desc'
+
+/**
+ * @zh 排序条件
+ * @en Sort condition
+ */
+export type SortCondition<T> = {
+    [K in keyof T]?: SortDirection
+}
+
+/**
+ * @zh 查询选项
+ * @en Query options
+ */
+export interface QueryOptions<T> {
+    /**
+     * @zh 过滤条件
+     * @en Filter conditions
+     */
+    where?: WhereCondition<T>
+
+    /**
+     * @zh 排序条件
+     * @en Sort conditions
+     */
+    sort?: SortCondition<T>
+
+    /**
+     * @zh 限制返回数量
+     * @en Limit number of results
+     */
+    limit?: number
+
+    /**
+     * @zh 跳过记录数
+     * @en Number of records to skip
+     */
+    offset?: number
+
+    /**
+     * @zh 是否包含软删除记录
+     * @en Whether to include soft deleted records
+     */
+    includeSoftDeleted?: boolean
+}
+
+// =============================================================================
+// 分页类型 | Pagination Types
+// =============================================================================
+
+/**
+ * @zh 分页参数
+ * @en Pagination parameters
+ */
+export interface PaginationParams {
+    /**
+     * @zh 页码（从 1 开始）
+     * @en Page number (starts from 1)
+     */
+    page: number
+
+    /**
+     * @zh 每页数量
+     * @en Items per page
+     */
+    pageSize: number
+}
+
+/**
+ * @zh 分页结果
+ * @en Pagination result
+ */
+export interface PaginatedResult<T> {
+    /**
+     * @zh 数据列表
+     * @en Data list
+     */
+    data: T[]
+
+    /**
+     * @zh 总记录数
+     * @en Total count
+     */
+    total: number
+
+    /**
+     * @zh 当前页码
+     * @en Current page
+     */
+    page: number
+
+    /**
+     * @zh 每页数量
+     * @en Page size
+     */
+    pageSize: number
+
+    /**
+     * @zh 总页数
+     * @en Total pages
+     */
+    totalPages: number
+
+    /**
+     * @zh 是否有下一页
+     * @en Whether has next page
+     */
+    hasNext: boolean
+
+    /**
+     * @zh 是否有上一页
+     * @en Whether has previous page
+     */
+    hasPrev: boolean
+}
+
+// =============================================================================
+// 仓库接口 | Repository Interface
+// =============================================================================
+
+/**
+ * @zh 仓库接口
+ * @en Repository interface
+ */
+export interface IRepository<T extends BaseEntity> {
+    /**
+     * @zh 集合名称
+     * @en Collection name
+     */
+    readonly collectionName: string
+
+    /**
+     * @zh 根据 ID 查找
+     * @en Find by ID
+     */
+    findById(id: string): Promise<T | null>
+
+    /**
+     * @zh 查找单条记录
+     * @en Find one record
+     */
+    findOne(options?: QueryOptions<T>): Promise<T | null>
+
+    /**
+     * @zh 查找多条记录
+     * @en Find many records
+     */
+    findMany(options?: QueryOptions<T>): Promise<T[]>
+
+    /**
+     * @zh 分页查询
+     * @en Paginated query
+     */
+    findPaginated(
+        pagination: PaginationParams,
+        options?: Omit<QueryOptions<T>, 'limit' | 'offset'>
+    ): Promise<PaginatedResult<T>>
+
+    /**
+     * @zh 统计记录数
+     * @en Count records
+     */
+    count(options?: QueryOptions<T>): Promise<number>
+
+    /**
+     * @zh 检查记录是否存在
+     * @en Check if record exists
+     */
+    exists(options: QueryOptions<T>): Promise<boolean>
+
+    /**
+     * @zh 创建记录
+     * @en Create record
+     */
+    create(data: Omit<T, 'id' | 'createdAt' | 'updatedAt'> & { id?: string }): Promise<T>
+
+    /**
+     * @zh 批量创建
+     * @en Bulk create
+     */
+    createMany(data: Array<Omit<T, 'id' | 'createdAt' | 'updatedAt'> & { id?: string }>): Promise<T[]>
+
+    /**
+     * @zh 更新记录
+     * @en Update record
+     */
+    update(id: string, data: Partial<Omit<T, 'id' | 'createdAt' | 'updatedAt'>>): Promise<T | null>
+
+    /**
+     * @zh 删除记录
+     * @en Delete record
+     */
+    delete(id: string): Promise<boolean>
+
+    /**
+     * @zh 批量删除
+     * @en Bulk delete
+     */
+    deleteMany(options: QueryOptions<T>): Promise<number>
+}
+
+// =============================================================================
+// 用户实体 | User Entity
+// =============================================================================
+
+/**
+ * @zh 用户实体
+ * @en User entity
+ */
+export interface UserEntity extends SoftDeleteEntity {
+    /**
+     * @zh 用户名
+     * @en Username
+     */
+    username: string
+
+    /**
+     * @zh 密码哈希
+     * @en Password hash
+     */
+    passwordHash: string
+
+    /**
+     * @zh 邮箱
+     * @en Email
+     */
+    email?: string
+
+    /**
+     * @zh 用户角色
+     * @en User roles
+     */
+    roles: string[]
+
+    /**
+     * @zh 是否启用
+     * @en Is active
+     */
+    isActive: boolean
+
+    /**
+     * @zh 最后登录时间
+     * @en Last login timestamp
+     */
+    lastLoginAt?: Date
+
+    /**
+     * @zh 额外数据
+     * @en Additional metadata
+     */
+    metadata?: Record<string, unknown>
+}

packages/framework/database/tsconfig.json

@@ -0,0 +1,10 @@
+{
+    "extends": "../../../tsconfig.base.json",
+    "compilerOptions": {
+        "outDir": "./dist",
+        "rootDir": "./src",
+        "declarationDir": "./dist"
+    },
+    "include": ["src/**/*"],
+    "exclude": ["node_modules", "dist"]
+}

packages/framework/database/tsup.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+    entry: ['src/index.ts'],
+    format: ['esm'],
+    dts: true,
+    clean: true,
+    sourcemap: true,
+    external: ['@esengine/database-drivers'],
+    treeshake: true,
+});

packages/framework/network/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @esengine/network
 
+## 5.0.3
+
+### Patch Changes
+
+- Updated dependencies [[`902c0a1`](https://github.com/esengine/esengine/commit/902c0a10749f80bd8f499b44154646379d359704)]:
+    - @esengine/rpc@1.1.3
+
+## 5.0.2
+
+### Patch Changes
+
+- Updated dependencies []:
+    - @esengine/rpc@1.1.2
+
 ## 5.0.1
 
 ### Patch Changes

packages/framework/network/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@esengine/network",
-    "version": "5.0.1",
+    "version": "5.0.3",
     "description": "Network synchronization for multiplayer games",
     "esengine": {
         "plugin": true,

packages/framework/rpc/CHANGELOG.md

@@ -1,5 +1,93 @@
 # @esengine/rpc
 
+## 1.1.3
+
+### Patch Changes
+
+- [#404](https://github.com/esengine/esengine/pull/404) [`902c0a1`](https://github.com/esengine/esengine/commit/902c0a10749f80bd8f499b44154646379d359704) Thanks [@esengine](https://github.com/esengine)! - feat(server): add HTTP file-based routing support / 添加 HTTP 文件路由支持
+
+    New feature that allows organizing HTTP routes in separate files, similar to API and message handlers.
+    新功能：支持将 HTTP 路由组织在独立文件中，类似于 API 和消息处理器的文件路由方式。
+
+    ```typescript
+    // src/http/login.ts
+    import { defineHttp } from '@esengine/server';
+
+    export default defineHttp<{ username: string; password: string }>({
+        method: 'POST',
+        handler(req, res) {
+            const { username, password } = req.body;
+            res.json({ token: '...', userId: '...' });
+        }
+    });
+    ```
+
+    Server configuration / 服务器配置:
+
+    ```typescript
+    const server = await createServer({
+        port: 8080,
+        httpDir: 'src/http', // HTTP routes directory / HTTP 路由目录
+        httpPrefix: '/api', // Route prefix / 路由前缀
+        cors: true
+    });
+    ```
+
+    File naming convention / 文件命名规则:
+    - `login.ts` → POST /api/login
+    - `users/profile.ts` → POST /api/users/profile
+    - `users/[id].ts` → POST /api/users/:id (dynamic routes / 动态路由)
+    - Set `method: 'GET'` in defineHttp for GET requests / 在 defineHttp 中设置 `method: 'GET'` 以处理 GET 请求
+
+    Also includes / 还包括:
+    - `defineHttp<TBody>()` helper for type-safe route definitions / 类型安全的路由定义辅助函数
+    - Support for merging file routes with inline `http` config / 支持文件路由与内联 `http` 配置合并
+    - RPC server supports attaching to existing HTTP server via `server` option / RPC 服务器支持通过 `server` 选项附加到现有 HTTP 服务器
+
+## 1.1.2
+
+### Patch Changes
+
+- feat(server): add HTTP file-based routing support
+
+    New feature that allows organizing HTTP routes in separate files, similar to API and message handlers:
+
+    ```typescript
+    // src/http/login.ts
+    import { defineHttp } from '@esengine/server';
+
+    export default defineHttp<{ username: string; password: string }>({
+        method: 'POST',
+        handler(req, res) {
+            const { username, password } = req.body;
+            // ... authentication logic
+            res.json({ token: '...', userId: '...' });
+        }
+    });
+    ```
+
+    Server configuration:
+
+    ```typescript
+    const server = await createServer({
+        port: 8080,
+        httpDir: 'src/http', // HTTP routes directory
+        httpPrefix: '/api', // Route prefix
+        cors: true
+    });
+    ```
+
+    File naming convention:
+    - `login.ts` → POST /api/login
+    - `users/profile.ts` → POST /api/users/profile
+    - `users/[id].ts` → POST /api/users/:id (dynamic routes)
+    - Set `method: 'GET'` in defineHttp for GET requests
+
+    Also includes:
+    - `defineHttp<TBody>()` helper function for type-safe route definitions
+    - Support for merging file routes with inline `http` config
+    - RPC server now supports attaching to existing HTTP server via `server` option
+
 ## 1.1.1
 
 ### Patch Changes

packages/framework/rpc/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esengine/rpc",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "description": "Elegant type-safe RPC library for ESEngine",
   "type": "module",
   "main": "./dist/index.js",

packages/framework/rpc/src/server/index.ts

@@ -4,6 +4,7 @@
  */
 
 import { WebSocketServer, WebSocket } from 'ws'
+import type { Server as HttpServer } from 'node:http'
 import type {
     ProtocolDef,
     ApiNames,
@@ -66,10 +67,19 @@ type MsgHandlers<P extends ProtocolDef, TConnData> = {
  */
 export interface ServeOptions<P extends ProtocolDef, TConnData = unknown> {
     /**
-     * @zh 监听端口
-     * @en Listen port
+     * @zh 监听端口（与 server 二选一）
+     * @en Listen port (mutually exclusive with server)
      */
-    port: number
+    port?: number
+
+    /**
+     * @zh 已有的 HTTP 服务器（与 port 二选一）
+     * @en Existing HTTP server (mutually exclusive with port)
+     *
+     * @zh 使用此选项可以在同一端口同时支持 HTTP 和 WebSocket
+     * @en Use this option to support both HTTP and WebSocket on the same port
+     */
+    server?: HttpServer
 
     /**
      * @zh API 处理器
@@ -280,7 +290,16 @@ export function serve<P extends ProtocolDef, TConnData = unknown>(
 
         async start() {
             return new Promise((resolve) => {
-                wss = new WebSocketServer({ port: options.port })
+                // 根据配置创建 WebSocketServer
+                if (options.server) {
+                    // 附加到已有的 HTTP 服务器
+                    wss = new WebSocketServer({ server: options.server })
+                } else if (options.port) {
+                    // 独立创建
+                    wss = new WebSocketServer({ port: options.port })
+                } else {
+                    throw new Error('Either port or server must be provided')
+                }
 
                 wss.on('connection', async (ws, req) => {
                     const id = String(++connIdCounter)
@@ -318,10 +337,16 @@ export function serve<P extends ProtocolDef, TConnData = unknown>(
                     await options.onConnect?.(conn)
                 })
 
-                wss.on('listening', () => {
-                    options.onStart?.(options.port)
+                // 如果使用已有的 HTTP 服务器，WebSocketServer 不会触发 listening 事件
+                if (options.server) {
+                    options.onStart?.(0) // 端口由 HTTP 服务器管理
                     resolve()
-                })
+                } else {
+                    wss.on('listening', () => {
+                        options.onStart?.(options.port!)
+                        resolve()
+                    })
+                }
             })
         },
 

packages/framework/server/CHANGELOG.md

@@ -1,5 +1,121 @@
 # @esengine/server
 
+## 4.3.0
+
+### Minor Changes
+
+- [#417](https://github.com/esengine/esengine/pull/417) [`b80e967`](https://github.com/esengine/esengine/commit/b80e96782991b0f5dea65949e5c55325d2775132) Thanks [@esengine](https://github.com/esengine)! - feat(server): HTTP 路由增强 | HTTP router enhancement
+
+    **新功能 | New Features**
+    - 路由参数支持：`/users/:id` → `req.params.id` | Route parameters: `/users/:id` → `req.params.id`
+    - 中间件支持：全局和路由级中间件 | Middleware support: global and route-level
+    - 请求超时控制：全局和路由级超时 | Request timeout: global and route-level
+
+    **内置中间件 | Built-in Middleware**
+    - `requestLogger()` - 请求日志 | Request logging
+    - `bodyLimit()` - 请求体大小限制 | Body size limit
+    - `responseTime()` - 响应时间头 | Response time header
+    - `requestId()` - 请求 ID | Request ID
+    - `securityHeaders()` - 安全头 | Security headers
+
+## 4.2.0
+
+### Minor Changes
+
+- [#404](https://github.com/esengine/esengine/pull/404) [`902c0a1`](https://github.com/esengine/esengine/commit/902c0a10749f80bd8f499b44154646379d359704) Thanks [@esengine](https://github.com/esengine)! - feat(server): add HTTP file-based routing support / 添加 HTTP 文件路由支持
+
+    New feature that allows organizing HTTP routes in separate files, similar to API and message handlers.
+    新功能：支持将 HTTP 路由组织在独立文件中，类似于 API 和消息处理器的文件路由方式。
+
+    ```typescript
+    // src/http/login.ts
+    import { defineHttp } from '@esengine/server';
+
+    export default defineHttp<{ username: string; password: string }>({
+        method: 'POST',
+        handler(req, res) {
+            const { username, password } = req.body;
+            res.json({ token: '...', userId: '...' });
+        }
+    });
+    ```
+
+    Server configuration / 服务器配置:
+
+    ```typescript
+    const server = await createServer({
+        port: 8080,
+        httpDir: 'src/http', // HTTP routes directory / HTTP 路由目录
+        httpPrefix: '/api', // Route prefix / 路由前缀
+        cors: true
+    });
+    ```
+
+    File naming convention / 文件命名规则:
+    - `login.ts` → POST /api/login
+    - `users/profile.ts` → POST /api/users/profile
+    - `users/[id].ts` → POST /api/users/:id (dynamic routes / 动态路由)
+    - Set `method: 'GET'` in defineHttp for GET requests / 在 defineHttp 中设置 `method: 'GET'` 以处理 GET 请求
+
+    Also includes / 还包括:
+    - `defineHttp<TBody>()` helper for type-safe route definitions / 类型安全的路由定义辅助函数
+    - Support for merging file routes with inline `http` config / 支持文件路由与内联 `http` 配置合并
+    - RPC server supports attaching to existing HTTP server via `server` option / RPC 服务器支持通过 `server` 选项附加到现有 HTTP 服务器
+
+### Patch Changes
+
+- Updated dependencies [[`902c0a1`](https://github.com/esengine/esengine/commit/902c0a10749f80bd8f499b44154646379d359704)]:
+    - @esengine/rpc@1.1.3
+
+## 4.1.0
+
+### Minor Changes
+
+- feat(server): add HTTP file-based routing support
+
+    New feature that allows organizing HTTP routes in separate files, similar to API and message handlers:
+
+    ```typescript
+    // src/http/login.ts
+    import { defineHttp } from '@esengine/server';
+
+    export default defineHttp<{ username: string; password: string }>({
+        method: 'POST',
+        handler(req, res) {
+            const { username, password } = req.body;
+            // ... authentication logic
+            res.json({ token: '...', userId: '...' });
+        }
+    });
+    ```
+
+    Server configuration:
+
+    ```typescript
+    const server = await createServer({
+        port: 8080,
+        httpDir: 'src/http', // HTTP routes directory
+        httpPrefix: '/api', // Route prefix
+        cors: true
+    });
+    ```
+
+    File naming convention:
+    - `login.ts` → POST /api/login
+    - `users/profile.ts` → POST /api/users/profile
+    - `users/[id].ts` → POST /api/users/:id (dynamic routes)
+    - Set `method: 'GET'` in defineHttp for GET requests
+
+    Also includes:
+    - `defineHttp<TBody>()` helper function for type-safe route definitions
+    - Support for merging file routes with inline `http` config
+    - RPC server now supports attaching to existing HTTP server via `server` option
+
+### Patch Changes
+
+- Updated dependencies []:
+    - @esengine/rpc@1.1.2
+
 ## 4.0.0
 
 ### Patch Changes

packages/framework/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esengine/server",
-  "version": "4.0.0",
+  "version": "4.3.0",
   "description": "Game server framework for ESEngine with file-based routing",
   "type": "module",
   "main": "./dist/index.js",
@@ -46,23 +46,19 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@esengine/rpc": "workspace:*"
+    "@esengine/rpc": "workspace:*",
+    "@esengine/ecs-framework": "workspace:*"
   },
   "peerDependencies": {
     "ws": ">=8.0.0",
-    "jsonwebtoken": ">=9.0.0",
-    "@esengine/ecs-framework": ">=2.7.1"
+    "jsonwebtoken": ">=9.0.0"
   },
   "peerDependenciesMeta": {
     "jsonwebtoken": {
       "optional": true
-    },
-    "@esengine/ecs-framework": {
-      "optional": true
     }
   },
   "devDependencies": {
-    "@esengine/ecs-framework": "workspace:*",
     "@types/jsonwebtoken": "^9.0.0",
     "@types/node": "^20.0.0",
     "@types/ws": "^8.5.13",

packages/framework/server/src/auth/__tests__/MockAuthProvider.test.ts

@@ -168,9 +168,9 @@ describe('MockAuthProvider', () => {
         it('should get all users', () => {
             const users = provider.getUsers();
             expect(users).toHaveLength(3);
-            expect(users.map(u => u.id)).toContain('1');
-            expect(users.map(u => u.id)).toContain('2');
-            expect(users.map(u => u.id)).toContain('3');
+            expect(users.map((u) => u.id)).toContain('1');
+            expect(users.map((u) => u.id)).toContain('2');
+            expect(users.map((u) => u.id)).toContain('3');
         });
     });
 

packages/framework/server/src/auth/__tests__/providers.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { describe, it, expect, beforeEach } from 'vitest';
 import { JwtAuthProvider, createJwtAuthProvider } from '../providers/JwtAuthProvider';
 import { SessionAuthProvider, createSessionAuthProvider, type ISessionStorage } from '../providers/SessionAuthProvider';
 
@@ -125,7 +125,7 @@ describe('JwtAuthProvider', () => {
             const token = provider.sign({ sub: '123', name: 'Alice' });
 
             // Wait a bit so iat changes
-            await new Promise(resolve => setTimeout(resolve, 1100));
+            await new Promise((resolve) => setTimeout(resolve, 1100));
 
             const result = await provider.refresh(token);
 
@@ -239,7 +239,7 @@ describe('SessionAuthProvider', () => {
         it('should validate user on verify', async () => {
             const validatingProvider = createSessionAuthProvider({
                 storage,
-                validateUser: (user) => user.id !== 'banned'
+                validateUser: (user: { id: string; name?: string }) => user.id !== 'banned'
             });
 
             const sessionId = await validatingProvider.createSession({ id: 'banned', name: 'Bad User' });
@@ -252,7 +252,7 @@ describe('SessionAuthProvider', () => {
         it('should pass validation for valid user', async () => {
             const validatingProvider = createSessionAuthProvider({
                 storage,
-                validateUser: (user) => user.id !== 'banned'
+                validateUser: (user: { id: string; name?: string }) => user.id !== 'banned'
             });
 
             const sessionId = await validatingProvider.createSession({ id: '123', name: 'Good User' });
@@ -269,7 +269,7 @@ describe('SessionAuthProvider', () => {
             const session1 = await provider.getSession(sessionId);
             const lastActive1 = session1?.lastActiveAt;
 
-            await new Promise(resolve => setTimeout(resolve, 10));
+            await new Promise((resolve) => setTimeout(resolve, 10));
 
             const result = await provider.refresh(sessionId);
             expect(result.success).toBe(true);

packages/framework/server/src/auth/context.ts

@@ -138,7 +138,7 @@ export class AuthContext<TUser = unknown> implements IAuthContext<TUser> {
      * @en Check if has any of specified roles
      */
     hasAnyRole(roles: string[]): boolean {
-        return roles.some(role => this._roles.includes(role));
+        return roles.some((role) => this._roles.includes(role));
     }
 
     /**
@@ -146,7 +146,7 @@ export class AuthContext<TUser = unknown> implements IAuthContext<TUser> {
      * @en Check if has all specified roles
      */
     hasAllRoles(roles: string[]): boolean {
-        return roles.every(role => this._roles.includes(role));
+        return roles.every((role) => this._roles.includes(role));
     }
 
     /**

packages/framework/server/src/auth/mixin/withAuth.ts

@@ -4,6 +4,7 @@
  */
 
 import type { ServerConnection, GameServer } from '../../types/index.js';
+import { createLogger } from '../../logger.js';
 import type {
     IAuthProvider,
     AuthResult,
@@ -14,6 +15,8 @@ import type {
 } from '../types.js';
 import { AuthContext } from '../context.js';
 
+const logger = createLogger('Auth');
+
 /**
  * @zh 认证数据键
  * @en Auth data key
@@ -155,7 +158,7 @@ export function withAuth<TUser = unknown>(
                     }
                 }
             } catch (error) {
-                console.error('[Auth] Error during auto-authentication:', error);
+                logger.error('Error during auto-authentication:', error);
             }
         }
 

packages/framework/server/src/auth/mixin/withRoomAuth.ts

@@ -5,9 +5,12 @@
 
 import type { Room, Player } from '../../room/index.js';
 import type { IAuthContext, AuthRoomConfig } from '../types.js';
+import { createLogger } from '../../logger.js';
 import { getAuthContext } from './withAuth.js';
 import { createGuestContext } from '../context.js';
 
+const logger = createLogger('AuthRoom');
+
 /**
  * @zh 带认证的玩家
  * @en Player with authentication
@@ -181,7 +184,7 @@ export function withRoomAuth<TUser = unknown, TBase extends new (...args: any[])
                 : createGuestContext<TUser>();
 
             if (requireAuth && !authContext.isAuthenticated) {
-                console.warn(`[AuthRoom] Rejected unauthenticated player: ${player.id}`);
+                logger.warn(`Rejected unauthenticated player: ${player.id}`);
                 this.kick(player as any, 'Authentication required');
                 return;
             }
@@ -192,7 +195,7 @@ export function withRoomAuth<TUser = unknown, TBase extends new (...args: any[])
                     : authContext.hasAllRoles(allowedRoles);
 
                 if (!hasRole) {
-                    console.warn(`[AuthRoom] Rejected player ${player.id}: insufficient roles`);
+                    logger.warn(`Rejected player ${player.id}: insufficient roles`);
                     this.kick(player as any, 'Insufficient permissions');
                     return;
                 }
@@ -204,12 +207,12 @@ export function withRoomAuth<TUser = unknown, TBase extends new (...args: any[])
                 try {
                     const allowed = await this.onAuth(authPlayer);
                     if (!allowed) {
-                        console.warn(`[AuthRoom] Rejected player ${player.id}: onAuth returned false`);
+                        logger.warn(`Rejected player ${player.id}: onAuth returned false`);
                         this.kick(player as any, 'Authentication rejected');
                         return;
                     }
                 } catch (error) {
-                    console.error(`[AuthRoom] Error in onAuth for player ${player.id}:`, error);
+                    logger.error(`Error in onAuth for player ${player.id}:`, error);
                     this.kick(player as any, 'Authentication error');
                     return;
                 }
@@ -242,7 +245,7 @@ export function withRoomAuth<TUser = unknown, TBase extends new (...args: any[])
          * @en Get players by role
          */
         getPlayersByRole(role: string): AuthPlayer<TUser>[] {
-            return this.getAuthPlayers().filter(p => p.auth?.hasRole(role));
+            return this.getAuthPlayers().filter((p) => p.auth?.hasRole(role));
         }
 
         /**
@@ -250,7 +253,7 @@ export function withRoomAuth<TUser = unknown, TBase extends new (...args: any[])
          * @en Get player by user ID
          */
         getPlayerByUserId(userId: string): AuthPlayer<TUser> | undefined {
-            return this.getAuthPlayers().find(p => p.auth?.userId === userId);
+            return this.getAuthPlayers().find((p) => p.auth?.userId === userId);
         }
     }
 
@@ -281,7 +284,7 @@ export function withRoomAuth<TUser = unknown, TBase extends new (...args: any[])
  * ```
  */
 export abstract class AuthRoomBase<TUser = unknown, TState = any, TPlayerData = Record<string, unknown>>
-    implements IAuthRoom<TUser> {
+implements IAuthRoom<TUser> {
 
     /**
      * @zh 认证配置（子类可覆盖）

packages/framework/server/src/auth/testing/MockAuthProvider.ts

@@ -77,7 +77,7 @@ export interface MockAuthConfig {
  * ```
  */
 export class MockAuthProvider<TUser extends MockUser = MockUser>
-    implements IAuthProvider<TUser, string> {
+implements IAuthProvider<TUser, string> {
 
     readonly name = 'mock';
 
@@ -102,7 +102,7 @@ export class MockAuthProvider<TUser extends MockUser = MockUser>
      */
     private async _delay(): Promise<void> {
         if (this._config.delay && this._config.delay > 0) {
-            await new Promise(resolve => setTimeout(resolve, this._config.delay));
+            await new Promise((resolve) => setTimeout(resolve, this._config.delay));
         }
     }
 

packages/framework/server/src/core/server.ts

@@ -3,9 +3,11 @@
  * @en Game server core
  */
 
-import * as path from 'node:path'
-import { serve, type RpcServer } from '@esengine/rpc/server'
-import { rpc } from '@esengine/rpc'
+import * as path from 'node:path';
+import { createServer as createHttpServer, type Server as HttpServer } from 'node:http';
+import { serve, type RpcServer } from '@esengine/rpc/server';
+import { rpc } from '@esengine/rpc';
+import { createLogger } from '../logger.js';
 import type {
     ServerConfig,
     ServerConnection,
@@ -14,20 +16,25 @@ import type {
     MsgContext,
     LoadedApiHandler,
     LoadedMsgHandler,
-} from '../types/index.js'
-import { loadApiHandlers, loadMsgHandlers } from '../router/loader.js'
-import { RoomManager, type RoomClass, type Room } from '../room/index.js'
+    LoadedHttpHandler
+} from '../types/index.js';
+import type { HttpRoutes, HttpHandler } from '../http/types.js';
+import { loadApiHandlers, loadMsgHandlers, loadHttpHandlers } from '../router/loader.js';
+import { RoomManager, type RoomClass, type Room } from '../room/index.js';
+import { createHttpRouter } from '../http/router.js';
 
 /**
  * @zh 默认配置
  * @en Default configuration
  */
-const DEFAULT_CONFIG: Required<Omit<ServerConfig, 'onStart' | 'onConnect' | 'onDisconnect'>> = {
+const DEFAULT_CONFIG: Required<Omit<ServerConfig, 'onStart' | 'onConnect' | 'onDisconnect' | 'http' | 'cors' | 'httpDir' | 'httpPrefix'>> & { httpDir: string; httpPrefix: string } = {
     port: 3000,
     apiDir: 'src/api',
     msgDir: 'src/msg',
-    tickRate: 20,
-}
+    httpDir: 'src/http',
+    httpPrefix: '/api',
+    tickRate: 20
+};
 
 /**
  * @zh 创建游戏服务器
@@ -49,63 +56,106 @@ const DEFAULT_CONFIG: Required<Omit<ServerConfig, 'onStart' | 'onConnect' | 'onD
  * ```
  */
 export async function createServer(config: ServerConfig = {}): Promise<GameServer> {
-    const opts = { ...DEFAULT_CONFIG, ...config }
-    const cwd = process.cwd()
+    const opts = { ...DEFAULT_CONFIG, ...config };
+    const cwd = process.cwd();
+    const logger = createLogger('Server');
 
     // 加载文件路由处理器
-    const apiHandlers = await loadApiHandlers(path.resolve(cwd, opts.apiDir))
-    const msgHandlers = await loadMsgHandlers(path.resolve(cwd, opts.msgDir))
+    const apiHandlers = await loadApiHandlers(path.resolve(cwd, opts.apiDir));
+    const msgHandlers = await loadMsgHandlers(path.resolve(cwd, opts.msgDir));
+
+    // 加载 HTTP 文件路由
+    const httpDir = config.httpDir ?? opts.httpDir;
+    const httpPrefix = config.httpPrefix ?? opts.httpPrefix;
+    const httpHandlers = await loadHttpHandlers(path.resolve(cwd, httpDir), httpPrefix);
 
     if (apiHandlers.length > 0) {
-        console.log(`[Server] Loaded ${apiHandlers.length} API handlers`)
+        logger.info(`Loaded ${apiHandlers.length} API handlers`);
     }
     if (msgHandlers.length > 0) {
-        console.log(`[Server] Loaded ${msgHandlers.length} message handlers`)
+        logger.info(`Loaded ${msgHandlers.length} message handlers`);
     }
+    if (httpHandlers.length > 0) {
+        logger.info(`Loaded ${httpHandlers.length} HTTP handlers`);
+    }
+
+    // 合并 HTTP 路由（文件路由 + 内联路由）
+    const mergedHttpRoutes: HttpRoutes = {};
+
+    // 先添加文件路由
+    for (const handler of httpHandlers) {
+        const existingRoute = mergedHttpRoutes[handler.route];
+        if (existingRoute && typeof existingRoute !== 'function') {
+            (existingRoute as Record<string, HttpHandler>)[handler.method] = handler.definition.handler;
+        } else {
+            mergedHttpRoutes[handler.route] = {
+                [handler.method]: handler.definition.handler
+            };
+        }
+    }
+
+    // 再添加内联路由（覆盖文件路由）
+    if (config.http) {
+        for (const [route, handlerOrMethods] of Object.entries(config.http)) {
+            if (typeof handlerOrMethods === 'function') {
+                mergedHttpRoutes[route] = handlerOrMethods;
+            } else {
+                const existing = mergedHttpRoutes[route];
+                if (existing && typeof existing !== 'function') {
+                    Object.assign(existing, handlerOrMethods);
+                } else {
+                    mergedHttpRoutes[route] = handlerOrMethods;
+                }
+            }
+        }
+    }
+
+    const hasHttpRoutes = Object.keys(mergedHttpRoutes).length > 0;
 
     // 动态构建协议
     const apiDefs: Record<string, ReturnType<typeof rpc.api>> = {
         // 内置 API
         JoinRoom: rpc.api(),
-        LeaveRoom: rpc.api(),
-    }
+        LeaveRoom: rpc.api()
+    };
     const msgDefs: Record<string, ReturnType<typeof rpc.msg>> = {
         // 内置消息（房间消息透传）
-        RoomMessage: rpc.msg(),
-    }
+        RoomMessage: rpc.msg()
+    };
 
     for (const handler of apiHandlers) {
-        apiDefs[handler.name] = rpc.api()
+        apiDefs[handler.name] = rpc.api();
     }
     for (const handler of msgHandlers) {
-        msgDefs[handler.name] = rpc.msg()
+        msgDefs[handler.name] = rpc.msg();
     }
 
     const protocol = rpc.define({
         api: apiDefs,
-        msg: msgDefs,
-    })
+        msg: msgDefs
+    });
 
     // 服务器状态
-    let currentTick = 0
-    let tickInterval: ReturnType<typeof setInterval> | null = null
-    let rpcServer: RpcServer<typeof protocol, Record<string, unknown>> | null = null
+    let currentTick = 0;
+    let tickInterval: ReturnType<typeof setInterval> | null = null;
+    let rpcServer: RpcServer<typeof protocol, Record<string, unknown>> | null = null;
+    let httpServer: HttpServer | null = null;
 
     // 房间管理器（立即初始化，以便 define() 可在 start() 前调用）
     const roomManager = new RoomManager((conn, type, data) => {
-        rpcServer?.send(conn, 'RoomMessage' as any, { type, data } as any)
-    })
+        rpcServer?.send(conn, 'RoomMessage' as any, { type, data } as any);
+    });
 
     // 构建 API 处理器映射
-    const apiMap: Record<string, LoadedApiHandler> = {}
+    const apiMap: Record<string, LoadedApiHandler> = {};
     for (const handler of apiHandlers) {
-        apiMap[handler.name] = handler
+        apiMap[handler.name] = handler;
     }
 
     // 构建消息处理器映射
-    const msgMap: Record<string, LoadedMsgHandler> = {}
+    const msgMap: Record<string, LoadedMsgHandler> = {};
     for (const handler of msgHandlers) {
-        msgMap[handler.name] = handler
+        msgMap[handler.name] = handler;
     }
 
     // 游戏服务器实例
@@ -113,15 +163,15 @@ export async function createServer(config: ServerConfig = {}): Promise<GameServe
         rooms: RoomManager
     } = {
         get connections() {
-            return (rpcServer?.connections ?? []) as ReadonlyArray<ServerConnection>
+            return (rpcServer?.connections ?? []) as ReadonlyArray<ServerConnection>;
         },
 
         get tick() {
-            return currentTick
+            return currentTick;
         },
 
         get rooms() {
-            return roomManager
+            return roomManager;
         },
 
         /**
@@ -129,12 +179,12 @@ export async function createServer(config: ServerConfig = {}): Promise<GameServe
          * @en Define room type
          */
         define(name: string, roomClass: new () => unknown): void {
-            roomManager.define(name, roomClass as RoomClass)
+            roomManager.define(name, roomClass as RoomClass);
         },
 
         async start() {
             // 构建 API handlers
-            const apiHandlersObj: Record<string, (input: unknown, conn: any) => Promise<unknown>> = {}
+            const apiHandlersObj: Record<string, (input: unknown, conn: any) => Promise<unknown>> = {};
 
             // 内置 JoinRoom API
             apiHandlersObj['JoinRoom'] = async (input: any, conn) => {
@@ -142,112 +192,165 @@ export async function createServer(config: ServerConfig = {}): Promise<GameServe
                     roomType?: string
                     roomId?: string
                     options?: Record<string, unknown>
-                }
+                };
 
                 if (roomId) {
-                    const result = await roomManager.joinById(roomId, conn.id, conn)
+                    const result = await roomManager.joinById(roomId, conn.id, conn);
                     if (!result) {
-                        throw new Error('Failed to join room')
+                        throw new Error('Failed to join room');
                     }
-                    return { roomId: result.room.id, playerId: result.player.id }
+                    return { roomId: result.room.id, playerId: result.player.id };
                 }
 
                 if (roomType) {
-                    const result = await roomManager.joinOrCreate(roomType, conn.id, conn, options)
+                    const result = await roomManager.joinOrCreate(roomType, conn.id, conn, options);
                     if (!result) {
-                        throw new Error('Failed to join or create room')
+                        throw new Error('Failed to join or create room');
                     }
-                    return { roomId: result.room.id, playerId: result.player.id }
+                    return { roomId: result.room.id, playerId: result.player.id };
                 }
 
-                throw new Error('roomType or roomId required')
-            }
+                throw new Error('roomType or roomId required');
+            };
 
             // 内置 LeaveRoom API
             apiHandlersObj['LeaveRoom'] = async (_input, conn) => {
-                await roomManager.leave(conn.id)
-                return { success: true }
-            }
+                await roomManager.leave(conn.id);
+                return { success: true };
+            };
 
             // 文件路由 API
             for (const [name, handler] of Object.entries(apiMap)) {
                 apiHandlersObj[name] = async (input, conn) => {
                     const ctx: ApiContext = {
                         conn: conn as ServerConnection,
-                        server: gameServer,
-                    }
-                    return handler.definition.handler(input, ctx)
-                }
+                        server: gameServer
+                    };
+                    return handler.definition.handler(input, ctx);
+                };
             }
 
             // 构建消息 handlers
-            const msgHandlersObj: Record<string, (data: unknown, conn: any) => void | Promise<void>> = {}
+            const msgHandlersObj: Record<string, (data: unknown, conn: any) => void | Promise<void>> = {};
 
             // 内置 RoomMessage 处理
             msgHandlersObj['RoomMessage'] = async (data: any, conn) => {
-                const { type, data: payload } = data as { type: string; data: unknown }
-                roomManager.handleMessage(conn.id, type, payload)
-            }
+                const { type, data: payload } = data as { type: string; data: unknown };
+                roomManager.handleMessage(conn.id, type, payload);
+            };
 
             // 文件路由消息
             for (const [name, handler] of Object.entries(msgMap)) {
                 msgHandlersObj[name] = async (data, conn) => {
                     const ctx: MsgContext = {
                         conn: conn as ServerConnection,
-                        server: gameServer,
-                    }
-                    await handler.definition.handler(data, ctx)
-                }
+                        server: gameServer
+                    };
+                    await handler.definition.handler(data, ctx);
+                };
             }
 
-            rpcServer = serve(protocol, {
-                port: opts.port,
-                createConnData: () => ({}),
-                onStart: (p) => {
-                    console.log(`[Server] Started on ws://localhost:${p}`)
-                    opts.onStart?.(p)
-                },
-                onConnect: async (conn) => {
-                    await config.onConnect?.(conn as ServerConnection)
-                },
-                onDisconnect: async (conn) => {
-                    // 玩家断线时自动离开房间
-                    await roomManager?.leave(conn.id, 'disconnected')
-                    await config.onDisconnect?.(conn as ServerConnection)
-                },
-                api: apiHandlersObj as any,
-                msg: msgHandlersObj as any,
-            })
+            // 如果有 HTTP 路由，创建 HTTP 服务器
+            if (hasHttpRoutes) {
+                const httpRouter = createHttpRouter(mergedHttpRoutes, {
+                    cors: config.cors ?? true
+                });
 
-            await rpcServer.start()
+                httpServer = createHttpServer(async (req, res) => {
+                    // 先尝试 HTTP 路由
+                    const handled = await httpRouter(req, res);
+                    if (!handled) {
+                        // 未匹配的请求返回 404
+                        res.statusCode = 404;
+                        res.setHeader('Content-Type', 'application/json');
+                        res.end(JSON.stringify({ error: 'Not Found' }));
+                    }
+                });
+
+                // 使用 HTTP 服务器创建 RPC
+                rpcServer = serve(protocol, {
+                    server: httpServer,
+                    createConnData: () => ({}),
+                    onStart: () => {
+                        logger.info(`Started on http://localhost:${opts.port}`);
+                        opts.onStart?.(opts.port);
+                    },
+                    onConnect: async (conn) => {
+                        await config.onConnect?.(conn as ServerConnection);
+                    },
+                    onDisconnect: async (conn) => {
+                        await roomManager?.leave(conn.id, 'disconnected');
+                        await config.onDisconnect?.(conn as ServerConnection);
+                    },
+                    api: apiHandlersObj as any,
+                    msg: msgHandlersObj as any
+                });
+
+                await rpcServer.start();
+
+                // 启动 HTTP 服务器
+                await new Promise<void>((resolve) => {
+                    httpServer!.listen(opts.port, () => resolve());
+                });
+            } else {
+                // 仅 WebSocket 模式
+                rpcServer = serve(protocol, {
+                    port: opts.port,
+                    createConnData: () => ({}),
+                    onStart: (p) => {
+                        logger.info(`Started on ws://localhost:${p}`);
+                        opts.onStart?.(p);
+                    },
+                    onConnect: async (conn) => {
+                        await config.onConnect?.(conn as ServerConnection);
+                    },
+                    onDisconnect: async (conn) => {
+                        await roomManager?.leave(conn.id, 'disconnected');
+                        await config.onDisconnect?.(conn as ServerConnection);
+                    },
+                    api: apiHandlersObj as any,
+                    msg: msgHandlersObj as any
+                });
+
+                await rpcServer.start();
+            }
 
             // 启动 tick 循环
             if (opts.tickRate > 0) {
                 tickInterval = setInterval(() => {
-                    currentTick++
-                }, 1000 / opts.tickRate)
+                    currentTick++;
+                }, 1000 / opts.tickRate);
             }
         },
 
         async stop() {
             if (tickInterval) {
-                clearInterval(tickInterval)
-                tickInterval = null
+                clearInterval(tickInterval);
+                tickInterval = null;
             }
             if (rpcServer) {
-                await rpcServer.stop()
-                rpcServer = null
+                await rpcServer.stop();
+                rpcServer = null;
+            }
+            if (httpServer) {
+                await new Promise<void>((resolve, reject) => {
+                    httpServer!.close((err) => {
+                        if (err) reject(err);
+                        else resolve();
+                    });
+                });
+                httpServer = null;
             }
         },
 
         broadcast(name, data) {
-            rpcServer?.broadcast(name as any, data as any)
+            rpcServer?.broadcast(name as any, data as any);
         },
 
         send(conn, name, data) {
-            rpcServer?.send(conn as any, name as any, data as any)
-        },
-    }
+            rpcServer?.send(conn as any, name as any, data as any);
+        }
+    };
 
-    return gameServer as GameServer
+    return gameServer as GameServer;
 }

packages/framework/server/src/ecs/ECSRoom.test.ts

@@ -3,20 +3,17 @@
  * @en ECSRoom integration tests
  */
 
-import { describe, it, expect, beforeEach, afterEach, beforeAll, afterAll } from 'vitest'
+import { describe, it, expect, beforeEach, afterEach, beforeAll, afterAll } from 'vitest';
 import {
     Core,
     Component,
     ECSComponent,
-    sync,
-    initChangeTracker,
-    getSyncMetadata,
-    registerSyncComponent,
-} from '@esengine/ecs-framework'
-import { createTestEnv, type TestEnvironment, wait } from '../testing/TestServer.js'
-import { ECSRoom } from './ECSRoom.js'
-import type { Player } from '../room/Player.js'
-import { onMessage } from '../room/decorators.js'
+    sync
+} from '@esengine/ecs-framework';
+import { createTestEnv, type TestEnvironment, wait } from '../testing/TestServer.js';
+import { ECSRoom } from './ECSRoom.js';
+import type { Player } from '../room/Player.js';
+import { onMessage } from '../room/decorators.js';
 
 // ============================================================================
 // Test Components | 测试组件
@@ -24,16 +21,10 @@ import { onMessage } from '../room/decorators.js'
 
 @ECSComponent('ECSRoomTest_PlayerComponent')
 class PlayerComponent extends Component {
-    @sync('string') name: string = ''
-    @sync('uint16') score: number = 0
-    @sync('float32') x: number = 0
-    @sync('float32') y: number = 0
-}
-
-@ECSComponent('ECSRoomTest_HealthComponent')
-class HealthComponent extends Component {
-    @sync('int32') current: number = 100
-    @sync('int32') max: number = 100
+    @sync('string') name: string = '';
+    @sync('uint16') score: number = 0;
+    @sync('float32') x: number = 0;
+    @sync('float32') y: number = 0;
 }
 
 // ============================================================================
@@ -50,69 +41,69 @@ interface TestPlayerData {
 
 class TestECSRoom extends ECSRoom<TestRoomState, TestPlayerData> {
     state: TestRoomState = {
-        gameStarted: false,
-    }
+        gameStarted: false
+    };
 
     onCreate(): void {
         // 可以在这里添加系统
     }
 
     onJoin(player: Player<TestPlayerData>): void {
-        const entity = this.createPlayerEntity(player.id)
-        const comp = entity.addComponent(new PlayerComponent())
-        comp.name = player.data.nickname || `Player_${player.id.slice(-4)}`
-        comp.x = Math.random() * 100
-        comp.y = Math.random() * 100
+        const entity = this.createPlayerEntity(player.id);
+        const comp = entity.addComponent(new PlayerComponent());
+        comp.name = player.data.nickname || `Player_${player.id.slice(-4)}`;
+        comp.x = Math.random() * 100;
+        comp.y = Math.random() * 100;
 
         this.broadcast('PlayerJoined', {
             playerId: player.id,
-            name: comp.name,
-        })
+            name: comp.name
+        });
     }
 
     async onLeave(player: Player<TestPlayerData>, reason?: string): Promise<void> {
-        await super.onLeave(player, reason)
-        this.broadcast('PlayerLeft', { playerId: player.id })
+        await super.onLeave(player, reason);
+        this.broadcast('PlayerLeft', { playerId: player.id });
     }
 
     @onMessage('Move')
     handleMove(data: { x: number; y: number }, player: Player<TestPlayerData>): void {
-        const entity = this.getPlayerEntity(player.id)
+        const entity = this.getPlayerEntity(player.id);
         if (entity) {
-            const comp = entity.getComponent(PlayerComponent)
+            const comp = entity.getComponent(PlayerComponent);
             if (comp) {
-                comp.x = data.x
-                comp.y = data.y
+                comp.x = data.x;
+                comp.y = data.y;
             }
         }
     }
 
     @onMessage('AddScore')
     handleAddScore(data: { amount: number }, player: Player<TestPlayerData>): void {
-        const entity = this.getPlayerEntity(player.id)
+        const entity = this.getPlayerEntity(player.id);
         if (entity) {
-            const comp = entity.getComponent(PlayerComponent)
+            const comp = entity.getComponent(PlayerComponent);
             if (comp) {
-                comp.score += data.amount
+                comp.score += data.amount;
             }
         }
     }
 
     @onMessage('Ping')
     handlePing(_data: unknown, player: Player<TestPlayerData>): void {
-        player.send('Pong', { timestamp: Date.now() })
+        player.send('Pong', { timestamp: Date.now() });
     }
 
     getWorld() {
-        return this.world
+        return this.world;
     }
 
     getScene() {
-        return this.scene
+        return this.scene;
     }
 
     getPlayerEntityCount(): number {
-        return this.scene.entities.buffer.length
+        return this.scene.entities.buffer.length;
     }
 }
 
@@ -121,25 +112,24 @@ class TestECSRoom extends ECSRoom<TestRoomState, TestPlayerData> {
 // ============================================================================
 
 describe('ECSRoom Integration Tests', () => {
-    let env: TestEnvironment
+    let env: TestEnvironment;
 
     beforeAll(() => {
-        Core.create()
-        registerSyncComponent('ECSRoomTest_PlayerComponent', PlayerComponent)
-        registerSyncComponent('ECSRoomTest_HealthComponent', HealthComponent)
-    })
+        Core.create();
+        // @ECSComponent 装饰器已自动注册组件
+    });
 
     afterAll(() => {
-        Core.destroy()
-    })
+        Core.destroy();
+    });
 
     beforeEach(async () => {
-        env = await createTestEnv({ tickRate: 20 })
-    })
+        env = await createTestEnv({ tickRate: 20 });
+    });
 
     afterEach(async () => {
-        await env.cleanup()
-    })
+        await env.cleanup();
+    });
 
     // ========================================================================
     // Room Creation | 房间创建
@@ -147,28 +137,28 @@ describe('ECSRoom Integration Tests', () => {
 
     describe('Room Creation', () => {
         it('should create ECSRoom with World and Scene', async () => {
-            env.server.define('ecs-test', TestECSRoom)
+            env.server.define('ecs-test', TestECSRoom);
 
-            const client = await env.createClient()
-            await client.joinRoom('ecs-test')
+            const client = await env.createClient();
+            await client.joinRoom('ecs-test');
 
-            expect(client.roomId).toBeDefined()
-        })
+            expect(client.roomId).toBeDefined();
+        });
 
         it('should have World managed by Core.worldManager', async () => {
-            env.server.define('ecs-test', TestECSRoom)
+            env.server.define('ecs-test', TestECSRoom);
 
-            const client = await env.createClient()
-            await client.joinRoom('ecs-test')
+            const client = await env.createClient();
+            await client.joinRoom('ecs-test');
 
             // 验证 World 正常创建（通过消息通信验证）
-            const pongPromise = client.waitForRoomMessage<{ timestamp: number }>('Pong')
-            client.sendToRoom('Ping', {})
-            const pong = await pongPromise
+            const pongPromise = client.waitForRoomMessage<{ timestamp: number }>('Pong');
+            client.sendToRoom('Ping', {});
+            const pong = await pongPromise;
 
-            expect(pong.timestamp).toBeGreaterThan(0)
-        })
-    })
+            expect(pong.timestamp).toBeGreaterThan(0);
+        });
+    });
 
     // ========================================================================
     // Player Entity Management | 玩家实体管理
@@ -176,41 +166,41 @@ describe('ECSRoom Integration Tests', () => {
 
     describe('Player Entity Management', () => {
         it('should create player entity on join', async () => {
-            env.server.define('ecs-test', TestECSRoom)
+            env.server.define('ecs-test', TestECSRoom);
 
-            const client1 = await env.createClient()
-            const { roomId } = await client1.joinRoom('ecs-test')
+            const client1 = await env.createClient();
+            const { roomId } = await client1.joinRoom('ecs-test');
 
             // 等待第二个玩家加入时收到广播
             const joinPromise = client1.waitForRoomMessage<{ playerId: string; name: string }>(
                 'PlayerJoined'
-            )
+            );
 
-            const client2 = await env.createClient()
-            await client2.joinRoomById(roomId)
+            const client2 = await env.createClient();
+            await client2.joinRoomById(roomId);
 
-            const joinMsg = await joinPromise
-            expect(joinMsg.playerId).toBe(client2.playerId)
-            expect(joinMsg.name).toContain('Player_')
-        })
+            const joinMsg = await joinPromise;
+            expect(joinMsg.playerId).toBe(client2.playerId);
+            expect(joinMsg.name).toContain('Player_');
+        });
 
         it('should destroy player entity on leave', async () => {
-            env.server.define('ecs-test', TestECSRoom)
+            env.server.define('ecs-test', TestECSRoom);
 
-            const client1 = await env.createClient()
-            const { roomId } = await client1.joinRoom('ecs-test')
+            const client1 = await env.createClient();
+            const { roomId } = await client1.joinRoom('ecs-test');
 
-            const client2 = await env.createClient()
-            await client2.joinRoomById(roomId)
+            const client2 = await env.createClient();
+            await client2.joinRoomById(roomId);
 
-            const leavePromise = client1.waitForRoomMessage<{ playerId: string }>('PlayerLeft')
+            const leavePromise = client1.waitForRoomMessage<{ playerId: string }>('PlayerLeft');
 
-            await client2.leaveRoom()
+            await client2.leaveRoom();
 
-            const leaveMsg = await leavePromise
-            expect(leaveMsg.playerId).toBeDefined()
-        })
-    })
+            const leaveMsg = await leavePromise;
+            expect(leaveMsg.playerId).toBeDefined();
+        });
+    });
 
     // ========================================================================
     // Component Sync | 组件同步
@@ -218,41 +208,41 @@ describe('ECSRoom Integration Tests', () => {
 
     describe('Component State Updates', () => {
         it('should update component via message handler', async () => {
-            env.server.define('ecs-test', TestECSRoom)
+            env.server.define('ecs-test', TestECSRoom);
 
-            const client = await env.createClient()
-            await client.joinRoom('ecs-test')
+            const client = await env.createClient();
+            await client.joinRoom('ecs-test');
 
-            client.sendToRoom('Move', { x: 100, y: 200 })
+            client.sendToRoom('Move', { x: 100, y: 200 });
 
             // 等待处理
-            await wait(50)
+            await wait(50);
 
             // 验证 Ping/Pong 仍能工作（房间仍活跃）
-            const pongPromise = client.waitForRoomMessage<{ timestamp: number }>('Pong')
-            client.sendToRoom('Ping', {})
-            const pong = await pongPromise
+            const pongPromise = client.waitForRoomMessage<{ timestamp: number }>('Pong');
+            client.sendToRoom('Ping', {});
+            const pong = await pongPromise;
 
-            expect(pong.timestamp).toBeGreaterThan(0)
-        })
+            expect(pong.timestamp).toBeGreaterThan(0);
+        });
 
         it('should handle AddScore message', async () => {
-            env.server.define('ecs-test', TestECSRoom)
+            env.server.define('ecs-test', TestECSRoom);
 
-            const client = await env.createClient()
-            await client.joinRoom('ecs-test')
+            const client = await env.createClient();
+            await client.joinRoom('ecs-test');
 
-            client.sendToRoom('AddScore', { amount: 50 })
-            client.sendToRoom('AddScore', { amount: 25 })
+            client.sendToRoom('AddScore', { amount: 50 });
+            client.sendToRoom('AddScore', { amount: 25 });
 
-            await wait(50)
+            await wait(50);
 
             // 确认房间仍然活跃
-            const pongPromise = client.waitForRoomMessage<{ timestamp: number }>('Pong')
-            client.sendToRoom('Ping', {})
-            await pongPromise
-        })
-    })
+            const pongPromise = client.waitForRoomMessage<{ timestamp: number }>('Pong');
+            client.sendToRoom('Ping', {});
+            await pongPromise;
+        });
+    });
 
     // ========================================================================
     // Sync Broadcast | 同步广播
@@ -260,22 +250,22 @@ describe('ECSRoom Integration Tests', () => {
 
     describe('State Sync Broadcast', () => {
         it('should receive $sync messages when enabled', async () => {
-            env.server.define('ecs-test', TestECSRoom)
+            env.server.define('ecs-test', TestECSRoom);
 
-            const client = await env.createClient()
-            await client.joinRoom('ecs-test')
+            const client = await env.createClient();
+            await client.joinRoom('ecs-test');
 
             // 触发状态变更
-            client.sendToRoom('Move', { x: 50, y: 75 })
+            client.sendToRoom('Move', { x: 50, y: 75 });
 
             // 等待 tick 处理
-            await wait(200)
+            await wait(200);
 
             // 检查是否收到 $sync 消息
-            const hasSync = client.hasReceivedMessage('RoomMessage')
-            expect(hasSync).toBe(true)
-        })
-    })
+            const hasSync = client.hasReceivedMessage('RoomMessage');
+            expect(hasSync).toBe(true);
+        });
+    });
 
     // ========================================================================
     // Multi-player Sync | 多玩家同步
@@ -283,47 +273,47 @@ describe('ECSRoom Integration Tests', () => {
 
     describe('Multi-player Scenarios', () => {
         it('should handle multiple players in same room', async () => {
-            env.server.define('ecs-test', TestECSRoom)
+            env.server.define('ecs-test', TestECSRoom);
 
-            const client1 = await env.createClient()
-            const { roomId } = await client1.joinRoom('ecs-test')
+            const client1 = await env.createClient();
+            const { roomId } = await client1.joinRoom('ecs-test');
 
-            const client2 = await env.createClient()
-            const joinPromise = client1.waitForRoomMessage<{ playerId: string }>('PlayerJoined')
-            await client2.joinRoomById(roomId)
+            const client2 = await env.createClient();
+            const joinPromise = client1.waitForRoomMessage<{ playerId: string }>('PlayerJoined');
+            await client2.joinRoomById(roomId);
 
-            const joinMsg = await joinPromise
-            expect(joinMsg.playerId).toBe(client2.playerId)
-        })
+            const joinMsg = await joinPromise;
+            expect(joinMsg.playerId).toBe(client2.playerId);
+        });
 
         it('should broadcast to all players on state change', async () => {
-            env.server.define('ecs-test', TestECSRoom)
+            env.server.define('ecs-test', TestECSRoom);
 
-            const client1 = await env.createClient()
-            const { roomId } = await client1.joinRoom('ecs-test')
+            const client1 = await env.createClient();
+            const { roomId } = await client1.joinRoom('ecs-test');
 
-            const client2 = await env.createClient()
+            const client2 = await env.createClient();
 
             // client1 等待收到 client2 加入的广播
-            const joinPromise = client1.waitForRoomMessage<{ playerId: string }>('PlayerJoined')
+            const joinPromise = client1.waitForRoomMessage<{ playerId: string }>('PlayerJoined');
 
-            await client2.joinRoomById(roomId)
+            await client2.joinRoomById(roomId);
 
-            const joinMsg = await joinPromise
-            expect(joinMsg.playerId).toBe(client2.playerId)
+            const joinMsg = await joinPromise;
+            expect(joinMsg.playerId).toBe(client2.playerId);
 
             // 验证每个客户端都能独立通信
-            const pong1Promise = client1.waitForRoomMessage<{ timestamp: number }>('Pong')
-            client1.sendToRoom('Ping', {})
-            const pong1 = await pong1Promise
-            expect(pong1.timestamp).toBeGreaterThan(0)
+            const pong1Promise = client1.waitForRoomMessage<{ timestamp: number }>('Pong');
+            client1.sendToRoom('Ping', {});
+            const pong1 = await pong1Promise;
+            expect(pong1.timestamp).toBeGreaterThan(0);
 
-            const pong2Promise = client2.waitForRoomMessage<{ timestamp: number }>('Pong')
-            client2.sendToRoom('Ping', {})
-            const pong2 = await pong2Promise
-            expect(pong2.timestamp).toBeGreaterThan(0)
-        })
-    })
+            const pong2Promise = client2.waitForRoomMessage<{ timestamp: number }>('Pong');
+            client2.sendToRoom('Ping', {});
+            const pong2 = await pong2Promise;
+            expect(pong2.timestamp).toBeGreaterThan(0);
+        });
+    });
 
     // ========================================================================
     // Cleanup | 清理
@@ -331,18 +321,18 @@ describe('ECSRoom Integration Tests', () => {
 
     describe('Room Cleanup', () => {
         it('should cleanup World on dispose', async () => {
-            env.server.define('ecs-test', TestECSRoom)
+            env.server.define('ecs-test', TestECSRoom);
 
-            const client = await env.createClient()
-            await client.joinRoom('ecs-test')
+            const client = await env.createClient();
+            await client.joinRoom('ecs-test');
 
-            await client.leaveRoom()
+            await client.leaveRoom();
 
             // 等待自动销毁
-            await wait(100)
+            await wait(100);
 
             // 房间应该已销毁
-            expect(client.roomId).toBeNull()
-        })
-    })
-})
+            expect(client.roomId).toBeNull();
+        });
+    });
+});

packages/framework/server/src/ecs/ECSRoom.ts

@@ -24,7 +24,7 @@ import {
     NETWORK_ENTITY_METADATA,
     type NetworkEntityMetadata,
     // Events
-    ECSEventType,
+    ECSEventType
 } from '@esengine/ecs-framework';
 
 import { Room, type RoomOptions } from '../room/Room.js';
@@ -62,7 +62,7 @@ export interface ECSRoomConfig {
 const DEFAULT_ECS_CONFIG: ECSRoomConfig = {
     syncInterval: 50, // 20 Hz
     enableDeltaSync: true,
-    enableAutoNetworkEntity: true,
+    enableAutoNetworkEntity: true
 };
 
 /**
@@ -305,7 +305,7 @@ export abstract class ECSRoom<TState = any, TPlayerData = Record<string, unknown
      */
     protected broadcastDelta(): void {
         const entities = this._getSyncEntities();
-        const changedEntities = entities.filter(entity => this._hasChanges(entity));
+        const changedEntities = entities.filter((entity) => this._hasChanges(entity));
 
         if (changedEntities.length === 0) return;
 

packages/framework/server/src/ecs/index.ts

@@ -41,7 +41,7 @@ export type {
     Component,
     EntitySystem,
     Scene,
-    World,
+    World
 } from '@esengine/ecs-framework';
 
 // Re-export sync types
@@ -55,7 +55,7 @@ export {
     SyncOperation,
     type SyncType,
     type SyncFieldMetadata,
-    type SyncMetadata,
+    type SyncMetadata
 } from '@esengine/ecs-framework';
 
 // Re-export room decorators

packages/framework/server/src/helpers/define.ts

@@ -1,9 +1,9 @@
 /**
- * @zh API 和消息定义助手
- * @en API and message definition helpers
+ * @zh API、消息和 HTTP 定义助手
+ * @en API, message, and HTTP definition helpers
  */
 
-import type { ApiDefinition, MsgDefinition } from '../types/index.js'
+import type { ApiDefinition, MsgDefinition, HttpDefinition } from '../types/index.js';
 
 /**
  * @zh 定义 API 处理器
@@ -25,7 +25,7 @@ import type { ApiDefinition, MsgDefinition } from '../types/index.js'
 export function defineApi<TReq, TRes, TData = Record<string, unknown>>(
     definition: ApiDefinition<TReq, TRes, TData>
 ): ApiDefinition<TReq, TRes, TData> {
-    return definition
+    return definition;
 }
 
 /**
@@ -47,5 +47,35 @@ export function defineApi<TReq, TRes, TData = Record<string, unknown>>(
 export function defineMsg<TMsg, TData = Record<string, unknown>>(
     definition: MsgDefinition<TMsg, TData>
 ): MsgDefinition<TMsg, TData> {
-    return definition
+    return definition;
+}
+
+/**
+ * @zh 定义 HTTP 路由处理器
+ * @en Define HTTP route handler
+ *
+ * @example
+ * ```typescript
+ * // src/http/login.ts
+ * import { defineHttp } from '@esengine/server'
+ *
+ * interface LoginBody {
+ *     username: string
+ *     password: string
+ * }
+ *
+ * export default defineHttp<LoginBody>({
+ *     method: 'POST',
+ *     handler(req, res) {
+ *         const { username, password } = req.body
+ *         // ... validate credentials
+ *         res.json({ token: '...', userId: '...' })
+ *     }
+ * })
+ * ```
+ */
+export function defineHttp<TBody = unknown>(
+    definition: HttpDefinition<TBody>
+): HttpDefinition<TBody> {
+    return definition;
 }

packages/framework/server/src/http/__tests__/router.test.ts

@@ -0,0 +1,672 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { createServer as createHttpServer, type IncomingMessage, type ServerResponse } from 'node:http';
+import { createHttpRouter } from '../router.js';
+import type { HttpMiddleware, HttpRoutes } from '../types.js';
+
+/**
+ * @zh 创建模拟请求对象
+ * @en Create mock request object
+ */
+function createMockRequest(options: {
+    method?: string;
+    url?: string;
+    headers?: Record<string, string>;
+    body?: string;
+} = {}): IncomingMessage {
+    const { method = 'GET', url = '/', headers = {}, body } = options;
+
+    const req = {
+        method,
+        url,
+        headers: { host: 'localhost', ...headers },
+        socket: { remoteAddress: '127.0.0.1' },
+        on: vi.fn((event: string, handler: (data?: any) => void) => {
+            if (event === 'data' && body) {
+                handler(Buffer.from(body));
+            }
+            if (event === 'end') {
+                handler();
+            }
+            return req;
+        })
+    } as unknown as IncomingMessage;
+
+    return req;
+}
+
+/**
+ * @zh 创建模拟响应对象
+ * @en Create mock response object
+ */
+function createMockResponse(): ServerResponse & {
+    _statusCode: number;
+    _headers: Record<string, string>;
+    _body: string;
+} {
+    const res = {
+        _statusCode: 200,
+        _headers: {} as Record<string, string>,
+        _body: '',
+        writableEnded: false,
+
+        get statusCode() {
+            return this._statusCode;
+        },
+        set statusCode(code: number) {
+            this._statusCode = code;
+        },
+
+        setHeader(name: string, value: string) {
+            this._headers[name.toLowerCase()] = value;
+        },
+        removeHeader(name: string) {
+            delete this._headers[name.toLowerCase()];
+        },
+        end(data?: string) {
+            this._body = data ?? '';
+            this.writableEnded = true;
+        }
+    } as any;
+
+    return res;
+}
+
+describe('HTTP Router', () => {
+    describe('Route Matching', () => {
+        it('should match exact paths', async () => {
+            const handler = vi.fn((req, res) => res.json({ ok: true }));
+            const router = createHttpRouter({
+                '/api/health': handler
+            });
+
+            const req = createMockRequest({ url: '/api/health' });
+            const res = createMockResponse();
+
+            const matched = await router(req, res);
+
+            expect(matched).toBe(true);
+            expect(handler).toHaveBeenCalled();
+        });
+
+        it('should return false for non-matching paths', async () => {
+            const router = createHttpRouter({
+                '/api/health': (req, res) => res.json({ ok: true })
+            });
+
+            const req = createMockRequest({ url: '/api/unknown' });
+            const res = createMockResponse();
+
+            const matched = await router(req, res);
+
+            expect(matched).toBe(false);
+        });
+
+        it('should match by HTTP method', async () => {
+            const getHandler = vi.fn((req, res) => res.json({ method: 'GET' }));
+            const postHandler = vi.fn((req, res) => res.json({ method: 'POST' }));
+
+            const router = createHttpRouter({
+                '/api/users': {
+                    GET: getHandler,
+                    POST: postHandler
+                }
+            });
+
+            const getReq = createMockRequest({ method: 'GET', url: '/api/users' });
+            const getRes = createMockResponse();
+            await router(getReq, getRes);
+            expect(getHandler).toHaveBeenCalled();
+            expect(postHandler).not.toHaveBeenCalled();
+
+            getHandler.mockClear();
+            postHandler.mockClear();
+
+            const postReq = createMockRequest({ method: 'POST', url: '/api/users' });
+            const postRes = createMockResponse();
+            await router(postReq, postRes);
+            expect(postHandler).toHaveBeenCalled();
+            expect(getHandler).not.toHaveBeenCalled();
+        });
+    });
+
+    describe('Route Parameters', () => {
+        it('should extract single route param', async () => {
+            let capturedParams: Record<string, string> = {};
+
+            const router = createHttpRouter({
+                '/users/:id': (req, res) => {
+                    capturedParams = req.params;
+                    res.json({ id: req.params.id });
+                }
+            });
+
+            const req = createMockRequest({ url: '/users/123' });
+            const res = createMockResponse();
+
+            await router(req, res);
+
+            expect(capturedParams).toEqual({ id: '123' });
+        });
+
+        it('should extract multiple route params', async () => {
+            let capturedParams: Record<string, string> = {};
+
+            const router = createHttpRouter({
+                '/users/:userId/posts/:postId': (req, res) => {
+                    capturedParams = req.params;
+                    res.json(req.params);
+                }
+            });
+
+            const req = createMockRequest({ url: '/users/42/posts/99' });
+            const res = createMockResponse();
+
+            await router(req, res);
+
+            expect(capturedParams).toEqual({ userId: '42', postId: '99' });
+        });
+
+        it('should decode URI components in params', async () => {
+            let capturedParams: Record<string, string> = {};
+
+            const router = createHttpRouter({
+                '/search/:query': (req, res) => {
+                    capturedParams = req.params;
+                    res.json({ query: req.params.query });
+                }
+            });
+
+            const req = createMockRequest({ url: '/search/hello%20world' });
+            const res = createMockResponse();
+
+            await router(req, res);
+
+            expect(capturedParams.query).toBe('hello world');
+        });
+
+        it('should prioritize static routes over param routes', async () => {
+            const staticHandler = vi.fn((req, res) => res.json({ type: 'static' }));
+            const paramHandler = vi.fn((req, res) => res.json({ type: 'param' }));
+
+            const router = createHttpRouter({
+                '/users/me': staticHandler,
+                '/users/:id': paramHandler
+            });
+
+            const req = createMockRequest({ url: '/users/me' });
+            const res = createMockResponse();
+
+            await router(req, res);
+
+            expect(staticHandler).toHaveBeenCalled();
+            expect(paramHandler).not.toHaveBeenCalled();
+        });
+    });
+
+    describe('Middleware', () => {
+        it('should execute global middlewares in order', async () => {
+            const order: number[] = [];
+
+            const middleware1: HttpMiddleware = async (req, res, next) => {
+                order.push(1);
+                await next();
+                order.push(4);
+            };
+
+            const middleware2: HttpMiddleware = async (req, res, next) => {
+                order.push(2);
+                await next();
+                order.push(3);
+            };
+
+            const router = createHttpRouter(
+                {
+                    '/test': (req, res) => {
+                        order.push(0);
+                        res.json({ ok: true });
+                    }
+                },
+                { middlewares: [middleware1, middleware2] }
+            );
+
+            const req = createMockRequest({ url: '/test' });
+            const res = createMockResponse();
+
+            await router(req, res);
+
+            expect(order).toEqual([1, 2, 0, 3, 4]);
+        });
+
+        it('should allow middleware to short-circuit', async () => {
+            const handler = vi.fn((req, res) => res.json({ ok: true }));
+
+            const authMiddleware: HttpMiddleware = async (req, res, next) => {
+                res.error(401, 'Unauthorized');
+                // 不调用 next()
+            };
+
+            const router = createHttpRouter(
+                { '/protected': handler },
+                { middlewares: [authMiddleware] }
+            );
+
+            const req = createMockRequest({ url: '/protected' });
+            const res = createMockResponse();
+
+            await router(req, res);
+
+            expect(handler).not.toHaveBeenCalled();
+            expect(res._statusCode).toBe(401);
+        });
+
+        it('should execute route-level middlewares', async () => {
+            const globalMiddleware = vi.fn(async (req, res, next) => {
+                (req as any).global = true;
+                await next();
+            });
+
+            const routeMiddleware = vi.fn(async (req, res, next) => {
+                (req as any).route = true;
+                await next();
+            });
+
+            let receivedReq: any;
+            const router = createHttpRouter(
+                {
+                    '/test': {
+                        handler: (req, res) => {
+                            receivedReq = req;
+                            res.json({ ok: true });
+                        },
+                        middlewares: [routeMiddleware]
+                    }
+                },
+                { middlewares: [globalMiddleware] }
+            );
+
+            const req = createMockRequest({ url: '/test' });
+            const res = createMockResponse();
+
+            await router(req, res);
+
+            expect(globalMiddleware).toHaveBeenCalled();
+            expect(routeMiddleware).toHaveBeenCalled();
+            expect(receivedReq.global).toBe(true);
+            expect(receivedReq.route).toBe(true);
+        });
+    });
+
+    describe('Timeout', () => {
+        it('should timeout slow handlers', async () => {
+            const router = createHttpRouter(
+                {
+                    '/slow': async (req, res) => {
+                        await new Promise(resolve => setTimeout(resolve, 200));
+                        res.json({ ok: true });
+                    }
+                },
+                { timeout: 50 }
+            );
+
+            const req = createMockRequest({ url: '/slow' });
+            const res = createMockResponse();
+
+            await router(req, res);
+
+            expect(res._statusCode).toBe(408);
+            expect(JSON.parse(res._body)).toEqual({ error: 'Request Timeout' });
+        });
+
+        it('should use route-specific timeout over global', async () => {
+            const router = createHttpRouter(
+                {
+                    '/slow': {
+                        handler: async (req, res) => {
+                            await new Promise(resolve => setTimeout(resolve, 100));
+                            res.json({ ok: true });
+                        },
+                        timeout: 200 // 路由级超时更长
+                    }
+                },
+                { timeout: 50 } // 全局超时较短
+            );
+
+            const req = createMockRequest({ url: '/slow' });
+            const res = createMockResponse();
+
+            await router(req, res);
+
+            // 应该成功，因为路由级超时是 200ms
+            expect(res._statusCode).toBe(200);
+        });
+
+        it('should not timeout fast handlers', async () => {
+            const router = createHttpRouter(
+                {
+                    '/fast': (req, res) => {
+                        res.json({ ok: true });
+                    }
+                },
+                { timeout: 1000 }
+            );
+
+            const req = createMockRequest({ url: '/fast' });
+            const res = createMockResponse();
+
+            await router(req, res);
+
+            expect(res._statusCode).toBe(200);
+        });
+    });
+
+    describe('Request Parsing', () => {
+        it('should parse query parameters', async () => {
+            let capturedQuery: Record<string, string> = {};
+
+            const router = createHttpRouter({
+                '/search': (req, res) => {
+                    capturedQuery = req.query;
+                    res.json({ query: req.query });
+                }
+            });
+
+            const req = createMockRequest({ url: '/search?q=hello&page=1' });
+            const res = createMockResponse();
+
+            await router(req, res);
+
+            expect(capturedQuery).toEqual({ q: 'hello', page: '1' });
+        });
+
+        it('should parse JSON body', async () => {
+            let capturedBody: unknown;
+
+            const router = createHttpRouter({
+                '/api/data': {
+                    POST: (req, res) => {
+                        capturedBody = req.body;
+                        res.json({ received: true });
+                    }
+                }
+            });
+
+            const req = createMockRequest({
+                method: 'POST',
+                url: '/api/data',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ name: 'test', value: 42 })
+            });
+            const res = createMockResponse();
+
+            await router(req, res);
+
+            expect(capturedBody).toEqual({ name: 'test', value: 42 });
+        });
+
+        it('should extract client IP', async () => {
+            let capturedIp: string = '';
+
+            const router = createHttpRouter({
+                '/ip': (req, res) => {
+                    capturedIp = req.ip;
+                    res.json({ ip: req.ip });
+                }
+            });
+
+            const req = createMockRequest({ url: '/ip' });
+            const res = createMockResponse();
+
+            await router(req, res);
+
+            expect(capturedIp).toBe('127.0.0.1');
+        });
+
+        it('should prefer X-Forwarded-For header for IP', async () => {
+            let capturedIp: string = '';
+
+            const router = createHttpRouter({
+                '/ip': (req, res) => {
+                    capturedIp = req.ip;
+                    res.json({ ip: req.ip });
+                }
+            });
+
+            const req = createMockRequest({
+                url: '/ip',
+                headers: { 'x-forwarded-for': '203.0.113.195, 70.41.3.18' }
+            });
+            const res = createMockResponse();
+
+            await router(req, res);
+
+            expect(capturedIp).toBe('203.0.113.195');
+        });
+    });
+
+    describe('CORS', () => {
+        it('should handle OPTIONS preflight', async () => {
+            const router = createHttpRouter(
+                { '/api/data': (req, res) => res.json({}) },
+                { cors: true }
+            );
+
+            const req = createMockRequest({
+                method: 'OPTIONS',
+                url: '/api/data',
+                headers: { origin: 'http://example.com' }
+            });
+            const res = createMockResponse();
+
+            await router(req, res);
+
+            expect(res._statusCode).toBe(204);
+            // cors: true 使用通配符 '*'，安全默认不启用 credentials
+            expect(res._headers['access-control-allow-origin']).toBe('*');
+        });
+
+        it('should use wildcard when origin: true without credentials (for security)', async () => {
+            // 为了安全（避免 CodeQL 警告），origin: true 现在等同于 origin: '*'
+            // For security (avoiding CodeQL warnings), origin: true now equals origin: '*'
+            const router = createHttpRouter(
+                { '/api/data': (req, res) => res.json({}) },
+                { cors: { origin: true } }
+            );
+
+            const req = createMockRequest({
+                method: 'OPTIONS',
+                url: '/api/data',
+                headers: { origin: 'http://example.com' }
+            });
+            const res = createMockResponse();
+
+            await router(req, res);
+
+            expect(res._statusCode).toBe(204);
+            expect(res._headers['access-control-allow-origin']).toBe('*');
+        });
+
+        it('should set CORS headers on regular requests', async () => {
+            const router = createHttpRouter(
+                { '/api/data': (req, res) => res.json({}) },
+                { cors: { origin: 'http://allowed.com', credentials: true } }
+            );
+
+            const req = createMockRequest({
+                url: '/api/data',
+                headers: { origin: 'http://allowed.com' }
+            });
+            const res = createMockResponse();
+
+            await router(req, res);
+
+            expect(res._headers['access-control-allow-origin']).toBe('http://allowed.com');
+            expect(res._headers['access-control-allow-credentials']).toBe('true');
+        });
+
+        it('should not set CORS headers when cors is false', async () => {
+            const router = createHttpRouter(
+                { '/api/data': (req, res) => res.json({}) },
+                { cors: false }
+            );
+
+            const req = createMockRequest({
+                url: '/api/data',
+                headers: { origin: 'http://example.com' }
+            });
+            const res = createMockResponse();
+
+            await router(req, res);
+
+            expect(res._headers['access-control-allow-origin']).toBeUndefined();
+        });
+
+        it('should not allow credentials with wildcard origin (security)', async () => {
+            const router = createHttpRouter(
+                { '/api/data': (req, res) => res.json({}) },
+                { cors: { origin: '*', credentials: true } }
+            );
+
+            const req = createMockRequest({
+                url: '/api/data',
+                headers: { origin: 'http://evil.com' }
+            });
+            const res = createMockResponse();
+
+            await router(req, res);
+
+            // 安全：credentials + 通配符时不设置 origin 头
+            expect(res._headers['access-control-allow-origin']).toBeUndefined();
+            expect(res._headers['access-control-allow-credentials']).toBeUndefined();
+        });
+
+        it('should not allow credentials with origin: true (security)', async () => {
+            const router = createHttpRouter(
+                { '/api/data': (req, res) => res.json({}) },
+                { cors: { origin: true, credentials: true } }
+            );
+
+            const req = createMockRequest({
+                url: '/api/data',
+                headers: { origin: 'http://evil.com' }
+            });
+            const res = createMockResponse();
+
+            await router(req, res);
+
+            // 安全：credentials + 反射时不设置 origin 头
+            expect(res._headers['access-control-allow-origin']).toBeUndefined();
+            expect(res._headers['access-control-allow-credentials']).toBeUndefined();
+        });
+
+        it('should allow credentials with whitelist origin', async () => {
+            const router = createHttpRouter(
+                { '/api/data': (req, res) => res.json({}) },
+                { cors: { origin: ['http://trusted.com', 'http://also-trusted.com'], credentials: true } }
+            );
+
+            const req = createMockRequest({
+                url: '/api/data',
+                headers: { origin: 'http://trusted.com' }
+            });
+            const res = createMockResponse();
+
+            await router(req, res);
+
+            expect(res._headers['access-control-allow-origin']).toBe('http://trusted.com');
+            expect(res._headers['access-control-allow-credentials']).toBe('true');
+        });
+
+        it('should reject non-whitelisted origin with credentials', async () => {
+            const router = createHttpRouter(
+                { '/api/data': (req, res) => res.json({}) },
+                { cors: { origin: ['http://trusted.com'], credentials: true } }
+            );
+
+            const req = createMockRequest({
+                url: '/api/data',
+                headers: { origin: 'http://evil.com' }
+            });
+            const res = createMockResponse();
+
+            await router(req, res);
+
+            expect(res._headers['access-control-allow-origin']).toBeUndefined();
+            expect(res._headers['access-control-allow-credentials']).toBeUndefined();
+        });
+    });
+
+    describe('Response Methods', () => {
+        it('should send JSON response', async () => {
+            const router = createHttpRouter({
+                '/json': (req, res) => res.json({ message: 'hello' })
+            });
+
+            const req = createMockRequest({ url: '/json' });
+            const res = createMockResponse();
+
+            await router(req, res);
+
+            expect(res._headers['content-type']).toBe('application/json; charset=utf-8');
+            expect(JSON.parse(res._body)).toEqual({ message: 'hello' });
+        });
+
+        it('should send text response', async () => {
+            const router = createHttpRouter({
+                '/text': (req, res) => res.text('Hello World')
+            });
+
+            const req = createMockRequest({ url: '/text' });
+            const res = createMockResponse();
+
+            await router(req, res);
+
+            expect(res._headers['content-type']).toBe('text/plain; charset=utf-8');
+            expect(res._body).toBe('Hello World');
+        });
+
+        it('should send error response', async () => {
+            const router = createHttpRouter({
+                '/error': (req, res) => res.error(404, 'Not Found')
+            });
+
+            const req = createMockRequest({ url: '/error' });
+            const res = createMockResponse();
+
+            await router(req, res);
+
+            expect(res._statusCode).toBe(404);
+            expect(JSON.parse(res._body)).toEqual({ error: 'Not Found' });
+        });
+
+        it('should support status chaining', async () => {
+            const router = createHttpRouter({
+                '/created': (req, res) => res.status(201).json({ id: 1 })
+            });
+
+            const req = createMockRequest({ url: '/created' });
+            const res = createMockResponse();
+
+            await router(req, res);
+
+            expect(res._statusCode).toBe(201);
+        });
+    });
+
+    describe('Error Handling', () => {
+        it('should catch handler errors and return 500', async () => {
+            const router = createHttpRouter({
+                '/error': () => {
+                    throw new Error('Something went wrong');
+                }
+            });
+
+            const req = createMockRequest({ url: '/error' });
+            const res = createMockResponse();
+
+            await router(req, res);
+
+            expect(res._statusCode).toBe(500);
+            expect(JSON.parse(res._body)).toEqual({ error: 'Internal Server Error' });
+        });
+    });
+});

packages/framework/server/src/http/index.ts

@@ -0,0 +1,8 @@
+/**
+ * @zh HTTP 模块导出
+ * @en HTTP module exports
+ */
+
+export * from './types.js';
+export { createHttpRouter } from './router.js';
+export * from './middleware.js';

packages/framework/server/src/http/middleware.ts

@@ -0,0 +1,167 @@
+/**
+ * @zh 内置 HTTP 中间件
+ * @en Built-in HTTP middlewares
+ */
+
+import { createLogger } from '../logger.js';
+import type { HttpMiddleware } from './types.js';
+
+/**
+ * @zh 请求日志中间件
+ * @en Request logging middleware
+ *
+ * @example
+ * ```typescript
+ * const router = createHttpRouter(routes, {
+ *     middlewares: [requestLogger()]
+ * });
+ * ```
+ */
+export function requestLogger(options: {
+    /**
+     * @zh 日志器名称
+     * @en Logger name
+     */
+    name?: string;
+    /**
+     * @zh 是否记录请求体
+     * @en Whether to log request body
+     */
+    logBody?: boolean;
+} = {}): HttpMiddleware {
+    const logger = createLogger(options.name ?? 'HTTP');
+    const logBody = options.logBody ?? false;
+
+    return async (req, res, next) => {
+        const start = Date.now();
+        const { method, path, ip } = req;
+
+        if (logBody && req.body) {
+            logger.debug(`→ ${method} ${path}`, { ip, body: req.body });
+        } else {
+            logger.debug(`→ ${method} ${path}`, { ip });
+        }
+
+        await next();
+
+        const duration = Date.now() - start;
+        logger.info(`← ${method} ${path} ${res.raw.statusCode} ${duration}ms`);
+    };
+}
+
+/**
+ * @zh 请求体大小限制中间件
+ * @en Request body size limit middleware
+ *
+ * @example
+ * ```typescript
+ * const router = createHttpRouter(routes, {
+ *     middlewares: [bodyLimit(1024 * 1024)] // 1MB
+ * });
+ * ```
+ */
+export function bodyLimit(maxBytes: number): HttpMiddleware {
+    return async (req, res, next) => {
+        const contentLength = req.headers['content-length'];
+
+        if (contentLength) {
+            const length = parseInt(contentLength as string, 10);
+            if (length > maxBytes) {
+                res.error(413, 'Payload Too Large');
+                return;
+            }
+        }
+
+        await next();
+    };
+}
+
+/**
+ * @zh 响应时间头中间件
+ * @en Response time header middleware
+ *
+ * @zh 在响应头中添加 X-Response-Time
+ * @en Adds X-Response-Time header to response
+ */
+export function responseTime(): HttpMiddleware {
+    return async (req, res, next) => {
+        const start = Date.now();
+        await next();
+        const duration = Date.now() - start;
+        res.header('X-Response-Time', `${duration}ms`);
+    };
+}
+
+/**
+ * @zh 请求 ID 中间件
+ * @en Request ID middleware
+ *
+ * @zh 为每个请求生成唯一 ID，添加到响应头和请求对象
+ * @en Generates unique ID for each request, adds to response header and request object
+ */
+export function requestId(headerName: string = 'X-Request-ID'): HttpMiddleware {
+    return async (req, res, next) => {
+        const id = req.headers[headerName.toLowerCase()] as string
+            ?? generateId();
+
+        res.header(headerName, id);
+        (req as any).requestId = id;
+
+        await next();
+    };
+}
+
+/**
+ * @zh 生成简单的唯一 ID
+ * @en Generate simple unique ID
+ */
+function generateId(): string {
+    return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 9)}`;
+}
+
+/**
+ * @zh 安全头中间件
+ * @en Security headers middleware
+ *
+ * @zh 添加常用的安全响应头
+ * @en Adds common security response headers
+ */
+export function securityHeaders(options: {
+    /**
+     * @zh 是否禁用 X-Powered-By
+     * @en Whether to remove X-Powered-By
+     */
+    hidePoweredBy?: boolean;
+    /**
+     * @zh X-Frame-Options 值
+     * @en X-Frame-Options value
+     */
+    frameOptions?: 'DENY' | 'SAMEORIGIN';
+    /**
+     * @zh 是否启用 noSniff
+     * @en Whether to enable noSniff
+     */
+    noSniff?: boolean;
+} = {}): HttpMiddleware {
+    const {
+        hidePoweredBy = true,
+        frameOptions = 'SAMEORIGIN',
+        noSniff = true
+    } = options;
+
+    return async (req, res, next) => {
+        if (hidePoweredBy) {
+            res.raw.removeHeader('X-Powered-By');
+        }
+
+        if (frameOptions) {
+            res.header('X-Frame-Options', frameOptions);
+        }
+
+        if (noSniff) {
+            res.header('X-Content-Type-Options', 'nosniff');
+        }
+
+        await next();
+    };
+}

packages/framework/server/src/http/router.ts

@@ -0,0 +1,622 @@
+/**
+ * @zh HTTP 路由器
+ * @en HTTP Router
+ *
+ * @zh 支持路由参数、中间件和超时控制的 HTTP 路由实现
+ * @en HTTP router with route parameters, middleware and timeout support
+ */
+
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { createLogger } from '../logger.js';
+import type {
+    HttpRequest,
+    HttpResponse,
+    HttpHandler,
+    HttpRoutes,
+    HttpRouteMethods,
+    HttpMiddleware,
+    HttpRouterOptions,
+    HttpMethodHandler,
+    HttpHandlerDefinition,
+    CorsOptions
+} from './types.js';
+
+const logger = createLogger('HTTP');
+
+// ============================================================================
+// 路由解析 | Route Parsing
+// ============================================================================
+
+/**
+ * @zh 解析后的路由
+ * @en Parsed route
+ */
+interface ParsedRoute {
+    method: string;
+    path: string;
+    handler: HttpHandler;
+    pattern: RegExp;
+    paramNames: string[];
+    middlewares: HttpMiddleware[];
+    timeout?: number;
+    isStatic: boolean;
+}
+
+/**
+ * @zh 解析路由路径，提取参数名并生成匹配正则
+ * @en Parse route path, extract param names and generate matching regex
+ */
+function parseRoutePath(path: string): { pattern: RegExp; paramNames: string[]; isStatic: boolean } {
+    const paramNames: string[] = [];
+    const isStatic = !path.includes(':');
+
+    if (isStatic) {
+        return {
+            pattern: new RegExp(`^${escapeRegex(path)}$`),
+            paramNames,
+            isStatic: true
+        };
+    }
+
+    const segments = path.split('/').map(segment => {
+        if (segment.startsWith(':')) {
+            const paramName = segment.slice(1);
+            paramNames.push(paramName);
+            return '([^/]+)';
+        }
+        return escapeRegex(segment);
+    });
+
+    return {
+        pattern: new RegExp(`^${segments.join('/')}$`),
+        paramNames,
+        isStatic: false
+    };
+}
+
+/**
+ * @zh 转义正则表达式特殊字符
+ * @en Escape regex special characters
+ */
+function escapeRegex(str: string): string {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * @zh 匹配路由并提取参数
+ * @en Match route and extract params
+ */
+function matchRoute(
+    routes: ParsedRoute[],
+    path: string,
+    method: string
+): { route: ParsedRoute; params: Record<string, string> } | null {
+    // 优先匹配静态路由
+    for (const route of routes) {
+        if (!route.isStatic) continue;
+        if (route.method !== '*' && route.method !== method) continue;
+        if (route.pattern.test(path)) {
+            return { route, params: {} };
+        }
+    }
+
+    // 然后匹配动态路由
+    for (const route of routes) {
+        if (route.isStatic) continue;
+        if (route.method !== '*' && route.method !== method) continue;
+
+        const match = path.match(route.pattern);
+        if (match) {
+            const params: Record<string, string> = {};
+            route.paramNames.forEach((name, index) => {
+                params[name] = decodeURIComponent(match[index + 1]);
+            });
+            return { route, params };
+        }
+    }
+
+    return null;
+}
+
+// ============================================================================
+// 请求/响应处理 | Request/Response Handling
+// ============================================================================
+
+/**
+ * @zh 创建 HTTP 请求对象
+ * @en Create HTTP request object
+ */
+async function createRequest(
+    req: IncomingMessage,
+    params: Record<string, string> = {}
+): Promise<HttpRequest> {
+    const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
+
+    const query: Record<string, string> = {};
+    url.searchParams.forEach((value, key) => {
+        query[key] = value;
+    });
+
+    let body: unknown = null;
+    if (req.method === 'POST' || req.method === 'PUT' || req.method === 'PATCH') {
+        body = await parseBody(req);
+    }
+
+    const ip =
+        (req.headers['x-forwarded-for'] as string)?.split(',')[0]?.trim() ||
+        req.socket?.remoteAddress ||
+        'unknown';
+
+    return {
+        raw: req,
+        method: req.method ?? 'GET',
+        path: url.pathname,
+        params,
+        query,
+        headers: req.headers as Record<string, string | string[] | undefined>,
+        body,
+        ip
+    };
+}
+
+/**
+ * @zh 解析请求体
+ * @en Parse request body
+ */
+function parseBody(req: IncomingMessage): Promise<unknown> {
+    return new Promise((resolve) => {
+        const chunks: Buffer[] = [];
+
+        req.on('data', (chunk: Buffer) => {
+            chunks.push(chunk);
+        });
+
+        req.on('end', () => {
+            const rawBody = Buffer.concat(chunks).toString('utf-8');
+
+            if (!rawBody) {
+                resolve(null);
+                return;
+            }
+
+            const contentType = req.headers['content-type'] ?? '';
+
+            if (contentType.includes('application/json')) {
+                try {
+                    resolve(JSON.parse(rawBody));
+                } catch {
+                    resolve(rawBody);
+                }
+            } else if (contentType.includes('application/x-www-form-urlencoded')) {
+                const params = new URLSearchParams(rawBody);
+                const result: Record<string, string> = {};
+                params.forEach((value, key) => {
+                    result[key] = value;
+                });
+                resolve(result);
+            } else {
+                resolve(rawBody);
+            }
+        });
+
+        req.on('error', () => {
+            resolve(null);
+        });
+    });
+}
+
+/**
+ * @zh 创建 HTTP 响应对象
+ * @en Create HTTP response object
+ */
+function createResponse(res: ServerResponse): HttpResponse {
+    let statusCode = 200;
+    let ended = false;
+
+    const response: HttpResponse = {
+        raw: res,
+
+        status(code: number) {
+            statusCode = code;
+            return response;
+        },
+
+        header(name: string, value: string) {
+            if (!ended) {
+                res.setHeader(name, value);
+            }
+            return response;
+        },
+
+        json(data: unknown) {
+            if (ended) return;
+            ended = true;
+            res.setHeader('Content-Type', 'application/json; charset=utf-8');
+            res.statusCode = statusCode;
+            res.end(JSON.stringify(data));
+        },
+
+        text(data: string) {
+            if (ended) return;
+            ended = true;
+            res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+            res.statusCode = statusCode;
+            res.end(data);
+        },
+
+        error(code: number, message: string) {
+            if (ended) return;
+            ended = true;
+            res.setHeader('Content-Type', 'application/json; charset=utf-8');
+            res.statusCode = code;
+            res.end(JSON.stringify({ error: message }));
+        }
+    };
+
+    return response;
+}
+
+// ============================================================================
+// CORS 处理 | CORS Handling
+// ============================================================================
+
+/**
+ * @zh 将 origin 数组转换为白名单对象（用于 CodeQL 安全验证模式）
+ * @en Convert origin array to whitelist object (for CodeQL security validation pattern)
+ */
+function createOriginWhitelist(origins: readonly string[]): Record<string, true> {
+    const whitelist: Record<string, true> = {};
+    for (const origin of origins) {
+        whitelist[origin] = true;
+    }
+    return whitelist;
+}
+
+/**
+ * @zh 应用 CORS 头
+ * @en Apply CORS headers
+ *
+ * @zh 安全规则：credentials 只能与固定 origin 或白名单一起使用，不能使用通配符或反射
+ * @en Security rule: credentials can only be used with fixed origin or whitelist, not wildcard or reflect
+ */
+function applyCors(res: ServerResponse, req: IncomingMessage, cors: CorsOptions): void {
+    const credentials = cors.credentials ?? false;
+
+    // 设置 Access-Control-Allow-Origin
+    // 安全策略：当 credentials 为 true 时，只允许固定 origin 或白名单
+    if (typeof cors.origin === 'string' && cors.origin !== '*') {
+        // 固定字符串 origin（非通配符）：服务器配置的固定值
+        // Fixed string origin (non-wildcard): fixed value from server configuration
+        // 安全：cors.origin 来自 createHttpRouter 的 options 参数，是编译时配置值
+        // Security: cors.origin comes from createHttpRouter's options param, a compile-time config value
+        res.setHeader('Access-Control-Allow-Origin', cors.origin);
+        if (credentials) {
+            res.setHeader('Access-Control-Allow-Credentials', 'true');
+        }
+    } else if (Array.isArray(cors.origin)) {
+        // 白名单模式：使用对象键查找验证 origin（CodeQL 认可的安全模式）
+        // Whitelist mode: use object key lookup to validate origin (CodeQL recognized safe pattern)
+        const requestOrigin = req.headers.origin;
+        if (typeof requestOrigin === 'string') {
+            const whitelist = createOriginWhitelist(cors.origin);
+            if (requestOrigin in whitelist) {
+                res.setHeader('Access-Control-Allow-Origin', requestOrigin);
+                if (credentials) {
+                    res.setHeader('Access-Control-Allow-Credentials', 'true');
+                }
+            }
+        }
+        // 不在白名单中：不设置 origin 头
+    } else if (!credentials) {
+        // 通配符或反射模式：仅在无 credentials 时允许
+        // Wildcard or reflect mode: only allowed without credentials
+        // 注意：为了通过 CodeQL 安全扫描，reflect 模式 (cors.origin === true) 等同于通配符
+        // Note: For CodeQL security scanning, reflect mode (cors.origin === true) is treated as wildcard
+        if (cors.origin === '*' || cors.origin === true) {
+            res.setHeader('Access-Control-Allow-Origin', '*');
+        }
+    }
+    // credentials + 通配符/反射：不设置任何 origin 头（安全拒绝）
+
+    res.setHeader(
+        'Access-Control-Allow-Methods',
+        cors.methods?.join(', ') ?? 'GET, POST, PUT, DELETE, PATCH, OPTIONS'
+    );
+
+    res.setHeader(
+        'Access-Control-Allow-Headers',
+        cors.allowedHeaders?.join(', ') ?? 'Content-Type, Authorization'
+    );
+
+    if (cors.maxAge) {
+        res.setHeader('Access-Control-Max-Age', String(cors.maxAge));
+    }
+}
+
+// ============================================================================
+// 中间件执行 | Middleware Execution
+// ============================================================================
+
+/**
+ * @zh 执行中间件链
+ * @en Execute middleware chain
+ */
+async function executeMiddlewares(
+    middlewares: HttpMiddleware[],
+    req: HttpRequest,
+    res: HttpResponse,
+    finalHandler: () => Promise<void>
+): Promise<void> {
+    let index = 0;
+
+    const next = async (): Promise<void> => {
+        if (index < middlewares.length) {
+            const middleware = middlewares[index++];
+            await middleware(req, res, next);
+        } else {
+            await finalHandler();
+        }
+    };
+
+    await next();
+}
+
+// ============================================================================
+// 超时控制 | Timeout Control
+// ============================================================================
+
+/**
+ * @zh 带超时的执行器
+ * @en Execute with timeout
+ */
+async function executeWithTimeout(
+    handler: () => Promise<void>,
+    timeoutMs: number,
+    res: ServerResponse
+): Promise<void> {
+    let resolved = false;
+
+    const timeoutPromise = new Promise<never>((_, reject) => {
+        setTimeout(() => {
+            if (!resolved) {
+                reject(new Error('Request timeout'));
+            }
+        }, timeoutMs);
+    });
+
+    try {
+        await Promise.race([
+            handler().then(() => { resolved = true; }),
+            timeoutPromise
+        ]);
+    } catch (error) {
+        if (error instanceof Error && error.message === 'Request timeout') {
+            if (!res.writableEnded) {
+                res.statusCode = 408;
+                res.setHeader('Content-Type', 'application/json; charset=utf-8');
+                res.end(JSON.stringify({ error: 'Request Timeout' }));
+            }
+        } else {
+            throw error;
+        }
+    }
+}
+
+// ============================================================================
+// 路由解析辅助 | Route Parsing Helpers
+// ============================================================================
+
+/**
+ * @zh 判断是否为处理器定义对象（带 handler 属性）
+ * @en Check if value is a handler definition object (with handler property)
+ */
+function isHandlerDefinition(value: unknown): value is HttpHandlerDefinition {
+    return typeof value === 'object' && value !== null && 'handler' in value && typeof (value as HttpHandlerDefinition).handler === 'function';
+}
+
+/**
+ * @zh 判断是否为路由方法映射对象
+ * @en Check if value is a route methods mapping object
+ */
+function isRouteMethods(value: unknown): value is HttpRouteMethods {
+    if (typeof value !== 'object' || value === null) return false;
+    const methods = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'];
+    return Object.keys(value).some(key => methods.includes(key));
+}
+
+/**
+ * @zh 从方法处理器提取处理函数和配置
+ * @en Extract handler and config from method handler
+ */
+function extractHandler(methodHandler: HttpMethodHandler): {
+    handler: HttpHandler;
+    middlewares: HttpMiddleware[];
+    timeout?: number;
+} {
+    if (isHandlerDefinition(methodHandler)) {
+        return {
+            handler: methodHandler.handler,
+            middlewares: methodHandler.middlewares ?? [],
+            timeout: methodHandler.timeout
+        };
+    }
+    return {
+        handler: methodHandler,
+        middlewares: [],
+        timeout: undefined
+    };
+}
+
+// ============================================================================
+// 主路由器 | Main Router
+// ============================================================================
+
+/**
+ * @zh 创建 HTTP 路由器
+ * @en Create HTTP router
+ *
+ * @example
+ * ```typescript
+ * const router = createHttpRouter({
+ *     '/users': {
+ *         GET: (req, res) => res.json([]),
+ *         POST: (req, res) => res.json({ created: true })
+ *     },
+ *     '/users/:id': {
+ *         GET: (req, res) => res.json({ id: req.params.id }),
+ *         DELETE: {
+ *             handler: (req, res) => res.json({ deleted: true }),
+ *             middlewares: [authMiddleware],
+ *             timeout: 5000
+ *         }
+ *     }
+ * }, {
+ *     cors: true,
+ *     timeout: 30000,
+ *     middlewares: [loggerMiddleware]
+ * });
+ * ```
+ */
+export function createHttpRouter(
+    routes: HttpRoutes,
+    options: HttpRouterOptions = {}
+): (req: IncomingMessage, res: ServerResponse) => Promise<boolean> {
+    const globalMiddlewares = options.middlewares ?? [];
+    const globalTimeout = options.timeout;
+
+    // 解析路由
+    const parsedRoutes: ParsedRoute[] = [];
+
+    for (const [path, handlerOrMethods] of Object.entries(routes)) {
+        const { pattern, paramNames, isStatic } = parseRoutePath(path);
+
+        if (typeof handlerOrMethods === 'function') {
+            // 简单函数处理器
+            parsedRoutes.push({
+                method: '*',
+                path,
+                handler: handlerOrMethods,
+                pattern,
+                paramNames,
+                middlewares: [],
+                timeout: undefined,
+                isStatic
+            });
+        } else if (isRouteMethods(handlerOrMethods)) {
+            // 方法映射对象 { GET, POST, ... }
+            for (const [method, methodHandler] of Object.entries(handlerOrMethods)) {
+                if (methodHandler !== undefined) {
+                    const { handler, middlewares, timeout } = extractHandler(methodHandler);
+                    parsedRoutes.push({
+                        method,
+                        path,
+                        handler,
+                        pattern,
+                        paramNames,
+                        middlewares,
+                        timeout,
+                        isStatic
+                    });
+                }
+            }
+        } else if (isHandlerDefinition(handlerOrMethods)) {
+            // 带配置的处理器定义 { handler, middlewares, timeout }
+            const { handler, middlewares, timeout } = extractHandler(handlerOrMethods);
+            parsedRoutes.push({
+                method: '*',
+                path,
+                handler,
+                pattern,
+                paramNames,
+                middlewares,
+                timeout,
+                isStatic
+            });
+        }
+    }
+
+    // CORS 配置
+    // 安全默认：cors: true 时不启用 credentials，避免凭证泄露
+    // Safe default: cors: true doesn't enable credentials to prevent credential leak
+    const corsOptions: CorsOptions | null =
+        options.cors === true
+            ? { origin: '*' }
+            : options.cors === false
+                ? null
+                : options.cors ?? null;
+
+    /**
+     * @zh 处理 HTTP 请求
+     * @en Handle HTTP request
+     */
+    return async function handleRequest(
+        req: IncomingMessage,
+        res: ServerResponse
+    ): Promise<boolean> {
+        const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
+        const path = url.pathname;
+        const method = req.method ?? 'GET';
+
+        // 应用 CORS
+        if (corsOptions) {
+            applyCors(res, req, corsOptions);
+
+            if (method === 'OPTIONS') {
+                res.statusCode = 204;
+                res.end();
+                return true;
+            }
+        }
+
+        // 查找匹配的路由
+        const match = matchRoute(parsedRoutes, path, method);
+
+        if (!match) {
+            return false;
+        }
+
+        const { route, params } = match;
+
+        try {
+            const httpReq = await createRequest(req, params);
+            const httpRes = createResponse(res);
+
+            // 合并中间件：全局 + 路由级
+            const allMiddlewares = [...globalMiddlewares, ...route.middlewares];
+
+            // 确定超时时间：路由级 > 全局
+            const timeout = route.timeout ?? globalTimeout;
+
+            // 最终处理器
+            const finalHandler = async () => {
+                await route.handler(httpReq, httpRes);
+            };
+
+            // 执行中间件链 + 处理器
+            const executeHandler = async () => {
+                if (allMiddlewares.length > 0) {
+                    await executeMiddlewares(allMiddlewares, httpReq, httpRes, finalHandler);
+                } else {
+                    await finalHandler();
+                }
+            };
+
+            // 带超时执行
+            if (timeout && timeout > 0) {
+                await executeWithTimeout(executeHandler, timeout, res);
+            } else {
+                await executeHandler();
+            }
+
+            return true;
+        } catch (error) {
+            logger.error('Route handler error:', error);
+            if (!res.writableEnded) {
+                res.statusCode = 500;
+                res.setHeader('Content-Type', 'application/json');
+                res.end(JSON.stringify({ error: 'Internal Server Error' }));
+            }
+            return true;
+        }
+    };
+}

packages/framework/server/src/http/types.ts

@@ -0,0 +1,272 @@
+/**
+ * @zh HTTP 路由类型定义
+ * @en HTTP router type definitions
+ */
+
+import type { IncomingMessage, ServerResponse } from 'node:http';
+
+/**
+ * @zh HTTP 请求上下文
+ * @en HTTP request context
+ */
+export interface HttpRequest {
+    /**
+     * @zh 原始请求对象
+     * @en Raw request object
+     */
+    raw: IncomingMessage;
+
+    /**
+     * @zh 请求方法
+     * @en Request method
+     */
+    method: string;
+
+    /**
+     * @zh 请求路径
+     * @en Request path
+     */
+    path: string;
+
+    /**
+     * @zh 路由参数（从 URL 路径提取，如 /users/:id）
+     * @en Route parameters (extracted from URL path, e.g., /users/:id)
+     */
+    params: Record<string, string>;
+
+    /**
+     * @zh 查询参数
+     * @en Query parameters
+     */
+    query: Record<string, string>;
+
+    /**
+     * @zh 请求头
+     * @en Request headers
+     */
+    headers: Record<string, string | string[] | undefined>;
+
+    /**
+     * @zh 解析后的 JSON 请求体
+     * @en Parsed JSON body
+     */
+    body: unknown;
+
+    /**
+     * @zh 客户端 IP
+     * @en Client IP
+     */
+    ip: string;
+}
+
+/**
+ * @zh HTTP 响应工具
+ * @en HTTP response utilities
+ */
+export interface HttpResponse {
+    /**
+     * @zh 原始响应对象
+     * @en Raw response object
+     */
+    raw: ServerResponse;
+
+    /**
+     * @zh 设置状态码
+     * @en Set status code
+     */
+    status(code: number): HttpResponse;
+
+    /**
+     * @zh 设置响应头
+     * @en Set response header
+     */
+    header(name: string, value: string): HttpResponse;
+
+    /**
+     * @zh 发送 JSON 响应
+     * @en Send JSON response
+     */
+    json(data: unknown): void;
+
+    /**
+     * @zh 发送文本响应
+     * @en Send text response
+     */
+    text(data: string): void;
+
+    /**
+     * @zh 发送错误响应
+     * @en Send error response
+     */
+    error(code: number, message: string): void;
+}
+
+/**
+ * @zh HTTP 路由处理器
+ * @en HTTP route handler
+ */
+export type HttpHandler = (req: HttpRequest, res: HttpResponse) => void | Promise<void>;
+
+/**
+ * @zh HTTP 中间件函数
+ * @en HTTP middleware function
+ *
+ * @example
+ * ```typescript
+ * const authMiddleware: HttpMiddleware = async (req, res, next) => {
+ *     if (!req.headers.authorization) {
+ *         res.error(401, 'Unauthorized');
+ *         return;
+ *     }
+ *     await next();
+ * };
+ * ```
+ */
+export type HttpMiddleware = (
+    req: HttpRequest,
+    res: HttpResponse,
+    next: () => Promise<void>
+) => void | Promise<void>;
+
+/**
+ * @zh 带中间件和超时的路由处理器定义
+ * @en Route handler definition with middleware and timeout support
+ */
+export interface HttpHandlerDefinition {
+    /**
+     * @zh 处理函数
+     * @en Handler function
+     */
+    handler: HttpHandler;
+
+    /**
+     * @zh 路由级中间件
+     * @en Route-level middlewares
+     */
+    middlewares?: HttpMiddleware[];
+
+    /**
+     * @zh 路由级超时时间（毫秒），覆盖全局设置
+     * @en Route-level timeout in milliseconds, overrides global setting
+     */
+    timeout?: number;
+}
+
+/**
+ * @zh HTTP 路由方法配置（支持简单处理器或完整定义）
+ * @en HTTP route method configuration (supports simple handler or full definition)
+ */
+export type HttpMethodHandler = HttpHandler | HttpHandlerDefinition;
+
+/**
+ * @zh HTTP 路由方法映射
+ * @en HTTP route methods mapping
+ */
+export interface HttpRouteMethods {
+    GET?: HttpMethodHandler;
+    POST?: HttpMethodHandler;
+    PUT?: HttpMethodHandler;
+    DELETE?: HttpMethodHandler;
+    PATCH?: HttpMethodHandler;
+    OPTIONS?: HttpMethodHandler;
+}
+
+/**
+ * @zh HTTP 路由配置
+ * @en HTTP routes configuration
+ *
+ * @example
+ * ```typescript
+ * const routes: HttpRoutes = {
+ *     // 简单处理器
+ *     '/health': (req, res) => res.json({ ok: true }),
+ *
+ *     // 按方法分开
+ *     '/users': {
+ *         GET: (req, res) => res.json([]),
+ *         POST: (req, res) => res.json({ created: true })
+ *     },
+ *
+ *     // 路由参数
+ *     '/users/:id': {
+ *         GET: (req, res) => res.json({ id: req.params.id }),
+ *         DELETE: {
+ *             handler: (req, res) => res.json({ deleted: true }),
+ *             middlewares: [authMiddleware],
+ *             timeout: 5000
+ *         }
+ *     }
+ * };
+ * ```
+ */
+export type HttpRoutes = Record<string, HttpMethodHandler | HttpRouteMethods>;
+
+/**
+ * @zh HTTP 路由定义（内部使用）
+ * @en HTTP route definition (internal use)
+ */
+export interface HttpRoute {
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS' | '*';
+    path: string;
+    handler: HttpHandler;
+}
+
+/**
+ * @zh CORS 配置
+ * @en CORS configuration
+ */
+export interface CorsOptions {
+    /**
+     * @zh 允许的来源
+     * @en Allowed origins
+     */
+    origin?: string | string[] | boolean;
+
+    /**
+     * @zh 允许的方法
+     * @en Allowed methods
+     */
+    methods?: string[];
+
+    /**
+     * @zh 允许的请求头
+     * @en Allowed headers
+     */
+    allowedHeaders?: string[];
+
+    /**
+     * @zh 是否允许携带凭证
+     * @en Allow credentials
+     */
+    credentials?: boolean;
+
+    /**
+     * @zh 预检请求缓存时间（秒）
+     * @en Preflight cache max age
+     */
+    maxAge?: number;
+}
+
+/**
+ * @zh HTTP 路由器选项
+ * @en HTTP router options
+ */
+export interface HttpRouterOptions {
+    /**
+     * @zh CORS 配置
+     * @en CORS configuration
+     */
+    cors?: CorsOptions | boolean;
+
+    /**
+     * @zh 全局请求超时时间（毫秒）
+     * @en Global request timeout in milliseconds
+     */
+    timeout?: number;
+
+    /**
+     * @zh 全局中间件
+     * @en Global middlewares
+     */
+    middlewares?: HttpMiddleware[];
+}

packages/framework/server/src/index.ts

@@ -27,15 +27,15 @@
  */
 
 // Core
-export { createServer } from './core/server.js'
+export { createServer } from './core/server.js';
 
 // Helpers
-export { defineApi, defineMsg } from './helpers/define.js'
+export { defineApi, defineMsg, defineHttp } from './helpers/define.js';
 
 // Room System
-export { Room, type RoomOptions } from './room/Room.js'
-export { Player, type IPlayer } from './room/Player.js'
-export { onMessage } from './room/decorators.js'
+export { Room, type RoomOptions } from './room/Room.js';
+export { Player, type IPlayer } from './room/Player.js';
+export { onMessage } from './room/decorators.js';
 
 // Types
 export type {
@@ -46,7 +46,19 @@ export type {
     MsgContext,
     ApiDefinition,
     MsgDefinition,
-} from './types/index.js'
+    HttpDefinition,
+    HttpMethod
+} from './types/index.js';
+
+// HTTP
+export { createHttpRouter } from './http/router.js';
+export type {
+    HttpRequest,
+    HttpResponse,
+    HttpHandler,
+    HttpRoutes,
+    CorsOptions
+} from './http/types.js';
 
 // Re-export useful types from @esengine/rpc
-export { RpcError, ErrorCode } from '@esengine/rpc'
+export { RpcError, ErrorCode } from '@esengine/rpc';

packages/framework/server/src/logger.ts

@@ -0,0 +1,34 @@
+/**
+ * @zh 日志模块 - 直接使用 @esengine/ecs-framework 的 Logger
+ * @en Logger module - Uses @esengine/ecs-framework Logger directly
+ */
+
+import { createLogger as ecsCreateLogger, type ILogger } from '@esengine/ecs-framework';
+
+export type { ILogger };
+
+/**
+ * @zh 创建命名日志器
+ * @en Create a named logger
+ *
+ * @param name - @zh 日志器名称 @en Logger name
+ * @returns @zh 日志器实例 @en Logger instance
+ *
+ * @example
+ * ```typescript
+ * import { createLogger } from './logger.js'
+ *
+ * const logger = createLogger('Server')
+ * logger.info('Started on port 3000')
+ * logger.error('Connection failed:', error)
+ * ```
+ */
+export function createLogger(name: string): ILogger {
+    return ecsCreateLogger(name);
+}
+
+/**
+ * @zh 默认服务器日志器
+ * @en Default server logger
+ */
+export const serverLogger = createLogger('Server');

packages/framework/server/src/ratelimit/__tests__/strategies.test.ts

@@ -42,7 +42,7 @@ describe('TokenBucketStrategy', () => {
                 strategy.consume('user-1');
             }
 
-            await new Promise(resolve => setTimeout(resolve, 150));
+            await new Promise((resolve) => setTimeout(resolve, 150));
 
             const result = strategy.consume('user-1');
             expect(result.allowed).toBe(true);
@@ -92,7 +92,7 @@ describe('TokenBucketStrategy', () => {
         it('should clean up full buckets', async () => {
             strategy.consume('user-1');
 
-            await new Promise(resolve => setTimeout(resolve, 100));
+            await new Promise((resolve) => setTimeout(resolve, 100));
 
             strategy.cleanup();
         });
@@ -131,7 +131,7 @@ describe('SlidingWindowStrategy', () => {
                 strategy.consume('user-1');
             }
 
-            await new Promise(resolve => setTimeout(resolve, 1100));
+            await new Promise((resolve) => setTimeout(resolve, 1100));
 
             const result = strategy.consume('user-1');
             expect(result.allowed).toBe(true);
@@ -192,7 +192,7 @@ describe('FixedWindowStrategy', () => {
                 strategy.consume('user-1');
             }
 
-            await new Promise(resolve => setTimeout(resolve, 1100));
+            await new Promise((resolve) => setTimeout(resolve, 1100));
 
             const result = strategy.consume('user-1');
             expect(result.allowed).toBe(true);
@@ -224,7 +224,7 @@ describe('FixedWindowStrategy', () => {
         it('should clean up old windows', async () => {
             strategy.consume('user-1');
 
-            await new Promise(resolve => setTimeout(resolve, 2100));
+            await new Promise((resolve) => setTimeout(resolve, 2100));
 
             strategy.cleanup();
         });

packages/framework/server/src/ratelimit/decorators/rateLimit.ts

@@ -100,7 +100,7 @@ function getMessageTypeFromMethod(target: any, methodName: string): string | und
  */
 export function rateLimit(config?: MessageRateLimitConfig): MethodDecorator {
     return function (
-        target: Object,
+        target: object,
         propertyKey: string | symbol,
         descriptor: PropertyDescriptor
     ): PropertyDescriptor {
@@ -159,7 +159,7 @@ export function rateLimit(config?: MessageRateLimitConfig): MethodDecorator {
  */
 export function noRateLimit(): MethodDecorator {
     return function (
-        target: Object,
+        target: object,
         propertyKey: string | symbol,
         descriptor: PropertyDescriptor
     ): PropertyDescriptor {
@@ -202,7 +202,7 @@ export function rateLimitMessage(
     config?: MessageRateLimitConfig
 ): MethodDecorator {
     return function (
-        target: Object,
+        target: object,
         propertyKey: string | symbol,
         descriptor: PropertyDescriptor
     ): PropertyDescriptor {
@@ -232,7 +232,7 @@ export function rateLimitMessage(
  */
 export function noRateLimitMessage(messageType: string): MethodDecorator {
     return function (
-        target: Object,
+        target: object,
         propertyKey: string | symbol,
         descriptor: PropertyDescriptor
     ): PropertyDescriptor {

packages/framework/server/src/ratelimit/mixin/withRateLimit.ts

@@ -108,6 +108,50 @@ function setPlayerRateLimitContext(player: Player, context: IRateLimitContext):
     });
 }
 
+/**
+ * @zh 抽象构造器类型
+ * @en Abstract constructor type
+ */
+type AbstractConstructor<T = object> = abstract new (...args: any[]) => T;
+
+/**
+ * @zh 可混入的 Room 构造器类型（支持抽象和具体类）
+ * @en Mixable Room constructor type (supports both abstract and concrete classes)
+ */
+type RoomConstructor = AbstractConstructor<Room>;
+
+// ============================================================================
+// Mixin 类型辅助函数 | Mixin Type Helpers
+// ============================================================================
+// TypeScript 的 mixin 模式存在类型系统限制：
+// 1. ES6 class 语法不支持 `extends` 抽象类型参数
+// 2. 泛型类型参数无法直接用于 class extends 子句
+// 以下辅助函数封装了必要的类型转换，使 mixin 实现更清晰
+//
+// TypeScript mixin pattern has type system limitations:
+// 1. ES6 class syntax doesn't support `extends` with abstract type parameters
+// 2. Generic type parameters cannot be used directly in class extends clause
+// The following helpers encapsulate necessary type casts for cleaner mixin implementation
+// ============================================================================
+
+/**
+ * @zh 将抽象 Room 构造器转换为可继承的具体构造器
+ * @en Convert abstract Room constructor to extendable concrete constructor
+ */
+function toExtendable<T extends RoomConstructor>(Base: T): new (...args: any[]) => Room {
+    return Base as unknown as new (...args: any[]) => Room;
+}
+
+/**
+ * @zh 将 mixin 类转换为正确的返回类型
+ * @en Cast mixin class to correct return type
+ */
+function toMixinResult<TBase extends RoomConstructor, TInterface>(
+    MixinClass: AbstractConstructor<any>
+): TBase & AbstractConstructor<TInterface> {
+    return MixinClass as unknown as TBase & AbstractConstructor<TInterface>;
+}
+
 /**
  * @zh 包装房间类添加速率限制功能
  * @en Wrap room class with rate limit functionality
@@ -148,10 +192,10 @@ function setPlayerRateLimitContext(player: Player, context: IRateLimitContext):
  * }
  * ```
  */
-export function withRateLimit<TBase extends new (...args: any[]) => Room = new (...args: any[]) => Room>(
+export function withRateLimit<TBase extends RoomConstructor>(
     Base: TBase,
     config: RateLimitConfig = {}
-): TBase & (new (...args: any[]) => IRateLimitRoom) {
+): TBase & AbstractConstructor<IRateLimitRoom> {
     const {
         messagesPerSecond = 10,
         burstSize = 20,
@@ -163,7 +207,9 @@ export function withRateLimit<TBase extends new (...args: any[]) => Room = new (
         cleanupInterval = 60000
     } = config;
 
-    abstract class RateLimitRoom extends (Base as new (...args: any[]) => Room) implements IRateLimitRoom {
+    const BaseRoom = toExtendable(Base);
+
+    abstract class RateLimitRoom extends BaseRoom implements IRateLimitRoom {
         private _rateLimitStrategy: IRateLimitStrategy;
         private _playerContexts: WeakMap<Player, RateLimitContext> = new WeakMap();
         private _cleanupTimer: ReturnType<typeof setInterval> | null = null;
@@ -381,5 +427,5 @@ export function withRateLimit<TBase extends new (...args: any[]) => Room = new (
         }
     }
 
-    return RateLimitRoom as unknown as TBase & (new (...args: any[]) => IRateLimitRoom);
+    return toMixinResult<TBase, IRateLimitRoom>(RateLimitRoom);
 }

packages/framework/server/src/ratelimit/strategies/SlidingWindow.ts

@@ -168,7 +168,7 @@ export class SlidingWindowStrategy implements IRateLimitStrategy {
      */
     private _cleanExpiredTimestamps(window: WindowState, now: number): void {
         const cutoff = now - this._windowMs;
-        window.timestamps = window.timestamps.filter(ts => ts > cutoff);
+        window.timestamps = window.timestamps.filter((ts) => ts > cutoff);
     }
 
     /**

packages/framework/server/src/room/Player.ts

@@ -3,7 +3,7 @@
  * @en Player class
  */
 
-import type { Connection } from '@esengine/rpc'
+import type { Connection } from '@esengine/rpc';
 
 /**
  * @zh 玩家接口
@@ -22,13 +22,13 @@ export interface IPlayer<TData = Record<string, unknown>> {
  * @en Player implementation
  */
 export class Player<TData = Record<string, unknown>> implements IPlayer<TData> {
-    readonly id: string
-    readonly roomId: string
-    data: TData
+    readonly id: string;
+    readonly roomId: string;
+    data: TData;
 
-    private _conn: Connection<any>
-    private _sendFn: (conn: Connection<any>, type: string, data: unknown) => void
-    private _leaveFn: (player: Player<TData>, reason?: string) => void
+    private _conn: Connection<any>;
+    private _sendFn: (conn: Connection<any>, type: string, data: unknown) => void;
+    private _leaveFn: (player: Player<TData>, reason?: string) => void;
 
     constructor(options: {
         id: string
@@ -38,12 +38,12 @@ export class Player<TData = Record<string, unknown>> implements IPlayer<TData> {
         leaveFn: (player: Player<TData>, reason?: string) => void
         initialData?: TData
     }) {
-        this.id = options.id
-        this.roomId = options.roomId
-        this._conn = options.conn
-        this._sendFn = options.sendFn
-        this._leaveFn = options.leaveFn
-        this.data = options.initialData ?? ({} as TData)
+        this.id = options.id;
+        this.roomId = options.roomId;
+        this._conn = options.conn;
+        this._sendFn = options.sendFn;
+        this._leaveFn = options.leaveFn;
+        this.data = options.initialData ?? ({} as TData);
     }
 
     /**
@@ -51,7 +51,7 @@ export class Player<TData = Record<string, unknown>> implements IPlayer<TData> {
      * @en Get underlying connection
      */
     get connection(): Connection<any> {
-        return this._conn
+        return this._conn;
     }
 
     /**
@@ -59,7 +59,7 @@ export class Player<TData = Record<string, unknown>> implements IPlayer<TData> {
      * @en Send message to player
      */
     send<T>(type: string, data: T): void {
-        this._sendFn(this._conn, type, data)
+        this._sendFn(this._conn, type, data);
     }
 
     /**
@@ -67,6 +67,6 @@ export class Player<TData = Record<string, unknown>> implements IPlayer<TData> {
      * @en Make player leave the room
      */
     leave(reason?: string): void {
-        this._leaveFn(this, reason)
+        this._leaveFn(this, reason);
     }
 }

packages/framework/server/src/room/Room.ts

@@ -3,7 +3,7 @@
  * @en Room base class
  */
 
-import { Player } from './Player.js'
+import { Player } from './Player.js';
 
 /**
  * @zh 房间配置
@@ -26,7 +26,7 @@ interface MessageHandlerMeta {
  * @zh 消息处理器存储 key
  * @en Message handler storage key
  */
-const MESSAGE_HANDLERS = Symbol('messageHandlers')
+const MESSAGE_HANDLERS = Symbol('messageHandlers');
 
 /**
  * @zh 房间基类
@@ -58,19 +58,19 @@ export abstract class Room<TState = any, TPlayerData = Record<string, unknown>>
      * @zh 最大玩家数
      * @en Maximum players
      */
-    maxPlayers = 16
+    maxPlayers = 16;
 
     /**
      * @zh Tick 速率（每秒），0 = 不自动 tick
      * @en Tick rate (per second), 0 = no auto tick
      */
-    tickRate = 0
+    tickRate = 0;
 
     /**
      * @zh 空房间自动销毁
      * @en Auto dispose when empty
      */
-    autoDispose = true
+    autoDispose = true;
 
     // ========================================================================
     // 状态 | State
@@ -80,21 +80,21 @@ export abstract class Room<TState = any, TPlayerData = Record<string, unknown>>
      * @zh 房间状态
      * @en Room state
      */
-    state: TState = {} as TState
+    state: TState = {} as TState;
 
     // ========================================================================
     // 内部属性 | Internal properties
     // ========================================================================
 
-    private _id: string = ''
-    private _players: Map<string, Player<TPlayerData>> = new Map()
-    private _locked = false
-    private _disposed = false
-    private _tickInterval: ReturnType<typeof setInterval> | null = null
-    private _lastTickTime = 0
-    private _broadcastFn: ((type: string, data: unknown) => void) | null = null
-    private _sendFn: ((conn: any, type: string, data: unknown) => void) | null = null
-    private _disposeFn: (() => void) | null = null
+    private _id: string = '';
+    private _players: Map<string, Player<TPlayerData>> = new Map();
+    private _locked = false;
+    private _disposed = false;
+    private _tickInterval: ReturnType<typeof setInterval> | null = null;
+    private _lastTickTime = 0;
+    private _broadcastFn: ((type: string, data: unknown) => void) | null = null;
+    private _sendFn: ((conn: any, type: string, data: unknown) => void) | null = null;
+    private _disposeFn: (() => void) | null = null;
 
     // ========================================================================
     // 只读属性 | Readonly properties
@@ -105,7 +105,7 @@ export abstract class Room<TState = any, TPlayerData = Record<string, unknown>>
      * @en Room ID
      */
     get id(): string {
-        return this._id
+        return this._id;
     }
 
     /**
@@ -113,7 +113,7 @@ export abstract class Room<TState = any, TPlayerData = Record<string, unknown>>
      * @en All players
      */
     get players(): ReadonlyArray<Player<TPlayerData>> {
-        return Array.from(this._players.values())
+        return Array.from(this._players.values());
     }
 
     /**
@@ -121,7 +121,7 @@ export abstract class Room<TState = any, TPlayerData = Record<string, unknown>>
      * @en Player count
      */
     get playerCount(): number {
-        return this._players.size
+        return this._players.size;
     }
 
     /**
@@ -129,7 +129,7 @@ export abstract class Room<TState = any, TPlayerData = Record<string, unknown>>
      * @en Is full
      */
     get isFull(): boolean {
-        return this._players.size >= this.maxPlayers
+        return this._players.size >= this.maxPlayers;
     }
 
     /**
@@ -137,7 +137,7 @@ export abstract class Room<TState = any, TPlayerData = Record<string, unknown>>
      * @en Is locked
      */
     get isLocked(): boolean {
-        return this._locked
+        return this._locked;
     }
 
     /**
@@ -145,7 +145,7 @@ export abstract class Room<TState = any, TPlayerData = Record<string, unknown>>
      * @en Is disposed
      */
     get isDisposed(): boolean {
-        return this._disposed
+        return this._disposed;
     }
 
     // ========================================================================
@@ -192,7 +192,7 @@ export abstract class Room<TState = any, TPlayerData = Record<string, unknown>>
      */
     broadcast<T>(type: string, data: T): void {
         for (const player of this._players.values()) {
-            player.send(type, data)
+            player.send(type, data);
         }
     }
 
@@ -203,7 +203,7 @@ export abstract class Room<TState = any, TPlayerData = Record<string, unknown>>
     broadcastExcept<T>(except: Player<TPlayerData>, type: string, data: T): void {
         for (const player of this._players.values()) {
             if (player.id !== except.id) {
-                player.send(type, data)
+                player.send(type, data);
             }
         }
     }
@@ -213,7 +213,7 @@ export abstract class Room<TState = any, TPlayerData = Record<string, unknown>>
      * @en Get player by id
      */
     getPlayer(id: string): Player<TPlayerData> | undefined {
-        return this._players.get(id)
+        return this._players.get(id);
     }
 
     /**
@@ -221,7 +221,7 @@ export abstract class Room<TState = any, TPlayerData = Record<string, unknown>>
      * @en Kick player
      */
     kick(player: Player<TPlayerData>, reason?: string): void {
-        player.leave(reason ?? 'kicked')
+        player.leave(reason ?? 'kicked');
     }
 
     /**
@@ -229,7 +229,7 @@ export abstract class Room<TState = any, TPlayerData = Record<string, unknown>>
      * @en Lock room
      */
     lock(): void {
-        this._locked = true
+        this._locked = true;
     }
 
     /**
@@ -237,7 +237,7 @@ export abstract class Room<TState = any, TPlayerData = Record<string, unknown>>
      * @en Unlock room
      */
     unlock(): void {
-        this._locked = false
+        this._locked = false;
     }
 
     /**
@@ -245,18 +245,18 @@ export abstract class Room<TState = any, TPlayerData = Record<string, unknown>>
      * @en Manually dispose room
      */
     dispose(): void {
-        if (this._disposed) return
-        this._disposed = true
+        if (this._disposed) return;
+        this._disposed = true;
 
-        this._stopTick()
+        this._stopTick();
 
         for (const player of this._players.values()) {
-            player.leave('room_disposed')
+            player.leave('room_disposed');
         }
-        this._players.clear()
+        this._players.clear();
 
-        this.onDispose()
-        this._disposeFn?.()
+        this.onDispose();
+        this._disposeFn?.();
     }
 
     // ========================================================================
@@ -272,18 +272,18 @@ export abstract class Room<TState = any, TPlayerData = Record<string, unknown>>
         broadcastFn: (type: string, data: unknown) => void
         disposeFn: () => void
     }): void {
-        this._id = options.id
-        this._sendFn = options.sendFn
-        this._broadcastFn = options.broadcastFn
-        this._disposeFn = options.disposeFn
+        this._id = options.id;
+        this._sendFn = options.sendFn;
+        this._broadcastFn = options.broadcastFn;
+        this._disposeFn = options.disposeFn;
     }
 
     /**
      * @internal
      */
     async _create(options?: RoomOptions): Promise<void> {
-        await this.onCreate(options)
-        this._startTick()
+        await this.onCreate(options);
+        this._startTick();
     }
 
     /**
@@ -291,7 +291,7 @@ export abstract class Room<TState = any, TPlayerData = Record<string, unknown>>
      */
     async _addPlayer(id: string, conn: any): Promise<Player<TPlayerData> | null> {
         if (this._locked || this.isFull || this._disposed) {
-            return null
+            return null;
         }
 
         const player = new Player<TPlayerData>({
@@ -299,27 +299,27 @@ export abstract class Room<TState = any, TPlayerData = Record<string, unknown>>
             roomId: this._id,
             conn,
             sendFn: this._sendFn!,
-            leaveFn: (p, reason) => this._removePlayer(p.id, reason),
-        })
+            leaveFn: (p, reason) => this._removePlayer(p.id, reason)
+        });
 
-        this._players.set(id, player)
-        await this.onJoin(player)
+        this._players.set(id, player);
+        await this.onJoin(player);
 
-        return player
+        return player;
     }
 
     /**
      * @internal
      */
     async _removePlayer(id: string, reason?: string): Promise<void> {
-        const player = this._players.get(id)
-        if (!player) return
+        const player = this._players.get(id);
+        if (!player) return;
 
-        this._players.delete(id)
-        await this.onLeave(player, reason)
+        this._players.delete(id);
+        await this.onLeave(player, reason);
 
         if (this.autoDispose && this._players.size === 0) {
-            this.dispose()
+            this.dispose();
         }
     }
 
@@ -327,16 +327,16 @@ export abstract class Room<TState = any, TPlayerData = Record<string, unknown>>
      * @internal
      */
     _handleMessage(type: string, data: unknown, playerId: string): void {
-        const player = this._players.get(playerId)
-        if (!player) return
+        const player = this._players.get(playerId);
+        if (!player) return;
 
-        const handlers = (this.constructor as any)[MESSAGE_HANDLERS] as MessageHandlerMeta[] | undefined
+        const handlers = (this.constructor as any)[MESSAGE_HANDLERS] as MessageHandlerMeta[] | undefined;
         if (handlers) {
             for (const handler of handlers) {
                 if (handler.type === type) {
-                    const method = (this as any)[handler.method]
+                    const method = (this as any)[handler.method];
                     if (typeof method === 'function') {
-                        method.call(this, data, player)
+                        method.call(this, data, player);
                     }
                 }
             }
@@ -344,21 +344,21 @@ export abstract class Room<TState = any, TPlayerData = Record<string, unknown>>
     }
 
     private _startTick(): void {
-        if (this.tickRate <= 0) return
+        if (this.tickRate <= 0) return;
 
-        this._lastTickTime = performance.now()
+        this._lastTickTime = performance.now();
         this._tickInterval = setInterval(() => {
-            const now = performance.now()
-            const dt = (now - this._lastTickTime) / 1000
-            this._lastTickTime = now
-            this.onTick(dt)
-        }, 1000 / this.tickRate)
+            const now = performance.now();
+            const dt = (now - this._lastTickTime) / 1000;
+            this._lastTickTime = now;
+            this.onTick(dt);
+        }, 1000 / this.tickRate);
     }
 
     private _stopTick(): void {
         if (this._tickInterval) {
-            clearInterval(this._tickInterval)
-            this._tickInterval = null
+            clearInterval(this._tickInterval);
+            this._tickInterval = null;
         }
     }
 }
@@ -368,7 +368,7 @@ export abstract class Room<TState = any, TPlayerData = Record<string, unknown>>
  * @en Get message handler metadata
  */
 export function getMessageHandlers(target: any): MessageHandlerMeta[] {
-    return target[MESSAGE_HANDLERS] || []
+    return target[MESSAGE_HANDLERS] || [];
 }
 
 /**
@@ -377,7 +377,7 @@ export function getMessageHandlers(target: any): MessageHandlerMeta[] {
  */
 export function registerMessageHandler(target: any, type: string, method: string): void {
     if (!target[MESSAGE_HANDLERS]) {
-        target[MESSAGE_HANDLERS] = []
+        target[MESSAGE_HANDLERS] = [];
     }
-    target[MESSAGE_HANDLERS].push({ type, method })
+    target[MESSAGE_HANDLERS].push({ type, method });
 }

packages/framework/server/src/room/RoomManager.ts

@@ -3,8 +3,11 @@
  * @en Room manager
  */
 
-import { Room, type RoomOptions } from './Room.js'
-import type { Player } from './Player.js'
+import { Room, type RoomOptions } from './Room.js';
+import type { Player } from './Player.js';
+import { createLogger } from '../logger.js';
+
+const logger = createLogger('Room');
 
 /**
  * @zh 房间类型
@@ -25,15 +28,15 @@ interface RoomDefinition {
  * @en Room manager
  */
 export class RoomManager {
-    private _definitions: Map<string, RoomDefinition> = new Map()
-    private _rooms: Map<string, Room> = new Map()
-    private _playerToRoom: Map<string, string> = new Map()
-    private _nextRoomId = 1
+    private _definitions: Map<string, RoomDefinition> = new Map();
+    private _rooms: Map<string, Room> = new Map();
+    private _playerToRoom: Map<string, string> = new Map();
+    private _nextRoomId = 1;
 
-    private _sendFn: (conn: any, type: string, data: unknown) => void
+    private _sendFn: (conn: any, type: string, data: unknown) => void;
 
     constructor(sendFn: (conn: any, type: string, data: unknown) => void) {
-        this._sendFn = sendFn
+        this._sendFn = sendFn;
     }
 
     /**
@@ -41,7 +44,7 @@ export class RoomManager {
      * @en Define room type
      */
     define<T extends Room>(name: string, roomClass: RoomClass<T>): void {
-        this._definitions.set(name, { roomClass })
+        this._definitions.set(name, { roomClass });
     }
 
     /**
@@ -49,33 +52,33 @@ export class RoomManager {
      * @en Create room
      */
     async create(name: string, options?: RoomOptions): Promise<Room | null> {
-        const def = this._definitions.get(name)
+        const def = this._definitions.get(name);
         if (!def) {
-            console.warn(`[RoomManager] Room type not found: ${name}`)
-            return null
+            logger.warn(`Room type not found: ${name}`);
+            return null;
         }
 
-        const roomId = this._generateRoomId()
-        const room = new def.roomClass()
+        const roomId = this._generateRoomId();
+        const room = new def.roomClass();
 
         room._init({
             id: roomId,
             sendFn: this._sendFn,
             broadcastFn: (type, data) => {
                 for (const player of room.players) {
-                    player.send(type, data)
+                    player.send(type, data);
                 }
             },
             disposeFn: () => {
-                this._rooms.delete(roomId)
-            },
-        })
+                this._rooms.delete(roomId);
+            }
+        });
 
-        this._rooms.set(roomId, room)
-        await room._create(options)
+        this._rooms.set(roomId, room);
+        await room._create(options);
 
-        console.log(`[Room] Created: ${name} (${roomId})`)
-        return room
+        logger.info(`Created: ${name} (${roomId})`);
+        return room;
     }
 
     /**
@@ -89,22 +92,22 @@ export class RoomManager {
         options?: RoomOptions
     ): Promise<{ room: Room; player: Player } | null> {
         // 查找可加入的房间
-        let room = this._findAvailableRoom(name)
+        let room = this._findAvailableRoom(name);
 
         // 没有则创建
         if (!room) {
-            room = await this.create(name, options)
-            if (!room) return null
+            room = await this.create(name, options);
+            if (!room) return null;
         }
 
         // 加入房间
-        const player = await room._addPlayer(playerId, conn)
-        if (!player) return null
+        const player = await room._addPlayer(playerId, conn);
+        if (!player) return null;
 
-        this._playerToRoom.set(playerId, room.id)
+        this._playerToRoom.set(playerId, room.id);
 
-        console.log(`[Room] Player ${playerId} joined ${room.id}`)
-        return { room, player }
+        logger.info(`Player ${playerId} joined ${room.id}`);
+        return { room, player };
     }
 
     /**
@@ -116,16 +119,16 @@ export class RoomManager {
         playerId: string,
         conn: any
     ): Promise<{ room: Room; player: Player } | null> {
-        const room = this._rooms.get(roomId)
-        if (!room) return null
+        const room = this._rooms.get(roomId);
+        if (!room) return null;
 
-        const player = await room._addPlayer(playerId, conn)
-        if (!player) return null
+        const player = await room._addPlayer(playerId, conn);
+        if (!player) return null;
 
-        this._playerToRoom.set(playerId, room.id)
+        this._playerToRoom.set(playerId, room.id);
 
-        console.log(`[Room] Player ${playerId} joined ${room.id}`)
-        return { room, player }
+        logger.info(`Player ${playerId} joined ${room.id}`);
+        return { room, player };
     }
 
     /**
@@ -133,16 +136,16 @@ export class RoomManager {
      * @en Player leave
      */
     async leave(playerId: string, reason?: string): Promise<void> {
-        const roomId = this._playerToRoom.get(playerId)
-        if (!roomId) return
+        const roomId = this._playerToRoom.get(playerId);
+        if (!roomId) return;
 
-        const room = this._rooms.get(roomId)
+        const room = this._rooms.get(roomId);
         if (room) {
-            await room._removePlayer(playerId, reason)
+            await room._removePlayer(playerId, reason);
         }
 
-        this._playerToRoom.delete(playerId)
-        console.log(`[Room] Player ${playerId} left ${roomId}`)
+        this._playerToRoom.delete(playerId);
+        logger.info(`Player ${playerId} left ${roomId}`);
     }
 
     /**
@@ -150,12 +153,12 @@ export class RoomManager {
      * @en Handle message
      */
     handleMessage(playerId: string, type: string, data: unknown): void {
-        const roomId = this._playerToRoom.get(playerId)
-        if (!roomId) return
+        const roomId = this._playerToRoom.get(playerId);
+        if (!roomId) return;
 
-        const room = this._rooms.get(roomId)
+        const room = this._rooms.get(roomId);
         if (room) {
-            room._handleMessage(type, data, playerId)
+            room._handleMessage(type, data, playerId);
         }
     }
 
@@ -164,7 +167,7 @@ export class RoomManager {
      * @en Get room
      */
     getRoom(roomId: string): Room | undefined {
-        return this._rooms.get(roomId)
+        return this._rooms.get(roomId);
     }
 
     /**
@@ -172,8 +175,8 @@ export class RoomManager {
      * @en Get player's room
      */
     getPlayerRoom(playerId: string): Room | undefined {
-        const roomId = this._playerToRoom.get(playerId)
-        return roomId ? this._rooms.get(roomId) : undefined
+        const roomId = this._playerToRoom.get(playerId);
+        return roomId ? this._rooms.get(roomId) : undefined;
     }
 
     /**
@@ -181,7 +184,7 @@ export class RoomManager {
      * @en Get all rooms
      */
     getRooms(): ReadonlyArray<Room> {
-        return Array.from(this._rooms.values())
+        return Array.from(this._rooms.values());
     }
 
     /**
@@ -189,17 +192,17 @@ export class RoomManager {
      * @en Get all rooms of a type
      */
     getRoomsByType(name: string): Room[] {
-        const def = this._definitions.get(name)
-        if (!def) return []
+        const def = this._definitions.get(name);
+        if (!def) return [];
 
         return Array.from(this._rooms.values()).filter(
-            room => room instanceof def.roomClass
-        )
+            (room) => room instanceof def.roomClass
+        );
     }
 
     private _findAvailableRoom(name: string): Room | null {
-        const def = this._definitions.get(name)
-        if (!def) return null
+        const def = this._definitions.get(name);
+        if (!def) return null;
 
         for (const room of this._rooms.values()) {
             if (
@@ -208,14 +211,14 @@ export class RoomManager {
                 !room.isLocked &&
                 !room.isDisposed
             ) {
-                return room
+                return room;
             }
         }
 
-        return null
+        return null;
     }
 
     private _generateRoomId(): string {
-        return `room_${this._nextRoomId++}`
+        return `room_${this._nextRoomId++}`;
     }
 }

packages/framework/server/src/room/decorators.ts

@@ -3,7 +3,7 @@
  * @en Room decorators
  */
 
-import { registerMessageHandler } from './Room.js'
+import { registerMessageHandler } from './Room.js';
 
 /**
  * @zh 消息处理器装饰器
@@ -30,6 +30,6 @@ export function onMessage(type: string): MethodDecorator {
         propertyKey: string | symbol,
         _descriptor: PropertyDescriptor
     ) {
-        registerMessageHandler(target.constructor, type, propertyKey as string)
-    }
+        registerMessageHandler(target.constructor, type, propertyKey as string);
+    };
 }

packages/framework/server/src/room/index.ts

@@ -3,7 +3,7 @@
  * @en Room system
  */
 
-export { Room, type RoomOptions } from './Room.js'
-export { Player, type IPlayer } from './Player.js'
-export { RoomManager, type RoomClass } from './RoomManager.js'
-export { onMessage } from './decorators.js'
+export { Room, type RoomOptions } from './Room.js';
+export { Player, type IPlayer } from './Player.js';
+export { RoomManager, type RoomClass } from './RoomManager.js';
+export { onMessage } from './decorators.js';

packages/framework/server/src/router/loader.ts

@@ -3,10 +3,21 @@
  * @en File-based router loader
  */
 
-import * as fs from 'node:fs'
-import * as path from 'node:path'
-import { pathToFileURL } from 'node:url'
-import type { ApiDefinition, MsgDefinition, LoadedApiHandler, LoadedMsgHandler } from '../types/index.js'
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createLogger } from '../logger.js';
+import type {
+    ApiDefinition,
+    MsgDefinition,
+    HttpDefinition,
+    LoadedApiHandler,
+    LoadedMsgHandler,
+    LoadedHttpHandler,
+    HttpMethod
+} from '../types/index.js';
+
+const logger = createLogger('Server');
 
 /**
  * @zh 将文件名转换为 API/消息名称
@@ -18,12 +29,12 @@ import type { ApiDefinition, MsgDefinition, LoadedApiHandler, LoadedMsgHandler }
  * 'save_blueprint.ts' -> 'SaveBlueprint'
  */
 function fileNameToHandlerName(fileName: string): string {
-    const baseName = fileName.replace(/\.(ts|js|mts|mjs)$/, '')
+    const baseName = fileName.replace(/\.(ts|js|mts|mjs)$/, '');
 
     return baseName
         .split(/[-_]/)
-        .map(part => part.charAt(0).toUpperCase() + part.slice(1))
-        .join('')
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join('');
 }
 
 /**
@@ -32,23 +43,23 @@ function fileNameToHandlerName(fileName: string): string {
  */
 function scanDirectory(dir: string): string[] {
     if (!fs.existsSync(dir)) {
-        return []
+        return [];
     }
 
-    const files: string[] = []
-    const entries = fs.readdirSync(dir, { withFileTypes: true })
+    const files: string[] = [];
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
 
     for (const entry of entries) {
         if (entry.isFile() && /\.(ts|js|mts|mjs)$/.test(entry.name)) {
             // 跳过 index 和下划线开头的文件
             if (entry.name.startsWith('_') || entry.name.startsWith('index.')) {
-                continue
+                continue;
             }
-            files.push(path.join(dir, entry.name))
+            files.push(path.join(dir, entry.name));
         }
     }
 
-    return files
+    return files;
 }
 
 /**
@@ -56,29 +67,29 @@ function scanDirectory(dir: string): string[] {
  * @en Load API handlers
  */
 export async function loadApiHandlers(apiDir: string): Promise<LoadedApiHandler[]> {
-    const files = scanDirectory(apiDir)
-    const handlers: LoadedApiHandler[] = []
+    const files = scanDirectory(apiDir);
+    const handlers: LoadedApiHandler[] = [];
 
     for (const filePath of files) {
         try {
-            const fileUrl = pathToFileURL(filePath).href
-            const module = await import(fileUrl)
-            const definition = module.default as ApiDefinition<unknown, unknown, unknown>
+            const fileUrl = pathToFileURL(filePath).href;
+            const module = await import(fileUrl);
+            const definition = module.default as ApiDefinition<unknown, unknown, unknown>;
 
             if (definition && typeof definition.handler === 'function') {
-                const name = fileNameToHandlerName(path.basename(filePath))
+                const name = fileNameToHandlerName(path.basename(filePath));
                 handlers.push({
                     name,
                     path: filePath,
-                    definition,
-                })
+                    definition
+                });
             }
         } catch (err) {
-            console.warn(`[Server] Failed to load API handler: ${filePath}`, err)
+            logger.warn(`Failed to load API handler: ${filePath}`, err);
         }
     }
 
-    return handlers
+    return handlers;
 }
 
 /**
@@ -86,27 +97,130 @@ export async function loadApiHandlers(apiDir: string): Promise<LoadedApiHandler[
  * @en Load message handlers
  */
 export async function loadMsgHandlers(msgDir: string): Promise<LoadedMsgHandler[]> {
-    const files = scanDirectory(msgDir)
-    const handlers: LoadedMsgHandler[] = []
+    const files = scanDirectory(msgDir);
+    const handlers: LoadedMsgHandler[] = [];
 
     for (const filePath of files) {
         try {
-            const fileUrl = pathToFileURL(filePath).href
-            const module = await import(fileUrl)
-            const definition = module.default as MsgDefinition<unknown, unknown>
+            const fileUrl = pathToFileURL(filePath).href;
+            const module = await import(fileUrl);
+            const definition = module.default as MsgDefinition<unknown, unknown>;
 
             if (definition && typeof definition.handler === 'function') {
-                const name = fileNameToHandlerName(path.basename(filePath))
+                const name = fileNameToHandlerName(path.basename(filePath));
                 handlers.push({
                     name,
                     path: filePath,
-                    definition,
-                })
+                    definition
+                });
             }
         } catch (err) {
-            console.warn(`[Server] Failed to load msg handler: ${filePath}`, err)
+            logger.warn(`Failed to load msg handler: ${filePath}`, err);
         }
     }
 
-    return handlers
+    return handlers;
+}
+
+/**
+ * @zh 递归扫描目录获取所有处理器文件
+ * @en Recursively scan directory for all handler files
+ */
+function scanDirectoryRecursive(dir: string, baseDir: string = dir): Array<{ filePath: string; relativePath: string }> {
+    if (!fs.existsSync(dir)) {
+        return [];
+    }
+
+    const files: Array<{ filePath: string; relativePath: string }> = [];
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+
+        if (entry.isDirectory()) {
+            files.push(...scanDirectoryRecursive(fullPath, baseDir));
+        } else if (entry.isFile() && /\.(ts|js|mts|mjs)$/.test(entry.name)) {
+            if (entry.name.startsWith('_') || entry.name.startsWith('index.')) {
+                continue;
+            }
+            const relativePath = path.relative(baseDir, fullPath);
+            files.push({ filePath: fullPath, relativePath });
+        }
+    }
+
+    return files;
+}
+
+/**
+ * @zh 将文件路径转换为路由路径
+ * @en Convert file path to route path
+ *
+ * @example
+ * 'login.ts' -> '/login'
+ * 'users/profile.ts' -> '/users/profile'
+ * 'users/[id].ts' -> '/users/:id'
+ */
+function filePathToRoute(relativePath: string, prefix: string): string {
+    let route = relativePath
+        .replace(/\.(ts|js|mts|mjs)$/, '')
+        .replace(/\\/g, '/')
+        .replace(/\[(\w+)\]/g, ':$1');
+
+    if (!route.startsWith('/')) {
+        route = '/' + route;
+    }
+
+    const fullRoute = prefix.endsWith('/')
+        ? prefix.slice(0, -1) + route
+        : prefix + route;
+
+    return fullRoute;
+}
+
+/**
+ * @zh 加载 HTTP 路由处理器
+ * @en Load HTTP route handlers
+ *
+ * @example
+ * ```typescript
+ * // Directory structure:
+ * // src/http/
+ * //   login.ts      -> POST /api/login
+ * //   register.ts   -> POST /api/register
+ * //   users/
+ * //     [id].ts     -> GET /api/users/:id
+ *
+ * const handlers = await loadHttpHandlers('src/http', '/api')
+ * ```
+ */
+export async function loadHttpHandlers(
+    httpDir: string,
+    prefix: string = '/api'
+): Promise<LoadedHttpHandler[]> {
+    const files = scanDirectoryRecursive(httpDir);
+    const handlers: LoadedHttpHandler[] = [];
+
+    for (const { filePath, relativePath } of files) {
+        try {
+            const fileUrl = pathToFileURL(filePath).href;
+            const module = await import(fileUrl);
+            const definition = module.default as HttpDefinition<unknown>;
+
+            if (definition && typeof definition.handler === 'function') {
+                const route = filePathToRoute(relativePath, prefix);
+                const method: HttpMethod = definition.method ?? 'POST';
+
+                handlers.push({
+                    route,
+                    method,
+                    path: filePath,
+                    definition
+                });
+            }
+        } catch (err) {
+            logger.warn(`Failed to load HTTP handler: ${filePath}`, err);
+        }
+    }
+
+    return handlers;
 }

packages/framework/server/src/testing/MockRoom.ts

@@ -3,7 +3,7 @@
  * @en Mock room for testing
  */
 
-import { Room, onMessage, type Player } from '../room/index.js'
+import { Room, onMessage, type Player } from '../room/index.js';
 
 /**
  * @zh 模拟房间状态
@@ -41,27 +41,27 @@ export class MockRoom extends Room<MockRoomState> {
     state: MockRoomState = {
         messages: [],
         joinCount: 0,
-        leaveCount: 0,
-    }
+        leaveCount: 0
+    };
 
     onCreate(): void {
         // 房间创建
     }
 
     onJoin(player: Player): void {
-        this.state.joinCount++
+        this.state.joinCount++;
         this.broadcast('PlayerJoined', {
             playerId: player.id,
-            joinCount: this.state.joinCount,
-        })
+            joinCount: this.state.joinCount
+        });
     }
 
     onLeave(player: Player): void {
-        this.state.leaveCount++
+        this.state.leaveCount++;
         this.broadcast('PlayerLeft', {
             playerId: player.id,
-            leaveCount: this.state.leaveCount,
-        })
+            leaveCount: this.state.leaveCount
+        });
     }
 
     @onMessage('*')
@@ -69,31 +69,31 @@ export class MockRoom extends Room<MockRoomState> {
         this.state.messages.push({
             type,
             data,
-            playerId: player.id,
-        })
+            playerId: player.id
+        });
 
         // 回显消息给所有玩家
         this.broadcast('MessageReceived', {
             type,
             data,
-            from: player.id,
-        })
+            from: player.id
+        });
     }
 
     @onMessage('Echo')
     handleEcho(data: unknown, player: Player): void {
         // 只回复给发送者
-        player.send('EchoReply', data)
+        player.send('EchoReply', data);
     }
 
     @onMessage('Broadcast')
     handleBroadcast(data: unknown, _player: Player): void {
-        this.broadcast('BroadcastMessage', data)
+        this.broadcast('BroadcastMessage', data);
     }
 
     @onMessage('Ping')
     handlePing(_data: unknown, player: Player): void {
-        player.send('Pong', { timestamp: Date.now() })
+        player.send('Pong', { timestamp: Date.now() });
     }
 }
 
@@ -107,7 +107,7 @@ export class MockRoom extends Room<MockRoomState> {
 export class EchoRoom extends Room {
     @onMessage('*')
     handleAnyMessage(data: unknown, player: Player, type: string): void {
-        player.send(type, data)
+        player.send(type, data);
     }
 }
 
@@ -120,15 +120,15 @@ export class EchoRoom extends Room {
  */
 export class BroadcastRoom extends Room {
     onJoin(player: Player): void {
-        this.broadcast('PlayerJoined', { id: player.id })
+        this.broadcast('PlayerJoined', { id: player.id });
     }
 
     onLeave(player: Player): void {
-        this.broadcast('PlayerLeft', { id: player.id })
+        this.broadcast('PlayerLeft', { id: player.id });
     }
 
     @onMessage('*')
     handleAnyMessage(data: unknown, player: Player, type: string): void {
-        this.broadcast(type, { from: player.id, data })
+        this.broadcast(type, { from: player.id, data });
     }
 }

packages/framework/server/src/testing/Room.test.ts

@@ -6,10 +6,10 @@
  * @en This file demonstrates how to use testing utilities for server testing
  */
 
-import { describe, it, expect, beforeEach, afterEach } from 'vitest'
-import { createTestEnv, type TestEnvironment, wait } from './TestServer.js'
-import { MockRoom, BroadcastRoom } from './MockRoom.js'
-import { Room, onMessage, type Player } from '../room/index.js'
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { createTestEnv, type TestEnvironment, wait } from './TestServer.js';
+import { MockRoom, BroadcastRoom } from './MockRoom.js';
+import { Room, onMessage, type Player } from '../room/index.js';
 
 // ============================================================================
 // Custom Room for Testing | 自定义测试房间
@@ -21,52 +21,52 @@ interface GameState {
 }
 
 class GameRoom extends Room<GameState> {
-    maxPlayers = 4
+    maxPlayers = 4;
 
     state: GameState = {
         players: new Map(),
-        scores: new Map(),
-    }
+        scores: new Map()
+    };
 
     onJoin(player: Player): void {
-        this.state.players.set(player.id, { x: 0, y: 0 })
-        this.state.scores.set(player.id, 0)
+        this.state.players.set(player.id, { x: 0, y: 0 });
+        this.state.scores.set(player.id, 0);
         this.broadcast('PlayerJoined', {
             playerId: player.id,
-            playerCount: this.state.players.size,
-        })
+            playerCount: this.state.players.size
+        });
     }
 
     onLeave(player: Player): void {
-        this.state.players.delete(player.id)
-        this.state.scores.delete(player.id)
+        this.state.players.delete(player.id);
+        this.state.scores.delete(player.id);
         this.broadcast('PlayerLeft', {
             playerId: player.id,
-            playerCount: this.state.players.size,
-        })
+            playerCount: this.state.players.size
+        });
     }
 
     @onMessage('Move')
     handleMove(data: { x: number; y: number }, player: Player): void {
-        const pos = this.state.players.get(player.id)
+        const pos = this.state.players.get(player.id);
         if (pos) {
-            pos.x = data.x
-            pos.y = data.y
+            pos.x = data.x;
+            pos.y = data.y;
             this.broadcast('PlayerMoved', {
                 playerId: player.id,
                 x: data.x,
-                y: data.y,
-            })
+                y: data.y
+            });
         }
     }
 
     @onMessage('Score')
     handleScore(data: { points: number }, player: Player): void {
-        const current = this.state.scores.get(player.id) ?? 0
-        this.state.scores.set(player.id, current + data.points)
+        const current = this.state.scores.get(player.id) ?? 0;
+        this.state.scores.set(player.id, current + data.points);
         player.send('ScoreUpdated', {
-            score: this.state.scores.get(player.id),
-        })
+            score: this.state.scores.get(player.id)
+        });
     }
 }
 
@@ -75,15 +75,15 @@ class GameRoom extends Room<GameState> {
 // ============================================================================
 
 describe('Room Integration Tests', () => {
-    let env: TestEnvironment
+    let env: TestEnvironment;
 
     beforeEach(async () => {
-        env = await createTestEnv()
-    })
+        env = await createTestEnv();
+    });
 
     afterEach(async () => {
-        await env.cleanup()
-    })
+        await env.cleanup();
+    });
 
     // ========================================================================
     // Basic Tests | 基础测试
@@ -91,39 +91,39 @@ describe('Room Integration Tests', () => {
 
     describe('Basic Room Operations', () => {
         it('should create and join room', async () => {
-            env.server.define('game', GameRoom)
+            env.server.define('game', GameRoom);
 
-            const client = await env.createClient()
-            const result = await client.joinRoom('game')
+            const client = await env.createClient();
+            const result = await client.joinRoom('game');
 
-            expect(result.roomId).toBeDefined()
-            expect(result.playerId).toBeDefined()
-            expect(client.roomId).toBe(result.roomId)
-        })
+            expect(result.roomId).toBeDefined();
+            expect(result.playerId).toBeDefined();
+            expect(client.roomId).toBe(result.roomId);
+        });
 
         it('should leave room', async () => {
-            env.server.define('game', GameRoom)
+            env.server.define('game', GameRoom);
 
-            const client = await env.createClient()
-            await client.joinRoom('game')
+            const client = await env.createClient();
+            await client.joinRoom('game');
 
-            await client.leaveRoom()
+            await client.leaveRoom();
 
-            expect(client.roomId).toBeNull()
-        })
+            expect(client.roomId).toBeNull();
+        });
 
         it('should join existing room by id', async () => {
-            env.server.define('game', GameRoom)
+            env.server.define('game', GameRoom);
 
-            const client1 = await env.createClient()
-            const { roomId } = await client1.joinRoom('game')
+            const client1 = await env.createClient();
+            const { roomId } = await client1.joinRoom('game');
 
-            const client2 = await env.createClient()
-            const result = await client2.joinRoomById(roomId)
+            const client2 = await env.createClient();
+            const result = await client2.joinRoomById(roomId);
 
-            expect(result.roomId).toBe(roomId)
-        })
-    })
+            expect(result.roomId).toBe(roomId);
+        });
+    });
 
     // ========================================================================
     // Message Tests | 消息测试
@@ -131,66 +131,66 @@ describe('Room Integration Tests', () => {
 
     describe('Room Messages', () => {
         it('should receive room messages', async () => {
-            env.server.define('game', GameRoom)
+            env.server.define('game', GameRoom);
 
-            const client = await env.createClient()
-            await client.joinRoom('game')
+            const client = await env.createClient();
+            await client.joinRoom('game');
 
-            const movePromise = client.waitForRoomMessage('PlayerMoved')
-            client.sendToRoom('Move', { x: 100, y: 200 })
+            const movePromise = client.waitForRoomMessage('PlayerMoved');
+            client.sendToRoom('Move', { x: 100, y: 200 });
 
-            const msg = await movePromise
+            const msg = await movePromise;
             expect(msg).toEqual({
                 playerId: client.playerId,
                 x: 100,
-                y: 200,
-            })
-        })
+                y: 200
+            });
+        });
 
         it('should receive broadcast messages', async () => {
-            env.server.define('game', GameRoom)
+            env.server.define('game', GameRoom);
 
-            const [client1, client2] = await env.createClients(2)
+            const [client1, client2] = await env.createClients(2);
 
-            const { roomId } = await client1.joinRoom('game')
-            await client2.joinRoomById(roomId)
+            const { roomId } = await client1.joinRoom('game');
+            await client2.joinRoomById(roomId);
 
             // client1 等待收到 client2 的移动消息
-            const movePromise = client1.waitForRoomMessage('PlayerMoved')
-            client2.sendToRoom('Move', { x: 50, y: 75 })
+            const movePromise = client1.waitForRoomMessage('PlayerMoved');
+            client2.sendToRoom('Move', { x: 50, y: 75 });
 
-            const msg = await movePromise
+            const msg = await movePromise;
             expect(msg).toMatchObject({
                 playerId: client2.playerId,
                 x: 50,
-                y: 75,
-            })
-        })
+                y: 75
+            });
+        });
 
         it('should handle player join/leave broadcasts', async () => {
-            env.server.define('broadcast', BroadcastRoom)
+            env.server.define('broadcast', BroadcastRoom);
 
-            const client1 = await env.createClient()
-            const { roomId } = await client1.joinRoom('broadcast')
+            const client1 = await env.createClient();
+            const { roomId } = await client1.joinRoom('broadcast');
 
             // 等待 client2 加入的广播
-            const joinPromise = client1.waitForRoomMessage<{ id: string }>('PlayerJoined')
+            const joinPromise = client1.waitForRoomMessage<{ id: string }>('PlayerJoined');
 
-            const client2 = await env.createClient()
-            const client2Result = await client2.joinRoomById(roomId)
+            const client2 = await env.createClient();
+            const client2Result = await client2.joinRoomById(roomId);
 
-            const joinMsg = await joinPromise
-            expect(joinMsg).toMatchObject({ id: client2Result.playerId })
+            const joinMsg = await joinPromise;
+            expect(joinMsg).toMatchObject({ id: client2Result.playerId });
 
             // 等待 client2 离开的广播
-            const leavePromise = client1.waitForRoomMessage<{ id: string }>('PlayerLeft')
-            const client2PlayerId = client2.playerId // 保存 playerId
-            await client2.leaveRoom()
+            const leavePromise = client1.waitForRoomMessage<{ id: string }>('PlayerLeft');
+            const client2PlayerId = client2.playerId; // 保存 playerId
+            await client2.leaveRoom();
 
-            const leaveMsg = await leavePromise
-            expect(leaveMsg).toMatchObject({ id: client2PlayerId })
-        })
-    })
+            const leaveMsg = await leavePromise;
+            expect(leaveMsg).toMatchObject({ id: client2PlayerId });
+        });
+    });
 
     // ========================================================================
     // MockRoom Tests | 模拟房间测试
@@ -198,45 +198,45 @@ describe('Room Integration Tests', () => {
 
     describe('MockRoom', () => {
         it('should record messages', async () => {
-            env.server.define('mock', MockRoom)
+            env.server.define('mock', MockRoom);
 
-            const client = await env.createClient()
-            await client.joinRoom('mock')
+            const client = await env.createClient();
+            await client.joinRoom('mock');
 
             // 使用 Echo 消息，因为它是明确定义的
-            const echoPromise = client.waitForRoomMessage('EchoReply')
-            client.sendToRoom('Echo', { value: 123 })
-            await echoPromise
+            const echoPromise = client.waitForRoomMessage('EchoReply');
+            client.sendToRoom('Echo', { value: 123 });
+            await echoPromise;
 
-            expect(client.hasReceivedMessage('RoomMessage')).toBe(true)
-        })
+            expect(client.hasReceivedMessage('RoomMessage')).toBe(true);
+        });
 
         it('should handle echo', async () => {
-            env.server.define('mock', MockRoom)
+            env.server.define('mock', MockRoom);
 
-            const client = await env.createClient()
-            await client.joinRoom('mock')
+            const client = await env.createClient();
+            await client.joinRoom('mock');
 
-            const echoPromise = client.waitForRoomMessage('EchoReply')
-            client.sendToRoom('Echo', { message: 'hello' })
+            const echoPromise = client.waitForRoomMessage('EchoReply');
+            client.sendToRoom('Echo', { message: 'hello' });
 
-            const reply = await echoPromise
-            expect(reply).toEqual({ message: 'hello' })
-        })
+            const reply = await echoPromise;
+            expect(reply).toEqual({ message: 'hello' });
+        });
 
         it('should handle ping/pong', async () => {
-            env.server.define('mock', MockRoom)
+            env.server.define('mock', MockRoom);
 
-            const client = await env.createClient()
-            await client.joinRoom('mock')
+            const client = await env.createClient();
+            await client.joinRoom('mock');
 
-            const pongPromise = client.waitForRoomMessage<{ timestamp: number }>('Pong')
-            client.sendToRoom('Ping', {})
+            const pongPromise = client.waitForRoomMessage<{ timestamp: number }>('Pong');
+            client.sendToRoom('Ping', {});
 
-            const pong = await pongPromise
-            expect(pong.timestamp).toBeGreaterThan(0)
-        })
-    })
+            const pong = await pongPromise;
+            expect(pong.timestamp).toBeGreaterThan(0);
+        });
+    });
 
     // ========================================================================
     // Multiple Clients Tests | 多客户端测试
@@ -244,45 +244,45 @@ describe('Room Integration Tests', () => {
 
     describe('Multiple Clients', () => {
         it('should handle multiple clients in same room', async () => {
-            env.server.define('game', GameRoom)
+            env.server.define('game', GameRoom);
 
-            const clients = await env.createClients(3)
-            const { roomId } = await clients[0].joinRoom('game')
+            const clients = await env.createClients(3);
+            const { roomId } = await clients[0].joinRoom('game');
 
             for (let i = 1; i < clients.length; i++) {
-                await clients[i].joinRoomById(roomId)
+                await clients[i].joinRoomById(roomId);
             }
 
             // 所有客户端都应该能收到消息
-            const promises = clients.map((c) => c.waitForRoomMessage('PlayerMoved'))
+            const promises = clients.map((c) => c.waitForRoomMessage('PlayerMoved'));
 
-            clients[0].sendToRoom('Move', { x: 1, y: 2 })
+            clients[0].sendToRoom('Move', { x: 1, y: 2 });
 
-            const results = await Promise.all(promises)
+            const results = await Promise.all(promises);
             for (const result of results) {
-                expect(result).toMatchObject({ x: 1, y: 2 })
+                expect(result).toMatchObject({ x: 1, y: 2 });
             }
-        })
+        });
 
         it('should handle concurrent room operations', async () => {
-            env.server.define('game', GameRoom)
+            env.server.define('game', GameRoom);
 
-            const clients = await env.createClients(4) // maxPlayers = 4
+            const clients = await env.createClients(4); // maxPlayers = 4
 
             // 顺序加入房间（避免并发创建多个房间）
-            const { roomId } = await clients[0].joinRoom('game')
+            const { roomId } = await clients[0].joinRoom('game');
 
             // 其余客户端加入同一房间
             const results = await Promise.all(
                 clients.slice(1).map((c) => c.joinRoomById(roomId))
-            )
+            );
 
             // 验证所有客户端都在同一房间
             for (const result of results) {
-                expect(result.roomId).toBe(roomId)
+                expect(result.roomId).toBe(roomId);
             }
-        })
-    })
+        });
+    });
 
     // ========================================================================
     // Error Handling Tests | 错误处理测试
@@ -290,31 +290,31 @@ describe('Room Integration Tests', () => {
 
     describe('Error Handling', () => {
         it('should reject joining non-existent room type', async () => {
-            const client = await env.createClient()
+            const client = await env.createClient();
 
-            await expect(client.joinRoom('nonexistent')).rejects.toThrow()
-        })
+            await expect(client.joinRoom('nonexistent')).rejects.toThrow();
+        });
 
         it('should handle client disconnect gracefully', async () => {
-            env.server.define('game', GameRoom)
+            env.server.define('game', GameRoom);
 
-            const client1 = await env.createClient()
-            const { roomId } = await client1.joinRoom('game')
+            const client1 = await env.createClient();
+            const { roomId } = await client1.joinRoom('game');
 
-            const client2 = await env.createClient()
-            await client2.joinRoomById(roomId)
+            const client2 = await env.createClient();
+            await client2.joinRoomById(roomId);
 
             // 等待 client2 离开的广播
-            const leavePromise = client1.waitForRoomMessage('PlayerLeft')
+            const leavePromise = client1.waitForRoomMessage('PlayerLeft');
 
             // 强制断开 client2
-            await client2.disconnect()
+            await client2.disconnect();
 
             // client1 应该收到离开消息
-            const msg = await leavePromise
-            expect(msg).toBeDefined()
-        })
-    })
+            const msg = await leavePromise;
+            expect(msg).toBeDefined();
+        });
+    });
 
     // ========================================================================
     // Assertion Helpers Tests | 断言辅助测试
@@ -322,50 +322,50 @@ describe('Room Integration Tests', () => {
 
     describe('TestClient Assertions', () => {
         it('should track received messages', async () => {
-            env.server.define('mock', MockRoom)
+            env.server.define('mock', MockRoom);
 
-            const client = await env.createClient()
-            await client.joinRoom('mock')
+            const client = await env.createClient();
+            await client.joinRoom('mock');
 
             // 发送多条消息
-            client.sendToRoom('Test', { n: 1 })
-            client.sendToRoom('Test', { n: 2 })
-            client.sendToRoom('Test', { n: 3 })
+            client.sendToRoom('Test', { n: 1 });
+            client.sendToRoom('Test', { n: 2 });
+            client.sendToRoom('Test', { n: 3 });
 
             // 等待消息处理
-            await wait(100)
+            await wait(100);
 
-            expect(client.getMessageCount()).toBeGreaterThan(0)
-            expect(client.hasReceivedMessage('RoomMessage')).toBe(true)
-        })
+            expect(client.getMessageCount()).toBeGreaterThan(0);
+            expect(client.hasReceivedMessage('RoomMessage')).toBe(true);
+        });
 
         it('should get messages of specific type', async () => {
-            env.server.define('mock', MockRoom)
+            env.server.define('mock', MockRoom);
 
-            const client = await env.createClient()
-            await client.joinRoom('mock')
+            const client = await env.createClient();
+            await client.joinRoom('mock');
 
-            client.sendToRoom('Ping', {})
-            await client.waitForRoomMessage('Pong')
+            client.sendToRoom('Ping', {});
+            await client.waitForRoomMessage('Pong');
 
-            const pongs = client.getMessagesOfType('RoomMessage')
-            expect(pongs.length).toBeGreaterThan(0)
-        })
+            const pongs = client.getMessagesOfType('RoomMessage');
+            expect(pongs.length).toBeGreaterThan(0);
+        });
 
         it('should clear message history', async () => {
-            env.server.define('mock', MockRoom)
+            env.server.define('mock', MockRoom);
 
-            const client = await env.createClient()
-            await client.joinRoom('mock')
+            const client = await env.createClient();
+            await client.joinRoom('mock');
 
-            client.sendToRoom('Test', {})
-            await wait(50)
+            client.sendToRoom('Test', {});
+            await wait(50);
 
-            expect(client.getMessageCount()).toBeGreaterThan(0)
+            expect(client.getMessageCount()).toBeGreaterThan(0);
 
-            client.clearMessages()
+            client.clearMessages();
 
-            expect(client.getMessageCount()).toBe(0)
-        })
-    })
-})
+            expect(client.getMessageCount()).toBe(0);
+        });
+    });
+});