@manohub/app-kit 0.2.8 → 0.2.9

package/CONTRACT.md

@@ -19,6 +19,9 @@ export const { mount, unmount } = createSubApp({
   // 用 vue-i18n 的应用走插件注入，不要用本包的 i18n 选项（那是 i18next 语义）
   extraPlugins: [i18n],
   rootPathAliases: ['/index.html'],   // 见 §9「初始守卫与选择模式」
+  // 路由历史模式：缺省 'history'（micro-app baseroute 口径）。宿主不支持深路径 fallback 时改 'hash'；
+  // 需要自定义 base 等细节时传 vue-router 的 RouterHistory 实例。见 §9 第 13 条
+  // history: 'hash',
 })
 ```
 
@@ -119,6 +122,10 @@ import { AppShell, AppPanel, AppTable, AppButton, notify } from '@manohub/app-ki
 </AppShell>
 ```
 
+- `AppShell.Header` 的五个位：`title`（页标题）/ `subTitle`（**下一行的次要说明**，不传即不渲染）/
+  `icon`（不传用内建图标）/ `toolbar`（**页面级操作**位）/ `tabs`（页头下方页签区）。
+  `subTitle` 给的是「一句话说明**什么数据**」（对象名、统计口径），不是第二颗标题，也不是放操作的地方；
+  跟随数据变化时直接传值即可（组件只渲染文本）。`title` 不传 = 整块走自定义页头出口，此时 `subTitle` 不生效。
 - 筛选字段 > 3 或跨区域时，在 `AppShell.Header` **之前**加 `<AppShell.Filter>`（页面级筛选的唯一位置）。
 - **分页归属跟「承载表格的容器」走**：表格直接挂在 `AppShell.Body` 下 → 分页放 `AppShell.Footer`（模板 A）；
   表格在 `AppPanel` 里 → 分页放 `AppPanel.Footer`（模板 B）。
