📋 PRD 文档标准模板

# 页面原型描述模板（YAML 格式）
page_id: user_management
page_name: 用户管理页面
route: /admin/users
layout: AdminLayout
components:
  - id: search_bar
    type: SearchBar
    position: top
    fields:
      - {name: username, label: 用户名，type: input}
      - {name: role, label: 角色，type: select, options: [admin, user, guest]}
      - {name: status, label: 状态，type: radio, options: [active, inactive]}
  
  - id: action_toolbar
    type: Toolbar
    position: top-right
    actions:
      - {label: 新增用户，icon: plus, action: openModal('create')}
      - {label: 批量删除，icon: delete, action: batchDelete}
      - {label: 导出 Excel, icon: export, action: exportData}
  
  - id: user_table
    type: DataTable
    dataSource: GET /api/v1/users
    columns:
      - {key: id, title: ID, width: 80}
      - {key: username, title: 用户名，width: 150}
      - {key: email, title: 邮箱，width: 200}
      - {key: role, title: 角色，width: 100, render: badge}
      - {key: status, title: 状态，width: 100, render: switch}
      - {key: created_at, title: 创建时间，width: 180}
      - {key: actions, title: 操作，width: 200, render: actionButtons}
    pagination:
      pageSize: 20
      showSizeChanger: true
  
  - id: create_modal
    type: Modal
    title: 新增用户
    form:
      - {field: username, label: 用户名，required: true, validator: minLength(3)}
      - {field: email, label: 邮箱，required: true, validator: email}
      - {field: password, label: 密码，required: true, type: password}
      - {field: role, label: 角色，type: select, required: true}
    submit: POST /api/v1/users
  
interactions:
  - trigger: row.click
    action: navigateTo('/admin/users/{id}')
  - trigger: delete.click
    action: confirmDelete → DELETE /api/v1/users/{id}
  - trigger: status.switch
    action: PATCH /api/v1/users/{id}/status

// 成功响应
{
  "code": 200,
  "message": "success",
  "data": { ... },
  "timestamp": 1710316800000,
  "traceId": "0a1b2c3d4e5f"
}

// 失败响应
{
  "code": 40001,
  "message": "参数验证失败：email 格式不正确",
  "data": null,
  "errors": [
    {"field": "email", "message": "无效的邮箱格式"}
  ],
  "timestamp": 1710316800000,
  "traceId": "0a1b2c3d4e5f"
}

# OpenAPI 3.0 规范示例
openapi: 3.0.3
info:
  title: 用户管理系统 API
  version: 1.0.0
  description: 端到端研发自动化系统的用户管理模块

servers:
  - url: https://api.example.com/api/v1
    description: 生产环境
  - url: https://test-api.example.com/api/v1
    description: 测试环境

paths:
  /users:
    get:
      summary: 获取用户列表
      tags: [Users]
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: size
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserListResponse'
    
    post:
      summary: 创建用户
      tags: [Users]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: 创建成功

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        username:
          type: string
        email:
          type: string
          format: email
        role:
          type: string
          enum: [admin, user, guest]
        status:
          type: string
          enum: [active, inactive]

src/
├── controller/           # 控制器层（HTTP 接口）
│   ├── UserController.java
│   └── AuthController.java
├── service/              # 服务层（业务逻辑）
│   ├── UserService.java
│   └── impl/
│       └── UserServiceImpl.java
├── repository/           # 数据访问层
│   ├── UserRepository.java
│   └── mapper/
│       └── UserMapper.xml
├── entity/               # 实体类
│   ├── User.java
│   └── Role.java
├── dto/                  # 数据传输对象
│   ├── request/
│   │   └── CreateUserRequest.java
│   └── response/
│       └── UserResponse.java
├── config/               # 配置类
│   ├── SecurityConfig.java
│   └── SwaggerConfig.java
├── exception/            # 异常处理
│   ├── GlobalExceptionHandler.java
│   └── BusinessException.java
├── common/               # 公共组件
│   ├── constants/
│   ├── utils/
│   └── enums/
└── resources/
    ├── application.yml
    └── db/migration/     # Flyway/Liquibase 迁移脚本

