# research

## Research scope

本研究用于支撑 `011-frontend-speckit-alignment` 的实施阶段，聚焦以下问题：

1. 前端仓如何稳定回指 `water-docs` 的正式 Speckit 工件。
2. 页面模板规范与样例索引如何分层，避免入口文件膨胀。
3. 实际页面样例如何组织成可复用的模板索引，并支持一页多模板参考。
4. 当前权限边界在普通页面、列表列配置与 BPM 场景之间应如何准确表述。

## Decision 1: `water-docs` 继续作为正式 Speckit 单一真源

**Decision**

- 正式 `spec / plan / tasks / baseline / docs-validation / final-verdict` 全部继续落在 `water-docs/specs/011-frontend-speckit-alignment/`。
- `water-frontend` 只承载实现侧入口说明、模板规则与样例索引，不复制 `.specify/`，也不维护第二套正式流程。
- `AGENTS.md` 与 `CLAUDE.md` 必须把“从 frontend 启动”和“回 docs 启动”的边界写成相同口径。

**Rationale**

- 该工作本质是多仓协作规则整理，不是单独的前端局部优化。
- `water-docs` 根仓的 `.specify/` 已是唯一正式流程入口，继续复用能避免前端仓和平行 docs 口径分叉。
- frontend 只保留实施入口，能让实现人员在正确位置读取正式文档，而不把 spec 工件散落到代码仓。

**Alternatives considered**

- 在 `water-frontend` 新建独立 `.specify/`：拒绝，破坏单一事实来源。
- 将 spec 只保留在前端仓：拒绝，本 feature 同时约束 docs 与 frontend 两边协作方式。

## Decision 2: 模板规范采用“规则文件 + 样例索引文件”双层结构

**Decision**

- `FRONTEND_PAGE_TEMPLATE_GUIDE.md` 作为规则层，承载模板分类、元模型、命名规则、权限边界与选型规则。
- `FRONTEND_PAGE_TEMPLATE_INDEX.md` 作为样例层，承载 `src/views` 到模板类型的实际映射、母板页优先级、主模板/辅模板关系与复用建议。
- `AGENTS.md` 与 `CLAUDE.md` 只做入口，不再重复内嵌大段模板分类正文。

**Rationale**

- 仅有规则文件时，实现人员仍需要自己搜索真实样例。
- 仅有样例索引时，又无法得到统一的命名、目录与权限接入规范。
- 双层结构既能定义规则，又能快速回扣现有母板页。

**Alternatives considered**

- 把全部内容塞回 `AGENTS.md` / `CLAUDE.md`：拒绝，入口文件会再次膨胀。
- 只保留 guide，不单独建 index：拒绝，无法满足“可复用样例映射”和“母板页优先级”要求。

## Decision 3: 页面分类按交互结构组织，并允许一页多模板参考

**Decision**

- 页面模板分类维持按交互结构划分，而不是按业务域命名：
  - 标准列表查询页
  - 左树右表页
  - 左树右详情维护页
  - 弹窗表单页
  - 导入上传页
  - 详情展示页
  - 配置 / 权限页
  - BPM / 流程页
  - 报表 / 可视化容器页
  - 登录 / 认证容器页
  - 组合容器 / 工作台页
- 对同时包含查询列表、弹窗表单、导入动作的页面，先确定主模板，再补充辅模板参考，不强行要求单一分类。

**Rationale**

- 同一业务域常同时包含多种页面交互形态。
- 页面生成与样例复用更依赖交互骨架，而不是模块名称。
- 允许“一页多模板参考”，能更准确映射 `system/user`、`settings/priceTemplate` 等复合页面。

**Alternatives considered**

- 按业务模块分类：拒绝，不能直接指导页面骨架复用。
- 按组件技术碎片分类：拒绝，过于细碎，不利于协作入口阅读。

## Decision 4: 权限结论以代码证据为准，不扩写未证实能力

**Decision**

- 计划和后续任务保持以下权限边界：
  - 角色权限：已存在
  - 按钮权限：已存在
  - 菜单 / 路由权限：已存在
  - 数据权限：已存在
  - 列表列可见配置：已存在，且为后端持久化能力
  - BPM 字段权限：已存在，仅限 BPM 场景
  - 普通业务表单全局字段权限框架：当前未发现通用实现

