# Q3 架构强化 + 前端体验 实施计划

> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 重构 ErpModule trait 实现自动化路由注册；修复 N+1 查询和错误映射；前端添加 Error Boundary、提取 5 个自定义 hooks、搭建 i18n 基础设施、接线行级数据权限。

**Architecture:** ErpModule trait 新增双路由注册方法，ModuleRegistry::build() 自动收集路由；前端 hooks 提取复用逻辑，react-i18next 管理文案；data_scope 从 JWT → handler → SQL 全链路贯通。

**Tech Stack:** Rust (Axum, SeaORM), React 19, Ant Design 6, Zustand 5, react-i18next

**Spec:** `docs/superpowers/specs/2026-04-17-platform-maturity-roadmap-design.md` §3

---

## File Structure

| 操作 | 文件 | 职责 |
|------|------|------|
| Modify | `crates/erp-core/src/module.rs:43-121` | ErpModule trait 添加路由注册方法 |
| Modify | `crates/erp-core/src/module.rs:124-258` | ModuleRegistry 添加 build() 返回路由 |
| Modify | `crates/erp-server/src/main.rs:300-430` | 简化模块注册和路由组装 |
| Modify | `crates/erp-auth/src/module.rs` | 实现 register_public/protected_routes |
| Modify | `crates/erp-config/src/module.rs` | 实现 register_public/protected_routes |
| Modify | `crates/erp-workflow/src/module.rs` | 实现 register_public/protected_routes |
| Modify | `crates/erp-message/src/module.rs` | 实现 register_public/protected_routes |
| Modify | `crates/erp-plugin/src/module.rs` | 实现 register_public/protected_routes |
| Modify | `crates/erp-auth/src/service/user_service.rs:170-182` | N+1 查询改为批量 |
| Modify | `crates/erp-plugin/src/service.rs:370-395` | N+1 查询改为批量 |
| Create | `apps/web/src/components/ErrorBoundary.tsx` | 全局 + 页面级 Error Boundary |
| Modify | `apps/web/src/App.tsx` | 包裹 Error Boundary |
| Create | `apps/web/src/hooks/useCountUp.ts` | 提取计数动画 hook |
| Create | `apps/web/src/hooks/useDarkMode.ts` | 提取暗色模式判断 hook |
| Create | `apps/web/src/hooks/useDebouncedValue.ts` | 防抖 hook |
| Create | `apps/web/src/hooks/usePaginatedData.ts` | 统一分页数据管理 |
| Create | `apps/web/src/hooks/useApiRequest.ts` | 统一 API 错误处理 |
| Create | `apps/web/src/api/types.ts` | 提取 PaginatedResponse 共享类型 |
| Create | `apps/web/src/api/errors.ts` | 提取 extractErrorMessage |
| Modify | `apps/web/src/api/client.ts:30-39` | CancelToken → AbortController |
| Modify | `apps/web/src/api/users.ts` | 移除重复 PaginatedResponse，从 types.ts 导入 |
| Modify | `apps/web/src/api/plugins.ts` | 同上 |
| Install | `react-i18next`, `i18next` | i18n 基础设施 |
| Create | `apps/web/src/i18n/` | i18n 配置和翻译文件 |
| Modify | `apps/web/src/pages/Users.tsx` | 使用 useDebouncedValue |
| Modify | `crates/erp-auth/src/middleware/jwt_auth.rs:50-51` | department_ids 查询 |
| Modify | `crates/erp-plugin/src/handler/data_handler.rs:108-113` | data_scope 接线 |

---

## Chunk 1: ErpModule Trait 重构

### Task 1: 扩展 ErpModule trait — 添加路由注册方法

**Files:**
- Modify: `crates/erp-core/src/module.rs:43-121`

- [ ] **Step 1: 在 ErpModule trait 中添加两个路由注册方法**

在 `crates/erp-core/src/module.rs` 的 `ErpModule` trait 中，在 `register_event_handlers` 之后添加：

```rust
/// 注册公开路由（不需要 JWT 认证）
/// 默认实现返回未修改的 router
fn register_public_routes(&self, router: Router) -> Router {
    router
}

/// 注册受保护路由（需要 JWT 认证）
/// 默认实现返回未修改的 router
fn register_protected_routes(&self, router: Router) -> Router {
    router
}
```