src/
├── components/           # 通用组件
│   ├── common/
│   │   ├── Button.tsx
│   │   ├── Modal.tsx
│   │   └── Table.tsx
│   └── business/
│       ├── UserForm.tsx
│       └── UserTable.tsx
├── pages/                # 页面组件
│   ├── users/
│   │   ├── UserList.tsx
│   │   └── UserDetail.tsx
│   └── login/
│       └── LoginPage.tsx
├── hooks/                # 自定义 Hooks
│   ├── useAuth.ts
│   └── useUsers.ts
├── store/                # 状态管理
│   ├── authStore.ts
│   └── userStore.ts
├── services/             # API 服务
│   ├── api.ts
│   ├── userService.ts
│   └── auth.service.ts
├── types/                # TypeScript 类型定义
│   ├── user.ts
│   └── api.d.ts
├── utils/                # 工具函数
│   ├── request.ts
│   └── validators.ts
├── styles/               # 全局样式
│   ├── variables.css
│   └── global.css
├── assets/               # 静态资源
│   ├── images/
│   └── icons/
├── router/               # 路由配置
│   └── index.tsx
├── App.tsx
└── main.tsx

// Java + JUnit 5 + Mockito 示例
class UserServiceTest {
    
    @Mock
    private UserRepository userRepository;
    
    @InjectMocks
    private UserService userService;
    
    @Test
    void should_returnUser_when_validIdProvided() {
        // Arrange
        Long userId = 1L;
        User mockUser = new User(userId, "admin", "admin@example.com");
        when(userRepository.findById(userId)).thenReturn(Optional.of(mockUser));
        
        // Act
        User result = userService.getUserById(userId);
        
        // Assert
        assertNotNull(result);
        assertEquals("admin", result.getUsername());
        verify(userRepository, times(1)).findById(userId);
    }
    
    @Test
    void should_throwException_when_userNotFound() {
        // Arrange
        Long userId = 999L;
        when(userRepository.findById(userId)).thenReturn(Optional.empty());
        
        // Act & Assert
        assertThrows(UserNotFoundException.class, () -> {
            userService.getUserById(userId);
        });
    }
}

// Playwright + TypeScript 示例
import { test, expect } from '@playwright/test';

test.describe('User Management', () => {
  
  test.beforeEach(async ({ page }) => {
    // 登录
    await page.goto('/login');
    await page.fill('[data-testid="username"]', 'admin');
    await page.fill('[data-testid="password"]', 'password123');
    await page.click('[data-testid="login-btn"]');
    await expect(page).toHaveURL('/dashboard');
  });

  test('should display user list', async ({ page }) => {
    await page.goto('/admin/users');
    
    // 验证表格存在
    await expect(page.locator('[data-testid="user-table"]')).toBeVisible();
    
    // 验证至少有一行数据
    const rows = page.locator('[data-testid="user-row"]');
    await expect(rows.count()).toBeGreaterThan(0);
  });

  test('should create new user', async ({ page }) => {
    await page.goto('/admin/users');
    
    // 点击新增按钮
    await page.click('[data-testid="add-user-btn"]');
    
    // 填写表单
    await page.fill('[data-testid="username-input"]', 'testuser');
    await page.fill('[data-testid="email-input"]', 'test@example.com');
    await page.selectOption('[data-testid="role-select"]', 'user');
    
    // 提交表单
    await page.click('[data-testid="submit-btn"]');
    
    // 验证成功提示
    await expect(page.locator('.toast-success')).toContainText('创建成功');
    
    // 验证新用户在列表中
    await expect(page.locator('text=testuser')).toBeVisible();
  });

  test('should delete user', async ({ page }) => {
    await page.goto('/admin/users');
    
    // 点击删除按钮
    await page.click('[data-testid="delete-user-1"]');
    
    // 确认删除
    await page.click('[data-testid="confirm-delete"]');
    
    // 验证删除成功
    await expect(page.locator('.toast-success')).toContainText('删除成功');
    await expect(page.locator('text=testuser')).not.toBeVisible();
  });
});

