@linyjs/plugin-docs 0.0.13

package/examples/hello-world/node_modules/@linyjs/client-module-interface/IMPLEMENTATION_SUMMARY.md

@@ -0,0 +1,166 @@
+# 实现总结
+
+## 已完成的工作
+
+### 1. 核心 Hook 实现
+
+在 `packages/client-module-interface/src/hooks.ts` 中实现了三个资源消费 Hook：
+
+#### useClientComponent
+- 从 `ClientComponentsContext` 获取 React 组件
+- 支持跨模块引用（完整路径）和模块内引用（短路径）
+- 提供类型安全的泛型参数 `<P = any>`
+- 找不到组件时返回 `undefined` 并输出警告
+
+#### useClientHook
+- 从 `ClientHooksContext` 获取自定义 Hook
+- 支持泛型类型约束 `<T extends Function>`
+- 找不到 Hook 时返回 `undefined` 并输出警告
+
+#### useClientService
+- 从 `ClientServicesContext` 获取服务实例
+- 支持泛型类型约束 `<T = any>`
+- 找不到服务时返回 `undefined` 并输出警告
+
+### 2. 路径解析机制
+
+实现了 `resolveRegistryKey` 函数，支持两种引用格式：
+
+- **跨模块引用**：`'moduleName.serviceTag.name'` → 直接使用
+- **模块内引用**：`'serviceTag.name'` → 需要补全模块名（当前版本暂不支持自动补全）
+
+### 3. 导出配置
+
+在 `src/index.ts` 中导出了所有三个 Hook：
+
+```typescript
+export {
+  useClientComponent,
+  useClientHook,
+  useClientService,
+} from './hooks.js'
+```
+
+### 4. 文档和示例
+
+创建了以下文档文件：
+
+- **README.md** - 包的整体说明和使用指南
+- **HOOKS_USAGE.md** - Hooks 的详细使用指南和最佳实践
+- **hooks-example.tsx** - 完整的使用示例代码
+
+## 设计特点
+
+### 1. 符合设计规范
+
+严格按照 [前端模块接口设计.md](../../spec/前端模块接口设计.md) 第 159-200 行的要求实现：
+
+- ✅ 支持模块内引用和跨模块引用
+- ✅ 使用 React Context 消费资源
+- ✅ 遵循 RegistryKey 命名规范
+- ✅ 提供类型安全的泛型接口
+
+### 2. 类型安全
+
+所有 Hook 都支持泛型参数，确保类型安全：
+
+```typescript
+// 组件
+const Avatar = useClientComponent<UserAvatarProps>('...')
+
+// Hook
+const useAuth = useClientHook<UseAuthHookType>('...')
+
+// 服务
+const userService = useClientService<IUserService>('...')
+```
+
+### 3. 错误处理
+
+- 资源未找到时返回 `undefined` 而非抛出异常
+- 输出清晰的警告信息，便于调试
+- 允许调用方进行优雅降级处理
+
+### 4. 可扩展性
+
+预留了 `useCurrentModuleName` Hook 的实现位置，未来可以通过 `ModuleContext` 自动获取当前模块名，实现真正的模块内短路径引用。
+
+## 文件结构
+
+```
+packages/client-module-interface/
+├── src/
+│   ├── hooks.ts              # 核心 Hook 实现
+│   ├── hooks-example.tsx     # 使用示例
+│   ├── index.ts              # 导出配置（已更新）
+│   └── ...其他文件
+├── dist/                     # 编译输出
+│   ├── hooks.js
+│   ├── hooks.d.ts
+│   └── ...其他文件
+├── README.md                 # 包说明文档
+└── HOOKS_USAGE.md           # Hooks 使用指南
+```
+
+## 使用方式
+
+### 基本用法
+
+```typescript
+import { 
+  useClientComponent, 
+  useClientHook, 
+  useClientService 
+} from '@ling/client-module-interface'
+
+function MyComponent() {
+  // 获取组件
+  const Avatar = useClientComponent('userModule.userComponents.Avatar')
+  
+  // 获取 Hook
+  type UseAuthHook = () => { isAuthenticated: boolean }
+  const useAuth = useClientHook<UseAuthHook>('authModule.authHooks.useAuth')
+  
+  // 获取服务
+  const userService = useClientService<IUserService>('userModule.userService')
+  
+  return (
+    <div>
+      {Avatar && <Avatar userId="123" />}
+    </div>
+  )
+}
+```
+
+## 与现有代码的集成
+
+这些 Hook 可以与现有的 SSR 演示项目无缝集成。例如，在 `packages/ssr/src/demo/client-modules.tsx` 中，可以这样使用：
+
+```typescript
+// 之前：直接使用 useContext
+const components = useContext(ClientComponentsContext)
+const Avatar = components['userModule.userComponents.Avatar']
+
+// 现在：使用 Hook（更简洁）
+const Avatar = useClientComponent('userModule.userComponents.Avatar')
+```
+
+## 后续改进建议
+
+1. **实现 ModuleContext**：添加 `ModuleContext` 来跟踪当前模块，实现真正的模块内短路径引用
+2. **添加缓存机制**：对查找结果进行缓存，提升性能
+3. **支持懒加载**：支持按需加载模块和资源
+4. **添加 DevTools 支持**：提供开发者工具，方便调试资源注册和消费
+
+## 测试建议
+
+虽然本次实现未包含单元测试，但建议后续添加：
+
+1. Hook 返回值测试
+2. 路径解析逻辑测试
+3. 空值处理测试
+4. 类型安全检查测试
+
+## 总结
+
+本次实现完成了 `client-module-interface` 包中的三个核心 Hook，使开发者能够方便地在模块中消费注册的资源。实现严格遵循设计文档，提供了类型安全、错误处理和良好的开发体验。