需要在文件顶部添加 `use axum::Router;` import（如果还没有）。

- [ ] **Step 2: 在 `ModuleRegistry` 中添加 `build()` 方法**

在 `ModuleRegistry` impl 中添加：

```rust
/// 构建路由：收集所有模块的公开路由和受保护路由
/// 返回 (registry, public_routes, protected_routes)
pub fn build(self) -> (Self, Router, Router) {
    let mut public_routes = Router::new();
    let mut protected_routes = Router::new();

    for module in self.modules() {
        public_routes = module.register_public_routes(public_routes);
        protected_routes = module.register_protected_routes(protected_routes);
    }

    (self, public_routes, protected_routes)
}
```

- [ ] **Step 3: 验证编译**

```bash
cargo check -p erp-core
```

- [ ] **Step 4: Commit**

```bash
git add crates/erp-core/src/module.rs
git commit -m "feat(core): ErpModule trait 添加 register_public/protected_routes 方法"
```

---

### Task 2: Auth 模块迁移到 trait 路由注册

**Files:**
- Modify: `crates/erp-auth/src/module.rs`

- [ ] **Step 1: 在 AuthModule 的 ErpModule impl 中实现路由注册**

将现有的 `AuthModule::public_routes()` 和 `AuthModule::protected_routes()` 静态方法逻辑搬到 trait 方法中：

```rust
fn register_public_routes(&self, router: Router) -> Router {
    router.merge(Self::public_routes())
}

fn register_protected_routes(&self, router: Router) -> Router {
    router.merge(Self::protected_routes())
}
```

保留静态方法作为内部实现（避免一次性改动过大），trait 方法调用静态方法。

- [ ] **Step 2: 验证编译**

```bash
cargo check -p erp-auth
```

- [ ] **Step 3: Commit**

```bash
git add crates/erp-auth/src/module.rs
git commit -m "refactor(auth): 实现 ErpModule trait 路由注册"
```

---

### Task 3: Config/Workflow/Message/Plugin 模块迁移

**Files:**
- Modify: `crates/erp-config/src/module.rs`
- Modify: `crates/erp-workflow/src/module.rs`
- Modify: `crates/erp-message/src/module.rs`
- Modify: `crates/erp-plugin/src/module.rs`

- [ ] **Step 1: 对每个模块重复 Task 2 的模式**

每个模块添加：
```rust
fn register_public_routes(&self, router: Router) -> Router {
    router.merge(Self::public_routes())
}

fn register_protected_routes(&self, router: Router) -> Router {
    router.merge(Self::protected_routes())
}
```

- [ ] **Step 2: 验证全 workspace 编译**

```bash
cargo check --workspace
```

- [ ] **Step 3: Commit**

```bash
git add crates/erp-config/ crates/erp-workflow/ crates/erp-message/ crates/erp-plugin/
git commit -m "refactor: 所有模块实现 ErpModule trait 路由注册"
```

---

### Task 4: main.rs 简化 — 使用 ModuleRegistry::build()

**Files:**
- Modify: `crates/erp-server/src/main.rs:300-430`

- [ ] **Step 1: 替换路由组装逻辑**

将当前的手动路由组装（第 390-419 行）改为自动收集：

```rust
// 替换 main.rs 中的路由组装部分
let (registry, module_public_routes, module_protected_routes) = registry.build();

// Public routes: health + openapi + 模块公开路由
let public_routes = Router::new()
    .merge(handlers::health::health_check_router())
    .merge(module_public_routes)
    .route("/docs/openapi.json", axum::routing::get(handlers::openapi::openapi_spec))
    .layer(axum::middleware::from_fn_with_state(
        state.clone(),
        middleware::rate_limit::rate_limit_by_ip,
    ))
    .with_state(state.clone());

// Protected routes: 模块受保护路由 + 审计日志
let protected_routes = module_protected_routes
    .merge(handlers::audit_log::audit_log_router())
    .layer(axum::middleware::from_fn_with_state(
        state.clone(),
        middleware::rate_limit::rate_limit_by_user,
    ))
    .layer(axum_middleware::from_fn(move |req, next| {
        let secret = jwt_secret.clone();
        async move { jwt_auth_middleware_fn(secret, req, next).await }
    }))
    .with_state(state.clone());
```

