fujian_water_biz_doc/specs/011-frontend-speckit-alignment/docs-validation.md

docs-validation

Validation scope

本次校验覆盖以下正式交付目标：

1. water-frontend 入口文件是否能正确回指 water-docs 的正式 Speckit 工件。
2. 页面模板规范是否已经抽离为独立规则文件，且入口说明保持一致。
3. 是否补充了“实际页面样例到模板类型”的索引文件，并支持一页多模板参考。
4. 权限边界说明是否保持证据可追溯，不引入新的错误结论。
5. 本轮 evidence 是否明确记录治理台账不更新的原因。

Checked documents

water-frontend

• ../water-frontend/AGENTS.md
• ../water-frontend/CLAUDE.md
• ../water-frontend/FRONTEND_PAGE_TEMPLATE_GUIDE.md
• ../water-frontend/FRONTEND_PAGE_TEMPLATE_INDEX.md

water-docs

• specs/011-frontend-speckit-alignment/spec.md
• specs/011-frontend-speckit-alignment/research.md
• specs/011-frontend-speckit-alignment/data-model.md
• specs/011-frontend-speckit-alignment/quickstart.md
• specs/011-frontend-speckit-alignment/baseline.md
• specs/011-frontend-speckit-alignment/docs-validation.md
• specs/011-frontend-speckit-alignment/final-verdict.md

Command execution

本轮按计划执行以下最小文档校验命令：

• 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

Five required validation dimensions

1. Relative-path readability

Result: Pass

Evidence

• ../water-frontend/AGENTS.md 明确给出 ../water-docs/specs/<feature>/spec.md、plan.md、tasks.md 的读取顺序。
• ../water-frontend/CLAUDE.md 明确给出相同的相对路径规则，并补充 ../water-docs/docs/ 为正式设计资料位置。
• specs/011-frontend-speckit-alignment/quickstart.md 明确区分 water-docs 与 water-frontend 的阅读入口。

Conclusion

从 frontend 根目录出发，可以稳定定位 formal specs/ 与 docs/。

2. Entry-rule consistency

Result: Pass

Evidence

• AGENTS.md 与 CLAUDE.md 都明确要求：正式 Speckit、治理台账、最终验收结论必须回到 water-docs。
• 两个入口文件都明确禁止在 water-frontend 新建或维护第二套 .specify/。
• quickstart.md 与 research.md 对启动边界保持同一口径。

Conclusion

frontend 侧不存在平行正式流程入口。

3. Independent-guide discoverability

Result: Pass

Evidence

• AGENTS.md 与 CLAUDE.md 都把 FRONTEND_PAGE_TEMPLATE_GUIDE.md、FRONTEND_PAGE_TEMPLATE_INDEX.md 标记为模板规范统一入口。
• quickstart.md 把 guide 与 index 列为 frontend 侧的必读文件。
• FRONTEND_PAGE_TEMPLATE_GUIDE.md 已完整承接分类规则、元模型、命名规则与权限边界。

Conclusion

模板规范已经独立可发现，不再依赖入口文件内嵌大段正文。

4. Sample-category mappability

Result: Pass

Evidence

• FRONTEND_PAGE_TEMPLATE_INDEX.md 已按模板类型、业务域、代表页面、页面路径、配套组件、母板优先级和复用建议建立映射。
• 索引已覆盖 spec 要求的主要模式，并额外覆盖详情页、报表容器、登录容器、组合工作台。
• 索引新增“主模板 / 辅模板”使用方式，能说明一页多模板参考。

Conclusion

实现人员可以先选模板类型，再快速定位母板页和辅助样例。

5. Permission-conclusion traceability

Result: Pass

Evidence

• research.md 与 data-model.md 都显式列出权限证据路径：
  • 用户信息与权限集合：src/store/modules/user.ts
  • 动态路由：src/store/modules/permission.ts、src/permission.ts
  • 按钮 / 角色权限：src/directives/permission/hasPermi.ts、src/directives/permission/hasRole.ts
  • 数据权限：src/api/system/permission/index.ts、src/views/system/role/RoleDataPermissionForm.vue
  • 列可见配置：src/api/system/userFormConfig.ts、src/components/ColumnSetting/hooks/useColumnSettingStorage.ts
  • BPM 字段权限：src/views/bpm/processInstance/create/ProcessDefinitionDetail.vue
• FRONTEND_PAGE_TEMPLATE_GUIDE.md 保持“普通业务表单无全局通用字段权限框架”的边界说明。

Conclusion

权限结论可回扣到具体代码路径，没有把未证实能力误写为已具备能力。

Mapping summary

推荐优先复用的母板页如下：

• 标准列表查询页：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

Governance applicability

• docs/design/00_Management/01_Project_Progress.md：保持不变
• docs/design/00_Management/03_Task_Checklist.md：保持不变

Reason

本轮交付边界限定为 frontend 协作入口、模板规则、样例索引与 feature evidence 收口，不涉及正式主设计文档修订或跨 feature 治理台账变更。

Follow-up notes

• 当前索引覆盖的是高频样例，不是 src/views 的全量页面清单；后续如出现新的高频页面模式，应增量维护。
• 当前仍未发现“普通业务表单的全局通用字段权限框架”，本结论未被本轮改动推翻。