YOU

Y.O.U stands for YOUR OWN UNIQUE, a pioneer in glowing inclusive beauty products. It provides daily power to glow the skin and life, aiming to make healthy skin touchable. --- AI生成技术文档 (前端开发指南文档) --- ## YOU项目前端开发指南 ### 1. 开发标准规范 #### 1.1 代码风格与格式化 - **统一工具链**： - ESLint配置：`eslint-config-airbnb` + `@typescript-eslint` 扩展 - Prettier规则：单引号/尾逗号/100字符行宽/2空格缩进 - 提交前自动格式化：`husky` + `lint-staged` - **TypeScript规范**： - 严格模式启用：`strict: true` - 禁止隐式any：`noImplicitAny: true` - 接口前缀：`I`（如`IProductInfo`） #### 1.2 命名约定 ```typescript // 变量/函数：camelCase const productSKU = 'GLOW-2023'; // 组件：PascalCase function GlowButton() {...} // 常量：UPPER_SNAKE_CASE const MAX_ITEMS = 10; // 布尔变量：is/has/can前缀 const isActive = true; ``` #### 1.3 文件组织 ``` src/ ├── domains/ // 业务领域 │ ├── product/ // 产品模块 │ └── user/ // 用户模块 ├── core/ // 核心逻辑 │ ├── lib/ // 工具库 │ └── hooks/ // 自定义Hook ├── design-system/ // 设计系统 └── assets/ // 静态资源 ``` #### 1.4 文档要求 - 组件文档：使用Storybook编写可视化用例 - 核心函数：JSDoc注释（含@param/@return） ```javascript /** * 计算产品发光效果值 * @param {number} skinTone - 肤色值(0-100) * @returns {string} HEX颜色码 */ function calculateGlow(skinTone) {...} ``` --- ### 2. UI/UX指南 #### 2.1 设计系统实现 - **组件库**：基于Material-UI定制 - 主题变量：`primaryGlow: '#FF6BD6'` - 动效规范：发光效果使用`text-shadow`动画 - 图标体系：`@mui/icons-material` + 自定义SVG #### 2.2 响应式设计 ```css /* 断点配置（基于品牌用户设备分析） */ @screen sm: 384px; /* 低端设备 */ @screen md: 768px; /* 平板 */ @screen lg: 1024px; /* 桌面 */ ``` #### 2.3 可访问性 - WCAG 2.1 AA级合规 - 对比度：文本/背景 ≥ 4.5:1 - ARIA属性：为发光效果添加`aria-live="polite"` - 键盘导航：焦点环使用品牌发光色 #### 2.4 交互模式 - **产品展示**：3D旋转+发光渐变动效 - **肤质检测**：分步向导式交互 - **反馈机制**：微交互震动（`react-spring`实现） --- ### 3. 组件架构 #### 3.1 组件分层 | 层级 | 示例 | 复用范围 | |------|------|----------| | 原子 | `GlowText` | 跨项目 | | 分子 | `SkinTonePicker` | 当前项目 | | 模板 | `ProductShowcaseLayout` | 特定页面 | #### 3.2 状态管理 - **全局状态**：Zustand（轻量级方案） ```javascript const useProductStore = create(set => ({ glowIntensity: 5, setGlow: (value) => set({ glowIntensity: value }) })); ``` - **局部状态**：`useReducer` + Context #### 3.3 组件契约 ```typescript interface GlowButtonProps { intensity: 1 | 2 | 3; // 发光强度等级 onGlowStart?: () => void; // 发光开始事件 glowColor?: string; // 可选自定义色 } ``` --- ### 4. 性能优化 #### 4.1 加载优化 - **代码分割**：基于路由的`React.lazy` ```javascript const SkinAnalysis = lazy(() => import('./domains/skin/Analysis')); ``` - **图片策略**： - WebP格式优先 - CDN动态裁剪：`?width=400&format=webp` #### 4.2 渲染性能 - **虚拟化列表**：`react-window`用于产品库 - **记忆化**：`React.memo` + `useCallback` - **GPU加速**：CSS `will-change: transform;` #### 4.3 包体积控制 ```bash # 构建分析 npx source-map-explorer build/static/js/*.js ``` - 目标：主包 ≤ 150KB - 策略：按需引入`@mui/icons-material` --- ### 5. 测试标准 #### 5.1 测试金字塔 | 层级 | 工具 | 覆盖率目标 | |------|------|------------| | 单元 | Jest | 核心逻辑100% | | 集成 | React Testing Library | 组件85% | | E2E | Cypress | 关键路径100% | #### 5.2 特殊测试场景 ```javascript // 发光效果测试用例 test('GlowButton should emit light on hover', () => { render(); fireEvent.mouseEnter(screen.getByRole('button')); expect(screen.getByTestId('glow-effect')).toHaveStyle('opacity: 1'); }); ``` --- ### 6. 构建与部署 #### 6.1 工作流 ```mermaid graph LR A[开发] -->|Commit| B(ESLint/Prettier) B --> C[单元测试] C --> D[MR请求] D --> E[CI流水线] E --> F[预发布验证] ``` #### 6.2 环境配置 ```env # .env.production REACT_APP_API_ENDPOINT=https://api.youbeauty.com/v2 REACT_APP_GLOW_EFFECT_LEVEL=pro ``` #### 6.3 部署策略 - **蓝绿部署**：通过CloudFront路由切换 - **渐进式发布**：Feature Flags控制新功能 - **回滚机制**：5分钟内可回退至上一版本 > **扩展性设计**： > 1. 设计系统版本独立发布（npm私库） > 2. 微前端准备：通过`module-federation`支持未来子产品线接入 > 3. 性能监控集成：Sentry + Lighthouse CI 本指南将持续更新于YOU项目的`frontend-wiki`仓库，所有变更需通过架构评审委员会批准。 --- AI Generated Technical Documentation (Frontend Guideline Document) --- ### **Frontend Development Guideline Document for YOU Project** *(YOUR OWN UNIQUE - Inclusive Beauty Products)* --- #### **1. Development Standards** **1.1 Code Style & Formatting** - **Tools**: ESLint (Airbnb config), Prettier - **Rules**: - 2-space indentation, LF line endings - Max line length: 100 characters - Semicolons enforced - Single quotes for JS, double quotes for JSX - **Automation**: Pre-commit hooks (Husky + lint-staged) **1.2 Naming Conventions** - **Variables**: `camelCase` (e.g., `userProfile`) - **Components**: `PascalCase` (e.g., `GlowButton.vue`) - **Constants**: `UPPER_SNAKE_CASE` (e.g., `MAX_RETRY_COUNT`) - **Files/Folders**: `kebab-case` (e.g., `product-card/`) **1.3 File & Folder Organization** ```plaintext src/ ├── assets/ # Static assets (SVGs, images) ├── components/ # Reusable components │ ├── common/ # Generic UI (Button, Card) │ └── domain/ # Domain-specific (SkinAnalysisTool) ├── composables/ # Vue Composition API logic ├── layouts/ # App-wide layouts ├── router/ # Vue Router configurations ├── store/ # Pinia state modules ├── styles/ # Global SCSS variables/mixins ├── utils/ # Helper functions └── views/ # Page-level components ``` **1.4 Documentation Requirements** - **Components**: JSDoc for props, events, and slots (e.g., `@prop {String} skinTone`). - **Functions**: TypeScript interfaces for arguments/return types. - **README.md** per module folder explaining purpose and usage. --- #### **2. UI/UX Guidelines** **2.1 Design System** - **Tools**: Figma integration via [Storybook](https://storybook.js.org/). - **Tokens**: CSS variables for colors, spacing, typography (e.g., `--glow-primary: #FF6B9D;`). - **Component Library**: Atomic design (Atoms → Molecules → Organisms). **2.2 Responsive Design** - **Breakpoints**: - Mobile: < 768px - Tablet: 768px – 1024px - Desktop: > 1024px - **Approach**: Mobile-first CSS, `flex/grid` layouts, relative units (`rem`, `%`). **2.3 Accessibility (WCAG 2.1 AA)** - **Semantic HTML**: ARIA labels for icons, `alt` text for images. - **Contrast**: Minimum 4.5:1 text/background ratio (verified via axe-core). - **Keyboard Navigation**: Focus management for interactive elements. **2.4 Interaction Patterns** - **Animations**: Subtle transitions (Framer Motion) for feedback (e.g., button hover). - **Loading States**: Skeleton loaders for async data. - **Error Handling**: Toast notifications with actionable messages. --- #### **3. Component Architecture** **3.1 Design Patterns** - **Stateless Components**: Pure UI elements (e.g., `GlowBadge`). - **Stateful Containers**: Fetches data and passes props (e.g., `SkinHealthDashboard`). - **Compound Components**: Context API for related components (e.g., `TabGroup` + `TabItem`). **3.2 State Management** - **Global State**: Pinia stores for cross-component data (e.g., user preferences). - **Local State**: Vue `ref`/`reactive` for component-specific state. - **Data Fetching**: Composables with `useFetch` abstraction (axios + error handling). **3.3 Props & Events** - **Props**: - Type-checked with TypeScript/Vue PropTypes. - Default values for optional props. - **Events**: Emit custom events (e.g., `@glow-effect-applied`). **3.4 Reusable Components** - **Props API**: Minimize required props; use slots for content injection. - **Theming**: Support `theme` prop (light/dark) via CSS variables. - **Documentation**: Storybook stories for visual testing. --- #### **4. Performance Guidelines** **4.1 Code Splitting & Lazy Loading** - **Routes**: Vue Router lazy imports (`() => import('./SkinAnalysis.vue')`). - **Components**: `defineAsyncComponent` for heavy non-critical UIs. **4.2 Bundle Optimization** - **Tree Shaking**: ES Module imports (e.g., `import { Button } from 'ui-library'`). - **Compression**: Brotli/Gzip via Vite build. - **Vendor Chunks**: Separate `node_modules` into `vendor-[hash].js`. **4.3 Rendering Performance** - **Virtualization**: `vue-virtual-scroller` for large lists. - **Memoization**: `computed` properties and `v-once` for static content. - **Debouncing**: Input handlers (e.g., search with Lodash `debounce`). **4.4 Memory Management** - **Event Listeners**: Remove in `onUnmounted()` lifecycle hook. - **Large Data**: Web Workers for CPU-intensive tasks (e.g., image processing). --- #### **5. Testing Standards** **5.1 Unit Testing** - **Tools**: Vitest + Vue Test Utils. - **Coverage**: > 80% for core logic (business rules, utils). - **Patterns**: Mock API calls (MSW), snapshot testing for components. **5.2 Integration Testing** - **Scope**: Component interactions (e.g., form validation flows). - **Tools**: Testing Library (`render`, `fireEvent`). **5.3 E2E Testing** - **Tool**: Cypress with Percy visual regression. - **Critical Paths**: User onboarding, product customization, checkout. **5.4 Testing Tools** ```json "devDependencies": { "vitest": "^1.0.0", "@testing-library/vue": "^7.0.0", "cypress": "^12.0.0", "@percy/cypress": "^3.0.0" } ``` --- #### **6. Build and Deployment** **6.1 Development Workflow** - **Branching**: GitFlow (main → develop → feature branches). - **CI/CD**: GitHub Actions for lint/test on PR; auto-deploy on merge to `main`. **6.2 Build Optimization** - **Vite Config**: - Minify CSS/JS (`cssnano`, `terser`). - PWA support via `vite-plugin-pwa`. - **Asset Handling**: Inline assets < 10KB; hash filenames for caching. **6.3 Environment Configuration** - **Env Variables**: `.env.[mode]` files (e.g., `.env.staging`, `.env.production`). - **Security**: Prefix sensitive keys with `VITE_` for Vite exposure. **6.4 Deployment Strategies** - **Static Hosting**: Vercel/Netlify for CDN distribution. - **Blue/Green**: Zero-downtime releases via cloud provider (AWS/Azure). - **Rollback**: Automated on E2E failure (monitored via Sentry). --- **Revision Log**: Maintain in `CHANGELOG.md`; review quarterly for tech debt. **Ownership**: Frontend Guild oversees updates; deviations require RFC. --- 生成时间: 6/19/2025, 9:06:00 PM ---