a207cb8d65
- .agents/skills 25 件全量 frontmatter 规范化与评审修入(含 prompt-governance 大修);.claude/skills 7 件薄壳按双层方案①落位 - 新增 skill:agentic-seat-context-design(agentic 席位与 context 工程设计基线,2026-07-05 探索蒸馏) - 设计波三件落档:复杂游戏北极星件(W-NSTAR 终审稿待拍)/黄金模板规格件(W-TPL 定稿待批)/生成侧过程蒸馏回路(W-GENLOG 骨架) - protocol/在飞板/作战清单/数据飞轮 SoT/契约 prompts 索引同步;breakout 九门证据刷新 - .gitignore 补 /localagents.md 真实忽略行(该文件自声明绝不提交,此前声明未被机器执行) - 刻意不入库:nacos-data/ 与 _tier2-gen、c2v-*、amgen-* 生成产物(可重生成,忽略行格式待拍) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
317 lines
35 KiB
Markdown
317 lines
35 KiB
Markdown
---
|
||
topic: 前端设计体系
|
||
canonical: true
|
||
date: 2026-06-12
|
||
---
|
||
|
||
# 前端域 · 设计主文档
|
||
|
||
> **这是什么**:绘境AI 前端域的设计主文档,回答"**两个前端长什么样、靠什么撑起一致的体验**"。它聚焦设计体系(design system)这一层——即把颜色、间距、字体、组件、主题、多语言这些"视觉与交互的共同语言"统一沉淀下来,让所有界面看起来像同一个产品。
|
||
> **给谁看**:前端工程师、设计师、产品经理、新加入的同事、外部技术尽调。
|
||
> **怎么读**:先读本页建立全局认知——我们有哪两个前端、它们各服务谁、设计体系分几层、为什么这么分、创始人定下了哪些不可动摇的硬约束;需要某条具体令牌(token)的取值或某个组件的签名时,再回到代码里的权威源文件(文末有指针)。
|
||
> **读这一页 = 前端设计体系的当前真相**。它从子系统活档 `docs/architecture/前端/README.md` 蒸馏而来,只取其架构骨架与关键决策的"为什么";逐令牌清单、逐组件实现、构建与走查的具体命令不在这里(分别交给代码里的 `tokens.css` 与 `.agents/skills/` 下的操作手册)。
|
||
|
||
---
|
||
|
||
## 1. 绘境AI 有两个前端
|
||
|
||
绘境AI 把面向不同人群的界面拆成两个独立的前端应用,它们在[架构域](../架构/README.md)里都画在"前端应用层",但服务的人和承载的能力截然不同。
|
||
|
||
**game-studio** 是产品前端,同时服务**创作者**和**玩家**两类终端用户。创作者在这里一句话生成游戏、预览迭代、发布到多个渠道、查看收益;玩家在这里刷"游戏信息流"(类似短视频的竖屏即刷即玩流)、点赞分享评论。它用 **Vue3 + Vant** 构建——Vant 是一套移动优先的 Vue 组件库,天然适配游戏流的滑动交互。
|
||
|
||
**game-admin** 是管理后台前端,服务**平台运营**和**管理员**。他们在这里做内容审核、用户管理、数据看板、合规处置等后台工作。它用 **Vue3 + Element Plus** 构建——Element Plus 是 Huijing(我们 fork 的开源 Java 企业级后台框架)官方主推的桌面端组件库,二次开发友好。
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
subgraph STUDIO["game-studio — 产品前端(消费级)"]
|
||
direction LR
|
||
CRT["创作者<br/>生成 / 预览 / 发布 / 收益"]
|
||
PLY["玩家<br/>游戏信息流 / 互动"]
|
||
end
|
||
subgraph ADMIN["game-admin — 管理后台前端"]
|
||
direction LR
|
||
OPS["运营<br/>审核 / 数据看板"]
|
||
MGR["管理员<br/>用户 / 合规处置"]
|
||
end
|
||
STUDIO -.->|Vue3 + Vant<br/>移动优先| DS["共同的设计语言<br/>(品牌色 / 间距 / 字体 / 圆角)"]
|
||
ADMIN -.->|Vue3 + Element Plus<br/>桌面端| DS
|
||
```
|
||
|
||
> **范围说明**:本档的设计体系建设当前**聚焦 game-studio**——因为它是直面大众市场的消费级产品,卖相与一致性的要求最高,投入产出比也最高。game-admin 是内部后台工具,沿用 Element Plus 默认体系即可满足,只在品牌色这一层与 studio 对齐。下文除非特别标注 admin,默认讲的都是 studio 的设计体系。
|
||
|
||
---
|
||
|
||
## 2. 一句话定位:studio 的体系化波次
|
||
|
||
我们给 studio 的设计体系建设起了一个内部编号 **HJ-FE-DS-001**(HJ = Huijing/绘境,FE = Frontend,DS = Design System)。它不是零散地改几个页面,而是一次**体系化的波次**(wave,指一组围绕同一目标、成批推进并统一收口的工作),一次性把六件事立起来:
|
||
|
||
1. **设计 token 两层** —— 把所有颜色、间距、字号抽成可复用的"设计令牌",分两层管理(详见 §4)。
|
||
2. **vue-i18n 中英双语** —— 用 vue-i18n(Vue 的国际化插件)做中英文切换,杜绝组件里写死中文。
|
||
3. **通用组件库** —— 在 Vant 之上封装一层带绘境AI 品牌气质的组件。
|
||
4. **暗/浅/柔三档主题** —— 用户可在设置里切换暗色、浅色、柔和三种舒适度的配色。
|
||
5. **统一圆角矩形** —— 全站圆角风格统一,禁止药丸形、椭圆、正圆混用。
|
||
6. **SVG 图标** —— 用矢量图标替代 Unicode 字符和 emoji。
|
||
|
||
**现状 = 已全量收口并合入主干 `dev/2.0.0`。** 19 个视图全部接入新体系,6 道 mini-desktop(在一台模拟桌面环境里跑真实浏览器)构建门全绿,真机三主题 × 双语的 CDP 走查(经 Chrome DevTools Protocol 远程驱动真浏览器逐屏验收)全部通过。落地经过了六个有序的提交批次,从最初的"卖相批"(先把退出登录入口、品牌渐变、Inter 字体这些最影响第一印象的点修好)一路推进到代表性页面全量上体系、品牌统一为绘境AI。
|
||
|
||
---
|
||
|
||
## 3. 一个核心判断:学 demo 的"设计语言",不学它的"布局范式"
|
||
|
||
设计体系从哪里起步?我们手上有一份早期的投资人路演原型 `docs-design/huijing-ai-demo.html`(下文简称 **demo**)。对它,我们做了一个关键的取舍判断,这个判断决定了整个前端的形态。
|
||
|
||
**保留** demo 的"设计语言"——它的 token 体系、`cyan→green`(青到绿)的品牌渐变、暗色玻璃质感。这套视觉语言有辨识度,值得沿用。
|
||
|
||
**否决** demo 的"布局范式"。demo 是一个**桌面产品外壳**:固定 236px 宽的左侧栏 + 1140px 宽的工作台,把短视频流硬塞进一个 390×660 的模拟手机框里展示。这是投资人路演用的"控制台"叙事,不是真正给大众用户的消费级界面。
|
||
|
||
现行定位因此是**响应式优先的消费级 Web**:移动端做沉浸式全屏体验,桌面端做居中放大,一套组件适配两端。原生桌面 App、原生移动 App 都是更远期的层级,现在不做,但设计 token 提前为它们铺好了路(见 §4)。
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
DEMO["demo 原型<br/>huijing-ai-demo.html"]
|
||
DEMO -->|保留| KEEP["设计语言<br/>token 体系 + cyan→green 渐变 + 暗色玻璃质感"]
|
||
DEMO -->|否决| DROP["桌面侧栏控制台布局<br/>(236px 侧栏 + 1140px 工作台 + 模拟手机框)"]
|
||
KEEP --> NOW["现行:响应式优先消费级 Web<br/>移动沉浸 / 桌面居中放大 / 一套组件"]
|
||
DROP -. 远期 .-> LATER["原生桌面 App / 移动 App<br/>(仅 token 契约先就绪)"]
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 设计体系怎么搭:token 两层 + 组件库四层
|
||
|
||
这是整个前端域最核心的一张架构图。它由两条主线组成:一条是**设计 token 的两层结构**(为什么是"两层"见下),另一条是**组件库的四层封装**,两者在语义层交汇。
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
subgraph TOKEN["设计 token · 跨端单一事实源"]
|
||
P["primitive 原始层<br/>原色板 / 灰阶 / 尺寸原子"] --> S["semantic 语义层<br/>语义令牌(bg / surface / accent / danger…)"]
|
||
S --> CT["component 组件层<br/>组件级令牌"]
|
||
end
|
||
S --> L0
|
||
subgraph LIB["组件库 · 四层封装"]
|
||
L0["L0 token<br/>CSS 变量落地"] --> L1["L1 Vant 适配<br/>把 Vant 变量映射到语义层<br/>复用 Vant 的交互 / 无障碍 / 键盘"]
|
||
L1 --> L2["L2 品牌基元<br/>AppButton / Field / Icon / Card / Chip<br/>EmptyState / NavHeader / TabBar / Skeleton / Toast"]
|
||
L2 --> L3["L3 业务组合<br/>GameCard / InteractBar / FilterTabs…"]
|
||
end
|
||
S -. 同一份 token JSON .-> APP["桌面 App 复用 Web 技术<br/>移动 App 用 RN / Flutter(远期)"]
|
||
```
|
||
|
||
### 4.1 为什么 token 要分两层
|
||
|
||
"token 两层"指的是**原始层(primitive)→ 语义层(semantic)** 的分离,组件层(component)是按需追加的第三层。
|
||
|
||
- **原始层**只描述"物理事实":`--cyan` 是某个青色、`--sp-3` 是 12px。它不带含义,只是调色板和尺子。
|
||
- **语义层**描述"用途":`--bg` 是页面背景、`--accent` 是强调色、`--danger` 是危险色、`--surface-1..3` 是从底到顶的层叠表面。组件**只准引用语义令牌**,绝不直接碰原始层。
|
||
|
||
这样分层带来一个关键好处:**换肤时零改组件**。主题切换只需在语义层重新指向不同的原始色(比如暗色主题下 `--bg` 指向深色、浅色主题下指向浅色),组件因为只认 `--bg` 这个语义名,会自动跟着变,一行组件代码都不用动。
|
||
|
||
### 4.2 token 作为"跨端单一事实源"
|
||
|
||
token 还承担一个长期使命:**做跨端的单一事实源**(single source of truth,即同一份事实只有一处权威定义)。同一份 token 现在服务 Web(吃 CSS 变量),未来桌面 App 复用 Web 技术栈直接沿用,移动 App 则把同一份 token 导出成 JSON 喂给 React Native 或 Flutter。这样无论平台怎么扩,品牌的颜色和尺寸只有一处定义,既服务"远期双 App",又避免长期沉淀出互相打架的垃圾代码。
|
||
|
||
### 4.3 组件库为什么是四层
|
||
|
||
组件库自底向上四层,每层职责单一:
|
||
|
||
- **L0 token 层**:把上面的设计令牌落地成 CSS 变量,是组件库的地基。
|
||
- **L1 Vant 适配层**:通过 `vant-theme.css` 把 Vant 自带的 `--van-*` 变量映射到我们的语义层。这一层的价值是**白嫖 Vant 的交互、无障碍、键盘支持**——这些是社区打磨多年的能力,不必自研。
|
||
- **L2 品牌基元层**:封装一批带绘境AI 品牌气质的基础组件,如 `AppButton`(应用按钮)、`Field`(输入域)、`Icon`(图标)、`Card`、`Chip`、`Badge`、`EmptyState`(空状态)、`NavHeader`(导航头)、`TabBar`(底部标签栏)、`Skeleton`(骨架屏)、`Toast`(轻提示)。
|
||
- **L3 业务组合层**:把基元拼成业务组件,如 `GameCard`(游戏卡片)、`InteractBar`(互动条)、`FilterTabs`(筛选标签)。
|
||
|
||
### 4.4 三条数据流
|
||
|
||
整个体系靠三条数据流串起来:
|
||
|
||
- **token 流**:`L0 token → L1 vant-theme → L2 品牌组件 → L3 业务面`,自底向上逐层消费。
|
||
- **theme 流**(主题/换肤):`localStorage(studio.theme) → <html data-theme> → 语义层覆盖 → 全组件自动反应`。为防止 FOUC(Flash of Unstyled Content,即页面首帧闪现未应用样式的难看瞬间),`index.html` 在首屏渲染前内联一段脚本,先读 `localStorage` 把 `data-theme` 和 `lang` 设好。
|
||
- **i18n 流**(国际化):`main.ts 注册 vue-i18n → 组件用 useI18n($t) 取文案 → localStorage(studio.lang) 与 <html lang> 同步`。
|
||
|
||
---
|
||
|
||
## 5. 创始人 5 项决议(已拍板 · 硬约束)
|
||
|
||
下面五条是创始人拍板的硬约束,不可动摇,是整个前端设计体系的地基。
|
||
|
||
1. **响应式优先消费级 Web**。否决 demo 的桌面侧栏控制台范式;移动端沉浸、桌面端居中放大,一套组件适配两端。
|
||
|
||
2. **暗色先行 + 设置内多档舒适主题可切**(暗 / 浅 / 柔和三档)。实现方式是在语义层用 `[data-theme]` 属性做覆盖,用 `localStorage` 持久化用户选择;**首次进入默认暗色**(`:root`,不写 `data-theme`),之后由用户在设置内显式切换。(跟随系统 `prefers-color-scheme` 信号是远期增强,当前尚未接入——代码只读 `localStorage`,无持久化值时一律回落暗色。)
|
||
|
||
3. **SVG 图标取代 Unicode/emoji**,取向 lucide(一套开源的线性 SVG 图标库)。
|
||
|
||
4. **金样板先行**。不一上来就全站铺开,而是先把"token + 组件库 + 1 个消费面(游戏信息流 Feed)+ 1 个创作面(Create)"打磨到位、双语化、验证通过,再批量推其余视图。这是项目"黄金模板先行"效率原则在前端的落地。
|
||
|
||
5. **统一圆角矩形**。禁止药丸形、椭圆、正圆混用;圆角半径按尺寸成比例分级——`xs/sm/md/lg/xl = 4/6/8/12/20`(像素),默认用 `md`(8px)。唯一例外是 loading 旋转环保留圆形。这条是铁律,单独立了一份规则文档 统一圆角规范(未立独立档,以本档为准) 约束。
|
||
|
||
---
|
||
|
||
## 6. 三大契约:token / 组件 / i18n
|
||
|
||
设计体系对外暴露三套契约(contract,即跨人协作时大家都遵守、不能私自破坏的约定)。三套都坚持 **additive**(增量式)原则——旧令牌一律保留为别名,各页面在迁移期新旧共存、逐面切换,绝不一刀切破坏现有引用。逐令牌的权威清单以代码里的 `game-studio/src/styles/tokens.css` 为准,这里只讲骨架与命名空间。
|
||
|
||
### 6.1 token 契约
|
||
|
||
旧令牌(`--cyan`/`--green`/`--radius`/`--shadow` 等)全部保留,其中 `--cyan` 等被设为新语义令牌 `--accent` 的别名,对现有引用零破坏。新增三组:
|
||
|
||
- **primitive 原始层**:原色板 `--cyan/--green/--pink/--amber/--danger/--violet`,以及一对"在彩色背景上的前景色"`--on-accent:#061014`、`--on-danger:#2a0608`。
|
||
- **semantic 语义层**:`--bg`、`--surface-1..3`、`--accent`、`--success`、`--warning`、`--danger`、`--border-1..2`、品牌渐变 `--grad-primary`、热区渐变 `--grad-hot`、焦点环 `--focus-ring`。
|
||
- **尺度令牌**:间距 `--sp-1..6 = 4/8/12/16/22/32`、圆角 `--radius-xs..xl = 4/6/8/12/20`(默认 `md`)、阴影 `--elev-1..3`、字号 `--fs-h1/h2/h3/body/caption`、字重 `--fw-*`。
|
||
|
||
三档主题 `[data-theme=light|dim]` **只覆盖语义层**,不碰原始层。另一条收口约定:手写的 `rgba()` 透明度一律改用 `color-mix(in srgb, var(--token) N%, transparent)`,让透明色也走令牌而非硬编码。
|
||
|
||
### 6.2 组件契约
|
||
|
||
`AppButton` 的 props 保持不变(`type/size/block/loading/disabled`),向后兼容;但 primary(主)按钮恢复了品牌的签名渐变(`--grad-primary` + `--fw-cta` 字重 + `--on-accent` 前景),并补齐全部交互态:`focus-visible` 焦点环、`disabled` 时 0.5 透明度、`active` 时 scale 0.98 的按压反馈。`Icon` 组件**禁用 emoji**。
|
||
|
||
### 6.3 i18n 契约
|
||
|
||
采用 **vue-i18n@10**。文案文件放在 `src/locales/*.{zh,en}.ts`,按业务域划分命名空间(`common/feed/create/profile/entry/taskflow/project/hub/biz`)。硬约束:**禁止组件内出现裸中文**;缺失的 key 回退(fallback)到 `zh-CN`;数字、日期、货币一律用浏览器原生的 `Intl` API 本地化;品牌字符串统一收敛到 `common.brand` 一个 key(其值 = "绘境AI"),改名时只改一处。
|
||
|
||
---
|
||
|
||
## 7. studio vs demo:勿误砍 / 勿误判清单
|
||
|
||
这一节是两份"记录型"结论,目的是防止后人把 demo 当成目标、反而削弱了 studio 已有的真实能力,或者把"有意砍掉的范围"误判成"缺陷"去返工。
|
||
|
||
### 7.1 反向超出(studio 有 / demo 无 · MVP 真实可用必需 · 勿砍)
|
||
|
||
这些是 studio 比 demo 多出来、且 MVP 真实可用所必需的能力,绝不能因为"demo 里没有"就砍掉:
|
||
|
||
- **真实试玩宿主**:iframe 沙箱 + SDK/Runtime 注入 + postMessage 双向桥接双校验 + manifest 的 sha256 校验。这是护城河的命门——demo 里的"试玩"只是一个 toast 提示加一块静态 div,根本不是真在跑游戏。
|
||
- **登录注册整屏**:短信登录即注册 + 协议同意门 + 登录后 redirect 回跳 + 匿名 id(anonId)衔接。demo 完全没有登录概念。
|
||
- **分享落地页**:独立的 `/share/:gameId` 页 + Open Graph 元数据(社交平台抓取生成卡片预览用)+ utm 渠道归因参数。demo 里分享仅是一个 toast。
|
||
- **失败/取消/重试闭环**:生成任务的七种失败原因有可读的中文映射 + 可取消可重试 + 进度色反馈。demo 用 720ms 模拟一卡到底的 complete,从不出现失败态。
|
||
- **发布门禁**:7 项客户端预检 + 服务端权威返回 `{admitted, gates}` + 三态展示。demo 是乐观直发,无审核。
|
||
- **鉴权守卫 + 全链路埋点**:路由守卫只认真实 token(`isRealLogin`)+ 性能/游玩/会话埋点。demo 是纯前端切屏,不接任何后端契约。
|
||
|
||
### 7.2 有意 MVP descope(是范围裁剪 · 不是缺陷 · 勿返工)
|
||
|
||
下面这些是有意排除在 MVP 之外的(descope = 主动缩减范围),不是漏做的缺陷:
|
||
|
||
- **首页门户**:投资人路演的载体,归 PC 官网/投资人 demo,远期。
|
||
- **素材中心**:属 P1/v2.0,不在 55 个 P0 之列;真要落地须先补素材契约 + 授权/分成支付模型,且采购流程必须走后端可信边界,不能停在前端 mock。
|
||
- **玩法模板中心**:注意——这里指的是 demo 那块"玩法品类层市场"屏,已被创始人 2026-06-12 的 W-CLEAN 清理(清理旧填参式模板的收口工作)废除。它与架构文档里"玩法模板 = 品类框架、未废、待建"是两回事,**不要混淆**。
|
||
- **创作者数据后台**:远期;落地须反向定义出回读 API + 把诊断接到生成侧,避免产生没有入口的孤儿数据。
|
||
- **多渠道发布**:抖音/微信/快手/TapTap 等渠道导出,归独立的渠道发行专项另行推进,游戏信息流的终裁不受影响。
|
||
- **完整可视化编排 IDE**:全自定义拖拽式编排、授权 IP 模式、编辑态逐参可视化调试等专业向能力,属远期,MVP 不做。
|
||
|
||
### 7.3 产品形态定调:对话式创作不是 descope(创始人 2026-06-21)
|
||
|
||
要把上一条和"对话式创作"分清,否则容易把产品形态错当成被砍掉的范围。绘境的**完整产品形态是对话式创作闭环**:多轮对话把游戏生成出来、对已经生成的游戏做差量修改(换美术、改第 2 关,只动一处、不毁全局)、以及修改游戏里用到的素材。"一句话 + 选玩法模板 → 整包生成"不是终点,而是**发起一次生成的启动点位之一**。
|
||
|
||
这套能力的后端已经是现行真相——`/studio/modify`、`/studio/extend` 端点和 SAA 的 modify 节点都建好了,studio 三路由 `/studio/{create,modify,extend}` 也在。当前缺的是前端承载:对话框、把六类素材传进去当生成上下文、系统解析意图后的目标确认卡、以及差量修改的入口和"改了哪、其余没动"的差异展示(对应历史回收判定的前端 C01–C04)。所以这块不是"descope 勿返工",而是**产品形态已经定调、前端 UI 待补设计**。
|
||
|
||
> 一处口径校准:产品域需求清单里"智能体对话式创作"(P-CRT-05)、素材中心(P-MAT 整组)仍标 P1;同款创作(P-FED-12)已由创始人 2026-06-22 拍板升 P0(数据飞轮网络效应核心杠杆,Doc A 已改)。把 P-CRT-05 / P-MAT 定调为产品形态讲的是**方向**,不等于把它们的验收优先级一次性提到 P0——这两项的调整仍另走评审,别擅自改动验收契约。
|
||
|
||
---
|
||
|
||
## 8. 现状:已完成与遗留
|
||
|
||
**已完成**(都已在 `dev/2.0.0`):
|
||
|
||
- 退出登录的孤儿入口已闭合——Profile 页调用既有的 `userStore.logout()`,真实清掉 5 个 localStorage 键。
|
||
- 主按钮品牌青绿渐变已回归(`AppButton.primary` 用 `--grad-primary` + `--on-accent`,字重约 800)。
|
||
- Inter 字体已 self-host(自托管,不依赖外部 CDN;`reset.css` 里 `@font-face` + `font-display:swap`,中文有兜底字体)。
|
||
- 消息中心一级入口已落地(底部标签栏从 3 个 tab 扩到 4 个,含 `/message`,带 `messageStore.unreadTotal` 未读角标)。
|
||
- B 端前端归属已定为 studio 承接(`src/views/biz/` 下已建 BizLeads/BizLeadDetail/BizTemplatePicker/BizCreate,接既有的 `/app-api/biz/*` 7 个端点)。
|
||
- 字号阶梯令牌已抽出(`--fs-h1/h2/h3/body/caption`)。
|
||
|
||
**遗留(小尾巴)**:
|
||
|
||
- `tokens.css:3` 的注释里还残留旧路径 `zaomeng-ai-demo.html`(实际文件是 `huijing-ai-demo.html`,品牌应为绘境AI),措辞漂移待清。
|
||
- 明确不做的范围:原生 App(仅 token 契约就绪)、RTL(从右到左书写,服务阿拉伯语等)、护眼/高对比主题(留作后续增量)。
|
||
|
||
**tier2 富游戏的前端承载(待建,归属已定)**:第二条生成轨 tier2 的产物是 Phaser 多文件工程、要渲入 game feed 真玩。它给前端域带来两件现在还没做的事——feed 同时承载两种产物(现有 LittleJS 单包 + tier2 Phaser 多文件工程)的装载分发,以及 studio 创作端体现"轻量档 / 富游戏档"的第二档创作入口。这两件归前端域(运行时容器 + 创作入口);装载与渲染的 how 在架构域,见生成运行时架构 SoT [`../架构/生成引擎/agentic运行时架构图说.md`](../架构/生成引擎/agentic运行时架构图说.md)。tier2 已过 0 号 spike(n=1 accept),前端承载可着手:这两件前端落点仍待建,现在先钉归属、详细的逐页 UI 留实现时展开。
|
||
|
||
---
|
||
|
||
## 9. 前端域承载范围:近期待补的前端落点
|
||
|
||
前面几节讲的是设计体系本身、以及 studio 相对 demo 的能力盘点。但前端域要承载的不止设计体系——有一批能力,后端、契约、运维、架构域都已经把"里子"做出来或定下来了,缺的只是前端这层"面子":页面、入口、按钮、展示。这一节把这些**归属在前端域、近期要补的落点**钉清楚,按时间窗分组。它只立"该谁承载、什么时候补"这件事,不在这里写逐页 UI 的详细设计——具体到组件与交互的 file 级设计,留给实现时在活代码里落。这一整节都来自创始人 2026-06-22 历史回收判定的捡回,逐条对应历史回收判定([创始人判定](../_recall/创始人判定.md))里同名的设计点。
|
||
|
||
### 9.1 前端域引用承载:把活在别域的前端约束引一份过来
|
||
|
||
前端的体验是很多跨域约束的最终执行点,但这些约束的权威定义常常活在架构域、运维域或代码里,前端域却看不到它们。这容易让人误以为"前端没有性能/观测责任",其实前端正是这些指标的兑现处。下面这几条不在前端域重新定义(避免一份事实两处写、口径漂移),只引用一句、点明它们的前端责任,让读前端档的人知道这些线压在前端身上。
|
||
|
||
**体验 SLO 的前端责任。** 信息流首屏 P75 < 3 秒、点卡到可玩 S2 常态 ≤ 2 秒(全新设备首次 ≤ 3.5 秒)这套体验承诺,权威定义在架构域(原《引擎与运行时》已并入运行时 SoT [`agentic运行时架构图说`](../架构/生成引擎/agentic运行时架构图说.md);其中首局可玩 ≤2s 那一档在 [`验收门`](../架构/生成引擎/验收门.md) 的首局体验门)。它对前端的含义是:首帧绘制、加载态反馈、预热时机这些都是前端的执行点——manifest 随 feed 清单先行下发后,前端要能在 300ms 量级先用它把游戏的主题底色和标题画出来,消除加载等待感,而不是干等游戏字节到齐才出画面。自适应质量分档(首次会话探测设备能力、低端机自动降画质)也有前端/宿主的探测与降级开关这一半。这些都不在前端档展开设计,只记一句:**前端是这套体验 SLO 的兑现处,设计与验收时要把它当成前端的首要约束,而不是别人家的指标。**
|
||
|
||
**feed 容器调度的前端责任。** 信息流的核心手势(上滑切下一款)、三容器预加载策略(销毁当前 + 激活预加载好的下一个、N±1 只预取字节不实例化)、以及 manifest 随 feed 清单下发省一次往返,这套运行时调度的"how"归架构域生成引擎子树。但**前端 feed 列表如何维护这三态容器、何时按滚动方向触发上/下预取、切换动画怎么做**,是前端实现问题。这里只钉归属:feed 的滑动手势承载与容器生命周期调度归前端域,装载与渲染的底层机制见架构域,别让它悬空成"两边都以为对方在管"。
|
||
|
||
**feed 方向与游戏方向的定义。** "竖屏 feed"定义的是**手机竖握场景下的垂直信息流容器**:玩家以上滑手势切换游戏,前端用三容器预加载承载连续消费体验。它不是"所有游戏画布必须竖屏"的内容约束。游戏本身可以是竖屏、横屏或自适应方向;前端不能把横屏游戏强行挤进竖屏画布,也不能为了维持卡片比例拉伸玩法画面。横屏游戏进入 feed 时,竖屏卡片只负责保留正确宽高比的预览、封面或 letterbox 画面,并给出旋转/进入横屏沉浸播放的清晰入口;真正游玩可以切到沉浸式 play 容器,由宿主按游戏声明的方向、宽高比和控制方案装载。桌面端只是响应式放大的兼容形态,不是 feed 的优先目标。
|
||
|
||
这条定义也给入 feed 的放行口径划边界:横屏游戏可以入 feed,但要和竖屏游戏一样过首屏、点开可玩、触控输入和错误观测等移动端验收门;控制方案不能只依赖键盘/手柄,必须有手机触控路径。`orientation / aspectRatio / controlScheme / feedPresentation` 这类字段属于后续 contract-first 待落的 manifest 契约,当前前端域先钉产品与承载口径,具体 schema、装载分支和验收探针仍按架构域生成运行时 SoT 推进。
|
||
|
||
**前端可观测性的承载。** 页面在真实用户浏览器里加载多慢、报了什么 JS 错、首屏耗时实测对齐 P75 < 3s——这种前端可观测性,和现有那条"业务遥测(性能/游玩/会话)落 `game_telemetry_event`"的业务数据回路是两回事。它的承载方案是运维域观测体系里那条 **OTel Web SDK**(给 `game-studio` / `game-admin` 接入,采页面性能 / JS 错误 / 前端 trace),权威定义见 [`../运维/观测体系.md`](../运维/观测体系.md)。现状标的是"可选、后期",前端域只引这一句、认下这个承载点:**前端的页面级性能与错误观测走 OTel Web SDK,不在前端另造一套采集。**
|
||
|
||
### 9.2 admin(game-admin)第一期承载:审核台四页 + 权限双层
|
||
|
||
现行前端档对 admin 几乎只说了"沿用 Element Plus 默认、品牌色对齐"。但随着内容审核后端落地,admin 侧有一组页面要进**第一期**(跟审核台后端同期建),它们归 game-admin 前端承载:
|
||
|
||
- **审核队列页**:待审内容列表,支持按状态/举报率/积压时长筛选,是运营每天的工作入口。
|
||
- **审核详情页**:单条内容的试玩预览 + 生成轨迹 + 就绪分 + 举报详情,供运营做判断。
|
||
- **审核处置页**:通过 / 拒绝 / 下架 / 加精选 / 限曝光这套决策操作,以及拒绝反馈与重提交流转。
|
||
- **锁风配置页**:内容安全策略(关键词、阈值、风控开关)的配置界面。
|
||
|
||
权限口径定**双层**:前端给这几页的操作入口挂 `v-hasPermi` 权限指令做按钮级显隐,后端再用 `@PreAuthorize` 兜底做真正的访问控制。这一条要和 admin 侧的历史现状对齐看——现存的 wanxiang 页是"零 `v-hasPermi`、全靠后端 `@PreAuthorize` 兜底",原因是前端挂权限点要求 `system_menu` 的权限种子已到位,否则超管以外的角色按钮会全隐。所以审核台这几页挂 `v-hasPermi` 的前提是先把对应的权限点种子配好;种子没到位前,先靠后端兜底这一层守住安全边界,不能因为前端没挂权限点就当成不设防。**前端的权限指令是体验层(让没权限的人看不到按钮),不是安全边界——安全边界永远在后端。**
|
||
|
||
> contract-first(待落地):审核台四页要挂 `v-hasPermi`,前置是 `system_menu` 里这几个审核操作的权限点种子(菜单/按钮权限编码)要先补一批 Flyway 种子数据;锁风配置页若要落配置项,涉及的配置存储与读写接口要先在后端定。这两项都标"待落地",当前 admin 还没有这套审核台页面。
|
||
|
||
### 9.3 admin 观测三入口:近期承载
|
||
|
||
观测体系正式稿(运维域)里定了 admin 要开一个进观测大盘的入口。落到 admin 前端,是三个近期要补的承载点:
|
||
|
||
- **观测大图入口**:在 admin 里挂一个进 Grafana / 夜莺大盘的入口,运营/管理员从后台直接看系统健康与生成指标,而不是各自记一串 Grafana 地址。
|
||
- **SSO 免登**:嵌入的观测大盘要和 admin 的登录态打通,做到免二次登录(涉及 Grafana 的 `X-Frame-Options` 放行与 SSO 对接,这两项是待处理的接入工作)。
|
||
- **告警概览**:在 admin 里给一个告警的概览视图,把当前活跃告警聚合展示,不必跳到夜莺才看得到。
|
||
|
||
这三个归 admin 前端承载,但它们的数据与嵌入方式依赖运维域观测栈先就绪(见 [`../运维/观测体系.md`](../运维/观测体系.md) 的 admin 观测入口那节)。`X-Frame-Options` / SSO 这两个嵌入前置没解决前,这三个入口落不实,所以排"近期"而非"第一期"。
|
||
|
||
### 9.4 C 端 studio 近期承载:钱包页 / 溯源条 / AIGC 标识 / 互动真接
|
||
|
||
C 端这一摊,后端大多已是现行真相,缺的是前端这层面子,逐条钉清归属与时间窗:
|
||
|
||
**创作者收益钱包页(近期)。** 后端钱包链路已经真跑——`game_trade_account`(收益账户,守 `balance + frozen + total_withdraw = total_income` 不变式)、`game_trade_income`(分账入账,区分广告/打赏)、`game_trade_withdraw`(提现,状态机 + 幂等)都在(见 [`../后端/数据模型.md`](../后端/数据模型.md) 的 trade 子图)。前端要补的是创作者看得见的钱包页:查余额、看收益明细(按日/周/月、按广告/素材/商单各渠道分)、发起提现。这是把已经跑通的后端能力接出一个用户入口,避免它成为没有前端的孤儿能力。"满 5 元才能提现"这类预期管理的文案也落在这一页(对应变现侧的提现门槛口径)。
|
||
|
||
**同款溯源条 + 创作者中心同款聚合卡(随数据飞轮阶段一一起落)。** 数据飞轮的溯源链设计(见 [`../架构/生成引擎/数据飞轮.md`](../架构/生成引擎/数据飞轮.md) §3.1)已经把前端这两个出口点写进了阶段一范围:试玩页读 `game_lineage_edge`,有 active 血缘边时展示"改编自 [原作标题] · @[原作者]"的**溯源条**(点击跳回原作,父被删时降级为不可跳转的灰态);原作者在**创作者中心**能看到"我的 [作品] 被 N 人做了同款"的**同款聚合卡**(走去重聚合 API)。这两个展示点是溯源链对用户可见的唯一出口,没有它们血缘就是库里的孤儿数据。它们归前端域承载,跟着数据飞轮阶段一(溯源链 + 同款创作)一起落,不早于、不晚于那条飞轮。
|
||
|
||
**AIGC 显式标识的前端展示(法定 P0,跟渠道线起步落)。** AI 生成内容的显式标识是法定要求(生成式 AI 服务的合规义务),它在前端的承载是把"AI 生成"这个标识展示在内容的每个对外触点——信息流卡片、游戏详情、分享落地页都要带上。这条归前端域,优先级对齐法定 P0,跟渠道线起步一起落(渠道发行场景对 AIGC 标识的合规要求最硬)。
|
||
|
||
**feed 互动按钮真接 community / social(排期真接)。** 现行 feed 的部分互动按钮还是 mock。后端 community / social 模块已建成并接入单体(见 [`../后端/README.md`](../后端/README.md) 的 13 模块现状),`game_feed_interact_log` 已有点赞/收藏/分享/举报四种互动埋点。前端要做的是把 feed 的互动按钮从 mock 真接到 community / social 的真实端点。这条捡回、排期真接,不再让互动停在 mock。
|
||
|
||
> contract-first(待落地):feed 互动按钮真接 community / social,前置是核对 community / social 已暴露的互动端点与 `game_feed_interact_log` 的埋点契约是否齐备(点赞/收藏/分享/举报四种已有,评论/关注若要进 feed 需另核后端端点与契约)。评论(P-SOC-01)、关注当前在 Doc A 标 P1,真接范围以已建端点为准,缺口标"待落地"。
|
||
|
||
### 9.5 青少年模式与分级展示(合规放量前补)
|
||
|
||
青少年模式的内容过滤 + 适龄分级提示展示,归前端域承载,时间窗是**合规放量前**——它不是 v2.0 远期能力,而是正式放量(面向更大用户盘)前必须补上的合规前端。落到前端是两件事:青少年模式下对不适龄内容做过滤(feed/详情不展示),以及适龄分级标识的展示(对应 Doc A 的 `P-ACC-03 适龄分级提示展示`)。这条钉一个清晰的时间锚:**合规放量前必补,别拖到放量之后才想起来。**
|
||
|
||
### 9.6 SDK 与移动端适配:补齐的前端能力
|
||
|
||
**Debug 调试插件补进 SDK 插件库。** 现行 SDK 插件库(运行时手册里的 Ad / Pay / Social / Storage 四插件,见 [`../../../.agents/skills/runtime-and-multichannel.md`](../../../.agents/skills/runtime-and-multichannel.md))漏了一个历史上规划过的 **Debug 插件**。它是开发模式下的调试面板:实时 FPS 曲线、SDK 事件流日志、GameConfig 运行时状态查看、从生成到运行的全链路 `trace_id` 展示、网络请求拦截、一键性能快照。它既是创作者调试自己游戏的工具,也是平台排查生成质量的利器。这条捡回,补进 SDK 插件库,作为一个仅开发模式加载、不进生产首屏的插件。
|
||
|
||
> contract-first(待落地):Debug 插件要进 SDK 插件库,涉及 SDK 契约(`contracts/sdk/`)新增一个 `debug` 插件声明 + GameConfig 里按需声明该插件的开关(仅开发模式加载),宿主据 manifest 决定是否注入该插件 chunk。当前 SDK 契约只声明了 Ad / Pay / Social / Storage 四插件,Debug 标"待落地"。
|
||
|
||
**移动端基本适配集。** 现行前端档把响应式大方向定了(移动沉浸/桌面居中放大),但移动端的几条具体适配约束是空白,捡回补成一个"移动端基本适配集",归前端域:① **安全区适配**——竖屏沉浸式 feed 在真机上必然遇到刘海、底部手势条,要用 `safe-area-inset` 留出安全区;② **软键盘处理**——创作页的一句话输入框、评论输入框在移动端软键盘弹起时会顶布局,要做遮挡处理;③ **横屏游戏在竖屏 feed 的呈现**——按 §9.1 的方向定义处理:竖屏 feed 是容器方向,不是游戏画布限制;横屏游戏要保留正确宽高比,给旋转提示、letterbox 预览或进入横屏沉浸 play 的入口,不能直接挤变形;④ **触觉反馈**——游戏关键节点、互动反馈用 `navigator.vibrate` 做轻量震动,提体感。这四条都是消费级移动 Web 的基本盘,作为一个适配集一并补,file 级细节留实现。
|
||
|
||
### 9.7 B 端 demo 取包:owner-agnostic 取包端点(卡 B 端现金线)
|
||
|
||
这是一条被历史评审标为高风险、卡 B 端现金线命脉的真实契约缺口:运营为客户代建的 biz demo,owner 是运营不是客户,客户走 `preview` 取包会被 owner 校验拦下,走 `play` 又要求游戏已正式发布(`status=1`)——于是客户根本没有一个能取到这个 demo 包的端点,B 端"给客户看 demo"这个闭环不可达。前端域要承载的是这个取包入口,但它依赖后端先补一个 **owner-agnostic 的取包判定端点**(或把 demo 走正式发布流绕开 owner 校验)。这条钉清:**B 端 demo 试玩的取包归前端承载,但前提是后端先把这个取包端点的契约缺口补上,否则前端有入口也取不到包。**
|
||
|
||
> contract-first(待落地):biz demo 的客户试玩取包,前置是 runtime 侧补一个 owner-agnostic 的取包端点(不做 owner 校验、也不要求 `status=1` 的受控取包路径,带 biz demo 的合法性判定),涉及 runtime 模块的 API 契约新增。当前 runtime 只有 `preview`(owner 校验)/ `play`(`status=1`)两条路,owner-agnostic 取包标"待落地"。
|
||
|
||
---
|
||
|
||
## 10. 关键指针
|
||
|
||
需要更深的细节时,回到这些权威源:
|
||
|
||
| 你想找 | 去哪里 |
|
||
|---|---|
|
||
| 逐令牌的权威取值 | `game-studio/src/styles/tokens.css`(token 单一事实源) |
|
||
| 子系统活档(本档的来源) | `docs/architecture/前端/README.md` |
|
||
| 可直接打开的设计稿(含实时中英 + 三主题切换,真 Chrome 验过) | `docs-design/studio-redesign-mockup.html` |
|
||
| 设计基准原型(只取设计语言,不取布局) | `docs-design/huijing-ai-demo.html` |
|
||
| 构建门与真机走查的操作配方 | `.agents/skills/staging-ops.md`(构建真门 = `npm run build` / `vue-tsc -b && vite build`;注意 `vue-tsc --noEmit` 是假门不算数)、`.agents/skills/ui-walkthrough-cdp.md`(CDP 三主题 × 双语走查) |
|
||
| 圆角铁律 | 统一圆角规范(未立独立档,以本档为准) |
|
||
| 落地提交记录(均在 `dev/2.0.0`) | `42342e8c` 卖相批 → `f98ad0f8` token 层 → `ecae9025` i18n 脚手架 → `655673eb` 组件库 → `caa2e1ba` 代表面 → `2c96e63a` 品牌+收尾 |
|
||
|
||
> **纪律**:前端域只讲"两个前端长什么样、靠什么撑起一致体验";产品对用户提供什么记在[产品域](../产品/README.md),系统用什么技术搭起来记在[架构域](../架构/README.md),它们各司其职、互不重复。
|