@linyjs/plugin-docs 0.0.15 → 0.0.17

package/docs/guides/client-routes.md

@@ -0,0 +1,631 @@
+# 前端页面路由
+
+本指南详细介绍 linyjs 插件前端页面路由的完整使用方式，包括路由定义、路由参数、路由守卫、数据预加载、嵌套路由以及 `useClientRoute` 路由功能 Hook。
+
+## 概述
+
+linyjs 前端路由基于 `IRouteService` 服务接口声明，框架在模块加载时自动调用 `getRoutes()` 收集所有路由并注册到路由注册表中。路由系统采用适配器模式，底层可对接 react-router、微信小程序等不同实现，消费端代码保持不变。
+
+### 路由声明流程
+
+```
+插件客户端模块
+  └── IRouteService (usageType: 'route')
+        └── getRoutes() → IRoute[]
+              └── 框架收集到 clientResult.routes
+                    └── SSR 中间件 / CSR 路由器 匹配并渲染
+```
+
+## 路由定义
+
+### IRoute 接口
+
+每条路由是一个 `IRoute` 对象：
+
+```typescript
+interface IRoute {
+  path: string               // 路由路径（如 '/'、'/:id'、'/settings'）
+  component: IComponent      // 对应的 React 组件
+  key?: string               // 路由唯一标识（用于缓存、调试）
+  children?: IRoute[]        // 子路由（嵌套路由）
+  guard?: IRouteGuard        // 路由守卫
+  loader?: IRouteLoader      // 数据预加载函数
+  meta?: {
+    title?: string           // 页面标题
+    requiresAuth?: boolean   // 是否需要登录
+    layout?: IComponent      // 布局组件
+    [key: string]: any       // 其他自定义元数据
+  }
+}
+```
+
+### 基本路由
+
+```typescript
+import type { IRouteService, IRouteDef } from '@linyjs/client-module-interface';
+import React from 'react';
+
+function HomePage() {
+  return <div>首页内容</div>;
+}
+
+class MyRouteService implements IRouteService {
+  getRoutes() {
+    return [
+      {
+        path: '/',
+        component: HomePage,
+        key: 'home',
+        meta: { title: '首页' }
+      }
+    ];
+  }
+}
+
+const myRouteDef: IRouteDef = {
+  serviceTag: 'myRoute',
+  serviceImpl: MyRouteService,
+  meta: { usageType: 'route' }
+};
+```
+
+### basePath 路由前缀
+
+`IRouteService.basePath` 用于为所有路由添加统一前缀，避免在每个路由的 `path` 中重复书写：
+
+```typescript
+class KanbanRouteService implements IRouteService {
+  basePath = '/kanban';  // 所有路由都会自动添加 /kanban 前缀
+
+  getRoutes() {
+    return [
+      // 实际路径：/kanban
+      {
+        path: '/',
+        component: KanbanBoardPage,
+        key: 'kanban-board',
+        meta: { title: '看板' }
+      },
+      // 实际路径：/kanban/settings
+      {
+        path: '/settings',
+        component: ProjectSettingsPage,
+        key: 'kanban-settings',
+        meta: { title: '项目设置' }
+      },
+      // 实际路径：/kanban/tasks/:id
+      {
+        path: '/tasks/:id',
+        component: TaskDetailPage,
+        key: 'kanban-task-detail',
+        meta: { title: '任务详情' }
+      }
+    ];
+  }
+}
+```
+
+> 💡 **最终路径** = `basePath` + `route.path`。如果未设置 `basePath`，则最终路径就是 `route.path`。
+
+## 路由参数
+
+### 动态路由参数
+
+使用 `:paramName` 语法定义动态路由参数：
+
+```typescript
+// 路由定义
+{
+  path: '/users/:id',
+  component: UserDetail,
+  key: 'user-detail'
+}
+
+// 路由匹配：/users/42 → params = { id: '42' }
+```
+
+### 在组件中获取参数
+
+通过 `useClientRoute('useParams')` 获取路由参数：
+
+```typescript
+import { useClientRoute } from '@linyjs/client-module-interface';
+
+function UserDetail() {
+  const useParams = useClientRoute('useParams');
+  const params = useParams();
+  const { id } = params;
+
+  return <div>用户 ID: {id}</div>;
+}
+```
+
+### 多参数路由
+
+```typescript
+// 路由定义
+{
+  path: '/groups/:groupId/tasks/:taskId',
+  component: TaskDetail,
+  key: 'task-detail'
+}
+
+// 路由匹配：/groups/5/tasks/12 → params = { groupId: '5', taskId: '12' }
+
+// 组件中获取
+function TaskDetail() {
+  const useParams = useClientRoute('useParams');
+  const { groupId, taskId } = useParams();
+
+  return <div>分组 {groupId} 的任务 {taskId}</div>;
+}
+```
+
+## 路由守卫（Guard）
+
+路由守卫用于在进入或离开路由前进行权限校验。
+
+### IRouteGuard 接口
+
+```typescript
+interface IRouteGuard {
+  /** 进入前校验，返回 false 阻止进入，返回 string 重定向到该路径 */
+  canEnter?(params: { location: Location }): boolean | string | Promise<boolean | string>
+  /** 离开前校验 */
+  canLeave?(params: { location: Location }): boolean | Promise<boolean>
+}
+```
+
+### 使用示例
+
+```typescript
+class AuthGuard implements IRouteGuard {
+  async canEnter({ location }) {
+    // 检查用户是否已登录
+    const token = localStorage.getItem('token');
+    if (!token) {
+      return '/login';  // 未登录，重定向到登录页
+    }
+    return true;  // 允许进入
+  }
+
+  async canLeave({ location }) {
+    // 编辑页面离开前确认
+    if (location.pathname.includes('/edit')) {
+      return confirm('有未保存的更改，确定要离开吗？');
+    }
+    return true;
+  }
+}
+
+// 在路由中使用
+{
+  path: '/admin',
+  component: AdminPanel,
+  key: 'admin',
+  guard: new AuthGuard(),
+  meta: { title: '管理后台', requiresAuth: true }
+}
+```
+
+### 守卫返回值
+
+| 返回值 | 行为 |
+|--------|------|
+| `true` | 允许导航 |
+| `false` | 阻止导航 |
+| `string`（路径） | 重定向到该路径 |
+| `Promise<boolean \| string>` | 异步校验，完成后按上述规则处理 |
+
+## 数据预加载（Loader）
+
+Loader 允许在渲染组件前预加载数据，适用于 SSR 和 CSR 两种模式。
+
+### IRouteLoader 类型
+
+```typescript
+type IRouteLoader = (params: {
+  request?: Request              // SSR 模式下的请求对象
+  params: Record<string, string> // 路由参数
+  location: Location             // 当前位置信息
+}) => Promise<any> | any
+```
+
+### 使用示例
+
+```typescript
+function ArticleList({ loaderData }: { loaderData?: any }) {
+  const { articles } = loaderData || { articles: [] };
+
+  return (
+    <div>
+      {articles.map(article => (
+        <div key={article._id}>{article.title}</div>
+      ))}
+    </div>
+  );
+}
+
+// 路由定义
+{
+  path: '/articles',
+  component: ArticleList,
+  key: 'article-list',
+  loader: async ({ params }) => {
+    const res = await fetch('/api/articles');
+    const data = await res.json();
+    return { articles: data };
+  }
+}
+```
+
+### SSR 中的 Loader
+
+在 SSR 模式下，框架会在服务端执行 `loader` 函数，并将返回的数据序列化到 HTML 中，客户端 hydrate 时直接使用，避免重复请求：
+
+```typescript
+{
+  path: '/articles/:id',
+  component: ArticleDetail,
+  key: 'article-detail',
+  loader: async ({ params }) => {
+    // SSR 时在服务端执行，客户端直接复用结果
+    const res = await fetch(`https://localhost:3578/api/articles/${params.id}`);
+    return { article: await res.json() };
+  }
+}
+```
+
+## 嵌套路由
+
+嵌套路由允许在父路由的组件内渲染子路由。
+
+### 定义嵌套路由
+
+```typescript
+class BlogRouteService implements IRouteService {
+  basePath = '/blog';
+
+  getRoutes() {
+    return [
+      {
+        path: '/',
+        component: BlogLayout,  // 布局组件，包含 <Outlet /> 或子路由渲染区域
+        key: 'blog-layout',
+        children: [
+          {
+            path: '',
+            component: ArticleList,  // /blog
+            key: 'article-list'
+          },
+          {
+            path: ':id',
+            component: ArticleDetail,  // /blog/:id
+            key: 'article-detail'
+          }
+        ]
+      }
+    ];
+  }
+}
+```
+
+### 路由匹配规则
+
+对于嵌套路由，框架会递归匹配。最终路径 = `basePath` + `parentPath` + `childPath`：
+
+```
+basePath = '/blog'
+parent.path = '/'
+child.path = ':id'
+
+→ 最终匹配路径：/blog/:id
+```
+
+## meta 元数据
+
+`meta` 字段允许为路由附加自定义元数据：
+
+### 标准字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `title` | `string` | 页面标题，框架会自动设置 `<title>` |
+| `requiresAuth` | `boolean` | 是否需要登录才能访问 |
+| `layout` | `IComponent` | 布局组件，包裹在页面组件外层 |
+
+### 自定义字段
+
+```typescript
+{
+  path: '/dashboard',
+  component: Dashboard,
+  key: 'dashboard',
+  meta: {
+    title: '仪表盘',
+    requiresAuth: true,
+    icon: '📊',           // 自定义：菜单图标
+    order: 10,            // 自定义：菜单排序
+    permission: 'dashboard:view'  // 自定义：权限标识
+  }
+}
+```
+
+### layout 布局组件
+
+通过 `meta.layout` 指定布局组件，框架会将页面组件作为 children 传入：
+
+```typescript
+function AdminLayout({ children, currentPage, pages }: {
+  children: React.ReactNode;
+  currentPage?: any;
+  pages?: any[];
+}) {
+  return (
+    <div className="admin-layout">
+      <aside className="sidebar">{/* 侧边栏 */}</aside>
+      <main className="content">{children}</main>
+    </div>
+  );
+}
+
+// 路由定义
+{
+  path: '/admin',
+  component: AdminPage,
+  key: 'admin',
+  meta: {
+    title: '管理后台',
+    layout: AdminLayout  // 指定布局组件
+  }
+}
+```
+
+## useClientRoute — 路由功能 Hook
+
+框架通过 `useClientRoute` 统一暴露路由相关的组件和 Hooks，确保切换路由适配器后消费端代码不变。
+
+### 可用的 Key
+
+| Key | 返回类型 | 说明 |
+|-----|----------|------|
+| `'NavLink'` | `React.ComponentType` | 导航链接组件（支持 active 状态） |
+| `'Link'` | `React.ComponentType` | 普通链接组件 |
+| `'useNavigate'` | `() => (to, options?) => void` | 编程式导航 Hook |
+| `'useParams'` | `() => Record<string, string>` | 获取路由参数 Hook |
+| `'useLocation'` | `() => Location` | 获取当前位置 Hook |
+| `'useSearchParams'` | `() => [URLSearchParams, setter]` | 获取查询参数 Hook |
+
+### 使用示例
+
+#### NavLink 导航链接
+
+```typescript
+import { useClientRoute } from '@linyjs/client-module-interface';
+
+function NavBar() {
+  const NavLink = useClientRoute('NavLink');
+
+  return (
+    <nav>
+      <NavLink to="/" end>首页</NavLink>
+      <NavLink to="/articles">文章</NavLink>
+      <NavLink to="/kanban">看板</NavLink>
+    </nav>
+  );
+}
+```
+
+#### 编程式导航
+
+```typescript
+import { useClientRoute } from '@linyjs/client-module-interface';
+
+function LoginForm() {
+  const useNavigate = useClientRoute('useNavigate');
+  const navigate = useNavigate();
+
+  const handleLogin = async () => {
+    // 登录逻辑...
+    if (success) {
+      navigate('/dashboard');           // 导航到仪表盘
+      // navigate('/dashboard', { replace: true });  // 替换历史记录
+    }
+  };
+
+  return <button onClick={handleLogin}>登录</button>;
+}
+```
+
+#### 获取路由参数
+
+```typescript
+import { useClientRoute } from '@linyjs/client-module-interface';
+
+function ArticleDetail() {
+  const useParams = useClientRoute('useParams');
+  const { id } = useParams();
+
+  return <div>文章 ID: {id}</div>;
+}
+```
+
+#### 获取当前位置
+
+```typescript
+import { useClientRoute } from '@linyjs/client-module-interface';
+
+function Breadcrumb() {
+  const useLocation = useClientRoute('useLocation');
+  const location = useLocation();
+
+  return <span>当前路径: {location.pathname}</span>;
+}
+```
+
+#### 获取查询参数
+
+```typescript
+import { useClientRoute } from '@linyjs/client-module-interface';
+
+function ArticleList() {
+  const useSearchParams = useClientRoute('useSearchParams');
+  const [searchParams, setSearchParams] = useSearchParams();
+
+  const page = searchParams.get('page') || '1';
+  const limit = searchParams.get('limit') || '10';
+
+  const handlePageChange = (newPage: number) => {
+    setSearchParams({ page: String(newPage), limit });
+  };
+
+  return (
+    <div>
+      <p>第 {page} 页，每页 {limit} 条</p>
+      <button onClick={() => handlePageChange(Number(page) + 1)}>下一页</button>
+    </div>
+  );
+}
+```
+
+> ⚠️ **注意**：`useClientRoute` 返回的值取决于路由适配器的实现。如果返回 `undefined`，请检查是否已正确设置 `RouterProvider`。
+
+## 完整示例
+
+以下是一个完整的看板插件路由定义示例：
+
+```typescript
+import type { IModule, IRouteDef, IRouteService } from '@linyjs/client-module-interface';
+import KanbanBoardPage from './pages/kanban-board-page.js';
+import ProjectSettingsPage from './pages/project-settings-page.js';
+import TaskDetailPage from './pages/task-detail-page.js';
+
+class KanbanRouteService implements IRouteService {
+  basePath = '/kanban';
+
+  getRoutes() {
+    return [
+      {
+        path: '/',
+        component: KanbanBoardPage,
+        key: 'kanban-board',
+        meta: { title: '看板', requiresAuth: true }
+      },
+      {
+        path: '/settings',
+        component: ProjectSettingsPage,
+        key: 'kanban-settings',
+        meta: { title: '项目设置', requiresAuth: true }
+      },
+      {
+        path: '/tasks/:id',
+        component: TaskDetailPage,
+        key: 'kanban-task-detail',
+        meta: { title: '任务详情', requiresAuth: true },
+        loader: async ({ params }) => {
+          const res = await fetch(`/api/kanban/tasks/${params.id}`);
+          return { task: await res.json() };
+        }
+      }
+    ];
+  }
+}
+
+const kanbanRouteDef: IRouteDef = {
+  serviceTag: 'kanbanRoute',
+  serviceImpl: KanbanRouteService,
+  meta: { usageType: 'route' }
+};
+
+export const kanbanClientModule: IModule = {
+  name: 'kanbanClient',
+  serviceDefs: [kanbanRouteDef]
+};
+
+export default kanbanClientModule;
+```
+
+## 调试技巧
+
+### 查看已注册的路由
+
+在开发模式下，框架会打印已加载的客户端路由：
+
+```
+[SSR] Loaded client routes: [ '/', '/articles', '/kanban', '/kanban/settings', '/kanban/tasks/:id' ]
+```
+
+### 路由匹配日志
+
+SSR 中间件会输出路由匹配详情：
+
+```
+[SSR Middleware] Incoming request: GET /kanban
+[SSR Middleware] Attempting to match route for: /kanban
+[SSR Middleware] Match result: /
+[SSR Middleware] Route matched, starting render pipeline...
+```
+
+如果看到 `Match result: null`，说明路由未注册或路径不匹配。
+
+## 常见问题
+
+### 1. 路由 404 — 页面显示找不到
+
+**原因**：客户端模块未成功加载，或路由路径不匹配。
+
+**排查步骤**：
+1. 检查控制台是否有模块加载错误日志
+2. 检查 `[SSR] Loaded client routes` 输出中是否包含目标路径
+3. 确认 `basePath` + `path` 的最终路径与浏览器访问的 URL 一致
+4. 如果服务端模块加载失败（如依赖注入错误），可能阻断客户端模块加载
+
+### 2. 路由参数获取不到
+
+```typescript
+// ❌ 错误：直接从 props 获取
+function UserDetail(props) {
+  const id = props.match.params.id;  // 可能 undefined
+}
+
+// ✅ 正确：使用 useClientRoute
+function UserDetail() {
+  const useParams = useClientRoute('useParams');
+  const { id } = useParams();
+}
+```
+
+### 3. basePath 重复
+
+```typescript
+// ❌ 错误：path 中重复了 basePath
+class MyRouteService implements IRouteService {
+  basePath = '/kanban';
+  getRoutes() {
+    return [
+      { path: '/kanban', component: Board }  // 最终路径变成 /kanban/kanban
+    ];
+  }
+}
+
+// ✅ 正确：path 不含 basePath
+class MyRouteService implements IRouteService {
+  basePath = '/kanban';
+  getRoutes() {
+    return [
+      { path: '/', component: Board }  // 最终路径是 /kanban
+    ];
+  }
+}
+```
+
+## 相关文档
+
+- 💻 [客户端模块开发](./client-module.md) — 模块整体结构
+- 🪝 [公共 Hooks 使用](./client-hooks.md) — `useClientComponent`、`useClientHook`、`useClientService`
+- 🔒 [权限管理](./permissions.md) — 路由守卫与权限结合
+- 🔧 [API 参考](../api-reference/index.md) — IRoute、IRouteService 接口定义
+
+---
+
+**上一篇**: [客户端模块开发](./client-module.md) | **下一篇**: [公共 Hooks 使用](./client-hooks.md)

package/docs/guides/dependency-injection.md

@@ -565,6 +565,9 @@ class MyController {
 
 - 📖 [服务端模块开发](./server-module.md) — 控制器、中间件、定时任务
 - 📦 [shared-module-interface 指南](./shared-module-interface.md) — 类型定义包使用说明
+- 💻 [客户端模块开发](./client-module.md) — 模块整体结构
+- 🛤️ [前端页面路由](./client-routes.md) — 路由定义与使用
+- 🪝 [公共 Hooks 使用](./client-hooks.md) — 跨模块资源消费
 - 💾 [数据持久化](./data-persistence.md) — MongoDB 服务使用
 - 🔒 [权限管理](./permissions.md) — 权限服务使用
 - 🔧 [API 参考](../api-reference/index.md) — 接口类型定义