@@ -234,7 +241,7 @@ import { AppShell, AppPanel, AppTable, AppButton, notify } from '@manohub/app-ki
 </AppForm>
 ```
 
-- `label` 是字段名；`required` 让星号自动落在 label 文本**左侧**；`error` 非空即进入错误态；
+- `label` 是字段名；`required` 让星号自动落在 label 文本**之后**（`服务名称*`）；`error` 非空即进入错误态；
   `hint` 是常驻说明。错误与说明排在控件**下方**（文档流），不会遮挡下一行。
 - `label` 与 `required` 都不给时**不渲染 label 列**，控件列占满整行 —— 整块内容（如列编辑区）
   与纯说明行用这个形态，不要另起一套 div 排版。
@@ -679,6 +686,10 @@ const list = useClientPagination(() => filteredRows.value)
   `component-audit.mjs`（组件使用：禁底层直连 / 禁底层风格写法）、
   `structure-audit.mjs`（页面结构：骨架必用 / 禁自绘页头面板头 / 字段数上限）。
   **排查单条**时才直接跑它（`pnpm exec appkit lint:style`），不必挂成脚本。
+- **「路由页」按目录判，与目录约定对齐**（S1）：`src/views|pages/` 下的 `.tsx` 才按路由页要求套 `AppShell`，
+  其中 **`…/components/` 子树内的文件不算路由页** —— 页面内的可复用件（弹窗 / 抽屉 / 表单块 / 子表格）
+  放同页面的 `components/` 子目录，用 `AppPanel` / `AppForm` / `AppDialog` 承载即可。
+  嵌套的页面目录（`views/<页>/<页>.tsx`）**仍然是路由页**，所以目录别只往深了挪、要把件放进 `components/`。
 - `--changed` 只跑改动文件（pre-commit 用；非 git 环境不裁剪，宁可多查）。
 - 每条违规都会给出 `file:line` + 片段 + **唯一改法**（`correction.summary` / `.example`）与 **`doc` 锚点**
   （指回本文件对应章节）。**照 `correction` 改，不要自己另想一套。**
@@ -780,7 +791,8 @@ pnpm --filter @manohub/app-kit test:unit     # vitest（契约单测）+ 护栏
 8. **`AppForm`（表单行）为自建件**：底层对应件 `FDynamicFormGroup` 是**动态表单（元数据驱动）体系**的分组件 ——
    控件要经 `editor` 描述对象交给它渲染、标签宽度与字段限宽写死在 farris 表单类里、校验信息是**绝对定位浮层**。
    与本包三条口径冲突（控件由消费方直接写 / 只收朴素业务值 / 错误走文档流），故按 §7 自建；
-   只沿用 farris 的两条既有约定：label 右对齐、必填星号在 label 文本左侧。
+   沿用 farris 的一条约定：label 缺省右对齐（`labelAlign` 可切左）；
+   **必填星号固定在 label 文本之后**（`服务名称*`）—— 这一条与 farris 的「星号在文本左侧」**有意不同**。
 9. **`AppSteps` 复刻了底层步骤条的节点结构**：底层 `FStep` 的默认模板**只渲染 `title`**
    （`description` / `icon` / `class` / `status` 四个字段压根不被读取），第二行副标题只能自己给 `stepTemplate`；
    本包按底层默认结构复刻 DOM 并沿用其类名（底层配色与连接线样式照旧生效）。
@@ -810,3 +822,9 @@ pnpm --filter @manohub/app-kit test:unit     # vitest（契约单测）+ 护栏
     | `Invalid prop: … prop "popupOffsetX"/"popupOffsetY". Expected Object, got Number 0`（来自 `FButtonEdit`，链路里能看到 `FComboList`） | 上游 `button/index.esm.js` 写的是 `{ type: Object, default: 0 }` | **无法在应用侧消除**（`FComboList` 不转发这两个 prop）。每渲染一个 `AppSelect` 会刷 2 条，属上游缺陷，忽略即可 |
     | `inject() can only be used inside setup()` | farris 内部与 `@gsp-sys/utils` 在组件上下文外调用 `inject`（app-kit 自己的 `inject` 只在 `AppForm.Item` 的 `setup` 内，`modalService` 走 `app.runWithContext`） | 平台/上游行为，与本包无关 |
     | `Extraneous non-props attributes (customClass) …`（来自 `FModal`） | 早期 `AppDialog` 曾把 class 当 `customClass` 转发，而 `FModal` 运行时没有该 prop、根节点又是 Teleport ⇒ 类名被丢弃还刷告警 | 已移除转发，**不再出现**；消费方要钩子请包在内容元素上 |
+13. **路由历史模式可配，缺省仍是 `history`**：`createSubApp` 默认 `createWebHistory()`（micro-app 以 baseroute 隔离子应用路由，
+    这也是平台既有子应用的口径）。宿主**不支持深路径 fallback**、或门户不允许子应用改写地址栏时，传 `history: 'hash'` ——
+    路由落进 hash（URL 形如 `<子应用产物路径>#/x`），既不要求宿主 rewrite，也不占用宿主的 pathname 空间。
+    需要自定义 base 等细节（如 `createWebHistory('/subapp/x/')`）时，直接传 vue-router 的 `RouterHistory` 实例，本包原样使用、
+    不干预 base 与滚动行为。两种模式下 §9 第 2 条的初始守卫口径不变（按 `to.path` 判，hash 模式下的 path 不含 `#`）。
+    用法示例见 §1。

package/README.md

