@done-coding/admin-core 0.24.0 → 0.25.0

package/src/components/app-layout/docs/README-AppHeader.md

@@ -10,6 +10,14 @@
 - 中间区 = 路由大模块菜单（menus 渲染，点击高亮 activeModulePath）
 - 整体显隐由 AppLayout 间接控制（store headerStyle.height=0 视觉收起 + dom 保留）
 
+## 模块条徽标（badge）
+
+模块条的每一项以其路由 **`path` 为 key** 查 `bridge.badge` 注册表，命中则渲染绝对定位角标（数量 / 新上线 / 更新 / 内测 / 开发 / 自定义），**不压字、不改变宿主尺寸**；未命中零影响、无需在菜单数据里加字段。
+
+与 AppSidebar 菜单树同一份注册表、同一套 key 规则——同一个 `path` 在两处显示同一个标。
+
+> AppHeader 的模块条是**自建实现**（扁平一级 + 横向滚动 + `router.push` 切模块），不走 `MenuTree`；徽标是两处各自接入的，行为对齐。契约见 [bridge 文档 · 徽标注册表](../../../bridge/docs/README.md)。
+
 ## 快速上手（最小可用）
 
 经 AppLayout 内容锚填充后由 shell 落位（App.vue 范式——#brand/#userEntry 即 Header #left/#right 的内容来源）：

package/src/components/app-layout/docs/README-AppLayout.md

@@ -32,8 +32,32 @@ App.vue 总装配——三个必填注入 + 两个必填内容锚即完整可跑
 - `watermarkContent`：默认不展示水印；仅需要页面水印时填内容（空数组/空串/undefined 即关闭；显隐走 content 切换，无独立开关 prop）。
 - `sidebarAboveHeader`：默认 `false` 即够用；仅当 sidebar 需要 z-index 盖住 header 悬浮时开。
 - **布局形态深度定制**：内置默认经典布局 shell 已可用（行为基线 [MUST NOT] 借重构改）；仅当落位/折叠策略不满足时才走布局插件自供 shell（AppShell 契约）——AppLayout 本身不动。
+- **单页全屏 / 关动画**（路由级，非 prop）：走 `meta.layout` 两个可选项——见下「路由级布局开关」。
 - **完整能力演示**（五锚全填 + 水印 + 自供 shell）：`apps/reference/src/App.vue`、`apps/reference/src/pages/app-layout/shell/`——能力展示，非最小起点。
 
+## 路由级布局开关（`meta.layout`）
+
+除既有的 `header` / `sidebar` / `aside` / `footer` / `breadcrumb` / `bodyShimPadding`，还有两个整页形态开关：
+
+| 选项 | 默认 | 语义 |
+| --- | --- | --- |
+| `noViewportPadding` | `false` | 全屏展示：viewport 四边套框留白归零 |
+| `noAnimation` | `false` | 进入本路由不做布局过渡动画（登录页 / 全屏页） |
+
+```ts
+{ path: "fullscreen", meta: { title: "全屏页", layout: { noViewportPadding: true, noAnimation: true } } }
+```
+
+**`noViewportPadding` 归零的是两条链，且同源**：① core 内部几何（header/sidebar/aside/footer/body 的 fixed 锚点与 minHeight）；② 对外 `--dc-core-viewport-*` CSS var（浮层 / 主题 decor / 业务页 CSS 消费）。二者都读 store 的 `viewportConfigEffective`，[MUST NOT] 让任一条回退成直读 bridge——只归零一边就是半吊子全屏（内容贴边了，读 CSS var 的浮层仍按套框内缘定位）。
+
+配套：主题的套框装饰（`useFrameGeometry` → `hasFrame`）随之整层不渲染。
+
+**只管最外圈套框留白**，不影响模块间距 `gap` —— 该页若仍开着 header/sidebar，模块之间的内缝照旧。
+
+**`noAnimation`** 挂 `app-layout_noAnimation` 根类，与既有的「未登录关动画」`app-layout_noLogin` **并列**（互不替代，共用同一份 `transition: none` 规则）。
+
+> 范式页：`apps/reference/src/pages/app-layout/viewport-fullscreen/`——同一个组件挂两条路由、只差 meta，来回切即对照。
+
 ## API
 > ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
 

package/src/components/display/README.md

@@ -1,11 +1,12 @@
 # display 展示族
 
-展示与交互原语：TabsMain（Tab 容器）/ ActionBtn 系列（确认闸门 + 自动 loading）/ 尺寸与高度工具（WatchSize / HeightProvider）/ BooleanTag / ShadowClone（影分身双渲染位）。
+展示与交互原语：TabsMain（Tab 容器）/ ActionBtn 系列（确认闸门 + 自动 loading + 徽标）/ 尺寸与高度工具（WatchSize / HeightProvider）/ BooleanTag / ShadowClone（影分身双渲染位）。
 
 ## 组件文档（docs/）
 
-- [TabsMain](./docs/README-TabsMain.md) — Tab 容器（channel 嵌套 / tile 平铺 / query 同步）
-- [ActionBtn](./docs/README-ActionBtn.md) — ElButton 超集（confirm 闸门 + beforeOpen + 自动 loading）
+- [TabsMain](./docs/README-TabsMain.md) — Tab 容器（channel 嵌套 / tile 平铺 / query 同步 / item badgeKey 徽标）
+- [ActionBtn](./docs/README-ActionBtn.md) — ElButton 超集（confirm 闸门 + beforeOpen + 自动 loading + badgeKey 徽标）
+- [BadgeMark](./docs/README-BadgeMark.md) — 徽标标记（按 key 查 bridge.badge 注册表挂绝对定位角标）
 - [ActionBtnGroup](./docs/README-ActionBtnGroup.md) — 配置式按钮组（渲染三态）
 - [ActionConfirm](./docs/README-ActionConfirm.md) — 确认原语（扁平，submitFn 返 Promise 才关）
 - [WatchSize](./docs/README-WatchSize.md) — 尺寸监听容器（mode / observeResize / debounce）
