nuxt-unified-ui

nuxt-unified-ui

主 Agent 决定代码的内容、存放位置以及调用哪些 API。工作完成后，应用流程会为每个文件运行一个子 Agent，检查技能规则并应用代码风格；只有在这个流程中才会应用格式规则。主 Agent 不会加载 references/code-style.md。

完成工作：/nuxt-unified-ui apply

每当你完成了新增或编辑 .vue、.js 或 .ts 文件的工作，都要在最终回复前运行 /nuxt-unified-ui apply：按照 references/apply.md 操作。技能以参数 apply 调用时，或用户要求在整个项目或当前分支应用 nuxt-unified-ui 时，也要这样做。不带参数调用时，该技能只会加载当前任务所需的指导。

在 dev、main 或 master 分支上，它会处理未提交的 .vue、.js 和 .ts 文件；如果该分支没有未提交文件，或项目不属于 Git 工作树，则会处理所有符合条件的文件。在其他分支上，它只会处理该分支相对于基分支新增或更改的文件。系统会使用轻量、快速的模型为每个文件启动一个子 Agent，应用逻辑、结构和代码风格规则，然后由主 Agent 执行跨文件的后续处理。

API

Layer API 来自此层，并会在整个应用及每个层中自动导入。Companion API 来自配套的 unified 层，实际项目始终会将它们与此层一并引入。如果此处未列出某个 API，请先查看源码再使用。

API	用途	来自	参考
un-form / useForm	渲染由 schema 驱动的表单；useForm 返回 { form, formTag }	layer	forms.md
registerFormExtraElement	添加自定义表单元素 identifier（从 Nuxt 插件中调用）	layer	forms.md
useFormExtraElements	读取已注册的自定义元素（使用 registerFormExtraElement 添加）	layer	forms.md
un-card	带图标 / 标题 / 副标题页眉、正文和操作行的卡片	layer	toast-and-ui.md
un-typography	图标 + 标题 + 副标题 + 文本块	layer	toast-and-ui.md
un-spinner	显示加载旋转图标	layer	toast-and-ui.md
un-table	显示一页数据行，包含行操作和分页页脚	layer	tables.md
launchFormPickerDialog	在模态框中请求表单输入；提交逻辑写在 submitButton.onClick 中	layer	dialogs.md
launchChoicePickerDialog	在模态框中确认或进行选择；逻辑写在各按钮的 onClick 中	layer	dialogs.md
launchDialog	打开任意对话框组件；返回其 close 负载	layer	dialogs.md
toast、toastSuccess、toastError、toastWarning、toastInfo	显示 Toast（带类型的辅助函数会设置图标和颜色）	layer	toast-and-ui.md
smartMatch	根据函数、Mongo 风格筛选器或真值，测试对象是否匹配	layer	forms.md
unSet	设置对象上的嵌套路径，并创建缺失层级（会修改原对象）	layer	—
formatDate / parseDate	格式化和解析日期（@formkit/tempo）；默认值来自 app.config 中的 dateFormat	layer	layer-setup.md
isSlotFilled	检查插槽是否有内容	layer	—
pathRelativeToBase	根据文件 URL 解析路径；也从包中导出，供 nuxt.config 使用	layer	layer-setup.md
makeConfetti	播放彩纸效果：template 选择内置效果（parade、on-top / on-left / on-right / on-bottom、on-frame、split-on-top、on-curtain），amount 设置每次喷发的粒子数，其他参数传给 canvas-confetti	layer	—
radXxx	任意 radashi 函数（radGet、radPick 等），可在应用和服务端使用	layer	radashi.md
ufetch	发起一次性 API 请求（提交、删除、点击）	companion	data-fetching.md
useUFetch	加载响应式页面数据（data、pending、refresh）	companion	data-fetching.md
parseSchema	将资源 schema DSL 编译为 { schema, type, inferred }	companion	resources.md
createUnifiedResourceController / UnifiedResourceController	为资源创建类型化的 Mongo 控制器（dbo）	companion	resources.md
createUnifiedSingletonController / UnifiedSingletonController	为一个固定的单例行创建类型化控制器（schema、retrieve、update）	companion	resources.md
app / UnifiedAppRegistry	资源的全局类型化注册表（app.users.dbo）	companion	resources.md
handleResourceSchema、handleResourceList、handleResourceCreate、handleResourceCount、handleResourceRetrieve、handleResourceUpdate、handleResourceDelete	实现资源的标准 REST 路由	companion	resources.md
handleSingletonSchema、handleSingletonRetrieve、handleSingletonUpdate	实现单例路由：获取该行的 schema、检索和更新	companion	resources.md
useResourceName	根据资源名称生成其 API 路径和显示标题	companion	resources.md
useResourceMeta	将资源 schema 映射为表单字段和表格列	companion	resources.md
<resource-manager>	资源的完整 CRUD 仪表盘卡片；提供 refreshResources()	companion	resources.md
<singleton-manager>	单例行的表单卡片；提供 refreshSingleton()	companion	resources.md
<resource-explorer-table>	资源的筛选栏 + 可排序表头 + un-table	companion	tables.md
assertBody	在服务端路由中根据 schema 验证请求正文	companion	—
assertRateLimit	对服务端路由进行速率限制	companion	—
createUnauthenticatedError	在服务端路由中抛出 401 错误	companion	—
generateUuid	生成 UUID	companion	—
useToken	读取或设置身份验证令牌	companion	—
is-authenticated 中间件；dashboard / empty 布局	保护页面；仪表盘和全屏页面布局	companion	pages.md
useJsonld	仅在安装了 nuxt-jsonld 时，在公开页面输出 JSON-LD	nuxt-jsonld	pages.md

文件结构

