wang259797/lingxi
1
0 Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
3b0a99d91f36222d978d6bce88bee04e39acbc6f
lingxi/docs/工程规范/11-前端路由与目录规范.md
T
Stev_Wang f849e443d7 refactor(web): 侧栏「用户与组织」更名为「用户管理」 
背景：
- 管理中心侧栏菜单名为「用户与组织」，与「角色管理」「部门管理」的命名方式不一致；
- 页面标题、面包屑仍沿用旧名，三处展示不统一；
- A1 文档与代码注释中该功能域本来即称「用户管理」。

改动：
- nav-config：菜单 label 改为「用户管理」，description 改为「成员账号、部门归属与登录状态」；
- breadcrumbs：用户新建 / 详情子路由的面包屑 2 处同步；
- UsersPage：页面 h1 同步；
- nav-config.spec / breadcrumbs.spec / e2e a1-identity 的标签与 heading 断言同步；
- 11-前端路由与目录规范、AppLayout 注释同步；PRD P-01 功能名保持「用户与组织管理」不变。

影响面：
- 仅前端文案与对应断言；路由、权限点、接口、数据均不变。

回滚方式：
- 回滚本提交即恢复原「用户与组织」文案与断言。

验证证据：
- pnpm format:check / lint / typecheck 通过；
- pnpm test：web 120/120 通过；
- Chrome 1440×900 实机：侧栏、面包屑、页面标题均显示「用户管理」。
2026-11-03 15:54:13 +08:00

7.3 KiB
Raw Blame History

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 组织架构补强
Reference in new issue View Git Blame Copy Permalink