From 339695c85160643e07d7f01fab4149d3815d529f Mon Sep 17 00:00:00 2001
From: huangping <huangping@craftlabs.cn>
Date: Tue, 19 May 2026 10:35:49 +0800
Subject: [PATCH] docs: add frontend framework design (10 sections:
 architecture, modules, layout, components, templates, dataflow, conventions)

---
 .../2026-05-19-frontend-framework-design.md   | 665 ++++++++++++++++++
 1 file changed, 665 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-05-19-frontend-framework-design.md

diff --git a/docs/superpowers/specs/2026-05-19-frontend-framework-design.md b/docs/superpowers/specs/2026-05-19-frontend-framework-design.md
new file mode 100644
index 0000000..1bc5877
--- /dev/null
+++ b/docs/superpowers/specs/2026-05-19-frontend-framework-design.md
@@ -0,0 +1,665 @@
+# CraftLabs 前端框架设计 v1.0
+
+> 基于设计体系 `2026-05-19-design-system.md` 提炼的前端工程框架规范  
+> 目标：统一架构、约束风格、加速开发、降低交接成本  
+> 日期：2026-05-19
+
+---
+
+## 目录
+
+1. [框架概述](#1-框架概述)
+2. [技术栈](#2-技术栈)
+3. [工程结构](#3-工程结构)
+4. [核心模块](#4-核心模块)
+5. [布局系统](#5-布局系统)
+6. [组件体系](#6-组件体系)
+7. [页面模板](#7-页面模板)
+8. [数据流](#8-数据流)
+9. [开发规范](#9-开发规范)
+10. [构建与部署](#10-构建与部署)
+
+---
+
+## 1. 框架概述
+
+### 1.1 定位
+
+CraftLabs 前端框架是基于 Vue 3 + Element Plus 的企业级 B2B 授权运营平台前端方案。在 Element Plus 之上注入品牌设计 Token，提供开箱即用的布局、组件、页面模板和开发约束。
+
+### 1.2 核心原则
+
+| 原则 | 说明 |
+|------|------|
+| **约定优于配置** | 路由、鉴权、API 封装、错误处理均有默认行为，开发者只需关注业务 |
+| **Token 驱动** | 所有视觉属性通过 CSS 变量控制，换肤只需改 `theme.css` |
+| **组件隔离** | 每个 `.vue` 文件自包含模板+逻辑+样式，`<script setup>` 统一风格 |
+| **渐进增强** | 在 Element Plus 基础上叠加品牌样式，不 fork 组件库 |
+| **安全默认** | JWT 存储 localStorage、401 自动登出、路由级鉴权 |
+
+### 1.3 层级架构
+
+```
+┌─────────────────────────────────────────────┐
+│               Views (页面层)                 │
+│   LicenseList  CustomersView  ContractsView  │
+├─────────────────────────────────────────────┤
+│            Components (组件层)               │
+│     StatsCard  SearchBar  DataTable  ...    │
+├─────────────────────────────────────────────┤
+│          Layout System (布局系统)            │
+│   MainLayout (Header+Sidebar+Breadcrumb)     │
+├──────────────┬──────────────┬───────────────┤
+│  Router      │  Store       │  API          │
+│  (鉴权/懒加载) │  (Pinia JWT) │  (axios封装)  │
+├──────────────┴──────────────┴───────────────┤
+│           Element Plus + Vue 3              │
+├─────────────────────────────────────────────┤
+│           Theme System (Token层)            │
+│         theme.css · CSS Variables           │
+└─────────────────────────────────────────────┘
+```
+
+---
+
+## 2. 技术栈
+
+| 层 | 选型 | 版本 | 说明 |
+|----|------|:--:|------|
+| 框架 | Vue 3 | ^3.5 | Composition API + `<script setup>` |
+| 构建 | Vite | ^6.0 | 极速 HMR + 开箱即用 |
+| UI 库 | Element Plus | ^2.9 | 组件库本体，CSS 变量覆盖换肤 |
+| 路由 | vue-router | ^4.5 | 懒加载 + meta 鉴权 |
+| 状态 | Pinia | ^2.3 | 轻量状态管理 |
+| HTTP | axios | ^1.7 | 拦截器 + JWT 注入 |
+| 语言 | JavaScript (ESM) | — | 暂用 JS，必要时渐进引入 TS |
+
+### 2.1 不引入的依赖
+
+| 库 | 原因 |
+|----|------|
+| Tailwind CSS | Element Plus 已覆盖组件样式，避免双体系 |
+| Vuex | Pinia 更轻量，官方推荐 |
+| Lodash | 项目规模不需要工具函数库 |
+| Moment.js | 日期格式化用原生 `Intl` 或字符串裁剪 |
+
+---
+
+## 3. 工程结构
+
+```
+web/delivery-platform-ui/
+├── public/
+│   ├── design-demo.html          # 设计 Demo（独立 HTML，无依赖）
+│   └── design-system.html        # 设计体系可视化
+├── src/
+│   ├── main.js                   # 入口：挂载 Vue + Pinia + Router + 401拦截器
+│   ├── App.vue                   # 根组件：纯 <router-view>
+│   ├── theme.css                 # ★ 全局主题 Token（CSS 变量）
+│   │
+│   ├── layout/
+│   │   └── MainLayout.vue        # ★ 主布局：Header + Sidebar + Breadcrumb
+│   │
+│   ├── router/
+│   │   └── index.js              # ★ 路由表 + 鉴权守卫
+│   │
+│   ├── stores/
+│   │   └── auth.js               # ★ 认证状态：JWT + login/logout/roles
+│   │
+│   ├── api/
+│   │   └── platform.js           # ★ API 封装：按模块导出 axios 请求函数
+│   │
+│   ├── utils/
+│   │   ├── apiErrorMessage.js    # 统一错误消息提取
+│   │   └── redactPayload.js      # Callback payload 脱敏
+│   │
+│   └── views/                    # ★ 页面组件（按模块命名）
+│       ├── HomeView.vue          # 工作台/Dashboard
+│       ├── LoginView.vue         # 登录页
+│       ├── ForbiddenView.vue     # 403
+│       ├── NotFoundView.vue      # 404
+│       ├── CustomersView.vue     # 客户管理
+│       ├── ProjectsView.vue      # 项目管理
+│       ├── ContractsView.vue     # 合同列表
+│       ├── ContractWizardView.vue # 合同创建向导
+│       ├── ContractDetailView.vue # 合同详情
+│       ├── DeliveriesView.vue    # 交付列表
+│       ├── DeliveryBatchWizardView.vue
+│       ├── DeliveryBatchDetailView.vue
+│       ├── LicenseSnListView.vue  # 许可SN列表
+│       ├── LicenseSnWizardView.vue
+│       ├── LicenseSnDetailView.vue
+│       ├── LicenseList.vue       # ★ 许可证管理（自研SDK核心页）
+│       ├── CallbackInboxView.vue  # Callback 收件箱
+│       ├── CallbackInboxDetailView.vue
+│       ├── IntegrationEnvironmentsView.vue
+│       ├── IntegrationProductLinesView.vue
+│       └── LayoutCompareView.vue  # 设计审核工具（内部）
+│
+├── package.json
+├── vite.config.js
+├── Dockerfile
+└── README.md
+```
+
+### 3.1 文件命名规范
+
+| 类型 | 规范 | 示例 |
+|------|------|------|
+| 页面视图 | `PascalCaseView.vue` | `CustomersView.vue` |
+| 布局组件 | `PascalCase.vue` | `MainLayout.vue` |
+| 路由/Store/API | `kebab-case.js` | `platform.js` |
+| 工具函数 | `camelCase.js` | `apiErrorMessage.js` |
+| 样式文件 | `kebab-case.css` | `theme.css` |
+
+---
+
+## 4. 核心模块
+
+### 4.1 主题系统 (`theme.css`)
+
+所有视觉 Token 集中在一个 CSS 文件中，通过覆盖 Element Plus 变量实现换肤。
+
+```css
+/* 核心 3 行即可改变全站主色调 */
+:root {
+  --el-color-primary: #2C3E6B;
+  --el-bg-color-page: #EAEFFA;
+  --el-border-radius-base: 6px;
+}
+
+/* 完整 Token 见 docs/superpowers/specs/2026-05-19-design-system.md */
+```
+
+**设计意图**：
+- 不修改 Element Plus 源码，只覆盖 CSS 变量
+- 更换品牌色只需改 `--el-color-primary` 一个值
+- 新页面自动继承主题，无需额外引入
+
+### 4.2 路由系统 (`router/index.js`)
+
+**路由表结构**：
+
+```js
+const routes = [
+  // 公开路由（无鉴权）
+  { path: "/login", component: LoginView },
+  
+  // 受保护路由（需要登录）
+  {
+    path: "/",
+    component: MainLayout,            // 统一布局壳
+    meta: { requiresAuth: true },
+    children: [
+      {
+        path: "licenses",             // 子路由路径
+        name: "licenses",             // 命名路由（用于编程跳转）
+        component: () => import("..."), // 懒加载
+        meta: { roles: ["SYS_ADMIN", "DEVELOPER"] }  // 角色鉴权
+      },
+      // ... 更多子路由
+    ]
+  },
+  
+  // 兜底路由
+  { path: "/403", component: ForbiddenView },
+  { path: "/:pathMatch(.*)*", component: NotFoundView },
+]
+```
+
+**鉴权守卫逻辑**：
+
+```
+用户访问页面
+  │
+  ├─ meta.requiresAuth && 无 token → 重定向 /login?redirect=原路径
+  │
+  ├─ meta.roles && 用户角色不匹配 → 重定向 /403
+  │
+  └─ 通过 → 正常渲染
+```
+
+**新增页面只需**：
+1. 在 `children` 数组中加一条路由
+2. 设置 `meta.roles` 控制可见角色
+3. `component: () => import(...)` 懒加载
+
+### 4.3 状态管理 (`stores/auth.js`)
+
+```js
+export const useAuthStore = defineStore("auth", {
+  state: () => ({
+    token: localStorage.getItem("craftlabs_platform_token") || "",
+    displayName: "",
+    roles: [],
+  }),
+  
+  actions: {
+    async login(username, password) {
+      const { data } = await axios.post("/api/v1/auth/login", { username, password })
+      this.token = data.token
+      this.roles = data.roles
+      localStorage.setItem("craftlabs_platform_token", this.token)
+      axios.defaults.headers.common.Authorization = `Bearer ${this.token}`
+    },
+    
+    logout() {
+      this.token = ""
+      localStorage.removeItem("craftlabs_platform_token")
+      delete axios.defaults.headers.common.Authorization
+    },
+  },
+})
+```
+
+**使用方式**：
+
+```js
+import { useAuthStore } from "../stores/auth"
+const auth = useAuthStore()
+
+// 模板中
+auth.hasAnyRole(["SYS_ADMIN", "DEVELOPER"])  // 角色判断
+auth.displayName                             // 用户名
+```
+
+### 4.4 API 层 (`api/platform.js`)
+
+```js
+// 每个后端端点导出为一个具名函数
+export function listCustomers(params) {
+  return axios.get("/api/v1/customers", { params })
+}
+
+export function createCustomer(body) {
+  return axios.post("/api/v1/customers", body)
+}
+
+export function updateCustomer(id, body) {
+  return axios.put(`/api/v1/customers/${id}`, body)
+}
+
+export function deleteCustomer(id) {
+  return axios.delete(`/api/v1/customers/${id}`)
+}
+```
+
+**约定**：
+- 函数名 = HTTP 动词 + 资源名：`listXxx` / `createXxx` / `updateXxx` / `deleteXxx` / `getXxx`
+- 状态变更用语义化函数名：`patchContractStatus()`、`addLine()`
+- 所有函数返回 axios Promise，由调用方 `await` + try/catch
+- 查询参数用 `{ params }` 传递（axios 自动序列化）
+
+### 4.5 全局错误处理 (`main.js`)
+
+```js
+// 401 自动登出拦截器
+axios.interceptors.response.use(
+  (r) => r,
+  (err) => {
+    if (err.response?.status === 401) {
+      const auth = useAuthStore()
+      auth.logout()
+      router.push({ name: "login", query: { redirect: router.currentRoute.value.fullPath } })
+    }
+    return Promise.reject(err)
+  }
+)
+```
+
+---
+
+## 5. 布局系统
+
+### 5.1 MainLayout 结构
+
+```
+┌──────────────────────────────────────────────────────────┐
+│ <header> 60px                                            │
+│  Logo │ 导航菜单 │         全局搜索 │ 🔔 │ ⚙️ │ 👤用户名   │
+├────────┬─────────────────────────────────────────────────┤
+│<aside> │ <div class="breadcrumb"> 46px                   │
+│ 232px  │ 授权运营 › 当前页面                              │
+│        ├─────────────────────────────────────────────────┤
+│ 菜单    │                                                 │
+│ 分组    │  <router-view />                               │
+│        │  (各页面通过 slot 注入到此区域)                   │
+│ 11项   │                                                 │
+│        │                                                 │
+└────────┴─────────────────────────────────────────────────┘
+```
+
+### 5.2 布局尺寸契约
+
+| 元素 | 尺寸 | CSS |
+|------|:--:|------|
+| Header | 60px | `height: 60px; flex-shrink: 0` |
+| Sidebar | 232px | `width: 232px; flex-shrink: 0` |
+| Breadcrumb | 46px | `height: 46px; flex-shrink: 0` |
+| Content | 自适应 | `flex: 1; padding: 16px 20px` |
+
+### 5.3 布局变体
+
+| 变体 | 触发条件 | 说明 |
+|------|---------|------|
+| 标准布局 | 默认 | Header + Sidebar + Breadcrumb + 全宽 Content |
+| Tree 布局 | `activeModule === 'licenses'` | 额外 280px Tree 面板在 Content 左侧 |
+| 全屏布局 | 无 Header/Sidebar | 登录页、403/404 页 |
+
+---
+
+## 6. 组件体系
+
+### 6.1 组件分类
+
+```
+组件层级：
+  Element Plus 基础组件 (el-button, el-table, el-dialog, ...)
+      │
+      ├── 直接使用（无需封装）
+      │   el-button  el-input  el-select  el-table  el-pagination
+      │   el-tag     el-badge  el-tree    el-dialog  el-card
+      │
+      ├── 组合组件（页面内组合）
+      │   搜索栏 + 表格 + 分页 → 列表页模板
+      │   统计卡片行 → Dashboard 模板
+      │
+      └── 业务组件（跨页面复用，按需抽取）
+          StatsCard  SearchFilterBar  StatusTag  ConfirmDialog
+```
+
+### 6.2 组件开发原则
+
+- **优先直接用 Element Plus**：90% 场景不需要封装
+- **抽取时机**：同一模式在 3+ 个页面出现时才抽取为独立组件
+- **Props 优先于全局状态**：组件通过 props 接收数据，不直接读 store
+- **Events 向上**：组件通过 `$emit` 通知父组件，不直接改父组件状态
+
+### 6.3 CSS 约定
+
+```css
+/* ✅ 推荐：scoped + CSS 变量 */
+<style scoped>
+.my-page { background: var(--el-bg-color-page); }
+.card { border-radius: var(--el-border-radius-base); }
+.btn-primary { background: var(--el-color-primary); }
+</style>
+
+/* ❌ 避免：硬编码色值 */
+<style scoped>
+.card { background: #EAEFFA; }  /* 应使用 CSS 变量 */
+</style>
+```
+
+---
+
+## 7. 页面模板
+
+### 7.1 标准列表页
+
+适用于：客户管理、合同管理、交付管理、许可SN
+
+```
+结构:
+  <统计卡片行> (可选)
+  <筛选栏>
+    [搜索框] [状态下拉] [查询按钮]          [+ 新建按钮]
+  </筛选栏>
+  <数据表格>
+    <el-table> + <el-pagination>
+  </数据表格>
+  <新建/编辑 Dialog>
+```
+
+**样板代码（约 200 行）**：
+
+```vue
+<script setup>
+import { ref, onMounted } from "vue"
+import { ElMessage, ElMessageBox } from "element-plus"
+import { useAuthStore } from "../stores/auth"
+import { listXxx, createXxx, updateXxx, deleteXxx } from "../api/platform"
+import { apiErrorMessage } from "../utils/apiErrorMessage"
+
+const auth = useAuthStore()
+const loading = ref(false), saving = ref(false)
+const rows = ref([]), total = ref(0), page = ref(1), pageSize = ref(10)
+const keyword = ref(""), filterStatus = ref("")
+const dialogVisible = ref(false), editingId = ref(null)
+const formRef = ref(null)
+const form = reactive({ name: "", ... })
+
+onMounted(() => { auth.restoreAxiosAuth(); load() })
+
+async function load() {
+  loading.value = true
+  try {
+    const { data } = await listXxx({ page: page.value-1, size: pageSize.value, keyword: keyword.value?.trim() })
+    rows.value = data.content ?? []
+    total.value = data.totalElements ?? 0
+  } catch(e) {
+    ElMessage.error(apiErrorMessage(e))
+  } finally { loading.value = false }
+}
+
+async function submit() {
+  await formRef.value.validate()
+  saving.value = true
+  try {
+    const payload = { name: form.name.trim(), ... }
+    editingId.value ? await updateXxx(editingId.value, payload) : await createXxx(payload)
+    dialogVisible.value = false
+    await load()
+  } catch(e) {
+    ElMessage.error(apiErrorMessage(e))
+  } finally { saving.value = false }
+}
+
+async function onDelete(row) {
+  await ElMessageBox.confirm(`确定删除「${row.name}」？`, "提示", { type: "warning" })
+  await deleteXxx(row.id)
+  await load()
+}
+</script>
+```
+
+### 7.2 Tree + 列表页
+
+适用于：许可证管理
+
+```
+结构:
+  <div class="license-page">        ← display: flex
+    <Tree Panel 280px>              ← 左侧固定宽度
+    <Main Panel>                    ← flex: 1
+      <统计卡片行>
+      <筛选栏 + 签发按钮>
+      <数据表格>
+    </Main Panel>
+  </div>
+```
+
+### 7.3 工作台 Dashboard
+
+适用于：首页
+
+```
+结构:
+  <统计卡片行 4列>
+  <趋势图 + 待办列表 2列>
+  <快捷入口>
+```
+
+### 7.4 详情页
+
+适用于：合同详情、交付详情、SN详情
+
+```
+结构:
+  <返回按钮 + 页面标题>
+  <详情卡片>
+    <el-descriptions> 或 自定义 KV 布局
+  </详情卡片>
+  <关联数据卡片> (可选：审计事件、Callback关联)
+  <操作按钮行>
+```
+
+---
+
+## 8. 数据流
+
+### 8.1 请求生命周期
+
+```
+用户操作（点击查询/新建/保存）
+    │
+    ▼
+loading.value = true          ← 显示加载态
+    │
+    ▼
+await apiFunction(payload)    ← axios 自动注入 JWT Header
+    │
+    ├─ 200: data → 更新响应式状态
+    │          ElMessage.success("操作成功")
+    │
+    ├─ 4xx: err → ElMessage.error(apiErrorMessage(e))
+    │             401 → 自动登出
+    │             403 → 提示无权限
+    │
+    └─ 5xx / Network Error → ElMessage.error("服务器错误")
+    │
+    ▼
+loading.value = false         ← 恢复交互
+```
+
+### 8.2 状态分类
+
+| 状态类型 | 存储位置 | 示例 |
+|---------|---------|------|
+| 页面级临时状态 | 组件内 `ref()` / `reactive()` | 表格数据、表单数据、loading |
+| 跨页面持久状态 | Pinia `auth.js` | token、用户名、角色 |
+| UI 状态 | 组件内 | dialogVisible、activeTab |
+| URL 状态 | `route.query` / `route.params` | 分页页码、详情页 ID |
+
+---
+
+## 9. 开发规范
+
+### 9.1 新增页面检查清单
+
+```
+□ 文件命名：PascalCaseView.vue
+□ 使用 <script setup> + Composition API
+□ 所有 API 调用有 try/catch + apiErrorMessage
+□ 列表有 v-loading / 提交按钮有 :loading
+□ 路由 meta 包含 roles 鉴权
+□ 表格表头使用 #F2F5FC 背景（继承 theme.css）
+□ 状态标签使用 .tag-active / .tag-revoked 等语义类
+□ CTA 按钮使用 .btn-cta 带阴影
+□ 色值使用 CSS 变量，不硬编码
+□ 弹框使用 <el-dialog>（自动继承 8px 圆角）
+```
+
+### 9.2 禁止事项
+
+| 禁止 | 原因 |
+|------|------|
+| 硬编码色值 (`#EAEFFA`) | 应使用 CSS 变量，便于换肤 |
+| 直接操作 DOM (`document.querySelector`) | 使用 Vue 响应式 + ref |
+| 在 `setup` 外定义响应式数据 | 非 `.vue` 文件需使用 `defineStore` |
+| `v-if` + `v-for` 同时使用 | Vue 性能警告 |
+| 忽略 try/catch | 未捕获异常导致白屏 |
+| 提交 `console.log` | 使用 `ElMessage` 或移除 |
+
+### 9.3 Git 提交规范
+
+```
+feat(web): 新增许可证管理页面
+fix(web): 修复合同列表分页重置bug
+refactor(web): 抽取 StatsCard 为独立组件
+style(web): 统一表格表头样式
+docs: 更新前端框架设计文档
+```
+
+---
+
+## 10. 构建与部署
+
+### 10.1 开发环境
+
+```bash
+cd web/delivery-platform-ui
+npm install
+npm run dev        # → http://localhost:5173
+                   # /api → proxy → http://127.0.0.1:8080
+```
+
+### 10.2 生产构建
+
+```bash
+# 指定后端地址
+VITE_API_BASE=https://api.craftlabs.cn npm run build
+
+# 产物：dist/
+# 部署：Nginx 静态托管 + 反代 /api 到后端
+```
+
+### 10.3 CI/CD
+
+```yaml
+# .github/workflows/ci-platform.yml (前端部分)
+- name: Build Frontend
+  run: |
+    cd web/delivery-platform-ui
+    npm ci
+    npm run build
+```
+
+### 10.4 Nginx 配置模板
+
+```nginx
+server {
+    listen 80;
+    server_name platform.craftlabs.cn;
+    root /var/www/delivery-platform-ui/dist;
+    index index.html;
+
+    location /api/ {
+        proxy_pass http://127.0.0.1:8080;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+
+    location / {
+        try_files $uri $uri/ /index.html;  # SPA fallback
+    }
+}
+```
+
+---
+
+## 附录 A：文件职责速查
+
+| 文件 | 职责 | 谁需要修改 |
+|------|------|-----------|
+| `theme.css` | 全局色彩/圆角/阴影 Token | 设计师/UED |
+| `MainLayout.vue` | 页面壳：Header/Sidebar/Breadcrumb | 架构师 |
+| `router/index.js` | 路由表 + 鉴权守卫 | 全栈/前端 |
+| `stores/auth.js` | JWT 认证状态 | 全栈/前端 |
+| `api/platform.js` | 后端 API 封装 | 前端（新增接口时） |
+| `utils/*.js` | 通用工具函数 | 前端 |
+| `views/*View.vue` | 业务页面 | 前端 |
+
+## 附录 B：快速上手
+
+**创建一个新页面（以「审计日志」为例）**：
+
+1. 创建 `src/views/AuditLogView.vue`，使用标准列表页模板
+2. 在 `api/platform.js` 添加 `listAuditEvents()` 函数
+3. 在 `router/index.js` 添加路由，设置 `meta.roles`
+4. 在 `MainLayout.vue` 的 `menuItems` 数组添加菜单项
+5. `npm run dev` 验证
+
+---
+
+*修订记录：2026-05-19 初版，基于设计体系 v1.0*