快速开始

选择一条路径即可：先看前端模板，不需要后端；体验真实管理操作，则同时运行管理后端和 Nuxt UI 应用。 不需要先运行 OpenSpec、生成一套 Schema 或阅读全部架构文档。

路径	需要什么	运行后得到什么
体验前端模板	仓库源码、Node、模板指定的 pnpm	布局、导航与明确使用演示数据的页面
运行前后端管理应用	以上环境，加 PowerShell 7、.NET SDK、PostgreSQL 及已构建公共包	真实登录、权限配置与数据库数据操作

本文面向仓库源码采用。仓库外包消费见升级与兼容；不要把本地候选当作 registry 版本。

准备开发环境

先获取与你采用版本一致的 YoyoBoot 源码。以下命令默认在仓库根目录执行；进入子目录后会明确说明。

工具	版本依据
Node	Starter 的 UPSTREAM.md 记录本地基线为 24.20.0；这是采用记录，不是对任意其他版本的支持承诺
pnpm	在目标目录读取 package.json 的 packageManager；Starter 与新宿主当前为 pnpm@12.6.0，不要把它强制用于仓库所有包
.NET SDK	仓库根 global.json；当前指定 10.0.401 并允许同范围补丁选择
PowerShell	后端运行脚本使用 PowerShell 7（pwsh）
PostgreSQL	按后端 README 和本地配置准备；当前迁移兼容下限为 14.5，不以 SQLite 替代运行数据库

node --version
pnpm --version
# 只有运行后端时才需要下面两个命令
dotnet --version
pwsh --version

各目录可能采用不同 pnpm 版本。进入目标目录后由既有工具管理方式使用 manifest 指定版本；不要为了启动示例批量改 packageManager、lockfile 或全仓依赖。

体验前端模板

安装并运行

pnpm --dir packages/ui-patterns build
Set-Location templates/admin-nuxtui-starter
pnpm install --frozen-lockfile
pnpm dev

打开 Vite 在终端实际输出的地址。模板没有固定生产端口，也不需要管理后端、数据库或真实账号。当前 manifest 还通过 file:../../packages/ui-patterns 引用本地包；安装前在仓库根执行 pnpm --dir packages/ui-patterns build。全新 checkout 应先按该包 README 安装其依赖。

你可以浏览首页、客户列表、设置等演示，体验布局与控件组合。演示数据由各 Feature / Lab 的 fixture 或 session 持有；示例按钮和表单不是 ABP 认证或服务端持久化的证明。

在另一个终端、同一模板目录检查本地修改：

pnpm typecheck
pnpm lint
pnpm build

用它创建自己的前端

当前模板依赖本地 @yoyoboot/ui-patterns，直接复制到仓库外不能安装这个相对路径。先按该包 README 准备匹配制品并更新消费者依赖，再复制模板到自己的项目目录，排除 node_modules、dist 和工具缓存，保留 LICENSE、UPSTREAM.md 及锁文件。应用不在运行时 import 模板源码；接入真实服务后移除对应演示数据，不能请求失败就回退演示结果。

只需要在仓库内查看模板时，到这里就完成了。后续采用与目录边界见 Nuxt UI 起点与真实宿主。

运行前后端管理应用

仓库依赖与独立采用

当前 Host 通过 file: 引用 admin-core 和 ui-patterns，不再依赖旧 runtime tarball。全新 checkout 先安装并构建这两个包；仓库外采用必须准备匹配制品并替换相对依赖，不能把本地构建当作已公开发布。

1. 准备公共包与本地配置

按各目录 manifest 指定的 pnpm 安装，不批量改全仓版本。从仓库根执行：

pnpm --dir packages/yoyo-admin install --frozen-lockfile
pnpm --dir packages/yoyo-admin/admin-core build
pnpm --dir packages/ui-patterns install --frozen-lockfile
pnpm --dir packages/ui-patterns build
pnpm --dir apps/yoyo-admin/admin-nuxtui install --frozen-lockfile

