# Phase 005 — ArkScope vendor + 样板页（风格基线）

| 项 | 值 |
|---|---|
| 目标 | vendor 2 个 ArkScope 组件；用 LoginView + AppSidebar 定视觉语言基线 |
| 前置 | Phase 004 通过（项目功能完整） |
| 产出 | `docs/ui-baseline.md` 定稿；后续批量迁移照它执行 |
| 参考 | `docs/03-施工蓝图.md` §7 |

---

## 0. 为什么必须先做样板页

naive-ui 渗透面是 **100 个文件 / 105 处**（不只 27 个视图，还含 `components/` `stores/` `composables/`）。

先定基线再批量，否则 100 个文件会被改两遍。

---

## 1. 功能任务 1 — vendor ArkScope

### 1.1 上游现状（已核实）

`github.com/triplepiers/ArkScope` — "对鹰角 UI 组件的拙劣复现"，Vue 3 + Vite，**无 LICENSE**，仓库 322MB。

`src/components/` 下的组件绝大多数**强绑定游戏美术素材**（干员立绘、Banner）。`public/assets/` 有 131 个路径全是游戏资源。

**只有 2 个组件可脱离素材复用**：

| 组件 | 依赖 | 判定 |
|---|---|---|
| `ScrambleTitle` | 纯 DOM + CSS，文字解码动画 | ✅ vendor |
| `IsometricWave` | CSS filter + 位移，类亚克力 hover | ✅ vendor |
| `Particle2D` / `Particle3D` | 3D 模型 + 遮罩图 | ❌ 太重 |
| `OperatorCarousel` / `ArknightsMedia` / `GameplayAlbum` / `NoticeCarousel` / `FullScreenNavigator` / `NewsList` / `EndfieldSidebar` / `Endfield/*` | 全部依赖游戏素材，脱离素材无意义 | ❌ 不 vendor |

其余组件的价值是**视觉手法**（斜切遮罩、噪点、扫描线、Reveal & Blink），后续页面按需自己实现，不搬代码。

### 1.2 做法

**不作为 npm 依赖，不 clone 整仓。**

1. 定位上游 commit（`main` 分支，记录 `pushed_at`），记下来
2. 只下载 `ScrambleTitle` 与 `IsometricWave` 两个组件目录
3. 放到 `packages/client/src/vendor/arkscore/<ComponentName>/`
4. **剥离**：`useAssetPreloader` / `particle3DModels` / `data/componentRegistry.js` / `router` / `views` / `showcases`（上游 demo 工程的东西）
5. **不搬**：`src/assets/**`、`public/**`、上游全局 `src/style.css`（只取组件 scoped 样式）
6. 保留原文件头注释 + 上游 commit hash

### 1.3 PROVENANCE.md（**必写**）

`packages/client/src/vendor/arkscore/PROVENANCE.md`：

```markdown
# ArkScope vendored components

- 上游：https://github.com/triplepiers/ArkScope
- commit：<hash>
- 拉取日期：<date>
- vendor 的组件：ScrambleTitle、IsometricWave
- 剥离内容：demo 工程（router/views/showcases/componentRegistry）、assets、public

## 许可证
上游仓库无 LICENSE 文件。

本 vendor 仅用于个人自用，不分发、不商用。
若要公开分发，必须先向上游作者取得授权或替换为自研实现。

## 未 vendor 的组件
其余组件强依赖鹰角游戏美术素材，脱离素材无实际价值，故未 vendor。
本项目仅参考其视觉手法（斜切遮罩、噪点、扫描线等），自行实现。
```

### 1.4 新增机械化测试

`tests/client/arkscope-vendor.test.ts`：

- 断言 `vendor/arkscore/` 下无 `.png` / `.jpg` / `.webp` / `.mp3` / `.mp4`
- 断言源码内无 `src/assets` / `public/assets` 引用
- 断言 `PROVENANCE.md` 存在且含 commit hash
- 断言组件总数 ≤ 3（防回流）

---

## 2. 功能任务 2 — 使用边界（硬约束，写进 `AGENTS.md`）

| 允许 | 禁止 |
|---|---|
| 登录页标题区装饰位面 | 聊天页（消息区 / 输入区 / 侧边栏） |
| Journey 图谱的背景层 | 任何表单页（Skills / Profiles / Settings / Models） |
| 首屏 loading / 空状态 | 任何表格页（Usage / Logs / Jobs / Kanban） |
| | 任何点击交互密集区域 |

**判定标准**：装饰位面**不得承载信息、不得承载交互、不得影响可读性**。

**`pointer-events: none` 是硬要求**，装饰层绝不能吃掉点击。

---

