100 lines
4.1 KiB
Markdown
100 lines
4.1 KiB
Markdown
# 前端开发规范
|
||
|
||
## 技术栈
|
||
|
||
Next.js + TypeScript + React + Tailwind CSS + Zustand/Jotai + pnpm
|
||
|
||
### 核心依赖
|
||
|
||
- **实时通信**: SSE / WebSocket
|
||
- **可视化**: Mermaid + 图谱可视化库
|
||
- **测试**: Vitest + Testing Library
|
||
- **代码质量**: ESLint (flat config) + Prettier + Husky + lint-staged
|
||
|
||
## 开发命令
|
||
|
||
```bash
|
||
pnpm install # 安装依赖
|
||
pnpm add <pkg> # 添加依赖
|
||
pnpm remove <pkg> # 移除依赖
|
||
|
||
pnpm dev # 启动开发服务器 (默认端口 3000)
|
||
pnpm build # 构建生产版本
|
||
pnpm start # 启动生产服务器
|
||
|
||
pnpm lint # 运行 ESLint 检查
|
||
pnpm type-check # TypeScript 类型检查
|
||
|
||
# 代码格式化（Prettier）
|
||
pnpm format # 格式化全部文件
|
||
pnpm format:check # 检查格式是否合规（CI / 提交钩子使用）
|
||
|
||
# 测试（Vitest）
|
||
pnpm test # 运行全部测试（单次）
|
||
pnpm test:watch # 监听模式
|
||
pnpm test:coverage # 运行测试并生成覆盖率报告
|
||
```
|
||
|
||
## 代码规范
|
||
|
||
### 页面设计
|
||
|
||
图标：统一使用 Lucide 图标，界面全程禁止使用表情符号。
|
||
设计标准：对标 Awwwards 顶级网站水准，达到 Awwwards、FWA、CSS Design Awards 每日最佳网站同等设计品质。
|
||
创意自由度：将浏览器视作交互式艺术画布，跳出传统布局框架，追求先锋视觉风格、实验性排版、流畅物理动效、极具冲击力的文字版式。
|
||
沉浸式体验：融合代码、高级渲染逻辑、图片素材，打造统一完整的精品页面，做出突破常规 UI 认知、令人惊艳的数字交互体验。
|
||
|
||
### 通用规范
|
||
|
||
- 遵循 ESLint + Prettier 配置，提交前必须通过 lint 与格式检查
|
||
- 使用 TypeScript 严格模式 (`strict: true`)，禁止使用 `any` 类型
|
||
- 组件使用函数式组件 + Hooks，优先使用 Server Components，必要时使用 `'use client'`
|
||
- 文件命名: 组件使用 PascalCase (`UserProfile.tsx`)，工具函数使用 camelCase (`formatDate.ts`)
|
||
- 使用 `path` 别名 (`@/*`) 导入模块，避免相对路径层级过深
|
||
- 状态管理: 全局状态使用 Zustand/Jotai，局部状态使用 React useState/useReducer
|
||
|
||
### CSS 变量引用
|
||
|
||
CSS 变量引用遵循 **三层递进规则**，优先级由上至下。
|
||
|
||
#### 规则
|
||
|
||
```text
|
||
Tailwind 映射类 → 优先使用
|
||
Tailwind 任意值 [var(--)] → 仅当变量不在 @theme 映射表中时使用
|
||
内联 style → 仅限复合值 / 动态运行时值
|
||
```
|
||
|
||
- 统一通过 `lib/api`（`client.ts` 出口）调用后端，禁止在组件内散落 fetch
|
||
- SSE 连接封装在 `lib/sse-client.ts`，不在组件内直接实例化 EventSource
|
||
- 所有 API 调用必须有 TypeScript 类型定义和错误处理（`ApiError` 统一承载 code/trace_id）
|
||
|
||
## 可视化规范
|
||
|
||
- 图谱可视化使用专用图谱库，Mermaid 用于流程图/时序图等
|
||
- 可视化组件必须支持响应式和主题切换 (暗色/亮色)
|
||
|
||
## 代码审查
|
||
|
||
```bash
|
||
pnpm lint # ESLint 检查
|
||
pnpm type-check # TypeScript 类型检查
|
||
pnpm format:check # Prettier 格式检查
|
||
pnpm test # Vitest 测试
|
||
```
|
||
|
||
- 必须同时通过 lint、type-check 与格式检查才能提交
|
||
- Husky + lint-staged 已配置 `pre-commit` 钩子：对暂存文件自动跑 ESLint --fix + Prettier，再整体 type-check；不通过则阻止提交（临时跳过用 `git commit --no-verify`）
|
||
|
||
## 绝对禁止事项
|
||
|
||
- 直接修改 `package.json` 或 `pnpm-lock.yaml`（依赖必须用 `pnpm add/remove`；scripts 字段可用 `pnpm pkg set`，注意带冒号的键需用方括号语法 `scripts["name"]`）
|
||
- 在客户端代码中硬编码敏感信息 (密钥、Token等)
|
||
- 使用 `any` 类型 (除非经过团队评审)
|
||
- 忽略 TypeScript 或 ESLint 错误强制提交
|
||
- 在 Server Component 中直接使用 `useState`、`useEffect` 等客户端 Hooks
|
||
- 使用 CSS-in-JS 方案 (统一使用 Tailwind CSS)
|
||
- 在 Client Component 中直接调用数据库
|
||
- 在 useEffect 中做页面初始数据请求
|
||
- 创建 Class 组件
|