fix

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

@@ -0,0 +1,108 @@
+## 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` 的引用（通过全局搜索验证）