@done-coding/admin-core 0.0.1-alpha.0

package/docs/specs/2026-05-09-055250-moderate-/345/210/227/350/241/250key/351/205/215/347/275/256/347/202/271/350/267/257/345/276/204/346/224/257/346/214/201/design.md

@@ -0,0 +1,575 @@
+---
+任务等级: Moderate
+日期: 2026-05-09
+审核状态: 已通过
+reviewer: architect 自查（用户 2026-05-09 裁决简化设计审核——不走 reviewer subagent，不走开发/测试/产品上下游预审）
+---
+
+# 技术设计文档：列表 KEY 配置点路径支持
+
+> 简化说明：本任务设计审核被用户裁决为「架构师同 agent 自查自纠」单步流程；
+> 故 `reviewer` 字段不含 `superpowers:code-reviewer` 与上下游预审。
+> 自查清单见末尾「自查记录」节，全部 ✓ 后 frontmatter 标记「已通过」。
+
+---
+
+## 1. 变更范围防火墙
+
+### Direct Targets（计划新建/修改）
+
+| # | 文件路径 | 类型 | 对应 REQ |
+|---|---|---|---|
+| 1 | `packages/core/src/types/dot-path.ts` | **新建** | REQ-1 |
+| 2 | `packages/core/src/config/list-model.ts` | **新建** | REQ-2 / REQ-3 |
+| 3 | `packages/core/src/index.ts` | 修改（追加 re-export） | REQ-1 / REQ-2 / REQ-3 |
+| 4 | `packages/app/src/config/request.ts` | 修改（删 5 项 + re-export） | REQ-2 |
+| 5 | `packages/app/src/components/table/types.ts` | 修改（重写 2 类型） | REQ-4 |
+| 6 | `packages/app/src/components/table/TableMain.vue` | 修改（4 处运行时改造） | REQ-5 |
+| 7 | `packages/core/docs/TECH_SNAPSHOT.md` | **新建** | REQ-6 |
+| 8 | `packages/core/README.md` | 修改（追加进阶用法节） | REQ-7 |
+
+> 实际计划修改 7 个文件 + 新建 3 个 = 8 处变更点（REQ-1 ~ REQ-7 全覆盖；其中 `core/src/index.ts` 同时承担 REQ-1/2/3 的 re-export 出口）。
+
+### Collateral Reads（仅供参考、[MUST NOT] 修改）
+
+| 文件 | 用途 |
+|---|---|
+| `packages/app/src/config/index.ts`（barrel） | 验证 `@/config` re-export 链路 |
+| `packages/app/src/views/**/*.vue`（业务页） | 验证 `TableApiResult<T>` 业务侧消费方写法是否需要补 `as UnwrapRef<T[]>` |
+| `packages/core/vite.config.ts` / `tsconfig.json` | 验证 `core/src/types/dot-path.ts` 与 `core/src/config/list-model.ts` 是否被构建打包 |
+| `packages/core/package.json` | 已确认 `lodash` 在 peerDependencies 行 71，无需新增 dependencies |
+
+### Out-of-Scope（[MUST NOT] 触碰的敏感区）
+
+| # | 区域 | 理由（对应 NG）|
+|---|---|---|
+| 1 | `packages/app/src/config/request.ts` 中 `APP_REQUEST_CONFIG` / `APP_API_BUSINESS_MODEL_KEY_CONFIG` / `AppApiBusinessModel` | NG-1 / NG-4：业务壳层永不下沉 core，本次保持 app 内现状不动 |
+| 2 | `packages/app/src/components/table/` 与 `packages/app/src/views/list-page/` 组件本体 | NG-3：本次仅前置升级 KEY 配置能力，组件迁移留期 #2 |
+| 3 | `packages/core/src/components/**` 现有 4 子目录（form / menu / display / misc） | 范围外，本次新增的是 `src/types/` + `src/config/` 两个**新目录** |
+| 4 | core/app 双份配置漂移检查（CI / lint rule） | NG-6：取消双份策略后根因消除 |
+| 5 | KEY 配置数组路径形态（`["a","b"]`）/ IoC 注入式 KEY 配置 | NG-2 / NG-5：YAGNI |
+| 6 | 列表/分页类型中手写嵌套字面量 | NG-7：必须从 `typeof KEY_CONFIG` 推导 |
+
+### Self-Healing Rule
+
+WHEN 验证失败（`vue-tsc` 类型不通 / `pnpm build` 失败 / 业务页 dev 报错），[MUST] 分析日志尝试修复一次；二次失败则停下汇报。
+
+---
+
+## 2. 架构决策记录 (ADR)
+
+### ADR-1：4 工具 2 层架构（基础 / 应用）
+
+| 维度 | 内容 |
+|---|---|
+| **决策** | dot-path 工具拆分为 2 层：基础层（`DotToObject` / `UnionToIntersection`）+ 应用层（`BuildListModel` / `BuildListParams`），全部归属 `packages/core/src/types/dot-path.ts` 单文件 |
+| **理由** | ① 基础层是纯 TypeScript 字符串路径推导，与列表领域无关，未来其他领域（如表单 schema、URL query）也可复用；② 应用层是基于基础层组合的列表领域专用工具，给 list-model.ts 提供高阶接口，避免 list-model.ts 直接耦合 `infer + UnionToIntersection` 实现细节 |
+| **备选方案 A** | 只提供 `BuildListModel` / `BuildListParams` 2 个高阶工具，不暴露基础层 |
+| **A 否决理由** | TableMain.vue 的 `TableApiResult<T>` 只需要"items + page.totalRecord"两字段子集，不需要 page.pageSize、page.page、items 全套——若只暴露 BuildListModel 高阶工具，强制带入完整 4 KEY 推导，会让 TableApiResult 必须用 `Pick<>` 二次裁剪。直接用基础层 `DotToObject + UnionToIntersection` 自由组合反而更灵活 |
+| **备选方案 B** | 4 工具拆 4 文件（`dot-to-object.ts` / `union-to-intersection.ts` / `build-list-model.ts` / `build-list-params.ts`） |
+| **B 否决理由** | 4 工具总行数 ≤ 50，强制分文件徒增 import 噪音；用户已锁定单文件方案 |
+| **状态** | 活跃 |
+
+### ADR-2：core/src/config/list-model.ts 单一来源 + app re-export 切源
+
+| 维度 | 内容 |
+|---|---|
+| **决策** | `APP_API_LIST_MODEL_KEY_CONFIG` / `AppApiListModel` / `AppApiListParamsModel` / `AppApiListPageParamsKey` / `AppNoPageParamsKey` 5 项的**唯一定义点**位于 `packages/core/src/config/list-model.ts`；`packages/app/src/config/request.ts` 删除原定义改为从 `@done-coding/admin-core` 整段 `export { ... } from` 转出，维持 `@/config` 消费面不破 |
+| **理由** | ① 消除 core/app 双份漂移根因（NG-6 取消 CI 检查的前提）；② core 自身后续的 list-page / table 组件迁移（期 #2）需要内部直接引用，不能从 app 反向 import；③ app 端通过 re-export 而非 import 改写，减少业务页面改动面 |
+| **备选方案 A** | 双份维护 + CI 检查保证一致性 |
+| **A 否决理由** | NG-6：用户裁决取消双份策略；治标不治本 |
+| **备选方案 B** | core 提供，app 端业务页改 import path 至 `@done-coding/admin-core` |
+| **B 否决理由** | 需要全仓库改业务页 import；用户裁决：app `request.ts` 内部 re-export 即可，业务面零改动 |
+| **状态** | 活跃 |
+
+### ADR-3：DUCK 最小化 + `typeof KEY_CONFIG` 推导贯彻全域（NG-7 硬约束）
+
+| 维度 | 内容 |
+|---|---|
+| **决策** | 所有列表/分页相关类型（`AppApiListModel` / `AppApiListParamsModel` / `AppApiListPageParamsKey` / `TableApiParams` / `TableApiResult`）的字段名 [MUST] 从 `typeof APP_API_LIST_MODEL_KEY_CONFIG.XXX_KEY` 读取，**禁止手写嵌套字面量**（如直接 `{ items: T[]; page: { totalRecord: number } }`） |
+| **理由** | KEY runtime 取值并非永久不变——消费方可通过发新版或 `pnpm patch` 重写 4 KEY 取值；手写字面量会让 runtime 改而类型不跟进，等于自废 dot-path 推导能力 |
+| **备选方案 A** | 类型层手写字面量，运行时层用 lodash get/set |
+| **A 否决理由** | 类型与运行时一旦不一致，pnpm patch 场景下消费方将获得错误的类型提示；NG-7 显式禁止 |
+| **状态** | 活跃 |
+
+### ADR-4：取消 core/app 双份镜像，pnpm patch 作为消费方自定义分页字段的逃生通道
+
+| 维度 | 内容 |
+|---|---|
+| **决策** | 不引入 IoC 注入（plugin install 选项 / createAdminCore 工厂等）；消费方需自定义分页 KEY 时通过 `pnpm patch @done-coding/admin-core` 重写已发布产物中的 `APP_API_LIST_MODEL_KEY_CONFIG` 取值 |
+| **理由** | ① IoC 注入需要给所有列表类型工具提供运行时配置出口，复杂度溢出；② 真实业务场景中分页字段是公司级约定，跨项目变更频率极低；③ pnpm patch 是 monorepo 工具链层标准能力，零代码侵入；④ 用户裁决：一个月内不考虑 IoC（NG-2） |
+| **备选方案 A** | createAdminCore 工厂 + plugin install 选项注入 KEY |
+| **A 否决理由** | NG-2 + 当前列表类型工具均为静态类型推导，IoC 化需要全部改成运行时 generic 工厂；改造面过大 |
+| **状态** | 活跃 |
+
+### ADR-5：业务壳层（code/data/message + APP_REQUEST_CONFIG）永不下沉 core
+
+| 维度 | 内容 |
+|---|---|
+| **决策** | `APP_REQUEST_CONFIG`（含 basePath 环境变量 + timeout）/ `APP_API_BUSINESS_MODEL_KEY_CONFIG`（code/message/data 业务码外壳）/ `AppApiBusinessModel<T>` 三项保留在 `packages/app/src/config/request.ts`，不下沉 core |
+| **理由** | ① 业务码字段名（code/data/message）属公司级业务约定，不同后端可能用 errno/result/msg；② basePath 来自 `import.meta.env.VITE_API_BASE_PATH` 是 app 构建期常量，core 包构建期不可知；③ NG-1 硬约束：业务壳层留 app |
+| **备选方案 A** | 与列表 KEY 配置一起下沉 core，通过 IoC 注入 |
+| **A 否决理由** | NG-1 + NG-2 双重否决；核心理由——列表分页是 admin 通用结构，业务码是公司业务特征，性质不同 |
+| **状态** | 活跃 |
+
+---
+
+## 3. 关键技术点设计
+
+### 3.1 REQ-1：dot-path.ts（新建）
+
+**路径：** `packages/core/src/types/dot-path.ts`
+
+**实现样例（直接采纳 requirements.md 锁定方案）：**
+
+```ts
+/**
+ * 列表 KEY 配置接口
+ * 约束消费方传入的 KEY_CONFIG 对象 shape，后续 BuildListModel / BuildListParams 工具基于本接口推导
+ */
+export interface ListModelKeyConfig {
+  PAGE_SIZE_KEY: string;
+  CURRENT_PAGE_KEY: string;
+  TOTAL_KEY: string;
+  LIST_KEY: string;
+}
+
+/**
+ * 字符串点路径转嵌套对象类型
+ * @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> }
+  : { [K in P]: V };
+
+/**
+ * 联合类型转交叉类型
+ * 用于多个 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;
+
+/**
+ * 基于 KEY_CONFIG 联合推导完整列表响应模型
+ * @example
+ *   BuildListModel<typeof APP_API_LIST_MODEL_KEY_CONFIG, User>
+ *     -> { items: User[]; page: { page: number; pageSize: number; totalRecord: number } }
+ */
+export type BuildListModel<KC extends ListModelKeyConfig, T> = UnionToIntersection<
+  | DotToObject<KC["LIST_KEY"], T[]>
+  | DotToObject<KC["TOTAL_KEY"], number>
+  | DotToObject<KC["CURRENT_PAGE_KEY"], number>
+  | DotToObject<KC["PAGE_SIZE_KEY"], number>
+>;
+
+/**
+ * 基于 KEY_CONFIG 联合推导列表请求参数模型
+ * @example
+ *   BuildListParams<typeof APP_API_LIST_MODEL_KEY_CONFIG, { keyword?: string }>
+ *     -> { keyword?: string } & { page: { page: number; pageSize: number } }
+ */
+export type BuildListParams<
+  KC extends ListModelKeyConfig,
+  P extends Record<string, any> = Record<string, any>,
+> = P &
+  UnionToIntersection<
+    DotToObject<KC["CURRENT_PAGE_KEY"], number> | DotToObject<KC["PAGE_SIZE_KEY"], number>
+  >;
+```
+
+**类型断言验证（开发实施时手写到验证脚本）：**
+
+```ts
+type Equal<X, Y> =
+  (<T>() => T extends X ? 1 : 2) extends <T>() => T extends Y ? 1 : 2 ? true : false;
+
+type _A1 = Equal<DotToObject<"page.page", number>, { page: { page: number } }>;        // true
+type _A2 = Equal<DotToObject<"items", string[]>, { items: string[] }>;                  // true
+type _A3 = Equal<
+  UnionToIntersection<{ a: { x: 1 } } | { a: { y: 2 } }>,
+  { a: { x: 1; y: 2 } }
+>;                                                                                       // true
+```
+
+### 3.2 REQ-2 + REQ-3：list-model.ts（新建）
+
+**路径：** `packages/core/src/config/list-model.ts`
+
+**实现样例（直接采纳 requirements.md 锁定方案）：**
+
+```ts
+import type { BuildListModel, BuildListParams } from "../types/dot-path";
+
+/** 应用接口列表模型配置（core 单一来源） */
+export const APP_API_LIST_MODEL_KEY_CONFIG = Object.freeze({
+  /** 当前页码 key */
+  CURRENT_PAGE_KEY: "page.page" as const,
+  /** 每页条数 key */
+  PAGE_SIZE_KEY: "page.pageSize" as const,
+  /** 总数 key */
+  TOTAL_KEY: "page.totalRecord" as const,
+  /** 数据列表 key */
+  LIST_KEY: "items" as const,
+});
+
+/** 应用接口列表模型 */
+export type AppApiListModel<T = any> = BuildListModel<typeof APP_API_LIST_MODEL_KEY_CONFIG, T>;
+
+/** 应用接口列表分页参数 key */
+export type AppApiListPageParamsKey =
+  | typeof APP_API_LIST_MODEL_KEY_CONFIG.PAGE_SIZE_KEY
+  | typeof APP_API_LIST_MODEL_KEY_CONFIG.CURRENT_PAGE_KEY;
+
+/** 应用 排除分页参数的 key */
+export type AppNoPageParamsKey = Exclude<string, AppApiListPageParamsKey>;
+
+/** 应用接口列表请求参数模型 */
+export type AppApiListParamsModel<
+  P extends Record<AppNoPageParamsKey, any> = Record<AppNoPageParamsKey, any>,
+> = BuildListParams<typeof APP_API_LIST_MODEL_KEY_CONFIG, Partial<P>>;
+```
+
+**core/src/index.ts 追加 re-export（在 `export * from "./types"` 之后追加 2 行）：**
+
+```ts
+// 已有：
+// export * from "./types";
+
+// 追加：
+export * from "./types/dot-path";
+export * from "./config/list-model";
+```
+
+> 注意：`./types` 当前若已 barrel-export 全部 `./types/*`，则 `./types/dot-path` 会被自动覆盖；本设计 [MUST] 在实施时检查 `core/src/types/index.ts`（若存在）是否已 `export * from "./dot-path"`。若 `core/src/types/` 当前无 barrel 文件，则在 `core/src/index.ts` 显式 re-export 子文件。
+
+### 3.3 REQ-4：app/components/table/types.ts 重写
+
+**改造点（仅 `TableApiParams` + `TableApiResult` 2 类型，其他 7 类型不动）：**
+
+```ts
+// 改造前
+import type { APP_API_LIST_MODEL_KEY_CONFIG, AppApiListModel } from "@/config";
+
+export type TableApiParams<
+  SQ extends Record<string, any> = Record<string, any>,
+> = SQ & {
+  [APP_API_LIST_MODEL_KEY_CONFIG.CURRENT_PAGE_KEY]: number;
+  [APP_API_LIST_MODEL_KEY_CONFIG.PAGE_SIZE_KEY]: number;
+};
+
+export type TableApiResult<
+  T extends Record<string, any> = Record<string, any>,
+> = Pick<
+  AppApiListModel<T>,
+  | typeof APP_API_LIST_MODEL_KEY_CONFIG.TOTAL_KEY
+  | typeof APP_API_LIST_MODEL_KEY_CONFIG.LIST_KEY
+>;
+
+// 改造后
+import type {
+  APP_API_LIST_MODEL_KEY_CONFIG,
+  BuildListParams,
+  DotToObject,
+  UnionToIntersection,
+} from "@/config";
+
+/** 表格请求参数 = 静态参数 SQ + KEY_CONFIG 推导出的 page.page / page.pageSize 嵌套 */
+export type TableApiParams<
+  SQ extends Record<string, any> = Record<string, any>,
+> = BuildListParams<typeof APP_API_LIST_MODEL_KEY_CONFIG, SQ>;
+
+/** 表格响应结果 = items 列表 + page.totalRecord 总数（仅 2 字段子集，不要 page.page / page.pageSize）*/
+export type TableApiResult<
+  T extends Record<string, any> = Record<string, any>,
+> = UnionToIntersection<
+  | DotToObject<typeof APP_API_LIST_MODEL_KEY_CONFIG.LIST_KEY, T[]>
+  | DotToObject<typeof APP_API_LIST_MODEL_KEY_CONFIG.TOTAL_KEY, number>
+>;
+```
+
+**等价验证（vue-tsc 通过后人工核对）：**
+
+| 类型 | 推导结果 |
+|---|---|
+| `TableApiParams<{ keyword?: string }>` | `{ keyword?: string } & { page: { page: number; pageSize: number } }` |
+| `TableApiResult<{ id: number }>` | `{ items: { id: number }[] } & { page: { totalRecord: number } }` |
+
+**[MUST NOT] 改动的 7 类型：** `TableMainInstance` / `TableColumnDefaultScope` / `TableColumnComponentProps` / `TableColumnHeaderScope` / `ExtractElTableColumnProps` / `ElTableColumnProps` / `TableMainProps`。
+
+**`@/config` re-export 链路：** REQ-2 已要求 `app/src/config/request.ts` 从 core re-export 5 项；本 REQ 新增 import 的 `BuildListParams` / `DotToObject` / `UnionToIntersection` 同样需在 `app/src/config/request.ts` 内补 re-export，或通过 `app/src/config/index.ts` barrel 直接 `export * from "@done-coding/admin-core"` 一次到位（实施时择优）。
+
+### 3.4 REQ-5：TableMain.vue 4 处运行时改造
+
+**改造点 1+2（`params` computed 构造，行 161-167）：**
+
+```ts
+// 改造前
+const params = computed<TableApiParams<SQ>>(() => {
+  return {
+    ...(props.query! || {}),
+    [APP_API_LIST_MODEL_KEY_CONFIG.PAGE_SIZE_KEY]: pageSize.value,
+    [APP_API_LIST_MODEL_KEY_CONFIG.CURRENT_PAGE_KEY]: currentPage.value,
+  };
+});
+
+// 改造后
+const params = computed<TableApiParams<SQ>>(() => {
+  const merged = _cloneDeep(props.query || {}) as TableApiParams<SQ>;
+  _set(merged, APP_API_LIST_MODEL_KEY_CONFIG.PAGE_SIZE_KEY, pageSize.value);
+  _set(merged, APP_API_LIST_MODEL_KEY_CONFIG.CURRENT_PAGE_KEY, currentPage.value);
+  return merged;
+});
+```
+
+**改造点 3+4（响应数据读取，行 212-215）：**
+
+```ts
+// 改造前
+list.value = res[APP_API_LIST_MODEL_KEY_CONFIG.LIST_KEY] as UnwrapRef<T[]>;
+total.value = res[APP_API_LIST_MODEL_KEY_CONFIG.TOTAL_KEY];
+
+// 改造后
+list.value = _get(res, APP_API_LIST_MODEL_KEY_CONFIG.LIST_KEY) as UnwrapRef<T[]>;
+total.value = _get(res, APP_API_LIST_MODEL_KEY_CONFIG.TOTAL_KEY);
+```
+
+**imports 调整（脚本顶部新增 2 行，保留现有 `_cloneDeep` / `_omit`）：**
+
+```ts
+import _cloneDeep from "lodash/cloneDeep";
+import _omit from "lodash/omit";
+import _set from "lodash/set";   // 新增
+import _get from "lodash/get";   // 新增
+```
+
+**关键约束验证：** `props.query` 已含 `{ page: { query: ..., orderBy: ... } }` 时，`_cloneDeep(props.query)` + `_set(merged, "page.page", N)` 仅更新 `page.page` 与 `page.pageSize` 字段，不覆盖 `page.query` / `page.orderBy` —— lodash set 自动 merge 中间对象，不打覆盖。
+
+### 3.5 REQ-6：core docs/TECH_SNAPSHOT.md 起步版骨架
+
+**路径：** `packages/core/docs/TECH_SNAPSHOT.md`（新建）
+
+**4 章节要点（实施时按本骨架填充）：**
+
+```markdown
+# @done-coding/admin-core 技术架构快照
+
+## 1. 设计边界
+
+### 1.1 包含范围（✓）
+- 通用 admin 基础设施组件（form / menu / display / misc）
+- 通用列表分页结构（APP_API_LIST_MODEL_KEY_CONFIG / AppApiListModel<T>）
+- dot-path 类型工具（DotToObject / UnionToIntersection / BuildListModel / BuildListParams）
+- 通用 hooks / utils / types
+
+### 1.2 排除范围（✗，业务壳层永不下沉）
+- 业务码外壳（APP_API_BUSINESS_MODEL_KEY_CONFIG / AppApiBusinessModel<T>）
+- 业务接口配置（APP_REQUEST_CONFIG，含 basePath / timeout）
+- 业务路由 / 业务枚举
+- IoC 注入式 KEY 配置（一个月内不引入）
+
+## 2. 已知约束
+
+### 2.1 分页 KEY 固化
+- 4 KEY 取值在 core 内固化为公司级约定（page.page / page.pageSize / page.totalRecord / items）
+- 类型层与运行时层均从 typeof KEY_CONFIG 推导，禁止手写嵌套字面量（NG-7）
+
+### 2.2 pnpm patch 逃生通道
+- 消费方自定义分页字段时通过 pnpm patch @done-coding/admin-core 重写已发布产物的 KEY 取值
+- 最小步骤：
+  1. pnpm patch @done-coding/admin-core
+  2. 修改 patch 目录下 es/index.mjs / lib/index.cjs / types/index.d.ts 中 APP_API_LIST_MODEL_KEY_CONFIG 取值
+  3. pnpm patch-commit <patch-dir>
+  4. 重启 dev / 重新 build
+- 警示：不通过业务运行时配置覆盖 KEY，会失去类型推导能力（typeof 推导依赖编译期常量）
+
+## 3. 类型工具说明
+
+### 3.1 DotToObject<P, V>
+- 字符串点路径转嵌套对象类型
+- 输入：`"a.b.c"` + `V` → 输出：`{ a: { b: { c: V } } }`
+
+### 3.2 UnionToIntersection<U>
+- 联合类型转交叉
+- 用于多个 DotToObject 结果合并
+
+### 3.3 BuildListModel<KC, T>
+- 基于 KEY_CONFIG 联合推导完整列表响应模型
+- 输入：`typeof KEY_CONFIG` + `T` → 输出：`{ items: T[]; page: { page; pageSize; totalRecord } }`
+
+### 3.4 BuildListParams<KC, P>
+- 基于 KEY_CONFIG 联合推导列表请求参数模型
+- 输入：`typeof KEY_CONFIG` + `P` → 输出：`P & { page: { page; pageSize } }`
+
+## 4. 架构决策记录 (ADR)
+
+### ADR-1：4 工具 2 层架构（基础 + 应用）
+（同本任务 design.md ADR-1 摘要）
+
+### ADR-2：core 单一来源 + app re-export
+（同本任务 design.md ADR-2 摘要）
+
+### ADR-3：DUCK 最小化 + typeof KEY_CONFIG 推导
+（同本任务 design.md ADR-3 摘要）
+
+### ADR-4：取消双份 + pnpm patch 逃生通道
+（同本任务 design.md ADR-4 摘要）
+
+### ADR-5：业务壳层永不下沉 core
+（同本任务 design.md ADR-5 摘要）
+```
+
+### 3.6 REQ-7：core README.md 进阶用法节骨架
+
+**追加节（在现有「使用」节之后）：**
+
+```markdown
+## 进阶用法
+
+### 自定义分页字段（pnpm patch 逃生通道）
+
+`@done-coding/admin-core` 的列表分页 KEY 配置（`APP_API_LIST_MODEL_KEY_CONFIG`）在 core 包内**固化为公司级约定**：
+
+```ts
+{
+  CURRENT_PAGE_KEY: "page.page",
+  PAGE_SIZE_KEY:    "page.pageSize",
+  TOTAL_KEY:        "page.totalRecord",
+  LIST_KEY:         "items",
+}
+```
+
+若消费方后端约定不同（如 `current` / `size` / `total` / `list`），通过 pnpm patch 在工具链层重写：
+
+```bash
+# 1. 创建 patch
+pnpm patch @done-coding/admin-core
+
+# 2. 编辑临时目录下的 es/index.mjs / lib/index.cjs / types/index.d.ts
+#    将 APP_API_LIST_MODEL_KEY_CONFIG 取值改为消费方约定
+#    （注意类型 d.ts 中的字符串字面量也要同步改）
+
+# 3. 提交 patch
+pnpm patch-commit <临时目录>
+
+# 4. 重启 dev / 重新 build
+```
+
+**[MUST NOT]** 在业务运行时通过 plugin 配置 / 全局变量 / 工厂函数覆盖 KEY 取值——会让 `typeof KEY_CONFIG` 类型推导失效（编译期常量），等于自废 dot-path 工具能力。详见 [TECH_SNAPSHOT 已知约束](./docs/TECH_SNAPSHOT.md#22-pnpm-patch-逃生通道)。
+```
+
+---
+
+## 4. 开发范式 / 参考模块
+
+| 范式 | 来源 / 参考 |
+|---|---|
+| 单文件类型工具 | `packages/core/src/types/dot-path.ts`（新建，本任务） |
+| `Object.freeze` + `as const` 配置常量 | 现有 `packages/app/src/config/request.ts` 已有 `APP_API_BUSINESS_MODEL_KEY_CONFIG` |
+| `BuildListModel` / `BuildListParams` 高阶组合 | 本次新建，无既有参考 |
+| lodash `_set` / `_get` 操作点路径 | `packages/app/src/components/table/TableMain.vue` 已用 `_cloneDeep` / `_omit`，新增 2 工具同族 |
+| core 包内子目录 barrel re-export | 现有 `packages/core/src/index.ts` 行 8-14（`export * from "./components/form"` 等） |
+| `Pick<>` / `Exclude<>` / `Partial<>` 工具类型组合 | 现有 `packages/app/src/components/table/types.ts` 已用 |
+
+---
+
+## 5. 风险登记表
+
+| # | 风险 | 严重度 | 应对策略 | 验证方式 |
+|---|---|---|---|---|
+| **R1** | 跨包 d.ts 同步：core 改后 app dev/build 是否能自动消费最新类型？vite-plugin-dts 是否 watch 模式？ | 中 | core 的 `dev` 脚本已是 `vite build -w -m hotBuild`（package.json 行 28），watch 模式启用；首次切源时 [MUST] 先在 core 目录跑 `pnpm build` 生成 d.ts，再启 app dev，确保 `node_modules/@done-coding/admin-core/types/index.d.ts` 已含新导出 | 实施 TASK-3.1：`pnpm -F @done-coding/admin-core build` 后再启 app `pnpm dev`，验证 vue-tsc 无报错 |
+| **R2** | lodash 依赖归属：core 是否需要显式声明 lodash 依赖？ | 低 | 已确认：`packages/core/package.json` 行 71 已在 peerDependencies 声明 `lodash: ^4.17.21`；类型 `@types/lodash` 已在 devDependencies 行 51。core 内 import `lodash/get` 等子模块类型可解析 | 实施 TASK-1.1：检查 `core/src/types/dot-path.ts` 内**纯类型**实现不需要 import lodash；list-model.ts 同样仅类型，无需 import lodash。core 包内本任务实际不引入新的 lodash runtime import |
+| **R3** | app re-export 后 vue-tsc 类型链路是否正确解析？`@/config` barrel 多层转出 + tsconfig paths 是否产生类型推导黑洞 | 中 | 实施前 [MUST] Read `packages/app/src/config/index.ts` 确认 barrel 形态；改造后 vue-tsc 跑全量 + 抽样业务页（Page1.vue 类）vue-tsc 验证；若出现类型推导降级（推导成 `any`），降级方案：业务页直接 `import { APP_API_LIST_MODEL_KEY_CONFIG } from "@done-coding/admin-core"` 跳过 barrel | TASK-3.1 / TASK-3.2 类型断言 + 业务页抽样 |
+| **R4** | pnpm patch 重写 KEY runtime 时 typeof 推导是否随之更新？ | 中 | typeof 推导基于 d.ts 中的字符串字面量类型；pnpm patch 同步改写 `types/index.d.ts` 中 `APP_API_LIST_MODEL_KEY_CONFIG` 的 `as const` 字面量；README 进阶用法节明文提示「3 文件同步改」（es / lib / types） | 本任务不实测 patch（验证由消费方接收），但 README 文档需含明文警示 |
+| **R5** | TableApiResult 改用 `DotToObject + UnionToIntersection` 后，业务侧 `as UnwrapRef<T[]>` 断言是否仍编译通过？ | 低 | `_get(res, "items")` 返回 `T[] \| undefined`（lodash get 类型签名），断言 `as UnwrapRef<T[]>` 在类型层强转，与改造前 `res["items"] as UnwrapRef<T[]>` 等价 | TASK-3.1 vue-tsc + TASK-3.3 业务页 dev 回归 |
+| **R6** | `_cloneDeep(props.query)` 类型断言到 `TableApiParams<SQ>` 时，TS 可能因结构不完整报错（缺 `page` 字段） | 中 | 用 `as TableApiParams<SQ>` 强制断言（merged 在 `_set` 后会补齐 page 子对象）；这是合理的"过程态"断言。若 TS 仍拒绝，降级为 `as unknown as TableApiParams<SQ>` 二次断言 | TASK-2.3 vue-tsc 验证 |
+
+---
+
+## 6. 任务粒度预案（tasks.md 拆分草案）
+
+3 批共 11 TASK，每个 TASK 满足 ≤ 3 文件 / ≤ 5 步骤。
+
+### 批次一：core 类型工具 + 配置 + 文档骨架（5 TASK）
+
+| TASK | 描述 | 文件数 | 步骤数 | 可并行 |
+|---|---|---|---|---|
+| TASK-1.1 | 新建 `core/src/types/dot-path.ts`（4 工具 + ListModelKeyConfig 接口） | 1 | 5（ListModelKeyConfig / DotToObject / UnionToIntersection / BuildListModel / BuildListParams） | 与 1.2 串行（1.2 import 1.1）|
+| TASK-1.2 | 新建 `core/src/config/list-model.ts`（const + 4 type） | 1 | 5（const + AppApiListModel + AppApiListPageParamsKey + AppNoPageParamsKey + AppApiListParamsModel） | 依赖 1.1 |
+| TASK-1.3 | 修改 `core/src/index.ts` 追加 2 行 re-export | 1 | 2 | 依赖 1.1+1.2 |
+| TASK-1.4 | 新建 `core/docs/TECH_SNAPSHOT.md`（4 章节起步版） | 1 | 4 | 与 1.1-1.3 并行 ✓ |
+| TASK-1.5 | 修改 `core/README.md` 追加进阶用法节 | 1 | 1 | 与 1.1-1.3 并行 ✓ |
+
+**批次一里程碑：** core 包 `pnpm build` 通过，`types/index.d.ts` 含 `APP_API_LIST_MODEL_KEY_CONFIG` / `AppApiListModel` / `BuildListModel` / `BuildListParams` 等导出。
+
+### 批次二：app 切源 + table 改造（3 TASK）
+
+| TASK | 描述 | 文件数 | 步骤数 | 可并行 |
+|---|---|---|---|---|
+| TASK-2.1 | 修改 `app/src/config/request.ts` 删除 5 项 + 从 core re-export | 1 | 3（删 5 项 / 加 import + re-export / 验证 `@/config` 消费面） | 依赖批次一 |
+| TASK-2.2 | 修改 `app/src/components/table/types.ts` 重写 `TableApiParams` + `TableApiResult` | 1 | 3（改 import / 重写 TableApiParams / 重写 TableApiResult） | 依赖 2.1 |
+| TASK-2.3 | 修改 `app/src/components/table/TableMain.vue` 4 处运行时改造 | 1 | 5（加 2 import / 改 params 改造点 1 / 改 params 改造点 2 / 改响应 LIST 读取 / 改响应 TOTAL 读取） | 依赖 2.2 |
+
+**批次二里程碑：** app 包 `pnpm build` + `vue-tsc` 通过；类型抽样验证 `TableApiParams<{keyword?: string}>` 推导为预期形态。
+
+### 批次三：验证（3 TASK）
+
+| TASK | 描述 | 文件数 | 步骤数 | 可并行 |
+|---|---|---|---|---|
+| TASK-3.1 | vue-tsc 类型断言验证（Equal 单元测试 + 业务页全量类型扫描） | 0（仅运行验证） | 3（写临时 .ts 类型断言文件 / 跑 vue-tsc / 删临时文件） | 依赖批次二 |
+| TASK-3.2 | `pnpm build` 在 core + app 双向通过 | 0 | 2（`pnpm -F @done-coding/admin-core build` / `pnpm -F app build`） | 依赖批次二 |
+| TASK-3.3 | 业务页 dev 回归（如 Page1.vue / 抽样 1-2 个 list-page 业务页） | 0 | 3（启 app dev / 触发表格分页+搜索+排序 / 对比改造前后行为） | 依赖批次二 |
+
+**总计：** 11 TASK，每个 TASK ≤ 3 文件（实际全部 ≤ 1 文件）+ ≤ 5 步骤 ✓。
+
+---
+
+## 7. 验证策略
+
+### 7.1 类型层验证
+
+| 验证点 | 命令 | 预期 |
+|---|---|---|
+| dot-path 4 工具 Equal 类型断言 | TASK-3.1 临时 `.ts` 文件 + `pnpm -F @done-coding/admin-core build` | vue-tsc 通过；3 个 `Equal` 类型推导为 `true` |
+| AppApiListModel 推导验证 | 同上 | `Equal<AppApiListModel<{id:1}>, {items:{id:1}[]; page:{page:number; pageSize:number; totalRecord:number}}>` = true |
+| TableApiParams 推导验证 | 同上 | `Equal<TableApiParams<{keyword?:string}>, {keyword?:string} & {page:{page:number; pageSize:number}}>` = true |
+| TableApiResult 推导验证 | 同上 | `Equal<TableApiResult<{id:number}>, {items:{id:number}[]} & {page:{totalRecord:number}}>` = true |
+
+### 7.2 构建层验证
+
+| 验证点 | 命令 | 预期 |
+|---|---|---|
+| core 包构建 | `pnpm -F @done-coding/admin-core build` | exit 0；产物 `packages/core/types/index.d.ts` 含 4 工具 + 5 项配置/类型 |
+| app 包构建 | `pnpm -F app build` | exit 0；产物正常打包 |
+
+### 7.3 运行时层验证
+
+| 验证点 | 操作 | 预期 |
+|---|---|---|
+| 业务页表格分页 | 启 app dev → 打开抽样 list-page → 切换页码 | 请求参数 body 含 `{ page: { page: N, pageSize: 20, ...原 page 字段 } }`；响应解析正确显示列表 |
+| 业务页表格搜索 | 同上 → 输入搜索条件 | 请求参数中 `props.query` 字段（如 `keyword`）正确合入；分页字段正确 |
+| 业务页表格排序 | 同上 → 切换排序列 | `props.query.page.orderBy`（若有）保留；不被 `_set("page.page", N)` 覆盖 |
+| `props.query` 含 `page.query` | mock `props.query = { page: { query: {...} } }` | `_set("page.page", N)` 后 merged 同时含 `page.query` 与 `page.page` / `page.pageSize` |
+
+---
+
+## 8. 自查记录（架构师同 agent 自查清单）
+
+| # | 自查项 | 状态 |
+|---|---|---|
+| 1 | design.md 与 requirements.md 一致性（无矛盾、无遗漏 REQ） | ✓ REQ-1 ~ REQ-7 全部覆盖到 §3.1-3.6；NG-1 ~ NG-7 全部映射到 §1.3 Out-of-Scope 与 ADR-3/4/5 |
+| 2 | DUCK + typeof KEY_CONFIG 推导原则贯彻每一行类型设计 | ✓ AppApiListModel / AppApiListParamsModel / TableApiParams / TableApiResult 全部从 `typeof APP_API_LIST_MODEL_KEY_CONFIG.XXX_KEY` 推导；零手写嵌套字面量；ADR-3 + NG-7 双重锁定 |
+| 3 | 变更范围防火墙完整（4 段都填） | ✓ §1 含 Direct Targets（8 处）/ Collateral Reads（4 项）/ Out-of-Scope（6 项）/ Self-Healing Rule |
+| 4 | 5 条 ADR 齐全 + 每条理由完整 | ✓ ADR-1 ~ ADR-5 全部含决策 / 理由 / 备选方案 / 否决理由 / 状态 5 字段 |
+| 5 | 风险登记 ≥ 4 条 + 每条含缓解策略 | ✓ R1 ~ R6 共 6 条，每条含描述 / 严重度 / 应对策略 / 验证方式 |
+| 6 | 任务粒度满足 ≤ 3 文件 / ≤ 5 步骤（每个 TASK 自检） | ✓ §6 共 11 TASK，每个 TASK 实际均 ≤ 1 文件 + ≤ 5 步骤 |
+| 7 | U+FFFD 乱码自检 | ✓ 全文无 U+FFFD 字符 |
+| 8 | 与 NG-1 ~ NG-7 无任何冲突 | ✓ NG-1 (业务壳层) → §1.3 #1 + ADR-5；NG-2 (IoC) → ADR-4；NG-3 (组件本体) → §1.3 #2；NG-4 (request.ts) → §1.3 #1；NG-5 (数组路径) → §1.3 #5；NG-6 (CI 检查) → §1.3 #4；NG-7 (字面量) → ADR-3 + §1.3 #6 |
+
+**自查结论：** 8 项全 ✓ → frontmatter 已标记「审核状态: 已通过」。