Stev_Wang
a1e28daec5
ci / 质量门禁 (push) Canceled after 0s
背景： - 前端路由缺少统一规范：导航模块 key 与 URL 首段不一致，页面目录未镜像 路由，04 规范中的历史路由示例与实际实现不符； - 用户确认「平台」更名为「管理中心」，路由统一为 /<模块>/<功能>。 改动： - 新增 11-前端路由与目录规范：模块与基础路径表、路径语法（复数 kebab-case、 /new、:id、层级与 query 状态）、pages/<模块>/<功能>/ 目录映射、路由注册、 旧链重定向、新增页面检查清单； - 04 §8 的 API-27 改为模块化路由并链接 11；工程规范索引与 AGENTS §9 登记 11； - 开发计划：平台更名管理中心，附录 C 页面清单收敛为模块化路由，§7.1 / §8.3 同步，版本记录补「路由规范回写」； - A1 实施报告路由说明更新为 /system/users（旧 /users* 重定向）。 影响面： - 仅文档与规范，不改变功能范围、权限点与后端接口；后续批次按 11 执行。 回滚方式： - 回滚本提交即恢复原附录 C 与 04 §8 描述；代码不受影响。 验证证据： - pnpm format:check 通过；路由与代码行为见相邻的 web 重构提交。
126 lines
7.1 KiB
Markdown
126 lines
7.1 KiB
Markdown
# 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/` |
|