← 返回首页

前端设计系统与业务工作台规范

# anenreo 前端设计系统与业务工作台规范

## 1. 目标

前端不是数据库表的可视化管理器，而是一个能够长期使用的“个人数字操作系统”。页面必须帮助用户理解：

- 当前处于什么状态；
- 最近发生了什么；
- 哪些行动、周期和承诺需要处理；
- 哪些关系需要维护；
- 哪些记录、AI推断和数据来源需要确认；
- 数据是否安全、可导出和可恢复。

本规范适用于：

```text
apps/web       Nuxt 4 + Vue 3 + Nuxt UI 4
apps/mobile    uni-app + Vue 3 + Wot Design Uni + UnoCSS
```

## 2. 视觉语言：Quiet Intelligence 2.0

关键词：安静、可信、克制、档案感、时间感、长期使用、私人空间。

明确避免：

- 大面积紫色渐变；
- 毛玻璃和透明悬浮层作为常规页面背景；
- 所有内容都包在相同白色卡片中；
- 用“AI光效”代替信息层级；
- 重阴影、夸张圆角和无意义动画；
- 只有英文模块代码，没有中文业务说明。

### 2.1 核心颜色

| 语义 | 浅色 | 深色 | 用途 |
|---|---|---|---|
| 页面背景 | `#F3F2ED` | `#111411` | 整体工作空间 |
| 内容表面 | `#FAF9F6` | `#181C19` | 主内容区 |
| 次级表面 | `#ECEBE5` | `#202520` | 辅助说明、筛选和弱强调 |
| 主文字 | `#202723` | `#E8E7E1` | 标题和正文 |
| 次级文字 | `#68716C` | `#A5ADA7` | 元数据与说明 |
| 主色 | `#3F5F54` | `#8FB0A3` | 主操作和当前状态 |
| AI语义 | `#5D6477` | `#9BA2B8` | AI草稿、推断、工具审批 |
| 遗产语义 | `#8A683C` | `#C49B63` | 数字遗产和时间胶囊 |
| 危险 | `#994D4B` | `#D27A77` | 已批准的不可逆设置操作和高风险错误；Record Kernel v2 不提供记录 DELETE |

隐私、错误和状态不能只通过颜色表达；必须同时使用图标、中文文本或边框结构。

## 3. 信息架构

### 3.1 PC主导航

```text
今日
采集
记忆
关系
行动
复盘
个人智能
资产与遗产
全部模块
```

24个模块继续保留稳定路由，但不直接铺满一级导航。高频任务优先，低频模块通过“全部模块”和全局搜索进入。

### 3.2 移动底部导航

```text
今日
采集
记忆
行动
我的
```

移动首页不复刻PC模块目录。“我的”承载AI设置、离线状态和24模块目录。

## 4. 首页：个人状态驾驶舱

首页至少包含：

1. 当前状态；
2. 快速采集；
3. 今天的行动、周期和承诺；
4. 最近记忆；
5. 主动访谈问题；
6. 关系新鲜度提醒；
7. AI、备份和安全入口。

首页对 `SECRET` 和 `LEGACY_ONLY` 只显示安全状态，不展示正文摘要。

## 5. 模块工作台

每个模块统一具有“概览、记录、流程”三种阅读任务，但概览必须按模块原型呈现：

| 原型 | 典型模块 | 展示方式 |
|---|---|---|
| 人物档案 | identity、state | 当前状态、阶段和版本摘要 |
| 排序账本 | constitution、resource、taxonomy | 排名、依据、冲突和分组 |
| 收件箱 | capture、knowledge、integration | 来源、处理状态和失败任务 |
| 时间流 | memory、timeline、review | 时间轴、热度和待复盘 |
| 多媒体 | media | 媒体网格、转写和完整性 |
| 关系 | relationship、commitment | 联系新鲜度、互动和开放循环 |
| 行动 | action、routine | 目标、任务、到期和完成节奏 |
| 健康 | health | 指标、趋势和实验 |
| 决策 | decision | 方案对比、预测、结果和偏差 |
| 访谈 | interview | 问题队列、回答和待确认提取 |
| 证据 | personal-model | 推断、证据、反证和置信度 |
| 助手 | ai-agent | 会话、工具审批和执行审计 |
| 遗产 | legacy、digital-asset | 准备度、接收人、恢复和演练 |

