happy-life-star/.kiro/specs/pncyssd-refactor/design.md

Design Document: PncyssD 页面重构

Overview

本设计文档描述了将 PncyssD 原型页面重构为 course-web 项目规范的 React 组件的技术方案。重构将保持原有的视觉设计风格（深色主题、玻璃拟态、橙色强调色）和后端接口调用逻辑，同时采用 React + Vite + Tailwind CSS 的现代前端架构。

Architecture

整体架构

PncyssD/                          →    course-web/src/
├── index.html                         ├── main.jsx (入口)
├── index.js (App 入口)                ├── App.jsx (路由控制)
├── state.js (状态管理)                ├── utils/store.js (已存在)
├── login.js (登录页)                  ├── pages/LoginPage.jsx (重构)
├── onboarding.js (引导页)             ├── pages/OnboardingPage.jsx (重构)
├── dashboard.js (仪表盘)              ├── pages/DashboardPage.jsx (重构)
├── components.js (UI组件)             ├── components/ui/*.jsx (复用)
├── api.js (AI服务)                    ├── utils/aiLogic.js (重构)
└── style.css (样式)                   └── index.css (合并样式)

页面流程

stateDiagram-v2
    [*] --> LandingPage: 首次访问
    LandingPage --> LoginPage: 点击登录
    LoginPage --> OnboardingPage: 登录成功(新用户)
    LoginPage --> DashboardPage: 登录成功(老用户)
    OnboardingPage --> DashboardPage: 完成引导
    DashboardPage --> TimelineView: 默认视图
    DashboardPage --> ScriptView: 点击爽文剧本
    DashboardPage --> PathView: 点击实现路径

Components and Interfaces

1. 登录页面组件 (LoginPage.jsx)

/**
 * 登录页面组件
 * 提供手机号验证码登录功能
 */
interface LoginPageProps {
  onLoginSuccess: () => void;  // 登录成功回调
  onBack: () => void;          // 返回首页回调
}

// 内部状态
interface LoginState {
  phone: string;           // 手机号
  code: string;            // 验证码
  countdown: number;       // 倒计时秒数
  loading: boolean;        // 登录中状态
  error: string;           // 错误信息
}

2. 引导页面组件 (OnboardingPage.jsx)

/**
 * 引导流程页面组件
 * 5步骤用户信息采集
 */
interface OnboardingPageProps {
  onFinish: () => void;  // 完成引导回调
}

// 步骤数据结构
interface OnboardingFormData {
  // Step 1: 基本信息
  nickname: string;
  gender: 'male' | 'female' | 'secret';
  zodiac: string;
  mbti: string;
  hobbies: string[];
  
  // Step 2-4: 人生记忆
  history: {
    childhood: { date: string; content: string };
    peak: { date: string; content: string };
    valley: { date: string; content: string };
  };
  
  // Step 5: 未来愿景
  futureVision: string;
}

// 灵感标签配置
const INSPIRATION_TAGS = {
  childhood: ['秋千', '晚霞', '糖果', '奔跑', '蝉鸣', '雨后泥土', '旧书包', '风筝'],
  peak: ['海浪', '拥抱', '掌声', '晨曦', '破土而出', '默契', '星空', '释放'],
  valley: ['落叶', '雨伞', '长廊', '深呼吸', '自愈', '沉潜', '坚韧', '等待', '破茧']
};

3. 仪表盘页面组件 (DashboardPage.jsx)

/**
 * 仪表盘页面组件
 * 包含导航栏和内容区域
 */
interface DashboardState {
  activeTab: 'timeline' | 'script' | 'path';
  isMobileMenuOpen: boolean;
  isUserMenuOpen: boolean;
  isMusicPlaying: boolean;
}

// 导航项配置
const NAV_ITEMS = [
  { id: 'timeline', icon: BookOpen, label: '生命长河' },
  { id: 'script', icon: Film, label: '爽文剧本' },
  { id: 'path', icon: Map, label: '实现路径' }
];

4. 生命长河视图组件 (TimelineView.jsx)

/**
 * 生命长河视图组件
 * 时间线形式展示人生事件
 */
interface LifeEvent {
  id: number;
  title: string;
  time: string;
  content: string;
  aiFeedback: string;
}

interface TimelineViewProps {
  events: LifeEvent[];
  onAddEvent: (event: Omit<LifeEvent, 'id' | 'aiFeedback'>) => Promise<void>;
}

5. 爽文剧本视图组件 (ScriptView.jsx)

/**
 * 爽文剧本视图组件
 * AI生成个性化剧本
 */
interface Script {
  id: number;
  theme: string;
  style: string;
  length: string;
  content: string;
  date: string;
}

interface ScriptParams {
  theme: string;
  style: '都市' | '古风' | '爱情' | '科幻' | '喜剧' | '悬疑' | '恐怖';
  length: '短' | '中' | '长';
}

interface ScriptViewProps {
  scripts: Script[];
  selectedScriptId: number | null;
  userProfile: UserProfile;
  onGenerateScript: (params: ScriptParams) => Promise<void>;
  onSelectScript: (id: number) => void;
  onSwitchToPath: () => void;
}

6. 实现路径视图组件 (PathView.jsx)

/**
 * 实现路径视图组件
 * 将剧本转化为行动计划
 */
interface PathStep {
  title: string;
  content: string;
}

