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

# Feature Specification: 前端 Speckit 协作对齐

**Feature Branch**: `[011-frontend-speckit-alignment]`
**Created**: 2026-03-24
**Status**: Draft
**Input**: User description: "我需要让前端的 的目录下CLUAD.md 与 AGENT.md 更友好的支持 speckit 可以正确的引用water-docs 里的目录,以及前端的生成应该模板化,你可以先看下前端下面有哪些类似与样例的,可以怎么分类? 以及权限是怎么弄的?权限来自于哪里?有没有字段权限的控制?"

## Document Scope & Sources *(mandatory)*

- **Target documents**:
  - `specs/011-frontend-speckit-alignment/spec.md`
  - `../water-frontend/AGENTS.md`
  - `../water-frontend/CLAUDE.md`
  - `../water-frontend/FRONTEND_PAGE_TEMPLATE_GUIDE.md`
- **Primary source of truth**:
  - `CLAUDE.md`
  - `docs/design/00_Management/01_Project_Progress.md`
  - `docs/design/00_Management/03_Task_Checklist.md`
  - `../water-frontend/AGENTS.md`
- **Reference sources**:
  - `../water-frontend/src/views/system/user/index.vue`
  - `../water-frontend/src/views/system/user/UserForm.vue`
  - `../water-frontend/src/views/custData/custCreate/components/ImportForm.vue`
  - `../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`
  - `../water-frontend/src/api/system/permission/index.ts`
  - `../water-frontend/src/views/system/role/RoleDataPermissionForm.vue`
  - `../water-frontend/src/views/system/menu/MenuForm.vue`
  - `../water-frontend/src/api/system/userFormConfig.ts`
  - `../water-frontend/src/components/ColumnSetting/hooks/useColumnSettingStorage.ts`
  - `../water-frontend/src/views/bpm/processInstance/create/ProcessDefinitionDetail.vue`
  - `../water-backend/sw-module-system/sw-module-system-server/src/main/java/cn/com/emsoft/sw/module/system/dal/dataobject/userformconfig/UserFormConfigDO.java`
  - `../water-backend/sw-module-system/sw-module-system-server/src/main/java/cn/com/emsoft/sw/module/system/controller/admin/userformconfig/vo/UserFormConfigBatchSaveReqVO.java`
  - `../water-backend/sw-module-bpm/sw-module-bpm-api/src/main/java/cn/com/emsoft/sw/module/bpm/enums/definition/BpmFieldPermissionEnum.java`
  - `../water-backend/sw-module-bpm/sw-module-bpm-server/src/main/java/cn/com/emsoft/sw/module/bpm/controller/admin/task/vo/instance/BpmApprovalDetailRespVO.java`
- **Scope decision**: 本需求在范围内，目标是形成前端仓库可直接执行的协作说明与模板化分类依据，使代理从 `water-frontend` 启动时也能正确回指 `water-docs` 的正式规格工件，并对当前权限模型给出可追溯结论。

## Repository Scope *(mandatory)*

- **Target repos**:
  - `water-docs`: Required
  - `water-backend`: Not Required
  - `water-frontend`: Required
- **Expected delivery type**: Mixed
- **Out of scope for this round**:
  - 后端权限模型改造
  - 前端业务页面代码生成器的实际开发
  - 新增字段级权限能力
  - 对既有业务页面的大规模重构
  - 在 `water-frontend` 新建独立 `.specify/` 流程

## Code Baseline *(mandatory for brownfield work)*

- **Backend baseline**: N/A
- **Frontend baseline**: `ae6593904544` / `develop`
- **Baseline capture rule**: 所有关于样例分类、权限来源、数据权限与字段权限结论，均以本次读取到的前端基线代码为准；若后续实施时基线变化，需要在验证工件中重新记录并说明差异。

## Evidence Scope *(mandatory)*

- **Document evidence required**:
  - 本 feature 的 `spec.md`
  - 后续 `plan.md`
  - 后续 `tasks.md`
  - 前端仓库协作说明改动后的差异说明
  - 独立页面模板规范文件 `../water-frontend/FRONTEND_PAGE_TEMPLATE_GUIDE.md`
- **Backend evidence required**: N/A
- **Frontend evidence required**:
  - `AGENTS.md` 与 `CLAUDE.md` 中对 `water-docs` 引用规则的落地结果
  - 前端页面/表单样例分类清单及对应示例路径
  - 当前权限来源、菜单权限、角色权限、数据权限、字段权限结论的证据回扣
- **Verification artifacts required**:
  - `baseline.md`
  - `docs-validation.md`
  - `final-verdict.md`

## User Scenarios & Testing *(mandatory)*

### User Story 1 - 前端仓库可正确回指正式规格 (Priority: P1)

作为在 `water-frontend` 仓库中启动代理的实现人员，我需要从仓库入口说明中快速找到 `water-docs` 中的正式规格、计划和任务文件，这样就不会在错误目录中生成流程工件，也不会引用错误的来源资料。

