初始化

docs/architecture/frontend-strategy.md

@@ -0,0 +1,128 @@
+# 🖥️ 双前端架构策略
+
+> 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*