# Precision Atelier 设计系统改造记录

## 改动日期
- 2026-04-02：视觉层改造（配色、字体、组件样式）
- 2026-04-03：全局布局改造（AppShell 三栏布局 + 去重）

## 背景
基于 `方案设定/stitch/` 中的 17 份前端设计稿（solidjoin_3d_1~15 + solidjoin_precision + solidjoin_3d_inventory_2），将前端视觉风格从 "Apple HIG" 切换为设计稿指定的 "Precision Atelier" 风格。

## 核心变更

### 1. 配色体系（colors.ts）

| 维度 | 旧值 | 新值 | 用途 |
|------|------|------|------|
| 品牌色 | `#008D74`（Teal） | `#546067`（Graphite） | 导航高亮、标题、CTA |
| 次要色 | `#47C4AF` | `#4b626e`（Fog Blue） | 链接、辅助操作 |
| 成功色 | `#34C759` | `#286c34`（Sage Green） | 成功状态、验证 |
| 错误色 | `#FF3B30` | `#9f403d` | 错误提示 |
| 主背景 | `#FFFFFF` | `#f9f9fb`（surface） | 页面底色 |
| 侧边栏 | `#F5F5F7` | `#f2f4f6`（surface-container-low） | 侧边栏 |
| 卡片/浮动面板 | `#FFFFFF` | `#ffffff`（surface-container-lowest） | 卡片 |
| 二级工作区 | — | `#ebeef2`（surface-container） | 数据区域 |
| 深色背景 | `#000000` / `#1C1C1E` | `#0c0e10` / `#1a1c1e` | 深色主题 |

新增令牌：
- `glassmorphismTokens` — 玻璃面板颜色（70% 白 + blur 20px）
- `ambientShadowTokens` — 环境阴影（带 on-surface 色调 `rgba(45, 51, 56, 0.06)`）
- `toastColors` — Toast 专用颜色

### 2. 字体系统（typography.ts）

双字体策略：
- **展示字体**：Manrope — 用于品牌标题、大标题
- **功能字体**：Inter — 用于数据、标签、表单、技术规格

命名体系对照：
| 旧名 | 新名 | 用途 |
|------|------|------|
| largeTitle | displayLg (3.5rem) | 品牌大标题 |
| title1 | displayMd (2.5rem) | 展示标题 |
| title2 | headlineLg (1.75rem) | 页面标题 |
| title3 | headlineMd (1.5rem) | 区块标题 |
| headline | headlineSm (1.25rem) | 小标题 |
| body | bodyMd (0.875rem) | 正文 |
| callout | bodyLg (1rem) | 大正文 |
| subhead | bodySm (0.75rem) | 小正文 |
| footnote | bodySm (0.75rem) | 注释 |
| caption1 | bodySm (0.75rem) | 小标签 |
| caption2 | labelSm (0.6875rem) | 微标签 |

兼容处理：`legacyTextStyleMap` 映射旧名到新名，`CompatibleTextStyle` 类型同时接受新旧名。

### 3. 全局样式（globals.css）

- **@theme 块**：颜色变量全部替换为 Precision Atelier 配色
- **字间距**：展示标题统一 `letter-spacing: -0.02em`，技术标签 `0.05em`
- **圆角**：改为紧凑风格（0.375rem ~ 1rem）
- **过渡**：200ms ease-out（"Snappy but Silky"）
- **阴影**：环境阴影 `0px 4px 32px rgba(45, 51, 56, 0.06)`
- **Ghost Border**：`rgba(172, 179, 184, 0.3)` 用于数据网格分隔
- **深色主题**：完整的深色变量覆盖
- **Glassmorphism**：70% 白/深 + 20px blur
- **滑块**：品牌色从 `#008D74` 改为 `#546067`，深色模式对应

### 4. UI 组件改动

**Button.tsx**
- filled 变体：纯色背景改为 145° 渐变 `linear-gradient(145deg, var(--color-blue), var(--color-teal))`