注意：`handlers::health::health_check_router()` 和 `handlers::audit_log::audit_log_router()` 是 erp-server 自身的路由，不属于任何模块，所以保留手动添加。`/docs/openapi.json` 也是 server 自有路由。

- [ ] **Step 2: 验证编译和测试**

```bash
cargo check -p erp-server && cargo test --workspace
```

- [ ] **Step 3: Commit**

```bash
git add crates/erp-server/src/main.rs
git commit -m "refactor(server): main.rs 使用 ModuleRegistry::build() 自动收集路由"
```

---

## Chunk 2: N+1 查询优化

### Task 5: user_service N+1 查询优化

**Files:**
- Modify: `crates/erp-auth/src/service/user_service.rs:170-182`

- [ ] **Step 1: 将循环内单独查询改为批量查询**

将当前的 N+1 模式（第 174-180 行）：

```rust
// 当前：每个用户单独查询角色
let mut resps = Vec::with_capacity(models.len());
for m in models {
    let roles: Vec<RoleResp> = Self::fetch_user_role_resps(m.id, tenant_id, db)
        .await
        .unwrap_or_default();
    resps.push(model_to_resp(&m, roles));
}
```

改为批量查询：

```rust
// 优化：一次查询所有用户的角色
let user_ids: Vec<Uuid> = models.iter().map(|m| m.id).collect();
let role_map = Self::fetch_batch_user_role_resps(&user_ids, tenant_id, db).await;

let resps: Vec<UserResp> = models
    .iter()
    .map(|m| model_to_resp(m, role_map.get(&m.id).cloned().unwrap_or_default()))
    .collect();
```

- [ ] **Step 2: 实现 `fetch_batch_user_role_resps` 方法**

新增方法，使用 `user_id IN (...)` 批量查询：

```rust
async fn fetch_batch_user_role_resps(
    user_ids: &[Uuid],
    tenant_id: Uuid,
    db: &DatabaseConnection,
) -> std::collections::HashMap<Uuid, Vec<RoleResp>> {
    if user_ids.is_empty() {
        return std::collections::HashMap::new();
    }

    // 批量查询 user_role 关联
    let user_roles: Vec<user_role::Model> = user_role::Entity::find()
        .filter(user_role::Column::UserId.is_in(user_ids.iter().copied()))
        .all(db)
        .await
        .unwrap_or_default();

    let role_ids: Vec<Uuid> = user_roles.iter().map(|ur| ur.role_id).collect();

    // 批量查询角色
    let roles: Vec<role::Model> = if role_ids.is_empty() {
        vec![]
    } else {
        role::Entity::find()
            .filter(role::Column::Id.is_in(role_ids.iter().copied()))
            .filter(role::Column::TenantId.eq(tenant_id))
            .filter(role::Column::DeletedAt.is_null())
            .all(db)
            .await
            .unwrap_or_default()
    };

    let role_map: std::collections::HashMap<Uuid, &role::Model> = roles
        .iter()
        .map(|r| (r.id, r))
        .collect();

    // 按 user_id 分组
    let mut result = std::collections::HashMap::new();
    for ur in &user_roles {
        let resp = role_map.get(&ur.role_id)
            .map(|r| RoleResp { id: r.id, name: r.name.clone(), code: r.code.clone() })
            .unwrap_or_else(|| RoleResp { id: ur.role_id, name: "Unknown".into(), code: "unknown".into() });
        result.entry(ur.user_id).or_insert_with(Vec::new).push(resp);
    }
    result
}
```

注意：需要从 `user_role` entity 和 `role` entity 中导入正确的类型。调整 `RoleResp` 字段名与实际 struct 一致。

- [ ] **Step 3: 验证编译**

```bash
cargo check -p erp-auth
```

- [ ] **Step 4: Commit**

```bash
git add crates/erp-auth/src/service/user_service.rs
git commit -m "perf(auth): 用户列表 N+1 查询优化为批量查询"
```

---

### Task 6: plugin_service N+1 查询优化

**Files:**
- Modify: `crates/erp-plugin/src/service.rs:370-395`

- [ ] **Step 1: 将 `find_plugin_entities` 循环调用改为批量查询**

