fujian_water_biz_doc/specs/011-frontend-speckit-alignment/data-model.md

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 负责验证以上实体在最终交付中的一致性、可发现性与可追溯性。