package/examples/hello-world/node_modules/@linyjs/client-module-interface/QUICK_REFERENCE.md

@@ -0,0 +1,130 @@
+# 快速参考
+
+## 导入
+
+```typescript
+import { 
+  useClientComponent, 
+  useClientHook, 
+  useClientService 
+} from '@ling/client-module-interface'
+```
+
+## API 速查
+
+### useClientComponent
+
+```typescript
+const Component = useClientComponent<PropsType>('moduleName.serviceTag.componentName')
+```
+
+**参数**：`refPath: string` - 组件的 RegistryKey  
+**返回**：`IComponent<PropsType> | undefined`
+
+**示例**：
+```typescript
+const Avatar = useClientComponent('userModule.userComponents.Avatar')
+// 使用
+{Avatar && <Avatar userId="123" />}
+```
+
+---
+
+### useClientHook
+
+```typescript
+const hook = useClientHook<HookType>('moduleName.serviceTag.hookName')
+```
+
+**参数**：`refPath: string` - Hook 的 RegistryKey  
+**返回**：`HookType | undefined`
+
+**示例**：
+```typescript
+type UseAuthHook = () => { isAuthenticated: boolean }
+const useAuth = useClientHook<UseAuthHook>('authModule.authHooks.useAuth')
+// 使用
+const authState = useAuth ? useAuth() : null
+```
+
+---
+
+### useClientService
+
+```typescript
+const service = useClientService<ServiceType>('moduleName.serviceTag')
+```
+
+**参数**：`refPath: string` - 服务的 RegistryKey  
+**返回**：`ServiceType | undefined`
+
+**示例**：
+```typescript
+interface IUserService {
+  getUser(id: string): Promise<User>
+}
+const userService = useClientService<IUserService>('userModule.userService')
+// 使用
+if (userService) {
+  const user = await userService.getUser('123')
+}
+```
+
+---
+
+## RegistryKey 格式
+
+| 资源类型 | 格式 | 示例 |
+|---------|------|------|
+| 组件 | `moduleName.serviceTag.componentName` | `'userModule.userComponents.Avatar'` |
+| Hook | `moduleName.serviceTag.hookName` | `'authModule.authHooks.useAuth'` |
+| 服务 | `moduleName.serviceTag` | `'userModule.userService'` |
+| 全局状态 | `moduleName.serviceTag.atomName` | `'userModule.userState.user'` |
+
+---
+
+## 注意事项
+
+✅ **必须做**：
+- 进行空值检查（返回值可能是 `undefined`）
+- 使用泛型提供类型约束
+- 使用完整的 RegistryKey（包含 moduleName）
+
+❌ **不要做**：
+- 忽略空值检查
+- 在循环中调用 Hook
+- 硬编码魔法字符串
+
+---
+
+## 常见模式
+
+### 条件渲染
+```typescript
+const Avatar = useClientComponent('...')
+return Avatar ? <Avatar /> : <Fallback />
+```
+
+### 错误处理
+```typescript
+const service = useClientService<IMyService>('...')
+if (!service) {
+  console.error('Service not found')
+  return null
+}
+```
+
+### 混合使用
+```typescript
+const Component = useClientComponent('...')
+const hook = useClientHook<HookType>('...')
+const service = useClientService<ServiceType>('...')
+```
+
+---
+
+## 更多信息
+
+- 📖 [完整使用指南](./HOOKS_USAGE.md)
+- 📝 [使用示例](./src/hooks-example.tsx)
+- 📋 [包说明](./README.md)