@@ -16,7 +17,9 @@
 ## 关键类型
 
 - `TabsMainProps` / `TabsMainItem` / `ActionBtnProps` / `ActionBtnConfirmConfig` / `ActionBtnConfigItem` / `ActionBtnGroupProps` / `ActionConfirmProps` / `BooleanTagProps` / `ShadowCloneProps`（经 `./types` 导出）
-- 内部件不导出：`TabsHeader` / `TabsTile` / `TabsRefineFlow` / `TabsNaturalFlow` / `use-tabs-query-sync` / `use-shadow-target`
+- 内部件不导出：`TabsHeader` / `TabsTile` / `TabsRefineFlow` / `TabsNaturalFlow` / `use-tabs-query-sync` / `use-shadow-target` / `use-badge`
+
+> **徽标（BadgeMark）**：按 key 查 `bridge.badge` 注册表渲染绝对定位角标，供 ActionBtn 与菜单族共用；**跨桶消费故公开导出**（同 WatchSize 被 app-layout 消费的先例），自供 shell 自渲染导航时也可直接用。完整契约（标记类型 / 失效路径 / key 约定 / 已知限制）见 [bridge 文档 · 徽标注册表](../../bridge/docs/README.md)。`use-badge` 收纳查表 + `expireAt` 判定 + 共享 tick，**不出桶**（规则 21/22，组件同级）。
 
 ## 跨族依赖（被依赖）
 

package/src/components/display/docs/README-ActionBtn.md

