@qlover/create-app 0.7.15 → 0.9.0

package/dist/templates/react-app/docs/en/index.md

@@ -1,173 +1,802 @@
-# React Application Development Documentation
+# Project Architecture Design
 
-## Introduction
+> **📖 This document is the entry point of the project, providing an architecture overview, core concepts, and complete documentation navigation.**
 
-This is a modern frontend application template based on React 18, integrating a complete development framework and toolchain. This template provides a comprehensive development solution, including state management, routing management, internationalization, theme system, and other core functionalities.
+## 📋 Table of Contents
 
-### Key Features
+- [Quick Start](#-quick-start)
+- [Architecture Overview](#-architecture-overview)
+- [Layered Architecture](#-layered-architecture)
+- [Complete Workflow](#-complete-workflow)
+- [Core Concepts](#-core-concepts)
+- [Quick Example](#-quick-example)
+- [Detailed Documentation Navigation](#-detailed-documentation-navigation)
 
-- 🚀 **Modern Technology Stack**: Based on React 18, TypeScript, Vite
-- 🎨 **Theme Customization**: Supports dynamic theme switching, dark mode
-- 🌍 **Internationalization**: Built-in multi-language support
-- 📦 **State Management**: Reactive state management based on publish-subscribe pattern
-- 🔑 **Authentication System**: Complete user authentication solution
-- 🛠️ **Development Tools**: ESLint, Prettier, TypeScript
-- 📱 **Responsive Design**: Supports multi-platform adaptation
-- 🧪 **Testing Support**: Integrated unit testing and component testing
+---
 
-## Quick Start
+## 🚀 Quick Start
+
+### New Developers
+
+If this is your first time with this project, we recommend the following order:
+
+1. **Read this document** - Understand overall architecture and core philosophy (10-15 minutes)
+2. **[IOC Container](./ioc.md)** - Understand UI and logic separation (10-15 minutes)
+3. **[Store State Management](./store.md)** - Understand how application layer notifies UI layer (10-15 minutes)
+4. **[Development Guide](./development-guide.md)** - Follow complete example to develop a page (20-30 minutes)
+
+### Experienced Developers
+
+If you already have relevant experience, you can directly:
+
+1. Quickly browse this document to understand architecture features
+2. Check [Development Guide](./development-guide.md) to understand development workflow
+3. Refer to specialized documentation as needed
+
+### Environment Setup
 
 ```bash
 # Install dependencies
-npm install
+pnpm install
 
 # Start development server
-npm run dev
+pnpm dev
+
+# Start staging environment
+pnpm dev:staging
 
 # Build production version
-npm run build
+pnpm build
+
+# Run tests
+pnpm test
 ```
 
-## Documentation Navigation
+---
+
+## 🎯 Architecture Overview
 
-### Architecture Guide
+This project adopts **Layered Architecture + Dependency Injection + Interface-Oriented Programming** design pattern.
 
-- [Project Structure](./project-structure.md)
-- [Development Guidelines](./development-guide.md)
-- [Build and Deployment Guide](./deployment.md)
+### Architecture Panorama
 
-### Core Features
+```
+┌─────────────────────────────────────────────────────┐
+│  Config Layer                                        │
+│  • Unified management of all configurations         │
+│    (routes, themes, i18n, IOC, etc.)                │
+│  • Environment variable injection target            │
+│    (AppConfig.ts)                                   │
+│  📄 See: env.md                                      │
+└─────────────────────────────────────────────────────┘
+                        ↓
+┌─────────────────────────────────────────────────────┐
+│  Entry Layer                                         │
+│  • main.tsx: Application startup                     │
+│  • Inject global dependencies (window, document)     │
+│  • Initialize IOC container                          │
+│  • Execute Bootstrap startup process                 │
+│  📄 See: bootstrap.md                                │
+└─────────────────────────────────────────────────────┘
+                        ↓
+┌─────────────────────────────────────────────────────┐
+│  Core Layer                                          │
+│  • globals.ts: Encapsulate browser APIs              │
+│  • clientIoc/: IOC container management              │
+│  • bootstraps/: Bootstrap startup process            │
+│  📄 See: why-no-globals.md                           │
+└─────────────────────────────────────────────────────┘
+                        ↓
+┌─────────────────────────────────────────────────────┐
+│  Business Layer                                      │
+│  • port/: Interface definitions                      │
+│  • services/: Service implementations                │
+│  • cases/: Business use cases                        │
+│  • apis/: External API adapters                      │
+│  📄 See: ioc.md                                      │
+└─────────────────────────────────────────────────────┘
+                        ↓
+┌─────────────────────────────────────────────────────┐
+│  UI Layer                                            │
+│  • pages/: Page components                           │
+│  • components/: UI components                        │
+│  • hooks/: React Hooks (useIOC, useStore, etc.)      │
+│  • bridges/: Page bridges                            │
+│  📄 See: store.md                                    │
+└─────────────────────────────────────────────────────┘
+```
+
+### Core Principles
 
-- [Router Development Guide](./router.md)
-- [State Management Guide](./store.md)
-- [Internationalization Guide](./i18n.md)
-- [Theme Development Guide](./theme.md)
-- [Request System Guide](./request.md)
+1. **Unidirectional Dependency** ↓ - Can only depend from top to bottom, not reverse
+2. **Depend on Interfaces, Not Implementations** 🔌 - All dependencies defined through interfaces
+3. **UI and Logic Separation** 🎨 - UI is UI, logic is logic
+4. **Single Responsibility** 📦 - Each module does one thing
+5. **Configuration-Driven** ⚙️ - Business logic driven by configuration
 
-### Component Development
+---
 
-- [Component Development Guide](./component-guide.md)
-- [TypeScript Development Standards](./typescript-guide.md)
-- [Styling Guide](./styling-guide.md)
+## 🏗️ Layered Architecture
 
-### Tools and Testing
+### 1. Config Layer
 
-- [Testing Development Guide](./testing.md)
-- [Git Workflow Guide](./git-workflow.md)
-- [Performance Optimization Guide](./performance.md)
+**Location:** `config/`, `src/base/cases/AppConfig.ts`
 
-### Security and Best Practices
+**Responsibilities:**
 
-- [Security Development Guide](./security.md)
-- [Documentation Writing Guide](./documentation.md)
+- Unified management of all configurations (routes, themes, i18n, IOC identifiers, etc.)
+- Serve as injection target for environment variables
 
-## Directory Structure
+**File Structure:**
 
 ```
-docs/en/
-├── index.md                # This document
-├── project-structure.md    # Project structure explanation
-├── development-guide.md    # Development guidelines
-├── router.md              # Router development guide
-├── store.md               # State management guide
-├── i18n.md                # Internationalization guide
-├── theme.md               # Theme development guide
-└── ...
+config/
+├── common.ts              # Common configuration
+├── theme.ts               # Theme configuration
+├── app.router.ts          # Route configuration
+├── IOCIdentifier.ts       # IOC identifiers
+├── i18n/                  # Internationalization config
+└── Identifier/            # Business identifiers
 ```
 
-## Core Concepts
+**👉 See:** [Environment Variable Management](./env.md)
+
+### 2. Entry Layer
+
+**Location:** `src/main.tsx`, `src/core/bootstraps/`
+
+**Responsibilities:**
+
+- Application startup
+- Inject global dependencies (browser APIs)
+- Create IOC container
+- Execute Bootstrap startup process
+
+**Key Characteristics:**
+
+- 🔴 **Only place allowed to directly access global variables**
+- 🔴 **Bootstrap executes all initialization before app renders**
+
+**👉 See:** [Bootstrap Initializer](./bootstrap.md)
 
-### 1. Startup Process
+### 3. Core Layer
 
-The application uses a plugin-based startup process:
+**Location:** `src/core/`
+
+**Responsibilities:**
+
+- Encapsulate browser APIs (localStorage, cookie, etc.)
+- Manage global instances (logger, dialog, etc.)
+- IOC container initialization and service registration
+- Bootstrap flow control
+
+**File Structure:**
 
 ```
-Bootstrap Initialization → Load Plugins → Initialize Services → Render Application
+core/
+├── globals.ts              # Global variable encapsulation
+├── IOC.ts                  # IOC utilities
+├── bootstraps/             # Startup process
+│   ├── BootstrapClient.ts
+│   └── BootstrapsRegistry.ts
+└── clientIoc/              # IOC container
+    ├── ClientIOC.ts
+    └── ClientIOCRegister.ts
 ```
 
-### 2. State Management
+**👉 See:** [Why Disable Global Variables](./why-no-globals.md)
+
+### 4. Business Layer
+
+**Location:** `src/base/`
 
-Reactive state management based on publish-subscribe pattern:
+**Responsibilities:**
+
+- Define business interfaces (Port)
+- Implement business services (Services)
+- Handle business logic (Cases)
+- Adapt external APIs (APIs)
+
+**File Structure:**
 
 ```
-Action Trigger → Store Update → Component Re-render
+base/
+├── port/                   # Interface definitions
+│   ├── UserServiceInterface.ts
+│   └── I18nServiceInterface.ts
+├── services/               # Service implementations
+│   ├── UserService.ts
+│   └── I18nService.ts
+├── cases/                  # Business use cases
+│   ├── AppConfig.ts
+│   └── AppError.ts
+└── apis/                   # API adapters
+    └── userApi/
+        ├── UserApi.ts
+        └── UserApiType.ts
 ```
 
-### 3. Routing System
+**Key Characteristics:**
+
+- 🔵 **Interface-Oriented** - All dependencies injected through interfaces
+- 🔵 **Single Responsibility** - Each service responsible for one domain
+- 🔵 **Testability** - Easy to mock and test
+
+**👉 See:** [IOC Container](./ioc.md)
+
+### 5. UI Layer
 
-Configuration-based route management:
+**Location:** `src/pages/`, `src/uikit/`
+
+**Responsibilities:**
+
+- Render pages and components
+- Handle user interactions
+- Get services through `useIOC`
+- Subscribe to state through `useStore`
+
+**File Structure:**
 
 ```
-Route Configuration → Auto-generate Routes → Code Splitting → Lazy Loading
+├── pages/                  # Page components
+│   ├── base/
+│   └── auth/
+└── uikit/                  # UI utilities
+    ├── components/         # Common components
+    ├── hooks/              # React Hooks
+    │   ├── useIOC.ts       # IOC Hook
+    │   └── useStore.ts     # Store Hook
+    ├── contexts/           # React Context
+    └── bridges/            # Page bridges
+```
+
+**Key Characteristics:**
+
+- 🟢 **Don't depend on implementations directly** - Get services through IOC
+- 🟢 **UI and logic separated** - Only handle rendering and interaction
+- 🟢 **Reactive updates** - Automatic updates through Store
+
+**👉 See:** [Store State Management](./store.md)
+
+---
+
+## 🔄 Complete Workflow
+
+### Data Flow Diagram
+
+```
+┌─────────────────────────────────────────────┐
+│  1. User Interaction (UI Layer)             │
+│  const userService = useIOC('UserService')  │
+│  userService.login(username, password)      │
+└──────────────────┬──────────────────────────┘
+                   ↓ (Call service through IOC)
+┌─────────────────────────────────────────────┐
+│  2. Service Layer Processing (Business)      │
+│  async login(username, password) {          │
+│    const response = await this.api.login()  │
+│    this.storage.setItem('token', ...)       │
+│    this.emit({ user: ... })  // Notify UI   │
+│  }                                          │
+└──────────────┬─────────────┬────────────────┘
+               ↓             ↓ (Call API)
+      (Use Storage)    ┌─────────────────────┐
+               ↓         │  3. API Layer        │
+    ┌──────────────┐    │  POST /api/login    │
+    │ Core/Globals │    └─────────────────────┘
+    │ localStorage │              ↓
+    └──────────────┘         (HTTP request)
+               ↓                 ↓
+    (Data persistence)      (Backend server)
+               ↓                 ↓
+               └────←── Return data ←┘
+                         ↓
+               (emit publishes new state)
+                         ↓
+          ┌─────────────────────────┐
+          │  4. Store notifies        │
+          │     subscribers           │
+          │  listeners.forEach(...)   │
+          └─────────────────────────┘
+                         ↓
+          ┌─────────────────────────┐
+          │  5. UI auto-updates       │
+          │  useStore receives        │
+          │  notification             │
+          │  Component re-renders     │
+          └─────────────────────────┘
+```
+
+### Application Startup Flow
+
+```
+1️⃣ main.tsx
+   ↓
+2️⃣ BootstrapClient.main()
+   ├── Create IOC container
+   ├── Register all services
+   ├── Execute Bootstrap plugins
+   │   ├── InjectEnv (Inject env vars to AppConfig)
+   │   ├── I18nService.onBefore() (Initialize i18n)
+   │   ├── UserService.onBefore() (Check user login)
+   │   └── ProcesserExecutor.startup() (Start processors)
+   └── Bootstrap complete
+       ↓
+3️⃣ React application renders
+   ├── App.tsx
+   ├── IOCContext.Provider (Provide IOC container)
+   └── AppRouterProvider (Routing)
+       ↓
+4️⃣ Page components render
+   ├── useIOC() get services
+   ├── useStore() subscribe to state
+   └── UI renders
+```
+
+---
+
+## 💡 Core Concepts
+
+### 1. IOC Container (Dependency Injection) ⭐
+
+**Core Philosophy:** UI is UI, logic is logic, they must be separated
+
+```typescript
+// ❌ Traditional approach: UI and logic mixed together
+function UserProfile() {
+  const [user, setUser] = useState(null);
+  useEffect(() => {
+    fetch('/api/user').then(res => res.json()).then(setUser);
+  }, []);
+  return <div>{user?.name}</div>;
+}
+
+// ✅ IOC approach: UI and logic completely separated
+function UserProfile() {
+  const userService = useIOC('UserServiceInterface');  // Get service
+  const { user } = useStore(userService);               // Subscribe to state
+  return <div>{user?.name}</div>;
+}
+```
+
+**Key Questions:**
+
+1. **Why does an implementation class also need an interface?** → For testability
+2. **Why separate even simple components?** → Simple now doesn't mean simple later
+
+**👉 See:** [IOC Container Detailed Documentation](./ioc.md)
+
+### 2. Store State Management (Application Layer Notifies UI Layer) ⭐
+
+**Core Philosophy:** Service publishes state through Store, UI subscribes to state through useStore
+
+```typescript
+// Service (Application Layer)
+@injectable()
+export class UserService extends StoreInterface<UserState> {
+  async login(username: string, password: string) {
+    this.emit({ loading: true });  // Publish: start loading
+    const response = await this.api.login({ username, password });
+    this.emit({ user: response.user, loading: false });  // Publish: complete
+  }
+}
+
+// UI (UI Layer)
+function LoginPage() {
+  const userService = useIOC('UserServiceInterface');
+  const { loading } = useStore(userService);  // Subscribe: auto-update
+
+  return (
+    <button onClick={() => userService.login('user', 'pass')} disabled={loading}>
+      {loading ? 'Logging in...' : 'Login'}
+    </button>
+  );
+}
+```
+
+**👉 See:** [Store State Management Detailed Documentation](./store.md)
+
+### 3. Bootstrap Initializer (Application Initialization) ⭐
+
+**Core Philosophy:** Execute all initialization logic before app renders
+
+```typescript
+// Bootstrap plugin
+export class I18nService implements BootstrapPlugin {
+  onBefore() {
+    // Initialize i18n before app starts
+    i18n.init({
+      /* ... */
+    });
+  }
+}
+
+// Bootstrap execution
+const bootstrap = new Bootstrap({
+  root: window,
+  ioc: clientIOC
+});
+
+await bootstrap.initialize(); // Execute all plugins' onBefore
+await bootstrap.start(); // Start application
+```
+
+**👉 See:** [Bootstrap Initializer Detailed Documentation](./bootstrap.md)
+
+### 4. Environment Variable Management (Multi-Environment Configuration) ⭐
+
+**Core Philosophy:** Use `vite --mode` to switch environments, inject to AppConfig through Bootstrap
+
+```bash
+# Different environments
+npm run dev           # Development environment (.env.localhost)
+npm run dev:staging   # Staging environment (.env.staging)
+npm run build         # Production environment (.env.production)
+```
+
+```typescript
+// AppConfig automatically injects environment variables
+export class AppConfig {
+  readonly env: string;
+  readonly apiBaseUrl = ''; // Auto-injected from VITE_API_BASE_URL
+  readonly appName = ''; // Auto-injected from VITE_APP_NAME
+}
+
+// Usage
+const config = useIOC(IOCIdentifier.AppConfig);
+console.log(config.apiBaseUrl); // Automatically switches based on environment
 ```
 
-### 4. Internationalization
+**👉 See:** [Environment Variable Management Detailed Documentation](./env.md)
 
-Automatic internationalization based on TypeScript comments:
+### 5. Internationalization (i18n Key) ⭐
 
+**Core Philosophy:** All text uses i18n Keys, never hard-code
+
+```typescript
+// ❌ Wrong: Hard-coded text
+<button>Login</button>
+
+// ✅ Correct: Use i18n Key
+import { BUTTON_LOGIN } from '@config/Identifier';
+<button>{t(BUTTON_LOGIN)}</button>
 ```
-Comment Definition → Auto-generate Resources → Dynamic Loading → Language Switching
+
+**Core Advantage:** Developers don't need to remember `'common:button.login'` string, just need to know `BUTTON_LOGIN` variable, IDE will auto-complete
+
+**👉 See:** [Internationalization Detailed Documentation](./i18n.md)
+
+---
+
+## 📝 Quick Example
+
+### Example: Create a Theme Switching Feature
+
+```typescript
+// 1️⃣ Define interface (base/port/ThemeServiceInterface.ts)
+export interface ThemeServiceInterface {
+  setTheme(theme: 'light' | 'dark'): void;
+  getTheme(): 'light' | 'dark';
+}
+
+// 2️⃣ Implement service (base/services/ThemeService.ts)
+@injectable()
+export class ThemeService extends StoreInterface<ThemeState> {
+  constructor(
+    @inject(IOCIdentifier.LocalStorage) private storage: Storage
+  ) {
+    super(() => ({ theme: 'light' }));
+  }
+
+  setTheme(theme: 'light' | 'dark') {
+    this.storage.setItem('theme', theme);
+    this.emit({ theme });  // Notify UI to update
+  }
+
+  getTheme() {
+    return this.state.theme;
+  }
+}
+
+// 3️⃣ Register to IOC (core/clientIoc/ClientIOCRegister.ts)
+register(ioc: IOCContainer) {
+  ioc.bind(IOCIdentifier.ThemeServiceInterface, ThemeService);
+}
+
+// 4️⃣ UI usage (components/ThemeSwitcher.tsx)
+function ThemeSwitcher() {
+  const themeService = useIOC('ThemeServiceInterface');
+  const { theme } = useStore(themeService);
+
+  return (
+    <button onClick={() => themeService.setTheme(theme === 'light' ? 'dark' : 'light')}>
+      {theme === 'light' ? '🌙 Dark' : '☀️ Light'}
+    </button>
+  );
+}
 ```
 
-## Development Process
+**For complete development workflow see:** [Development Guide](./development-guide.md)
+
+---
+
+## 📚 Detailed Documentation Navigation
+
+### Core Documentation ⭐
+
+#### 1. [Development Guide](./development-guide.md)
+
+**Target Audience:** Developers preparing to develop new features  
+**Reading Time:** 20-30 minutes
+
+**Content Overview:**
+
+- What's needed to develop a page (8-item checklist)
+- Complete 10-step development process
+- Practical example: User list page (complete code)
+- Common scenarios (add button, dialog, search, etc.)
+- Code standards and development tools
+
+**Core Value:** Step-by-step guide to develop a complete page
+
+#### 2. [IOC Container](./ioc.md)
+
+**Core Questions:** How to separate UI and logic? Why need interfaces?
+
+**Key Content:**
+
+- Why need IOC (UI and logic separation)
+- Two key questions:
+  1. Why does an implementation class also need an interface? (Testability)
+  2. Why separate even simple components? (Future extensibility)
+- How to test logic and UI independently
+- How to test in combination
+- Complete practical examples
+
+**Applicable Scenarios:**
+
+- Need to create new services
+- Need to understand dependency injection
+- Need to write testable code
+
+#### 3. [Store State Management](./store.md)
+
+**Core Question:** How does application layer (Service) notify UI layer to update?
+
+**Key Content:**
+
+- Why need Store (solve communication problem)
+- Service publishes state through `emit`
+- UI subscribes to state through `useStore`
+- Selectors and performance optimization
+- Independent testing and combination testing
+
+**Applicable Scenarios:**
+
+- Service needs to notify UI to update
+- Need to implement reactive UI
+- Need to optimize rendering performance
+
+#### 4. [Bootstrap Initializer](./bootstrap.md)
+
+**Core Question:** How does application initialize? Why need Bootstrap?
+
+**Key Content:**
+
+- What is Bootstrap (plugin system)
+- Why need Bootstrap (problem-driven)
+- Core advantages of Bootstrap (especially testing)
+- Complete project implementation and examples
+- Vitest testing guide
+
+**Applicable Scenarios:**
+
+- Need to execute initialization logic before app starts
+- Need to understand application startup flow
+- Need to add new startup plugins
+
+#### 5. [Environment Variable Management](./env.md)
+
+**Core Question:** How to manage multi-environment configuration?
+
+**Key Content:**
+
+- Use `vite --mode` to switch environments
+- `.env` file management and priority
+- AppConfig automatic injection mechanism
+- Bootstrap's InjectEnv plugin
+- Multi-environment configuration examples
+
+**Applicable Scenarios:**
+
+- Need to add new environment variables
+- Need to switch between dev/staging/production environments
+- Need to understand configuration injection mechanism
+
+#### 6. [Internationalization (i18n)](./i18n.md)
+
+**Core Question:** How to manage multi-language text?
+
+**Key Content:**
+
+- **Core Principle:** All text uses i18n Keys, never hard-code
+- **Core Advantage:** Reduce developer thinking (don't need to remember strings, just variable names)
+- Auto-generate translation files (ts2Locales)
+- I18nService Bootstrap plugin
+- Complete usage examples
 
-1. **Requirement Analysis**
-   - Understand business requirements
-   - Design technical solutions
-   - Evaluate development cycle
+**Applicable Scenarios:**
 
-2. **Development Phase**
-   - Follow development standards
-   - Write unit tests
-   - Conduct code reviews
+- Need to add new text
+- Need to support new languages
+- Need to understand i18n Key concept
 
-3. **Testing Phase**
-   - Unit testing
-   - Integration testing
-   - Performance testing
+### Supporting Documentation
 
-4. **Deployment**
-   - Build optimization
-   - Deployment configuration
-   - Monitoring and alerts
+#### [Why Disable Global Variables](./why-no-globals.md)
 
-## Common Issues
+**Core Question:** Why can't we directly use `window`, `document`, etc.?
 
-### 1. Development Environment Setup
+**Key Content:**
 
-- Ensure Node.js version >= 16
-- Use recommended IDE configuration
-- Install necessary development tools
+- Core philosophy: Global variables should be injected from entry point
+- Allowed locations: `main.tsx`, `core/globals.ts`
+- Why do this (testing, SSR, traceability)
+- Practical application scenarios (IOC container)
+- Test-friendliness comparison
 
-### 2. Build Related
+#### [Route Management](./router.md)
 
-- Common build error solutions
-- Performance optimization suggestions
-- Deployment considerations
+**Core Content:**
 
-### 3. Development Related
+- Route configuration file (`config/app.router.ts`)
+- Route metadata (title, requiresAuth, etc.)
+- Dynamic route loading
+- RouteService usage
 
-- Code standard issues
-- Type system usage
-- Component development standards
+#### [Theme System](./theme.md)
+
+**Core Content:**
+
+- Tailwind CSS configuration
+- CSS variable management
+- Theme switching implementation
+- ThemeService usage
+
+#### [Request Handling](./request.md)
+
+**Core Content:**
+
+- API adapter pattern
+- Request plugin system
+- Error handling
+- Mock data
+
+#### [Testing Guide](./test-guide.md)
+
+**Core Content:**
+
+- Vitest testing framework
+- Service testing (logic layer)
+- UI testing (component layer)
+- Integration testing (workflow)
+- Testing best practices
+
+#### [Playwright E2E Testing](./playwright/) 🎭
+
+**Core Content:**
+
+- Complete E2E testing documentation
+- Multi-browser testing (Chromium, Firefox, WebKit, Mobile)
+- Page Object Model architecture
+- Test writing guide and best practices
+- Debugging techniques and CI/CD integration
+- See [Playwright Documentation Hub](./playwright/)
+- Quick reference: [Playwright Overview](./playwright/overview.md)
+
+#### [TypeScript Guide](./typescript-guide.md)
+
+**Core Content:**
+
+- TypeScript type standards
+- Generic usage
+- Type inference
+- Common issues
+
+---
+
+## 🎯 Quick Lookup
+
+### I want to...
+
+**Develop a new page** → [Development Guide](./development-guide.md)
+
+**Understand UI and logic separation** → [IOC Container](./ioc.md)
+
+**Let Service notify UI to update** → [Store State Management](./store.md)
+
+**Add environment variables** → [Environment Variable Management](./env.md)
+
+**Add multi-language text** → [Internationalization](./i18n.md)
+
+**Execute initialization before app starts** → [Bootstrap Initializer](./bootstrap.md)
+
+**Encapsulate browser APIs** → [Why Disable Global Variables](./why-no-globals.md)
+
+**Add routes** → [Route Management](./router.md)
+
+**Switch themes** → [Theme System](./theme.md)
+
+**Call APIs** → [Request Handling](./request.md)
+
+**Write unit tests** → [Testing Guide](./test-guide.md)
+
+**Write E2E tests** → [Playwright E2E Testing](./playwright/README.md)
+
+**Solve TypeScript issues** → [TypeScript Guide](./typescript-guide.md)
+
+---
+
+## 🎯 Core Philosophy Summary
+
+| Philosophy                    | Description                               | Benefits                         |
+| ----------------------------- | ----------------------------------------- | -------------------------------- |
+| **Layered Architecture**      | Clear responsibility division             | Easy to understand and maintain  |
+| **Unidirectional Dependency** | Can only depend from top to bottom        | Avoid circular dependencies      |
+| **Interface-Oriented**        | Depend on interfaces, not implementations | Easy to test and replace         |
+| **Dependency Injection**      | IOC container manages dependencies        | Decoupling, testable             |
+| **UI Separation**             | UI is UI, logic is logic                  | Independent testing, reusable    |
+| **State Management**          | Service emits, UI uses useStore           | Auto-update, maintain separation |
+| **Single Responsibility**     | Each module does one thing                | Easy to reuse and maintain       |
+| **Configuration-Driven**      | Business driven by configuration          | Flexible, easy to extend         |
+
+---
+
+## 🚦 Development Workflow
+
+```
+1. Define i18n Key (config/Identifier/)
+   ↓
+2. Define interface (base/port/)
+   ↓
+3. Implement service (base/services/)
+   ↓
+4. Implement API (if needed) (base/apis/)
+   ↓
+5. Configure routes (config/app.router.ts)
+   ↓
+6. Implement page (pages/)
+   ├── useIOC() get services
+   └── useStore() subscribe to state
+   ↓
+7. Register IOC (if new service) (core/clientIoc/)
+   ↓
+8. Write tests (__tests__/)
+   ├── Service tests (logic)
+   ├── UI tests (rendering)
+   └── Integration tests (workflow)
+```
 
-## Contribution Guide
+---
 
-1. Fork the project
-2. Create feature branch
-3. Submit changes
-4. Create Pull Request
+## 💡 Development Recommendations
 
-## Changelog
+### New Developers
 
-See [CHANGELOG.md](../../CHANGELOG.md) for detailed update history.
+1. Understand architecture first - Read this document
+2. Learn IOC - Read [IOC Container Documentation](./ioc.md)
+3. Learn Store - Read [Store Documentation](./store.md)
+4. See example code - Refer to existing `UserService`, `I18nService`, etc.
+5. Hands-on practice - Create a simple feature
 
-## Support and Help
+### Experienced Developers
 
-- Submit Issues
-- Check Wiki
-- Participate in discussions
+- **Bootstrap mechanism** → [Bootstrap Documentation](./bootstrap.md)
+- **Environment variable management** → [Environment Variable Documentation](./env.md)
+- **Internationalization implementation** → [i18n Documentation](./i18n.md)
+- **Global variable standards** → [why-no-globals Documentation](./why-no-globals.md)
 
-## License
+---
 
-This project is open-sourced under the [ISC License](../../LICENSE).
+**Feedback:**  
+If you have any questions or suggestions about the architecture design, please discuss in the team channel or submit an Issue.