# 11 · 前端路由与目录规范

| 项 | 内容 |
| --- | --- |
| 文档版本 | V1.0（2026-11-03） |
| 依据 | 技术架构 §6 / §10、[04 · API 与路由规范](04-API与路由规范.md) §8、`AGENTS.md` §5 |
| 适用范围 | `apps/web` 全部页面路由、导航配置与页面目录 |
| 强制级别 | 强制 |

> 目标：URL、导航、面包屑、页面目录四者一一对应，做到「看 URL 就能找到代码，看目录就能知道路由」。

---

## 1　模块与基础路径

导航一级模块与 URL 首段必须一致，模块 key 同时用于 `nav-config` 与占位路由解析。

| 导航模块 | 模块 key | 基础路径 | 页面目录 |
| --- | --- | --- | --- |
| 工作台 | `dashboard` | `/` | `pages/dashboard/` |
| 脚本 | `scripts` | `/scripts` | `pages/scripts/` |
| 素材 | `material` | `/material` | `pages/material/` |
| 资产 | `assets` | `/assets` | `pages/assets/` |
| 交付 | `delivery` | `/delivery` | `pages/delivery/` |
| 管理中心 | `system` | `/system` | `pages/system/` |

- `FE-01` 新增一级模块必须先登记本表，再改 `nav-config`、路由与目录；禁止出现「导航有、路由无」或「路由有、导航无」。
- `FE-02` 模块 key 取 URL 首段（复数资源用复数：`scripts` / `assets`），**不得**再用 `platform` 这类与路径不一致的别名。
- `FE-03` 基础路径之外的例外页面只有：`/login`、`/401`、`/403`、`/404`、`/500`。

---

## 2　路径语法

统一形式：`/<模块>/<功能>[/<子资源>/...]`，功能段使用 **kebab-case 复数资源名**。

| 页面类型 | 形式 | 示例 |
| --- | --- | --- |
| 列表 / 首页 | `/<module>/<feature>` | `/system/users`、`/scripts/library` |
| 新建 | `/<module>/<feature>/new` | `/system/users/new` |
| 详情 | `/<module>/<feature>/:id` | `/system/users/:id` |
| 子资源 | `/<module>/<feature>/:id/<sub>` | `/system/users/:id/...` |
| 子功能 | `/<module>/<feature>/<sub-feature>` | `/system/customer-fields/approvals` |

- `FE-04` 资源名用复数 kebab-case：`users`、`roles`、`audit-logs`；禁止 `/system/user`、`/system/getUser`、`/system/users_list`。
- `FE-05` 新建统一用 `/new`，**不用** `/create`、`/add`；详情参数统一叫 `:id`。
- `FE-06` URL 中禁止动词（`/doGenerate`、`/approveUser`）；动作走接口或子资源。
- `FE-07` 禁止尾斜杠；大小写敏感，全部小写。
- `FE-08` 层级：模块 → 功能 → 资源 ID → 子资源，**最多 4 段**；更深归属改用 query 过滤。
- `FE-09` 筛选 / 分页 / 排序 / 选中态必须进 query（与 [04](04-API与路由规范.md) `API-31` 一致），保证链接可分享、刷新可恢复。
- `FE-10` 路由参数中的 ID 必须 `encodeURIComponent`，拼接统一走 `routes.ts` 的 helper（如 `userDetailPath`）。

---

## 3　目录映射

```
apps/web/src/pages/
├─ dashboard/                 # 工作台（对应 /）
│  └─ HomePage.tsx
├─ scripts/                   # 脚本（对应 /scripts）
├─ material/                  # 素材（对应 /material）
├─ assets/                    # 资产（对应 /assets）
├─ delivery/                  # 交付（对应 /delivery）
├─ system/                    # 管理中心（对应 /system）
│  └─ users/                  # 用户与组织（对应 /system/users）
│     ├─ UsersPage.tsx
│     ├─ UserNewPage.tsx
│     ├─ UserListPanel.tsx
│     ├─ dialogs/
│     └─ *.spec.tsx
├─ login/                     # 例外：登录页
├─ errors/                    # 例外：401 / 403 / 404 / 500
└─ workspace/                 # 例外：未实现批次的通用占位页
```

