games-development-ai/docs/architecture/前端/README.md

topic, canonical, date

topic	canonical	date
前端设计体系	true	2026-06-12

前端域 · 设计主文档

这是什么:绘境AI 前端域的设计主文档,回答"两个前端长什么样、靠什么撑起一致的体验"。它聚焦设计体系(design system)这一层——即把颜色、间距、字体、组件、主题、多语言这些"视觉与交互的共同语言"统一沉淀下来,让所有界面看起来像同一个产品。 给谁看:前端工程师、设计师、产品经理、新加入的同事、外部技术尽调。 怎么读:先读本页建立全局认知——我们有哪两个前端、它们各服务谁、设计体系分几层、为什么这么分、创始人定下了哪些不可动摇的硬约束;需要某条具体令牌(token)的取值或某个组件的签名时,再回到代码里的权威源文件(文末有指针)。 读这一页 = 前端设计体系的当前真相。它从子系统活档 docs/architecture/前端/README.md 蒸馏而来,只取其架构骨架与关键决策的"为什么";逐令牌清单、逐组件实现、构建与走查的具体命令不在这里(分别交给代码里的 tokens.css 与 .agents/skills/ 下的操作手册)。

---

1. 绘境AI 有两个前端

绘境AI 把面向不同人群的界面拆成两个独立的前端应用,它们在架构域里都画在"前端应用层",但服务的人和承载的能力截然不同。

game-studio 是产品前端,同时服务创作者和玩家两类终端用户。创作者在这里一句话生成游戏、预览迭代、发布到多个渠道、查看收益;玩家在这里刷"游戏信息流"(类似短视频的竖屏即刷即玩流)、点赞分享评论。它用 Vue3 + Vant 构建——Vant 是一套移动优先的 Vue 组件库,天然适配游戏流的滑动交互。

game-admin 是管理后台前端,服务平台运营和管理员。他们在这里做内容审核、用户管理、数据看板、合规处置等后台工作。它用 Vue3 + Element Plus 构建——Element Plus 是 Huijing(我们 fork 的开源 Java 企业级后台框架)官方主推的桌面端组件库,二次开发友好。

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)。

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 的两层结构(为什么是"两层"见下),另一条是组件库的四层封装,两者在语义层交汇。

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。tier2 已过 0 号 spike(n=1 accept),前端承载可着手:这两件前端落点仍待建,现在先钉归属、详细的逐页 UI 留实现时展开。

---

9. 前端域承载范围:近期待补的前端落点

前面几节讲的是设计体系本身、以及 studio 相对 demo 的能力盘点。但前端域要承载的不止设计体系——有一批能力,后端、契约、运维、架构域都已经把"里子"做出来或定下来了,缺的只是前端这层"面子":页面、入口、按钮、展示。这一节把这些归属在前端域、近期要补的落点钉清楚,按时间窗分组。它只立"该谁承载、什么时候补"这件事,不在这里写逐页 UI 的详细设计——具体到组件与交互的 file 级设计,留给实现时在活代码里落。这一整节都来自创始人 2026-06-22 历史回收判定的捡回,逐条对应历史回收判定(创始人判定)里同名的设计点。

9.1 前端域引用承载:把活在别域的前端约束引一份过来

前端的体验是很多跨域约束的最终执行点,但这些约束的权威定义常常活在架构域、运维域或代码里,前端域却看不到它们。这容易让人误以为"前端没有性能/观测责任",其实前端正是这些指标的兑现处。下面这几条不在前端域重新定义(避免一份事实两处写、口径漂移),只引用一句、点明它们的前端责任,让读前端档的人知道这些线压在前端身上。

体验 SLO 的前端责任。 信息流首屏 P75 < 3 秒、点卡到可玩 S2 常态 ≤ 2 秒(全新设备首次 ≤ 3.5 秒)这套体验承诺,权威定义在架构域(原《引擎与运行时》已并入运行时 SoT agentic运行时架构图说;其中首局可玩 ≤2s 那一档在 验收门 的首局体验门)。它对前端的含义是:首帧绘制、加载态反馈、预热时机这些都是前端的执行点——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。现状标的是"可选、后期",前端域只引这一句、认下这个承载点:前端的页面级性能与错误观测走 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 的 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 的 trade 子图)。前端要补的是创作者看得见的钱包页:查余额、看收益明细(按日/周/月、按广告/素材/商单各渠道分)、发起提现。这是把已经跑通的后端能力接出一个用户入口,避免它成为没有前端的孤儿能力。"满 5 元才能提现"这类预期管理的文案也落在这一页(对应变现侧的提现门槛口径)。

同款溯源条 + 创作者中心同款聚合卡(随数据飞轮阶段一一起落)。 数据飞轮的溯源链设计(见 ../架构/生成引擎/数据飞轮.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 的 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)漏了一个历史上规划过的 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 品牌+收尾

纪律:前端域只讲"两个前端长什么样、靠什么撑起一致体验";产品对用户提供什么记在产品域,系统用什么技术搭起来记在架构域,它们各司其职、互不重复。