AI+Code驱动的M站首页重构实践：从技术债务到智能化开发

// ProductFloor 组件属性类型export type ProductFloorProps = {  // 动态模板类型，固定为 'ProductFloor'  dynamicTemplate: 'ProductFloor';  // 埋点信息  homeActivityInfo?: HomeActivityInfo;  // 楼层标题  title: string;  // 楼层标题图标  titleIcon?: string;  // 楼层副标题  subTitle: string;  // 楼层整体点击跳转链接  action: string;  // 商品卡片主标题样式  itemTitleStyle?: 'primary' | 'normal';  // 商品卡片副标题样式  itemSubTitleStyle?: 'primary' | 'normal';  // 背景图片 URL  backgroundImage?: string;  // 商品卡片列表  items: Item[];  // 是否使用 RTL 布局  isRTL?: boolean;  // 是否显示间隔块  isShowGap?: string;};// Item 类型定义export type Item = {  // 项目唯一标识  id: string;  // 商品ID（如果是商品类型）  productId?: string;  // 项目标题  title: string;  // 标题颜色  titleColor?: string;  // 价格  price?: string;  // 主图URL  image: string;  // 主图宽度  imageWidth?: string;  // 主图高度  imageHeight?: string;  // 角标图片URL  cornerImg?: string;  // 角标宽度  cornerWidth?: string;  // 角标高度  cornerHeight?: string;  // 副标题  subTitle?: string;  // 副标题图标  subIcon?: string;  // 最小订单量文本  moqText?: string;  // 已售数量文本  soldText?: string;  // 本地库存标签  localField?: string;  // 国家国旗URL  countryFlagUrl?: string;  // 点击跳转链接  action?: string;  // 埋点信息  homeActivityInfo?: HomeActivityInfo;  // 是否显示闪购标签  showFlashDeal?: boolean;  // 闪购标签文本  label?: string;  // 图片中间描述信息  centerDesc?: string;  // 浏览量  views?: string;};

