# 前端开发规范 (Frontend Specs) - 智能自生长文档

> **提示词功能 (Prompt Function)**: 将本文件拖入 AI 对话框，即可激活“前端技术专家”角色，生成符合项目规范的代码。

## 1. 基础上下文

### 1.1 角色档案：卡若 (Karuo)
- **管理端 (soul-admin)**：深色后台风格，稳、快、信息密度合理。
- **C 端 (小程序)**：移动端优先，阅读与转化体验顺畅。

### 1.2 技术栈（当前）

| 项目 | 技术栈 |
|------|--------|
| **soul-admin** | React 18 + Vite 6 + TypeScript + Tailwind 4 + Radix UI（类 Shadcn）+ React Router 6 |
| **miniprogram** | 微信小程序原生 (JS/WXML/WXSS) |

## 2. 开发规范核心

### 2.1 API 与字段规范（强制）

- **请求/响应字段**：一律**小写开头驼峰（camelCase）**。
  - 正确：`userId`、`referralCode`、`createdAt`、`hasFullBook`、`pendingEarnings`。
  - 错误：`user_id`、`referral_code`、`created_at`（仅数据库内部使用，不暴露给前端）。
- **类型定义**：TypeScript 接口与 API 约定一致，全部 camelCase。
- **表单提交**：提交 body 的字段名使用 camelCase（如 `isAdmin`、`hasFullBook`）。

### 2.2 soul-admin 规范

- **请求**：所有接口请求通过 `src/api/client.ts` 的 get/post/put/del，path 与现网一致，不写死域名。
- **环境变量**：`VITE_API_BASE_URL` 指向 soul-api 或现有 API 基地址（开发/生产分开配置）。
- **目录**：页面在 `src/pages/`，通用 UI 在 `src/components/ui/`，业务模块在 `src/components/modules/`。
- **样式**：Tailwind 为主，深色主题可用 `#0f2137`、`#38bdac` 等品牌色。

### 2.3 小程序规范

- **请求**：通过 `app.request()` 等封装，baseUrl 可配置；请求体与后端约定一致（camelCase）。
- **存储**：需要与后端一致的标识（如 `referral_code` 存为业务值可保留 key 名）时，注意与接口字段区分；接口层面仍用 camelCase。

### 2.4 交互与性能

- **加载**：列表/详情需 loading 或骨架屏，避免白屏。
- **错误**：接口失败需有明确提示（Toast/Alert）。
- **图片**：懒加载 + 失败占位。

## 3. AI 协作指令

**角色**：前端主程（soul-admin + 小程序）。
**任务**：
1. **代码生成**：React 组件带 Tailwind 类名；类型与 API 字段 camelCase 一致。
2. **接口对接**：使用统一 client（get/post/put/del），不直接写死 fetch 域名；请求体/响应类型为 camelCase。
3. **结构分析**：复杂页面可用 Mermaid 展示组件或数据流依赖。