EmailBill/openspec/changes/unified-popup-component/specs/unified-popup-system/spec.md

ADDED Requirements

Requirement: 统一弹窗组件提供底部弹出式容器

系统 SHALL 提供统一的弹窗组件 PopupContainer，支持底部弹出式布局，用于展示表单、列表、详情等内容。

Scenario: 基础弹窗展示

• WHEN 用户触发弹窗打开
• THEN 系统显示底部弹出的弹窗容器，带有圆角和关闭按钮
• THEN 弹窗高度可配置（默认 80%）

Scenario: 弹窗头部固定内容可滚动

• WHEN 弹窗内容超出可视区域
• THEN 弹窗头部保持固定，内容区域可滚动
• THEN 底部页脚（如有）保持固定不可滚动

Requirement: 统一弹窗组件支持标题和副标题

系统 SHALL 允许配置弹窗的标题和副标题，副标题用于显示统计信息或辅助说明。

Scenario: 显示标题和副标题

• WHEN 弹窗配置了标题和副标题
• THEN 标题显示在弹窗头部，字体大小 16px，加粗
• THEN 副标题显示在标题下方，字体大小 14px，居中显示

Scenario: 无副标题时的头部布局

• WHEN 弹窗只配置了标题，未配置副标题
• THEN 标题居中显示
• THEN 如果有操作按钮，操作按钮显示在标题右侧

Requirement: 统一弹窗组件支持头部操作按钮插槽

系统 SHALL 提供 header-actions 插槽，允许在弹窗头部插入自定义操作按钮。

Scenario: 插入头部操作按钮

• WHEN 父组件使用 header-actions 插槽
• THEN 操作按钮显示在弹窗头部的合适位置（有副标题时在右侧，无副标题时与标题同行右侧）

Requirement: 统一弹窗组件支持底部固定页脚

系统 SHALL 提供固定底部的页脚区域，用于放置确认、取消等操作按钮。

Scenario: 显示底部页脚

• WHEN 父组件使用 footer 插槽
• THEN 页脚固定显示在弹窗底部，内容区域可滚动
• THEN 页脚区域有上边框分隔，背景色与头部一致

Requirement: 统一弹窗组件支持双向绑定

系统 SHALL 使用 v-model:show 或 v-model 控制弹窗的显示/隐藏状态。

Scenario: 通过 v-model 控制弹窗显示

• WHEN 父组件修改 v-model 绑定的值为 true
• THEN 弹窗打开并显示内容
• WHEN 用户点击关闭按钮或弹窗外部区域
• THEN 弹窗关闭，v-model 绑定的值更新为 false

Requirement: 统一弹窗组件支持关闭按钮配置

系统 SHALL 允许通过 closeable prop 配置是否显示关闭按钮。

Scenario: 禁用关闭按钮

• WHEN closeable 设置为 false
• THEN 弹窗不显示关闭按钮
• THEN 用户只能通过 v-model 关闭弹窗或点击弹窗外部区域

Requirement: 统一弹窗组件支持点击外部关闭

系统 SHALL 支持点击弹窗外部区域关闭弹窗（继承自 Vant UI 的 van-popup）。

Scenario: 点击外部区域关闭

• WHEN 用户点击弹窗外部区域
• THEN 弹窗关闭，v-model 绑定的值更新为 false

Requirement: 统一弹窗组件支持表单验证场景

系统 SHALL 支持在弹窗内容区域放置表单，并提供表单验证功能。

Scenario: 表单弹窗提交

• WHEN 用户填写表单并点击页脚的提交按钮
• THEN 父组件可以访问表单数据进行验证和提交
• THEN 验证失败时，弹窗保持打开状态

Requirement: 统一弹窗组件使用 Vant UI 主题变量

系统 SHALL 使用 Vant UI 的 CSS 变量（如 --van-text-color、--van-border-color、--van-background 等）保持与现有设计系统一致。

Scenario: 主题适配

• WHEN 应用切换主题（深色/浅色）
• THEN 弹窗组件自动适配主题颜色

Requirement: 统一弹窗组件支持 teleport 到 body

系统 SHALL 将弹窗挂载到 body 元素，避免被父组件的样式或层级影响。

Scenario: 弹窗层级正确

• WHEN 弹窗在嵌套组件中打开
• THEN 弹窗正确显示在最顶层，不被父组件的 z-index 影响