**Why this priority**: 这是后续所有实现、联调和验收工作的前提；如果入口规则不清晰，会直接导致规格引用错误、流程分叉和回写缺失。

**Independent Test**: 仅阅读更新后的前端仓库入口说明，验证审阅者是否能明确回答“正式 spec/plan/tasks 在哪里”“前端实现何时从 frontend 启动、何时必须回到 water-docs 启动”。

**Acceptance Scenarios**:

1. **Given** 代理从 `water-frontend` 根目录启动，**When** 它需要查找正式需求规格，**Then** 它能直接定位到 `../water-docs/specs/<feature>/spec.md`、`plan.md`、`tasks.md` 的引用规则。
2. **Given** 代理需要执行 Speckit 相关正式流程，**When** 它阅读前端仓库入口说明，**Then** 它会回到 `water-docs` 而不是在前端仓库新建并维护平行流程工件。
3. **Given** 代理需要判断页面类型、目录结构、命名方式或权限边界，**When** 它读取前端仓库入口说明，**Then** 它会继续读取独立规范文件 `FRONTEND_PAGE_TEMPLATE_GUIDE.md`，而不是依赖分散在多个入口文件中的重复规则。

---

### User Story 2 - 前端生成样例形成模板化分类 (Priority: P2)

作为要扩展前端页面的实现人员，我需要知道当前前端仓库已有的典型页面、表单和导入场景样例如何分类，以及每一类应参考哪些已有页面，这样新增页面时可以优先复用现有模式而不是重新发明结构。

**Why this priority**: 模板化分类可以降低页面实现的不一致性，减少搜索成本，并为后续生成型工作提供稳定的参照类别。

**Independent Test**: 仅根据分类说明，验证审阅者能否把至少一个“列表查询页”、一个“弹窗表单”、一个“导入表单”、一个“权限配置页”映射到现有样例路径。

**Acceptance Scenarios**:

1. **Given** 实现人员需要新增标准后台页面，**When** 它查看样例分类说明，**Then** 它能区分列表查询、弹窗表单、导入表单、树形配置、权限配置等主要类别，并找到每类代表样例。
2. **Given** 实现人员需要生成新页面，**When** 它根据分类说明选择模板类别，**Then** 它不会把不适合的样例错误地作为基线模式。

---

### User Story 3 - 权限能力边界可被准确说明 (Priority: P3)

作为实现人员或评审人员，我需要在开始页面开发前明确当前前端权限来自哪里、页面按钮权限与数据权限如何生效、是否已有字段级权限控制，这样就不会对现有能力作出超出事实的假设。

**Why this priority**: 权限认知错误会直接影响页面可见性、操作按钮、数据范围和需求评估，属于高风险误判点。

**Independent Test**: 仅根据规格与后续实施说明，验证审阅者能否明确回答权限数据来源、按钮权限的使用方式、数据权限的现状，以及字段级权限是否存在现成控制能力。

**Acceptance Scenarios**:

1. **Given** 实现人员要给页面增加操作按钮，**When** 它查看权限说明，**Then** 它能知道按钮权限由用户权限集合驱动，并通过既有页面模式进行控制。
2. **Given** 实现人员要判断是否能直接做字段级隐藏或只读控制，**When** 它查看权限说明，**Then** 它能知道当前基线是否已有现成字段权限能力，若没有则不会误判为已支持。

---

### Edge Cases

- 前端仓库根目录当前没有 `CLAUDE.md` 时，协作说明仍需保证代理有单一、稳定的入口规则。
- 当某个页面同时包含查询列表、弹窗表单和导入动作时，分类规则需要允许“一页多模板参考”，而不是强制归为单一类别。
- 当菜单权限、按钮权限、数据权限、列表列可见配置和 BPM 字段权限来自不同代码路径时，说明文档需要明确区分来源，避免把它们混为一种能力。
- 当当前基线未能证明“普通业务表单”的通用字段权限能力时，交付结论必须明确标记其边界；但若 BPM 场景字段权限或列表列可见配置已存在，也必须如实说明，不得一概表述为“字段权限不存在”。

## Requirements *(mandatory)*

### Functional Requirements

