# 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` 的全量页面清单；后续如出现新的高频页面模式，应增量维护。
- 当前仍未发现“普通业务表单的全局通用字段权限框架”，本结论未被本轮改动推翻。