# 创建动态楼层
这个 snippet 用于在 DynamicFloors 目录中创建新的楼层。## 步骤- 注意下述相关命名只是以 NewFloor 示例，具体根据识别结果判断楼层与相关变量命名，不能直接用  NewFloor。- 整体上各个代码文件格式规范方面可以参考 DynamicFloors/ProductFloor 下的一系列实现- 需要符合WCAG 1.4 版本 AA等级的无障碍规范（尤其img元素需要补充alt字段）1. 创建楼层目录，例如`floors/NewFloor`并在楼层目录下创建类型定义文件 `floors/NewFloor/types.ts`：```typescriptimport type { HomeActivityInfo } from '@/components/DynamicFloors/types';// 如果需要扩展通用 Item 类型，可以这样做export interface NewFloorItem {  // Item字段}export type NewFloorProps = {  dynamicTemplate: 'NewFloor';  title: string;  subTitle?: string;  action?: string;  items: NewFloorItem[];  homeActivityInfo?: HomeActivityInfo;  isRTL?: boolean;};```2. 在楼层目录下创建模拟数据文件 `floors/NewFloor/mock.ts`,注意 image 相关数据调用 getRandomImage()方   法，不要自己写 url3. 更新根目录的 `types.ts`，添加新楼层的类型：```typescript// ... 其他导入import type { NewFloorProps } from './floors/NewFloor/types';// 更新 DSLData 类型export type DSLData = (ProductFloorType | ThemeFloorType | GapFloorType | NewFloorProps)[];```4. 使用 `figma_d2c` MCP 方法生成自定义卡片内容：- 请求用户补充坑位卡片对应的设计稿链接（例如  ：https://www.figma.com/file/xxxx），调用figma_d2c方法生成组件代码- 生成的卡片代码替换到 `floors/NewFloor/index.tsx`，样式代码替换到`floors/NewFloor/index.less`- 不要对 `figma_d2c` 生成的代码做任何修改5. 更新根目录的 `mock.ts`，导出新楼层的模拟数据：```typescript// ... 其他导入import { mockNewFloor } from './floors/NewFloor/mock';// 导出所有楼层的模拟数据export {  ...,  mockNewFloor};```6. 创建楼层组件 `floors/NewFloor/index.tsx`：```typescriptimport'./index.less';// 分析设计稿，有楼层级别的标题才引入FloorTitleBlockimport FloorTitleBlock from '@/components/DynamicFloors/blocks/FloorTitleBlock';import ErrorBoundary from '@/components/ErrorBoundary';import MDotElement from '@/components/MDotElement';import React from 'react';import { NewFloorProps } from './types';const NewFloor: React.FC<NewFloorProps> = props => {  const { items, homeActivityInfo, isRTL } = props;  return (    <ErrorBoundary sceneName={'NewFloor'}>      <div className="new-floor">        // 有楼层标题区域才需要该组件        <FloorTitleBlock {...props} />        <div className={`card-container ${isRTL ? 'rtl' : ''}`}>          {items.map((item, index) => (            <MDotElement              key={item.id}              url={item.action}              className="card"              dotParams={{                sceneName: homeActivityInfo?.moduleType || 'NewFloor',                pos: index,                elementType: item.homeActivityInfo?.elementType,              }}            >              {/* 自定义卡片内容占位，不要直接写内容 */}            </MDotElement>          ))}        </div>      </div>    </ErrorBoundary>  );};exportdefault NewFloor;```6. 创建样式文件 `floors/NewFloor/index.less`：```less@import'src/styles/global';.new-floor {  padding: 16px 0;  background: #fff;  .card-container {    display: flex;    overflow-x: auto;    scrollbar-width: none;    padding: 012px;    gap: 12px;    &.rtl {      direction: rtl;    }    &::-webkit-scrollbar {      display: none;    }    .card {      flex: 00auto;      // 自定义卡片样式占位，不要直接写样式    }  }}```7. 更新 `constants.ts` 中的组件映射：```typescriptimport GapFloor from '@/components/DynamicFloors/floors/GapFloor';import ProductFloor from '@/components/DynamicFloors/floors/ProductFloor';import ThemeFloor from '@/components/DynamicFloors/floors/ThemeFloor';import NewFloor from '@/components/DynamicFloors/floors/NewFloor';exportconst ComponentsMap = {  ...,  NewFloor, // 添加新楼层};```8. 在 `pages/FloorTest/index.tsx` 中添加新楼层的测试：```typescriptconst FloorTestPage = () => {  const testDSL: DSLData = [    ...,    mockNewFloor, // 添加新楼层的测试数据  ];  return (    <div>      <h1>Dynamic Floors Test Page</h1>      <DynamicFloors DSL={testDSL} />    </div>  );};exportdefault FloorTestPage;```9. 创建说明文档 `floors/NewFloor/README.md` 中增加新楼层的说明：```markdown# 新楼层## 组件概述## API 定义## 使用示例```## 注意事项1. 确保所有类型定义正确，特别是 `dynamicTemplate` 的字面量类型2. 使用 `ErrorBoundary` 包裹组件3. 支持埋点功能，确保 `homeActivityInfo` 和 `dotParams` 的正确配置4. 支持 RTL 布局5. 遵循现有楼层的代码风格和最佳实践6. 确保在 `constants.ts` 中正确导入和导出新楼层组件7. 类型定义和模拟数据应该放在楼层目录下，根目录的 `types.ts` 和 `mock.ts` 只负责导出8. 记得在 `FloorTest` 页面中添加新楼层的测试数据9. 相关命名只是以 NewFloor 示例，具体根据识别结果判断楼层与相关变量命名，不能直接用 NewFloor10. 优先使用现有的通用组件，如 `FloorTitleBlock` 来处理标题部分，注意如果没有楼层标题模块，不要强行    使用它！11. 命名规范：    - 使用 `subTitle` 而不是 `subtitle`    - 使用 `action` 而不是 `url`    - 尽可能复用通用的 `Item` 类型，需要额外字段时通过继承扩展    - 组件属性类型以 `Props` 结尾，如 `NewFloorProps`    - 模拟数据变量以 `mock` 开头，如 `mockNewFloor`12. 图片资源：    - 测试数据中使用实际的阿里巴巴图片链接，如      ：'[https://s.alicdn.com/@sc04/kf/H6d8a4c02a984415e9c7052e5d95c09b0V.jpg_220x220.jpg](https://s.alicdn.com/@sc04/kf/H6d8a4c02a984415e9c7052e5d95c09b0V.jpg_220x220.jpg)'    - 不要使用 example.com 的示例图片链接    - 国家图标规范:      `https://u.alicdn.com/mobile/g/common/flags/1.0.0/assets/{countryCode}.png`，countryCode 使用      国家简称如 `pk`、`tr` 等。13. 图片展示规范：    - 商品主图需要添加灰色遮罩层，使用 `.overlay` 类，背景色为 `#0000000a`    - 图片容器需要设置 `position: relative`，遮罩层使用绝对定位14. 样式规范：    - 避免使用不必要的阴影效果    - 价格信息直接使用 `item.title` 展示，不要单独维护 price 字段    - 商品副标题（subTitle）使用黑色系（#222），而不是红色    - 横向滚动列表中的卡片间距（gap）使用 4px## 示例参考 DynamicFloors/floors/PrdouctFloor 的实现：- 类型定义：`floors/PrdouctFloor/types.ts`- 模拟数据：`floors/PrdouctFloor/mock.ts`- 组件实现：`floors/PrdouctFloor/index.tsx`- 样式文件：`floors/PrdouctFloor/index.less`- 组件映射：在 `constants.ts` 中添加 `PrdouctFloor`- 组件说明： `floors/PrdouctFloor/README.md`- 测试楼层：在 `pages/FloorTest/index.tsx` 中添加新楼层的测试

           ┌─────────────────┐           │  获取楼层设计图  │           └─────────┬───────┘                     ▼           ┌─────────────────┐           │  分析楼层特征   │           └─────────┬───────┘                     ▼           ┌─────────────────┐           │ 检查现有楼层组件 │           └─────────┬───────┘                     ▼           ┌─────────────────┐           │ 阅读组件README文档│           └─────────┬───────┘                     ▼           ┌─────────────────┐       ┌───┤   相似度评估    ├───┐       │   └─────────────────┘   │       ▼                         ▼┌─────────────────┐     ┌─────────────────┐│ 相似度高 (≥70%) │     │ 相似度低 (<70%) │└─────────┬───────┘     └─────────┬───────┘          │                       │          ▼                       ▼┌─────────────────┐     ┌─────────────────┐│   复用现有组件   │     │   创建新组件    │└─────────┬───────┘     └─────────┬───────┘          │                       │          ▼                       ▼┌─────────────────┐     ┌─────────────────┐│  与开发者确认   │     │  与开发者确认   │└─────────┬───────┘     └─────────┬───────┘          │                       │          ▼                       ▼      ┌───────┐             ┌───────────┐   ┌──┤ 认同  │        ┌────┤ 认同      │   │  └───┬───┘        │    └─────┬─────┘   │      │            │          │   │      ▼            │          ▼   │  ┌───────────┐    │   ┌─────────────────┐   │  │ 生成测试  │    │   │ 创建新组件      │   │  │ 样例代码  │    │   └─────────────────┘   │  └───────────┘    │   │                   │   ▼                   ▼┌─────────────────┐    ┌─────────────────┐│ 不认同,需重新评估│    │ 不认同,询问需求 │└─────────┬───────┘    └─────────┬───────┘          │                      │          ▼                      ▼  ┌───────────────┐     ┌──────────────────────┐  │ 迭代现有组件  │     │ 根据开发者反馈调整方案│  └───────────────┘     └──────────────────────┘

