@linyjs/plugin-docs 0.0.15 → 0.0.17

package/docs/guides/state-management.md

@@ -0,0 +1,905 @@
+# 前端状态管理
+
+本指南详细介绍 linyjs 前端的全局状态管理机制，包括状态的定义、注册、消费和跨模块共享。
+
+## 概述
+
+linyjs 前端状态管理基于 [Jotai](https://jotai.org/) 实现，采用 **模块化声明 + 全局注册表** 的架构：
+
+- 📦 **模块化声明** — 每个客户端模块通过 `IGlobalStateService` 声明自己的 atoms
+- 🌐 **全局注册表** — 框架自动收集所有模块的 atoms，合并到全局注册表
+- 🔗 **跨模块共享** — 任意模块的组件都可以读取和修改其他模块注册的状态
+- ⚡ **SSR 兼容** — 状态通过 React Context 提供，SSR 和 CSR 模式下均可使用
+
+### 架构流程
+
+```
+模块 A (IGlobalStateService)     模块 B (IGlobalStateService)
+  atoms: { user, theme }           atoms: { cart, wishlist }
+         │                                │
+         └──────────┬─────────────────────┘
+                    ▼
+          框架收集 & 注册
+     ClientGlobalStateContext
+     { 'moduleA.state.user': atom,
+       'moduleA.state.theme': atom,
+       'moduleB.state.cart': atom, ... }
+                    │
+         ┌──────────┴──────────┐
+         ▼                     ▼
+    组件 useContext()      组件 useContext()
+    + useAtom()           + useAtom()
+```
+
+---
+
+## 核心接口
+
+### IAtom
+
+`IAtom` 是 Jotai Atom 的兼容类型，框架不直接依赖 Jotai，但运行时应使用 Jotai 的 `atom()` 创建：
+
+```typescript
+interface IAtom<T = any> {
+  readonly key: symbol    // atom 唯一标识（由 atom() 自动生成）
+  init?: T                // 初始值
+  [key: string]: unknown  // 其他 Jotai 内部属性
+}
+```
+
+> 💡 实际开发中，你不需要手动构造 `IAtom` 对象，直接使用 Jotai 的 `atom()` 函数即可。
+
+### IGlobalStateService
+
+全局状态服务接口，模块通过实现此接口来声明 atoms：
+
+```typescript
+interface IGlobalStateService {
+  atoms: Record<string, IAtom>
+}
+```
+
+### IGlobalStateDef
+
+全局状态服务的 ServiceDef 类型：
+
+```typescript
+type IGlobalStateDef = IServiceDef<IGlobalStateService, IGlobalStateMetadata>
+
+interface IGlobalStateMetadata extends IServiceMetadata {
+  usageType: 'global_state'
+}
+```
+
+### ClientGlobalStateContext
+
+React Context，持有所有模块注册的 atoms 注册表。框架在根组件中自动提供此 Context：
+
+```typescript
+const ClientGlobalStateContext: React.Context<Record<string, IAtom>>
+```
+
+---
+
+## 定义状态
+
+### 安装 Jotai
+
+linyjs 前端状态管理依赖 Jotai，在插件项目中安装：
+
+```bash
+npm install jotai
+```
+
+### 基本状态
+
+使用 Jotai 的 `atom()` 创建原始状态：
+
+```typescript
+import { atom } from 'jotai'
+import type { IGlobalStateService, IGlobalStateDef, IModule } from '@linyjs/client-module-interface'
+
+// 基础状态
+const userAtom = atom<{ id: string; name: string } | null>(null)
+const themeAtom = atom<'light' | 'dark'>('light')
+const countAtom = atom(0)
+
+// 状态服务
+class MyStateService implements IGlobalStateService {
+  atoms = {
+    user: userAtom,
+    theme: themeAtom,
+    count: countAtom,
+  }
+}
+
+// ServiceDef
+const myStateDef: IGlobalStateDef = {
+  serviceTag: 'myState',
+  serviceImpl: MyStateService,
+  meta: { usageType: 'global_state' },
+}
+
+// 模块声明
+export const myClientModule: IModule = {
+  name: 'myClient',
+  serviceDefs: [myStateDef],
+}
+```
+
+### 派生状态（只读）
+
+派生状态从其他 atom 计算而来，只读不可写：
+
+```typescript
+import { atom } from 'jotai'
+
+const userAtom = atom<{ id: string; name: string; roles: string[] } | null>(null)
+
+// 派生状态：用户是否已登录
+const isLoggedInAtom = atom((get) => get(userAtom) !== null)
+
+// 派生状态：用户是否是管理员
+const isAdminAtom = atom((get) => {
+  const user = get(userAtom)
+  return user?.roles?.includes('admin') ?? false
+})
+
+// 派生状态：用户显示名称
+const displayNameAtom = atom((get) => {
+  const user = get(userAtom)
+  return user ? user.name : '游客'
+})
+```
+
+### 可写派生状态
+
+可写派生状态既可以从其他 atom 读取，也可以接受写入操作：
+
+```typescript
+import { atom } from 'jotai'
+
+const itemsAtom = atom<{ id: string; name: string; done: boolean }[]>([])
+
+// 可写派生状态：未完成任务数量（只读）
+const pendingCountAtom = atom((get) => {
+  return get(itemsAtom).filter(item => !item.done).length
+})
+
+// 可写派生状态：切换任务完成状态
+const toggleItemAtom = atom(
+  (get) => get(itemsAtom),
+  (get, set, itemId: string) => {
+    const items = get(itemsAtom)
+    set(itemsAtom, items.map(item =>
+      item.id === itemId ? { ...item, done: !item.done } : item
+    ))
+  }
+)
+```
+
+### 异步状态
+
+Jotai 支持异步 atom，适合从 API 加载数据：
+
+```typescript
+import { atom } from 'jotai'
+
+// 异步 atom：从 API 加载用户信息
+const userProfileAtom = atom(async () => {
+  const token = localStorage.getItem('token')
+  if (!token) return null
+
+  const response = await fetch('/api/auth/me', {
+    headers: { 'Authorization': `Bearer ${token}` }
+  })
+  const result = await response.json()
+  return result.user ?? null
+})
+
+// 依赖其他 atom 的异步 atom
+const userIdAtom = atom<string | null>(null)
+const userDetailAtom = atom(async (get) => {
+  const userId = get(userIdAtom)
+  if (!userId) return null
+
+  const response = await fetch(`/api/users/${userId}`)
+  return response.json()
+})
+```
+
+---
+
+## 注册状态
+
+### 完整模块示例
+
+```typescript
+import { atom } from 'jotai'
+import type {
+  IModule,
+  IGlobalStateService,
+  IGlobalStateDef,
+  IRouteService,
+  IRouteDef,
+} from '@linyjs/client-module-interface'
+
+// ==================== 状态定义 ====================
+
+interface CartItem {
+  id: string
+  name: string
+  price: number
+  quantity: number
+}
+
+// 基础状态
+const cartItemsAtom = atom<CartItem[]>([])
+const couponAtom = atom<string | null>(null)
+
+// 派生状态
+const cartTotalAtom = atom((get) => {
+  const items = get(cartItemsAtom)
+  return items.reduce((sum, item) => sum + item.price * item.quantity, 0)
+})
+
+const cartCountAtom = atom((get) => {
+  return get(cartItemsAtom).reduce((sum, item) => sum + item.quantity, 0)
+})
+
+// ==================== 状态服务 ====================
+
+class CartStateService implements IGlobalStateService {
+  atoms = {
+    cartItems: cartItemsAtom,
+    coupon: couponAtom,
+    cartTotal: cartTotalAtom,
+    cartCount: cartCountAtom,
+  }
+}
+
+const cartStateDef: IGlobalStateDef = {
+  serviceTag: 'cartState',
+  serviceImpl: CartStateService,
+  meta: { usageType: 'global_state' },
+}
+
+// ==================== 路由服务 ====================
+
+class CartRouteService implements IRouteService {
+  basePath = '/shop'
+
+  getRoutes() {
+    return [
+      { path: '/cart', component: CartPage, key: 'cart-page' }
+    ]
+  }
+}
+
+const cartRouteDef: IRouteDef = {
+  serviceTag: 'cartRoute',
+  serviceImpl: CartRouteService,
+  meta: { usageType: 'route' },
+}
+
+// ==================== 模块声明 ====================
+
+export const shopClientModule: IModule = {
+  name: 'shopClient',
+  serviceDefs: [cartStateDef, cartRouteDef],
+}
+```
+
+### 注册表 Key 格式
+
+框架收集 atoms 时，会自动生成全局唯一的注册表 key，采用 **三段式格式**：
+
+```
+{moduleName}.{serviceTag}.{atomName}
+```
+
+以上面的 `shopClient` 模块为例，注册后的 key 为：
+
+| atom 名 | 注册表 key |
+|---------|-----------|
+| `cartItems` | `shopClient.cartState.cartItems` |
+| `coupon` | `shopClient.cartState.coupon` |
+| `cartTotal` | `shopClient.cartState.cartTotal` |
+| `cartCount` | `shopClient.cartState.cartCount` |
+
+> ⚠️ 消费状态时必须使用完整的注册表 key，而非原始的 atom 引用。
+
+---
+
+## 消费状态
+
+### 基本用法
+
+通过 `useContext` 获取 atoms 注册表，再用 Jotai 的 `useAtom` 读取和修改状态：
+
+```typescript
+import { useContext } from 'react'
+import { useAtom } from 'jotai'
+import { ClientGlobalStateContext } from '@linyjs/client-module-interface'
+
+function CartPage() {
+  // 1. 从 Context 获取 atoms 注册表
+  const atoms = useContext(ClientGlobalStateContext)
+
+  // 2. 通过注册表 key 获取 atom
+  const cartItemsAtom = atoms['shopClient.cartState.cartItems']
+  const cartTotalAtom = atoms['shopClient.cartState.cartTotal']
+
+  // 3. 使用 useAtom 读取和修改状态
+  const [cartItems, setCartItems] = useAtom(cartItemsAtom)
+  const [cartTotal] = useAtom(cartTotalAtom)
+
+  const removeItem = (id: string) => {
+    setCartItems(cartItems.filter(item => item.id !== id))
+  }
+
+  return (
+    <div>
+      <h1>购物车 ({cartItems.length})</h1>
+      <ul>
+        {cartItems.map(item => (
+          <li key={item.id}>
+            {item.name} × {item.quantity} = ¥{item.price * item.quantity}
+            <button onClick={() => removeItem(item.id)}>删除</button>
+          </li>
+        ))}
+      </ul>
+      <p>总计: ¥{cartTotal}</p>
+    </div>
+  )
+}
+```
+
+### 只读状态
+
+对于派生状态（只读 atom），使用 `useAtomValue`：
+
+```typescript
+import { useAtomValue } from 'jotai'
+import { useContext } from 'react'
+import { ClientGlobalStateContext } from '@linyjs/client-module-interface'
+
+function CartBadge() {
+  const atoms = useContext(ClientGlobalStateContext)
+  const cartCountAtom = atoms['shopClient.cartState.cartCount']
+
+  // 只读取，不需要 setter
+  const count = useAtomValue(cartCountAtom)
+
+  return <span className="badge">{count}</span>
+}
+```
+
+### 只写状态
+
+如果只需要修改状态而不需要读取当前值，使用 `useSetAtom`：
+
+```typescript
+import { useSetAtom } from 'jotai'
+import { useContext } from 'react'
+import { ClientGlobalStateContext } from '@linyjs/client-module-interface'
+
+function AddToCartButton({ product }: { product: { id: string; name: string; price: number } }) {
+  const atoms = useContext(ClientGlobalStateContext)
+  const cartItemsAtom = atoms['shopClient.cartState.cartItems']
+
+  // 只获取 setter，不订阅状态变化
+  const setCartItems = useSetAtom(cartItemsAtom)
+
+  const handleAdd = () => {
+    setCartItems(items => [...items, { ...product, quantity: 1 }])
+  }
+
+  return <button onClick={handleAdd}>加入购物车</button>
+}
+```
+
+---
+
+## 跨模块状态访问
+
+全局状态的核心优势是跨模块共享。任何模块的组件都可以读取其他模块注册的状态。
+
+### 示例场景
+
+假设 `authClient` 模块注册了用户状态，`shopClient` 模块需要读取用户信息：
+
+```typescript
+// authClient 模块注册的状态
+// key: authClient.authState.user
+class AuthStateService implements IGlobalStateService {
+  atoms = {
+    user: atom<{ id: string; name: string; roles: string[] } | null>(null)
+  }
+}
+```
+
+```typescript
+// shopClient 模块的组件读取 authClient 的用户状态
+import { useContext } from 'react'
+import { useAtomValue } from 'jotai'
+import { ClientGlobalStateContext } from '@linyjs/client-module-interface'
+
+function CheckoutPage() {
+  const atoms = useContext(ClientGlobalStateContext)
+
+  // ✅ 跨模块读取：使用完整的三段式 key
+  const userAtom = atoms['authClient.authState.user']
+  const user = useAtomValue(userAtom)
+
+  if (!user) {
+    return <div>请先登录</div>
+  }
+
+  return <div>结账 - 用户: {user.name}</div>
+}
+```
+
+### 封装自定义 Hook
+
+为避免在多个组件中重复 `useContext` + `useAtom` 的样板代码，建议封装自定义 Hook：
+
+```typescript
+import { useContext } from 'react'
+import { useAtom, useAtomValue, useSetAtom } from 'jotai'
+import { ClientGlobalStateContext, type IAtom } from '@linyjs/client-module-interface'
+
+/** 获取全局状态注册表中的 atom */
+function useGlobalAtom<T>(key: string): IAtom<T> | undefined {
+  const atoms = useContext(ClientGlobalStateContext)
+  return atoms[key] as IAtom<T> | undefined
+}
+
+/** 读取和修改全局状态 */
+function useGlobalState<T>(key: string): [T, (value: T | ((prev: T) => T)) => void] {
+  const atom = useGlobalAtom<T>(key)
+  if (!atom) {
+    throw new Error(`[useGlobalState] Atom not found: ${key}`)
+  }
+  return useAtom(atom as any)
+}
+
+/** 只读全局状态 */
+function useGlobalStateValue<T>(key: string): T {
+  const atom = useGlobalAtom<T>(key)
+  if (!atom) {
+    throw new Error(`[useGlobalStateValue] Atom not found: ${key}`)
+  }
+  return useAtomValue(atom as any)
+}
+
+/** 只写全局状态 */
+function useSetGlobalState<T>(key: string): (value: T | ((prev: T) => T)) => void {
+  const atom = useGlobalAtom<T>(key)
+  if (!atom) {
+    throw new Error(`[useSetGlobalState] Atom not found: ${key}`)
+  }
+  return useSetAtom(atom as any)
+}
+```
+
+使用封装后的 Hook：
+
+```typescript
+// 读取当前模块的状态
+const [cartItems, setCartItems] = useGlobalState<CartItem[]>('shopClient.cartState.cartItems')
+const cartTotal = useGlobalStateValue<number>('shopClient.cartState.cartTotal')
+
+// 跨模块读取
+const user = useGlobalStateValue<User | null>('authClient.authState.user')
+```
+
+---
+
+## 封装为公共 Hook 注册
+
+如果希望将状态消费逻辑封装为可复用的 Hook，可以通过 `IHooksService` 注册，供其他模块通过 `useClientHook` 消费：
+
+```typescript
+import { atom, useAtomValue, useSetAtom } from 'jotai'
+import { useContext } from 'react'
+import type {
+  IModule,
+  IGlobalStateService,
+  IGlobalStateDef,
+  IHooksService,
+  IHooksDef,
+} from '@linyjs/client-module-interface'
+import { ClientGlobalStateContext } from '@linyjs/client-module-interface'
+
+// ==================== 状态定义 ====================
+
+const userAtom = atom<{ id: string; name: string } | null>(null)
+
+class AuthStateService implements IGlobalStateService {
+  atoms = { user: userAtom }
+}
+
+const authStateDef: IGlobalStateDef = {
+  serviceTag: 'authState',
+  serviceImpl: AuthStateService,
+  meta: { usageType: 'global_state' },
+}
+
+// ==================== 封装 Hook ====================
+
+function useAuthUser() {
+  const atoms = useContext(ClientGlobalStateContext)
+  const userAtom = atoms['authClient.authState.user']
+  return useAtomValue(userAtom)
+}
+
+function useSetAuthUser() {
+  const atoms = useContext(ClientGlobalStateContext)
+  const userAtom = atoms['authClient.authState.user']
+  return useSetAtom(userAtom)
+}
+
+// ==================== Hook 注册 ====================
+
+class AuthHooksService implements IHooksService {
+  hooks = {
+    useAuthUser,
+    useSetAuthUser,
+  }
+}
+
+const authHooksDef: IHooksDef = {
+  serviceTag: 'authHooks',
+  serviceImpl: AuthHooksService,
+  meta: { usageType: 'hook' },
+}
+
+// ==================== 模块声明 ====================
+
+export const authClientModule: IModule = {
+  name: 'authClient',
+  serviceDefs: [authStateDef, authHooksDef],
+}
+```
+
+其他模块通过 `useClientHook` 消费：
+
+```typescript
+import { useClientHook } from '@linyjs/client-module-interface'
+
+type UseAuthUser = () => { id: string; name: string } | null
+
+function NavBar() {
+  const useAuthUser = useClientHook<UseAuthUser>('authClient.authHooks.useAuthUser')
+
+  if (!useAuthUser) return null
+
+  const user = useAuthUser()
+
+  return <span>{user ? user.name : '未登录'}</span>
+}
+```
+
+> 📖 关于 `useClientHook` 的详细用法，请阅读 [公共 Hooks 使用](./client-hooks.md)。
+
+---
+
+## SSR 注意事项
+
+### Context 自动提供
+
+在 SSR 模式下，框架的 SSR 中间件会自动将 atoms 注册表通过 `ClientGlobalStateContext.Provider` 提供给组件树：
+
+```typescript
+// 框架内部实现（简化）
+createElement(
+  ClientGlobalStateContext.Provider,
+  { value: registries.atoms },  // 所有模块的 atoms 注册表
+  contentElement
+)
+```
+
+客户端 hydration 时同样会提供 Context，确保 SSR 和 CSR 行为一致。
+
+### SSR 中的状态读取
+
+SSR 渲染时，atoms 使用初始值（`atom(initialValue)` 的参数）。如果需要 SSR 时从服务端获取数据，请使用路由的 `loader` 预加载数据，而非异步 atom：
+
+```typescript
+// ✅ 推荐：使用 loader 预加载数据（SSR 友好）
+{
+  path: '/dashboard',
+  component: Dashboard,
+  key: 'dashboard',
+  loader: async () => {
+    const res = await fetch('/api/dashboard/stats')
+    return { stats: await res.json() }
+  }
+}
+
+// ⚠️ 注意：异步 atom 在 SSR 中可能不会完成请求
+const statsAtom = atom(async () => {
+  const res = await fetch('/api/dashboard/stats')
+  return res.json()
+})
+```
+
+> 📖 关于路由 Loader 的详细用法，请阅读 [前端页面路由](./client-routes.md)。
+
+---
+
+## 最佳实践
+
+### 1. 按领域拆分状态
+
+将不同领域的状态放在不同的 ServiceDef 中，保持职责清晰：
+
+```typescript
+// ✅ 好的做法：按领域拆分
+class UserStateService implements IGlobalStateService {
+  atoms = { user: userAtom, isLoggedIn: isLoggedInAtom }
+}
+
+class ThemeStateService implements IGlobalStateService {
+  atoms = { theme: themeAtom, fontSize: fontSizeAtom }
+}
+
+class CartStateService implements IGlobalStateService {
+  atoms = { cartItems: cartItemsAtom, cartTotal: cartTotalAtom }
+}
+```
+
+### 2. 使用派生状态避免冗余
+
+不要在多个 atom 中存储相同的数据，使用派生状态从源头计算：
+
+```typescript
+// ✅ 好的做法：单一数据源 + 派生状态
+const cartItemsAtom = atom<CartItem[]>([])
+const cartTotalAtom = atom((get) =>
+  get(cartItemsAtom).reduce((sum, i) => sum + i.price * i.quantity, 0)
+)
+const cartCountAtom = atom((get) =>
+  get(cartItemsAtom).reduce((sum, i) => sum + i.quantity, 0)
+)
+
+// ❌ 避免：在多个 atom 中存储冗余数据
+const cartItemsAtom = atom<CartItem[]>([])
+const cartTotalAtom = atom(0)  // 需要手动同步，容易出错
+const cartCountAtom = atom(0)  // 需要手动同步，容易出错
+```
+
+### 3. 为 atom 命名时使用清晰的名称
+
+注册表 key 由 `moduleName.serviceTag.atomName` 组成，确保 atom 名具有描述性：
+
+```typescript
+// ✅ 好的命名
+atoms = {
+  currentUser: userAtom,         // shopClient.shopState.currentUser
+  cartItems: cartItemsAtom,      // shopClient.shopState.cartItems
+  selectedCategoryId: categoryAtom, // shopClient.shopState.selectedCategoryId
+}
+
+// ❌ 避免模糊的命名
+atoms = {
+  data: dataAtom,      // 什么 data？
+  value: valueAtom,    // 什么 value？
+  state: stateAtom,    // 什么 state？
+}
+```
+
+### 4. 处理 atom 未找到的情况
+
+从注册表获取 atom 时，可能因为模块未加载或 key 拼写错误导致获取到 `undefined`：
+
+```typescript
+function CartBadge() {
+  const atoms = useContext(ClientGlobalStateContext)
+  const cartCountAtom = atoms['shopClient.cartState.cartCount']
+
+  // ✅ 始终检查 atom 是否存在
+  if (!cartCountAtom) {
+    return <span className="badge">0</span>
+  }
+
+  const count = useAtomValue(cartCountAtom)
+  return <span className="badge">{count}</span>
+}
+```
+
+### 5. 避免在渲染期间创建 atom
+
+atom 应在模块顶层创建，不要在组件内部或 ServiceDef 的方法中动态创建：
+
+```typescript
+// ✅ 好的做法：在模块顶层创建
+const userAtom = atom(null)
+
+class MyStateService implements IGlobalStateService {
+  atoms = { user: userAtom }
+}
+
+// ❌ 避免：在组件内部创建（每次渲染都会创建新 atom）
+function MyComponent() {
+  const dataAtom = atom(null)  // 错误！
+  const [data] = useAtom(dataAtom)
+}
+```
+
+### 6. 遵循 ServiceDef 代码风格规范
+
+> 📐 **重要**: ServiceDef 必须声明为独立变量，禁止内联在 `serviceDefs` 数组中。详见 [ServiceDef 代码风格规范](../best-practices/service-definition.md)。
+
+```typescript
+// ✅ 好的做法：独立变量声明
+const myStateDef: IGlobalStateDef = {
+  serviceTag: 'myState',
+  serviceImpl: MyStateService,
+  meta: { usageType: 'global_state' },
+}
+
+export const myModule: IModule = {
+  name: 'myClient',
+  serviceDefs: [myStateDef],
+}
+
+// ❌ 避免：内联声明
+export const myModule: IModule = {
+  name: 'myClient',
+  serviceDefs: [
+    { serviceTag: 'myState', serviceImpl: MyStateService, meta: { usageType: 'global_state' } }
+  ],
+}
+```
+
+---
+
+## 完整示例
+
+以下示例展示一个主题管理模块，包含状态定义、消费组件和跨模块共享：
+
+```typescript
+// theme-client-module.ts
+import { atom, useAtom } from 'jotai'
+import { useContext } from 'react'
+import type {
+  IModule,
+  IGlobalStateService,
+  IGlobalStateDef,
+} from '@linyjs/client-module-interface'
+import { ClientGlobalStateContext } from '@linyjs/client-module-interface'
+
+// ==================== 类型定义 ====================
+
+type Theme = 'light' | 'dark'
+
+interface ThemeState {
+  theme: Theme
+  fontSize: number
+  sidebarCollapsed: boolean
+}
+
+// ==================== 状态定义 ====================
+
+const themeStateAtom = atom<ThemeState>({
+  theme: 'light',
+  fontSize: 14,
+  sidebarCollapsed: false,
+})
+
+// 派生状态
+const isDarkThemeAtom = atom((get) => get(themeStateAtom).theme === 'dark')
+
+// 可写派生状态
+const toggleThemeAtom = atom(
+  (get) => get(themeStateAtom).theme,
+  (get, set) => {
+    const current = get(themeStateAtom)
+    set(themeStateAtom, {
+      ...current,
+      theme: current.theme === 'light' ? 'dark' : 'light',
+    })
+  }
+)
+
+// ==================== 状态服务 ====================
+
+class ThemeStateService implements IGlobalStateService {
+  atoms = {
+    themeState: themeStateAtom,
+    isDarkTheme: isDarkThemeAtom,
+    toggleTheme: toggleThemeAtom,
+  }
+}
+
+const themeStateDef: IGlobalStateDef = {
+  serviceTag: 'themeState',
+  serviceImpl: ThemeStateService,
+  meta: { usageType: 'global_state' },
+}
+
+export const themeClientModule: IModule = {
+  name: 'themeClient',
+  serviceDefs: [themeStateDef],
+}
+
+// ==================== 消费组件 ====================
+
+// 主题切换按钮（同模块消费）
+function ThemeToggle() {
+  const atoms = useContext(ClientGlobalStateContext)
+  const toggleThemeAtom = atoms['themeClient.themeState.toggleTheme']
+
+  const [theme, toggle] = useAtom(toggleThemeAtom)
+
+  return (
+    <button onClick={toggle}>
+      {theme === 'light' ? '🌙 深色模式' : '☀️ 浅色模式'}
+    </button>
+  )
+}
+
+// 布局组件（跨模块消费，读取主题状态）
+function AdminLayout({ children }: { children: React.ReactNode }) {
+  const atoms = useContext(ClientGlobalStateContext)
+  const isDarkAtom = atoms['themeClient.themeState.isDarkTheme']
+  const themeStateAtom = atoms['themeClient.themeState.themeState']
+
+  const isDark = useAtomValue(isDarkAtom)
+  const themeState = useAtomValue(themeStateAtom)
+
+  return (
+    <div style={{
+      backgroundColor: isDark ? '#1a1a1a' : '#ffffff',
+      color: isDark ? '#ffffff' : '#000000',
+      fontSize: `${themeState.fontSize}px`,
+    }}>
+      <Sidebar collapsed={themeState.sidebarCollapsed} />
+      <main>{children}</main>
+    </div>
+  )
+}
+```
+
+---
+
+## ⚠️ 构建注意事项：Jotai 由宿主提供
+
+Jotai 与 React 一样，**必须由宿主环境统一提供**，插件打包时不应该将 Jotai 打包进 bundle。
+
+CLI 默认已将 `jotai` 设为 external，无需额外配置。宿主 SSR 应用通过 Import Map 提供全局 Jotai 实例：
+
+```html
+<script type="importmap">
+{
+  "imports": {
+    "react": "/client/vendor/react.js",
+    "react-dom": "/client/vendor/react-dom.js",
+    "jotai": "/client/vendor/jotai.js"
+  }
+}
+</script>
+```
+
+**为什么 Jotai 必须 external？**
+
+所有插件必须共享同一个 Jotai 实例。如果每个插件打包自己的 Jotai，则：
+- 一个插件创建的 `atom()` 无法被另一个插件的 `useAtom()` 识别
+- `ClientGlobalStateContext` 中注册的全局 atom 无法跨模块消费
+- Store 实例隔离，状态互不可见
+
+
+---
+
+## 相关文档
+
+- 💻 [客户端模块开发](./client-module.md) — 模块结构总览
+- 🪝 [公共 Hooks 使用](./client-hooks.md) — `useClientHook` 获取跨模块 Hook
+- 🛤️ [前端页面路由](./client-routes.md) — 路由 Loader 预加载数据
+- 🔧 [API 参考](../api-reference/index.md) — `IGlobalStateService`、`IAtom` 接口定义
+
+---
+
+**上一篇**: [公共 Hooks 使用](./client-hooks.md) | **下一篇**: [UI 扩展插槽](./ui-slots.md)