leaudit-platform-frontend/docs/route-alias-guidelines.md

Route Alias 约束文档

目标

app/utils/route-alias.shared.js 只解决一类问题：
“功能子页没有独立菜单入口，但它在权限上应明确复用某个父页面/父模块的能力”。

它不是通用兜底，也不应该替代真正的菜单建模。

---

什么时候应该加 alias

满足以下条件时，优先加 alias：

1. 页面是父页面的派生操作页

   • 例如：/document-types/new、/rules/new、/documents/edit
   • 这类页面本质上是列表页的“新建 / 编辑 / 复制 / 查看详情”能力延伸

2. 页面不需要在侧边栏单独展示

   • 用户不需要从菜单直接点击进入
   • 通常只会从父列表页按钮跳转进入

3. 页面权限应该与父页面完全一致

   • 例如“能看列表的人才能进编辑页”
   • 不需要单独拆出新的菜单权限或模块权限

4. 页面属于同一业务模块内部流转

   • 例如：搜索结果页、详情页、起草页，统一归属合同模板模块

---

什么时候不应该加 alias，而应该直接补菜单路由

出现以下任一情况时，不要加 alias，要去补菜单路由 / 后端路由定义 / permissionMap：

1. 页面本身应该在导航中独立出现

   • 例如：/cross-checking/upload
   • 用户需要从侧边栏或首页快捷入口直接访问

2. 页面权限和父页面不一致

   • 例如列表可看，但新建需要更高权限
   • 这时必须单独建权限点，不能简单复用父页

3. 页面是稳定的一级/二级业务页面

   • 不是“新建 / 编辑 / 详情”这类派生页
   • 而是一个真实存在、长期运营的功能节点

4. 页面需要独立的按钮权限、接口权限或审计语义

   • 如果未来要单独授权、单独统计、单独审计，就不该藏在 alias 里

---

判断原则

可以用一句话判断：

• 如果这是“父页的一个动作结果页”，加 alias
• 如果这是“系统里一个真正独立的功能页”，补菜单路由

---

当前已覆盖的典型场景

• 新建/编辑类

  • /entry-modules/new -> /entry-modules
  • /document-types/new -> /document-types
  • /config-lists/new -> /config-lists
  • /prompts/new -> /prompts
  • /rule-groups/new -> /rule-groups
  • /rules/new -> /rules
  • /documents/list -> /documents
  • /documents/edit -> /documents

• 模块内子页

  • /contract-template/search/results -> /contract-template/search
  • /contract-template/detail/:id -> /contract-template/list
  • /contract-draft/:id -> /contract-template/list
  • /chat-with-llm/chat -> /chat-with-llm
  • /chat-with-llm/dataset-manager -> /chat-with-llm

• 历史兼容页

  • /reviewsTest -> /reviews
  • /rulesTest/list -> /rules
  • /rulesTest/detail -> /rules

---

新增 alias 时必须同步做的事

1. 在 app/utils/route-alias.shared.js 添加规则
2. 写清 note
3. 为该规则添加 examples
4. 执行：

cd new_doc_review
npm run test:route-aliases

---

反例

以下情况不要用 alias 硬压过去：

• 访问 /some-page/create 被拒，就直接映射到 /some-page
• 访问 /settings/xxx 被拒，就全部映射到 /settings

如果这个子页未来可能独立授权、独立显示、独立审计，那就应该补真实路由，而不是继续堆 alias。