soul-yongping/开发文档/4、前端/前端开发规范.md

前端开发规范 (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 展示组件或数据流依赖。