Frontend Build

受众：开发者 摘要：前端工程聚合说明：views/ 源码 / spring-open-views/ 构建模块 / public/ 产物 / 截图规范。

本文档说明前端源码目录和 Maven 构建模块的关系。

目录规划

前端源码统一放在根目录 views/，当前和规划中的目录如下：

views/
├── docs/        # VitePress 文档站点
├── install/     # 企业安装 Vue3 单页向导
├── admin/       # 后台管理 Vue3，基于 vue-pure-admin 完整版
├── app/         # 用户端 uni-app，多端覆盖 H5 / 小程序 / App
└── pc/          # PC 电脑端用户视图，Nuxt 4 + Vue 3 + TypeScript

前端构建模块统一放在根目录 spring-open-views/，当前和规划中的模块如下：

spring-open-views/
├── spring-open-view-docs/   # docs 站点 Maven 构建模块
├── spring-open-view-install/ # 安装向导构建模块
├── spring-open-view-app/    # uni-app 移动端 H5 构建模块
├── spring-open-view-admin/  # 后台管理界面构建模块
└── spring-open-view-pc/     # Nuxt PC 用户端构建模块

views/ 放源码，spring-open-views/ 放 Maven 构建入口。这样早期可以前后端同仓库一键打包，后期项目变大时，也可以把任意前端工程独立拆出去。

设计原则

• 根目录不放 package.json，避免把 Java 多模块项目变成 Node 工程。
• 每个前端工程自己维护 package.json、pnpm-lock.yaml 和构建脚本。
• 每个前端工程对应一个 spring-open-view-* Maven 构建模块。
• view 模块只负责构建和复制静态产物，不提供 Java 代码，不作为业务依赖引入。
• spring-open-application 不依赖 view 模块，保持应用装配入口清爽。
• 构建产物不提交 Git。

