V0 项目转换规范

将 V0 生成的 Next.js 项目快速转换为本项目页面组件，保持视觉效果和功能，符合本项目开发规范。

核心目标

• 保持页面视觉一致性
• 移除 Next.js 特有实现
• 产出可在本项目中运行的页面组件

使用方式

步骤 1：运行预处理脚本

node scripts/v0-converter.mjs <v0-project-dir> [output-name]

# 示例
node scripts/v0-converter.mjs "temp/my-v0-project" my-page

脚本会自动完成：

• 完整复制 V0 项目到 src/prototypes/[页面名]/
• 分析项目结构（路径别名、Next.js 代码等）
• 生成 AI 工作文档（.v0-tasks.md）
• 生成详细数据（.v0-analysis.json）
• 不修改任何代码（100% 安全）

步骤 2：按任务清单完成转换

脚本会生成 .v0-tasks.md 文件，包含：

• 项目概况统计
• 6 个具体任务清单
• 路径别名转换参考表
• 依赖安装命令
• 验收测试步骤

按任务清单与本规范示例执行转换。

转换要点

本项目页面组件规范

默认先转换为普通 React 页面组件。只有在需求明确要求接入 Axhub / Axure 运行时能力时，才引入 forwardRef<AxureHandle, AxureProps>、useImperativeHandle 和 axure-types。

默认格式（推荐）：

/**
 * @name 页面名称
 * 
 * 参考资料：
 * - /rules/development-guide.md
 * - /skills/default-resource-recommendations/SKILL.md
 */

import './style.css';
import React from 'react';

export default function PageName() {
  // 组件逻辑
  
  return (
    // JSX 内容
  );
}

仅在以下场景才接入 Axure API：

• 页面需要被 Axhub / Axure 接管
• 需要配置面板、外部数据源、事件回调或动作触发
• 用户明确要求保持与现有 Axure 组件一致的接口形式

此时再参考 /rules/axure-api-guide.md，使用如下包装形式：

import React, { forwardRef, useImperativeHandle } from 'react';
import type { AxureProps, AxureHandle } from '../../common/axure-types';

const Component = forwardRef<AxureHandle, AxureProps>(function PageName(innerProps, ref) {
  useImperativeHandle(ref, function () {
    return {
      getVar: function () { return undefined; },
      fireAction: function () {},
      eventList: [],
      actionList: [],
      varList: [],
      configList: [],
      dataList: []
    };
  }, []);

  return (
    // JSX 内容
  );
});

export default Component;

移除 Next.js 特定代码

移除所有 Next.js 特定实现：

// ❌ 需要移除
"use client"                                    // Next.js 客户端组件指令，本项目不需要
import { useRouter } from 'next/navigation'    // Next.js 路由
import Image from 'next/image'                 // Next.js 图片组件
import Link from 'next/link'                   // Next.js 链接组件
import type { Metadata } from 'next'           // Next.js 元数据类型
import { Analytics } from '@vercel/analytics/next'  // Vercel 分析

// ✅ 替换为
// 删除 "use client" 指令
// 删除 useRouter 相关代码
<img> 替代 <Image>
<a> 替代 <Link>
// 删除 Metadata 和 Analytics

关于 "use client"： -本项目不使用 Next.js，所有组件都是客户端渲染

• 必须删除，否则会导致语法错误

路径别名转换

将 V0 的 @/ 别名转换为相对路径：

// V0 原始代码
import { cn } from "@/lib/utils"
import { Button } from "@/components/ui/button"

// 在 app/page.tsx 中转换为
import { cn } from "../lib/utils"
import { Button } from "../components/ui/button"

// 在 components/ui/card.tsx 中转换为
import { cn } from "../../lib/utils"

脚本生成的分析报告会提供每个文件的具体转换参考。

样式文件

/* style.css 必须以此开头 */
@import "tailwindcss";

/* 然后是原 globals.css 的内容 */
/* 保持 Tailwind V4 语法不变 */
@theme inline { ... }
@custom-variant dark (...);

依赖管理

排除 Next.js 相关依赖：

• next 及所有 next-* 包
• @vercel/* 包
• react 和 react-dom（本项目已有）

保留其他依赖：

• class-variance-authority, clsx, tailwind-merge
• @radix-ui/* 组件
• lucide-react, recharts, date-fns 等

验收标准

转换完成后运行验收脚本：

node scripts/check-app-ready.mjs /prototypes/[页面名]

验收要求：

• 状态为 READY
• 页面能正常渲染
• 无控制台错误
• 交互功能正常
• 样式显示正确

常见问题

依赖缺失

# 根据报告中的依赖列表安装
pnpm add [依赖名称]

路径错误

• 检查 @/ 是否已转换为相对路径
• 参考 .v0-analysis.md 中的转换表

样式问题

• 确认 style.css 包含 @import "tailwindcss"
• 检查 CSS 变量是否完整

Next.js 残留

• 搜索 "use client"、next/、@vercel/
• 确保全部移除或替换

参考资源

• 开发规范：/rules/development-guide.md
• 调试指南：/rules/debugging-guide.md
• Tailwind CSS：/skills/default-resource-recommendations/SKILL.md