当前（第 393 行）每个 plugin 单独查询 entities。改为先收集所有 `plugin_id`，一次批量查询，再按 `plugin_id` 分组。

- [ ] **Step 2: 实现 `find_batch_plugin_entities`**

使用 `WHERE plugin_id IN (...)` 一次查询所有 plugin 的 entities，返回 `HashMap<Uuid, Vec<EntityModel>>`。

- [ ] **Step 3: 验证编译**

```bash
cargo check -p erp-plugin
```

- [ ] **Step 4: Commit**

```bash
git add crates/erp-plugin/src/service.rs
git commit -m "perf(plugin): 插件列表 N+1 查询优化为批量查询"
```

---

## Chunk 3: 前端 Error Boundary + hooks 提取

### Task 7: 创建 ErrorBoundary 组件

**Files:**
- Create: `apps/web/src/components/ErrorBoundary.tsx`

- [ ] **Step 1: 创建类组件 ErrorBoundary**

```tsx
import { Component, ReactNode } from 'react';
import { Button, Result } from 'antd';

interface Props {
  children: ReactNode;
  /** 是否为页面级（显示更详细的错误信息） */
  pageLevel?: boolean;
}

interface State {
  hasError: boolean;
  error: Error | null;
}

export class ErrorBoundary extends Component<Props, State> {
  constructor(props: Props) {
    super(props);
    this.state = { hasError: false, error: null };
  }

  static getDerivedStateFromError(error: Error): State {
    return { hasError: true, error };
  }

  componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
    console.error('ErrorBoundary caught:', error, errorInfo);
  }

  handleReset = () => {
    this.setState({ hasError: false, error: null });
  };

  render() {
    if (this.state.hasError) {
      return (
        <Result
          status="error"
          title={this.props.pageLevel ? '页面加载出错' : '出了点问题'}
          subTitle={this.props.pageLevel
            ? `错误信息：${this.state.error?.message || '未知错误'}`
            : '请刷新页面重试'}
          extra={[
            <Button key="retry" type="primary" onClick={this.handleReset}>
              重试
            </Button>,
            <Button key="home" onClick={() => window.location.hash = '/'}>
              返回首页
            </Button>,
          ]}
        />
      );
    }
    return this.props.children;
  }
}
```

- [ ] **Step 2: Commit**

```bash
git add apps/web/src/components/ErrorBoundary.tsx
git commit -m "feat(web): 添加 ErrorBoundary 组件"
```

---

### Task 8: App.tsx 包裹 Error Boundary

**Files:**
- Modify: `apps/web/src/App.tsx`

- [ ] **Step 1: 在 App.tsx 中添加全局和页面级 Error Boundary**

在路由渲染外层包裹全局 ErrorBoundary，在每个 Suspense 内部包裹页面级 ErrorBoundary：

```tsx
import ErrorBoundary from './components/ErrorBoundary';

// 全局包裹 — 在 HashRouter 内、Routes 外
<HashRouter>
  <ErrorBoundary>
    <ConfigProvider ...>
      <Routes>
        {/* 公开路由 */}
        <Route path="/login" element={<Login />} />
        {/* 受保护路由 — 每个页面级 ErrorBoundary */}
        <Route path="/" element={
          <PrivateRoute>
            <MainLayout>
              <ErrorBoundary pageLevel>
                <Suspense fallback={<Spin size="large" />}>
                  <Home />
                </Suspense>
              </ErrorBoundary>
            </MainLayout>
          </PrivateRoute>
        } />
        {/* ... 其他路由同样模式 ... */}
      </Routes>
    </ConfigProvider>
  </ErrorBoundary>
</HashRouter>
```

注意：为所有懒加载路由添加页面级 ErrorBoundary 包裹。可以创建一个辅助组件简化重复：

```tsx
function LazyPage({ children }: { children: ReactNode }) {
  return (
    <ErrorBoundary pageLevel>
      <Suspense fallback={<Spin size="large" className="page-loading" />}>
        {children}
      </Suspense>
    </ErrorBoundary>
  );
}
```

- [ ] **Step 2: 验证前端构建**

```bash
cd apps/web && pnpm build
```

- [ ] **Step 3: Commit**

```bash
git add apps/web/src/App.tsx
git commit -m "feat(web): App.tsx 包裹全局 + 页面级 Error Boundary"
```