模块顶部指标只基于当前已加载记录，必须明确统计范围。

## 6. 记录、表单和详情

### 6.1 记录卡片

展示：

- 业务时间；
- 标题与安全摘要；
- 两个最重要的模块字段；
- 生命周期状态；
- 隐私等级；
- 修订号。

卡片必须是真实链接或按钮，支持键盘、焦点和足够触控区域。

### 6.2 表单

字段按业务分组，而不是一张从上到下的长表：

```text
基础信息
模块专用分组A
模块专用分组B
来源、时间和隐私
修改原因
```

用户原文、AI草稿、AI推断和用户确认内容的来源必须明确区分。

### 6.3 详情

详情至少区分：

- 用户可读内容；
- 模块专用字段分组；
- 来源、时间和隐私；
- 修订和版本；
- 相关功能；
- 生命周期和危险操作。

Record Kernel v2 只提供可恢复归档，不提供记录 DELETE/永久销毁；若其他配置领域拥有独立不可逆操作，必须沿用同样的确认、响应和权威回读边界，不能把它推导到统一记录页面。

## 7. 响应式布局

PC使用Grid、Flexbox和Container Query：

```text
≥1280px    导航 + 主工作区 + 上下文
900–1279px 导航 + 主工作区，上下文转抽屉
600–899px  折叠导航 + 两列内容
<600px     单列内容
```

模块组件根据所在容器而非只根据视口调整布局。移动端优先保证88rpx左右触控区域和单手操作。

## 8. 状态与反馈

必须提供业务化状态：

- 加载：骨架屏；
- 空状态：解释为什么值得创建第一条记录；
- 错误：说明发生什么、数据是否保存、如何重试；
- 无权限：区分会话失效、重新验证、仅遗产可见；
- 保存成功：说明影响范围；
- 危险操作：分级确认；
- AI执行：显示Provider、模型、输入边界和副作用。

## 9. AI设置

Web和移动端均支持：

- 本地Mock；
- OpenAI兼容接口；
- base URL；
- 模型名；
- API Key只提交给服务端加密保存；
- 页面只显示是否存在和脱敏尾号；
- 固定无隐私内容连接测试；
- 不把Key写入浏览器或移动本地存储。

## 10. 可访问性

- 提供跳到主内容链接；
- 路由变化后聚焦页面标题；
- 页面只有一个主H1；
- 使用 `nav`、`main`、`aside`、`search` 等语义；
- 所有可点击元素支持键盘与清晰 `:focus-visible`；
- 表单错误与字段关联；
- 加载和保存结果使用 `aria-live`；
- 对话框管理焦点；
- 支持 `prefers-reduced-motion`；
- 深色模式单独验证对比度。

## 11. 代码复用边界

共享组件负责一致性：

```text
PageHeader
AppSectionPanel
AppStatePanel
AppMetricTile
PrivacyBadge
RecordStatusBadge
MobileMetricStrip
MobileRecordCard
MobileBottomNav
```

模块专用视图负责业务理解：

```text
TimelineBusinessView
RelationshipBusinessView
ActionBusinessView
HealthBusinessView
DecisionBusinessView
InterviewBusinessView
AiBusinessView
LegacyBusinessView
MobileBusinessSnapshot
```

共享组件不能把所有模块重新压回通用CRUD；模块原型和字段分组必须来自统一展示目录。

## 12. 分层偏好中心

偏好中心使用“基础设置 + 高级设置”两层，不复制后台框架中与个人系统无关的租户、报表和多标签样式。

基础设置：

```text
主题模式
主题预设
字体大小
信息密度
圆角
减少动态效果
```

高级设置：

```text
Web导航模式
内容宽度
右侧上下文栏
粘性操作栏
首页Widget
技术代码显示
移动底部标签
触觉反馈
隐私模糊
单手模式
常用模块数量
```

偏好必须：

- 经过版本化和归一化；
- 默认只保存在本机；
- 支持安全导出、导入和恢复默认；
- 不包含 API Key、业务正文、会话令牌和恢复秘密；
- Web 映射到 Nuxt UI 语义色和 CSS 变量；
- 移动端同时更新 Wot ConfigProvider 与页面级 CSS 变量。