## 3. 功能任务 3 — 主题令牌迁移

### 3.1 新建 `packages/client/src/styles/arco-theme.ts`

替换 `styles/theme.ts`（Naive 的 `GlobalThemeOverrides`）：

```ts
export const arcoTheme = {
  // 延续旧版克制灰阶
  colorPrimary: '#2f2f2f',
  colorBgLayout: '#fafafa',
  colorBgContainer: '#ffffff',
  borderRadius: 6,
  fontFamily: 'Inter, system-ui, -apple-system, sans-serif',
  fontFamilyMono: '"JetBrains Mono", "Fira Code", monospace',
}
```

暗色模式走 CSS 变量覆盖，**不用** Arco 的 `dark` theme + overrides 双轨。

### 3.2 改 `App.vue`

旧版是 `naiveTheme` computed（浅/深两套对象）。改为：

```html
<div class="app-root" :class="{ 'dark': isDark }">
```

暗色由 `body[arco-theme='dark']` 承载（Arco 官方机制），app 只负责切换属性。

### 3.3 改 `index.html` 的 FOUC 脚本

保留旧版机制（内联脚本读 localStorage 提前定 class），但改为切 `arco-theme` 属性：

```html
<script>
  // 首屏前定主题，避免闪烁
  const t = localStorage.getItem('hermes_style')
  document.documentElement.setAttribute('arco-theme', t === 'dark' ? 'dark' : 'light')
</script>
```

> localStorage key `hermes_style` **保留**（Phase 002 白名单）。

### 3.4 `styles/variables.scss`

保留，但把 Naive 相关的 SCSS 变量映射到 Arco CSS 变量名。Phase 007 会重写 `style-system.test.ts`。

---

## 4. 功能任务 4 — 全局 Provider

`main.ts`：

```ts
import ArcoVue from '@arco-design/web-vue'
import '@arco-design/web-vue/dist/arco.css'
app.use(ArcoVue)
```

**全量注册，不做按需 tree-shaking** —— 换迁移速度，包体问题后期再优化。

---

## 5. 功能任务 5 — 三个全局 hook 适配层（**Phase 006/007 强依赖，先写**）

Naive 是 hook API，Arco 是命令式。全仓 200+ 处调用，必须先建适配层并**冻结接口**，后续批次只调用适配层。

新建 `packages/client/src/composables/`：

### 5.1 `useMessage.ts`

```ts
// 模块级单例，main.ts 里 app.use 时把 Message 实例挂上来
export function useMessage() {
  return {
    success: (c) => Message.success(c),
    error:   (c) => Message.error(c),
    warning: (c) => Message.warning(c),
    info:    (c) => Message.info(c),
    loading: (c) => Message.loading(c),
  }
}
```

### 5.2 `useDialog.ts`

```ts
export function useDialog() {
  return { confirm, info, success, error, warning }
}
```

### 5.3 `useNotification.ts`

```ts
export function useNotification() {
  return { success, error, warning, info }
}
```

**要求**：这三个文件的对外签名定下后**不再改**。后续所有批次只能调它们。若发现签名不够用，先扩适配层，不要在页面里直接引 Arco 的 `Message`。

---

## 6. 功能任务 6 — 组件映射表

新建 `docs/arco-mapping.md`，把全仓用到的 Naive 组件逐个映射。**先建表再改代码。**

已核实的核心映射（完整表在 Phase 006 补全）：

| Naive | Arco | 备注 |
|---|---|---|
| `NConfigProvider` | 直接用 `body[arco-theme]` | 不需要组件 |
| `NMessageProvider` / `useMessage` | `useMessage()` composable | §5.1 |
| `NDialogProvider` / `useDialog` | `useDialog()` composable | §5.2 |
| `NNotificationProvider` / `useNotification` | `useNotification()` composable | §5.3 |
| `NButton` | `a-button` | prop 名基本一致 |
| `NInput` | `a-input` / `a-textarea` | `type=textarea` → 独立组件 |
| `NSelect` | `a-select` | `options` 语义不同，需转换函数 |
| `NDataTable` | `a-table` | **列定义 API 差异最大** |
| `NModal` | `a-modal` | `v-model:show` 一致 |
| `NDrawer` | `a-drawer` | |
| `NPopover` / `NTooltip` | `a-popover` / `a-tooltip` | trigger 语义有差异 |
| `NSwitch` | `a-switch` | |
| `NTag` | `a-tag` | `bordered` 无对应，改 style |
| `NCard` | `a-card` | |
| `NProgress` | `a-progress` | |
| `NEmpty` | `a-empty` | |
| `NCollapse` | `a-collapse` | |
| `NTabs` | `a-tabs` | |
| `NForm` / `NFormItem` | `a-form` / `a-form-item` | **校验规则 API 不同，需适配** |
| `NGrid` / `NGridItem` | `a-row` / `a-col` | |
| `NIcon` | `<Icon />` + `@arco-design/web-vue/es/icon` | 需全局注册 |
| `NLayout` / `NLayoutSider` | `a-layout` / `a-layout-sider` | |
| `NScrollbar` | `a-scrollbar` | |
| `NTimeline` | `a-timeline` | |
| `NUpload` | `a-upload` | |
| `NTree` | `a-tree` | 结构差异大 |