---

### Task 9: 提取 useCountUp hook

**Files:**
- Create: `apps/web/src/hooks/useCountUp.ts`
- Modify: `apps/web/src/pages/Home.tsx` — 删除内联 useCountUp，改为 import
- Modify: `apps/web/src/pages/dashboard/DashboardWidgets.tsx` — 同上

- [ ] **Step 1: 从 Home.tsx 提取 useCountUp 到 hooks/ 目录**

```ts
// apps/web/src/hooks/useCountUp.ts
import { useState, useEffect, useRef } from 'react';

export function useCountUp(end: number, duration = 800) {
  const [count, setCount] = useState(0);
  const prevEnd = useRef(end);

  useEffect(() => {
    if (end === prevEnd.current && count > 0) return;
    prevEnd.current = end;
    if (end === 0) { setCount(0); return; }

    const startTime = performance.now();
    function tick(now: number) {
      const elapsed = now - startTime;
      const progress = Math.min(elapsed / duration, 1);
      const eased = 1 - Math.pow(1 - progress, 3);
      setCount(Math.round(end * eased));
      if (progress < 1) requestAnimationFrame(tick);
    }
    requestAnimationFrame(tick);
  }, [end, duration]);

  return count;
}
```

- [ ] **Step 2: 更新 Home.tsx 和 DashboardWidgets.tsx**

在两个文件中：
- 删除内联的 `function useCountUp(...)` 定义
- 添加 `import { useCountUp } from '../hooks/useCountUp';`（或对应相对路径）

- [ ] **Step 3: 验证构建**

```bash
cd apps/web && pnpm build
```

- [ ] **Step 4: Commit**

```bash
git add apps/web/src/hooks/useCountUp.ts apps/web/src/pages/Home.tsx apps/web/src/pages/dashboard/DashboardWidgets.tsx
git commit -m "refactor(web): 提取 useCountUp hook，消除 Home/Dashboard 重复"
```

---

### Task 10: 提取 useDarkMode hook

**Files:**
- Create: `apps/web/src/hooks/useDarkMode.ts`

- [ ] **Step 1: 创建 useDarkMode hook**

```ts
// apps/web/src/hooks/useDarkMode.ts
import { theme } from 'antd';

export function useDarkMode(): boolean {
  const { token } = theme.useToken();
  // 使用 colorBgBase（更可靠的基础背景色判断）
  // 亮色主题 colorBgBase = '#ffffff'，暗色主题 colorBgBase = '#141414'
  const isDark = token.colorBgBase !== '#ffffff' && token.colorBgBase !== '#fff';
  return isDark;
}
```

注意：此 hook 必须在 Ant Design `<ConfigProvider>` 内部使用。当前 `token.colorBgContainer === '#111827'` 的字符串比较方式可被此 hook 替代。

- [ ] **Step 2: 在 8+ 个文件中替换暗色模式判断**

搜索 `colorBgContainer === '#111827'` 或 `colorBgContainer === 'rgb(17, 24, 39)'` 的文件，替换为 `useDarkMode()` hook 调用。

- [ ] **Step 3: 验证构建**

```bash
cd apps/web && pnpm build
```

- [ ] **Step 4: Commit**

```bash
git add apps/web/src/
git commit -m "refactor(web): 提取 useDarkMode hook，替换 8+ 处字符串比较"
```

---

### Task 11: 提取 useDebouncedValue hook

**Files:**
- Create: `apps/web/src/hooks/useDebouncedValue.ts`
- Modify: `apps/web/src/pages/Users.tsx`

- [ ] **Step 1: 创建 useDebouncedValue hook**

```ts
// apps/web/src/hooks/useDebouncedValue.ts
import { useState, useEffect } from 'react';

export function useDebouncedValue<T>(value: T, delay = 300): T {
  const [debouncedValue, setDebouncedValue] = useState(value);

  useEffect(() => {
    const timer = setTimeout(() => setDebouncedValue(value), delay);
    return () => clearTimeout(timer);
  }, [value, delay]);

  return debouncedValue;
}
```

- [ ] **Step 2: 在 Users.tsx 中应用防抖**

