Northern_Lights/cherry-studio
1
0
Fork 0
mirror of https://github.com/CherryHQ/cherry-studio.git synced 2026-01-09 23:10:20 +08:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

refactor: update data management documentation and structure

Browse Source 
- 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.
This commit is contained in:
fullex 2025-09-16 17:30:02 +08:00
parent f48674b2c7
commit bd7cd22220
3 changed files with 238 additions and 170 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
CLAUDE.md
View File

@ -57,11 +57,11 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
- **Client Factory**: Supports multiple AI providers (OpenAI, Anthropic, Gemini, etc.) - **Client Factory**: Supports multiple AI providers (OpenAI, Anthropic, Gemini, etc.)
- **Stream Processing**: Real-time response handling - **Stream Processing**: Real-time response handling
#### State Management (`src/renderer/src/store/`) #### Data Management
- **Redux Toolkit**: Centralized state management - **Cache System**: Three-layer caching (memory/shared/persist) with React hooks integration
- **Persistent Storage**: Redux-persist for data persistence - **Preferences**: Type-safe configuration management with multi-window synchronization
- **Thunks**: Async actions for complex operations - **User Data**: SQLite-based storage with Drizzle ORM for business data
#### Knowledge Management #### Knowledge Management
@ -115,6 +115,34 @@ HeroUI Docs: https://www.heroui.com/docs/guide/introduction
- **Timestamps**: Use existing `crudTimestamps` utility - **Timestamps**: Use existing `crudTimestamps` utility
- **Migrations**: Generate via `yarn run migrations:generate` - **Migrations**: Generate via `yarn run migrations:generate`
## Data Access Patterns
The application uses three distinct data management systems. Choose the appropriate system based on data characteristics:
### Cache System
- **Purpose**: Temporary data that can be regenerated
- **Lifecycle**: Component-level (memory), window-level (shared), or persistent (survives restart)
- **Use Cases**: API response caching, computed results, temporary UI state
- **APIs**: `useCache`, `useSharedCache`, `usePersistCache` hooks, or `cacheService`
### Preference System
- **Purpose**: User configuration and application settings
- **Lifecycle**: Permanent until user changes
- **Use Cases**: Theme, language, editor settings, user preferences
- **APIs**: `usePreference`, `usePreferences` hooks, or `preferenceService`
### User Data API
- **Purpose**: Core business data (conversations, files, notes, etc.)
- **Lifecycle**: Permanent business records
- **Use Cases**: Topics, messages, files, knowledge base, user-generated content
- **APIs**: `useDataApi` hook or `dataApiService` for direct calls
### Selection Guidelines
- **Use Cache** for data that can be lost without impact (computed values, API responses)
- **Use Preferences** for user settings that affect app behavior (UI configuration, feature flags)
- **Use User Data API** for irreplaceable business data (conversations, documents, user content)
## Logging Standards ## Logging Standards
### Usage ### Usage

241
packages/shared/data/README.md
View File

