# 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/list`
  - `/documents/edit` -> `/documents`

- 模块内子页
  - `/contract-template/search/results` -> `/contract-template/search`
  - `/contract-template/detail/:id` -> `/contract-template`
  - `/contract-draft/:id` -> `/contract-template`

- 历史兼容页
  - `/reviewsTest` -> `/reviews`
  - `/rulesTest/list` -> `/rules/list`
  - `/rulesTest/detail` -> `/rules/list`

---

## 新增 alias 时必须同步做的事

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

```bash
cd new_doc_review
npm run test:route-aliases
```

---

## 反例

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

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

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