## 五、分析标准
### 1. 结构相似度分析评估新楼层与现有楼层的结构相似度：| 结构元素 | 权重 | 说明 ||---------|------|------|| 布局结构 | 30% | 整体布局、元素排列方式 || 主要组件 | 25% | 卡片、图标、按钮等关键元素 || 交互模式 | 20% | 点击、滑动、展开等交互方式 || 数据结构 | 15% | 数据的组织和展示方式 || 样式特征 | 10% | 颜色、字体、间距等样式细节 |### 2. 功能差异分析评估新楼层与现有楼层的功能差异：| 功能方面 | 判断标准 ||---------|---------|| 核心功能 | 如果核心功能完全不同，建议创建新组件 || 交互方式 | 如果交互逻辑差异较大，建议创建新组件 || 性能要求 | 如果性能要求有特殊差异，建议创建新组件 || 业务逻辑 | 如果业务逻辑复杂且独特，建议创建新组件 || 设计意图 | 如果设计意图与README中描述的组件定位不符，建议创建新组件 |### 3. 可配置性评估评估现有组件通过配置支持新需求的可行性：| 配置方面 | 评估指标 ||---------|---------|| 样式配置 | 现有组件是否支持所需的样式变化 || 结构配置 | 是否可以通过条件渲染调整结构 || 功能配置 | 扩展现有功能的难易程度 || 可维护性 | 添加配置后代码是否仍然清晰可维护 || API兼容性 | 新需求是否符合README中定义的API规范 |## 六、决策标准### 1. 建议复用现有组件的情况当满足以下条件时，建议复用现有组件并通过 props 扩展：- 结构相似度评分 ≥ 70%- 核心功能基本一致- 通过少量配置可以支持新需求- 不会导致组件过于复杂难以维护- 复用后性能不会显著下降- **设计需求与README中描述的组件定位和使用场景相符**### 2. 建议创建新组件的情况当满足以下条件时，建议创建新的楼层组件：- 结构相似度评分 < 70%- 核心功能有本质区别- 需要大量配置才能支持，导致代码复杂度大幅增加- 业务逻辑独特且复杂- 有特殊的性能优化需求- 未来可能有更多类似楼层需要基于此组件扩展- **设计需求与现有组件README中描述的定位和应用场景明显不符**

