workspace/code/g3soft-libs/packages/framework/README.md

@g3soft/framework

G3Soft 前端框架。目标：基础架子一处维护，留好插槽和接口，业务项目引用方便，既不绑死又灵活。

设计原则

framework 提供「骨架 + 契约」，业务负责「填充」；依赖单向 host → framework，framework 永不 import 业务代码。

• 三层契约：配置契约（G3FrameworkOptions）/ 数据契约（NavItem、G3RouteMeta、UserInfo）/ UI 契约（slots + emits）。
• 一切外部信息靠注入：菜单、用户、token、跳转都由宿主提供，framework 内部零业务依赖。
• 默认能跑：零配置即可启动（默认 sidebar-nav + 浅色），配置与插槽均为可选增强。

归属边界

层	内容	说明
core	布局（7 种模式）、偏好模型、契约类型	后端无关，只依赖 vue(peer) + @g3soft/ui
presets/*	传输、ApiResponse 解包、/data/* client、默认菜单源	后续接入，可选，import 才生效
项目	业务接口、业务页面	——

铁律：core 里绝不出现具体后端名（如 s_menu、/data/loaddata、ApiResponse）；一旦出现，它就该在 presets。

当前进度

• core 类型契约（数据 / 配置 / UI 三类）
• 偏好层：defaultPreferences / usePreferences（reactive 单例，无需 pinia）/ 持久化 / applyThemeVars
• createG3Framework（app.use() 一次初始化）
• 布局子组件：Logo / 递归 Menu（垂直+水平）/ Sidebar（单列+双列，含折叠按钮、拖拽调宽、悬浮展开）/ Header / Breadcrumb / Tabbar
• G3Layout 编排 7 种模式（模式配置表驱动）
• 偏好抽屉面板
• 接线层 G3AdminLayout（接 router / 页签状态 / 用户菜单）
• 接口层 preset（/request + g3-backend + 默认菜单源）

布局结构与交互对齐 vben-admin 的 layout-ui，样式改写为 --g3-* 变量 + g3- 前缀（不引入 Tailwind，业务项目零额外配置）。

使用

// main.ts —— 初始化（可选）
import { createG3Framework } from '@g3soft/framework'
app.use(
  createG3Framework({
    preferences: { app: { layout: 'sidebar-nav' }, theme: { colorPrimary: '#2563eb' } },
    storageKey: 'g3-preferences',
  }),
)

<script setup lang="ts">
import { G3Layout, type NavItem } from '@g3soft/framework'

const menus: NavItem[] = [
  { key: 'home', title: '工作台', path: '/' },
  { key: 'sys', title: '系统管理', children: [{ key: 'user', title: '用户', path: '/sys/user' }] },
]
</script>

<template>
  <G3Layout layout="sidebar-nav" :menus="menus" :active-key="$route.path" @navigate="onNavigate">
    <template #header-right><!-- 用户菜单 --></template>
    <template #page><RouterView /></template>
  </G3Layout>
</template>

菜单数据由宿主注入（:menus 直接给数组，或 :menu-source 给函数），framework 不关心来源。

偏好与主题

• usePreferences()：读偏好（只读响应式）、update(patch) / setLayout() / toggleSidebar()。
• 偏好状态是模块级 reactive 单例，不依赖 pinia；持久化用 localStorage（SSR 安全）。
• 主题唯一输出仍是 @g3soft/ui 的 ConfigProvider → derivePalette → --g3-*；radius / fontSize / 布局尺寸写入 CSS 变量。

归属边界

层	内容	说明
core	布局（7 种模式）、偏好、契约类型	后端无关，只依赖 vue(peer) + @g3soft/ui
presets/*	传输、ApiResponse 解包、/data/* client、默认菜单源	后续接入，可选，import 才生效
项目	业务接口、业务页面	——

铁律：core 里绝不出现具体后端名（如 s_menu、/data/loaddata、ApiResponse）；一旦出现，它就该在 presets。