前端技术方案标准模板

一、项目概述

1.1 项目基本信息

1.2 核心功能清单

1.3 研发全流程图

二、技术选型方案

const envConfig = {
  "node_version": ">=18.0.0",
  "npm_version": ">=9.0.0",
  "browsers": ["Chrome >= 100", "Safari >= 15", "Firefox >= 90"],
  "screen_resolutions": ["1920x1080", "1366x768", "375x667 (mobile)"]
};

# 生产依赖
npm install react react-dom
npm install typescript @types/react @types/react-dom

# 开发依赖
npm install -D vite @vitejs/plugin-react
npm install -D eslint prettier stylelint
npm install -D vitest @testing-library/react
npm install -D husky lint-staged

三、组件设计规范

3.1 组件分类体系

src/components/
├── base/                    # 基础组件（无业务逻辑）
│   ├── Button/
│   ├── Input/
│   ├── Modal/
│   └── Table/
├── business/                # 业务组件（含业务逻辑）
│   ├── UserCard/
│   ├── OrderForm/
│   └── ProductList/
├── layout/                  # 布局组件
│   ├── Header/
│   ├── Sidebar/
│   └── PageContainer/
└── composite/               # 复合组件（组合多个组件）
    ├── DataTable/
    └── FormModal/

3.2 组件设计原则 (SOLID)

// ✅ 好的设计：Button 只负责按钮展示和点击
const Button = ({ children, onClick }) => (
  <button onClick={onClick}>{children}</button>
);

// ❌ 坏的设计：组件承担过多职责
const BadButton = ({ data }) => {
  // 同时处理数据获取、验证、展示...
};

interface ButtonProps {
  variant?: 'primary' | 'secondary' | 'danger';
  size?: 'small' | 'medium' | 'large';
  // 可通过添加新 variant 扩展，无需修改组件
}

3.3 组件 API 设计规范

interface ComponentProps {
  // 必需属性
  title: string;
  
  // 可选属性（带默认值）
  size?: 'small' | 'medium' | 'large';
  disabled?: boolean;
  
  // 回调函数
  onClick?: (event: MouseEvent) => void;
  onChange?: (value: any) => void;
  
  // 样式相关
  className?: string;
  style?: React.CSSProperties;
  
  // 子元素
  children?: React.ReactNode;
}

3.4 响应式断点规范

四、交互设计规范

4.1 交互状态定义

enum InteractionState {
  IDLE = 'idle',           // 初始状态
  LOADING = 'loading',     // 加载中
  SUCCESS = 'success',     // 成功
  ERROR = 'error',         // 错误
  EMPTY = 'empty',         // 空状态
}

4.2 用户反馈规范

4.3 动画过渡规范

五、API 接口协议设计

5.1 RESTful API 规范

interface ApiResponse<T> {
  code: number;           // 状态码
  message: string;        // 消息
  data: T;                // 数据
  timestamp: number;      // 时间戳
  traceId: string;        // 追踪 ID
}

interface PaginationParams {
  page: number;           // 页码（从 1 开始）
  pageSize: number;       // 每页数量
  sortBy?: string;        // 排序字段
  sortOrder?: 'asc' | 'desc'; // 排序方向
}

5.2 错误码定义

5.3 全局错误处理

const errorHandler = (error: ApiError) => {
  const { code, message } = error;
  
  switch (code) {
    case 401:
      redirectToLogin();
      break;
    case 403:
      showMessage('warning', '无权限访问');
      break;
    case 404:
      showMessage('error', '资源不存在');
      break;
    case 500:
      showMessage('error', '服务器错误，请稍后重试');
      break;
    default:
      showMessage('error', message || '未知错误');
  }
};

六、部署与 CI/CD

6.1 性能指标目标

6.2 Docker 部署配置

# Dockerfile
FROM node:18-alpine AS builder

WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf

EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

6.3 K8S 部署配置

# k8s/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: frontend-app
  namespace: production
spec:
  replicas: 3
  selector:
    matchLabels:
      app: frontend-app
  template:
    metadata:
      labels:
        app: frontend-app
    spec:
      containers:
      - name: frontend
        image: registry.example.com/frontend-app:latest
        ports:
        - containerPort: 80
        resources:
          requests:
            memory: "128Mi"
            cpu: "100m"
          limits:
            memory: "256Mi"
            cpu: "200m"
        livenessProbe:
          httpGet:
            path: /health
            port: 80
          initialDelaySeconds: 30
          periodSeconds: 10

6.4 CI/CD 流水线

七、AI Coding 集成指南

7.1 Prompt 模板示例

请根据以下要求生成一个 React 组件：

【组件名称】: [组件名]
【功能描述】: [详细描述]
【Props 接口】: [TypeScript 接口定义]
【样式要求】: [样式规范]
【测试要求】: [测试用例要求]

请生成：
1. 组件源代码（TSX）
2. 样式文件（SCSS/CSS Modules）
3. 单元测试文件
4. 组件文档（Storybook）

请根据以下 API 文档生成前端集成代码：

【接口地址】: [API URL]
【请求方法】: GET/POST/PUT/DELETE
【请求参数】: [参数定义]
【响应结构】: [响应数据类型]

请生成：
1. API 调用函数
2. TypeScript 类型定义
3. 错误处理逻辑
4. 使用示例

请为以下组件生成完整的测试套件：

【组件名称】: [组件名]
【组件功能】: [功能描述]
【测试框架】: Jest + React Testing Library
【覆盖率要求】: ≥ 90%

请生成：
1. 单元测试用例
2. 边界条件测试
3. 交互行为测试
4. Mock 数据定义