- `FE-11` 页面目录 = `pages/<模块>/<功能>/`，与 URL 逐段对应；功能目录名与路由 feature 段一致。
- `FE-12` 路由入口文件命名为 `<Feature>Page.tsx`（如 `UsersPage.tsx`）；新建 / 详情页同目录，命名为 `<Feature>NewPage.tsx` / `<Feature>DetailPage.tsx`。
- `FE-13` 页面私有组件、弹窗、格式化函数、单测放在同一功能目录内（`dialogs/`、`*.spec.tsx`）；**不**为单个页面另建共享目录。
- `FE-14` 跨多个功能复用的组件放 `src/components/`，跨页面 Hook 放 `src/hooks/`；领域逻辑被两个以上页面复用时才考虑 `src/features/<module>/`。
- `FE-15` `pages/login`、`pages/errors`、`pages/workspace` 是基础设施例外，不按模块归位。
- `FE-16` 禁止把页面放到 `src/` 根下或 `pages/<module>/` 根下；必须落在具体功能目录内。

---

## 4　路由常量与注册

- `FE-17` 全部路径集中在 `src/routes.ts`，按模块分组；组件内禁止写字符串路径（与 [04](04-API与路由规范.md) `API-26` 一致）。
- `FE-18` 路由在 `src/router.tsx` 集中声明；登录后页面挂在 `AppLayout` 下，页面级组件使用懒加载。
- `FE-19` 导航配置 `nav-config.ts` 的模块 key 与 item path 必须与 `routes.ts` 一致；面包屑从导航配置派生，禁止在页面内写死。
- `FE-20` 权限守卫按 [04](04-API与路由规范.md) `API-29`：`<RequirePermission>` 无权限渲染 403 页，不隐藏路由；按钮级权限用 `<Can>`。
- `FE-21` 旧路径重命名时保留一个版本的 301/302 式前端重定向（`<Navigate replace>`），并在计划 / 文档同一提交登记；下一版本删除。
- `FE-22` 新增 / 改名路由必须同步：`routes.ts`、`router.tsx`、`nav-config.ts`、页面目录、面包屑、单测、e2e、开发计划附录 C。

---

## 5　新增页面检查清单

- [ ] 模块 key / 基础路径 / 页面目录能在 §1 表中查到；
- [ ] 路径符合 §2（复数、kebab-case、`/new`、`:id`、无动词、无尾斜杠）；
- [ ] 路由常量集中在 `routes.ts`，无散落字符串；
- [ ] 导航、面包屑、页面标题与路由一致；
- [ ] 页面目录为 `pages/<模块>/<功能>/`，入口命名为 `<Feature>Page.tsx`；
- [ ] 权限点与守卫齐全，无权限进 403；
- [ ] 旧路径（如有）加重定向与测试；
- [ ] 单测覆盖路由常量 / 导航 / 守卫；e2e 覆盖真实跳转；
- [ ] 开发计划附录 C 与实施报告已同步。

---

## 6　附：模块路径全表（当前）

| 模块 | 功能路径 |
| --- | --- |
| 脚本 | `/scripts/library`、`/scripts/framework-cards`、`/scripts/templates`、`/scripts/batch`、`/scripts/review` |
| 素材 | `/material/image-compose`、`/material/video`、`/material/tasks`、`/material/quick-review`、`/material/preview` |
| 资产 | `/assets/library`、`/assets/templates`、`/assets/pools`、`/assets/prompts` |
| 交付 | `/delivery/export`、`/delivery/records`、`/delivery/manifests` |
| 管理中心 | `/system/users`、`/system/roles`、`/system/customers`、`/system/industries`、`/system/dicts`、`/system/audit-logs`、`/system/ai`、`/system/settings`、`/system/industry-packs`、`/system/forms`、`/system/customer-fields`、`/system/compliance` |

## 7　修订记录

| 版本 | 日期 | 变更 |
| --- | --- | --- |
| V1.0 | 2026-11-03 | 初版：模块表、路径语法、目录映射、路由注册、旧链重定向与检查清单；管理中心由「平台」改名，A1 用户页迁移至 `/system/users` 与 `pages/system/users/` |