refactor: update data management documentation and structure

- Renamed "State Management" to "Data Management" in CLAUDE.md for clarity. - Enhanced data management section with detailed descriptions of Cache System, Preference System, and User Data API. - Updated README.md in shared/data to reflect new directory structure and provide clearer organization of type definitions and schemas. - Added guidelines for selecting appropriate data access patterns based on data characteristics.
2025-09-16 17:30:02 +08:00
parent f48674b2c7
commit bd7cd22220
3 changed files with 238 additions and 170 deletions
@@ -0,0 +1,131 @@
+# Main Data Layer
+
+This directory contains the main process data management system, providing unified data access for the entire application.
+
+## Directory Structure
+
+```
+src/main/data/
+├── api/                    # Data API framework
+│   ├── core/              # Core API infrastructure
+│   │   ├── ApiServer.ts   # Request routing and handler execution
+│   │   ├── MiddlewareEngine.ts # Request/response middleware
+│   │   └── adapters/      # Communication adapters
+│   ├── handlers/          # API endpoint implementations
+│   ├── services/          # Business logic services
+│   └── index.ts          # API framework exports
+├── db/                    # Database layer
+│   ├── schemas/          # Drizzle table definitions
+│   ├── seeding/          # Database initialization
+│   └── DbService.ts      # Database connection and management
+├── migrate/              # Data migration system
+│   └── dataRefactor/     # v2 data refactoring migration tools
+├── CacheService.ts       # Main process cache management
+├── DataApiService.ts     # Data API coordination service
+└── PreferenceService.ts  # User preferences management
+```
+
+## Core Services
+
+### CacheService
+- **Purpose**: Main process caching with TTL support
+- **Features**: Memory cache, IPC synchronization, cross-window broadcasting
+- **Usage**: Internal caching for main process services
+
+### PreferenceService
+- **Purpose**: Type-safe user configuration management
+- **Features**: SQLite persistence, multi-window sync, batch operations
+- **Usage**: Managing user settings and application configuration
+
+### DataApiService
+- **Purpose**: Coordinates API server and IPC communication
+- **Features**: Request routing, error handling, type safety
+- **Usage**: Central hub for all data API operations
+
+## Data API Framework
+
+### API Server (`api/core/ApiServer.ts`)
+- Request routing and handler execution
+- Middleware pipeline processing
+- Type-safe endpoint definitions
+
+### Handlers (`api/handlers/`)
+- Endpoint implementations for business logic
+- Currently contains test handlers (production handlers pending)
+- Must implement types defined in `@shared/data/api`
+
+### Services (`api/services/`)
+- Business logic layer
+- Database operations and data validation
+- Called by API handlers
+
+## Database Layer
+
+### DbService
+- SQLite database connection management
+- Automatic migrations and seeding
+- Drizzle ORM integration
+
+### Schemas (`db/schemas/`)
+- Table definitions using Drizzle ORM
+- Follow naming convention: `{entity}Table` exports
+- Use `crudTimestamps` helper for timestamp fields
+
+### Current Tables
+- `preference`: User configuration storage
+- `appState`: Application state persistence
+
+## Usage Examples
+
+### Accessing Services
+```typescript
+// Get service instances
+import { cacheService } from '@/data/CacheService'
+import { preferenceService } from '@/data/PreferenceService'
+import { dataApiService } from '@/data/DataApiService'
+
+// Services are singletons, initialized at app startup
+```
+
+### Adding New API Endpoints
+1. Define endpoint in `@shared/data/api/apiSchemas.ts`
+2. Implement handler in `api/handlers/index.ts`
+3. Create service in `api/services/` if needed
+4. Add database schema in `db/schemas/` if required
+
+### Adding Database Tables
+1. Create schema in `db/schemas/{tableName}.ts`
+2. Generate migration: `yarn run migrations:generate`
+3. Add seeding data in `db/seeding/` if needed
+4. Create corresponding service in `api/services/`
+
+## Data Flow
+
+```
+Renderer IPC Request
+    ↓
+DataApiService (coordination)
+    ↓
+ApiServer (routing)
+    ↓
+Handler (endpoint logic)
+    ↓
+Service (business logic)
+    ↓
+DbService (data persistence)
+```
+
+## Development Guidelines
+
+- All services use singleton pattern
+- Database operations must be type-safe (Drizzle)
+- API endpoints require complete type definitions
+- Services should handle errors gracefully
+- Use existing logging system (`@logger`)
+
+## Integration Points
+
+- **IPC Communication**: All services expose IPC handlers for renderer communication
+- **Type Safety**: Shared types in `@shared/data` ensure end-to-end type safety
+- **Error Handling**: Standardized error codes and handling across all services
+- **Logging**: Comprehensive logging for debugging and monitoring