主题预设必须由共享设计令牌统一提供二十套跨端方案。每套方案包含主色、辅助色和强调色三个安全十六进制颜色槽，预览使用混合渐变；Web 使用原生颜色选择器，移动端使用可滚动色板弹层，禁止把颜色值作为普通文本让用户手填。PC 与移动端的主题代码、名称、颜色目录和自定义偏好字段必须保持一致。

## 13. 六类模板与八个专用工作台

六类基础模板用于共享布局和组件：

```text
档案类
网络关系类
行动流程类
评估分析类
智能推断类
高敏感治理类
```

以下核心模块必须拥有专用摘要和交互，不得退回单一通用CRUD：

```text
memory
relationship
action
routine
decision
interview
personal-model
legacy
```

共享模板负责一致性，专用工作台负责业务理解。模块页面可以复用记录列表、状态面板和字段组件，但必须提供本模块独有的指标、业务分组、状态转换和下一步动作。

## 14. 页面状态和空数据原则

- 404、403、409、网络失败和未知错误分别呈现，并提供恢复动作；
- 页面加载结束后必须进入成功或错误状态，不允许永久显示加载；
- 所有聚合数据为空时，首页只显示一个初始化向导；
- 统计数据不足时解释如何建立统计，不显示无意义的四个0；
- 技术枚举默认显示中文，可由“显示技术代码”偏好显示英文代码；
- 粘性和固定操作栏必须为正文预留空间，并正确处理移动端安全区。

## 15. 浏览器验收运行输入

Playwright、截图和页面验证脚本属于有权限的验收客户端，不得在源码中携带登录秘密或绑定某位开发者的浏览器缓存：

- 需要登录的脚本必须由调用方显式提供 `ANENREO_DEMO_PASSWORD`；缺失或空白时在启动浏览器和访问网络前失败；
- `ANENREO_CHROMIUM_PATH` 显式提供时优先使用并验证为普通文件，无效时失败关闭；
- 未显式提供浏览器路径时，只允许检查当前操作系统常见的 Google Chrome 和 Microsoft Edge 安装文件；
- `ANENREO_PC_URL`、`ANENREO_MOBILE_URL` 与 `ANENREO_API_URL` 必须在密码读取和网络访问前解析为字面量 `127.0.0.1`；默认端口分别为 `3000`、`5173`、`4000`，显式隔离端口必须位于 1024～65535 且三端互异，API 路径固定为 `/api/v1`；IPv6、HTTPS、localhost 名称、URL 凭据、查询、哈希、越界/重复端口和远端主机一律失败关闭；
- 禁止从 `.env` 读取验收密码，禁止把固定密码、Cookie、Token 或用户专用 `ms-playwright` 路径写入脚本、报告和截图清单；
- live AI 验收脚本遵守相同输入门禁，但只有获得单独授权时才可运行；普通浏览器验收不得隐式访问 Provider。

这些门禁只证明验收工具的输入安全和可迁移性，不代表页面流程、领域功能或外部 Provider 已完成验收。

## 16. Web 字体与图标的离线构建边界

PC Web 的发布候选必须能够在不访问公共字体服务的环境中完成构建：

- `apps/web/nuxt.config.ts` 必须通过 `ui.fonts=false` 关闭 Nuxt UI 默认带入的 `@nuxt/fonts`；
- 不得显式注册 `@nuxt/fonts`，也不得配置 Google、Google Icons、Bunny、Fontshare、Adobe 等远程字体 Provider；
- 主界面继续使用 `ui-sans-serif`、系统 UI 字体、苹方和微软雅黑等本机字体回退，不从 CSS 导入远程字体；
- Nuxt UI 组件、颜色模式和 Icon 模块继续保留，图标使用仓库依赖中的 `@iconify-json/lucide` 本地集合；
- 若未来引入品牌字体，字体文件必须随源码候选交付或来自已安装的本地 npm 字体包，并补充离线构建与许可证据；
- `check-web-build-network-policy.mjs` 同时检查源码策略和实际 build 日志，发现远程字体端点、Provider 下载、重试或超时即失败。

该门禁只证明 Web 构建的字体网络隔离，不代表页面交互或任何领域功能完成验收。