Admin 前端的后台管理请求对外统一使用 /api/v1/admin/{domain}/**。API wrapper 必须直接声明真实 owning domain 前缀，不再依赖请求拦截器把旧后台路径规范化；鉴权、安装向导、公开站点信息和开放平台公开入口仍按各自公开路由调用。

响应式单位

页面样式优先使用响应式单位处理布局、间距、宽高、栅格、卡片、底部导航、安全区和按钮容器，避免大量固定 px 让移动端页面在不同设备上变形。

移动端新代码优先使用 rpx。upx 作为 uni-app 旧写法或兼容代码可以保留，但新页面不主动扩大 upx 使用面。H5、PC 和后台管理端的响应式布局可以组合使用 vw、vh、百分比、rem、CSS 变量和 clamp()。

字体大小、密集表格和复杂后台表单不要机械使用视口单位；优先走项目设计 token 或组件库变量，并保证长中文、英文单词和按钮文字不会溢出或重叠。移动端固定底部导航和悬浮按钮必须配合安全区、底部 padding 或等效布局处理，不要只靠截图裁切掩盖真实遮挡。

工具链基线

前端工具链在仓库内统一约束，避免本机 Node / pnpm 版本漂移导致 Admin、App、PC 或 Docs 构建结果不一致。

工具	要求	生效位置
Node.js	v24.16.0	views/.nvmrc、views/.node-version、views/.tool-versions、spring-open-views/pom.xml
pnpm	>=11	views/.npmrc、各视图 .npmrc / engines.pnpm / devEngines.packageManager

本机直接执行前端命令前，先进入 views/ 或具体视图目录，再切到项目 Node 版本：

cd views
nvm use
corepack enable
corepack prepare pnpm@latest --activate

Maven 构建不依赖当前 shell 的 Node 版本。spring-open-views/pom.xml 会统一指定 Node.js v24.16.0，并给 Maven 插件提供 pnpm 默认下载版本 11.0.0；所有 spring-open-view-* 子模块都从父 POM 继承同一套配置。不要在子模块里再单独维护 Node / pnpm 版本，避免 Admin、App、PC、Docs 和 Install 之间再次分裂。

views/.npmrc 和各视图 .npmrc 已开启 engine-strict=true 和 package-manager-strict=true。本机直接在视图目录运行 pnpm install、pnpm build、pnpm typecheck 时，如果 Node.js 不符合项目基线，或 pnpm 低于 11，会在安装阶段尽早失败。

如果本机仍使用 Node.js 20.11.x 或其他旧版本直接执行 pnpm build，Nuxt、Vite 或 Corepack 可能因为缺少新的 Node API 而失败；这属于本机工具链不符合项目基线，不应按业务代码问题处理。

每个视图子项目独立维护自己的 package.json、pnpm-lock.yaml 和 devDependencies。截图、页面 smoke、相对路径检查、静态导出验证等常用开发工具应放在对应视图目录的 devDependencies 中，不放到项目根目录，也不要求开发者全局安装。当前 views/admin、views/app、views/pc、views/install、views/docs 都声明了 playwright，用于后续页面截图和交互验证脚本稳定运行。

当前 Docs

正式 Markdown 文档当前只维护简体中文。当前中文文档放在：

docs/zh-CN

docs/index.md 继续作为语言入口。繁体中文和英文目录只保留首页占位：

docs/zh-TW/index.md
docs/en-US/index.md

V1.0 发布以后，再评估是否按中文目录结构补齐繁体中文和英文文档。V1.0 之前不要提前创建大量空页面，避免开发者误以为对应语言文档已经进入维护期。

VitePress 工程放在：

views/docs

Maven 构建模块放在：

spring-open-views/spring-open-view-docs

构建产物导出到：

public/docs

public/.gitignore 会忽略 docs/ 目录，实际 HTML、JS、CSS 不进入 Git。这样 public/docs/ 可以直接删除，下次构建会重新生成。

Docs 站点使用 VitePress 默认客户端增强模式构建，保留搜索、明暗外观切换等交互能力。导出时会按 HTML 页面所在层级重写资源与站内链接：根页面引用 ./assets/...，二级页面引用 ../assets/...，不会写死 /docs/assets/...、/help/assets/... 或 /assets/... 这类根路径绝对地址。

为了同时支持任意子路径部署和 VitePress 客户端交互，导出脚本会在 HTML 中注入运行时 base 识别逻辑，并保留 VitePress 需要的 hashmap.json。这样构建产物可以在部署时挂载到任意路径，例如 /docs/、/help/、/manual/，不需要重新构建。

文档根入口会直接进入 zh-CN 目录，并保留 query string 与 hash。V1.0 之前不按浏览器语言跳转到繁体中文或英文目录。

导出脚本还会在浏览器端规范化中文目录链接。比如从 /docs/ 进入 /docs/zh-CN/ 后，导航仍会指向当前部署目录下的 /docs/zh-CN/conventions.html，不会因为 VitePress 客户端路由复用根页面链接而叠加成 /docs/zh-CN/zh-CN/conventions.html。

线上部署优先于本地直接打开 HTML。hashmap.json 是 VitePress 客户端路由元数据，不属于 Node 工程污染文件，不要在导出阶段删除。

Docs 多语言规划

当前 docs 站点只维护简体中文。简体中文内容默认放在：

docs/zh-CN

繁体中文和英文目录只保留首页占位：

docs/zh-TW/index.md
docs/en-US/index.md

V1.0 发布以后，再评估是否逐步补齐繁体中文和英文功能文档。规划原则：

• 简体中文文档放在 docs/zh-CN/。
• docs/zh-TW/ 和 docs/en-US/ 只保留 index.md 占位，不放正式功能文档。
• docs/index.md 只做简体中文文档入口，不承载具体功能文档。
• 新增功能只更新简体中文文档；繁体中文和英文文档进入维护期后，再同步翻译稳定内容。

Pagefind 搜索当前只维护简体中文界面文案：简体中文页面显示“搜索 / 搜索文档”。繁体中文和英文文档进入维护期后，再恢复对应搜索文案和多语言索引策略。

当前 docs 已内置：

能力	用途
Pagefind	本地全文搜索，适合无外部 Algolia 的私有部署
Group Icons	代码组自动显示 npm、pnpm、Maven、Docker 等图标
Mermaid	Markdown 中直接书写架构图和流程图

当前 Install

企业安装视图源码放在：

views/install

Maven 构建模块放在：

spring-open-views/spring-open-view-install

构建产物导出到：

public/install

第一阶段安装视图使用 Vue 3 + TypeScript + Vite，页面只接入安装状态、安装令牌校验和基础环境预检。后续数据库、Redis、Storage、站点配置、管理员创建和安装执行会继续在同一视图内扩展。

只构建安装视图：

./mvnw -pl spring-open-views/spring-open-view-install package -DskipTests -DskipITs -Dbuild.skip.views=false

安装视图由主分支维护，和 Admin / App / PC 一样在 main 内按视图目录收口。

HTML 页面会写入禁用缓存 meta；生产 Nginx 也建议对文档目录增加 no-cache 响应头，并使用 location ^~ /docs/ 这类前缀优先规则，避免全站 JS/CSS 缓存规则覆盖文档资产。否则浏览器可能继续加载旧的 VitePress 客户端 JS，导致搜索、移动端菜单或外观切换看起来“回到旧版本”。

示例：

pnpm

cd views/docs
pnpm docs:export

Maven

./mvnw -pl spring-open-views/spring-open-view-docs package -DskipTests -DskipITs -Dbuild.skip.views=false

Public 静态资源

public/ 是站点静态资源根目录。后续 Nginx 或其他 Web Server 直接以 public/ 作为网站根目录时，根目录下的资源会按原路径访问。

后端代理模式下，View starter 会为 admin、app、pc 三个 SPA 目录提供深层路由兜底：浏览器直接访问 /admin/iam/users、/app/pages/home/index 或 /pc/user/profile 这类无扩展名路径时，会回退到对应端的 index.html；带扩展名的静态资源路径仍按真实文件处理，不会被兜底页面吞掉。

当前默认提供：

文件	尺寸	用途
public/favicon.ico	128x128	浏览器 favicon
public/apple-touch-icon.png	180x180	iOS 添加到主屏幕图标
public/site.webmanifest	JSON	PWA 图标和主题色元数据
public/images/logo/logo.svg	紧凑 viewBox	可编辑矢量源稿，保留用于设计维护，不作为默认运行时引用
public/images/logo/logo.png	512x512	前端和文档站默认 PNG logo
public/images/logo/logo-192.png	192x192	PWA / App 小图标
public/images/logo/logo-512.png	512x512	PWA / App 高清图标
public/images/logo/logo-1024.png	1024x1024	App Store / 高分辨率品牌图标

默认品牌标识采用原创几何线框方向。整体气质参考 Laravel 的简洁几何感，配色对齐 Spring 官方 favicon 的 #77BC1F 和 #FFFFFF，不使用渐变色，便于 favicon、PWA 图标、文档站和站点品牌统一使用。主 logo 通过紧凑 viewBox 减少多余透明空白，保留少量视觉留白，不做非等比拉伸。SVG 和 PNG 均使用透明背景，PNG 只保留品牌绿和白色，避免位图边缘出现偏色。后续替换品牌资源时，优先保持同一套图形语义和配色系统。

VitePress 文档站顶部左上角使用 public/images/logo/logo.png。构建时会复制到 docs 站点产物内的 images/logo/logo.png，并由导出脚本按页面层级改写为相对路径，避免部署到 /docs/、/manual/docs/ 等任意目录时出现静态资源路径失效。

品牌色参考：

参考	预览	链接
Spring 项目图标		https://spring.io/img/projects/spring.svg

当前主色以 Spring 官方品牌绿色为准。

站点约定文件，例如 favicon、apple touch icon 和 manifest，保留在 public/ 根目录。Logo 资源统一放在 public/images/logo/，其他运行时公共图片统一放在 public/images/ 下并按场景细分，例如 icons、banners、illustrations。前端页面截图属于正式文档源资源，不放在 public/images/。

站点信息接口

前端视图需要展示站点名称、标题、描述、关键词、Logo、备案、联系方式、版权信息和实时连接入口时，统一读取：

GET /api/v1/site

返回值来自 spring.open.site.*，并支持数据库配置覆盖。本地默认配置放在 application.yml，后台管理界面可通过配置元数据生成表单维护这些字段。url 显式配置时优先使用；为空且 auto-detect-url=true 时，接口会根据当前 HTTP 请求自动推断站点地址。

接口会同时返回 websocketEndpoint、websocketUrl、websocketTokenParameter 和 websocketDeviceParameter。三端实时连接优先使用这些字段，不要在源码里写死 ws://localhost:8080/api/ws。部署到 Nginx、Docker、子路径或 HTTPS 后，websocketUrl 会按站点地址推导为 ws:// 或 wss://；如果站点 URL 为空，前端可用 websocketEndpoint 基于当前 location.origin 自行拼接。

接口会同时返回站点访问策略字段：accessStatus、accessMessage、accessResumeAt、accessRestricted、allowAdminAccess、allowApiDocs，并保留嵌套 access 对象。accessStatus=closed 表示站点关闭，accessStatus=maintenance 表示维护升级；两种状态都使用同一个 accessMessage 作为用户可见说明，管理员未配置说明时前端不展示正文。

App 和 PC 发现 accessRestricted=true 后展示站点状态页，并保留重新检查入口；状态页需要允许展示后台配置的关闭 / 维护说明和预计恢复时间。Admin 后台默认仍可登录并进入配置中心，页面只做维护 / 关闭提示，不要把该状态暴露给普通用户端的登录会话或业务页面。

接口会返回 supportedLocales 作为当前站点允许切换的语言列表，默认包含 zh-CN、zh-TW 和 en-US。前端语言选择器必须优先使用该列表渲染，不再在页面里固定写死两种语言；后台后续只需要维护站点配置中的支持语言，App / PC / Admin 就能同步收敛语言入口。

接口会同时返回 defaultCountry、defaultCurrency、defaultTimeZone 和 supportedCurrencies。前端首次进入时可以用这些字段初始化国家 / 地区、默认展示法币、时区和货币选择列表；用户主动选择后，再通过当前用户偏好接口保存，并在后续请求中按需传 X-Country、X-Currency、X-Time-Zone。这些字段只用于展示默认值，不作为 KYC、税务、支付准入或资金合规依据。

Admin 后台管理端、App 移动端和 PC 电脑端都必须优先使用该接口渲染站点名称、浏览器标题、描述、关键词、Logo、favicon、备案、联系方式、协议链接、版权信息和 WebSocket 连接入口。接口不可用时可以保留本地默认值作为兜底，但业务页面不要把站点名称、备案、联系方式、版权文案或实时连接地址写死在源码里；Logo 和 favicon 默认引用 public/ 下的公开资源路径。

站点名称、短名称、标题、描述、关键词、联系地址、版权主体和版权文案属于动态业务元数据。接口会按当前 Accept-Language / locale 解析这些用户可见字段：配置值可以是 {messages.xxx} / messages.xxx 这类显式 key，也可以直接使用原文；如果数据库 i18n 文案存在对应翻译，接口返回翻译后的值，未配置翻译时返回原文。URL、Logo、favicon、备案号、邮箱和电话等结构化字段保持原值，不做翻译。

Install 安装视图属于安装完成前的特殊入口。安装前还没有稳定站点配置时，可以使用安装表单和本地默认值；安装完成后，常规产品入口继续以站点信息接口为准。

Logo 文件命名规则：

• logo.svg 是唯一矢量源稿；文件不写固定宽高，调整视觉大小时只允许等比缩放或调整 viewBox，不做横向或纵向拉伸。该源文件必须保留，但默认运行时引用使用 PNG。
• logo.png 是稳定的前端 PNG 引用入口，Admin / App / PC / 文档站默认使用它。
• logo-{size}.png 只表示明确像素尺寸，例如 logo-192.png、logo-512.png、logo-1024.png。
• 不再使用 logo-dark、logo-og 或带项目品牌前缀的 logo 文件命名；深色背景适配优先通过页面背景和 SVG/PNG 本身透明底处理。

不要把长期公共图片放到 public/assets/ 这类后续可能被前端构建产物整体替换的目录。

用户端后端接口缺口状态

当前主分支已补齐一批三端视图联调需要的低风险接口：

场景	接口 / 能力	状态
跨设备主题色	当前用户偏好新增 themeColor	已完成
普通用户附件	/api/v1/file/users/me/records 当前用户文件分页、详情、上传和删除	已完成
Blog 封面	使用当前用户附件接口，建议 businessType=blog-cover、directory=content	已完成
Blog 草稿详情	GET /api/v1/blog/me/articles/{id}	已完成
Blog 审核原因	GET /api/v1/blog/me/articles/{id}/moderation-records	已完成
Blog 跨设备冲突	第一阶段以前端对比 updatedAt 为准	已完成基础 contract

仍需主分支继续补齐：

• Forum liked、favorited、reported、reportStatus 等互动状态稳定 contract、版规校验和通知联动。
• 统一搜索聚合、热词、纠错、排序和搜索统计。
• Mall 支付回跳参数、售后附件文件化、退款 / 退货状态和通知联动。

打包

只构建 docs 站点：

./mvnw -pl spring-open-views/spring-open-view-docs package -DskipTests -DskipITs -Dbuild.skip.views=false

该命令会执行 docs Maven 构建模块，并显式追加 -Dbuild.skip.views=false，用于确保本次打包一定构建 docs 站点，即使后续 docs 模块默认值被调整也不会失效。IDEA 中可以直接展开 spring-open-views/spring-open-view-docs，双击生命周期里的 package 或 install。

也可以直接执行 Maven 构建全部模块：

./mvnw package -DskipTests

spring-open-views 聚合模块默认：

<build.skip.views>false</build.skip.views>

因此根项目执行 package 时，会自动执行 docs、app、admin、pc 四个前端 view 模块，并分别导出到 public/docs、public/app、public/admin 和 public/pc。

IDEA 中直接打开 Maven 面板，双击根项目 spring-open 的 package 即可。

视图聚合打包

如果只想打包前端视图，可以直接运行 spring-open-views 聚合模块：

./mvnw -f spring-open-views/pom.xml package -DskipTests

IDEA 中也可以直接在 Maven 面板展开 spring-open-views，双击生命周期里的 package 或 install，默认会打包全部视图模块。

如果只想打包单个视图，在 IDEA Maven 面板直接展开对应子模块并双击它自己的 package 或 install 即可，例如 spring-open-view-pc 只会打包 PC 端。

命令行也可以直接指定单个 view 模块：

./mvnw -pl spring-open-views/spring-open-view-admin package -DskipTests
./mvnw -pl spring-open-views/spring-open-view-app package -DskipTests
./mvnw -pl spring-open-views/spring-open-view-pc package -DskipTests
./mvnw -pl spring-open-views/spring-open-view-docs package -DskipTests
./mvnw -pl spring-open-views/spring-open-view-install package -DskipTests

这种方式不需要额外 -Dview 选择参数，Maven 模块本身就是选择器。

跳过前端构建

如果只想快速编译 Java，不想构建前端视图：

./mvnw package -Dbuild.skip.views=true -DskipTests

相关 property：

Property	默认值	说明
build.skip.views	false	是否跳过所有前端视图构建
view.node.version	v24.16.0	所有前端视图构建使用的 Node.js 版本
view.pnpm.version	11.0.0	Maven 视图构建默认下载的 pnpm 版本；本机直接执行前端命令只要求 pnpm >=11

build.skip.views 是唯一的视图构建总开关，由 spring-open-views 聚合 POM 统一给出默认值；所有视图自己的 Node.js / pnpm 版本统一继承 spring-open-views/pom.xml，子模块不再单独维护工具链版本。

新增视图模块直接消费 build.skip.views 总开关；是否单独打包某个视图由 Maven 子模块选择决定。

本地预览

cd views/docs
pnpm install
pnpm docs:dev

页面截图与页面清单规范

完成一个完整页面后，需要在正式前端文档中补充页面截图和页面清单，方便开发者和产品侧快速了解当前已有页面、页面效果和后续优化点。

完整页面包括可访问路由页面、主要业务列表页、详情页、表单页、用户中心子页、后台管理功能页、App tab 页面等。PC / Admin 页面优先提供桌面全屏截图；App / uni-app 页面优先提供移动端全屏截图；响应式差异明显时，同时补桌面和移动端截图。

截图文件放入 docs/zh-CN/assets/frontend/<view>/，文件名使用端类型 + 页面语义命名，例如 admin-user-list.png、pc-mall-cart.png、app-login.png。截图必须在对应前端文档中引用，不能只提交图片文件。页面预览文档应在文件级说明所属端；每个页面条目至少包含页面名称、路由路径、当前完成状态、截图、需要主分支补齐的后端/API 事项和后续可优化点。页面后续明显改版时，应同步更新截图，避免文档展示旧 UI。

全屏截图要求覆盖完整浏览器 / 设备视口，不截局部组件、弹窗外框、单张卡片或裁剪后的局部区域；页面可滚动时优先使用 Playwright fullPage 或等效方式生成全页长图。既有非全屏截图在对应视图分支继续开发或模块闭环收口时必须重新截取，并用新的全屏截图替换旧图。

移动端页面采用“双图方案”：*-screen.png 保留真实手机视口、底部导航和悬浮操作，用于展示用户实际看到的首屏；*-full.png 用于页面清单和长图阅读，优先采用 Playwright 滚动分段截图 + sharp 拼接，按内容可见区域逐段截图并裁掉重复固定层，比浏览器一次性 fullPage 更自然。

截图脚本可以临时隐藏或从拼接区域裁掉底部 tabbar、悬浮客服、悬浮购物车等会遮挡正文的固定元素。隐藏固定元素只允许发生在截图环境中，不能修改产品源码；如果真实页面内容被底部导航遮挡，应修复 safe area、底部 padding 或滚动容器布局。不优先引入无人维护的一键长截图包，html2canvas 这类 DOM 渲染方案只作为浏览器原生截图不可用时的备选。

页面文档可以优先展示真实首屏图，再补无遮挡长图；页面清单只放一张图时优先放不遮挡正文的 *-full.png。既有旧命名截图可在页面改版或截图收口时逐步迁移，不要求一次性重命名全部历史图片。

文档站正文图片默认支持点击放大查看，页面清单里的缩略图不需要额外提供大图链接；如果某张图片需要保留原始点击行为，可在图片上添加 no-zoom class 或放入链接中。

三端页面预览文档统一使用纵向页面条目展示，桌面和手机都不依赖多列表格或横向拖拽阅读。

三端截图源目录统一如下，public/docs/** 是文档构建产物，不作为源文件维护。

端	截图源目录	Markdown 引用示例
Admin	docs/zh-CN/assets/frontend/admin/	./assets/frontend/admin/admin-account-management.png
App	docs/zh-CN/assets/frontend/app/	./assets/frontend/app/app-home.png
PC	docs/zh-CN/assets/frontend/pc/	./assets/frontend/pc/pc-home.png

三端页面预览入口统一放在文档首页，避免在工程说明页和导航中重复出现入口。

后续前端模块

后续新增前端工程时，保持同样模式：

源码目录	构建模块	产物建议
views/install	spring-open-view-install	public/install
views/admin	spring-open-view-admin	public/admin
views/app	spring-open-view-app	H5 导出到 public/app，小程序/App 按 uni-app 平台目录输出
views/pc	spring-open-view-pc	public/pc，产物可整体复制到任意 Nginx 站点目录

默认不要把这些前端模块引入 spring-open-application。它们属于构建模块，不属于 Java 运行时依赖。

前端视图优先级：

1. views/docs：当前已完成文档站点。
2. views/install：安装向导，V1.0 前必须完成；工程骨架和 Maven 构建模块已完成。
3. views/admin：后台管理界面，V0.7 核心；工程骨架和 Maven 构建模块已完成。
4. views/app：用户端 uni-app 多端应用，V0.7 核心。
5. views/pc：PC 电脑端用户视图，采用 Nuxt 4 + Vue 3 + TypeScript，面向普通用户、访客和会员。

拆分方式

如果后续要把文档站点独立出去，只需要：

1. 删除 spring-open-views/spring-open-view-docs。
2. 删除 spring-open-views/pom.xml 中的 <module>spring-open-view-docs</module>。
3. 按需迁移或删除 views/docs。
4. 按需保留或删除 public/docs。

如果整个前端构建聚合都要移除，再删除根 POM 中的：

<module>spring-open-views</module>

其他 Java starter、业务模块和 spring-open-application 不受影响。