本文档用于指导如何处理App与M站双端楼层需求的文档
* 注意，完成需求分析之后一定要用户确认之后再进行代码生成工作
# 处理流程1.  Agent输入与需求分析：    *   开发者通过Agent输入相关信息。Agent的输入会基于以下三方面信息：        *   **设计稿**        *   **双端生成要求**（即App端和M站端的具体生成规则或需求）        *   **需求描述**（贴上PRD链接 或者 对要实现功能的文字性描述， 注意我们只关心PRD中首页楼层部分的改动）   
2. 输出需求描述内容：    * 输出需求描述，让用户判断是否准确或者有修改的地方，若可行，就准备继续生成楼层代码   

3.  双路径处理前端楼层代码-根据用户生成要求来进行：    *   **路径A：M站楼层代码处理**        *   触发“M站楼层代码生成链路”。        *   一定要参考项目.cursor/snippets/analyze-floor.md文档来处理M站楼层，一定要进行相似度打分，最终判断是复用已有楼层组件（一般情况都是复用ProductFloor或者ThemeFloor）还是新增楼层组件（相似度不高情况下）        *   处理好之后通知开发者运行项目，并前往floorTest页面预览mock数据下的楼层效果    *   **路径B：App楼层DX代码处理**        *   触发“App楼层DX代码处理链路”。        *   一定要参考项目.cursor/snippets/DX-generate-guide.md文档来生成DX代码        *   生成的DX代码存放在src/DXCode目录下        *   处理好之后通知开发者前往DX平台创建模板并使用生成的代码
4. 总结需求与生成的代码，以及如何测试验证这部分内容