lingxi/docs/工程规范/11-前端路由与目录规范.md

11 · 前端路由与目录规范

项	内容
文档版本	V1.1（2026-11-03）
依据	技术架构 §6 / §10、04 · API 与路由规范 §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 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 API-26 一致）。
• FE-18 路由在 src/router.tsx 集中声明；登录后页面挂在 AppLayout 下，页面级组件使用懒加载。
• FE-19 导航配置 nav-config.ts 的模块 key 与 item path 必须与 routes.ts 一致；面包屑从导航配置派生，禁止在页面内写死。
• FE-20 权限守卫按 04 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/departments、/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/
V1.1	2026-11-03	管理中心补充部门管理 /system/departments（pages/system/departments/），作为 A1 组织架构补强