# 🖥️ 双前端架构策略

> AI Agent 在生成前端代码时必须先阅读本文档，明确目标前端的职责边界、技术约束和设计原则。

---

## 1. 整体架构

本项目采用「一后端 + 双前端 + 共享层」架构：

```
vibe-cursor-pro/（Cursor 工作区）
├── Case-Database-Backend/          ← PHP Hyperf + Swoole 后端（统一 API 服务）
├── Case-Database-Frontend-user/    ← Vue 3 用户端（面向终端用户）
├── Case-Database-Frontend-admin/   ← Vue 3 管理端（面向运营/管理人员）
└── Case-Database-Frontend-shared/           ← 共享类型定义、工具函数、API 契约常量
```

---

## 2. 前端职责边界

### Case-Database-Frontend-user/（用户端）

| 维度 | 说明 |
|---|---|
| **目标用户** | 普通终端用户（公开访问 + 登录用户） |
| **核心体验** | 性能优先、流畅交互、移动端友好 |
| **设计风格** | 品牌化、轻量、视觉吸引力强 |
| **页面规模** | 中小型页面，单页功能聚焦 |
| **权限模型** | 简单（登录/未登录、会员等级） |
| **SEO 需求** | 有（落地页、详情页考虑 SSG/SSR） |
| **API 前缀** | `/api/`（用户端接口） |

**典型页面**：首页、商品详情、购物车、个人中心、订单查询

### Case-Database-Frontend-admin/（管理端）

| 维度 | 说明 |
|---|---|
| **目标用户** | 内部运营人员、管理员 |
| **核心体验** | 功能完整、信息密度高、操作高效 |
| **设计风格** | 专业、实用、Element Plus 标准组件优先（仅管理端） |
| **页面规模** | 复杂页面（多 Tab、嵌套表单、数据大表格） |
| **权限模型** | 精细（RBAC：角色、菜单、按钮级权限） |
| **SEO 需求** | 无（内部系统，登录后访问） |
| **API 前缀** | `/admin/`（管理端接口） |

**典型页面**：数据看板、订单管理、用户管理、权限配置、系统设置

---

## 3. 共享层（Case-Database-Frontend-shared/）

仅包含**纯 TypeScript**内容（配合 JSDoc 类型注释），不引入任何 UI 框架：

```
Case-Database-Frontend-shared/
├── constants/      ← 业务枚举（订单状态、权限码等）
├── utils/          ← 纯函数工具（日期格式化、金额计算等）
└── api-schema/     ← API 请求/响应的 JSDoc 类型定义
```

> **规则**：Case-Database-Frontend-shared/ 中的代码必须可被两个前端同时使用，不得包含平台特定代码。

---

## 4. 技术差异对比

| 技术点 | Case-Database-Frontend-user/ | Case-Database-Frontend-admin/ |
|---|---|---|
| **UI 框架** | 自定义组件 + Tailwind | Element Plus（优先使用标准组件） |
| **响应式** | 移动优先（xs → xl） | 桌面优先（≥ 1280px 为主） |
| **路由** | Vue Router（History 模式） | Vue Router（History 模式 + 权限守卫） |
| **状态管理** | Pinia（轻量 Store） | Pinia（含权限 Store、菜单 Store） |
| **打包优化** | 激进代码分割、图片优化、SSG 评估 | 按需分割（菜单级懒加载） |
| **错误处理** | 用户友好提示（Toast） | 详细错误码 + 日志上报 |
| **主题** | 品牌色（见 ui-specs-user.md） | 专业蓝灰（见 ui-specs-admin.md） |

---

## 5. AI Agent 工作约定

### 目录前缀约定

**每次前端相关任务，必须在 prompt 中明确指定目标目录**：

```
✅ 正确：在 Case-Database-Frontend-user/ 中创建商品详情页
✅ 正确：在 Case-Database-Frontend-admin/ 中创建订单管理页
❌ 错误：创建商品详情页（未指定前端）
```

### 设计原则差异

当 Agent 在 `Case-Database-Frontend-user/` 工作时：
- 移动端优先（先写 xs 断点，再扩展到 lg）
- 组件必须考虑骨架屏 / 懒加载
- 图片必须有 alt 属性、考虑 WebP 格式
- 交互反馈必须流畅（避免页面跳动）

当 Agent 在 `Case-Database-Frontend-admin/` 工作时：
- 桌面端优先（以 1280px 为基准设计）
- 优先使用 Element Plus 标准组件（`el-table`、`el-form`、`el-dialog` 等）
- 页面操作必须有权限守卫（`v-permission` 指令 或 `hasPermission()` 检查）
- 数据操作必须有二次确认（删除、批量操作等危险操作）

### 共享代码优先

在生成 API 调用代码时：
1. 先检查 `Case-Database-Frontend-shared/constants/` 是否已有对应枚举或常量
2. 先检查 `Case-Database-Frontend-shared/api-schema/` 是否已有接口契约
3. 有则复用，无则在 Case-Database-Frontend-shared/ 中新建后再引用

---

## 6. 部署架构

```
用户端:   https://www.example.com       → Nginx → Case-Database-Frontend-user/dist/
管理端:   https://admin.example.com     → Nginx → Case-Database-Frontend-admin/dist/
API:      https://api.example.com       → Nginx → Hyperf (9501)
WebSocket: wss://api.example.com/ws    → Nginx → Swoole (9502)
```

---

*最后更新: 2026-02-26*