EmailBill/openspec/changes/archive/2026-02-20-remove-popup-container-v1/specs/popup-v2-migration/spec.md

ADDED Requirements

Requirement: PopupContainer 组件导入路径迁移

所有引用 PopupContainer.vue 的文件必须更新导入路径为 PopupContainerV2.vue，并将组件名更改为 PopupContainerV2。

Scenario: 更新 import 语句

• WHEN 文件中存在 import PopupContainer from '@/components/PopupContainer.vue' 或 import PopupContainer from './PopupContainer.vue'
• THEN 系统必须将其替换为 import PopupContainerV2 from '@/components/PopupContainerV2.vue'

Scenario: 更新模板中的组件名

• WHEN 模板中使用 <PopupContainer> 标签
• THEN 系统必须将其替换为 <PopupContainerV2>

Requirement: Props API 映射转换

V1 和 V2 的 props 差异必须通过重构适配，确保功能等价。

Scenario: 基础 props 映射

• WHEN V1 使用 v-model:show、title 等基础 props
• THEN V2 必须保留这些 props 不变（modelValue、title 在两个版本中一致）

Scenario: height prop 默认值处理

• WHEN V1 未显式指定 height prop（默认 80%）
• THEN V2 必须显式添加 :height="'80%'" 以保持一致的视觉效果

Scenario: 移除不支持的 props

• WHEN V1 使用 closeable、subtitle、showConfirmButton、showCancelButton、confirmText、cancelText 等 props
• THEN 系统必须移除这些 props，并通过插槽方式重构（见下一需求）

Requirement: subtitle 功能迁移

V1 的 subtitle prop 必须转换为 V2 的默认插槽内容或自定义标题结构。

Scenario: subtitle 作为内容区域展示

• WHEN V1 使用 subtitle prop 显示副标题
• THEN 必须将 subtitle 内容移至 <PopupContainerV2> 的默认插槽中，并使用适当的样式包裹（如 <p class="subtitle-text">{{ subtitle }}</p>）

Scenario: subtitle 包含 HTML 内容

• WHEN V1 的 subtitle 使用 v-html 渲染（如统计信息）
• THEN 必须在默认插槽中创建等价的 HTML 结构，保持语义和样式一致

Requirement: 确认/取消按钮迁移

V1 的 showConfirmButton、showCancelButton 等按钮相关 props 必须转换为 V2 的 footer 插槽。

Scenario: 标准确认/取消按钮

• WHEN V1 使用 show-confirm-button 和 show-cancel-button props
• THEN 必须在 V2 的 <template #footer> 中手动创建 <van-button> 组件，绑定相同的事件处理器（@confirm、@cancel）

Scenario: 自定义按钮文本

• WHEN V1 使用 confirm-text 或 cancel-text 自定义按钮文字
• THEN 必须将文本内容应用到 footer 插槽中的按钮组件

Scenario: 按钮布局样式

• WHEN 创建 footer 插槽内的按钮
• THEN 必须使用 flexbox 布局确保按钮水平排列，间距为 12px，与 V1 的视觉效果一致

Requirement: header-actions 插槽迁移

V1 的 header-actions 插槽必须根据业务逻辑转换为 V2 的内容区域或自定义实现。

Scenario: 移除 header-actions 插槽

• WHEN V1 使用 <template #header-actions> 插槽放置操作按钮
• THEN V2 必须将这些按钮移至默认插槽顶部或 footer 插槽中，根据业务语义选择合适位置

Scenario: 保持操作按钮的视觉层级

• WHEN V1 的 header-actions 与标题同行显示（grid 布局）
• THEN 必须在 V2 的默认插槽中创建自定义布局，使用绝对定位或 flexbox 实现相同效果

Requirement: 样式和暗色模式兼容性

迁移后的组件必须保持视觉一致性，正确响应暗色模式。

Scenario: 暗色模式自动适配

• WHEN 用户切换到暗色模式
• THEN V2 的硬编码颜色（#ffffff、#09090b 等）必须通过 @media (prefers-color-scheme: dark) 自动切换

Scenario: 内容区域 padding 处理

• WHEN V1 的可滚动内容区域有默认样式
• THEN V2 的内容插槽无默认 padding，必须由使用方手动添加（如 <div class="content" style="padding: 16px">）

Requirement: 事件处理器兼容性

V1 的事件（@confirm、@cancel）必须正确映射到 V2 的按钮点击事件。

Scenario: 确认事件触发

• WHEN 用户点击 footer 插槽中的确认按钮
• THEN 必须手动触发原有的 @confirm 事件处理逻辑（可能需要通过 emit 或直接调用方法）

Scenario: 取消事件触发

• WHEN 用户点击取消按钮或关闭弹窗
• THEN 必须确保原有的 @cancel 逻辑被正确执行（V2 已通过关闭按钮自动关闭弹窗，但可能需要额外的清理逻辑）

Requirement: 代码质量和测试

迁移后的代码必须通过 ESLint 检查，并保持功能正确性。

Scenario: ESLint 验证通过

• WHEN 完成迁移后
• THEN 运行 pnpm lint 必须无错误和警告

Scenario: 功能回归测试

• WHEN 迁移后的页面加载
• THEN 弹窗的打开/关闭、内容展示、按钮交互必须与迁移前行为一致

Requirement: 删除旧版本组件

所有迁移完成后，必须删除 PopupContainer.vue 文件以避免混淆。

Scenario: 文件删除

• WHEN 所有 18 个文件迁移完成并验证通过
• THEN 系统必须删除 Web/src/components/PopupContainer.vue 文件

Scenario: 无残留引用

• WHEN 删除旧组件后
• THEN 项目中不得存在任何对 PopupContainer.vue 的引用（通过全局搜索验证）