**Typography.tsx**
- `variant` prop 类型改为 `CompatibleTextStyle`，兼容旧名（caption1/body/headline 等）
- `fontType` 新增 `display` 选项，支持 Manrope 展示字体

### 5. 硬编码颜色替换

~20 个业务文件中的 82 处 `#008D74` 硬编码替换为 CSS 变量引用。

### 6. 兼容性处理

- `appleColorTokens`、`appleSemanticColors`、`appleToastColors`：旧名兼容导出
- `appleTypographyTokens`：旧名兼容导出
- `appleAnimationTokens`：保持原名不变
- `precisionAtelierSpacingTokens`：新名，旧函数签名不变

## 设计原则

1. **No-Line Rule**：不用 1px 边框，通过 surface 层级的 hex 差异产生视觉分离
2. **Glassmorphism**：浮动面板用 70% 白 + 20px blur
3. **环境阴影**：仅用于浮动元素，颜色带 on-surface 色调
4. **Snappy but Silky**：200ms ease-out 过渡
5. **Ghost Border**：数据网格用 0.5px `outline-variant` @ 30% 透明度
6. **CTA 渐变**：primary → primary-dim，145° 角，"machined metal" 质感

## 改动文件清单

| 文件 | 改动类型 |
|------|----------|
| `src/lib/design-tokens/colors.ts` | 全部重写 |
| `src/lib/design-tokens/typography.ts` | 全部重写 |
| `src/lib/design-tokens/spacing.ts` | 重命名+圆角调整 |
| `src/lib/design-tokens/index.ts` | 注释更新 |
| `src/app/globals.css` | 颜色/字体/阴影全部替换 |
| `src/components/ui/Button.tsx` | CTA 渐变效果 |
| `src/components/ui/Typography.tsx` | 兼容旧名 variant |
| ~20 个业务文件 | 硬编码颜色替换 |

---

## 第二阶段：全局布局改造（2026-04-03）

### 7. AppShell 三栏布局

新增全局布局框架，所有常规页面统一使用三栏结构：

```
┌─────────────────────────────────────────────────┐
│  AppTopNav（h-14，Glassmorphism 毛玻璃顶栏）      │
│  Logo + 搜索 + 通知 + 主题切换 + 用户菜单          │
├──────────┬──────────────────────────────────────┤
│ AppSideNav│  主内容区（ml-56 mt-14）              │
│ w-56      │                                      │
│           │  PlatformSplitLayout 等页面组件        │
│ 导航链接   │                                      │
│ 新建配置   │                                      │
│ 技术支持   │                                      │
│ 归档      │                                      │
└──────────┴──────────────────────────────────────┘
```

**新增文件：**
- `src/components/layout/AppTopNav.tsx` — 固定顶栏（Logo + 搜索 + 工具按钮）
- `src/components/layout/AppSideNav.tsx` — 固定左侧导航（5 个导航项 + 底部操作区）
- `src/components/layout/AppShell.tsx` — 全局布局容器，组合 TopNav + SideNav + main

**排除页面：** `/login`、`/first-login`、`/debug-theme`、`/ui-preview` 不使用 AppShell。

**AppSideNav 导航项：**
| 路由 | 标签 | 图标 |
|------|------|------|
| `/` | 首页概览 | Home |
| `/asset-center` | 资产中心 | Boxes |
| `/assisted-assembly` | 辅助装配 | Layers |
| `/draft-groups` | 草稿组 | PackageOpen |
| `/warehouse` | 仓库管理 | Warehouse |

### 8. 功能去重

引入 AppShell 后，各页面中与全局导航重复的元素已清理：

**去重 1：顶栏导航 tab 移除**
- AppTopNav 原本有 5 个导航 tab（首页/资产中心/辅助装配/草稿组/仓库），与 AppSideNav 完全重复
- 已移除顶栏中的导航 tab，顶栏只保留：Logo、搜索框、通知铃铛、主题切换、用户菜单
- 导航职责统一由左侧边栏承担

