129 lines
4.9 KiB
Markdown
129 lines
4.9 KiB
Markdown
# 🖥️ 双前端架构策略
|
||
|
||
> 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*
|