# 前端架构设计

> **最后更新**: 2026-04-06

---

## 路由分组设计

通过 Next.js App Router 的路由分组稳定模块边界，降低跨模块耦合：

```
app/
  (auth)/       # 鉴权相关页面
  (core)/       # 核心能力（审计/日志/通知）
  (engines)/    # 引擎模块（审批/表单/自动化）
  (modules)/    # 业务模块
  (workspace)/  # 工作台
```

**为什么这样分**：每组有独立的关注点和变更频率。`(engines)` 是底层能力，变更少；`(modules)` 是业务功能，变更频繁。分组避免业务模块的路由变更影响引擎模块。

---

## 分层职责

```
页面层 (app/)
    ↓ 负责：路由、数据获取、页面级状态
组件层 (components/)
    ↓ 负责：UI 展示、用户交互
工具层 (lib/, hooks/, services/)
    ↓ 负责：通用逻辑、API 调用、状态管理
```

### 组件分类

| 类型 | 目录 | 职责 |
|------|------|------|
| UI 组件 | `components/ui/` | 基础 UI 元素，与业务无关，高度可复用 |
| 通用业务组件 | `components/common/` | 跨模块复用的业务组件 |
| 布局组件 | `components/layout/` | 页面结构、导航、响应式布局 |

---

## 侧栏折叠态交互约定

- 折叠态仅显示图标，悬停/聚焦时显示菜单名称浮层
- 浮层文案复用导航 i18n 名称，禁止硬编码
- 图标按钮提供 `aria-label`

---

## 国际化

所有用户可见文案通过 `useTranslation` hook 获取，翻译文件在 `src/locales/`。

---

## 相关文档

- [前端规范详情](../../.agents/skills/frontend-main/references/frontend-standards.md)