**去重 2：页面内 headerTools（ThemeToggle + UserMenu）移除**
以下 7 个文件移除了 `headerTools={<PlatformHeaderTools user={user} />}` 传参：
- `src/app/asset-center/AssetCenterClient.tsx`
- `src/app/assisted-assembly/page.tsx`（服务端）+ `AssistedAssemblyClient.tsx`（客户端）
- `src/app/draft-groups/DraftGroupsClient.tsx`
- `src/app/draft-groups/[id]/DraftGroupDetailClient.tsx`
- `src/app/intake/IntakeClient.tsx`
- `src/app/warehouse/WarehouseClient.tsx`
- `src/app/HomeClient.workspace.tsx`

**去重 3：eyebrow 副标题移除**
各页面中 `eyebrow` prop（如"主链起点"、"系列模板驱动"、"中台承接页"等）已全部移除。
侧边栏已有清晰的页面标识，无需重复。

### 9. Platform 组件适配

**PlatformPageFrame.tsx**
- 移除：radial-gradient 背景、rounded-[28px] 卡片包装、liquid-glass-enhanced 头部
- 现在：简洁的内联布局，Manrope 标题 + 内联 eyebrow badge + PlatformFlowNav

**PlatformSplitLayout.tsx**
- 移除：独立的 sticky 头部（含 Card、返回按钮、eyebrow）
- 适配：`h-[calc(100vh-56px)]` 填满 AppShell 主内容区
- 右侧面板：w-80（320px），surface-container-lowest 背景
- `eyebrow` 和 `headerTools` 保留为 `@deprecated` props（解构后静默忽略），确保旧代码不报错

## 最终布局职责划分

| 区域 | 组件 | 职责 |
|------|------|------|
| 顶栏 | AppTopNav | Logo、搜索、通知、主题切换、用户菜单 |
| 侧边栏 | AppSideNav | 5 个导航链接、新建配置按钮、技术支持、归档 |
| 主内容区 | 各页面组件 | 只负责业务内容，不再自带导航/头部工具 |

## 改动文件清单（完整）

| 文件 | 改动类型 |
|------|----------|
| `src/lib/design-tokens/colors.ts` | 全部重写 |
| `src/lib/design-tokens/typography.ts` | 全部重写 |
| `src/lib/design-tokens/spacing.ts` | 重命名+圆角调整 |
| `src/app/globals.css` | 颜色/字体/阴影全部替换 |
| `src/components/ui/Button.tsx` | CTA 渐变效果 |
| `src/components/ui/Typography.tsx` | 兼容旧名 variant |
| `src/components/layout/AppTopNav.tsx` | **新增**：全局顶栏 |
| `src/components/layout/AppSideNav.tsx` | **新增**：全局侧边导航 |
| `src/components/layout/AppShell.tsx` | **新增**：全局布局容器 |
| `src/app/layout.tsx` | 引入 AppShell 包裹 |
| `src/components/platform/PlatformPageFrame.tsx` | 简化为内联布局 |
| `src/components/platform/PlatformSplitLayout.tsx` | 适配 AppShell + deprecated props |
| `src/app/asset-center/AssetCenterClient.tsx` | 移除 headerTools/eyebrow |
| `src/app/assisted-assembly/page.tsx` | 移除 headerTools 传参 |
| `src/app/assisted-assembly/AssistedAssemblyClient.tsx` | headerTools 改为可选 |
| `src/app/draft-groups/DraftGroupsClient.tsx` | 移除 headerTools/eyebrow |
| `src/app/draft-groups/[id]/DraftGroupDetailClient.tsx` | 移除 headerTools/eyebrow（2 处） |
| `src/app/intake/IntakeClient.tsx` | 移除 headerTools/eyebrow（2 处） |
| `src/app/warehouse/WarehouseClient.tsx` | 移除 headerTools/eyebrow |
| `src/app/HomeClient.workspace.tsx` | 移除 topTools 传参 |
| ~20 个业务文件 | 硬编码颜色替换 |

---

## 第三阶段：管理基础设施视觉升级 (2026-04-16)

### 10. 管理端专属视觉模式 (Management UI Patterns)