**Evidence paths**

- 用户信息与权限集合加载：`../water-frontend/src/store/modules/user.ts`
- 菜单路由缓存与动态路由生成：`../water-frontend/src/store/modules/permission.ts`、`../water-frontend/src/permission.ts`
- 按钮权限指令：`../water-frontend/src/directives/permission/hasPermi.ts`
- 角色权限指令：`../water-frontend/src/directives/permission/hasRole.ts`
- 角色菜单/数据权限 API：`../water-frontend/src/api/system/permission/index.ts`
- 数据权限页面消费：`../water-frontend/src/views/system/role/RoleDataPermissionForm.vue`
- 菜单权限与权限标识录入：`../water-frontend/src/views/system/menu/MenuForm.vue`
- 列可见配置 API 与前端存取：`../water-frontend/src/api/system/userFormConfig.ts`、`../water-frontend/src/components/ColumnSetting/hooks/useColumnSettingStorage.ts`
- BPM 字段权限消费：`../water-frontend/src/views/bpm/processInstance/create/ProcessDefinitionDetail.vue`

**Rationale**

- spec 已明确要求不能把未证实的能力描述为已具备。
- 当前工作只需要如实表达边界，不新增权限模型设计。

**Alternatives considered**

- 统一称“字段权限不存在”：拒绝，BPM 字段权限与列表列配置都属于已存在能力。
- 直接规划普通业务表单字段权限：拒绝，超出本轮 feature 范围。

## Decision 5: `contracts/` 保留目录，但本 feature 不新增外部接口契约

**Decision**

- 本 feature 保留 Speckit 标准 `contracts/` 目录结构，但不新增 API / CLI / 外部系统契约文件。
- 前端协作入口、模板规范与样例索引约束由 `plan.md`、`quickstart.md` 与前端 Markdown 文件承接。

**Rationale**

- 本轮交付对象是文档规范与协作方式，而不是新增系统接口。
- 强行编造 OpenAPI 或伪契约不会提升可实施性，反而会引入假细节。

**Alternatives considered**

- 创建伪 API contract：拒绝，与 feature 无关。
- 完全跳过 `contracts/` 目录：不采用，保留标准目录结构更利于后续延展。

## Decision 6: 验证以文档一致性与 evidence 闭环为主

**Decision**

- 本轮主要验证产物为：
  - `baseline.md`
  - `docs-validation.md`
  - `final-verdict.md`
- 最小文档校验命令固定为：
  - `make validate-file FILE=specs/011-frontend-speckit-alignment/quickstart.md`
  - `make validate-file FILE=specs/011-frontend-speckit-alignment/data-model.md`
  - `make validate-file FILE=specs/011-frontend-speckit-alignment/research.md`
  - `make validate-file FILE=specs/011-frontend-speckit-alignment/docs-validation.md`
  - `make check-links`
- 不强制执行 frontend build / lint，因为本轮未触达 Vue 业务代码。

**Rationale**

- 变更范围仅涉及 Markdown 协作文件与规范文件。
- spec 已将交付边界限定为前端协作说明、独立规范文件与 evidence 工件。

**Alternatives considered**

- 强制跑前端构建：未采用，与当前改动无直接关联。
- 不做任何 evidence：拒绝，无法满足 spec 对可追溯验证的要求。

## Research conclusion

本 feature 的实施路径已经明确：

1. 在 `water-docs` 保持正式 `spec / plan / tasks / evidence` 单一真源。
2. 在 `water-frontend` 形成：
   - 入口规则：`AGENTS.md`、`CLAUDE.md`
   - 模板规则文件：`FRONTEND_PAGE_TEMPLATE_GUIDE.md`
   - 样例索引文件：`FRONTEND_PAGE_TEMPLATE_INDEX.md`
3. 对权限边界严格按代码证据回写，不把普通业务表单字段权限误写为既有能力。
4. 用 `baseline.md`、`docs-validation.md`、`final-verdict.md` 固定基线、验证与最终结论，不更新本轮不适用的治理台账。