# data-model

## Overview

本 feature 不引入业务数据库实体变更。`data-model.md` 用于描述本轮协作整理涉及的文档实体、页面样例实体、权限边界实体与 evidence 实体，作为 tasks 拆分、实施回写和验收对照的语义模型。

## Entities

### 1. Frontend Collaboration Entry

**Description**

- 前端仓中的入口说明文件，用于约束代理如何引用正式 spec 工件，以及何时留在前端仓、何时回到 `water-docs`。

**Instances in scope**

- `../water-frontend/AGENTS.md`
- `../water-frontend/CLAUDE.md`

**Fields**

- `repoScope`: 适用仓库范围
- `sourceOfTruth`: 正式工件来源声明
- `featurePathRule`: `spec / plan / tasks` 相对路径引用规则
- `docsPathRule`: `../water-docs/docs/` 的正式文档定位规则
- `executionBoundary`: frontend 执行任务 vs `water-docs` 执行任务边界
- `templateGuideEntry`: 模板规则文件入口
- `templateIndexEntry`: 样例索引文件入口
- `validationRule`: 最小验证要求

**Validation rules**

- 必须显式声明 `water-docs` 为正式 Speckit 单一来源。
- 必须包含 `../water-docs/specs/<feature>/` 与 `../water-docs/docs/` 的稳定相对路径规则。
- 不得要求在 `water-frontend` 新建第二套 `.specify/`。

### 2. Template Guide

**Description**

- 前端页面模板化规则文件，用于定义页面分类、语义角色、命名规则、模板元模型、权限边界与选型规则。

**Instance in scope**

- `../water-frontend/FRONTEND_PAGE_TEMPLATE_GUIDE.md`

**Fields**

- `templateCategories`: 模板分类清单
- `semanticRoles`: 页面语义角色定义
- `namingRules`: 命名与目录约定
- `metaModels`: 高频模板元模型
- `permissionBoundaries`: 权限边界定义
- `generationChecklist`: 页面生成输入清单
- `selectionRules`: 模板选型决策规则
- `motherboardSelection`: 母板页选择步骤

**Validation rules**

- 必须覆盖 spec 中要求的主要模板类别。
- 必须提供必备区块、推荐组件、推荐变量名、推荐 API 命名、推荐权限接入点。
- 必须区分普通业务表单、列表列可见配置、BPM 字段权限边界。
- 必须被前端入口文件统一引用。

### 3. Template Index Entry

**Description**

- 将真实 `src/views` 页面映射到模板类型的索引条目，是“规则层”与“实际样例层”的桥接对象。

**Instance in scope**

- `../water-frontend/FRONTEND_PAGE_TEMPLATE_INDEX.md`

**Fields**

- `templateType`: 模板类型
- `domain`: 业务域
- `pageName`: 代表页面名称
- `pagePath`: 页面路径
- `companionComponents`: 配套组件 / 子块
- `classificationEvidence`: 判定依据
- `motherboardPriority`: `P0 / P1 / P2`
- `primaryTemplate`: 主模板
- `secondaryTemplates`: 辅模板列表
- `reuseAdvice`: 复用建议

**Validation rules**

- 每个高频模板至少有一个可追溯代表页。
- `P0` 条目应优先对应结构最稳定、复用价值最高的页面。
- 索引必须支持“一页多模板参考”的表达方式。
- 索引只做样例映射，不扩写新的权限或架构结论。

### 4. Permission Source

**Description**

- 登录后进入前端状态管理的权限相关数据集合。

**Evidence sources**

- `../water-frontend/src/store/modules/user.ts`
- `../water-frontend/src/store/modules/permission.ts`
- `../water-frontend/src/permission.ts`

**Fields**

- `roles`: 角色集合
- `permissions`: 按钮 / 操作权限集合
- `menus`: 动态菜单与路由数据
- `cacheLocation`: 前端缓存位置
- `routeGeneration`: 动态路由生成入口

**Relationships**

- 被 `Frontend Collaboration Entry` 与 `Template Guide` 用于权限边界说明。
- 被页面按钮与路由生成逻辑消费。

### 5. Field-level Permission Capability

**Description**

- 用于区分当前前端不同层次字段 / 列级控制能力边界的对象集合。

**Subtypes**

- `ColumnVisibilityConfiguration`
- `BpmFieldPermission`
- `GenericBusinessFormFieldPermission`

### 5.1 ColumnVisibilityConfiguration

- `scene`: 列表列显示、打印、顺序、宽度
- `storageMode`: 后端持久化，必要时可回退到本地存储
- `apiEntry`: `../water-frontend/src/api/system/userFormConfig.ts`
- `consumerEntry`: `../water-frontend/src/components/ColumnSetting/hooks/useColumnSettingStorage.ts`
- `appliesTo`: 列表页列级控制

### 5.2 BpmFieldPermission

- `scene`: BPM 流程表单字段可编辑 / 只读 / 隐藏
- `scope`: 仅 BPM 场景有效
- `consumerEntry`: `../water-frontend/src/views/bpm/processInstance/create/ProcessDefinitionDetail.vue`
- `appliesTo`: 流程发起 / 审批 / 详情页中的流程表单

### 5.3 GenericBusinessFormFieldPermission

- `scene`: 普通业务表单字段级控制
- `currentState`: 未发现可直接复用的全局通用框架
- `warning`: 不得把局部页面显隐逻辑误写为平台级字段权限能力

**Validation rules**

- 交付文本不得把三个子类型混写成一个概念。
- 未证实的普通业务字段权限不得被表述为现成能力。

### 6. Verification Artifact

**Description**

- 固定 baseline、验证结果与最终 verdict 的 evidence 实体。

**Instances in scope**

- `specs/011-frontend-speckit-alignment/baseline.md`
- `specs/011-frontend-speckit-alignment/docs-validation.md`
- `specs/011-frontend-speckit-alignment/final-verdict.md`

**Fields**

- `validationDimensions`: 五个必检维度
- `commandSet`: 最小验证命令集合
- `governanceDecision`: 是否更新项目进度与任务清单的结论
- `storyVerdicts`: US1 / US2 / US3 的验收结果

**Validation rules**

- 必须覆盖 relative-path readability、entry-rule consistency、independent-guide discoverability、sample-category mappability、permission-conclusion traceability 五个维度。
- 必须记录为何本轮 `01_Project_Progress.md` 与 `03_Task_Checklist.md` 保持不变。

## Relationships

- `Frontend Collaboration Entry` 引用 `Template Guide` 与 `Template Index Entry`。
- `Template Guide` 约束 `Template Index Entry` 的分类规则与母板页选择步骤。
- `Template Index Entry` 以 `Representative Sample` 形式回扣真实页面。
- `Permission Source` 与 `Field-level Permission Capability` 共同构成权限边界说明的证据基础。
- `Verification Artifact` 负责验证以上实体在最终交付中的一致性、可发现性与可追溯性。