interface PathViewProps {
  selectedScript: Script | null;
  path: PathStep[] | null;
  onGeneratePath: () => Promise<void>;
  onSwitchToScript: () => void;
}

7. 用户菜单组件 (UserMenu.jsx)

/**
 * 用户菜单弹窗组件
 * 查看和编辑用户资料
 */
interface UserMenuProps {
  isOpen: boolean;
  onClose: () => void;
  onLogout: () => void;
}

interface UserMenuState {
  isEditing: boolean;
  editData: Partial<UserProfile>;
}

Data Models

Store 数据结构

const STORE_SCHEMA = {
  onboardingComplete: false,        // 是否完成引导
  audioMuted: true,                 // 音乐是否静音
  userProfile: {
    nickname: "",
    gender: "secret",
    zodiac: "",
    mbti: "",
    hobbies: [],
    history: {
      childhood: { date: "", content: "" },
      peak: { date: "", content: "" },
      valley: { date: "", content: "" }
    },
    futureVision: ""
  },
  lifeTimeline: [],                 // 生命事件列表
  generatedScripts: [],             // 生成的剧本列表
  paths: [],                        // 实现路径列表
  selectedScriptId: null,           // 当前选中的剧本ID
  selectedPath: null                // 当前选中的路径
};

API 接口

// 认证接口 (保持不变)
POST /auth/sms-code?phone={phone}  // 发送验证码
POST /auth/login                    // 登录
  Body: { phone, smsCode }
  Response: { accessToken }

// 用户资料接口 (保持不变)
GET  /user/profile                  // 获取用户资料
POST /user/profile                  // 创建用户资料
PUT  /user/profile                  // 更新用户资料

// AI 服务接口 (OpenRouter)
POST https://openrouter.ai/api/v1/chat/completions
  Headers: { Authorization: Bearer {API_KEY} }
  Body: { model, messages }

Correctness Properties

A property is a characteristic or behavior that should hold true across all valid executions of a system-essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.

Property 1: 手机号格式验证

For any 输入字符串，手机号验证函数应当仅对11位数字且以1开头的字符串返回 true，对其他所有输入返回 false。

Validates: Requirements 1.2

Property 2: 步骤导航数据完整性

For any 引导流程中的步骤切换操作（前进或后退），用户在各步骤填写的数据应当被完整保留，不会因为步骤切换而丢失。

Validates: Requirements 2.7, 2.8

Property 3: 导航视图切换一致性

For any 仪表盘导航项点击操作，当前激活的视图应当与点击的导航项对应，且导航项的高亮状态应当正确反映当前视图。

Validates: Requirements 3.3

Property 4: 事件列表渲染完整性

For any 生命事件数组，时间线视图应当渲染所有事件，且每个事件卡片应当包含标题、时间、内容和 AI 洞察四个字段。

Validates: Requirements 4.4

Property 5: 事件时间排序正确性

For any 包含多个事件的生命事件数组，时间线视图应当按时间倒序排列事件，即最新的事件显示在最前面。

Validates: Requirements 4.6

Property 6: 数据持久化往返一致性

For any 有效的用户数据对象，保存到 localStorage 后再读取，应当得到与原始数据等价的对象。

Validates: Requirements 10.1, 10.2, 10.3

Error Handling

网络错误处理

// API 调用统一错误处理
try {
  const response = await request.post('/auth/login', data);
  // 处理成功响应
} catch (error) {
  if (error.response) {
    // 服务器返回错误
    showToast(error.response.data.message || '请求失败');
  } else if (error.request) {
    // 网络错误
    showToast('网络连接异常，请检查网络设置');
  } else {
    // 其他错误
    showToast('发生未知错误');
  }
}

表单验证错误

// 表单验证规则
const VALIDATION_RULES = {
  phone: {
    required: true,
    pattern: /^1[3-9]\d{9}$/,
    message: '请输入正确的手机号'
  },
  code: {
    required: true,
    length: 6,
    message: '请输入6位验证码'
  },
  nickname: {
    required: true,
    maxLength: 20,
    message: '昵称不能为空且不超过20字'
  }
};

存储错误处理

// localStorage 存储错误处理
try {
  localStorage.setItem(STORAGE_KEY, JSON.stringify(data));
} catch (error) {
  if (error.name === 'QuotaExceededError') {
    showToast('存储空间不足，部分数据可能无法保存');
  }
}

Testing Strategy

单元测试

使用 Vitest 进行单元测试，覆盖以下场景：

1. 工具函数测试

   • 手机号格式验证函数
   • 数据序列化/反序列化函数
   • 日期格式化函数

2. 组件渲染测试

   • 各页面组件的基本渲染
   • 条件渲染逻辑（空状态、加载状态）
   • 用户交互响应

3. 状态管理测试

   • Store 的 CRUD 操作
   • 数据持久化逻辑

属性测试

使用 fast-check 进行属性测试，验证以下属性：

1. Property 1: 手机号验证 - 生成各种字符串测试验证函数
2. Property 2: 步骤导航 - 生成随机步骤切换序列测试数据保留
3. Property 5: 事件排序 - 生成随机事件数组测试排序正确性
4. Property 6: 数据持久化 - 生成随机数据对象测试往返一致性

测试配置

// vitest.config.js
export default {
  test: {
    environment: 'jsdom',
    globals: true,
    setupFiles: ['./src/test/setup.js']
  }
};

// 属性测试最小迭代次数: 100