package/examples/hello-world/node_modules/@linyjs/client-module-interface/README.md

@@ -0,0 +1,214 @@
+# @ling/client-module-interface
+
+前端模块接口定义包，提供插件式架构所需的类型定义和工具函数。
+
+## 安装
+
+```bash
+npm install @ling/client-module-interface
+```
+
+## 核心功能
+
+### 1. 依赖注入类型
+
+- `IModule` - 模块定义
+- `IServiceDef` - 服务定义
+- `IModuleHandler` - 模块生命周期处理器
+- `IModuleContainer` - 模块容器
+
+### 2. 前端领域类型
+
+- `IComponent` - React 组件类型
+- `IRoute` - 路由定义
+- `IRouteGuard` - 路由守卫
+- `IRouteLoader` - 路由数据加载器
+
+### 3. 服务接口
+
+- `IRouteService` - 路由服务
+- `IGlobalStateService` - 全局状态服务（jotai atoms）
+- `IComponentListService` - 组件列表服务
+- `IHooksService` - Hooks 服务
+
+### 4. 资源消费 Hooks ⭐
+
+#### useClientComponent
+
+从全局注册表中获取 React 组件。
+
+```typescript
+import { useClientComponent } from '@ling/client-module-interface'
+
+// 跨模块引用
+const Avatar = useClientComponent('userModule.userComponents.Avatar')
+
+// 在组件中使用
+function UserProfile() {
+  return (
+    <div>
+      {Avatar && <Avatar userId="123" size="large" />}
+    </div>
+  )
+}
+```
+
+#### useClientHook
+
+从全局注册表中获取自定义 Hook。
+
+```typescript
+import { useClientHook } from '@ling/client-module-interface'
+
+// 跨模块引用
+type UseAuthHook = () => { isAuthenticated: boolean; user: any }
+const useAuth = useClientHook<UseAuthHook>('authModule.authHooks.useAuth')
+
+// 在组件中使用
+function AuthStatus() {
+  const authState = useAuth ? useAuth() : null
+  
+  return (
+    <div>
+      {authState?.isAuthenticated ? '已登录' : '未登录'}
+    </div>
+  )
+}
+```
+
+#### useClientService
+
+从全局注册表中获取服务实例。
+
+```typescript
+import { useClientService } from '@ling/client-module-interface'
+
+interface IUserService {
+  getUser(id: string): Promise<User>
+  updateUser(id: string, data: Partial<User>): Promise<void>
+}
+
+// 跨模块引用
+const userService = useClientService<IUserService>('userModule.userService')
+
+// 在组件中使用
+function UserManagement() {
+  const handleLoadUser = async () => {
+    if (userService) {
+      const user = await userService.getUser('123')
+      console.log(user)
+    }
+  }
+  
+  return <button onClick={handleLoadUser}>加载用户</button>
+}
+```
+
+### 5. React Context
+
+- `ClientComponentsContext` - 组件注册表 Context
+- `ClientGlobalStateContext` - 全局状态 Context（jotai atoms）
+- `ClientServicesContext` - 服务注册表 Context
+- `ClientHooksContext` - Hooks 注册表 Context
+
+## 引用规则
+
+### 模块内引用 vs 跨模块引用
+
+| 资源类型 | 模块内引用 | 跨模块引用 |
+|---------|-----------|-----------|
+| 组件 | `serviceTag.componentName` | `moduleName.serviceTag.componentName` |
+| Hook | `serviceTag.hookName` | `moduleName.serviceTag.hookName` |
+| 服务 | `serviceTag` | `moduleName.serviceTag` |
+| 全局状态 | `serviceTag.atomName` | `moduleName.serviceTag.atomName` |
+
+**注意**：当前版本中，模块内引用需要显式传递完整路径（包含 moduleName），未来会通过 ModuleContext 自动获取当前模块名。
+
+### RegistryKey 格式
+
+- 组件：`moduleName.serviceTag.componentName`
+  - 示例：`'userModule.userComponents.Avatar'`
+- Hook：`moduleName.serviceTag.hookName`
+  - 示例：`'authModule.authHooks.useAuth'`
+- 服务：`moduleName.serviceTag`
+  - 示例：`'userModule.userService'`
+- 全局状态：`moduleName.serviceTag.atomName`
+  - 示例：`'userModule.userState.user'`
+
+## 最佳实践
+
+### 1. 类型安全
+
+使用泛型参数为服务和 Hook 提供类型约束：
+
+```typescript
+// ✅ 推荐
+const userService = useClientService<IUserService>('userModule.userService')
+const useAuth = useClientHook<UseAuthHook>('authModule.authHooks.useAuth')
+
+// ❌ 不推荐（失去类型检查）
+const userService = useClientService('userModule.userService')
+```
+
+### 2. 空值检查
+
+所有 Hook 都可能返回 `undefined`（资源未找到时），使用前应该进行空值检查：
+
+```typescript
+const Avatar = useClientComponent('userModule.userComponents.Avatar')
+
+// ✅ 推荐：空值检查
+if (Avatar) {
+  return <Avatar userId="123" />
+}
+
+// ✅ 推荐：可选链
+return Avatar ? <Avatar userId="123" /> : null
+```
+
+### 3. 命名规范
+
+- **组件**：PascalCase，如 `Avatar`、`UserProfile`
+- **Hook**：camelCase 且以 `use` 开头，如 `useAuth`、`useUser`
+- **服务**：camelCase，如 `userService`、`apiService`
+
+### 4. 模块设计
+
+每个模块应该明确声明提供的服务类型：
+
+```typescript
+// 组件服务
+class UserComponentService implements IComponentListService {
+  components = {
+    Avatar: UserAvatar,
+    Profile: UserProfile,
+  }
+}
+
+// Hook 服务
+class AuthHooksService implements IHooksService {
+  hooks = {
+    useAuth,
+    usePermissions,
+  }
+}
+
+// 普通服务
+class UserServiceImpl implements IUserService {
+  // ...
+}
+```
+
+## 示例项目
+
+查看 `src/hooks-example.tsx` 文件了解完整的使用示例。
+
+## 相关文档
+
+- [前端模块接口设计](../../spec/前端模块接口设计.md)
+- [前端插件式架构设计](../../spec/前端插件式架构设计.md)
+- [依赖注入机制设计](../../spec/依赖注入机制设计.md)
+
+## License
+
+MIT