@@ -75,6 +75,8 @@ export const { mount, unmount } = createSubApp({
   // extraPlugins: [i18n],
   // 以 `index.html?xxx=1` 直开的入口（iframe / 选择模式）必须登记，否则首屏守卫会清空 query
   // rootPathAliases: ['/index.html'],
+  // 宿主不支持深路径 fallback 时改 hash；需要自定义 base 时传 RouterHistory 实例
+  // history: 'hash',
 })
 ```
 

package/dist/components/app-form.d.ts

@@ -42,7 +42,10 @@ export interface AppFormItemProps {
      * —— 用于无字段名的整块内容（如列编辑区）与纯说明行。
      */
     label?: string;
-    /** 必填标记：星号渲染在 label 文本**左侧**（沿 farris 表单字段的同一约定；label 整体右对齐） */
+    /**
+     * 必填标记：星号渲染在 label 文本**之后**（`服务名称*`）—— 星号是字段名的一部分，
+     * 跟着字段名走；与 farris 动态表单「星号在左」的写法**有意不同**（本仓口径）。
+     */
     required?: boolean;
     /** 校验错误文案：非空即进入 invalid 态，文案排布在控件**下方**（不遮挡后续行） */
     error?: string;
@@ -86,7 +89,8 @@ export interface AppFormItemProps {
  * （inline 6rem 右对齐、字段 max-width 26.625rem），校验信息走**绝对定位的浮层提示条**。
  * 与本仓三条口径冲突：① 控件由消费方直接写（不构造底层配置对象）；② 数据入参只收朴素业务值；
  * ③ 错误与说明按文档流排布（浮层在弹窗里会压住下一行的控件）。故按「缺件处置流程」自建，
- * 沿 farris 的既有约定：必填星号固定在 label 文本左侧；**label 对齐是维度**（`labelAlign`，
+ * 必填星号固定在 label 文本**之后**（`服务名称*`，有意偏离 farris 的「星号在左」）；
+ * **label 对齐是维度**（`labelAlign`，
  * 默认 `right`（与 farris / 主流水平表单一致），`left` 时所有 label 起点一致）。
  *
  * ## 宽表单怎么处理（两条杠杆，可叠加）

package/dist/components/app-form.js

@@ -86,11 +86,11 @@ const AppFormItem = /* @__PURE__ */ defineComponent({
         "style": styles
       }, [showLabel ? createVNode("label", {
         "class": "ak-form-item__label"
-      }, [props.required ? createVNode("span", {
-        "class": "ak-form-item__required"
-      }, [createTextVNode("*")]) : null, createVNode("span", {
+      }, [createVNode("span", {
         "class": "ak-form-item__label-text"
-      }, [props.label])]) : null, createVNode("div", {
+      }, [props.label]), props.required ? createVNode("span", {
+        "class": "ak-form-item__required"
+      }, [createTextVNode("*")]) : null]) : null, createVNode("div", {
         "class": "ak-form-item__control",
         "style": controlWidth ? {
           maxWidth: `${controlWidth}px`

package/dist/entry/create-sub-app.d.ts

@@ -1,9 +1,18 @@
 import { QueryClient } from '@tanstack/vue-query';
 import { type App as VueApp, type Component, type Plugin } from 'vue';
-import { type RouteRecordRaw } from 'vue-router';
+import { type RouterHistory, type RouteRecordRaw } from 'vue-router';
+/**
+ * 路由历史模式：
+ * - `'history'`（缺省）：正常 history，micro-app 以 baseroute 隔离子应用路由；
+ * - `'hash'`：宿主**不支持深路径 fallback**（刷新深路径 404）、或门户不允许子应用改写地址栏时用；
+ * - 传 `RouterHistory` 实例（如 `createWebHistory('/subapp/x/')`）：自行定制 base 等细节。
+ */
+export type CreateSubAppHistory = 'history' | 'hash' | RouterHistory;
 export interface CreateSubAppOptions {
     rootComponent: Component;
     routes: RouteRecordRaw[];
+    /** 路由历史模式（缺省 `'history'`）。宿主是否支持深路径 fallback 见 `CONTRACT.md` §9 第 13 条 */
+    history?: CreateSubAppHistory;
     i18n?: {
         resources: Record<string, Record<string, unknown>>;
         fallbackLng?: string;
@@ -32,6 +41,9 @@ export interface CreateSubAppOptions {
  * farris 插件（app.use(Farris)）注册在本工厂内部 —— farris 只允许存在于 app-kit，
  * 应用侧不得 import '@farris/ui-vue'（oxlint 护栏）。
  *
+ * 路由历史模式由 `history` 决定：缺省 `'history'`（micro-app 以 baseroute 隔离），
+ * 宿主不支持深路径 fallback 时传 `'hash'`，需要自定义 base 等细节时直接传 `RouterHistory` 实例。
+ *
  * @example
  * export const { mount, unmount } = createSubApp({
  *   rootComponent: Root,

package/dist/entry/create-sub-app.js

@@ -2,7 +2,7 @@ import Farris from "@farris/ui-vue";
 import { VueQueryPlugin } from "@tanstack/vue-query";
 import { createPinia } from "pinia";
 import { defineComponent, ref, provide, h, createApp } from "vue";
-import { createRouter, createWebHistory } from "vue-router";
+import { createRouter, createWebHistory, createWebHashHistory } from "vue-router";
 import { installInitialGuard } from "./initial-guard.js";
 import { createQueryClient } from "./create-query-client.js";
 import { setupI18n } from "../providers/setup-i18n.js";
@@ -11,6 +11,7 @@ function createSubApp(options) {
   const {
     rootComponent,
     routes,
+    history: historyMode = "history",
     i18n,
     queryClient,
     extraPlugins = [],
@@ -26,7 +27,7 @@ function createSubApp(options) {
   let removeGlobalDataListener = null;
   let i18nInstance = null;
   const mount = () => {
-    router = createRouter({ history: createWebHistory(), routes });
+    router = createRouter({ history: resolveRouterHistory(historyMode), routes });
     const ContainerRoot = defineComponent({
       name: "AppKitRoot",
       setup() {
@@ -95,6 +96,11 @@ function createSubApp(options) {
   }
   return { mount, unmount };
 }
+function resolveRouterHistory(value) {
+  if (value === "history") return createWebHistory();
+  if (value === "hash") return createWebHashHistory();
+  return value;
+}
 function exposeToHost(mount, unmount) {
   if (typeof window === "undefined") return;
   const w = window;

package/dist/entry/index.d.ts

@@ -1,4 +1,4 @@
-export { createSubApp, type CreateSubAppOptions } from './create-sub-app';
+export { createSubApp, type CreateSubAppHistory, type CreateSubAppOptions } from './create-sub-app';
 export { installInitialGuard } from './initial-guard';
 export { createQueryClient } from './create-query-client';
 export { setupI18n, i18n, type SetupI18nOptions } from '../providers/setup-i18n';

package/dist/shell/AppShell.d.ts

@@ -2,6 +2,11 @@ import { type PropType, type SlotsType, type VNodeChild } from 'vue';
 export interface AppShellHeaderProps {
     /** 传入 title 走内置布局；不传则纯 slot 直出（自定义页头出口） */
     title?: string;
+    /**
+     * 页头副标题：标题**下一行**的次要说明（对象名、统计口径等），随 `title` 一起进内置布局。
+     * 不传即不渲染（页头条高度不变）；`title` 不传时本项不生效（整块走自定义页头出口）。
+     */
+    subTitle?: string;
     /**
      * 标题左侧图标：**svg 节点或返回节点的函数**皆可。缺省渲染设计稿默认图标
      * （MH后台-0911 node 0:3904：26×26 圆角方块 #2660FF）。
@@ -55,6 +60,10 @@ export declare const AppShell: {
             type: StringConstructor;
             default: undefined;
         };
+        subTitle: {
+            type: StringConstructor;
+            default: undefined;
+        };
         icon: {
             type: PropType<any>;
             default: undefined;
@@ -74,6 +83,10 @@ export declare const AppShell: {
             type: StringConstructor;
             default: undefined;
         };
+        subTitle: {
+            type: StringConstructor;
+            default: undefined;
+        };
         icon: {
             type: PropType<any>;
             default: undefined;
@@ -88,6 +101,7 @@ export declare const AppShell: {
         };
     }>> & Readonly<{}>, {
         title: string;
+        subTitle: string;
         icon: any;
         toolbar: any;
         tabs: any;

package/dist/shell/AppShell.js

@@ -36,6 +36,10 @@ const AppShellHeader = /* @__PURE__ */ defineComponent({
       type: String,
       default: void 0
     },
+    subTitle: {
+      type: String,
+      default: void 0
+    },
     icon: {
       type: [Function, Object, Array, String],
       default: void 0
@@ -81,7 +85,9 @@ const AppShellHeader = /* @__PURE__ */ defineComponent({
         "class": "ak-shell-header-icon"
       }, [renderIcon()]), createVNode("h1", {
         "class": "ak-shell-header-title"
-      }, [props.title])])]), toolbar ? createVNode("div", {
+      }, [props.title])]), props.subTitle ? createVNode("div", {
+        "class": "ak-shell-header-subtitle"
+      }, [props.subTitle]) : null]), toolbar ? createVNode("div", {
         "class": "ak-shell-header-toolbar"
       }, [toolbar]) : null]), tabs ? createVNode("div", {
         "class": "ak-shell-header-tabs"

package/dist/shell/shell.css

@@ -78,6 +78,19 @@
   color: var(--ui-base-content);
 }
 
+/* 页头副标题（Header 的 subTitle）：标题下一行的次要说明，取 caption 档字号与次要色。
+   间距只用 margin-top 4：页头条的上下留白由 .ak-shell-header 的 padding 提供，
+   这里只负责标题行与副标题行之间的距离 —— 有副标题时条目高度自然变高（56 → 80），
+   不再另调 padding（避免「有/无副标题」两套页头规格）。
+   工具条与文本块**底线对齐**是 .ak-shell-header-inner 的既有口径（flex-end），
+   有副标题时即与副标题行对齐，不在本项里改。 */
+.ak-shell-header-subtitle {
+  margin-top: var(--ui-space-1);
+  font-size: var(--ui-font-caption);
+  line-height: var(--ui-line-caption);
+  color: var(--ui-base-content-muted);
+}
+
 /* 筛选区块（Header 上方的第一子块）：query-solution / 筛选条。
    无边框；padding-bottom 恒为 0 —— 与 Header 的间距由 Header 自身的 top padding
    （14px）提供，避免两块 padding 叠加成双倍间距 */

package/lint/__tests__/fixtures/clean-src/views/good-thing/components/picker-dialog.tsx

@@ -0,0 +1,5 @@
+/**
+ * 合规样本里的 `components/` 子树文件：没有 AppShell 也应该全绿。
+ * 一旦 S1 的判定退回「路径里有 views/ 就算路由页」，本样本会变红 —— 这是回归锁。
+ */
+export const PickerDialog = () => <div class="other-picker" data-probe="clean-picker" />

package/lint/__tests__/fixtures/violations-src/views/nested-dir/inner-page.tsx

@@ -0,0 +1,5 @@
+/**
+ * 嵌套页面目录下的真路由页（S1 必须命中）：
+ * 反向锁定「只认 views 直属文件」这种收窄写法 —— 那样写会让这类页面静默漏报。
+ */
+export const InnerPage = () => <section data-probe="inner" />

package/lint/__tests__/fixtures/violations-src/views/thing/components/picker-dialog.tsx

@@ -0,0 +1,5 @@
+/**
+ * 页面内的可复用件（弹窗）：按约定放同页面的 `components/` 子目录 → **不受 S1 约束**（不应出现在报告里）。
+ * 它没有 AppShell 是正确写法（弹窗用 AppDialog / AppPanel 承载）。
+ */
+export const PickerDialog = () => <div data-probe="picker" />

package/lint/__tests__/guardrails.spec.mjs

@@ -150,6 +150,29 @@ test('S4：原生按钮、「无 href 的锚点」、跨行写法的原生输入
   }
 })
 
+test('S1：路由页判定按目录约定 —— 嵌套页面目录仍算，components/ 子树不算', () => {
+  const root = makeConsumer('violations-src')
+  try {
+    const { out } = runAudit('structure-audit.mjs', root)
+    const hits = out.split('\n').filter((line) => line.includes('structure/no-shell'))
+    assert.ok(
+      hits.some((line) => line.includes('no-shell-page.tsx')),
+      `views 直属的路由页应命中，实际：${hits.join(' | ')}`,
+    )
+    assert.ok(
+      hits.some((line) => line.includes('nested-dir/inner-page.tsx')),
+      `嵌套页面目录下的路由页不能被漏掉（那正是「只认 views 直属文件」的收窄写法），实际：${hits.join(' | ')}`,
+    )
+    // 弹窗 / 抽屉这类可复用件放同页面的 components/ 子目录 → 不是路由页，不该套 AppShell（契约 §4.3 / §4.10）
+    assert.ok(
+      !out.includes('picker-dialog.tsx'),
+      `components/ 子树内的可复用件不该报 structure/no-shell，实际输出：\n${out}`,
+    )
+  } finally {
+    rmSync(root, { recursive: true, force: true })
+  }
+})
+
 test('合规样本：三条护栏必须全绿（不得误报）', () => {
   const root = makeConsumer('clean-src')
   try {

package/lint/shared.mjs

@@ -304,7 +304,8 @@ export const CORRECTIONS = {
     doc: 'CONTRACT.md#3-统一-prop-词表',
   },
   'structure/no-shell': {
-    summary: '路由级页面必须用 AppShell 承载结构。',
+    summary:
+      '路由级页面必须用 AppShell 承载结构（页面内的可复用件放同页面的 components/ 子目录，不属于路由页、不受本规则约束）。',
     example: '<AppShell><AppShell.Header title="…" /><AppShell.Body mode="table">…</AppShell.Body></AppShell>',
     doc: 'CONTRACT.md#41-三种页面模板',
   },

package/lint/structure-audit.mjs

@@ -2,7 +2,7 @@
 /**
  * structure-audit —— 页面结构护栏（S1–S7 + 自绘竖直边框检查）。
  *
- *   S1 路由级页面必须用 AppShell
+ *   S1 路由级页面必须用 AppShell（views|pages 下的 tsx；`components/` 子树内的可复用件除外）
  *   S2 AppShell.Header 必须传 title（或登记为自定义页头白名单）
  *   S3 AppShell.Body 必须显式声明 mode
  *   S4 禁原生 button/input/select/textarea 带 class 承载外观
@@ -32,8 +32,22 @@ const cwd = args.cwd
 const config = loadConfig(cwd)
 const changed = args.changed ? changedFiles(cwd) : null
 
-/** 路由级页面的判定：位于 views/pages 目录下的 tsx（弹窗组件在 components 下，不受 S1 约束）。 */
+/**
+ * 路由级页面的判定：**`views|pages` 目录下的 tsx，但 `components/` 子树不算**。
+ *
+ * 页面内的可复用件（弹窗 / 抽屉 / 表单块 / 子表格）按通行约定放在**同页面的 `components/` 子目录**下，
+ * 它们该由 `AppPanel` / `AppForm` / `AppDialog` 承载、不套 `AppShell`（契约 §4.3 / §4.7 / §4.10）。
+ *
+ * 早期实现只判「路径里有没有 `views|pages/`」，于是 `views/<页>/components/*.tsx` 全被当成路由页报 S1
+ * —— 契约要求的目录写法反而被判违规（真实误报：某应用 13 个 tsx 全中，其中 10 个是弹窗/表单/抽屉）。
+ * 这里按**目录段**排除，判据与契约的目录约定对齐。
+ *
+ * 注意：**嵌套的页面目录（`views/<页>/<页>.tsx`）仍然是路由页**，不要收窄成「只认 views 的直属文件」，
+ * 那会让嵌套页面目录下的真路由页静默漏报。
+ */
 const ROUTE_PAGE_RE = /(?:^|\/)(?:views|pages)\//
