ishenwei/nexus
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Sync: add automation governance notes

Browse Source
This commit is contained in:
weishen
2026-04-25 13:11:48 +08:00
parent e812681628
commit 9fccf27053
14 changed files with 840 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files

322
Project/fonrey/UI_SYSTEM/UI_SYSTEM.md
View File

@@ -1,6 +1,6 @@
# Fonrey UI System 设计规范
**版本**：v1.1
**版本**：v1.2
**最后更新**：2026-04-25
**维护者**：UI/UX 架构组
**适用技术栈**：Tailwind CSS + HTMX + Alpine.js + Django 模板
@@ -966,50 +966,288 @@ Flatpickr 自定义样式覆盖见附录 10.3。
### 5.1 整体框架
```
┌──────────────────────────────────────────────────────────────┐
│ 顶部导航 Topbar（56px） │
│ [Logo 150px] [全局搜索 360px] [消息] [帮助] [头像▾] │
├────────────┬─────────────────────────────────────────────────┤
│ │ 面包屑 [次要操作] [主操作] │
│ 侧边导航 │ ┌─────────────────────────────────────────────┐ │
│ Sidebar │ │ 页面标题 H1 │ │
│ 240px │ ├─────────────────────────────────────────────┤ │
│ 可折叠 │ │ 筛选 / 工具栏（Sticky） │ │
│ → 64px │ ├─────────────────────────────────────────────┤ │
│ │ │ │ │
│ │ │ 内容主体 │ │
│ │ │ │ │
│ │ └─────────────────────────────────────────────┘ │
└────────────┴─────────────────────────────────────────────────┘
┌──────────────────────────────────────────────────────────────────────┐
│ Topbar（56px，sticky top-0 z-20） │
│ [Logo 150px] [主导航: 主页 房源 客源 营销 交易 数据 人事 系统] │
│ [消息🔔] [帮助?] [头像▾] │
├─────────────────┬────────────────────────────────────────────────────┤
│ Sidebar │ 内容区（Content Area） │
│ 展开 240px │ 面包屑 > 房源管理 > 二手 & 租赁 [次操作] [主操作] │
│ 折叠 64px │ ───────────────────────────────────────────────── │
│ │ 页面标题 H1 │
│ [当前主分类 │ ───────────────────────────────────────────────── │
│ 的子菜单] │ 筛选 / 工具栏（Sticky，top-14） │
│ │ ───────────────────────────────────────────────── │
│ ← 折叠按钮 │ 内容主体（表格 / 卡片 / 表单） │
│ │ │
│ │ 分页栏 │
└─────────────────┴────────────────────────────────────────────────────┘
```
- **Topbar 高度**：56px，`h-14`，`bg-white border-b border-neutral-200 sticky top-0 z-20`
- **Sidebar 宽度**：展开 240px (`w-60`) / 折叠 64px (`w-16`)；Alpine.js 控制，状态持久化到 `localStorage`
- **内容区左内边距**：展开态 `ml-60`，折叠态 `ml-16`，配合 `transition-all`
- **主内容区内边距**：`px-6 py-4`
**尺寸约定**
### 5.2 侧边栏（Sidebar）
| 区域 | 规格 |
|---|---|
| Topbar 高度 | 56px（`h-14`）；`sticky top-0 z-20` |
| Sidebar 展开宽度 | 240px（`w-60`）；`fixed left-0 top-14 h-[calc(100vh-56px)] z-20` |
| Sidebar 折叠宽度 | 64px（`w-16`） |
| 内容区偏移 | 展开态 `ml-60`，折叠态 `ml-16`；`transition-[margin] duration-200` |
| 内容区内边距 | `px-6 py-4` |
| 工具栏 Sticky 偏移 | `sticky top-14 z-30`（Topbar 下方紧贴） |
---
### 5.2 顶部导航栏（Topbar）
#### 5.2.1 结构规范
Topbar 分三区：左区（Logo）、中区（主导航）、右区（工具区）。
```
[🏢 Fonrey] 展开态 折叠态
────────────── ──────────────
仪表盘 Dashboard 🏠
房源管理 ▾ Property 🏘️
全部房源
二手 & 租赁
商铺 / 写字楼
客源管理 ▾ Client 👤
楼盘管理 Complex 🏢
组织人事 ▾ Org 👥
权限管理 Permission 🔒
系统设置 ▾ Settings ⚙️
┌─────────────────────────────────────────────────────────────────────┐
│ [🏢 Fonrey ▾] 主页 房源 客源 营销 交易 数据 人事 系统 │
│ [🔍] [🔔2] [?] [WS 王顺▾] │
└─────────────────────────────────────────────────────────────────────┘
```
- 一级菜单：图标（20px） + 文字 + 右侧箭头（有子菜单时）
- 二级菜单：文字缩进 32px，激活态为 `bg-primary-50 text-primary-700 font-medium` + 左侧 2px 主色竖条
- 折叠态：只显示图标，Hover 时 Tooltip 显示名称
| 区域 | 内容 | 样式 |
|---|---|---|
| 左区（150px） | Logo 图 + 产品名"Fonrey" | `flex items-center gap-2 px-4 text-base font-semibold text-neutral-900` |
| 中区（flex-1） | 主分类导航 Tab | 见 5.2.2 |
| 右区（auto） | 全局搜索图标 / 消息 / 帮助 / 头像菜单 | `flex items-center gap-1 px-4` |
### 5.3 列表页模板
#### 5.2.2 主导航 Tab
主分类（8项）：**主页 / 房源 / 客源 / 营销 / 交易 / 数据 / 人事 / 系统**
- 每项：`px-3 py-1 text-sm font-medium rounded-md`
- 默认态：`text-neutral-600 hover:bg-neutral-100 hover:text-neutral-800`
- 激活态：`bg-primary-50 text-primary-700`
- 点击切换主分类 → Sidebar 同步切换为该分类的子菜单
#### 5.2.3 右区工具
| 元素 | 图标 | 说明 |
|---|---|---|
| 全局搜索 | `MagnifyingGlassIcon` 20px | 点击展开全局搜索 Popover（`max-w-lg`） |
| 消息通知 | `BellIcon` 20px + 红点 Badge | 未读数 ≤ 99，超出显示"99+"；点击打开通知 Drawer |
| 帮助 | `QuestionMarkCircleIcon` 20px | 链接到帮助中心或触发 Tour |
| 头像菜单 | 头像（`w-8 h-8 rounded-full`）+ 姓名缩写 | 下拉菜单：个人设置 / 切换角色 / 退出 |
#### 5.2.4 Topbar HTML 片段
```html
<header class="fixed top-0 left-0 right-0 h-14 z-20
bg-white border-b border-neutral-200
flex items-center justify-between">
<!-- 左区：Logo -->
<div class="flex items-center gap-2 px-4 w-60 shrink-0">
<img src="/static/img/logo.svg" class="w-7 h-7" alt="Fonrey">
<span class="text-base font-semibold text-neutral-900">Fonrey</span>
</div>
<!-- 中区：主导航 -->
<nav class="flex items-center gap-0.5 flex-1 px-2" aria-label="主导航">
{% for item in nav_items %}
<a href="{{ item.url }}"
class="px-3 py-1.5 text-sm font-medium rounded-md
{% if item.active %}bg-primary-50 text-primary-700
{% else %}text-neutral-600 hover:bg-neutral-100 hover:text-neutral-800{% endif %}">
{{ item.label }}
</a>
{% endfor %}
</nav>
<!-- 右区：工具 -->
<div class="flex items-center gap-1 px-4 shrink-0">
<!-- 全局搜索 -->
<button class="p-1.5 text-neutral-500 hover:bg-neutral-100 hover:text-neutral-700 rounded-md"
aria-label="搜索">
<svg class="w-5 h-5"><!-- MagnifyingGlassIcon --></svg>
</button>
<!-- 消息通知 -->
<button class="relative p-1.5 text-neutral-500 hover:bg-neutral-100 rounded-md"
aria-label="消息通知">
<svg class="w-5 h-5"><!-- BellIcon --></svg>
<span class="absolute top-1 right-1 min-w-[16px] h-4 px-1 text-[10px] font-bold
bg-danger-600 text-white rounded-full flex items-center justify-center
leading-none">2</span>
</button>
<!-- 帮助 -->
<button class="p-1.5 text-neutral-500 hover:bg-neutral-100 rounded-md" aria-label="帮助">
<svg class="w-5 h-5"><!-- QuestionMarkCircleIcon --></svg>
</button>
<!-- 头像菜单 -->
<div x-data="{ open: false }" @click.away="open=false" class="relative ml-1">
<button @click="open=!open"
class="flex items-center gap-2 p-1 rounded-md hover:bg-neutral-100">
<span class="w-8 h-8 rounded-full bg-primary-100 text-primary-700
flex items-center justify-center text-sm font-semibold">
王
</span>
<span class="text-sm text-neutral-700 font-medium">王顺</span>
<svg class="w-4 h-4 text-neutral-400"><!-- ChevronDownIcon --></svg>
</button>
<div x-show="open" x-transition
class="absolute right-0 mt-1 w-44 bg-white rounded-md shadow-md
border border-neutral-200 py-1 z-40">
<a href="/profile/" class="flex items-center gap-2 px-3 py-2 text-sm text-neutral-700 hover:bg-neutral-50">
<svg class="w-4 h-4 text-neutral-400"><!-- UserIcon --></svg> 个人设置
</a>
<div class="my-1 border-t border-neutral-100"></div>
<a href="/logout/" class="flex items-center gap-2 px-3 py-2 text-sm text-danger-600 hover:bg-danger-50">
<svg class="w-4 h-4"><!-- ArrowRightOnRectangleIcon --></svg> 退出登录
</a>
</div>
</div>
</div>
</header>
```
---
### 5.3 侧边栏（Sidebar）
#### 5.3.1 结构与折叠规范
```
展开态（240px） 折叠态（64px）
┌─────────────────────────┐ ┌──────┐
│ ▾ 房源管理 │ │ 🏘️ │ ← 一级图标，Hover Tooltip
│ 全部房源 ● │ │──────│
│ 二手 & 租赁 │ │ 👤 │
│ 商铺 / 写字楼 │ │ 🏢 │
│─────────────────────────│ │ ⚙️ │
│ 客源管理 │ └──────┘
│ 私客管理 ● │
│ 公客池 │
│─────────────────────────│
│ [← 折叠] │ ← 折叠按钮（固定在 Sidebar 底部）
└─────────────────────────┘
```
- **Sidebar 定位**：`fixed left-0 top-14 h-[calc(100vh-56px)] z-20 overflow-y-auto`
- **展开宽度**：`w-60`（240px）；折叠宽度：`w-16`（64px）
- **Alpine.js 状态**：`x-data="{ collapsed: $persist(false).as('fonrey:sidebar:collapsed') }"`（使用 `@alpinejs/persist` 持久化）
- **内容区联动**：`<main :class="collapsed ? 'ml-16' : 'ml-60'" class="transition-[margin] duration-200">`
#### 5.3.2 菜单层级
Sidebar 展示**当前主分类的子菜单**，分为一级菜单和二级菜单（可选）。
| 层级 | 样式 | 激活态 |
|---|---|---|
| 一级菜单（有子项） | `flex items-center gap-3 px-3 py-2 text-sm font-medium text-neutral-700 rounded-md hover:bg-neutral-100 cursor-pointer` | `text-neutral-900 bg-neutral-100` |
| 一级菜单（无子项，直链） | 同上 | `bg-primary-50 text-primary-700 font-semibold border-l-2 border-primary-600 rounded-l-none` |
| 二级菜单 | `ml-8 flex items-center gap-2 px-3 py-1.5 text-sm text-neutral-600 rounded-md hover:bg-neutral-100` | `bg-primary-50 text-primary-700 font-medium border-l-2 border-primary-600 rounded-l-none` |
| 分组标题（可选） | `px-3 pt-4 pb-1 text-xs font-semibold text-neutral-400 uppercase tracking-wider` | — |
#### 5.3.3 折叠态行为
- 仅显示一级菜单图标（`w-5 h-5`），居中 `justify-center`
- 文字、箭头、二级菜单全部隐藏（`x-show="!collapsed"`）
- Hover 图标时，右侧弹出 Tooltip：菜单名称（`absolute left-16 ml-1 px-2 py-1 text-xs bg-neutral-900 text-white rounded whitespace-nowrap z-40`）
- 折叠按钮变为展开图标（`ChevronRightIcon`），固定在底部
#### 5.3.4 Sidebar HTML 片段
```html
<aside x-data="{ collapsed: $persist(false).as('fonrey:sidebar:collapsed'),
openGroup: $persist('property').as('fonrey:sidebar:openGroup') }"
:class="collapsed ? 'w-16' : 'w-60'"
class="fixed left-0 top-14 h-[calc(100vh-56px)] z-20
bg-white border-r border-neutral-200
flex flex-col overflow-y-auto overflow-x-hidden
transition-[width] duration-200">
<!-- 菜单主体 -->
<nav class="flex-1 py-3 space-y-0.5 px-2">
<!-- 一级菜单（有子菜单，可折叠） -->
<div>
<button @click="openGroup = (openGroup === 'property' ? '' : 'property')"
class="w-full flex items-center gap-3 px-3 py-2 text-sm font-medium
text-neutral-700 rounded-md hover:bg-neutral-100
relative group">
<svg class="w-5 h-5 text-neutral-500 shrink-0"><!-- HomeModernIcon --></svg>
<span x-show="!collapsed" class="flex-1 text-left">房源管理</span>
<svg x-show="!collapsed"
:class="openGroup === 'property' ? 'rotate-90' : ''"
class="w-4 h-4 text-neutral-400 transition-transform shrink-0"><!-- ChevronRightIcon --></svg>
<!-- 折叠态 Tooltip -->
<span x-show="collapsed"
class="pointer-events-none absolute left-14 ml-1 px-2 py-1 text-xs
bg-neutral-900 text-white rounded whitespace-nowrap z-40
opacity-0 group-hover:opacity-100 transition-opacity">
房源管理
</span>
</button>
<!-- 二级菜单 -->
<div x-show="!collapsed && openGroup === 'property'" x-collapse class="mt-0.5 space-y-0.5">
<a href="/property/all/"
class="ml-8 flex items-center gap-2 px-3 py-1.5 text-sm text-neutral-600
rounded-r-md hover:bg-neutral-100
{% if active_sub == 'all' %}bg-primary-50 text-primary-700 font-medium
border-l-2 border-primary-600{% endif %}">
全部房源
</a>
<a href="/property/sale/"
class="ml-8 flex items-center gap-2 px-3 py-1.5 text-sm text-neutral-600
rounded-r-md hover:bg-neutral-100">
二手 &amp; 租赁
</a>
<a href="/property/commercial/"
class="ml-8 flex items-center gap-2 px-3 py-1.5 text-sm text-neutral-600
rounded-r-md hover:bg-neutral-100">
商铺 / 写字楼
</a>
</div>
</div>
<!-- 一级菜单（直链，无子菜单） -->
<a href="/complex/"
class="flex items-center gap-3 px-3 py-2 text-sm font-medium
text-neutral-700 rounded-md hover:bg-neutral-100
relative group
{% if active_nav == 'complex' %}bg-primary-50 text-primary-700 border-l-2 border-primary-600 rounded-l-none{% endif %}">
<svg class="w-5 h-5 text-neutral-500 shrink-0"><!-- BuildingOffice2Icon --></svg>
<span x-show="!collapsed">楼盘管理</span>
<span x-show="collapsed"
class="pointer-events-none absolute left-14 ml-1 px-2 py-1 text-xs
bg-neutral-900 text-white rounded whitespace-nowrap z-40
opacity-0 group-hover:opacity-100 transition-opacity">
楼盘管理
</span>
</a>
</nav>
<!-- 折叠按钮 -->
<div class="border-t border-neutral-200 p-2">
<button @click="collapsed = !collapsed"
class="w-full flex items-center justify-center gap-2 px-3 py-2 text-sm
text-neutral-500 hover:bg-neutral-100 rounded-md">
<svg :class="collapsed ? 'rotate-180' : ''"
class="w-4 h-4 transition-transform shrink-0"><!-- ChevronLeftIcon --></svg>
<span x-show="!collapsed" class="text-xs">收起</span>
</button>
</div>
</aside>
<!-- 内容区偏移联动（写在 body 或 layout wrapper 层） -->
<main :class="collapsed ? 'ml-16' : 'ml-60'"
class="mt-14 transition-[margin] duration-200 min-h-[calc(100vh-56px)] bg-neutral-50">
{% block content %}{% endblock %}
</main>
```
---
### 5.4 列表页模板
适用：房源列表、客源列表、楼盘列表、权限人员列表、组织人员列表等。
@@ -1029,7 +1267,7 @@ Flatpickr 自定义样式覆盖见附录 10.3。
分页栏（共 3629 条 · 1 2 3 … · 20/页 · 跳至）
```
### 5.4 详情页模板
### 5.5 详情页模板
适用：房源详情、客源详情、楼盘详情、员工详情。
@@ -1056,7 +1294,7 @@ Flatpickr 自定义样式覆盖见附录 10.3。
- 右侧栏（`w-80`）用于维护度、相关员工等辅助信息；主区 `flex-1`
- **编辑入口 = 详情字段旁的"编辑"链接 → 右侧 Drawer 滑入**（遵循"保留上下文"原则）
### 5.5 设置页模板
### 5.6 设置页模板
适用：系统设置、权限管理、个人设置。
@@ -1081,15 +1319,15 @@ Flatpickr 自定义样式覆盖见附录 10.3。
- 左侧导航支持二级折叠，激活项左侧 2px 主色竖条
- 底部保存按钮 Sticky（编辑态）
### 5.6 登录/认证页
### 5.7 登录/认证页
独立布局，不使用 Sidebar。居中卡片 `max-w-md`，品牌色背景装饰（左侧 logo + slogan，右侧表单），参考 Salesforce Lightning 登录页密度。
### 5.7 空状态页（Empty Page）
### 5.8 空状态页（Empty Page）
见 6.3。
### 5.8 错误页（403/404/500）
### 5.9 错误页（403/404/500）
三视图共享同一模板，仅图案与文案不同。`max-w-md mx-auto text-center` + SVG 插图 + 主按钮"返回首页"+ 次按钮"联系管理员"。