@ -1,197 +1,106 @@
# Cherry Studio Shared Data # Cherry Studio Shared Data
This directory contains shared data structures and API type definitions for the Cherry Studio application. It includes both persistent data schemas and API contract definitions. This directory contains shared type definitions and schemas for the Cherry Studio data management systems. These files provide type safety and consistency across the entire application.
## 📁 File Organization ## 📁 Directory Structure
### Persistent Data (Root Level) ```
packages/shared/data/
├── api/ # Data API type system
│ ├── index.ts # Barrel exports for clean imports
│ ├── apiSchemas.ts # API endpoint definitions and mappings
│ ├── apiTypes.ts # Core request/response infrastructure types
│ ├── apiModels.ts # Business entity types and DTOs
│ ├── apiPaths.ts # API path definitions and utilities
│ └── errorCodes.ts # Standardized error handling
├── cache/ # Cache system type definitions
│ ├── cacheTypes.ts # Core cache infrastructure types
│ ├── cacheSchemas.ts # Cache key schemas and type mappings
│ └── cacheValueTypes.ts # Cache value type definitions
├── preference/ # Preference system type definitions
│ ├── preferenceTypes.ts # Core preference system types
│ └── preferenceSchemas.ts # Preference schemas and default values
└── README.md # This file
```
- **`preferences.ts`** - User preference data schema and default values ## 🏗️ System Overview
- **`preferenceTypes.ts`** - TypeScript types for preference system
### API Types (`api/` subdirectory) This directory provides type definitions for three main data management systems:
- **`api/index.ts`** - Barrel export file providing clean imports for all API types ### API System (`api/`)
- **`api/apiTypes.ts`** - Core request/response types and API infrastructure - **Purpose**: Type-safe IPC communication between Main and Renderer processes
- **`api/apiModels.ts`** - Business entity types and Data Transfer Objects (DTOs) - **Features**: RESTful patterns, error handling, business entity definitions
- **`api/apiSchemas.ts`** - Complete API endpoint definitions with type mappings - **Usage**: Ensures type safety for all data API operations
- **`api/errorCodes.ts`** - Error handling utilities and standardized error codes
## 🏗️ Architecture Overview ### Cache System (`cache/`)
- **Purpose**: Type definitions for three-layer caching architecture
- **Features**: Memory/shared/persist cache schemas, TTL support, hook integration
- **Usage**: Type-safe caching operations across the application
These files are part of the **Renderer-Main Virtual Data Acquisition Architecture** that enables: ### Preference System (`preference/`)
- **Purpose**: User configuration and settings management
- **Features**: 158 configuration items, default values, nested key support
- **Usage**: Type-safe preference access and synchronization
- **Type-safe IPC communication** between Electron processes ## 📋 File Categories
- **RESTful API patterns** within the Electron application
- **Standardized error handling** across the application
- **Future extensibility** to standalone API servers
## 🔄 Classification Status **Framework Infrastructure** - These are TypeScript type definitions that:
- ✅ Exist only at compile time
**Important**: These files are **NOT classified** in the data refactor system because they are: - ✅ Provide type safety and IntelliSense support
- ✅ Define contracts between application layers
- ✅ **Type definitions** - Not actual data storage - ✅ Enable static analysis and error detection
- ✅ **Compile-time artifacts** - Exist only during TypeScript compilation
- ✅ **Framework infrastructure** - Enable the data API architecture
- ✅ **Development tools** - Similar to interfaces in other languages
## 📖 Usage Examples ## 📖 Usage Examples
### Basic Imports ### API Types
```typescript ```typescript
// Import API types from the api subdirectory // Import API types
import { Topic, CreateTopicDto, DataRequest, ApiSchemas, ErrorCode } from '@shared/data/api' import type { DataRequest, DataResponse, ApiSchemas } from '@shared/data/api'
// Import specific groups
import type { TopicTypes, MessageTypes } from '@shared/data/api'
// Import preferences
import type { UserPreferences } from '@shared/data/preferences'
``` ```
### API Schema Usage ### Cache Types
```typescript ```typescript
import type { ApiSchemas, ApiResponse } from '@shared/data/api' // Import cache types
import type { UseCacheKey, UseSharedCacheKey } from '@shared/data/cache'
// Get the response type for a specific endpoint
type TopicsListResponse = ApiResponse<'/topics', 'GET'>
// Result: PaginatedResponse<Topic>
type CreateTopicResponse = ApiResponse<'/topics', 'POST'>
// Result: Topic
``` ```
### Error Handling ### Preference Types
```typescript ```typescript
import { DataApiErrorFactory, ErrorCode, isDataApiError } from '@shared/data/api' // Import preference types
import type { PreferenceKeyType, PreferenceDefaultScopeType } from '@shared/data/preference'
// Create standardized errors
const notFoundError = DataApiErrorFactory.notFound('Topic', '123')
const validationError = DataApiErrorFactory.validation({
title: ['Title is required']
})
// Check if error is a Data API error
if (isDataApiError(error)) {
console.log(`Error ${error.code}: ${error.message}`)
}
```
### Request/Response Types
```typescript
import type { DataRequest, DataResponse, PaginatedResponse, Topic } from '@shared/data/api'
// Type-safe request construction
const request: DataRequest = {
id: 'req_123',
method: 'GET',
path: '/topics',
params: { page: 1, limit: 10 }
}
// Type-safe response handling
const response: DataResponse<PaginatedResponse<Topic>> = {
id: 'req_123',
status: 200,
data: {
items: [...],
total: 100,
page: 1,
pageCount: 10,
hasNext: true,
hasPrev: false
}
}
``` ```
## 🔧 Development Guidelines ## 🔧 Development Guidelines
### Adding New Domain Models ### Adding Cache Types
1. Add cache key to `cache/cacheSchemas.ts`
2. Define value type in `cache/cacheValueTypes.ts`
3. Update type mappings for type safety
1. Add the interface to `api/apiModels.ts` ### Adding Preference Types
2. Create corresponding DTOs (Create/Update) 1. Add preference key to `preference/preferenceSchemas.ts`
3. Export from `api/index.ts` 2. Define default value and type
4. Update API schemas if needed 3. Preference system automatically picks up new keys
```typescript ### Adding API Types
// In api/apiModels.ts 1. Define business entities in `api/apiModels.ts`
export interface NewEntity { 2. Add endpoint definitions to `api/apiSchemas.ts`
id: string 3. Export types from `api/index.ts`
name: string
createdAt: string
updatedAt: string
}
export interface CreateNewEntityDto { ### Best Practices
name: string - Use `import type` for type-only imports
} - Follow existing naming conventions
``` - Document complex types with JSDoc
- Maintain type safety across all imports
### Adding New API Endpoints ## 🔗 Related Implementation
1. Add endpoint definition to `api/apiSchemas.ts` ### Main Process Services
2. Include JSDoc comments with examples - `src/main/data/CacheService.ts` - Main process cache management
3. Ensure all types are properly referenced - `src/main/data/PreferenceService.ts` - Preference management service
- `src/main/data/DataApiService.ts` - Data API coordination service
```typescript ### Renderer Process Services
// In api/apiSchemas.ts - `src/renderer/src/data/CacheService.ts` - Renderer cache service
export interface ApiSchemas { - `src/renderer/src/data/PreferenceService.ts` - Renderer preference service
/** - `src/renderer/src/data/DataApiService.ts` - Renderer API client
* New entity endpoint
* @example GET /entities?page=1&limit=10
*/
'/entities': {
/** List all entities */
GET: {
query?: PaginationParams
response: PaginatedResponse<NewEntity>
}
}
}
```
### Type Safety Best Practices
- Always use `import type` for type-only imports
- Leverage the type helpers (`ApiResponse`, `ApiParams`, etc.)
- Use the barrel export for clean imports
- Document complex types with JSDoc comments
## 🔗 Related Files
### Main Process Implementation
- `src/main/data/DataApiService.ts` - Main process data service
- `src/main/data/api/` - Controllers, services, and routing
### Renderer Process Implementation
- `src/renderer/src/data/DataApiService.ts` - Renderer API client
- `src/renderer/src/data/hooks/` - React hooks for data fetching
### Shared Data Types
- `packages/shared/data/api/` - API contract definitions
- `packages/shared/data/preferences.ts` - User preference schemas
### Architecture Documentation
- `.claude/data-request-arch.md` - Complete architecture documentation
- `CLAUDE.md` - Project development guidelines
## 🚀 Future Enhancements
The type system is designed to support:
- **HTTP API Server** - Types can be reused for standalone HTTP APIs
- **GraphQL Integration** - Schema can be mapped to GraphQL resolvers
- **Real-time Subscriptions** - WebSocket/SSE event types are defined
- **Advanced Caching** - Cache-related types are ready for implementation
---
_This README is part of the Cherry Studio data refactor project. For more information, see the project documentation in `.claude/` directory._

131
src/main/data/README.md Normal file
View File

@ -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