@linyjs/plugin-docs 0.1.0

package/docs/guides/client-module.md

@@ -0,0 +1,598 @@
+# 客户端模块开发
+
+本指南详细介绍如何开发 linyjs 插件的客户端模块。
+
+## 概述
+
+客户端模块负责:
+
+- 🎨 定义页面路由和组件
+- 📊 管理全局状态
+- 🔗 提供可复用的组件和 Hooks
+- 💫 实现用户交互和 UI 逻辑
+
+## 模块结构
+
+一个完整的客户端模块包含:
+
+```typescript
+import type { IModule } from '@linyjs/client-module-interface';
+
+export const myClientModule: IModule = {
+  name: 'myClient',
+  serviceDefs: [
+    routeDef,           // 路由
+    stateDef,           // 全局状态
+    componentDef,       // 组件注册
+    hookDef,            // Hooks 注册
+    serviceDef          // 普通服务
+  ]
+};
+```
+
+## 路由(Route)
+
+路由用于定义页面的 URL 和组件映射。
+
+### 基本示例
+
+```typescript
+import type { IRouteService } from '@linyjs/client-module-interface';
+import React from 'react';
+
+function MyPage() {
+  return <div>My Page</div>;
+}
+
+class MyRouteService implements IRouteService {
+  basePath = '/my';  // 路由前缀
+  
+  getRoutes() {
+    return [
+      {
+        path: '/',
+        component: MyPage,
+        key: 'my-page',
+        meta: { 
+          title: 'My Page',
+          requiresAuth: true  // 需要登录
+        }
+      }
+    ];
+  }
+}
+
+export const routeDef = {
+  serviceTag: 'myRoute',
+  serviceImpl: MyRouteService,
+  meta: { usageType: 'route' }
+};
+```
+
+### 路由参数
+
+```typescript
+// 动态路由: /blog/:id
+{
+  path: '/:id',
+  component: BlogDetail,
+  key: 'blog-detail',
+  meta: { title: 'Blog Detail' }
+}
+
+// 在组件中获取参数
+import { useParams } from 'react-router-dom';
+
+function BlogDetail() {
+  const { id } = useParams();
+  return <div>Blog ID: {id}</div>;
+}
+```
+
+### 路由守卫
+
+```typescript
+{
+  path: '/admin',
+  component: AdminPanel,
+  key: 'admin',
+  guard: {
+    canEnter: async ({ location }) => {
+      // 检查权限
+      const hasPermission = checkAdminPermission();
+      if (!hasPermission) {
+        return '/forbidden';  // 重定向到禁止访问页面
+      }
+      return true;  // 允许访问
+    }
+  }
+}
+```
+
+### 数据预加载(Loader)
+
+```typescript
+{
+  path: '/articles',
+  component: ArticleList,
+  key: 'article-list',
+  loader: async ({ params }) => {
+    // 在渲染组件前预加载数据(SSR 友好)
+    const res = await fetch('/api/articles');
+    return { articles: await res.json() };
+  }
+}
+
+// 在组件中使用 loader 数据
+import { useLoaderData } from 'react-router-dom';
+
+function ArticleList() {
+  const { articles } = useLoaderData();
+  return <div>{/* 渲染文章列表 */}</div>;
+}
+```
+
+### 嵌套路由
+
+```typescript
+class BlogRouteService implements IRouteService {
+  basePath = '/blog';
+  
+  getRoutes() {
+    return [
+      {
+        path: '/',
+        component: BlogLayout,  // 布局组件
+        key: 'blog-layout',
+        children: [
+          {
+            path: '',
+            component: ArticleList,
+            key: 'article-list'
+          },
+          {
+            path: ':id',
+            component: ArticleDetail,
+            key: 'article-detail'
+          }
+        ]
+      }
+    ];
+  }
+}
+```
+
+## 全局状态(Global State)
+
+使用 Jotai 进行状态管理。
+
+### 定义状态
+
+```typescript
+import type { IGlobalStateService } from '@linyjs/client-module-interface';
+import { atom } from 'jotai';
+
+interface UserState {
+  id: number;
+  name: string;
+  email: string;
+}
+
+interface AppState {
+  user: UserState | null;
+  loading: boolean;
+  theme: 'light' | 'dark';
+}
+
+class MyStateService implements IGlobalStateService {
+  atoms = {
+    // 应用状态
+    appState: atom<AppState>({
+      user: null,
+      loading: false,
+      theme: 'light'
+    }),
+    
+    // 派生状态
+    isLoggedIn: atom((get) => {
+      const state = get(this.atoms.appState);
+      return state.user !== null;
+    }),
+    
+    // 可写状态
+    userName: atom(
+      (get) => get(this.atoms.appState).user?.name || '',
+      (get, set, newName: string) => {
+        const state = get(this.atoms.appState);
+        set(this.atoms.appState, {
+          ...state,
+          user: state.user ? { ...state.user, name: newName } : null
+        });
+      }
+    )
+  };
+}
+
+export const stateDef = {
+  serviceTag: 'myState',
+  serviceImpl: MyStateService,
+  meta: { usageType: 'global_state' }
+};
+```
+
+### 使用状态
+
+```typescript
+import { useAtom } from 'jotai';
+
+function UserProfile() {
+  const [appState, setAppState] = useAtom('myState.appState');
+  const [isLoggedIn] = useAtom('myState.isLoggedIn');
+  const [userName, setUserName] = useAtom('myState.userName');
+  
+  if (!isLoggedIn) {
+    return <div>Please login</div>;
+  }
+  
+  return (
+    <div>
+      <h1>Welcome, {userName}!</h1>
+      <button onClick={() => setUserName('New Name')}>
+        Change Name
+      </button>
+    </div>
+  );
+}
+```
+
+### 异步状态
+
+```typescript
+import { atom } from 'jotai';
+
+const userDataAtom = atom(async () => {
+  const res = await fetch('/api/user');
+  return res.json();
+});
+
+function UserDashboard() {
+  const [user] = useAtom(userDataAtom);
+  
+  if (!user) {
+    return <div>Loading...</div>;
+  }
+  
+  return <div>{user.name}</div>;
+}
+```
+
+## 组件注册(Component)
+
+注册可跨模块复用的组件。
+
+### 定义组件
+
+```typescript
+import type { IComponentListService } from '@linyjs/client-module-interface';
+import React from 'react';
+
+// 按钮组件
+function MyButton({ 
+  onClick, 
+  children 
+}: { 
+  onClick: () => void; 
+  children: React.ReactNode 
+}) {
+  return (
+    <button 
+      onClick={onClick}
+      style={{ padding: '8px 16px' }}
+    >
+      {children}
+    </button>
+  );
+}
+
+// 卡片组件
+function MyCard({ 
+  title, 
+  children 
+}: { 
+  title: string; 
+  children: React.ReactNode 
+}) {
+  return (
+    <div className="card">
+      <h3>{title}</h3>
+      {children}
+    </div>
+  );
+}
+
+class MyComponentService implements IComponentListService {
+  components = {
+    MyButton,
+    MyCard
+  };
+}
+
+export const componentDef = {
+  serviceTag: 'myComponents',
+  serviceImpl: MyComponentService,
+  meta: { usageType: 'component' }
+};
+```
+
+### 跨模块使用组件
+
+```typescript
+import { useClientComponent } from '@linyjs/client-module-interface';
+
+function MyPage() {
+  // 从其他模块获取组件
+  const MyButton = useClientComponent('otherModule.myComponents.MyButton');
+  
+  return (
+    <MyButton onClick={() => alert('Clicked!')}>
+      Click Me
+    </MyButton>
+  );
+}
+```
+
+## Hooks 注册
+
+注册可跨模块复用的自定义 Hooks。
+
+### 定义 Hooks
+
+```typescript
+import type { IHooksService } from '@linyjs/client-module-interface';
+import { useState, useEffect } from 'react';
+
+// 获取数据的 Hook
+function useFetchData<T>(url: string) {
+  const [data, setData] = useState<T | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  
+  useEffect(() => {
+    fetch(url)
+      .then(res => res.json())
+      .then(setData)
+      .catch(err => setError(err.message))
+      .finally(() => setLoading(false));
+  }, [url]);
+  
+  return { data, loading, error };
+}
+
+// 本地存储 Hook
+function useLocalStorage(key: string, initialValue: any) {
+  const [value, setValue] = useState(() => {
+    const stored = localStorage.getItem(key);
+    return stored ? JSON.parse(stored) : initialValue;
+  });
+  
+  useEffect(() => {
+    localStorage.setItem(key, JSON.stringify(value));
+  }, [key, value]);
+  
+  return [value, setValue];
+}
+
+class MyHooksService implements IHooksService {
+  hooks = {
+    useFetchData,
+    useLocalStorage
+  };
+}
+
+export const hookDef = {
+  serviceTag: 'myHooks',
+  serviceImpl: MyHooksService,
+  meta: { usageType: 'hook' }
+};
+```
+
+### 跨模块使用 Hooks
+
+```typescript
+import { useClientHook } from '@linyjs/client-module-interface';
+
+function MyComponent() {
+  const useFetchData = useClientHook('otherModule.myHooks.useFetchData');
+  const { data, loading } = useFetchData('/api/data');
+  
+  if (loading) return <div>Loading...</div>;
+  
+  return <div>{JSON.stringify(data)}</div>;
+}
+```
+
+## 样式处理
+
+### CSS Modules
+
+```typescript
+import styles from './MyComponent.module.css';
+
+function MyComponent() {
+  return <div className={styles.container}>Hello</div>;
+}
+```
+
+### 内联样式
+
+```typescript
+function MyComponent() {
+  return (
+    <div style={{ 
+      padding: '20px',
+      backgroundColor: '#f5f5f5'
+    }}>
+      Hello
+    </div>
+  );
+}
+```
+
+### Tailwind CSS
+
+```typescript
+function MyComponent() {
+  return (
+    <div className="p-4 bg-gray-100 rounded-lg">
+      Hello
+    </div>
+  );
+}
+```
+
+## 错误边界
+
+```typescript
+import React, { Component } from 'react';
+
+class ErrorBoundary extends Component {
+  state = { hasError: false };
+  
+  static getDerivedStateFromError(error: Error) {
+    return { hasError: true };
+  }
+  
+  render() {
+    if (this.state.hasError) {
+      return <div>Something went wrong.</div>;
+    }
+    return this.props.children;
+  }
+}
+
+// 使用
+function MyApp() {
+  return (
+    <ErrorBoundary>
+      <MyComponent />
+    </ErrorBoundary>
+  );
+}
+```
+
+## 性能优化
+
+### React.memo
+
+```typescript
+import { memo } from 'react';
+
+const ExpensiveComponent = memo(({ data }) => {
+  // 复杂计算...
+  return <div>{/* ... */}</div>;
+});
+```
+
+### useMemo
+
+```typescript
+import { useMemo } from 'react';
+
+function MyComponent({ items }) {
+  const sortedItems = useMemo(() => {
+    return [...items].sort((a, b) => a.name.localeCompare(b.name));
+  }, [items]);
+  
+  return <div>{/* ... */}</div>;
+}
+```
+
+### useCallback
+
+```typescript
+import { useCallback } from 'react';
+
+function MyComponent() {
+  const handleClick = useCallback(() => {
+    console.log('Clicked');
+  }, []);
+  
+  return <button onClick={handleClick}>Click</button>;
+}
+```
+
+### 懒加载
+
+```typescript
+import { lazy, Suspense } from 'react';
+
+const HeavyComponent = lazy(() => import('./HeavyComponent'));
+
+function MyPage() {
+  return (
+    <Suspense fallback={<div>Loading...</div>}>
+      <HeavyComponent />
+    </Suspense>
+  );
+}
+```
+
+## 完整示例
+
+查看完整示例:
+
+- 📁 [Hello World 示例](../../examples/hello-world/src/client/index.tsx)
+
+## 最佳实践
+
+### 1. 组件拆分
+
+```
+src/client/
+├── pages/           # 页面组件
+├── components/      # 可复用组件
+├── hooks/           # 自定义 Hooks
+└── services/        # 服务类
+```
+
+### 2. 类型安全
+
+```typescript
+interface MyComponentProps {
+  title: string;
+  onClick?: () => void;
+}
+
+function MyComponent({ title, onClick }: MyComponentProps) {
+  return <button onClick={onClick}>{title}</button>;
+}
+```
+
+### 3. 错误处理
+
+```typescript
+function SafeComponent() {
+  const [error, setError] = useState<string | null>(null);
+  
+  useEffect(() => {
+    fetchData()
+      .catch(err => setError(err.message));
+  }, []);
+  
+  if (error) {
+    return <div>Error: {error}</div>;
+  }
+  
+  return <div>Content</div>;
+}
+```
+
+## 下一步
+
+- 🎨 阅读 [UI 扩展插槽](./ui-slots.md)
+- 🔒 阅读 [权限管理](./permissions.md)
+- 💾 阅读 [数据持久化](./data-persistence.md)
+
+---
+
+**上一篇**: [服务端模块开发](./server-module.md) | **下一篇**: [UI 扩展插槽](./ui-slots.md)