```tsx
// Users.tsx — 替换直接使用 searchText 触发 fetchUsers
import { useDebouncedValue } from '../hooks/useDebouncedValue';

// 在组件内
const debouncedSearch = useDebouncedValue(searchText, 300);

const fetchUsers = useCallback(async (p = page) => {
    setLoading(true);
    try {
      const result = await listUsers(p, 20, debouncedSearch);
      setUsers(result.data);
      setTotal(result.total);
    } catch {
      message.error('加载用户列表失败');
    } finally {
      setLoading(false);
    }
  }, [page, debouncedSearch]);
```

- [ ] **Step 3: 验证构建**

```bash
cd apps/web && pnpm build
```

- [ ] **Step 4: Commit**

```bash
git add apps/web/src/hooks/useDebouncedValue.ts apps/web/src/pages/Users.tsx
git commit -m "feat(web): 添加 useDebouncedValue hook，用户搜索防抖"
```

---

### Task 12: 提取 usePaginatedData 和 useApiRequest hooks

**Files:**
- Create: `apps/web/src/hooks/usePaginatedData.ts`
- Create: `apps/web/src/hooks/useApiRequest.ts`

- [ ] **Step 1: 创建 usePaginatedData hook**

```ts
// apps/web/src/hooks/usePaginatedData.ts
import { useState, useCallback } from 'react';
import { message } from 'antd';

interface PaginatedState<T> {
  data: T[];
  total: number;
  page: number;
  loading: boolean;
}

export function usePaginatedData<T>(
  fetchFn: (page: number, pageSize: number, search: string) => Promise<{ data: T[]; total: number }>,
  pageSize = 20,
) {
  const [state, setState] = useState<PaginatedState<T>>({
    data: [],
    total: 0,
    page: 1,
    loading: false,
  });
  const [searchText, setSearchText] = useState('');

  const refresh = useCallback(async (p?: number) => {
    const targetPage = p ?? state.page;
    setState(s => ({ ...s, loading: true }));
    try {
      const result = await fetchFn(targetPage, pageSize, searchText);
      setState({ data: result.data, total: result.total, page: targetPage, loading: false });
    } catch {
      message.error('加载数据失败');
      setState(s => ({ ...s, loading: false }));
    }
  }, [fetchFn, pageSize, searchText, state.page]);

  return { ...state, searchText, setSearchText, refresh };
}
```

- [ ] **Step 2: 创建 useApiRequest hook**

```ts
// apps/web/src/hooks/useApiRequest.ts
import { useCallback } from 'react';
import { message } from 'antd';

export function useApiRequest() {
  const execute = useCallback(async <T>(
    fn: () => Promise<T>,
    successMsg?: string,
    errorMsg = '操作失败',
  ): Promise<T | null> => {
    try {
      const result = await fn();
      if (successMsg) message.success(successMsg);
      return result;
    } catch (err) {
      const msg = extractErrorMessage(err);
      message.error(msg || errorMsg);
      return null;
    }
  }, []);

  return { execute };
}

function extractErrorMessage(err: unknown): string {
  if (err && typeof err === 'object' && 'response' in err) {
    const resp = (err as { response?: { data?: { message?: string } } }).response;
    return resp?.data?.message || '';
  }
  if (err instanceof Error) return err.message;
  return '';
}
```

- [ ] **Step 3: 验证构建**

```bash
cd apps/web && pnpm build
```

- [ ] **Step 4: Commit**

```bash
git add apps/web/src/hooks/
git commit -m "feat(web): 添加 usePaginatedData + useApiRequest hooks"
```

---

## Chunk 4: 前端共享类型统一 + CancelToken 替换

### Task 13: 提取 PaginatedResponse 共享类型

**Files:**
- Create: `apps/web/src/api/types.ts`
- Modify: `apps/web/src/api/users.ts`
- Modify: `apps/web/src/api/plugins.ts`
- Modify: `apps/web/src/api/` 中所有导入 `PaginatedResponse` 的文件

- [ ] **Step 1: 创建 `api/types.ts`**

```ts
// apps/web/src/api/types.ts
export interface PaginatedResponse<T> {
  data: T[];
  total: number;
  page: number;
  page_size: number;
  total_pages: number;
}
```

- [ ] **Step 2: 从 users.ts 和 plugins.ts 删除重复定义，改为 import**

```ts
// users.ts 和 plugins.ts 中
import { PaginatedResponse } from './types';
```