- **FR-001**: 规格必须明确前端仓库中用于承接协作规则的目标文件，并将 `water-docs` 明确标注为正式规格、计划、任务的单一权威来源。
- **FR-002**: 规格必须定义从 `water-frontend` 启动代理时，何种任务留在前端仓库执行，何种任务必须回到 `water-docs` 启动。
- **FR-003**: 规格必须要求前端仓库说明提供稳定的相对路径引用规则，使代理能够从前端仓库正确定位 `water-docs/specs/` 与 `water-docs/docs/`。
- **FR-004**: 规格必须要求将页面模板化分类、语义化页面规范、命名约定与权限边界抽离到独立规范文件中，并由 `AGENTS.md` 与 `CLAUDE.md` 统一引用。
- **FR-005**: 规格必须要求对当前前端页面/表单样例进行模板化分类，并为每个主要类别给出至少一个现有样例路径作为参考。
- **FR-006**: 规格必须要求模板化分类至少覆盖列表查询页、弹窗表单、导入表单、树形配置或权限配置等当前仓库中已存在的主要模式。
- **FR-007**: 规格必须要求独立规范文件提供高频页面的模板元模型，包括必备区块、推荐组件、推荐变量名、推荐 API 命名和推荐权限接入点。
- **FR-008**: 规格必须要求权限说明明确区分角色权限、按钮权限、菜单/路由权限、数据权限、列表列可见配置和 BPM 场景字段权限，不得将不同层级的权限能力混写。
- **FR-009**: 规格必须记录当前权限来源的代码证据，包括用户信息加载、权限集合缓存、菜单路由生成、页面权限校验、列表列配置保存/读取以及 BPM 字段权限返回与消费的来源路径。
- **FR-010**: 规格必须明确说明当前基线下字段级控制能力的边界：普通业务表单未见通用字段级权限框架；但 BPM 场景已存在字段可编辑/只读/隐藏能力，列表页已存在后端持久化的列可见配置能力。
- **FR-011**: 规格必须保持单一事实来源原则，不得要求在 `water-frontend` 仓库复制 `.specify/` 流程或创建第二套正式规格入口。
- **FR-012**: 规格必须限定本轮不改造后端权限实现、不新增权限能力，只对协作说明、样例分类、模板规范和现状结论进行整理与约束。
- **FR-013**: 规格必须明确验证范围，至少覆盖相对路径可读性、入口规则一致性、独立规范文件可发现性、样例分类可映射性和权限结论可追溯性。
- **FR-014**: 规格必须说明本轮不要求更新 `docs/design/00_Management/01_Project_Progress.md` 与 `docs/design/00_Management/03_Task_Checklist.md`，因为交付边界限定为前端仓库协作说明、独立规范文件与 spec 工件。

### Key Entities *(include if feature involves data)*

- **Frontend Collaboration Entry**: 前端仓库中的入口说明文件，用于约束代理在何处读取正式规格、何处执行实现任务。
- **Reference Path Rule**: 从 `water-frontend` 指向 `water-docs` 的稳定相对路径约定，用于定位 spec、plan、tasks 与正式文档。
- **Template Category**: 对现有页面/表单样例的归类结果，例如列表查询、弹窗表单、导入表单、树形配置、权限配置。
- **Representative Sample**: 能代表某一模板类别的现有页面或组件路径，用于后续复用和比对。
- **Permission Source**: 登录后加载到前端用户态中的角色、权限集合和菜单数据来源。
- **Data Scope Permission**: 角色层面的数据范围配置能力，例如全部、指定部门、仅本人等范围控制。
- **Column Visibility Configuration**: 由后端持久化并在前端列表中消费的列显示、打印、排序与宽度配置能力。
- **BPM Field Permission**: 仅在 BPM 流程表单场景中生效的字段可编辑、只读、隐藏控制能力。
- **Field-level Permission Capability**: 对页面字段级显示、编辑或只读控制的现成能力；本轮需要区分“普通业务表单的通用能力”与“BPM 场景专用能力”。
- **Verification Artifact**: 记录基线、校验结果与最终结论的工件，用于回扣本次整理结论。

## Assumptions & Dependencies *(optional)*

- `water-frontend` 与 `water-docs` 将继续以同级目录形式存在，允许通过 `../water-docs/` 进行稳定引用。
- 当前前端基线下，用户权限与菜单数据通过登录后的用户信息加载流程进入前端缓存和状态管理。
- 当前基线已存在按钮权限、角色权限和数据权限相关证据；此外还存在后端持久化的列表列可见配置能力，以及 BPM 场景专用的字段可编辑/只读/隐藏能力。
- 当前未见普通业务表单可直接复用的通用字段级权限框架，因此若要在非 BPM 页面引入字段权限，仍需单独规划其模型和消费方式。
- 样例分类仅以当前已存在页面和组件为依据，不扩展到尚未存在的业务模式。

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: 从 `water-frontend` 仓库入口说明出发，审阅者可在一次查阅内明确找到正式 `spec`、`plan`、`tasks` 的权威位置，以及独立页面模板规范文件的位置。
- **SC-002**: 审阅者无需额外口头解释，即可区分至少 4 类前端样例模板，并为每类指出至少 1 个现有代表样例。
- **SC-003**: 审阅者可仅根据交付说明回答以下三个问题：权限来自哪里、按钮/菜单权限如何接入、当前有哪些字段级或列级控制能力以及它们分别适用于哪些场景。
- **SC-004**: 前端仓库协作说明、独立模板规范文件与 `water-docs` 的单一事实来源原则之间不存在冲突或平行入口表述。
- **SC-005**: 高频页面类型具备统一的模板元模型，审阅者可从独立规范文件中直接找到必备区块、推荐变量名、推荐 API 命名和权限接入建议。
- **SC-006**: 本 feature 的最终结论不会把未在当前基线中证实的权限能力描述为已具备能力。