@@ -48,6 +48,7 @@ const handleDelete = async () => {
 | `loading` | ❌ 被 Omit | — | 对外不可设置，内部独占 innerLoading（对接异步 confirm / beforeOpen / click handler） |
 | `confirmMode` | `ActionConfirmMode?` | `"popconfirm"` | "popconfirm"\|"messageConfirm"（后者内嵌 ConfirmModal 居中模态） |
 | `confirmConfig` | `ActionBtnConfirmConfig \| ((data: T) => ActionBtnConfirmConfig)?` | 无=普通按钮 | 确认闸门；函数形态入参 data 来自 beforeOpen 返回值 |
+| `badgeKey` | `string?` | 无=不显徽标 | 徽标键；命中 `bridge.badge` 注册表则在按钮内容右侧渲染绝对定位角标（不压字，且**不改变按钮尺寸**）。按钮无 path，[MUST] 显式给键。契约见 [bridge 文档 · 徽标注册表](../../../bridge/docs/README.md) |
 | `beforeOpen` | `() => Promise<T>?` | — | 点击后、弹层前异步预取；reject 静默退出（不弹层不触发 click，调用方 [MUST] 内部 catch 反馈）；期间按钮 loading。⚠️ confirmConfig/beforeOpen 均会消耗瞬时用户激活窗口，之后 handler [MUST NOT] 调 window.open/navigator.clipboard 等 |
 
 `ActionBtnConfirmConfig`：`title?` / `content?`（`ActionConfirmTextResolver` = string | (() => string | VNode[])）、`confirmText?`（默认「确定」）、`cancelText?`（默认「取消」）、`type?: ButtonProps["type"]`

package/src/components/display/docs/README-BadgeMark.md

@@ -0,0 +1,125 @@
+# BadgeMark（徽标标记）
+
+> 按 `badgeKey` 查 `bridge.badge` 注册表，命中且未过期则给默认插槽内容挂**绝对定位角标**（包 ElBadge，不挤压主体）；未命中渲染裸插槽、DOM 逐字节不变。
+> 范式页：`apps/reference/src/pages/integration/badge/`（7 场景）；生产驱动点见 MenuTree / MenuItemSub / AppHeader / ActionBtn 内部接入。
+
+## 定位
+
+- **何时用**：自供 shell 自渲染导航、或业务自建的入口元素需要接徽标体系时
+- **何时不用**：core 的菜单族与 `ActionBtn` **已内置接入**，用它们时 [MUST NOT] 再自行包一层
+- **opt-in 且零侵入**：未 `app.use(bridge)` / key 未命中 / 标已过期 → 静默渲染裸插槽，[MUST NOT] 抛错
+- 完整契约（标记类型 / `expireAt` 失效 / key 约定 / 已知限制 / 为何不做冒泡聚合）见 [bridge 文档 · 徽标注册表](../../../bridge/docs/README.md)
+
+## 快速上手（最小可用）
+
+```vue
+<BadgeMark badgeKey="/order/list">
+  <span>订单列表</span>
+</BadgeMark>
+```
+
+app 侧往注册表写一条即出标：
+
+```ts
+bridge.badge.set("/order/list", { kind: "new" });
+```
+
+## 能力边界 / 按需使用
+
+- **`align` 怎么选：看被包内容盒是否紧贴文字**（不是看宿主类型）。
+
+| 宿主 | `.el-badge` 盒高 | 宿主高 | `corner` 落点 | core 用 |
+| --- | --- | --- | --- | --- |
+| `ActionBtn` | 14px（紧贴文字行） | 32px | 角标顶齐按钮顶，上溢 **0** | **`corner`** 右上角 |
+| `TabsHeader` tab | 22px（紧贴） | 40px | 上溢 **−1**，不越界 | **`corner`** 右上角 |
+| 菜单项 / AppHeader 模块条 / tile 卡片头 | **50px（撑满整行）** | 50px | 钉在**行顶**、上溢 **9px** 侵入上一行 | **`middle`** 垂直居中 |
+
+差别根源：菜单项的 `span` 继承整行 `line-height`，`.el-badge` 盒跟着撑满一行，于是「内容顶边」≠「文字顶边」；按钮 / tab 的盒紧贴文字行，顶边即文字顶边。
+
+- **[MUST NOT] 用 `top: N%` 或 ElBadge `offset` 魔数去凑**：与字号 / 行高 / 主题 density 强耦合，一变就错位。盒紧贴文字的宿主用 `corner`，盒撑满行的用 `middle`。
+
+### 硬约束：角标的出现 [MUST NOT] 改变宿主尺寸
+
+两档均为**绝对定位**，不占布局位。实测证据：同一批按钮打标前后逐项宽度差 **全 0**。
+
+代价是绝对定位不占位 → 角标必然向右**逃逸出宿主边界**，逃逸量 = `角标宽 − 13px`（EP 的 10px 内嵌已归零，另留 2px 让位；文字距按钮右缘 15px padding）：
+
+| 内置标 | 宽 | 逃逸 | 后果 |
+| --- | --- | --- | --- |
+| 新 | 26px | 13px | 落在间距里 |
+| 更新 / 内测 | 38px | 25px | 压进邻居 padding，**不压邻居文字** |
+| ~~开发中（3 字）~~ | ~~50px~~ | ~~37px~~ | ~~右缘顶到下一个按钮~~ → 已改「开发」 |
+
+**故内置标文案 [MUST] ≤ 2 个汉字。** 逃逸量最终由消费方的布局间距决定，core [MUST NOT] 声称能保证零重叠；`custom` 传长文本的后果由消费方自负。
+
+### 尺寸：固定 12px / 18px，不随 density 变
+
+| 项 | 值 | 来源 |
+| --- | --- | --- |
+| 字号 | **12px** | `--el-badge-font-size`（EP **组件级**变量，定义在 `.el-badge` 上，非 `:root`） |
+| pill 高 | **18px** | `--el-badge-size` |
+| 内 padding | 0 6px | `--el-badge-padding` |
+
+实测按钮 / tab / 菜单三处**完全一致**，文字在 pill 内垂直居中偏移均为 0（三处 `line-height` 虽不同——按钮 12px、tab 16.8px、菜单 56px 继承整行行高——但 pill 是 `inline-flex + align-items:center + 固定高`，不产生偏移）。
+
+⚠️ **不随主题 density 缩放**：core 的 `THEME_FIELD_SPECS` 只往 `:root` 挂变量且未映射任何 badge 变量，故 density 档（compact / cozy / comfortable）不改角标尺寸。这是刻意的——角标应恒为全局最小号，跟着 density 缩放可能小到不可读。消费方要改自行覆盖 `--el-badge-font-size` / `--el-badge-size`。
+
+### ⚠️ 换英文**不能**减宽（已实测，[MUST NOT] 再试）
+
+12px 字号 + pill 内 padding 实测：
+
+| 中文 | 宽 | 英文 | 宽 | 差 |
+| --- | --- | --- | --- | --- |
+| 新 | 26 | NEW | 41 | **+15** |
+| 更新 | 38 | UPDATED | 70 | **+32** |
+| 内测 | 38 | BETA | 45 | **+7** |
+| 开发中 | 50 | WIP | 36 | −14 |
+
+汉字在小字号下表意密度远高于大写字母——除「开发中→WIP」外全部变宽。压宽度的正确手段是**减字数**，不是换语种。
+
+## API
+
+> ⚠️ API 以源码为真相源；与文档冲突时以源码为准。
+
+### Props
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `badgeKey` | `string?` | 无=不显 | 徽标键。菜单侧传路由 `path`，按钮侧传显式键 |
+| `align` | `"corner" \| "middle"` | `"corner"` | 角标垂直锚点：`corner`=骑内容顶边（按钮/图标）；`middle`=与内容垂直居中（纯文字标签） |
+
+### Emits / Expose
+
+无。
+
+### Slots
+
+| 槽 | scope | 语义 |
+| --- | --- | --- |
+| `#default` | 无 | 被挂标的内容；未命中时原样渲染，不加任何包裹层 |
+
+## 内置标预设
+
+文案与语义色由 core 统一定（跨 app 一致）；语义档解析到 `--el-color-*`，**主题风格 / 亮暗切换自动跟随**（规则 14，[MUST NOT] 写死色值）。
+
+| kind | 文案 | 语义色 | 为什么 |
+| --- | --- | --- | --- |
+| `count` | 数字 | `danger` 红 | 待办数量**要人行动**，未读红点是全行业最强共识 |
+| `new` | 新 | `success` 绿 | 新功能上线是**正面资讯**（Atlassian success 档即覆盖 "added"）。[MUST NOT] 复用红——会与 `count` 撞色，扫视时分不清「有新东西」和「有待办」 |
+| `updated` | 更新 | `primary` 主色 | 中性被动通知，不喧宾夺主 |
+| `beta` | 内测 | `warning` 橙 | 能用但**不稳定需谨慎**，正是 warning 语义 |
+| `wip` | 开发 | `info` 灰 | 不可用，中性、不引导点击 |
+| `custom` | 自定 | 缺省 `primary` | 内置档不够用时才用；`type` 只收语义档 |
+
+## 反模式 / 注意
+
+- **`custom` 传色值字面量**：`type` [MUST] 取语义档（`primary`/`success`/`warning`/`danger`/`info`），写死色跨主题不响应（规则 14）
+- **包纯文字却用默认 `corner`**：角标会悬在文字上方并溢出相邻行
+- **指望它做聚合**：本组件只按 key 查表渲染，core [MUST NOT] 把子级的标上卷到父级；聚合由 app 自算后往父级 key 写 entry
+- **角标文字色恒为白**（EP 的 `--el-color-white`，主题不覆盖）：若某主题的语义色很浅，白字对比度会不足——这是 EP 层面的约束
+
+## 关联
+
+- 数据真源：`bridge.badge`（`bridge/badge.ts`）
+- 内部 hook：`use-badge`（同级、不出桶；查表 + `expireAt` 判定 + 全 app 共享 tick）
+- 已接入的生产驱动点：`MenuTree` / `MenuItemSub` / `AppHeader` 模块条 / `ActionBtn`

package/src/components/display/docs/README-TabsMain.md

@@ -62,7 +62,7 @@ const tabs = [
 
 | name | type | 默认 | 语义 |
 | --- | --- | --- | --- |
-| `tabs` | `TabsMainItem[]`（必填） | — | tab 配置列表 |
+| `tabs` | `TabsMainItem[]`（必填） | — | tab 配置列表（`{ key, title, component?, badgeKey? }`；`badgeKey` 见下「tab 标题徽标」） |
 | `viewportHeight` | `number?` | — | 显式视口高度，优先级最高；未传降级 inject SCOPE_VIEWPORT_MAX_HEIGHT scope 链 |
 | `minHeight` | `number?` | `100` | 内容区高度兜底下限 |
 | `channel` | `string?` | — | 作为父时的 scope 标识。⚠️ 与 parentChannel 均 [MUST NOT] 响应式变更（setup 期快照）；且仅 refine=true 路径生效 |
@@ -108,3 +108,22 @@ const tabs = [
 - 内部实现：`TabsNaturalFlow` / `TabsRefineFlow` / `TabsHeader` / `TabsTile` / `use-tabs-query-sync.ts`（均不导出）
 - 高度链：`SCOPE_VIEWPORT_MAX_HEIGHT` scope 链（viewportHeight / parentChannel 消费侧）
 - 范式页：`apps/reference/src/pages/display/tabs/showcase/`、`pages/display/tabs/nested-channel/`、`pages/display/tabs/tile/`
+
+## tab 标题徽标（`badgeKey`）
+
+给 `TabsMainItem` 配 `badgeKey`，命中 `bridge.badge` 注册表且未过期时，在 tab 标题右侧挂绝对定位角标（不改变 tab 尺寸）——**三处同步**：tab-bar 标题、平铺（tile）卡片标题、平铺角落 nav。未配 / 未命中 → DOM 与不接入时逐字节一致。
+
+```ts
+const tabs = [
+  { key: "detail", title: "详情" },
+  { key: "export", title: "导出", badgeKey: "order.export" },
+];
+// app 侧
+bridge.badge.set("order.export", { kind: "beta" });
+```
+
+**[MUST NOT] 拿 `item.key` 当徽标键。** `key` 是**局部唯一**的（v-model 值 + 槽名），两个页面都可能有 `key: "detail"`，复用它会跨页串标。徽标键需全局唯一，故显式另给（同 `ActionBtn.badgeKey` 范式）。
+
+**徽标包在标题 slot 外**——消费方自定义 `#{key}` / `#header-{key}` 标题槽时，角标依然在（徽标标的是"这个 tab 有东西"，与标题怎么渲染无关）。
+
+完整契约（六种标记类型 / `expireAt` 失效 / 已知限制）见 [bridge 文档 · 徽标注册表](../../../bridge/docs/README.md)。

package/src/components/menu/README.md

@@ -20,6 +20,14 @@
 - [MenuTree](./docs/README-MenuTree.md) — 菜单主体（menus 递归 + `groupMode` 树形 / 分组双形态 + routerMode / autoClose / collapse + open/close expose）
 - [MenuItemSub](./docs/README-MenuItemSub.md) — 递归子菜单分组件（ElSubMenu 递归节点，一般由 MenuTree 自用；分组形态下承接 L2 及更深层级）
 
+## 菜单项徽标
+
+两种形态下，凡渲染出路由 `path` 的位置（叶子项 / ElSubMenu 标题 / 分组标题）都会按 **`path` 作 key** 查 `bridge.badge` 注册表，命中则渲染绝对定位角标（数量 / 新上线 / 更新 / 内测 / 开发 / 自定义），**不压字、不改变宿主尺寸**；未命中零影响。
+
+无需在菜单数据里另配 key。完整契约见 [bridge 文档 · 徽标注册表](../../bridge/docs/README.md)。
+
+> core **不做**子级到父级的冒泡聚合——需要「模块上有引导点」由 app 自己算完往父级 path 写 entry，理由见上述文档。
+
 ## 关键类型
 
 - `RouteMetaResolveRaw`（@/types，menus / menuFlatList 数据契约）

package/src/components/menu/docs/README-MenuItemSub.md

@@ -12,6 +12,10 @@
   - MenuTree `groupMode=false`（树形）→ 承接 **L1 及以下**全部有子项的节点
   - MenuTree `groupMode=true`（分组）→ L1 已被 `ElMenuItemGroup` 分组标题接管，本组件**只承接 L2 及更深**层级（即「分组标题内的手风琴」）。分组标题只吃掉一层，深层级仍归本组件——这是分组形态下三级菜单混合渲染的实现落点
 
+## 徽标（badge）
+
+本组件渲染的 ElSubMenu 标题与其下叶子项，同样以各自的 `path` 为 key 查 `bridge.badge` 渲染角标，规则与 MenuTree 一致（未命中零影响、不挤压文案、不聚合）。见 [README-MenuTree.md](./README-MenuTree.md#徽标badge)。
+
 ## 快速上手（最小可用）
 
 MenuTree 内部驱动（menu/MenuTree.vue 片段）：

package/src/components/menu/docs/README-MenuTree.md

@@ -26,6 +26,16 @@
 
 **视觉不自造**：分组标题吃 EP 原生皮肤（`el-menu-item-group__title` = `font-size:12px` + `--el-text-color-secondary`）；需微调只走主题 var（规则 14），[MUST NOT] 写死颜色。
 
+## 徽标（badge）
+
+每个渲染出 `menu.path` 的位置——L1 叶子、L1 分组标题（分组形态）、递归下去的 ElSubMenu 标题与叶子（经 MenuItemSub）——都以 **`path` 为 key** 查 `bridge.badge`，命中即渲染绝对定位角标（不改变宿主尺寸）。
+
+- **零配置**：菜单数据不用加任何字段；未命中不渲染，对既有菜单零影响。
+- **不压字、不改尺寸**：角标绝对定位（内部包 ElBadge），跟在标题右侧、不覆盖任何字，且**角标的出现不改变菜单项尺寸**（实测有标/无标逐项宽度差 0）。
+- **不聚合**：MenuTree [MUST NOT] 把子项的标上卷到父级，父级只显示注册表里挂在它自己 path 上的 entry。
+
+契约（标记类型 / `expireAt` 失效 / 已知限制）见 [bridge 文档 · 徽标注册表](../../../bridge/docs/README.md)。
+
 ## 快速上手（最小可用）
 
 必填只有 `menus` + `menuFlatList`——默认 ElMenu 主题、无路由联动、无选中收合：

package/types/bridge/badge.d.ts

@@ -0,0 +1,112 @@
+import { ShallowRef } from 'vue';
+import { BadgeProps } from 'element-plus';
+/**
+ * bridge 徽标注册表 hook（按耦合度从 index.ts 拆出，规则 12）。
+ *
+ * 一张扁平的 `key → 标记` 表；菜单项（AppSidebar 菜单树 / AppHeader 模块条）与
+ * `ActionBtn` 按 key 查表渲染**绝对定位角标**（跟在文案右侧、不压字；[MUST] 不改变宿主尺寸）。
+ *
+ * **分工：core 只负责展示。** 聚合、归属、清标、数据来源全部在 app——
+ * core [MUST NOT] 把子级的标上卷到父级菜单（归属在真实系统里多对多且有例外：
+ * 弹窗内按钮 / 全局工具栏按钮 / 一个入口挂两个模块；core 定义归属模型即越权）。
+ * 需要「一级模块上有引导点」由 app 自己算完往父级 path 写一条 entry。
+ *
+ * 每次 `createCoreBridge` 各自闭包内构造（零模块级单例，守实例隔离，规则 8）。
+ */
+/** 徽标 key → 标记 的注册表载荷 */
+export type BadgeMarkMap = Record<string, BadgeEntry>;
+/**
+ * 徽标标记。
+ *
+ * `expireAt` 提在交叉类型外——**所有 kind 一律支持过期**，缺省或 `0` = 永久展示
+ * （两个哨兵指同一件事，`!expireAt` 一个表达式同时吃掉，零分支；后端 JSON 常发
+ * `0` 而非省略字段）。
+ *
+ * 两条失效路径正交可共存：
+ * - 有 `expireAt`（如随版本写死到某日的 NEW）→ core 内部 tick 到点自动落，app 不用管；
+ * - 无 `expireAt`（如服务端来的待办数 / Beta 标）→ app 下一轮 `setAll` 刷掉。
+ *
+ * 故 `expireAt` **不是必填**——它是给「没有轮询通道」的静态标准备的兜底。
+ */
+export type BadgeEntry = {
+    /** 展示截止的绝对时间（epoch ms）；缺省或 0 = 永久展示 */
+    expireAt?: number;
+    /**
+     * 面向 agent / AI 对话的语义描述——**core 不消费，纯透传**。
+     *
+     * 供应用层做「本期上了什么功能」这类对话时，让模型知道这个 key 指向什么、
+     * 怎么用、什么时候还不该用。与 `kind`（= 变更类别，同 Keep a Changelog 的
+     * Added/Changed 词汇）+ `expireAt`（时效）合起来，这张表即一份机器可读的功能公告。
+     *
+     * **自由文本，[MUST NOT] 拆成正反两个字段**——对齐 MCP / OpenAI function calling /
+     * JSON Schema 的 tool `description` 范式（均为单 string，约定把「何时用 / 何时不该用」
+     * 写在同一段里）。区别于主题 preset 的 {@link CoreConfigDescription}：那是**闭集选型**
+     * 场景（35 套主题里挑一套），正 / 反 facets 能做无 LLM 预筛；徽标是**讲解**场景，
+     * 不做排除，拆正反会让「新功能的不宜选场景是什么」这种问题无从填起。
+     *
+     * 重内容（图文步骤 / 深链 / 视频）[SHOULD] 走 app 自己的知识库、用同一 key 关联——
+     * [MUST NOT] 往本字段堆，否则 `BadgeEntry` 会从「一个标」膨胀成 CMS 条目。
+     *
+     * @example "批量导出订单为 Excel。适合按月对账；单次超 10 万行会超时，内测期不建议用于生产对账。"
+     */
+    description?: string;
+} & ({
+    /** 数字角标 */
+    kind: "count";
+    /** 计数值 */
+    value: number;
+    /** 上限，超出显 `{max}+`（透传 ElBadge） */
+    max?: number;
+} | {
+    kind: "new";
+} | {
+    kind: "updated";
+} | {
+    kind: "beta";
+} | {
+    kind: "wip";
+} | {
+    /** 自定义标：内置五档不够用时才用 */
+    kind: "custom";
+    /** 标签文案 */
+    text: string;
+    /**
+     * 语义色档（透传 ElBadge `type`），随主题亮暗自适配。
+     * [MUST NOT] 传色值字面量——规则 14，写死色切主题不响应。
+     */
+    type?: BadgeProps["type"];
+});
+/** 内置标（非 count / custom）的 kind 联合——文案与语义色由 core 统一定，保证跨 app 一致 */
+export type BadgeBuiltinKind = "new" | "updated" | "beta" | "wip";
+/** bridge 徽标 hook 工厂入参 */
+export interface BridgeBadgeInit {
+    /** 初始标记表（如随版本发布的静态 NEW 标）；缺省空表 */
+    marks?: BadgeMarkMap;
+}
+/**
+ * 徽标注册表模块（bridge 公开面 `bridge.badge`）。
+ *
+ * ⚠️ [MUST NOT] 用 `bridge.update()` 维护徽标——那是 `Object.assign` **浅合并**，
+ * 轮询场景下服务端本轮已撤下的标会永远留在表里。徽标独立走本模块。
+ */
+export interface CoreBadgeModule {
+    /** 全部标记（响应式只读；内部 shallowRef，每次操作产新对象） */
+    readonly marks: Readonly<ShallowRef<BadgeMarkMap>>;
+    /** **整体替换** —— 轮询主路径，服务端本轮撤下的标随之消失 */
+    setAll: (marks: BadgeMarkMap) => void;
+    /** 单点写入 / 覆盖 */
+    set: (key: string, entry: BadgeEntry) => void;
+    /** 单点移除 */
+    remove: (key: string) => void;
+}
+/** bridge 徽标 hook 工厂返回（聚合到 `bridge.badge`） */
+export interface BridgeBadgeHook {
+    badge: CoreBadgeModule;
+}
+/**
+ * bridge 徽标注册表 hook 工厂。
+ *
+ * 内部 `shallowRef` + 每次操作产新对象：整体替换语义天然正确、无深代理开销
+ * （标记是值对象，不需要逐字段深响应）。
+ */
+export declare function createBridgeBadgeHook(init?: BridgeBadgeInit): BridgeBadgeHook;

package/types/bridge/index.d.ts

@@ -6,11 +6,13 @@ import { UpdatableConfigKey, UpdatableConfigMap } from './config-hook';
 import { CoreBridgePluginLike } from './plugin';
 import { CoreThemeModule, CoreThemeMode, CoreThemeDensity, CoreThemeMotion, BridgeThemeLayoutState } from './theme';
 import { CoreLayoutModule } from './layout';
+import { CoreBadgeModule, BadgeMarkMap } from './badge';
 export { createUseState, type UseStateOptions } from './state';
 export { createGenerateRouteMetaRawTree, type RouteMetaDefaultConfig, } from './route';
 export { createStorageWithNamespace } from './storage';
 export type { CoreThemeEntry, CoreThemeLifecycleContext, CoreThemeLifecycleHooks, CoreConfigDescription, CoreThemeModule, CoreThemeMode, CoreThemeDensity, CoreThemeMotion, ElSize, CoreThemeComponentDefaults, CoreThemePresetLayout, BridgeThemeLayoutState, BridgeThemeLayoutBaseline, BridgeThemeHook, } from './theme';
 export type { CoreLayoutModule, BridgeLayoutHook, BridgeLayoutInit, LayoutCollapsePersistShape, } from './layout';
+export type { BadgeEntry, BadgeMarkMap, BadgeBuiltinKind, CoreBadgeModule, BridgeBadgeHook, BridgeBadgeInit, } from './badge';
 /**
  * 认证桥接无状态纯工厂。
  *
@@ -480,6 +482,13 @@ export interface CoreBridgeInitOptions<UserInfo = unknown> {
      * 经 `bridge.showThemeStyleSwitcher` readonly 暴露，AppTheme 直读 `v-if` 自控。
      */
     showThemeStyleSwitcher?: boolean;
+    /**
+     * 徽标注册表初值（`key → 标记`）；缺省空表。
+     *
+     * 适合放「随版本发布的静态标」（如写死 `expireAt` 的 NEW）；服务端来的动态标
+     * 由 app 在拿到数据后经 `bridge.badge.setAll(map)` 整体替换。
+     */
+    badgeMarks?: BadgeMarkMap;
     /** app 嵌套路由树（必传，#4e additive；createUserStore 权限树依赖 children 嵌套，[MUST NOT] 传扁平化数据） */
     routes: RouteRecordRaw[];
     /** 用户信息空保底工厂（v3 终锁 Δ0b；恒返非空业务字段默认值对象，createUserStore useState 经此取初值，core 不锁业务 shape） */
@@ -608,6 +617,15 @@ export interface CoreBridge<UserInfo = unknown, LoginParams = unknown> {
      * [MUST NOT] 解构/快照折叠态（⚠️ 切换后定格）。
      */
     readonly layout: CoreLayoutModule;
+    /**
+     * 徽标注册表模块（`key → 标记` 扁平表）。
+     *
+     * 菜单项以路由 `path` 为 key、`ActionBtn` 以显式 `badgeKey` 查表渲染绝对定位角标。
+     * `marks` 响应式只读 + `setAll`（整体替换，轮询主路径）/ `set` / `remove`。
+     * ⚠️ [MUST NOT] 改用 `update()` 维护——浅合并会让服务端已撤下的标永远留存。
+     * core 只负责展示：聚合 / 归属 / 清标 / 数据来源全在 app。
+     */
+    readonly badge: CoreBadgeModule;
     /** 用户信息字段访问器集（业务注入；createUserStore 经 bridge.userInfoAccess.<字段>.get/set 读写，第一宪法 core 零字段耦合） */
     readonly userInfoAccess: UserInfoAccess<UserInfo>;
     /**

package/types/components/display/BadgeMark.vue.d.ts

@@ -0,0 +1,57 @@
+type __VLS_Props = {
+    /**
+     * 徽标键；命中 `bridge.badge` 注册表且未过期才渲染角标。
+     * 菜单侧传路由 `path`，`ActionBtn` 侧传显式 `badgeKey`。
+     */
+    badgeKey?: string;
+    /**
+     * 角标垂直锚点（两档均为**绝对定位**——[MUST] 保证角标的出现不改变宿主尺寸）：
+     * - `"corner"` ＝ 右上角（EP 原生骑角，角标中心钉在**被包内容盒的顶边**）。
+     * - `"middle"`（**缺省**）＝ 与被包内容盒垂直居中。
+     *
+     * **怎么选：看被包内容盒是否紧贴文字**（实测三类宿主，同一段 CSS 落点完全不同）：
+     *
+     * | 宿主 | `.el-badge` 盒高 | 宿主高 | `corner` 落点 | 选 |
+     * | --- | --- | --- | --- | --- |
+     * | ActionBtn | 14px（紧贴文字行） | 32px | 角标顶齐按钮顶，上溢 0 | `corner` |
+     * | TabsHeader tab | 22px（紧贴） | 40px | 上溢 −1（不越界） | `corner` |
+     * | 菜单项 / AppHeader 模块条 / tile 卡片头 | **50px（撑满整行）** | 50px | 钉在**行顶**、上溢 9px 侵入上一行 | `middle` |
+     *
+     * 差别根源：菜单项的 span 继承整行 `line-height`，`.el-badge` 盒跟着撑满一行，
+     * 于是「内容顶边」≠「文字顶边」。[MUST NOT] 靠 `top: N%` 魔数去凑——换字号 /
+     * density 就错位；盒紧贴文字的宿主用 `corner`，盒撑满行的用 `middle`。
+     *
+     * **横向几何（两档共用，见 style 块）**：EP `.is-fixed` 默认 `right: calc(1px+size/2)`
+     * 让角标**向内嵌 10px**——那是为「包裹整个按钮」设计的，而本组件包的是**内容本身**
+     * （标题 / label 文字），10px 内嵌直接压住最后一个字（14px 字号下≈3/4 个汉字）。故归零 + 2px 让位。
+     *
+     * **代价（[MUST] 知悉）**：绝对定位不占位，角标必然向右**逃逸出宿主边界**，逃逸量
+     * = 角标宽 − 13px。实测中文内置标逃逸 12–24px，只压进邻居 padding、不压邻居文字；
+     * 但这依赖消费方的布局间距，core [MUST NOT] 声称能保证不重叠。故内置标文案
+     * [MUST] 控制在 **2 个汉字以内**（3 字的「开发中」实测逃逸 36px、右缘顶到下一个按钮）。
+     *
+     * ⚠️ 换英文**不能**减宽：实测 12px 字号下 NEW=41 > 新=26、UPDATED=70 > 更新=38、
+     * BETA=45 > 内测=38——汉字表意密度远高于大写字母。[MUST NOT] 为「更短」而改英文。
+     *
+     * [MUST NOT] 用 ElBadge `offset` 魔数调位——与字号 / 行高强耦合，主题 density 一变就错位。
+     */
+    align?: "middle" | "corner";
+};
+declare function __VLS_template(): {
+    attrs: Partial<{}>;
+    slots: {
+        default?(_: {}): any;
+        default?(_: {}): any;
+    };
+    refs: {};
+    rootEl: any;
+};
+type __VLS_TemplateResult = ReturnType<typeof __VLS_template>;
+declare const __VLS_component: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const _default: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
+export default _default;
+type __VLS_WithTemplateSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/types/components/display/index.d.ts

@@ -6,6 +6,7 @@ import { default as ActionBtn } from './ActionBtn.vue';
 import { default as ActionConfirm } from './ActionConfirm.vue';
 import { default as ActionBtnGroup } from './ActionBtnGroup.vue';
 import { default as BooleanTag } from './BooleanTag.vue';
+import { default as BadgeMark } from './BadgeMark.vue';
 export { 
 /** 尺寸监听容器：debounce 测默认槽内容宽/高，派发 `@height-change` / `@size-change` */
 WatchSize, 
@@ -25,6 +26,12 @@ HeightProvider,
  * 确认闸门 + `beforeOpen` 异步预取 + onClick 返 Promise 自动 loading（内部接管）。
  */
 ActionBtn, 
+/**
+ * 徽标标记：按 `badgeKey` 查 `bridge.badge` 注册表，命中且未过期则给默认插槽内容
+ * 挂绝对定位角标（包 ElBadge，不挤压主体）；未命中渲染裸插槽、DOM 零变化。
+ * 菜单族 / ActionBtn 内部已接入；自供 shell 自渲染导航时可直接复用。
+ */
+BadgeMark, 
 /**
  * confirm 原语（扁平，可独立于 ActionBtn 消费）：触发元素由默认 slot 提供，
  * 弹层可见性 `v-model:show` 声明式驱动；`submitFn` 返 Promise 时仅成功才关弹层。

package/types/components/display/types.d.ts

@@ -61,6 +61,15 @@ export type ActionBtnProps<T = void> = Omit<ButtonProps, "loading"> & {
      *   瞬时用户激活（详见 {@link ActionBtnConfirmConfig} 顶部注释）。
      */
     beforeOpen?: () => Promise<T>;
+    /**
+     * 徽标键——命中 `bridge.badge` 注册表且未过期时，在按钮内容右侧挂**绝对定位角标**
+     * （包 ElBadge；不压字，且 [MUST] 不改变按钮尺寸；未命中时 DOM 与不传时逐字节一致）。
+     *
+     * 按钮没有路由 path，[MUST] 显式给键（菜单侧则默认取 path，无需另配）。
+     * 配置驱动（`ActionBtnGroup`）经 `actionBtnProps` 工厂返回 `{ badgeKey }` 即可。
+     * 契约详见 bridge 文档「徽标注册表」章节。
+     */
+    badgeKey?: string;
 };
 /**
  * ActionConfirm 组件 props（扁平，confirm 原语；可独立于 ActionBtn 消费）。
@@ -142,6 +151,15 @@ export interface TabsMainItem {
     title: string;
     /** 内容组件，#{key} 槽缺省时回退渲染 */
     component?: Component;
+    /**
+     * 徽标键——命中 `bridge.badge` 注册表且未过期时，在 tab 标题右侧挂绝对定位角标
+     * （tab-bar / 平铺卡片标题 / 平铺角落 nav 三处同步）；[MUST] 不改变 tab 尺寸。
+     *
+     * [MUST NOT] 复用本项的 `key`：那是**局部唯一**（v-model 值 + 槽名），两个页面
+     * 都可能有 `key: "detail"`，当徽标键会跨页串标。徽标键需全局唯一，故显式另给
+     * （同 `ActionBtn.badgeKey` 范式）。契约见 bridge 文档「徽标注册表」章节。
+     */
+    badgeKey?: string;
 }
 /** [top, right, bottom, left] px——TabsMain 默认插槽容器内置 padding（top+bottom 同步从 channel viewportHeight 扣减） */
 export type TabsMainPadding = [number, number, number, number];

package/types/components/display/use-badge.d.ts

@@ -0,0 +1,19 @@
+import { ComputedRef } from 'vue';
+import { BadgeProps } from 'element-plus';
+/** 徽标解析结果——已过滤过期项，直接可渲染 */
+export interface BadgeResolved {
+    /** ElBadge value（数量标为数字，其余为文案） */
+    value: string | number;
+    /** ElBadge max（仅 count 有意义） */
+    max?: number;
+    /** ElBadge 语义色档 */
+    type: BadgeProps["type"];
+}
+/**
+ * 按 key 解析出可渲染的徽标；无 key / 未 `app.use(bridge)` / 未命中 / 已过期 → `undefined`。
+ *
+ * bridge 经 `CORE_BRIDGE_KEY`（app 级整实例）而非 `APP_LAYOUT_BRIDGE_KEY`（layout 窄切片）——
+ * `ActionBtn` 可用在 AppLayout 之外的任何地方。**opt-in**：未 `app.use(bridge)` 时静默不显，
+ * [MUST NOT] 抛错。
+ */
+export declare function useBadgeResolved(getKey: () => string | undefined): ComputedRef<BadgeResolved | undefined>;

package/types/injectInfo.json.d.ts

@@ -1,6 +1,6 @@
 declare const _default: {
   "name": "@done-coding/admin-core",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "内部前端库"
 };
 

package/types/store/app.d.ts

@@ -77,6 +77,13 @@ export declare function createAppStore<UserInfo = unknown, LoginParams = unknown
         bottom: string;
         left: string;
     }>;
+    viewportConfigEffective: import('vue').ComputedRef<{
+        readonly paddingTop: number;
+        readonly paddingRight: number;
+        readonly paddingBottom: number;
+        readonly paddingLeft: number;
+    }>;
+    noAnimation: import('vue').ComputedRef<boolean>;
     sidebarIsCollapse: import('vue').ComputedRef<boolean>;
     asideIsCollapse: import('vue').ComputedRef<boolean>;
     changeSidebarCollapseStatus: (status: boolean) => void;
@@ -130,13 +137,20 @@ export declare function createAppStore<UserInfo = unknown, LoginParams = unknown
         bottom: string;
         left: string;
     }>;
+    viewportConfigEffective: import('vue').ComputedRef<{
+        readonly paddingTop: number;
+        readonly paddingRight: number;
+        readonly paddingBottom: number;
+        readonly paddingLeft: number;
+    }>;
+    noAnimation: import('vue').ComputedRef<boolean>;
     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" | "contentViewportInset" | "bodyShimStyle" | "viewportPadding" | "sidebarIsCollapse" | "asideIsCollapse">, Pick<{
+}, "name" | "theme" | "showHeader" | "keepAlive" | "bodyShimPadding" | "noAnimation" | "isDarkTheme" | "showFooter" | "showSidebar" | "showAside" | "showBreadcrumb" | "headerStyle" | "footerStyle" | "sidebarStyle" | "asideStyle" | "bodyStyle" | "contentViewportInset" | "bodyShimStyle" | "viewportPadding" | "viewportConfigEffective" | "sidebarIsCollapse" | "asideIsCollapse">, Pick<{
     name: import('vue').ComputedRef<string>;
     isDarkTheme: import('vue').ComputedRef<boolean>;
     theme: import('vue').ComputedRef<{
@@ -183,6 +197,13 @@ export declare function createAppStore<UserInfo = unknown, LoginParams = unknown
         bottom: string;
         left: string;
     }>;
+    viewportConfigEffective: import('vue').ComputedRef<{
+        readonly paddingTop: number;
+        readonly paddingRight: number;
+        readonly paddingBottom: number;
+        readonly paddingLeft: number;
+    }>;
+    noAnimation: import('vue').ComputedRef<boolean>;
     sidebarIsCollapse: import('vue').ComputedRef<boolean>;
     asideIsCollapse: import('vue').ComputedRef<boolean>;
     changeSidebarCollapseStatus: (status: boolean) => void;