在重构 `/admin` 和 `/users` 页面时，引入了针对“高密度控制类页面”的增强视觉模式，以平衡“工业精密感”与“视觉通透度”。

**1. 沉浸式页头 (Immersive Page Header)**
- **视觉特征**：
  - 采用 `bg-white/60` + `backdrop-blur-2xl`。
  - 强化左侧 Icon 视觉，使用 `rounded-[2rem] bg-black` 黑色底座，并叠加状态徽章（如 `ShieldCheck`）。
  - **排版建议**：Manrope 3XL 标题 + 紧跟其后的 `text-apple-blue` 高亮关键词。
  - **副标题**：使用 `text-[10px] tracking-[0.4em] uppercase` 的精密说明文字。

**2. 精密控制条 (Precision Control Bar)**
- **定义**：将原本分散的“搜索框”与“筛选器”整合进一个逻辑整体。
- **视觉实现**：
  - 容器：`rounded-[2rem]` 极圆圆角，`border-white/80` 微光边框，`bg-white/40` 背景。
  - 搜索框：沉浸式设计，背景为 `bg-white/80`，聚焦时通过 `ring-apple-blue/5` 产生柔和晕染。
  - 筛选器：图标 (Lucide Icon) + Select 组件的紧凑组合，图标作为装饰前缀。

**3. 玻璃态卡片增强 (Enhanced Glass Cards)**
- **改动**：在 `rounded-[2rem]` 的基础上，引入了“装饰线”动效。
- **动效逻辑**：`group-hover:w-full` 的底部 1.5px 强调线，颜色与模块 Icon 色调一致。
- **背景文字装饰**：绝对定位的 `text-[80px]` 背景大字（如模块 path），设置 `opacity-[0.03]` 极低透明度，增加“空间感”。

**4. 状态指标看板 (System Health Dashboard)**
- 应用场景：`/admin` 首页。
- 组成：Icon 容器 + 上下两行文本（上行为微缩标签，下行为状态值）。
- 配色：动态使用 `emerald-500` (正常), `blue-500` (活动), `amber-500` (注意)。

**5. 三栏工作区 (Three-Column Workspace)**
- 应用场景：`/asset-center/material-library`。
- 定义：左侧极简分类 (Navigation) + 中间响应式网格 (Grid) + 右侧实时定义面板 (Inspector)。
- 优势：极大降低页面跳转成本，实现“即时反馈”。

**6. 精密滑块交互 (Precision Sliders)**
- 视觉表现：细条轨道 + 圆形 Thumb + 右侧数值百分比徽章。
- 应用场景：物理参数调节 (Metallic/Roughness/Opacity)。
- 规范：取代原有的输入框，滑动步长固定为 0.01 (1%)。

**7. 悬浮坞系统 (Floating Dock System)**
- 应用场景：`/assisted-assembly`。
- 定义：左侧布局的交互式入口，采用 `bg-black/60` + `backdrop-blur-3xl`。
- 动效：点击后向右水平展开列表。
- 逻辑：通过视觉发光 (Glow) 和计数徽标反馈当前分类的选择状态。

**8. 环境 HUD (Ambient HUD)**
- 定义：底部的非侵入式信息条。
- 样式：极圆胶囊型，`backdrop-blur-xl`。
- 作用：提供当前操作环境的实时状态（如“捕捉已就绪”）。

### 11. 改动文件清单

| 文件 | 改动类型 | 备注 |
|------|----------|------|
| `src/app/admin/page.tsx` | 重构 | 系统总控制台首页视觉重载 |
| `src/app/users/page.tsx` | 重构 | 身份控制中心 (用户管理) 三栏重写 |
| `src/app/asset-center/material-library/MaterialLibraryClient.tsx` | 重构 | 材质库首页视觉重写 (草稿图 12.png) |
| `src/app/assisted-assembly/AssistedAssemblyClient.tsx` | 重构 | 拼装工作台沉浸式重写 & 引入 Floating Dock |
| `src/components/platform/PlatformSplitLayout.tsx` | 基础重构 | 统一加装 backHref 导航标准 |