fujian_water_biz_doc/specs/011-frontend-speckit-alignment/research.md

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 固定基线、验证与最终结论，不更新本轮不适用的治理台账。