生成实际用到的组件清单：

```bash
grep -rho "from 'naive-ui'" packages/client/src | wc -l          # 105 处
grep -rhoE "N[A-Z][a-zA-Z]+" packages/client/src --include="*.vue" | sort -u
```

---

## 7. 功能任务 7 — 样板页 A：LoginView

选它的理由：只用到输入框 + 按钮 + 少量文本，是**最小可控面**，且是装饰位面的合法落点。

改造点：
- `NInput` → `a-input`
- `NButton` → `a-button`
- 标题区挂 ArkScope `ScrambleTitle`
- 明暗切换走 §3.2 机制
- 装饰层 `pointer-events: none`
- 保留「hermes CLI 缺失引导」的入口（Phase 004 做的 `HermesMissingView`）

---

## 8. 功能任务 8 — 样板页 B：AppSidebar

选它的理由：全站导航唯一入口。Arco 的 `Menu` / `Layout.Sider` 语义在这里定型后，其余 20+ 视图的导航写法全部照抄。

改造点：
- `NLayout` / `NLayoutSider` → `a-layout` / `a-layout-sider`
- `NMenu` → `a-menu`
- `NIcon` → Arco Icon
- `NSelect`（profile 切换）→ `a-select`
- `NAvatar` → `a-avatar`
- `NTooltip` → `a-tooltip`

**它同时是最难场景**：深层文件 + `v-if="isSuperAdmin"` 条件渲染 + 大量 naive 引用。过了这关，剩下的是体力活。

---

## 9. 功能任务 9 — 定稿 `docs/ui-baseline.md`

本 Phase 的**核心交付物**。必须写清：

1. 色板（浅色 / 深色两套，含强调色）
2. 圆角 / 间距 / 字号阶梯
3. 字体栈（中英 / 等宽）
4. 阴影 / 分割线
5. 组件使用约定（什么时候用 Modal 什么时候用 Drawer、表格空态怎么处理、loading 怎么做）
6. 装饰位面的边界（复述 §2，落到本文档）
7. 三条不可破的规则：
   - 不引入第三个 UI 库
   - 消息气泡内部不用 Arco 组件（性能，见 Phase 006）
   - 装饰层一律 `pointer-events: none`

---

## 10. 验收

```bash
cd /Users/jack/source/MyProject/js/hermes-ui

# vendor 边界
find packages/client/src/vendor/arkscore -type f \
  \( -name "*.png" -o -name "*.jpg" -o -name "*.webp" -o -name "*.mp3" \)
# 期望：零命中

npm run test   # 含 arkscope-vendor.test.ts
npm run build
```

### 手工

- [ ] 登录页渲染正常，ArkScope 位面出现且鼠标穿透
- [ ] 明暗切换无闪烁（刷新页面验证）
- [ ] 侧边栏菜单全部可点进各视图（视图本身还没迁移，样式不完美是正常的）
- [ ] `npm run dev` 无 console 报错
- [ ] `docs/ui-baseline.md` 已写完

---

## 11. 风险

| # | 风险 | 缓解 |
|---|---|---|
| P5-1 | ArkScope 上游无 LICENSE | 只 vendor 2 个无素材组件；PROVENANCE.md 标注；仅自用；`arkscope-vendor.test.ts` 卡住素材回流 |
| P5-2 | 装饰层吃掉点击导致登录按钮点不动 | `pointer-events: none` 写进基线文档 + 手工点一遍 |
| P5-3 | 暗色切换闪烁 | FOUC 脚本在 `index.html` 内联，必须同步改（§3.3） |
| P5-4 | composable 适配层签名后续不够用 | §5 要求先定后冻结，不够用先扩适配层 |
| P5-5 | 样板页看着好，批量时发现约定不够 | §9 的基线文档要覆盖到 Phase 006/007 会遇到的场景 |
| P5-6 | 忘删 Naive Provider 包裹层 | 改完 grep `NConfigProvider` / `NMessageProvider` 确认归零 |

---

## 12. 完成标志

**风格基线定稿。** 进入 Phase 006（聊天页迁移）。