// Jenkins Declarative Pipeline
pipeline {
    agent any
    
    environment {
        DOCKER_REGISTRY = 'registry.example.com'
        IMAGE_NAME = 'myapp-backend'
        KUBE_CONFIG = credentials('kubeconfig')
    }
    
    stages {
        stage('Checkout') {
            steps {
                git branch: 'main', url: 'https://github.com/org/repo.git'
            }
        }
        
        stage('Code Review') {
            steps {
                sh 'sonar-scanner -Dsonar.projectKey=myapp'
                script {
                    def qualityGate = waitForQualityGate()
                    if (qualityGate.status != 'OK') {
                        error "Pipeline aborted due to quality gate failure: ${qualityGate.status}"
                    }
                }
            }
        }
        
        stage('Unit Test') {
            steps {
                sh 'mvn test -DskipITs'
                junit 'target/surefire-reports/*.xml'
                publishCoverage adapters: [jacocoAdapter('target/jacoco.exec')]
            }
        }
        
        stage('Build Docker Image') {
            steps {
                script {
                    docker.build("${DOCKER_REGISTRY}/${IMAGE_NAME}:${BUILD_NUMBER}")
                }
            }
        }
        
        stage('Push Image') {
            steps {
                script {
                    docker.withRegistry("https://${DOCKER_REGISTRY}", 'docker-credentials') {
                        docker.image("${DOCKER_REGISTRY}/${IMAGE_NAME}:${BUILD_NUMBER}").push()
                    }
                }
            }
        }
        
        stage('Deploy to Test') {
            steps {
                sh """
                    kubectl --namespace=test set image deployment/myapp \
                    myapp=${DOCKER_REGISTRY}/${IMAGE_NAME}:${BUILD_NUMBER}
                    kubectl --namespace=test rollout status deployment/myapp
                """
            }
        }
        
        stage('Integration Test') {
            steps {
                sh 'newman run tests/postman_collection.json -e tests/test_environment.json'
            }
        }
        
        stage('UI Automation Test') {
            steps {
                sh 'npx playwright test --reporter=html'
                publishHTML([
                    allowMissing: false,
                    alwaysLinkToLastBuild: true,
                    keepAllHistory: true,
                    reportDir: 'playwright-report',
                    reportFiles: 'index.html',
                    reportName: 'Playwright Report'
                ])
            }
        }
        
        stage('Deploy to Production') {
            when {
                branch 'main'
                expression { currentBuild.result == null || currentBuild.result == 'SUCCESS' }
            }
            steps {
                input message: 'Deploy to production?', ok: 'Deploy'
                sh """
                    kubectl --namespace=production set image deployment/myapp \
                    myapp=${DOCKER_REGISTRY}/${IMAGE_NAME}:${BUILD_NUMBER}
                    kubectl --namespace=production rollout status deployment/myapp
                """
            }
        }
    }
    
    post {
        always {
            cleanWs()
        }
        success {
            slackSend channel: '#deployments', color: 'good', message: "Build ${BUILD_NUMBER} succeeded!"
        }
        failure {
            slackSend channel: '#deployments', color: 'danger', message: "Build ${BUILD_NUMBER} failed!"
        }
    }
}

# 多阶段构建 - Java Spring Boot 示例
# Stage 1: Build
FROM maven:3.9-eclipse-temurin-17 AS builder
WORKDIR /app
COPY pom.xml .
COPY src ./src
RUN mvn clean package -DskipTests

# Stage 2: Runtime
FROM eclipse-temurin:17-jre-alpine
WORKDIR /app

# 创建非 root 用户
RUN addgroup -S appgroup && adduser -S appuser -G appgroup

# 复制构建产物
COPY --from=builder /app/target/*.jar app.jar

# 设置时区
ENV TZ=Asia/Shanghai
RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone

# 健康检查
HEALTHCHECK --interval=30s --timeout=3s --start-period=40s --retries=3 \
  CMD wget -qO- http://localhost:8080/actuator/health || exit 1

# 切换用户
USER appuser

EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]

# Kubernetes Deployment
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
  namespace: production
  labels:
    app: myapp
    version: v1.0.0
spec:
  replicas: 3
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
    spec:
      containers:
      - name: myapp
        image: registry.example.com/myapp-backend:latest
        ports:
        - containerPort: 8080
        env:
        - name: SPRING_PROFILES_ACTIVE
          value: "production"
        - name: DB_HOST
          valueFrom:
            secretKeyRef:
              name: db-secret
              key: host
        resources:
          requests:
            memory: "512Mi"
            cpu: "250m"
          limits:
            memory: "1Gi"
            cpu: "500m"
        livenessProbe:
          httpGet:
            path: /actuator/health/liveness
            port: 8080
          initialDelaySeconds: 60
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /actuator/health/readiness
            port: 8080
          initialDelaySeconds: 30
          periodSeconds: 5
---
# Kubernetes Service
apiVersion: v1
kind: Service
metadata:
  name: myapp-service
  namespace: production
spec:
  selector:
    app: myapp
  ports:
  - protocol: TCP
    port: 80
    targetPort: 8080
  type: ClusterIP
---
# Kubernetes Ingress
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: myapp-ingress
  namespace: production
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
spec:
  tls:
  - hosts:
    - myapp.example.com
    secretName: myapp-tls
  rules:
  - host: myapp.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: myapp-service
            port:
              number: 80