package/examples/hello-world/node_modules/@linyjs/client-module-interface/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@linyjs/client-module-interface",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.1.6",
+    "react": "^19.1.0",
+    "typescript": "^5.7.0"
+  }
+}

package/examples/hello-world/node_modules/@linyjs/client-module-interface/src/application.ts

@@ -0,0 +1,50 @@
+/**
+ * 客户端应用接口
+ * 详见 [前端插件式架构设计](../../spec/前端插件式架构设计.md)
+ */
+
+import type { IModule, IModuleHandler } from './di.js'
+import type { IRoute, IComponent } from './domain.js'
+import type { IRouterAdapter } from './router.js'
+import type { IAtom } from './interfaces.js'
+
+/** 客户端注册表 */
+export interface IClientRegistries {
+  /** 路由注册表（按 basePath 前缀分组） */
+  routes: IRoute[]
+  /** 组件注册表 */
+  components: Record<string, IComponent>
+  /** 全局状态注册表（jotai atoms） */
+  atoms: Record<string, IAtom>
+  /** 服务注册表 */
+  services: Record<string, any>
+  /** Hook 注册表 */
+  hooks: Record<string, Function>
+}
+
+/** 客户端应用接口 */
+export interface IClientApplication {
+  /** 设置模块生命周期处理器 */
+  setHandler(handler: IModuleHandler): void
+
+  /** 设置路由适配器 */
+  setRouterAdapter(adapter: IRouterAdapter): void
+
+  /** 加载一组模块，按依赖拓扑排序后由容器实例化服务 */
+  loadModules(modules: IModule[]): Promise<void>
+
+  /** 获取所有注册表 */
+  getRegistries(): IClientRegistries
+
+  /** 获取 React 根组件（CSR 模式，包含路由 + Context） */
+  getReactRootElement(): import('react').JSX.Element
+
+  /** SSR 模式：hydrate 已渲染的 HTML */
+  hydrate(ssrState: { loaderData?: any }): Promise<void>
+
+  /** CSR 模式：挂载根组件到 DOM */
+  run(): Promise<void>
+
+  /** 卸载所有已加载模块 */
+  destroyAll(): Promise<void>
+}