+/** 路由页目录内的可复用件目录：S1 不查这里面的文件（`components-x` 这类同前缀目录不误伤） */
+const PAGE_PARTIAL_DIR_RE = /(?:^|\/)components\//
 /** 表单控件（S7 计数用）。 */
 const FORM_CONTROLS = /<(AppInput|AppSearchBox|AppSelect|AppDatePicker|AppTextarea|AppNumber)\b/g
 /** 自绘页头/面板头类名（S6）。 */
@@ -85,8 +99,9 @@ for (const app of config.apps) {
     const hasShell = /<AppShell\b/.test(source)
     if (/<AppShell\.Split\b/.test(source)) usesSplit = true
 
-    // S1：路由级页面必须用 AppShell
-    if (ROUTE_PAGE_RE.test(rel) && file.endsWith('.tsx') && !hasShell) {
+    // S1：路由级页面必须用 AppShell（`views|pages` 下、但不在 `components/` 子树内）
+    const isRoutePage = ROUTE_PAGE_RE.test(rel) && !PAGE_PARTIAL_DIR_RE.test(rel)
+    if (isRoutePage && file.endsWith('.tsx') && !hasShell) {
       violations.push(violation(app.name, file, 'structure/no-shell', 1, '路由级页面必须使用 AppShell 承载结构', rel))
     }
     // S2 / S3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@manohub/app-kit",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "private": false,
   "type": "module",
   "description": "子应用统一骨架层：入口编排（createSubApp）、布局契约（AppShell）、页面组件、原子件、服务、样式底座。farris 被收敛在本包内部，对外只暴露标准 API。",
@@ -63,7 +63,7 @@
   },
   "dependencies": {
     "@farris/ui-vue": "^1.8.4",
-    "@manohub/icon": "^0.2.8"
+    "@manohub/icon": "^0.2.9"
   },
   "devDependencies": {
     "@tanstack/vue-query": "catalog:",

package/skills/app-kit/references/adoption.md

@@ -54,6 +54,8 @@ export const { mount, unmount } = createSubApp({
   // extraPlugins: [i18n],
   // 以 `index.html?xxx=1` 直开的入口（iframe / 选择模式）必须登记，否则首屏守卫会清空 query
   // rootPathAliases: ['/index.html'],
+  // 宿主不支持深路径 fallback（刷新深路径 404）时改 hash；需要自定义 base 时传 RouterHistory 实例
+  // history: 'hash',
 })
 ```
 
@@ -62,6 +64,7 @@ export const { mount, unmount } = createSubApp({
 | 选项 | 用途 |
 |---|---|
 | `rootComponent` / `routes` | 根组件与路由表（路由由应用维护，骨架层只负责装载与守卫） |
+| `history` | 路由历史模式：缺省 `'history'`（micro-app 以 baseroute 隔离）；宿主不支持深路径 fallback（刷新深路径 404）或不允许子应用改写地址栏时传 `'hash'`；要自定义 base 等细节则直接传 vue-router 的 `RouterHistory` 实例 |
 | `extraPlugins` | 额外插件（vue-i18n、埋点等）；**i18next 不用它** |
 | `i18n` | i18next 语义：`{ resources: { en: { translation: … }, zh: … }, fallbackLng? }`，随包做宿主语言切换 |
 | `queryClient` | 已有 `@tanstack/vue-query` 实例时传入；不传则骨架层自建（不要传第二份） |
@@ -146,6 +149,7 @@ pnpm exec appkit install --dry-run       # 只预览
 | 类型检查报「无法解析 `*.css`」 | 消费方 `types` 未包含 `vite/client`，或引入了其它包的 CSS 声明 | 补齐 `types: ["vite/client"]` |
 | 弹层/下拉落点偏移 | 门户容器不是文档原点 | 应用侧只写变量（`--ibp-popup-shift-*`），位移规则由包内桥接层负责 |
 | 页面被跳到根路径、query 丢了 | 直开入口未登记 `rootPathAliases` | 见 §3 注释与契约 §9 |
+| 刷新深路径 404（或子应用路由与宿主地址栏互相污染） | 宿主没有 SPA fallback、或不允子应用改写地址栏 | 入口传 `history: 'hash'`，路由改落 hash（见 §3 选项表与契约 §9 第 13 条） |
 | 装到的版本低于 0.1.1 | 0.1.0 已作废 | 升级到 0.1.1+ |
 
 ## 9. 新应用从零搭建（最小骨架）
@@ -194,6 +198,7 @@ pnpm add vue vue-router pinia @tanstack/vue-query i18next i18next-vue i18next-br
 |---|---|
 | 子应用产物路径与挂载方式（如 `/subapp/<group>/<app>/index.html`） | 宿主按约定路径加载，写错等于打不开 |
 | 是否有 `index.html?xxx=1` 这类直开入口（iframe / 选择模式） | 有就必须登记 `rootPathAliases`，否则首屏守卫会清空 query（CONTRACT.md §9.2） |
+| **是否支持深路径 fallback**（`/subapp/.../<深路径>` 回落到 `index.html`） | 支持则入口用缺省的 `history`；不支持就得用 `history: 'hash'`，否则刷新即 404（契约 §9 第 13 条） |
 | dev server 端口与代理规则 | 端口冲突与跨域问题都出在这里 |
 | 宿主下发的语言键与初始路由约定 | 语言切换与首屏落点由宿主导 |
 

package/skills/app-kit-migrate/references/migration-map.md

@@ -16,7 +16,7 @@
 | 旧写法 | 新写法 | 注意事项 |
 |---|---|---|
 | 自绘根容器（`display:flex; flex-direction:column` + `height:100vh` + padding） | `AppShell` + `AppShell.Body`（`mode="plain"\|"scroll"\|"table"`） | **禁 `100vh`**：注入宿主容器后会溢出；高度一律 `100%` |
-| 自绘页头（标题 + 关闭 + 操作按钮） | `AppShell.Header title=… toolbar={…}` | 页头规格（高度、间距、按钮形态）归组件；选择模式这类极简页可以不给页头，只留 Body |
+| 自绘页头（标题 + **副标题** + 关闭 + 操作按钮） | `AppShell.Header title=… subTitle=… toolbar={…}` | 页头规格（高度、间距、副标题行距、按钮形态）归组件；**副标题走 `subTitle`**（跟随业务值直接传文本），不要自绘标题块；选择模式这类极简页可以不给页头，只留 Body |
 | 自绘面板头 / 工具条 / 搜索位 | `AppPanel toolbar={…} actions={…}` 或 `AppPanel.Header` | `toolbar` 是区域筛选（≤3 字段）、`actions` 是区域操作，**两位不可互换**；弹窗内可以不给 title |
 | 自绘表格外框 / 卡片（描边 + 圆角 + 表头） | `AppTable framed` | 卡片外观由内容件承担；`AppPanel` 本身无框 |
 | 自绘双栏 + 手写 1px 竖直分隔线 | `AppShell.Split sidebar={{ width: 208, content: () => … }}` | 中间分隔线由 Split 统一给；**业务侧不得再写 `border-left/right`**；`width` 是内容宽 |
@@ -110,7 +110,8 @@
 
 | 旧写法 | 新写法 | 注意事项 |
 |---|---|---|
-| 手写 `createApp` / `mount` / `window.mount` / 微前端协议 / pinia / 路由守卫 / 宿主语言监听 | `createSubApp({ rootComponent, routes, extraPlugins, rootPathAliases, onReady })` | 工厂内部已完成容器包裹、pinia、路由、守卫、协议、非微前端自动挂载；应用侧**不得重复书写**。vue-i18n 走 `extraPlugins`（骨架层内置的 i18n 选项是另一套语义，不要用） |
+| 手写 `createApp` / `mount` / `window.mount` / 微前端协议 / pinia / 路由守卫 / 宿主语言监听 | `createSubApp({ rootComponent, routes, extraPlugins, rootPathAliases, history, onReady })` | 工厂内部已完成容器包裹、pinia、路由、守卫、协议、非微前端自动挂载；应用侧**不得重复书写**。vue-i18n 走 `extraPlugins`（骨架层内置的 i18n 选项是另一套语义，不要用） |
+| `createWebHashHistory()` / 自定义 base 的 `createWebHistory(base)` | `createSubApp({ history: 'hash' })`，或直接把 `RouterHistory` 实例传给 `history` | 历史模式归工厂统一管理：缺省 `history`（micro-app baseroute 口径），宿主不支持深路径 fallback 时才改 hash（契约 §9 第 13 条） |
 | 手写样式导入顺序 | 固定三行：`reset.css` → `styles.css` → `./app.css` | 顺序即契约，不增不减 |
 | 应用侧各自声明底层组件库 / 图标包依赖 | 只声明骨架层包；其余由骨架层的依赖带入 | 应用侧不得安装或 `import` 底层组件库 |
 | 自建 lint 脚本多条 | 只挂 `lint` / `lint:changed` 两条 | 三条护栏由统一入口并发跑 |

package/skills/app-kit-migrate/references/migration-playbook.md

@@ -163,6 +163,7 @@ export APPKIT_APP_DIR=apps/<x>
 | 缺口 | 影响 | 处理 |
 |---|---|---|
 | 结构护栏只扫 `.ts` / `.tsx`，不扫 `.vue` | 未纳入骨架的 `.vue` 页面不会报 `structure/no-shell` | 属已知范围，不要以为漏了；要覆盖需先有页面级豁免能力 |
+| `structure/no-shell` 的「路由页」按目录判：`views|pages` 下、**`components/` 子树除外** | 弹窗 / 抽屉 / 表单块放对了目录就不会被报；放错位置（直接在 `views/` 下）仍会被当路由页 | 把这些件收进同页面的 `components/` 子目录（契约 §8）；**不要**用「把页面挪深一层」来躲规则 |
 | 骨架层尚未提供的件 | 某些位置只能用现有件近似 | 走契约缺件处置流程，不在应用侧自绘；缺件清单与替代口径见契约 §7.1 |
 | 底层组件库版本跃迁带来的视觉差异 | 个别间距/圆角可能与改造前有细微不同 | 先确认是否骨架层规范使然；确属缺陷则记为骨架层待修项，不在应用侧写覆盖样式 |