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

quickstart

Goal

在 011-frontend-speckit-alignment feature 下，快速判断应该看哪些文件、从哪里启动、如何选母板页，以及页面权限边界应该怎样判断。

1. 从哪里启动

正式 Speckit / 文档流程

当任务属于以下类型时，从 water-docs 根目录启动：

• 写 / 改 spec.md
• 写 / 改 plan.md
• 写 / 改 tasks.md
• 更新 baseline.md、docs-validation.md、final-verdict.md
• 输出最终验收结论
• 更新治理台账或正式设计文档

正式 feature 目录：

• specs/011-frontend-speckit-alignment/

前端实现 / 页面参考

当任务属于以下类型时，从 water-frontend 根目录启动：

• 新增页面
• 修复前端页面问题
• 对齐页面目录结构
• 选择页面母板页
• 判断页面该接入哪种权限方式
• 查阅真实样例路径并与当前页面做对照

2. 先看哪些文件

在 water-docs 中

优先顺序如下：

1. specs/011-frontend-speckit-alignment/spec.md
2. specs/011-frontend-speckit-alignment/plan.md
3. specs/011-frontend-speckit-alignment/tasks.md
4. specs/011-frontend-speckit-alignment/research.md
5. specs/011-frontend-speckit-alignment/data-model.md
6. specs/011-frontend-speckit-alignment/docs-validation.md
7. specs/011-frontend-speckit-alignment/final-verdict.md

如需查正式设计资料，再看：

• ../water-docs/docs/
• ../water-docs/docs/design/

在 water-frontend 中

1. AGENTS.md
2. CLAUDE.md
3. FRONTEND_PAGE_TEMPLATE_GUIDE.md
4. FRONTEND_PAGE_TEMPLATE_INDEX.md

3. 如何选页面模板

第一步：按交互结构判断主模板

优先判断页面属于：

• 标准列表查询页
• 左树右表页
• 左树右详情维护页
• 弹窗表单页
• 导入上传页
• 详情展示页
• 配置 / 权限页
• BPM / 流程页
• 报表 / 可视化容器页
• 登录 / 认证容器页
• 组合容器 / 工作台页

第二步：到索引表中找母板页

优先找 P0 母板页：

• 标准列表：src/views/infra/config/index.vue
• 左树右表：src/views/system/user/index.vue
• 左树右详情维护：src/views/settings/address/community/index.vue
• 弹窗表单：src/views/infra/config/ConfigForm.vue
• 导入上传：src/views/meterRead/meterEnter/components/ImportForm.vue
• 配置 / 权限页：src/views/system/menu/index.vue
• BPM / 流程页：src/views/bpm/model/index.vue
• 报表容器：src/views/report/goview/index.vue
• 登录容器：src/views/Login/Login.vue
• 工作台容器：src/views/ai/chat/index/index.vue

第三步：如果一页有多种交互，按“主模板 + 辅模板”选样例

常见复合页面判断方式：

• 查询列表 + 新增编辑弹窗：主模板选“标准列表查询页”，辅模板参考“弹窗表单页”
• 查询列表 + 导入：主模板选“标准列表查询页”，辅模板参考“导入上传页”
• 左树右表 + 权限配置弹窗：主模板选“左树右表页”，辅模板参考“配置 / 权限页”
• 流程详情 + 字段权限：主模板选“BPM / 流程页”，不要误套用“普通详情页”

第四步：确认权限边界

新增页面前，先确认属于哪一类权限接入：

• 按钮权限
• 角色权限
• 菜单 / 路由权限
• 数据权限
• 列表列可见配置
• BPM 字段权限

不要默认假设普通业务表单已经存在全局字段权限框架。

4. docs-only 最小验证命令

本 feature 完成后，至少执行以下命令：

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

5. 本 feature 的交付边界

本 feature 当前包含：

• 前端入口文件 Speckit 回指规则
• 模板规范独立化
• 页面模板样例索引
• 权限边界结论整理
• baseline / docs-validation / final-verdict evidence

本 feature 当前不包含：

• 新的前端页面生成器开发
• 普通业务表单字段权限框架开发
• 后端权限模型改造
• 大规模业务页面重构

6. 治理台账边界

本轮不更新以下治理台账：

• docs/design/00_Management/01_Project_Progress.md
• docs/design/00_Management/03_Task_Checklist.md

原因：本轮范围限定为 frontend 入口与 feature evidence 收敛，不涉及正式主文档变更或跨 feature 治理项收口。