搜索所有从 `users.ts` 导入 `PaginatedResponse` 的文件，改为从 `./types` 导入。

- [ ] **Step 3: 创建 `api/errors.ts`**

```ts
// apps/web/src/api/errors.ts
export function extractErrorMessage(err: unknown, fallback = '操作失败'): string {
  if (err && typeof err === 'object' && 'response' in err) {
    const resp = (err as { response?: { data?: { message?: string } } }).response;
    if (resp?.data?.message) return resp.data.message;
  }
  if (err instanceof Error) return err.message;
  return fallback;
}
```

- [ ] **Step 4: 验证构建**

```bash
cd apps/web && pnpm build
```

- [ ] **Step 5: Commit**

```bash
git add apps/web/src/api/
git commit -m "refactor(web): 提取 PaginatedResponse 共享类型和 extractErrorMessage"
```

---

### Task 14: CancelToken → AbortController

**Files:**
- Modify: `apps/web/src/api/client.ts:30-39`

- [ ] **Step 1: 替换缓存实现中的 CancelToken**

将缓存命中时的 `CancelToken.source()` 模式改为直接返回缓存数据：

```ts
// 替换前（第 30-39 行）
if (config.method === 'get' && config.url) {
  const key = getCacheKey(config);
  const entry = requestCache.get(key);
  if (entry && Date.now() - entry.timestamp < CACHE_TTL) {
    const source = axios.CancelToken.source();
    config.cancelToken = source.token;
    source.cancel(JSON.stringify({ __cached: true, data: entry.data }));
  }
}

// 替换后
if (config.method === 'get' && config.url) {
  const key = getCacheKey(config);
  const entry = requestCache.get(key);
  if (entry && Date.now() - entry.timestamp < CACHE_TTL) {
    // 直接返回缓存的响应数据，不再使用 CancelToken hack
    return Promise.resolve({
      data: entry.data,
      status: 200,
      statusText: 'OK (cached)',
      headers: {} as any,
      config,
    } as AxiosResponse);
  }
}
```

同时移除响应拦截器中的 `axios.isCancel` 处理逻辑。

- [ ] **Step 2: 验证构建**

```bash
cd apps/web && pnpm build
```

- [ ] **Step 3: Commit**

```bash
git add apps/web/src/api/client.ts
git commit -m "refactor(web): 移除废弃的 CancelToken，改用直接返回缓存"
```

---

## Chunk 5: i18n 基础设施

### Task 15: 安装 react-i18next 并配置

**Files:**
- Install: `react-i18next`, `i18next`
- Create: `apps/web/src/i18n/index.ts`
- Create: `apps/web/src/i18n/locales/zh-CN.json`
- Modify: `apps/web/src/main.tsx`

- [ ] **Step 1: 安装依赖**

```bash
cd apps/web && pnpm add react-i18next i18next
```

- [ ] **Step 2: 创建 i18n 配置**

```ts
// apps/web/src/i18n/index.ts
import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import zhCN from './locales/zh-CN.json';

i18n.use(initReactI18next).init({
  resources: { 'zh-CN': { translation: zhCN } },
  lng: 'zh-CN',
  fallbackLng: 'zh-CN',
  interpolation: { escapeValue: false },
});

export default i18n;
```

- [ ] **Step 3: 创建初始翻译文件**

```json
// apps/web/src/i18n/locales/zh-CN.json
{
  "common": {
    "save": "保存",
    "cancel": "取消",
    "delete": "删除",
    "edit": "编辑",
    "create": "新建",
    "search": "搜索",
    "confirm": "确认",
    "loading": "加载中...",
    "success": "操作成功",
    "error": "操作失败"
  },
  "auth": {
    "login": {
      "title": "登录",
      "username": "用户名",
      "password": "密码",
      "submit": "登录",
      "success": "登录成功",
      "failed": "用户名或密码错误"
    }
  },
  "nav": {
    "home": "首页",
    "users": "用户管理",
    "roles": "角色管理",
    "organizations": "组织管理",
    "workflow": "工作流",
    "messages": "消息中心",
    "settings": "系统设置",
    "plugins": "插件管理"
  }
}
```

- [ ] **Step 4: 在 main.tsx 中导入 i18n**

