前端-01：工程结构与核心依赖

版本：v4
更新日期：2026-05-13
目标读者：前端 / 架构 / 产品
阅读时间：20-35 分钟
边界说明：这里只讲前端信息架构、路由组织、目录边界和前端状态分层；本文件描述目标前端形态，不代表当前代码都已实现。编辑器交互看 前端-02，元引擎看 前端-03，精确接口看 后端-05。

1. 技术栈与核心依赖

这里只列“类别与职责”，不在设计文档里维护依赖版本号。

1.1 核心框架

应用框架：Next.js(前端框架) App Router / React(前端库) / TypeScript(类型脚本语言)
样式：Tailwind CSS(样式框架)

1.2 关键依赖（按职责）

富文本编辑：Tiptap(富文本编辑器)，基于 ProseMirror(富文本底层库)，用于文本块(Block)级编辑、标注和候选合并。
服务器状态：TanStack Query(查询缓存库)，用于缓存、变更请求(mutation)、重试和失效刷新。
客户端状态：Zustand(状态库)，用于当前工作区 UI 状态、候选卡流选择态、编辑器局部状态和抽屉状态。
表单：React Hook Form(表单库)，用于作品规划、管理员配置和动态字段输入。
校验：Zod(校验库)，用于前端即时校验；最终权限、并发和跨字段事实校验仍由后端负责。
认证授权：前端只消费 Sa-Token 后端适配后的登录态、角色和权限摘要，不直接接触 Sa-Token 内部会话实现。

2. 前端信息架构

前端目标形态必须按角色边界拆成三个产品空间，不能把管理员页面和普通用户作品工作台混在同一组导航里。

信息架构区域	使用角色	默认入口	前端负责什么	禁止混入什么
管理员控制台(Admin Console)	管理员(Admin)	管理后台首页	系统能力、元数据、智能体、指令模板、全局知识库、访问策略、用户、审计、质量评估的配置界面	单个作品正文写作、候选确认、作品知识取舍
用户工作区(User Workspace)	普通用户(User)	我的作品(My Works)	我的作品、单作品作品工作台、写作台、作品规划台、知识与一致性、导入解析、导出交付、记录与用量	系统 Prompt、Agent、Pipeline、底层 MetaSchema 配置和管理员日志
个人中心(Personal Center)	普通用户(User)	个人资料或用量页	个人资料、偏好、令牌(Token)使用、配额、套餐和生成记录总览	单作品深层创作决策和管理员配置

普通用户登录后的默认入口是我的作品(My Works)，不是作品工作台(Work Workspace)。用户只有打开某个作品后，才进入该作品的作品工作台；作品工作台默认落在写作台(Writing Desk)。

3. 路由与目录建议

路由建议按角色和产品空间组织。这里给出前端边界建议，不定义后端接口。

app/
  (auth)/
    login/
  (admin)/
    admin/
      page.tsx
      metadata/
      agents/
      prompts/
      global-knowledge/
      users/
      audit/
      evaluation/
  (user)/
    works/
      page.tsx
      [workId]/
        writing/
        planning/
        knowledge/
        import/
        export/
        usage/
    profile/
      page.tsx
      usage/
      preferences/

components/
  admin/
  workspace/
    my-works/
    writing-desk/
    planning-desk/
    knowledge/
    import-parse/
    export-delivery/
    usage/
  personal-center/
  editor/
  meta/
    admin-config/
    planning/
  common/

lib/
  api/
  queries/
  mutations/
  store/
  auth/
  permissions/
  types/

目录约束：

app/(admin) 和 components/admin 只承载管理员控制台(Admin Console)界面；普通用户作品流程不能依赖管理员页面组件。
app/(auth)/login 承载登录页；登录成功后按 /auth/me 返回的角色和默认入口跳转。
app/(user)/works/page.tsx 只承载我的作品(My Works)：列表、搜索、筛选、排序、新建、打开和继续写作入口。
app/(user)/works/[workId]/* 才承载单个作品工作台(Work Workspace)深层流程，例如写作台、作品规划台、知识与一致性、导入解析、导出交付、记录与用量。
app/(user)/profile 承载个人中心(Personal Center)，不承载单作品编辑、规划或知识确认。
components/meta/admin-config 可以显示 MetaSchema、domain + scope + targetType 等管理员语言；components/meta/planning 面向普通用户，只展示作品设定、章节大纲、世界设定、角色关系、文风检查等创作语言。

4. 前端状态分层

前端状态按来源和生命周期分层，避免把正式事实、待确认内容、历史记录和临时 UI 状态混进一个 store。

状态类型	建议拥有者	内容示例	约束
服务器状态	TanStack Query(查询缓存库)	作品、章节、文本块、已确认设定、用户可见投影、生成历史、用量记录	只能通过接口刷新和变更；不能在本地伪造成正式事实
当前工作区 UI 状态	Zustand(状态库)	当前作品工作区、右侧面板打开状态、当前候选卡、冲突解决弹窗、生成历史抽屉	只影响界面，不成为事实源
编辑器局部状态	编辑器实例 + 局部 store	当前文本块选择、光标、临时输入、标注高亮	写入正文必须经过修订号(revision)和后端确认
表单状态	React Hook Form(表单库)	管理员配置表单、普通用户作品规划表单、导出配置	提交前可即时校验；最终事实校验在后端
待确认内容视图状态	Query + 局部 UI 状态	AI 候选、待确认知识、解析章节待确认结果	用户界面使用创作语言；不能把 Shadow / Proposal / Canonical 做成普通用户默认导航

正式事实来自规范数据(Canonical)，待确认内容来自待审层(Shadow)，历史记录来自归档层(Archive)。这些底层概念可以在前端代码和调试视图中存在，但普通用户默认界面应显示为“AI 候选 / 待确认知识 / 已确认设定 / 历史记录”。

5. 权限与导航边界

前端需要维护登录状态、刷新状态和当前用户摘要，但只把后端返回的角色/权限用于菜单展示、路由跳转和体验提示。
管理员控制台(Admin Console)必须由权限和路由守卫保护；普通用户不能通过 URL 直接进入管理员配置页。
用户工作区(User Workspace)中的作品路由必须校验当前用户对作品的访问权限。
普通用户在我的作品(My Works)点击“导入”或“导出”时，前端语义应跳转到某个作品的导入解析或导出交付流程，不在列表页展开完整深层操作。
管理员配置影响普通用户生成链路时，普通用户界面只展示可理解的能力变化、失败原因或不可用提示，不暴露系统配置对象本身。
前端隐藏按钮、菜单或页面入口不是安全边界；后端 Sa-Token 鉴权和 Muse 业务权限必须同时生效。
普通用户工作区与管理员控制台必须保持分离路由；不能用同一套后台 layout 切换权限来承载全部产品空间。

6. 关联阅读

产品边界：产品-02-核心功能与交互边界.md
普通用户操作流程：流程-01B-普通用户操作流程(操作视角).md
系统边界：架构-01-系统全貌与边界上下文.md
编辑器与作品写作台：前端-02-编辑器与影子层交互.md
元引擎与动态表单：前端-03-元引擎与动态表单.md

7.5 KiB Raw Blame History Unescape Escape