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

package/README.md

@@ -0,0 +1,48 @@
+# @done-coding/admin-core
+
+```
+后台管理核心
+```
+
+## 使用
+
+```bash
+npm install @done-coding/admin-core
+```
+
+## 进阶用法
+
+### 自定义分页字段（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. 编辑临时目录下 3 个产物文件（必须同步改）
+#    - es/index.mjs        （ESM 运行时）
+#    - lib/index.cjs       （CJS 运行时）
+#    - types/index.d.ts    （as const 字符串字面量类型，必须同步以保 typeof 推导）
+#    将 APP_API_LIST_MODEL_KEY_CONFIG 4 KEY 取值改为消费方约定
+
+# 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-逃生通道)。

package/docs/TECH_SNAPSHOT.md

@@ -0,0 +1,146 @@
+# @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/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/RETROSPECTIVE.md

@@ -0,0 +1,63 @@
+# 任务复盘 — 列表 KEY 配置点路径支持（前置任务）
+
+> 任务路径：`packages/core/docs/specs/2026-05-09-055250-moderate-列表key配置点路径支持/`
+> 任务等级：Moderate
+> 完成日期：2026-05-09
+> 复盘者：PM (pm-delivery)
+
+## 任务复盘
+
+### 执行自评
+────────────────────
+专注力集中值：85    全程未漏 NG 约束（特别是 NG-7 typeof KEY_CONFIG 推导）；用户重申原则后及时修订 REQ-4 A 项
+工作量：60          改动量 6/10，机械化系数中（类型工具设计为决策密集 ×1.5；切源 + 改 lodash 为高机械化 ×0.4）→ 实际成本 ≈ 4
+任务关联度：90      所有 7 文件围绕同一目标（KEY 配置 core 单一来源 + dot-path 推导贯彻），关联度极高
+可验证证据：
+  - REQ 修订次数：1 次（REQ-4 A 项 a→b，用户主动否决"完整复用 sugar"违反 DUCK 原则）
+  - 偏离 design.md 次数：2 次（mock 修复 + barrel 追加，均在 design.md §3.3 允许范围内）
+  - vue-tsc / build / dev 一次通过率：3/3
+  - 跨阶段中断次数：0
+吐槽：开始时把 4 个工具的"作用 / 用途"塞在命名表格里没讲清，被用户指正"命名没说作用"——以后类型工具介绍 [MUST] 先讲一句话作用 + 输入输出举例
+────────────────────
+
+### 决策回顾
+
+**关键决策 1：BuildListModel sugar 是否取消**
+- 当时方案：保留 BuildListModel 工具
+- 判断依据：sugar 工具本身不违反 DUCK，使用方决定是否冗余；TableApiResult 用基础工具组合（DotToObject + UnionToIntersection）即可保证 DUCK
+- 实际结果：BuildListModel 在 list-model.ts 内被 AppApiListModel 用，TableApiResult 用基础工具——两条路径共存
+- 回顾评价：**正确**——保留了 sugar 的便利性同时不强制使用方接受冗余字段，符合"分层架构"价值
+
+**关键决策 2：设计审核简化（同 architect agent 自查）**
+- 当时方案：跳过 superpowers:code-reviewer subagent + 上下游预审五步流程
+- 判断依据：用户主动裁决——任务约束已充分（DUCK + typeof + 实现样例已锁），AI 自由发挥空间小，基本是执行
+- 实际结果：架构师 agent 自查 8/8 通过；实施阶段无返工
+- 回顾评价：**正确**——流程匹配复杂度，节省了不必要的派发开销；如果有方案空间则不该简化
+
+**关键决策 3：Self-Healing Rule 修复 mock bug**
+- 当时方案：发现 src/api/mock/index.ts 7 处类型错（design 阶段未穷举到该路径），修复一次
+- 判断依据：与 design 同方向（嵌套 shape + lodash get/set），未引入新设计
+- 实际结果：tasks.md TASK-3.1 写明 bug + 修复 + 验证证据齐全
+- 回顾评价：**正确**——遵守 Self-Healing 一次修复纪律；R3 风险登记记录"未穷举到 src/api/"作为期 #2 启动前的扫描提醒
+
+────────────────────
+
+## 学到的（写入长期记忆）
+
+| 时机 | 学到 | 已落 |
+|---|---|---|
+| 用户重申"DUCK 最小化 + typeof 推导"原则后我仍逐项问子决策 | 「先问原则，按原则推下游」协作模式 | ✅ `feedback_principles_over_answers.md` |
+| 用户指出"工作量不能纯看改动量" | 工作量双维度评估（改动量 + 机械化系数） | ✅ `feedback_workload_mechanical.md` |
+| 用户指出"specs 应落子项目而非 workspace" | 子项目内部任务 specs 落子项目 docs/specs/ | ✅（之前会话）`feedback_specs_location.md` |
+
+## 后续行动（期 #2 立项时一并处理）
+
+1. **app TECH_SNAPSHOT 更新**：本任务 app 端有 4 文件改动（request.ts / table/types.ts / TableMain.vue / config/index.ts），应更新 `packages/app/docs/TECH_SNAPSHOT.md` 反映「list-model 已切 core」+「table 运行时 lodash 改造」——推迟到期 #2 完成后一并更新
+2. **Portfolio 更新**：当前工作区 `done-coding-admin-monorepo_split_new` 在 `~/.claude/company/capabilities/projects/` 中无对应条目，期 #2 完成后一并补建
+3. **期 #2 启动前**：扫描 app 中是否还有用 `[KEY.XXX_KEY]` 索引签名的"漏网"代码（按 Self-Healing Rule R3 风险）
+
+## 验收记录
+
+- 用户「整体通过」：2026-05-09 07:58（需求阶段）
+- 全栈开发自查 8/8：2026-05-09 08:21（实施阶段）
+- 用户「同意立项开工」（含本前置任务最终验收）：2026-05-09（睡前）