🖥️ 双前端架构策略

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 调用代码时：

先检查 Case-Database-Frontend-shared/constants/ 是否已有对应枚举或常量
先检查 Case-Database-Frontend-shared/api-schema/ 是否已有接口契约
有则复用，无则在 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

4.9 KiB Raw Blame History Unescape Escape