# 前端架构

**我是卡若。**

前端分两块：**管理端 soul-admin**（给运营/自己用）、**C 端 miniprogram**（给用户用）。目标都是稳、快、体验好。

## 1. 当前前端分工

| 项目 | 技术栈 | 说明 |
|------|--------|------|
| **soul-admin** | React 18 + Vite 6 + TypeScript + Tailwind 4 + Radix UI (Shadcn 风格) | 管理后台 SPA，对接 soul-api，路由与现网 /admin/* 对应 |
| **miniprogram** | 微信小程序原生 (JS/WXML/WXSS) | C 端主阵地：阅读、购买、分销、提现等 |

（原 Next.js 的 `app/view/`、`app/admin/` 可保留为备用或逐步下线。）

## 2. soul-admin 技术底座

- **框架**: React 18 + Vite 6，构建快、热更新稳。
- **语言**: TypeScript，类型与 API 字段一致（camelCase）。
- **样式**: Tailwind CSS 4，全局与组件级样式。
- **UI**: Radix UI 系（Dialog、Tabs、Switch 等），类 Shadcn 用法，深色管理后台风格。
- **路由**: React Router 6，路径与现网管理端一致（如 `/dashboard`、`/users`、`/withdrawals`）。
- **请求**: 统一走 `src/api/client.ts`（get/post/put/del），baseUrl 为 `VITE_API_BASE_URL`，path 与 soul-api 一致；**请求体与响应字段一律 camelCase**。

## 3. soul-admin 目录结构

\`\`\`
soul-admin/src/
├── api/
│   └── client.ts           # 统一请求封装，baseUrl + path
├── components/
│   ├── ui/                 # 通用 UI (Button, Card, Dialog, Table...)
│   └── modules/            # 业务模块 (如 UserDetailModal)
├── layouts/
│   └── AdminLayout.tsx     # 管理端布局与侧栏
├── pages/                  # 页面（与路由一一对应）
│   ├── login/
│   ├── dashboard/
│   ├── users/
│   ├── orders/
│   ├── distribution/
│   ├── withdrawals/
│   ├── content/
│   ├── chapters/
│   ├── settings/
│   ├── referral-settings/
│   ├── payment/
│   ├── match/
│   └── ...
├── lib/
│   └── utils.ts
├── App.tsx
└── main.tsx
\`\`\`

## 4. 小程序 (miniprogram)

- **技术**: 微信原生，`app.js` 全局、`app.request()` 封装请求，baseUrl 可配置指向 soul-api。
- **页面**: 首页、阅读、个人中心、分销、提现等；与 soul-api 接口对接，**请求/响应字段已统一为 camelCase**（如 `userId`、`referralCode`、`createdAt`）。
- **登录**: 微信登录 + 手机号授权，与后端 `/api/miniprogram/login` 等对接。

## 5. API 与数据规范

- **路径**: 与现网完全一致（如 `/api/user/profile`、`/api/admin/withdrawals`），由 soul-api 提供。
- **字段**: 所有请求体、响应体、前端类型定义**统一小写开头驼峰（camelCase）**：`userId`、`createdAt`、`referralCode`、`hasFullBook` 等。禁止对外使用 snake_case。
- **类型**: TypeScript 接口与 API 响应一一对应，便于联调与维护。

## 6. 交互与体验（通用）

- **加载**: 列表/详情加载时使用骨架屏或明确 loading 状态，避免白屏。
- **错误**: 接口失败要有提示（Toast/Alert），必要处可重试。
- **表单**: 提交字段与后端约定一致（camelCase），校验与错误信息清晰。

---
**总结**：管理端在 soul-admin（React+Vite），C 端在小程序；两者都通过统一 API 封装对接 soul-api，字段规范统一为 camelCase。