@done-coding/admin-core 0.12.1 → 0.12.2-alpha.0

package/types/store/app.d.ts

@@ -1,35 +1,8 @@
 import { CSSProperties } from 'vue';
-import { AdminBridge } from '../bridge';
-/**
- * createAppStore 工厂依赖（#A 期，与 createUserStore deps 收敛单字段 `{ bridge }` 范式对齐）。
- *
- * 业务无泛型消费——layout/theme 配置全经 bridge 12 readonly 属性直读，业务 shape
- * 不渗透 core；UserInfo / LoginParams 双泛型纯透传给入参 `AdminBridge` 签名
- * （避免 app 侧具体类型 bridge 赋给 `AdminBridge<unknown,unknown>` 时的逆变位置
- * 类型冲突，与 createUserStore 范式对齐），core setup 内 [MUST NOT] 消费双泛型字段。
- * #C 期：删第 3 泛型 RefreshTokenParams 透传（bridge 签名已删第 3 泛型）。
- */
+import { CoreBridge } from '../bridge';
 export interface CreateAppStoreDeps<UserInfo = unknown, LoginParams = unknown> {
-    /** app 侧 admin bridge 单例（注入而非 core 持单例，守规则 8；layout/theme 配置全经此读） */
-    bridge: AdminBridge<UserInfo, LoginParams>;
+    bridge: CoreBridge<UserInfo, LoginParams>;
 }
-/**
- * app store 工厂下沉 core。
- *
- * 返回 `defineStore("APP", setup)` 结果（store id 保持 `"APP"`；core 工厂无状态，
- * store 实例由 app 侧 pinia 管理，规则 8）。
- *
- * 主题架构反转（不再 1:1 镜像原 app store dark 状态机）：dark/风格切换真相全移交
- * bridge（`bridge.themeIsDark` / `bridge.theme.setStyle/setDark`）——
- * - `isDarkTheme` 改读 `bridge.themeIsDark`（store 不再持 ref 真相）；
- * - `changeIsDarkTheme` 转发 `bridge.theme.setDark`（旧消费方兼容兜底）；
- * - 退役 store `watch isDarkTheme → className`（由挂值 composable toggle `.dark`）；
- * - 退役 store dark 持久化（`pick:["isDarkTheme"]`）——bridge 持久化 `{themeStyle,themeIsDark}`。
- * layout/route/sidebar 等非主题运行时行为保持不变。
- *
- * @example
- *   export const useAppStore = createAppStore({ bridge: appAdminBridge });
- */
 export declare function createAppStore<UserInfo = unknown, LoginParams = unknown>(deps: CreateAppStoreDeps<UserInfo, LoginParams>): import('pinia').StoreDefinition<"APP", Pick<{
     name: import('vue').ComputedRef<string>;
     isDarkTheme: import('vue').ComputedRef<boolean>;
@@ -72,7 +45,9 @@ export declare function createAppStore<UserInfo = unknown, LoginParams = unknown
         left: string;
     }>;
     sidebarIsCollapse: import('vue').ComputedRef<boolean>;
+    asideIsCollapse: import('vue').ComputedRef<boolean>;
     changeSidebarCollapseStatus: (status: boolean) => void;
+    changeAsideCollapseStatus: (status: boolean) => void;
     changeSidebarHasMenusStatus: (status: boolean) => void;
     changeIsDarkTheme: (status: boolean) => void;
 }, never>, Pick<{
@@ -117,10 +92,12 @@ export declare function createAppStore<UserInfo = unknown, LoginParams = unknown
         left: string;
     }>;
     sidebarIsCollapse: import('vue').ComputedRef<boolean>;
+    asideIsCollapse: import('vue').ComputedRef<boolean>;
     changeSidebarCollapseStatus: (status: boolean) => void;
+    changeAsideCollapseStatus: (status: boolean) => void;
     changeSidebarHasMenusStatus: (status: boolean) => void;
     changeIsDarkTheme: (status: boolean) => void;
-}, "name" | "theme" | "showHeader" | "keepAlive" | "bodyShimPadding" | "isDarkTheme" | "showFooter" | "showSidebar" | "showAside" | "showBreadcrumb" | "headerStyle" | "footerStyle" | "sidebarStyle" | "asideStyle" | "bodyStyle" | "bodyShimStyle" | "viewportPadding" | "sidebarIsCollapse">, Pick<{
+}, "name" | "theme" | "showHeader" | "keepAlive" | "bodyShimPadding" | "isDarkTheme" | "showFooter" | "showSidebar" | "showAside" | "showBreadcrumb" | "headerStyle" | "footerStyle" | "sidebarStyle" | "asideStyle" | "bodyStyle" | "bodyShimStyle" | "viewportPadding" | "sidebarIsCollapse" | "asideIsCollapse">, Pick<{
     name: import('vue').ComputedRef<string>;
     isDarkTheme: import('vue').ComputedRef<boolean>;
     theme: import('vue').ComputedRef<{
@@ -162,7 +139,9 @@ export declare function createAppStore<UserInfo = unknown, LoginParams = unknown
         left: string;
     }>;
     sidebarIsCollapse: import('vue').ComputedRef<boolean>;
+    asideIsCollapse: import('vue').ComputedRef<boolean>;
     changeSidebarCollapseStatus: (status: boolean) => void;
+    changeAsideCollapseStatus: (status: boolean) => void;
     changeSidebarHasMenusStatus: (status: boolean) => void;
     changeIsDarkTheme: (status: boolean) => void;
-}, "changeSidebarCollapseStatus" | "changeSidebarHasMenusStatus" | "changeIsDarkTheme">>;
+}, "changeSidebarCollapseStatus" | "changeAsideCollapseStatus" | "changeSidebarHasMenusStatus" | "changeIsDarkTheme">>;

