From 5500a0b45b3cee7139ea8b6f2b0ae3b6b7de1737 Mon Sep 17 00:00:00 2001
From: xiaoxia <dev@xiaoxiajianji.com>
Date: Thu, 23 Jul 2026 22:02:12 +0800
Subject: [PATCH] =?UTF-8?q?docs(#783):=20=E8=A1=A5=E5=85=85=E5=89=8D?=
 =?UTF-8?q?=E7=AB=AF=E5=91=BD=E5=90=8D=E8=A7=84=E8=8C=83=E5=88=B0CODING-ST?=
 =?UTF-8?q?ANDARD.md?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

新增第8章 前端规范，涵盖：
- 文件命名规范（目录/组件/API/Hooks/Store等）
- 组件命名
- 变量与函数命名
- 导入路径规范
- CSS/样式命名
---
 docs/CODING-STANDARD.md | 85 ++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 83 insertions(+), 2 deletions(-)
 mode change 100644 => 100755 docs/CODING-STANDARD.md

diff --git a/docs/CODING-STANDARD.md b/docs/CODING-STANDARD.md
old mode 100644
new mode 100755
index cc9fa1a53..94e21f178
--- a/docs/CODING-STANDARD.md
+++ b/docs/CODING-STANDARD.md
@@ -445,5 +445,86 @@ def list_all_assets() -> list[Asset]:
 
 ---
 
-**最后更新**: 2026-06-15  
-**版本**: v1.0
+## 8. 前端规范（React + TypeScript）
+
+### 8.1 文件命名规范
+
+| 类型 | 风格 | 示例 | 说明 |
+|------|------|------|------|
+| **目录名** | kebab-case | `editing-planner/`, `asset-selector/` | 全小写，多单词用短横线连接 |
+| **组件文件** | PascalCase | `AssetSelector.tsx`, `MediaPanel.tsx` | 与组件导出名一致 |
+| **页面组件** | PascalCase | `EditingPlanner.tsx`, `MyTemplates.tsx` | 放在 kebab-case 目录中 |
+| **API 文件** | kebab-case | `template-editor.ts`, `voice-clone.ts` | 与 RESTful 资源路径风格一致 |
+| **Hooks** | camelCase (use前缀) | `useAuth.ts`, `useCloneProgress.ts` | React 官方惯例 |
+| **Store** | kebab-case | `auth-store.ts`, `ui-store.ts` | |
+| **工具函数/helpers** | kebab-case | `format-duration.ts`, `date-utils.ts` | |
+| **类型定义** | kebab-case | `types.ts`, `subtitle-types.ts` | 目录内类型定义可用 `types.ts` |
+| **常量** | UPPER_SNAKE_CASE | `MAX_UPLOAD_SIZE`, `API_BASE_URL` | |
+| **测试文件** | 与被测文件同名 + `.test` | `auth.test.ts`, `AssetSelector.test.tsx` | 放在 `test/` 目录下，保持相同相对路径 |
+
+### 8.2 组件命名
+
+- 组件名使用 **PascalCase**，与文件名一致
+- 默认导出组件名与文件名相同
+- 高阶组件/包装器用 `with` 前缀：`withAuth(Component)`
+- 渲染属性组件用 `Render` 后缀：`UserRender`
+
+```tsx
+// ✅ 正确
+// 文件: AssetSelector.tsx
+const AssetSelector: React.FC<AssetSelectorProps> = ({ assets }) => { ... };
+export default AssetSelector;
+
+// ❌ 错误
+// 文件: asset-selector.tsx
+const assetSelector = () => { ... };
+```
+
+### 8.3 变量与函数命名
+
+- **变量/函数**：camelCase
+- **布尔变量**：用 `is/has/should/can` 前缀
+- **事件处理函数**：用 `handle` 前缀 + 事件名
+- **事件 handler prop**：用 `on` 前缀
+
+```tsx
+// ✅ 正确
+const isLoading = true;
+const hasError = false;
+const handleSubmit = () => { ... };
+
+<Button onClick={onClick} />
+```
+
+### 8.4 导入路径
+
+- 使用 `@/` 别名引用 `src/` 下的文件
+- 同一目录内用相对路径 `./`
+- 导入顺序：React → 第三方库 → @/内部模块 → 相对路径 → 样式
+
+```tsx
+import React, { useState } from 'react';
+import { Button, Modal } from 'antd';
+import { useAuth } from '@/hooks/useAuth';
+import { Asset } from '@/api/asset-selector';
+import { MediaPanel } from './MediaPanel';
+import './AssetSelector.css';
+```
+
+### 8.5 CSS/样式命名
+
+- CSS Modules / CSS 类名：kebab-case
+- styled-components：PascalCase（与组件一致）
+- Tailwind 工具类遵循官方惯例
+
+```css
+/* ✅ 正确 */
+.asset-selector { ... }
+.asset-item { ... }
+.asset-item--active { ... }
+```
+
+---
+
+**最后更新**: 2026-07-23  
+**版本**: v1.1