docs(routing): 新增前端路由与目录规范并收敛计划路由

背景： - 前端路由缺少统一规范：导航模块 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 重构提交。
2026-11-03 10:30:55 +08:00
1 parent f8b6232b4c
commit a1e28daec5
@@ -0,0 +1,125 @@
+# 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/` |