package/types/store/router-permission.d.ts

@@ -1,72 +1,19 @@
 import { RouteLocationNormalizedLoaded } from 'vue-router';
-import { AdminBridge } from '../bridge';
-/**
- * createRoutePermissionStore 工厂依赖（#B 期；与 createUserStore / createAppStore
- * deps 范式对齐——bridge 经 init 注入，业务 hook / 业务路径常量经 deps 注入）。
- *
- * `useUserStore` 采用 hook 注入（方案 A）——业务层传入 createUserStore 实例化结果，
- * core setup 内调 `useUserStore()` 取响应式 store 实例。方案 B（store 实例注入）
- * 在 createRoutePermissionStore 模块求值期调 hook 会 throw "pinia not active"，故采纳 A。
- * Hook 返回的 store 实例形状用结构最小约束 `{ isLogin, havePermissionByPath, noApiLogout }`
- * 表达——避免 core 反向耦合 createUserStore 三泛型 + 与 createUserStore 返回的具体
- * store 结构自动结构兼容（业务侧零摩擦传入 useUserStore）。
- *
- * `paths` 4 业务路径经 deps 注入而非 bridge schema——业务路径非通用 layout config，
- * 不内化到 bridge（产研统筹勘察结论；保 bridge schema 0 扩张）。
- *
- * 双泛型 `<UserInfo, LoginParams>` 纯透传给入参 `AdminBridge` 签名（避免 app 侧
- * 具体类型 bridge 赋给 `AdminBridge<unknown,unknown>` 时的逆变位置类型冲突，
- * 与 createUserStore / createAppStore 范式对齐），core setup 内 [MUST NOT] 消费双泛型字段。
- * #C 期：删第 3 泛型 RefreshTokenParams 透传（bridge 签名已删第 3 泛型）。
- */
+import { CoreBridge } from '../bridge';
 export interface CreateRoutePermissionStoreDeps<UserInfo = unknown, LoginParams = unknown> {
-    /** app 侧 admin bridge 单例（注入而非 core 持单例，守规则 8；APP_ROUTER_META_DEFAULT_CONFIG 经此直读 + register goToLogin 经此注册） */
-    bridge: AdminBridge<UserInfo, LoginParams>;
-    /**
-     * 业务侧 createUserStore 实例化结果（hook 形态）。
-     * core setup 内调 `useUserStore()` 取响应式 store 实例；本字段仅约束最小消费面，
-     * [MUST NOT] 扩展为全 user store API surface（保 core 对 UserInfo shape 不透明）。
-     */
+    bridge: CoreBridge<UserInfo, LoginParams>;
     useUserStore: () => {
         isLogin: boolean;
         havePermissionByPath: (path: string) => boolean;
         noApiLogout: () => void;
     };
-    /**
-     * 4 业务路径常量（业务路径非通用 layout config，[MUST NOT] 内化到 bridge schema）。
-     * core 不知具体路径值，经 deps 注入；业务层在 packages/app/src/router/config.ts 维护。
-     */
     paths: {
-        /** 登录路径 */
         login: string;
-        /** 无权限路径 */
         noPermission: string;
-        /** 登录免检路径列表 */
         loginNoCheck: string[];
-        /** 权限免检路径列表 */
         authNoCheck: string[];
     };
 }