主 Agent 在实现时决定文件的存放位置和职责。应用子 Agent 只报告文件位置不当的问题，不会移动文件或更新调用方。

每个 .vue、.js 和 .ts 文件都只负责一项工作。如果一个文件需要承担两项互不相关的工作，就创建两个文件。

Nuxt 会在每一层自动导入 app/components/ 和 app/utils/。app/composables/ 同样是公开目录。必须留在单层内部的文件不能放在这些目录中。

角色	目录	可见范围
私有 Vue 组件	app/atoms/	仅此层
私有函数、组合式函数或辅助函数	app/libs/	仅此层
公共 Vue 组件	app/components/	整个应用，自动导入
公共工具函数	app/utils/	整个应用，自动导入

优先创建私有文件。新组件从 app/atoms/ 开始。新函数及类似的辅助函数从 app/libs/ 开始。只有在其他层需要时，才将文件提升到 app/components/ 或 app/utils/。提升后，更新所有调用方并移除相对导入；公共模块会自动导入。

只能使用相对路径导入 atoms 和 libs（../atoms/foo.vue、../libs/bar）。绝不要使用 ~/、@/、#layers/ 或其他别名。绝不要导入其他层的 atoms 或 libs；先提升该文件，再使用公共自动导入。

不要在 Nuxt components 或 imports 配置中注册 atoms 或 libs。

开始编写前

创建或编辑文件前，先阅读与任务对应的参考文档。具体说明请查阅相应参考文档。

任务	首先阅读
图层安装和必需的 CSS	references/layer-setup.md
表单、字段架构、内置和自定义元素	references/forms.md
对话框	references/dialogs.md
Toast、un-* UI、按钮 / 徽章 / 图标约定	references/toast-and-ui.md
表格	references/tables.md
页面和路由	references/pages.md
ufetch / useUFetch	references/data-fetching.md
统一资源	references/resources.md
Radashi radXxx 导出	references/radashi.md

主 Agent 负责的决策

实现时做出这些选择。应用流程之后会再次检查。

• 优先使用上文所述的 API，而不是手动实现等效功能（原始 $fetch、手动构建的 u-modal 流程、直接导入 radashi）。
• 新资源必须包含其服务端插件、完整的 REST 路由集，以及仪表盘导航项或自定义 <resource-manager> 页面。
• 单次请求使用 ufetch。响应式页面数据使用 useUFetch。
• 每个页面都必须显式设置 definePageMeta.name，并使用 useHead 设置 SEO 标题、使用 useSeoMeta 设置描述。
• 按钮、徽章和图标遵循 references/toast-and-ui.md 中的组件约定。编写任何按钮前先阅读该文档。
• 拆分或提升文件时，在同一任务中更新其调用方。
• 安装图层时，必须包含宿主项目的 assets/css/main.css，并在 nuxt.config 中添加 pathRelativeToBase CSS 条目。

i18n

i18n 是可选的。请遵循项目的当前状态。

• 如果项目没有翻译自己的字符串（使用字面文本，不使用 $t，也没有自己的语言文件），就继续编写字面字符串。除非用户决定集成 i18n，否则不要引入 $t、语言文件或 i18n 配置。
• 如果项目已在其他布局中使用 i18n，请遵循该布局。
• 以下规则适用于项目决定集成 i18n 或已经遵循这些规则之后。此层自身对 $t 的使用不算作项目决定集成 i18n。
• 参考示例为简洁起见，通常使用英文原文。在集成 i18n 的项目中，这些字符串应写成 $t('...') 键。

集成 i18n 时

• 所有面向用户的字符串都必须通过 $t，无论是在模板中还是脚本中。两者都可以直接使用 $t，无需调用 useI18n()。
• 全局 i18n 设置——strategy、defaultLocale 和完整的 locales 列表（代码、名称、语言）——应放在 aarde 层（项目扩展 nuxt-unified-ui 的基础应用层，例如 layers/100-aarde/）的 nuxt.config.ts 中。如果项目没有 aarde 层，则使用扩展 nuxt-unified-ui 的层。
• 其他每个层（功能层）都在自己的 i18n/locales/<code>.json 中保留语言文件。在自己的 nuxt.config.ts 中，只声明这些文件——i18n: { locales: [{ code, file }] }——不设置其他 i18n 选项。@nuxtjs/i18n 只会在某个层列出其语言文件时加载这些文件，然后将每个层中相同语言的内容合并到一个消息树中。
• 文件所属的层是其上方最近一个包含 nuxt.config 的目录。该文件中的字符串只能放在该层的语言文件中，不能放在其他层或宿主项目的语言文件中。
• 每个层的语言文件必须恰好有一个顶层键：该层的命名空间，例如 patients 或 billing。所有键都必须嵌套在该键下（$t('patients.single.title')），以避免合并后的树发生冲突。
• 为该层声明的每种语言都添加每个新键。
• 此层拥有两个顶层键：组件使用的 un 和共享标签使用的 common（common.submit、common.cancel、common.close 等）。请复用 common.*，不要重复定义这些标签；但绝不要从其他层向 un 或 common 添加键。

Aarde 层 nuxt.config.ts（片段）：

i18n: {
  strategy: 'no_prefix',
  defaultLocale: 'en',
  locales: [
    {
      code: 'en',
      name: 'English',
      file: 'en.json',
    },
    {
      code: 'de',
      name: 'Deutsch',
      file: 'de.json',
    },
  ],
},

功能层 nuxt.config.ts（片段）及其 i18n/locales/en.json：

i18n: {
  locales: [
    {
      code: 'en',
      file: 'en.json',
    },
    {
      code: 'de',
      file: 'de.json',
    },
  ],
},

{
  "patients": {
    "single": {
      "title": "Patient"
    }
  }
}