在 `apps/web/src/main.tsx` 顶部添加：
```ts
import './i18n';
```

- [ ] **Step 5: 验证构建**

```bash
cd apps/web && pnpm build
```

- [ ] **Step 6: Commit**

```bash
git add apps/web/src/i18n/ apps/web/src/main.tsx apps/web/package.json apps/web/pnpm-lock.yaml
git commit -m "feat(web): 搭建 i18n 基础设施 (react-i18next)"
```

---

## Chunk 6: 行级数据权限接线

### Task 16: JWT 中间件注入 department_ids

**Files:**
- Modify: `crates/erp-auth/src/middleware/jwt_auth.rs:50-51`

- [ ] **Step 1: 实现 department_ids 查询**

将当前的：
```rust
// TODO: 待 user_positions 关联表建立后，从数据库查询用户所属部门 ID 列表
department_ids: vec![],
```

改为实际查询。需要从 JWT 的 state 中获取 `DatabaseConnection`（可能需要修改中间件签名以传入 db）：

```rust
// 查询用户所属部门 ID 列表（通过 user_positions 关联表）
let department_ids = match find_user_departments(claims.sub, claims.tid, &db).await {
    Ok(ids) => ids,
    Err(e) => {
        tracing::warn!(error = %e, "查询用户部门列表失败，默认为空");
        vec![]
    }
};

let ctx = TenantContext {
    tenant_id: claims.tid,
    user_id: claims.sub,
    roles: claims.roles,
    permissions: claims.permissions,
    department_ids,
};
```

注意：需要实现 `find_user_departments` 函数，查询 `user_positions` 表。如果中间件签名无法传入 `db`，需要考虑通过 State 或 Extension 传递。参考 `data_handler.rs` 中的注释（第 108-113 行）。

- [ ] **Step 2: 验证编译**

```bash
cargo check -p erp-auth
```

- [ ] **Step 3: Commit**

```bash
git add crates/erp-auth/src/middleware/jwt_auth.rs
git commit -m "feat(auth): JWT 中间件注入 department_ids"
```

---

### Task 17: data_handler 接线 data_scope 过滤

**Files:**
- Modify: `crates/erp-plugin/src/handler/data_handler.rs:108-113`

- [ ] **Step 1: 实现第 108 行 TODO 描述的 4 步逻辑**

按照 TODO 注释中的 4 个步骤实现：

```rust
// 1. 检查 entity 定义是否声明 data_scope
let entity_def = resolve_entity_def(&manifest_id, &entity, &state.db).await;
if entity_def.data_scope.unwrap_or(false) {
    // 2. 获取当前用户的 data scope 等级
    let scope = get_data_scope(&ctx, &fine_perm, &state.db).await?;

    // 3. 若 scope != "all"，获取部门成员列表
    if scope.level != "all" {
        // 4. 将 scope 条件合并到 filter
        let scope_filter = build_data_scope_condition(
            &scope,
            &ctx.department_ids,
            ctx.user_id,
        )?;
        // 合并 scope_filter 到现有 filter
    }
}
```

参考 `crates/erp-plugin/src/dynamic_table.rs` 中的 `build_data_scope_condition()` 函数。

- [ ] **Step 2: 同样修改 update/delete/count/aggregate 端点**

所有涉及数据查询的端点都需要注入 data_scope 条件。

- [ ] **Step 3: 验证编译**

```bash
cargo check -p erp-plugin
```

- [ ] **Step 4: Commit**

```bash
git add crates/erp-plugin/src/handler/data_handler.rs
git commit -m "feat(plugin): data_handler 接线行级数据权限过滤"
```

---

## 验证清单

- [ ] **V1: 全 workspace 编译和测试**
```bash
cargo check && cargo test --workspace
```

- [ ] **V2: 前端构建**
```bash
cd apps/web && pnpm build
```

- [ ] **V3: ErpModule 路由自动化验证**
```bash
cargo run -p erp-server
```
验证所有 API 端点仍然正常工作（路由未丢失）

- [ ] **V4: Error Boundary 验证**
在浏览器中访问一个不存在的路由或触发一个渲染错误，验证 Error Boundary 捕获并显示友好提示

- [ ] **V5: i18n 验证**
在代码中使用 `useTranslation()` 输出一个翻译 key，验证显示正确的中文文案