-/**
- * 路由权限 store 泛型工厂下沉 core。
- *
- * 返回 `defineStore("ROUTE_PERMISSION", setup)` 结果（store id 保持 `"ROUTE_PERMISSION"`；
- * core 工厂无状态，store 实例由 app 侧 pinia 管理，规则 8）。setup 内 1:1 镜像原
- * `packages/app/src/store/router-permission.ts` 全部 139 行运行时行为
- * （checkRouteNeedLogin / checkNeedGoToLoginPage / needGoToLoginPage /
- * checkNeedGoToAuthPage / needGoToAuthPage / goToLoginPage / register goToLogin /
- * 2 watch redirect），[MUST NOT] 重构 / 精简 / 调整顺序。
- *
- * `bridge.APP_ROUTER_META_DEFAULT_CONFIG` 直读取代原 `from "@/config"` import；
- * `getRoutePermissionKey` 走 `@/utils` 复用。
- *
- * @example
- *   export const useRoutePermission = createRoutePermissionStore({
- *     bridge: appAdminBridge,
- *     useUserStore,
- *     paths: { login: loginPath, noPermission: noPermissionPath, loginNoCheck: loginNoCheckPath, authNoCheck: authNoCheckPath },
- *   });
- */
 export declare function createRoutePermissionStore<UserInfo = unknown, LoginParams = unknown>(deps: CreateRoutePermissionStoreDeps<UserInfo, LoginParams>): import('pinia').StoreDefinition<"ROUTE_PERMISSION", Pick<{
     checkNeedGoToAuthPage: (routeInfo: Pick<RouteLocationNormalizedLoaded, "path">) => boolean;
     checkNeedGoToLoginPage: (routeInfo: RouteLocationNormalizedLoaded) => boolean;

package/types/store/user.d.ts

@@ -1,33 +1,9 @@
 import { ComputedRef } from 'vue';
-import { AdminBridge } from '../bridge';
+import { CoreBridge } from '../bridge';
 import { RoutePermission } from '../types';
-/**
- * createUserStore 工厂依赖（v3 终锁 Δ1：deps 收敛单字段 `{ bridge }`）。
- *
- * 业务类型 shape 经泛型 `<UserInfo, LoginParams>` 注入（core 不锁 shape，规则 8）；
- * 运行时配置 + 注入面全部经 `bridge`——`getAppConfig` / `getRoutes` / 4 业务 api /
- * `getUserInfoInitFn()`（用户信息空保底工厂，替代 0fd94cc `userInfoInit` deps 字段）。
- *
- * 第一宪法：token / refreshToken / permission 三字段经 `bridge.userInfoAccess.<字段>`
- * 业务注入访问器读写（纯函数 get/set，core 零字面字段名耦合，业务 UserInfo shape 自由）。
- */
 export interface CreateUserStoreDeps<UserInfo, LoginParams = unknown> {
-    /** app 侧 admin bridge 单例（注入而非 core 持单例，守规则 8；getUserInfoInitFn 经 bridge.init 注入，本工厂经 bridge.getUserInfoInitFn() 读） */
-    bridge: AdminBridge<UserInfo, LoginParams>;
+    bridge: CoreBridge<UserInfo, LoginParams>;
 }
-/**
- * 用户 store 泛型工厂下沉 core。
- *
- * 返回 `defineStore("USER", setup)` 结果（store id 保持 `"USER"`；core 工厂
- * 无状态，store 实例由 app 侧 pinia 管理，规则 8）。setup 内 1:1 镜像原
- * `packages/app/src/store/user.ts` 全部运行时行为（actions / computed / watch /
- * return / 路由权限计算），[MUST NOT] 重构 / 精简 / 调整顺序。
- *
- * @example
- *   export const useUserStore = createUserStore<LoginAccountInfo, AccountLoginParams>({
- *     bridge: appAdminBridge,
- *   });
- */
 export declare function createUserStore<UserInfo, LoginParams = unknown>(deps: CreateUserStoreDeps<UserInfo, LoginParams>): import('pinia').StoreDefinition<"USER", Pick<{
     userInfo: ComputedRef<UserInfo>;
     token: ComputedRef<string>;

package/types/types/dot-path.d.ts

@@ -1,11 +1,3 @@
-/**
- * 字符串点路径转嵌套对象类型
- * ---
- * @example
- *   DotToObject<"page.page", number>     -> { page: { page: number } }
- *   DotToObject<"items", T[]>            -> { items: T[] }
- *   DotToObject<"a.b.c", string>         -> { a: { b: { c: string } } }
- */
 export type DotToObject<P extends string, V> = P extends `${infer Head}.${infer Tail}` ? {
     [K in Head]: DotToObject<Tail, V>;
 } : {

package/types/types/route.d.ts

@@ -1,93 +1,48 @@
 import { RouteRecordRaw } from 'vue-router';
 import { DefineComponent } from 'vue';
-/** 路由权限配置 */
 export type RoutePermission = Partial<{
-    /** 是否需要登录 */
     login: boolean;
-    /**
-     * 权限key
-     * 若为number 期望!=0
-     * 若为string 期望!=""
-     */
     key: number | string;
-    /** 权限key使用路径 */
     keyUsePath: boolean;
-    /** 权限编辑时是否展示 默认配置权限key就会展示 */
     editShow: boolean;
 }>;
-/**
- * 路由 meta 扩展形状（与 app 端 vue-router declaration merging 对齐）
- * ---
- * core 不做全局 declaration merging,仅作 core 内部类型自洽用;
- * app 端仍通过自身 router-meta.d.ts 做 vue-router declaration merging,获得 vue-router RouteMeta 的扩展类型
- */
 export interface AppRouteMeta {
-    /** 页面名称 */
     title: string;
-    /** 是否缓存 */
     keepAlive?: boolean;
-    /** 是否重定向到第一个有权限的子路由 */
     redirectToFirstChildRoute?: boolean;
-    /** 页面布局 */
     layout?: Partial<{
         header: boolean;
         sidebar: boolean;
-        /** 右侧 aside 补充区显隐（additive；默认 false，仅自定义 shell 渲染） */
         aside: boolean;
         footer: boolean;
         breadcrumb: boolean;
         bodyShimPadding: number;
     }>;
-    /** 菜单 */
     menu?: Partial<{
         show: boolean;
         sort: number;
-        /** 图标 (element-plus 等图标实例的 DefineComponent 签名差异较大,这里用 any 兼容) */
         icon: any;
     }>;
-    /** 权限 */
     permission?: RoutePermission;
 }
-/** 获取路由权限key入参 */
 export interface GetRoutePermissionParams {
-    /** 路由路径 */
     path: string;
-    /** 权限配置 */
     permission: RoutePermission | undefined;
 }
-/** 路由元信息解析raw */
 export interface RouteMetaResolveRaw {
-    /** 路由地址 */
     path: string;
-    /** 页面名称 */
     title: string;
-    /** 路由级别 */
     routeLevel: number;
-    /**
-     * 是否重定向到第一个有权限的子路由
-     * 详见 RouteMeta.redirectToFirstChildRoute
-     */
     redirectToFirstChildRoute: boolean;
-    /** 是否在菜单展示 */
     menuShow: boolean;
-    /** 菜单icon */
     menuIcon?: DefineComponent;
-    /** 菜单排序 */
     menuSort: number;
-    /** 子路由原始配置 */
     childrenRaw: RouteRecordRaw[];
-    /** 子路由元信息解析raw */
     children: RouteMetaResolveRaw[];
-    /** 父路由地址 */
     parentPath: string;
-    /** 父路由地址列表 */
     parentPathList: string[];
-    /** 权限key */
     permissionKey?: string | number;
-    /** 是否检测权限 */
     checkPermission: boolean;
-    /** (配置权限的前提下)权限编辑时是否展示 */
     permissionEditShow: boolean;
-    /** 是否需要登录 */
     needLogin: boolean;
 }

package/types/types/utility-types.d.ts

@@ -1,8 +1 @@
-/**
- * 联合类型转交叉类型
- * ---
- * 用于多个 DotToObject 结果合并：
- *   { page: { page: number } } | { page: { pageSize: number } }
- *     -> { page: { page: number; pageSize: number } }
- */
 export type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;

package/types/utils/export.d.ts

@@ -1,31 +1,16 @@
 import { ElTableColumnProps } from '../components/table/types';
-/** 操作列标记 prop。消费方以此值标记操作列，导出时自动过滤 */
 export declare const OPERATE_COLUMN_PROP = "OPERATE";
-/** 前端导出最大行数 */
 export declare const EXPORT_MAX_LIMIT = 10000;
-/** 导出列：从 ElTableColumnProps 中提取 prop、label、type */
-export type ExportColumn<T extends Record<string, any>, 
-/** 期望注入到表格列插槽上的额外内容 */
-F extends Record<string, any> = {}> = Pick<ElTableColumnProps<T, F>, "prop" | "label" | "type">;
-/** 导出列配置：支持 valueMap 自定义取值 */
+export type ExportColumn<T extends Record<string, any>, F extends Record<string, any> = {}> = Pick<ElTableColumnProps<T, F>, "prop" | "label" | "type">;
 export interface ExportColumnConfig<T extends Record<string, any>> {
     prop: keyof T;
     label: string;
-    /** 自定义取值，不传则取 row[prop] */
     valueMap?: (row: Record<keyof T, any>) => unknown;
 }
-/** 导出参数 */
 export interface ExportOptions<T extends Record<string, any>> {
     columns: ExportColumnConfig<T>[];
     list: T[];
     filename?: string;
 }
-/**
- * 从表格列配置中提取可导出列
- * ---
- * 过滤规则：排除 type 为 selection / index / expand 的列（除 default 外均排除），
- * 排除 prop 为 OPERATE_COLUMN_PROP 的列，排除无 prop 的列
- */
 export declare const pickExportColumns: <T extends Record<string, any>, F extends Record<string, any>>(columns: ElTableColumnProps<T, F>[]) => ExportColumn<T, F>[];
-/** 导出 CSV 文件 */
 export declare const exportCSV: <T extends Record<string, any>>({ columns, list, filename, }: ExportOptions<T>) => void;

package/types/utils/id.d.ts

@@ -1,2 +1 @@
-/** 获取不重复的值[单次生命周期中] */
 export declare const getId: (prefix?: string) => string;

package/types/utils/router.d.ts

@@ -1,7 +1,5 @@
 import { GetRoutePermissionParams } from '../types';
-/** 获取路由权限key */
 export declare const getRoutePermissionKey: ({ path, permission: permissionConfig, }: GetRoutePermissionParams) => string | number | undefined;
-/** 扁平化路由元信息解析raw */
 export declare const flatRouteMetaResolveRaw: <T extends {
     children: T[];
 }>(list: T[], arr?: T[]) => T[];

package/types/utils/theme-scale.d.ts

@@ -1,15 +1,5 @@
-/**
- * 主题色阶派生（模式感知，复刻 Element Plus 的 SCSS `mix` 算法）。
- *
- * core 挂值时对 6 个语义色（primary/success/warning/danger/info + error）
- * 由基色派生 EP 7 档（base 自身 + light-3/5/7/8/9 + dark-2），亮/暗模式各用
- * 不同的混入色，使派生结果与 EP 原生色阶一致。
- */
-/** 主题明暗模式（决定色阶向哪一端混合） */
 export type ThemeScaleMode = "light" | "dark";
-/** 一个语义色的 EP 7 档色阶（key 与 `--el-color-*-light-#` / `-dark-2` 对齐） */
 export interface ThemeColorScale {
-    /** 基色自身 */
     base: string;
     "light-3": string;
     "light-5": string;
@@ -18,28 +8,7 @@ export interface ThemeColorScale {
     "light-9": string;
     "dark-2": string;
 }
-/** `#rgb` / `#rrggbb` → [r,g,b]；非法格式返回 null */
 export declare const themeScaleParseHex: (hex: string) => [number, number, number] | null;
-/**
- * 混色：`c1` 占 `w1`、`c2` 占 `1-w1`，各通道线性混合后四舍五入
- * （复刻 EP/SCSS `mix(c1, c2, w1)` 语义，w1 为 c1 的权重 [0,1]）。
- * 任一入参非 hex（如 `var(...)` / `rgba(...)`）→ 返回 `c2` 兜底，不崩。
- */
 export declare const themeScaleMix: (c1: string, c2: string, w1: number) => string;
-/**
- * `#rgb` / `#rrggbb` + alpha → `rgba(r, g, b, a)`。
- *
- * 供吃不了 CSS `var()` 的 JS / canvas 消费方（如 ElWatermark `font.color`）按主题
- * 真实色值 + 透明度生成可绘制色串。`alpha` 自动裁剪到 [0,1]。
- * 非 hex 入参（`var(...)` / `rgba(...)`）→ 原样返回（不崩、不强转）。
- */
 export declare const themeScaleToRgba: (hex: string, alpha: number) => string;
-/**
- * 按 EP 算法 + 模式感知派生一个语义色的 7 档色阶。
- *
- * - light：`light-i = mix(#fff, base, i*10%)`，`dark-2 = mix(#000, base, 20%)`
- * - dark： `light-i = mix(#141414, base, i*10%)`，`dark-2 = mix(#fff, base, 20%)`
- *
- * `base` 非 hex 时各档兜底返回 `base` 原值（保持可挂载、不崩）。
- */
 export declare const themeScaleDerive: (base: string, mode: ThemeScaleMode) => ThemeColorScale;

package/types/utils/time.d.ts

@@ -1,2 +1 @@
-/** 倒计时 */
 export declare const timeCountDown: (time: number, handler: (t: number) => void, endHandler: () => void) => () => void;

package/docs/TECH_SNAPSHOT.md

@@ -1,146 +0,0 @@
-# @done-coding/admin-core 技术架构快照
-
-> 文档定位：快照型——始终反映当前技术架构状态，覆盖式更新，不保留历史变更（变更见 git history）。
-> 维护者：架构师；触发时机：归档协议执行时。
-
-## 1. 设计边界
-
-### 1.1 包含范围（✓）
-
-- 通用 admin 基础设施组件（form / menu / display / misc）
-- 通用列表分页结构（`APP_API_LIST_MODEL_KEY_CONFIG` / `AppApiListModel<T>` / `AppApiListParamsModel<P>` / `AppApiListPageParamsKey` / `AppNoPageParamsKey`）
-- dot-path 类型工具（`DotToObject` / `UnionToIntersection` / `BuildListModel` / `BuildListParams`）
-- 通用 hooks / utils / types
-- 路由通用类型（`./types/route`）
-
-### 1.2 排除范围（✗，业务壳层永不下沉）
-
-- 业务码外壳：`APP_API_BUSINESS_MODEL_KEY_CONFIG` / `AppApiBusinessModel<T>`（code / message / data 字段名属公司级业务约定）
-- 业务接口配置：`APP_REQUEST_CONFIG`（含 `basePath` 来自 `import.meta.env.VITE_API_BASE_PATH` 的构建期常量，core 包构建期不可知）
-- 业务路由 / 业务枚举（如 `BusinessErrorEnum`）
-- IoC 注入式 KEY 配置（一个月内不引入；见 ADR-4）
-
-> 边界硬规则：**业务壳层永不下沉 core**。任何带公司业务特征（业务码语义 / basePath 构建期常量 / 业务路由）的成员均留 app 包。
-
-## 2. 已知约束
-
-### 2.1 分页 KEY 固化
-
-`APP_API_LIST_MODEL_KEY_CONFIG` 的 4 KEY 取值在 core 内固化为公司级约定：
-
-| KEY | 取值 |
-|---|---|
-| CURRENT_PAGE_KEY | `"page.page"` |
-| PAGE_SIZE_KEY | `"page.pageSize"` |
-| TOTAL_KEY | `"page.totalRecord"` |
-| LIST_KEY | `"items"` |
-
-**类型层与运行时层均从 `typeof KEY_CONFIG` 推导**——所有列表/分页相关类型（`AppApiListModel` / `AppApiListParamsModel` / `TableApiParams` / `TableApiResult`）的字段名 [MUST] 通过 `typeof APP_API_LIST_MODEL_KEY_CONFIG.XXX_KEY` 读取，[MUST NOT] 手写嵌套字面量（如 `{ items: T[]; page: { totalRecord: number } }`）。
-
-理由——KEY runtime 取值并非永久不变，消费方可通过发新版或 pnpm patch 重写；手写字面量会让 runtime 改而类型不跟进，等于自废 dot-path 推导能力。
-
-### 2.2 pnpm patch 逃生通道
-
-消费方自定义分页字段时，通过 `pnpm patch @done-coding/admin-core` 在工具链层重写已发布产物的 `APP_API_LIST_MODEL_KEY_CONFIG` 取值。
-
-最小步骤：
-
-```bash
-# 1. 创建 patch
-pnpm patch @done-coding/admin-core
-
-# 2. 修改 patch 临时目录下 3 个产物文件（必须同步改）
-#    - es/index.mjs        （ESM 运行时）
-#    - lib/index.cjs       （CJS 运行时）
-#    - types/index.d.ts    （as const 字符串字面量类型，必须同步以保 typeof 推导）
-#    将 APP_API_LIST_MODEL_KEY_CONFIG 4 KEY 取值改为消费方约定（如 current / size / total / list）
-
-# 3. 提交 patch
-pnpm patch-commit <临时目录>
-
-# 4. 重启 dev / 重新 build
-```
-
-**警示：** [MUST NOT] 通过业务运行时配置（plugin install 选项 / 全局变量 / 工厂函数）覆盖 KEY 取值——会让 `typeof KEY_CONFIG` 类型推导失效（编译期常量），等于自废 dot-path 工具能力。
-
-## 3. 类型工具说明
-
-### 3.1 `DotToObject<P, V>`
-
-字符串点路径转嵌套对象类型。
-
-| 输入 | 输出 |
-|---|---|
-| `DotToObject<"a.b.c", string>` | `{ a: { b: { c: string } } }` |
-| `DotToObject<"page.page", number>` | `{ page: { page: number } }` |
-| `DotToObject<"items", T[]>` | `{ items: T[] }` |
-
-### 3.2 `UnionToIntersection<U>`
-
-联合类型转交叉类型。用于多个 `DotToObject` 结果合并：
-
-| 输入 | 输出 |
-|---|---|
-| `UnionToIntersection<{a:{x:1}} \| {a:{y:2}}>` | `{a:{x:1; y:2}}` |
-
-### 3.3 `BuildListModel<KC, T>`
-
-基于 KEY_CONFIG 联合推导完整列表响应模型（高阶组合工具）。
-
-| 输入 | 输出 |
-|---|---|
-| `BuildListModel<typeof APP_API_LIST_MODEL_KEY_CONFIG, User>` | `{ items: User[]; page: { page: number; pageSize: number; totalRecord: number } }` |
-
-### 3.4 `BuildListParams<KC, P>`
-
-基于 KEY_CONFIG 联合推导列表请求参数模型。
-
-| 输入 | 输出 |
-|---|---|
-| `BuildListParams<typeof APP_API_LIST_MODEL_KEY_CONFIG, { keyword?: string }>` | `{ keyword?: string } & { page: { page: number; pageSize: number } }` |
-
-## 4. 架构决策记录 (ADR)
-
-### ADR-1：4 工具 2 层架构（基础 + 应用）
-
-**决策：** dot-path 工具拆分为 2 层——基础层（`DotToObject` / `UnionToIntersection`）与应用层（`BuildListModel` / `BuildListParams`），全部归属 `packages/core/src/types/dot-path.ts` 单文件。
-
-**理由：** 基础层是纯 TS 字符串路径推导，与列表领域无关，未来其他领域（表单 schema / URL query）也可复用；应用层是基于基础层组合的列表领域专用工具，给 list-model.ts 提供高阶接口。
-
-**否决方案：** 仅暴露 2 个高阶工具（不出基础层）——TableApiResult 只需 items + page.totalRecord 子集，强制带入完整 4 KEY 推导后还要 Pick 二次裁剪，反而不灵活。
-
-**状态：** 活跃。
-
-### ADR-2：core 单一来源 + app re-export 切源
-
-**决策：** `APP_API_LIST_MODEL_KEY_CONFIG` 等 5 项的唯一定义点位于 `packages/core/src/config/list-model.ts`；`packages/app/src/config/request.ts` 删除原定义，改为从 `@done-coding/admin-core` re-export。
-
-**理由：** ① 消除 core/app 双份漂移根因（取消 CI 检查的前提）；② core 自身后续迁组件需直接引用，不能从 app 反向 import；③ app 端通过 re-export 而非全仓库改 import path，业务面零改动。
-
-**否决方案：** 双份维护 + CI 检查——治标不治本，已被用户裁决取消（NG-6）。
-
-**状态：** 活跃。
-
-### ADR-3：DUCK 最小化 + `typeof KEY_CONFIG` 推导贯彻全域
-
-**决策：** 所有列表/分页类型（`AppApiListModel` / `AppApiListParamsModel` / `AppApiListPageParamsKey` / `TableApiParams` / `TableApiResult`）的字段名 [MUST] 从 `typeof APP_API_LIST_MODEL_KEY_CONFIG.XXX_KEY` 读取，禁止手写嵌套字面量。
-
-**理由：** KEY runtime 可经 pnpm patch 改写；手写字面量会让 runtime 改而类型不跟进。
-
-**状态：** 活跃。
-
-### ADR-4：取消双份镜像，pnpm patch 作为消费方自定义分页字段的逃生通道
-
-**决策：** 不引入 IoC 注入（plugin install 选项 / createAdminCore 工厂等）；消费方需自定义 KEY 时通过 pnpm patch 重写产物。
-
-**理由：** ① IoC 注入需给所有列表类型工具提供运行时配置出口，复杂度溢出；② 真实业务场景中分页字段是公司级约定，跨项目变更频率极低；③ pnpm patch 是 monorepo 工具链层标准能力，零代码侵入；④ 用户裁决：一个月内不考虑 IoC（NG-2）。
-
-**状态：** 活跃。
-
-### ADR-5：业务壳层（code / data / message + APP_REQUEST_CONFIG）永不下沉 core
-
-**决策：** `APP_REQUEST_CONFIG` / `APP_API_BUSINESS_MODEL_KEY_CONFIG` / `AppApiBusinessModel<T>` 三项保留 app，不下沉 core。
-
-**理由：** ① 业务码字段名（code / data / message）属公司级业务约定，不同后端可能用 errno / result / msg；② basePath 来自 `import.meta.env.VITE_API_BASE_PATH` 是 app 构建期常量，core 包构建期不可知；③ NG-1 硬约束。
-
-**状态：** 活跃。

package/docs/nested-config-paradigm.md

@@ -1,80 +0,0 @@
-# 配置化嵌套范式（FormMain 套 FormMain / PanelMain 套 PanelMain / 交叉互套）— 实现纪要
-
-> **定位**：**P1/P2/P3 已实现纪要**。本文原为设计提案（design-only），其后 nest 联结组件落地，P1（校验穿透）、P2（Panel 嵌套）、P3（布局 rebase span 值轴）均已实现，**实现走了比初版设想更干净的路**；仅 P3 的**断点选择轴**（容器查询）留后续 opt-in。
-> **实现去向**：4 个联结薄壳（C1 `FormItemNestForm` / C4 `FormItemNestFormList` / C2 `PanelItemNestPanel` / C3 `PanelItemNestForm`）+ 配套 helper（`nestFormItem` / `nestFormItemList` / `nestPanelItem` / `nestPanelForm`）。
-> **上位原则**：KB `paradigm.md` §3.0.1「非顶级子空间挂载薄壳（递归下探二等公民层）」——本文是该范式在 Form/Panel 自嵌套 + 交叉嵌套切片上的工程纪要。
-
----
-
-## 1. 范式：薄壳即嵌套（已落地）
-
-FormMain / PanelMain **本身没有**「表单套表单 / 面板套面板」的一等 prop 支持，但**也不需要**——两族配置化 item 的渲染出口（`render` / `editorRender`）本就是**开放契约**：返回 `VNode[]` 即可，内容由配置方决定。
-
-> 嵌套 = 在一个 item 的 `render`/`editorRender` 里套一层**薄壳**（联结组件），薄壳内部挂一个**新的配置化容器**（子 FormMain / PanelMain）。只要薄壳对外仍满足父容器对该 item 的契约（值、校验、布局），父容器无感知，嵌套即成立。
-
-三种形态（无界组合，均已落地）：
-- **Form 套 Form**：C1 `FormItemNestForm`（1:1）/ C4 `FormItemNestFormList`（1:N 数组）。
-- **Panel 套 Panel**：C2 `PanelItemNestPanel`（纯展示）。
-- **交叉互套**：C3 `PanelItemNestForm`（Panel 项编辑态内嵌 FormMain）。
-
-> KB 视角的本体定位：联结薄壳 = 把**空间二等公民**（子 FormMain/PanelMain，当不了空间根）适配成满足父 item 契约的可嵌挂载件，**非空间一等公民**。见 `paradigm.md` §3.0.1。
-
----
-
-## 2. P1 校验穿透 — ✅ 已实现（registry 级联，非初版 validator 桥）
-
-### 实际落地
-
-- **form 族经 registry 级联**：`FormItemNestForm`（C1）/ `FormItemNestFormList`（C4）经 `useNestForm` / `useNestFormList` 把子 `FormMain` 的 `{ validate, clearValidate, resetFields }` 注册进**最近祖先 FormMain** 的 `exposeMap`（`NestFormExposeMap = shallowReactive<Record<itemKey, NestFormExpose>>`，`nest-registry.ts`）。父顶层一次 `validate/clearValidate/resetFields` 即经 `exposeMap` 级联到子（C4 为聚合 expose + fan-out 遍历 N 行）。
-- **对齐 hideKeyList**：父 FormMain `validate` 按 item key 过滤——整 list 被 hide 时不级联（ADR-8）。
-- **panel 族不接 registry**：panel 是 per-item submit、无父顶层 validate，故 C3 `PanelItemNestForm` 改走组件内**局部 `validateChild`**（提交前自校验，reject 留编辑态）；C2 纯展示无校验。
-
-> **与初版提案的差异（求真）**：提案曾设想用 item `rules` 的 async `validator` 作「校验穿透桥」。**实现未采用**——registry/exposeMap 级联更干净（无需把子 formInstance 塞进规则闭包，天然对齐 hideKeyList）。初版 validator 桥设想已废弃，不再保留为方向。
-
----
-
-## 3. P2 PanelMain 嵌套 — ✅ 已实现
-
-- **展示态**（C2 `PanelItemNestPanel`）：内层 PanelMain 置 `itemCard=false` → 子项平铺（"一项展示多字段"观感，本质潜套 PanelMain）；值贯通 = `render` 的 `scope.value` 嵌套对象只读直供子 PanelMain。
-- **编辑态**（C3 `PanelItemNestForm`）：经 `editorRender`（优先级高于 `editorConfig`，互斥）挂子 FormMain；`PanelEditSwitch` 进编辑深克隆**草稿**，子 FormMain 绑草稿 in-place，校验通过 `submitFn(草稿) → closeEdit` **回流**真实 data，取消弃草稿。这正是「配置式 `editorConfig` 单字段表达不了的多字段子表单」的合规 escape hatch。
-
----
-
-## 4. P3 嵌套后的布局继承（layout 基于父 item 实际宽而非屏幕）— ✅ 已实现（span 值轴；断点选择轴留 opt-in）
-
-### 落地（2026-06-13）
-
-- 4 联结薄壳现经 `layoutScale` 累乘因子向子 FormMain/PanelMain 传 rebase 因子：`childScale = parentScale × (24 / 父item span)`，子 `resolveFormLayout(span, scale)` 把 span×scale 后 `ceilToTier` 到档集 `{6,8,12,24}`（封顶 24）。**默认开**；helper 加 `rebase?: boolean`（缺省 `true`，`false` = 逆向逃生口原样直透）。
-- 链路：`FormMain`/`PanelMain` 加 prop `layoutScale`（缺省 1）+ provide `NEST_LAYOUT_SCALE_KEY`；薄壳 `useNestLayoutScale` inject 父 scale 叠本层因子；helper 经 `resolveLayoutSpan(layout)` 把父 item 代表 span 传薄壳。
-- 不变量：叶子字段绝对宽 ≈ `(authoredSpan/24) × 屏宽`，与嵌套深度无关。
-- 设计 + worked examples 见 `docs/specs/2026-06-13-045727-moderate-嵌套布局rebase-P3/design.md`。
-
-### 解决的缺口
-
-外层 item 用窄栅格（如父 `span:12` = 半宽容器）时，子字段 `span` 相对**容器**算百分比 → 嵌套层过挤；rebase 按父 item 实际分配宽放大子 span，维持字段绝对宽与顶级一致。
-
-### 已知近似（v1 接受）
-
-- 仅修 **span 值轴**；**断点选择轴**（el 的 `xs/sm/md/lg/xl` 由 **window 宽** media query 选档，非容器宽）留后续 opt-in 容器查询治理。
-- 3+ 层且中间层被 ceil/clamp 时，因子用 authored span 略欠精；2 层常见场景精确。
-
----
-
-## 5. 状态小结
-
-| # | 缺口 | 状态 | 实际落地 / 遗留 |
-|---|---|---|---|
-| P1 | 校验穿透 | ✅ 已实现 | form 族 registry/exposeMap 级联（C1/C4，ADR-1/8）；panel 族局部 validateChild（C3）/ 无校验（C2）。初版 validator 桥设想已废 |
-| P2 | Panel 嵌套 | ✅ 已实现 | C2 展示（itemCard 平铺）+ C3 编辑（editorRender 挂子 FormMain + 草稿回流） |
-| P3 | 布局继承 rebase | ✅ 已实现（span 值轴） | layoutScale 累乘链 + ceilToTier 档集；断点选择轴留 opt-in 容器查询 |
-
-**遗留边界**：本文不再据 P1/P2/P3 实现展开（已落地，API 见 KB 组件档 + MIGRATION §38）；唯一未做项为 P3 的**断点选择轴**（容器查询替代 viewport 媒体断点），留后续 opt-in spec。
-
----
-
-## 附：相关源码 / KB 锚点
-
-- 联结薄壳源：`packages/core/src/components/form/{FormItemNestForm,FormItemNestFormList}.vue` + `{nest-form-item,nest-form-item-list}.ts`；`packages/core/src/components/panel/{PanelItemNestPanel,PanelItemNestForm}.vue` + `{nest-panel-item,nest-panel-form}.ts`
-- registry 基建：`packages/core/src/components/form/{nest-registry,use-nest-form,use-nest-form-list}.ts`
-- 上位范式 + 组件 API（KB）：`~/.claude/knowledge/admin-core/paradigm.md` §3.0.1；`components/{FormItemNestForm,FormItemNestFormList,PanelItemNestPanel,PanelItemNestForm}.md`
-- 嵌套三件套实现 spec（含 ADR-1/5/6/8）：`docs/specs/2026-06-12-020608-complex-配置化嵌套联结组件Nest三件套/`