包职责与独立采用限制见 Nuxt UI 起点与真实宿主。没有匹配制品时，不猜 registry 版本，不借用过期候选。

按 apps/yoyo-admin/aspnet-core/README.md 与仓库本地开发说明配置 PostgreSQL 连接。产品运行地址由 apps/yoyo-admin/.env.<profile> 管理；凭据只放本地配置或环境变量，不写进模板、文档或提交。

首次完整启动会恢复/构建后端并执行适用的数据库准备。确认指向自己的开发数据库，不能把以下命令直接用于生产或不明来源的连接。

2. 用统一入口启动

从仓库根目录执行：

apps\yoyo-admin\Run-FullStack.bat -DryRun
apps\yoyo-admin\Run-FullStack.bat -Full

先看 DryRun 计划，确认 profile、端口和数据库，再完整启动。当前默认前端是 admin-nuxtui；-WithE2E 才额外启动旧 admin-vue 的 Mock，不是普通采用步骤。环境或 readiness 检查失败时按提示修复。

后端已经按当前源码准备且无需恢复/构建/迁移时，可改用：

apps\yoyo-admin\Run-FullStack.bat -Reuse

-Reuse 只复用现有服务，不能让旧进程自动加载新的后端代码。后端合同或实现变化后，应按脚本约定重新准备并启动，不拿旧进程验证新代码。

3. 打开启动器给出的地址

打开当前 profile 的 Web 地址。启动器显式传入前端端口和 API 地址，默认 development 的 Web 为 http://127.0.0.1:6610；不要用单独执行 Vite 的默认端口推定整个应用地址。参数和状态查询见仓库 apps/yoyo-admin/scripts/README.md。

4. 登录并完成一次真实操作

使用本地环境实际存在的账号登录。Host 登录留空租户名称；租户账号填写其真实租户名。没有账号或密码不一致时，查当前种子配置和本地初始化结果，不猜密码、不擅自重置，也不将凭据提交到文档。

当前新宿主的普通账号密码路径不代表所有额外认证分支都已接入。出现额外认证要求时按真实提示处理，不绕过后端要求。

登录后按账号实际权限打开“用户管理”，查询并编辑允许修改的测试用户，保存后重新读取；源码位于 apps/yoyo-admin/admin-nuxtui/src/app/identity/users/。要查看较小的全栈范例，可按计量单位名称编辑操作；源码位于 src/app/basic-data/measurement-units/。使用已有测试数据，不把示例保存当作生产验收。

测试库没有可用记录时，由有权限的管理员使用现有创建能力准备测试数据；不为了让新页面看起来可用而植入假记录。

5. 停止你启动的服务

FullStack 启动的服务按当前 profile 使用：

pwsh -File apps/yoyo-admin/scripts/Stop-FullStack.ps1

先确认停止范围，不按猜测批量终止其他项目的进程。状态检查及 profile 操作沿现有本地开发文档，不另造一套运行脚本。

常见问题

现象	先检查什么
安装或导入提示找不到公共包入口	当前 manifest 的 file: 目标是否存在，admin-core / ui-patterns 是否已安装并构建
登录请求连接失败	后端是否就绪，代理目标是否匹配当前 profile；只运行前端不能验证真实登录
返回 403 或看不到菜单	当前账号、租户与实际权限；由管理员明确配置，不补替代权限或演示授权
修改后仍看到旧实现	后端进程是否加载当前代码、公共包是否重新构建；按启动入口重启受影响前端
只看到部分管理模块	新 UI 按功能迁移，先查 src/app 与导航登记，不能从后端接口存在推定页面已上线

开始开发

直接页面开发从Nuxt UI 宿主接线和后端合同开始。旧 Schema/compiler 的参考在既有 Kit 与 Schema。

本页是运行入口，不要求先跑全部产品测试。修改功能后按受影响范围验证；正式浏览器流程使用既有 apps/yoyo-admin/ui-tests-playwright，部署与包发布另按对应流程进行。