@done-coding/admin-core 0.28.0 → 0.28.1-alpha.0

package/es/style.css

@@ -66,34 +66,35 @@
   justify-content: flex-end;
   gap: 8px;
 }
-.badge-mark[data-v-4116ac36] .el-badge__content.is-fixed {
+.badge-mark[data-v-18853ddc] .el-badge__content.is-fixed {
   right: 0;
   transform: translateY(-50%) translateX(calc(100% + 2px));
 }
-.badge-mark_middle[data-v-4116ac36] .el-badge__content.is-fixed {
+.badge-mark_middle[data-v-18853ddc] .el-badge__content.is-fixed {
   top: 50%;
 }
-.badge-mark[data-v-4116ac36] .badge-mark__icon {
+.badge-mark[data-v-18853ddc] .badge-mark__icon {
   display: block;
   font-size: 1em;
   line-height: 1;
 }
-.app-page[data-v-d875cc1d] {
-  --dc-page-content-viewport-top: var(--b28df728);
-  --dc-page-content-viewport-bottom: var(--d4142898);
-  --dc-page-content-viewport-left: var(--v3063bfd0);
-  --dc-page-content-viewport-right: var(--v472ac91a);
-  --dc-page-content-viewport-width: var(--v469df1c6);
-  --dc-page-content-viewport-height: var(--c0be3aa0);
+.app-page[data-v-facaf577] {
+  --dc-page-content-viewport-top: var(--v14c1dc69);
+  --dc-page-content-viewport-bottom: var(--v6d1cb697);
+  --dc-page-content-viewport-left: var(--f914311a);
+  --dc-page-content-viewport-right: var(--v28c52fa0);
+  --dc-page-content-viewport-width: var(--v2838584c);
+  --dc-page-content-viewport-height: var(--v76c7ad93);
 }
-.app-page-shim[data-v-d875cc1d] {
+.app-page-shim[data-v-facaf577] {
   display: flow-root;
-  --app-viewport-max-height: var(--v52d7da39);
+  --app-viewport-max-height: var(--v9258c294);
 }
-.app-page-slot-shim[data-v-d875cc1d] {
+.app-page-slot-shim[data-v-facaf577] {
   box-sizing: border-box;
   width: 100%;
   height: 100%;
+  border-radius: var(--dc-core-radius, var(--el-border-radius-base));
 }
 [data-v-64f355fe] .auto-refresh-label {
   display: flex;
@@ -130,7 +131,7 @@ to {
   text-align: center;
   font-variant-numeric: tabular-nums;
 }
-.view-layout-header[data-v-0507f728] {
+.view-layout-header[data-v-e7dc3f12] {
   flex: 0 1 auto;
   min-width: 0;
   overflow: hidden;
@@ -141,38 +142,47 @@ to {
   white-space: nowrap;
   text-overflow: ellipsis;
 }
-html.dark .view-layout-toolbar[data-v-0507f728] {
-  box-shadow: inset 0 -1px 0 0 var(--el-border-color-extra-light), inset 0 -6px 6px -6px var(--el-border-color-extra-light);
-}
-.view-layout[data-v-0507f728] {
+.view-layout[data-v-e7dc3f12] {
   display: flex;
   flex-direction: column;
 }
-.view-layout-toolbar[data-v-0507f728] {
+.view-layout-toolbar[data-v-e7dc3f12] {
   display: flex;
   justify-content: space-between;
   align-items: center;
-  padding-bottom: 8px;
+  padding: 0 8px 8px;
+  position: relative;
   gap: 20px;
-  box-shadow: inset 0 -1px 0 0 var(--el-border-color-darker), inset 0 -6px 6px -6px var(--el-border-color-darker);
+  background: color-mix(in srgb, var(--dc-core-surface, var(--el-bg-color)) 50%, var(--dc-core-ground, var(--el-bg-color-page)));
+  border-radius: 0;
 }
-.view-layout-toolbar__left[data-v-0507f728],
-.view-layout-toolbar__right[data-v-0507f728] {
+.view-layout-toolbar[data-v-e7dc3f12]::before {
+  content: "";
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  left: 0;
+  width: 3px;
+  border-radius: 3px;
+  background: var(--dc-core-primary-color, var(--el-color-primary));
+}
+.view-layout-toolbar__left[data-v-e7dc3f12],
+.view-layout-toolbar__right[data-v-e7dc3f12] {
   display: flex;
   align-items: center;
   gap: 10px;
 }
-.view-layout-toolbar__left[data-v-0507f728] > *,
-.view-layout-toolbar__right[data-v-0507f728] > * {
+.view-layout-toolbar__left[data-v-e7dc3f12] > *,
+.view-layout-toolbar__right[data-v-e7dc3f12] > * {
   flex: none;
 }
-.view-layout-toolbar__left .view-layout-header[data-v-0507f728] {
+.view-layout-toolbar__left .view-layout-header[data-v-e7dc3f12] {
   flex: 1 1 auto;
 }
-.view-layout-toolbar__right[data-v-0507f728] {
+.view-layout-toolbar__right[data-v-e7dc3f12] {
   flex: none;
 }
-.view-layout-content[data-v-0507f728] {
+.view-layout-content[data-v-e7dc3f12] {
   overflow: auto;
 }
 .dc-app-page-detail__title[data-v-4426d26a] {
@@ -232,33 +242,33 @@ html.dark .view-layout-toolbar[data-v-0507f728] {
     opacity: 0.3;
 }
 }
-[data-v-6ea6d3c8] .el-row > .el-col > .el-form-item {
-  margin-bottom: 18px;
+[data-v-ba043bbe] .el-row > .el-col > .el-form-item {
+  margin-bottom: var(--dc-core-form-item-gap, 18px);
 }
-[data-v-6ea6d3c8] .el-row > .el-col > .el-form-item.dc-form-item-collapsed,[data-v-6ea6d3c8] .el-row > .el-col:has(> .el-form-item.dc-form-item-collapsed) {
+[data-v-ba043bbe] .el-row > .el-col > .el-form-item.dc-form-item-collapsed,[data-v-ba043bbe] .el-row > .el-col:has(> .el-form-item.dc-form-item-collapsed) {
   display: none;
 }
-[data-v-6ea6d3c8] .el-row > .el-col > .el-form-item.dc-form-item-pseudo {
+[data-v-ba043bbe] .el-row > .el-col > .el-form-item.dc-form-item-pseudo {
   margin-bottom: 8px;
 }
-.dc-form-main[data-v-6ea6d3c8] {
+.dc-form-main[data-v-ba043bbe] {
   position: relative;
 }
-.dc-form-main .form-ai-fill-anchor[data-v-6ea6d3c8] {
+.dc-form-main .form-ai-fill-anchor[data-v-ba043bbe] {
   opacity: 0.45;
   transition: opacity var(--dc-core-motion-duration, 0.2s) ease;
 }
-.dc-form-main:hover .form-ai-fill-anchor[data-v-6ea6d3c8],
-.dc-form-main:focus-within .form-ai-fill-anchor[data-v-6ea6d3c8],
-.dc-form-main .form-ai-fill-anchor[data-v-6ea6d3c8]:hover,
-.dc-form-main .form-ai-fill-anchor[data-v-6ea6d3c8]:focus-within {
+.dc-form-main:hover .form-ai-fill-anchor[data-v-ba043bbe],
+.dc-form-main:focus-within .form-ai-fill-anchor[data-v-ba043bbe],
+.dc-form-main .form-ai-fill-anchor[data-v-ba043bbe]:hover,
+.dc-form-main .form-ai-fill-anchor[data-v-ba043bbe]:focus-within {
   opacity: 1;
 }
-[data-v-6ea6d3c8] .el-col.dc-form-item-ai-filled > .el-form-item {
-  animation: dc-form-ai-filled-flash-6ea6d3c8 1.6s ease-out;
+[data-v-ba043bbe] .el-col.dc-form-item-ai-filled > .el-form-item {
+  animation: dc-form-ai-filled-flash-ba043bbe 1.6s ease-out;
   border-radius: 4px;
 }
-@keyframes dc-form-ai-filled-flash-6ea6d3c8 {
+@keyframes dc-form-ai-filled-flash-ba043bbe {
 0% {
     background-color: var(--dc-core-primary-color-light-8, var(--el-color-primary-light-8));
 }
@@ -385,16 +395,23 @@ html.dark .view-layout-toolbar[data-v-0507f728] {
 .panel-main-item-col:not(:last-of-type) .panel-main-item-col-wrap_card[data-v-e74d05c3] {
   margin-bottom: var(--v0799966c);
 }
-.form-search_show[data-v-c1fe91f1] {
+.form-search[data-v-e52f9711] {
+  display: flow-root;
+}
+.form-search_show[data-v-e52f9711] {
   margin-bottom: 10px;
 }
-.form-search .btn-box[data-v-c1fe91f1] {
+.form-search[data-v-e52f9711] > .el-form {
+  margin-bottom: calc(-1 * var(--dc-core-form-item-gap, 18px));
+}
+.form-search .btn-box[data-v-e52f9711] {
   display: flex;
   align-items: center;
   gap: 8px;
   justify-content: flex-end;
+  margin-bottom: var(--dc-core-form-item-gap, 18px);
 }
-.form-search .btn-box-expand-icon[data-v-c1fe91f1] {
+.form-search .btn-box-expand-icon[data-v-e52f9711] {
   margin-right: 2px;
 }
 .form-verify-image[data-v-7a70397e] .el-input__suffix-inner * {
@@ -417,11 +434,13 @@ html.dark .view-layout-toolbar[data-v-0507f728] {
   height: 100%;
   background-color: #f4f4f4;
 }
-.tabs-main-bar[data-v-14448dd1] {
+.tabs-main-bar[data-v-2fbdd074] {
   position: relative;
   display: flex;
   align-items: center;
   /* ============ Level —— 只控字号 ============ */
+  /* 卡片变体的内缩距离：**同心圆角公式 R₂ = R₁ + D 的那个 D**。
+     容器 padding 与外圆角 [MUST] 共用它，[MUST NOT] 两处各写一个数（改一处就不同心了）。 */
   /* ============ Variant: card —— 分段块（segmented / pill） ============
      容器一条**面色底**，选中项一块**浅色圆角块** + 主色字。对比来自「块」本身，
      不依赖与下方 content 的连通 —— 故在「各模块成面 + gap 露底」的布局里同样成立。
@@ -435,77 +454,77 @@ html.dark .view-layout-toolbar[data-v-0507f728] {
   /* ============ Variant: indicator-compact —— 紧凑 1px 下划线 ============ */
   /* ============ Variant: plain —— 无装饰(active 加粗 + primary 字色) ============ */
 }
-.tabs-main-bar-item[data-v-14448dd1] {
+.tabs-main-bar-item[data-v-2fbdd074] {
   border: none;
   background: transparent;
   cursor: pointer;
   color: var(--el-text-color-regular);
   transition: background 0.2s, color 0.2s, box-shadow 0.2s;
 }
-.tabs-main-bar-indicator[data-v-14448dd1] {
+.tabs-main-bar-indicator[data-v-2fbdd074] {
   position: absolute;
   left: 0;
   background: var(--dc-core-primary-color);
   transition: transform 0.2s, width 0.2s;
 }
-.tabs-main-bar--l1 .tabs-main-bar-item[data-v-14448dd1] {
+.tabs-main-bar--l1 .tabs-main-bar-item[data-v-2fbdd074] {
   font-size: 16px;
 }
-.tabs-main-bar--l2 .tabs-main-bar-item[data-v-14448dd1] {
+.tabs-main-bar--l2 .tabs-main-bar-item[data-v-2fbdd074] {
   font-size: 14px;
 }
-.tabs-main-bar--l3 .tabs-main-bar-item[data-v-14448dd1] {
+.tabs-main-bar--l3 .tabs-main-bar-item[data-v-2fbdd074] {
   font-size: 12px;
 }
-.tabs-main-bar--l4 .tabs-main-bar-item[data-v-14448dd1] {
+.tabs-main-bar--l4 .tabs-main-bar-item[data-v-2fbdd074] {
   font-size: 12px;
 }
-.tabs-main-bar--variant-card[data-v-14448dd1] {
+.tabs-main-bar--variant-card[data-v-2fbdd074] {
   gap: 2px;
   align-items: stretch;
-  padding: 4px 4px 0;
+  padding: 8px 8px 0;
   background: var(--el-bg-color);
-  border-radius: var(--dc-core-radius, var(--el-border-radius-base)) var(--dc-core-radius, var(--el-border-radius-base)) 0 0;
+  border-radius: calc(var(--dc-core-radius, var(--el-border-radius-base)) + 8px) calc(var(--dc-core-radius, var(--el-border-radius-base)) + 8px) 0 0;
 }
-.tabs-main-bar--variant-card .tabs-main-bar-item[data-v-14448dd1] {
+.tabs-main-bar--variant-card .tabs-main-bar-item[data-v-2fbdd074] {
   display: flex;
   align-items: center;
   padding: 6px 16px;
   line-height: 1.4;
   border-radius: var(--dc-core-radius, var(--el-border-radius-base)) var(--dc-core-radius, var(--el-border-radius-base)) 0 0;
 }
-.tabs-main-bar--variant-card .tabs-main-bar-item[data-v-14448dd1]:hover:not(.tabs-main-bar-item_active) {
+.tabs-main-bar--variant-card .tabs-main-bar-item[data-v-2fbdd074]:hover:not(.tabs-main-bar-item_active) {
   color: var(--dc-core-primary-color);
 }
-.tabs-main-bar--variant-card .tabs-main-bar-item_active[data-v-14448dd1] {
+.tabs-main-bar--variant-card .tabs-main-bar-item_active[data-v-2fbdd074] {
   color: var(--dc-core-primary-color);
   font-weight: 500;
-  background: var(--v72da80bd);
+  background: var(--v0fab19c0);
 }
-.tabs-main-bar--variant-indicator .tabs-main-bar-item[data-v-14448dd1] {
+.tabs-main-bar--variant-indicator .tabs-main-bar-item[data-v-2fbdd074] {
   padding: 8px 16px;
 }
-.tabs-main-bar--variant-indicator .tabs-main-bar-item_active[data-v-14448dd1] {
+.tabs-main-bar--variant-indicator .tabs-main-bar-item_active[data-v-2fbdd074] {
   color: var(--dc-core-primary-color);
 }
-.tabs-main-bar--variant-indicator .tabs-main-bar-indicator[data-v-14448dd1] {
+.tabs-main-bar--variant-indicator .tabs-main-bar-indicator[data-v-2fbdd074] {
   bottom: 0;
   height: 2px;
 }
-.tabs-main-bar--variant-indicator-compact .tabs-main-bar-item[data-v-14448dd1] {
+.tabs-main-bar--variant-indicator-compact .tabs-main-bar-item[data-v-2fbdd074] {
   padding: 6px 10px;
 }
-.tabs-main-bar--variant-indicator-compact .tabs-main-bar-item_active[data-v-14448dd1] {
+.tabs-main-bar--variant-indicator-compact .tabs-main-bar-item_active[data-v-2fbdd074] {
   color: var(--dc-core-primary-color);
 }
-.tabs-main-bar--variant-indicator-compact .tabs-main-bar-indicator[data-v-14448dd1] {
+.tabs-main-bar--variant-indicator-compact .tabs-main-bar-indicator[data-v-2fbdd074] {
   bottom: 0;
   height: 1px;
 }
-.tabs-main-bar--variant-plain .tabs-main-bar-item[data-v-14448dd1] {
+.tabs-main-bar--variant-plain .tabs-main-bar-item[data-v-2fbdd074] {
   padding: 4px 8px;
 }
-.tabs-main-bar--variant-plain .tabs-main-bar-item_active[data-v-14448dd1] {
+.tabs-main-bar--variant-plain .tabs-main-bar-item_active[data-v-2fbdd074] {
   color: var(--dc-core-primary-color);
   font-weight: 600;
 }
@@ -631,7 +650,7 @@ html.dark .view-layout-toolbar[data-v-0507f728] {
   height: 100%;
   padding: 0 20px;
 }
-.app-header[data-v-9ff1c70b] {
+.app-header[data-v-fe33f01b] {
   transition-duration: 0.3s;
   transition-property: height;
   transition-timing-function: linear;
@@ -639,13 +658,13 @@ html.dark .view-layout-toolbar[data-v-0507f728] {
   box-shadow: var(--dc-core-shadow, var(--el-box-shadow));
   z-index: 1;
 }
-.app-header-module[data-v-9ff1c70b] {
+.app-header-module[data-v-fe33f01b] {
   display: flex;
   flex: 1;
   height: 100%;
   overflow-x: auto;
 }
-.app-header-module-item[data-v-9ff1c70b] {
+.app-header-module-item[data-v-fe33f01b] {
   display: flex;
   justify-content: center;
   align-items: center;
@@ -653,24 +672,24 @@ html.dark .view-layout-toolbar[data-v-0507f728] {
   white-space: nowrap;
   height: 100%;
 }
-.app-header-module-item[data-v-9ff1c70b]:hover,
-.app-header-module-item_active[data-v-9ff1c70b] {
-  color: var(--v0b60c1aa);
+.app-header-module-item[data-v-fe33f01b]:hover,
+.app-header-module-item_active[data-v-fe33f01b] {
+  color: var(--v5a41bfe6);
 }
-.app-header-module-item_active[data-v-9ff1c70b] {
+.app-header-module-item_active[data-v-fe33f01b] {
   position: relative;
 }
-.app-header-module-item_active[data-v-9ff1c70b]::before {
+.app-header-module-item_active[data-v-fe33f01b]::before {
   content: "";
   position: absolute;
   left: 50%;
   top: 0;
   width: 100%;
   height: 3px;
-  background-color: var(--v0b60c1aa);
+  background-color: var(--v5a41bfe6);
   transform: translateX(-50%);
 }
-.app-header-shim[data-v-9ff1c70b] {
+.app-header-shim[data-v-fe33f01b] {
   width: 100%;
   height: 100%;
   display: flex;
@@ -680,10 +699,10 @@ html.dark .view-layout-toolbar[data-v-0507f728] {
   font-size: 18px;
   font-weight: bold;
 }
-.app-header-module-item__icon[data-v-9ff1c70b] {
+.app-header-module-item__icon[data-v-fe33f01b] {
   margin-right: 8px;
 }
-.app-header-right[data-v-9ff1c70b] {
+.app-header-right[data-v-fe33f01b] {
   padding-left: 80px;
   display: flex;
   align-items: center;

package/es/utils/dom.mjs

@@ -20,10 +20,20 @@ function domClosestStickyScrollport(el) {
   }
   return void 0;
 }
+function domPreferredScrollBehavior() {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
+    return "smooth";
+  }
+  return window.matchMedia("(prefers-reduced-motion: reduce)").matches ? "auto" : "smooth";
+}
 function domScrollIntoViewport(target, options = {}) {
   if (!target || typeof target.scrollIntoView !== "function") return;
-  const { behavior = "auto", block = "nearest", inline = "nearest" } = options;
-  target.scrollIntoView({ behavior, block, inline });
+  const { block = "nearest", inline = "nearest" } = options;
+  target.scrollIntoView({
+    behavior: options.behavior ?? domPreferredScrollBehavior(),
+    block,
+    inline
+  });
 }
 export {
   domClosestScrollableAncestor,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@done-coding/admin-core",
-  "version": "0.28.0",
+  "version": "0.28.1-alpha.0",
   "description": "内部前端库",
   "private": false,
   "main": "es/index.mjs",
@@ -83,5 +83,5 @@
   "dependencies": {
     "@tanstack/vue-virtual": "^3.13.35"
   },
-  "gitHead": "94210a8d00374756d42018048143cf4b5c0799fe"
+  "gitHead": "89cee2eb458d349b9a6f2f1acb6088f811cd5e8d"
 }

package/src/bridge/docs/README.md

@@ -86,18 +86,26 @@ type BadgeEntry = {
   expireAt?: number;
   /** 面向 agent / AI 对话的语义描述（core 不消费，纯透传；自由文本） */
   description?: string;
+  /** 本条标的版本号（core 不消费，纯透传）；消费方据它做「版本化的已读记录」 */
+  version?: string | number;
 } & (
   | { kind: "count";   value: number; max?: number }   // 数字角标
   | { kind: "new" }        // 新上线
   | { kind: "updated" }    // 更新
   | { kind: "beta" }       // 内测：能用，不稳定
-  | { kind: "wip" }        // 开发：不可用（可用性由 app 自行处置）
+  | { kind: "wip" }        // 开发中：仅提示，**不拦点击**
   | { kind: "custom";  text: string; type?: BadgeProps["type"] }
+  | { kind: "anchor" }     // 伪标：不渲染角标，只留 DOM 挂点供引导定位
 );
 ```
 
 内置五档的文案与语义色由 core 统一定，保证跨 app 一致；`custom` 只在内置档不够用时用。
 
+**`version` 的用处**：消费方（如 `forge-plugin-guide`）把已读记录的 key 取成 `key@version`
+⇒ **功能有实质更新时改一下版本号，引导 / 提示就对所有人重新出现一次**；不改则关过的人不再被打扰。
+不填时退化为裸 `key`。与 `expireAt`（时效）、`bizKey`（业务标识）三者正交，
+[MUST NOT] 拿它做灰度 / 权限判断。
+
 `custom.type` 取 element-plus 的语义色档（`primary` / `success` / `warning` / `danger` / `info`），随主题亮暗自适配。[MUST NOT] 传色值字面量——规则 14，写死色切主题不响应。
 
 ### API
@@ -124,10 +132,27 @@ type BadgeEntry = {
 
 | 消费点 | key 取值 |
 | --- | --- |
-| 菜单项（AppSidebar 菜单树 / AppHeader 模块条） | **路由 `path`**，无需另配 |
+| 菜单项（AppSidebar 菜单树 / AppHeader 模块条） | **路由 `name` 优先、`path` 兜底**（两者都查，先命中先用），无需另配 |
 | `ActionBtn` | 显式 `badgeKey`（按钮没有 path） |
 | `TabsMain` 的 tab 标题（tab-bar / tile 卡片 / tile 角落 nav 三处同步） | `TabsMainItem.badgeKey`。[MUST NOT] 复用 `item.key`——那是**局部唯一**（v-model 值 + 槽名），跨页会串标 |
 
+#### 菜单侧为什么 `name` 优先
+
+看标的**数据来源**：有 `expireAt` 的静态标（随版本写死的 NEW）在前端代码里写，用什么 key 都行；
+而**无 `expireAt` 的动态标（待办数 / 未开通）由服务端下发、app 轮询 `setAll`** —— 那才是主场景，
+而**服务端不该知道前端的 URL 结构**。`path` 是展示层产物：加一层路由前缀、把模块挪一级、
+路径国际化，服务端那张 key 表就整体失效，且**静默失效**（标不显示而已，不报错、不告警）。
+`name` 是路由的逻辑标识，正是为这种跨层引用存在。
+
+`path` [MUST NOT] 拿掉：`name` 在 vue-router 里是**可选的**，没配 name 的路由拿不到 key
+就直接挂不上标；留 path 兜底也让本能力天然 additive —— 现有以 path 注册的一行都不用动。
+
+key 空间不会串：`name` 惯例是 camelCase、`path` 必带 `/`。
+[MUST NOT] 为此引入「带前缀区分类型」之类的 key 编码 —— 那是给零概率问题上税。
+
+⚠️ vue-router 的 `RouteRecordName = string | symbol`，**symbol 不能当 key**；
+`bridge.getRoutes()` 的解析期已过滤（`typeof name === "string" ? name : undefined`）。
+
 ### `description`：让这张表可被 agent 读
 
 `description` 是 **core 完全不消费**的纯透传字段，供应用层做「本期上了什么功能」这类 AI 对话时，让模型知道某个 key 指向什么、怎么用、什么时候还不该用。

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

@@ -62,7 +62,7 @@
 | `contentCentered` | `boolean` | `false` | 默认 slot 内容限宽居中（超宽屏适配）；同步收窄对后代公布的内容几何（见下） |
 | `contentMaxWidth` | `number` | `1200` | 限宽值（px），仅 `contentCentered` 开启时生效 |
 | `gap` | `number` | `8` | 间距基数 px（缺省读 bridge `APP_LAYOUT_GAP_CONFIG.size`）。**槽 ↔ 内容**与**槽 ↔ 槽**都取由它派生的「外圈档」（`基数 × 2`，随密度缩放），两处同式同源 |
-| `topBg` / `bottomBg` / `leftBg` / `rightBg` | `string` | `var(--el-bg-color)`（面色） | 各槽 shim 背景；传 `"transparent"` 可关 |
+| `topBg` / `bottomBg` / `leftBg` / `rightBg` | `string` | `var(--el-bg-color)`（面色） | 各槽 shim 背景；传 `"transparent"` 可关。**shim 自带圆角**（`--dc-core-radius`，随主题；无 bg 的槽透明、圆角无视觉影响） |
 
 > **五个背景 prop 的契约（分两组，判据是「块」还是「容器」）**
 >

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

@@ -108,8 +108,31 @@ bridge.badge.set("/order/list", { kind: "new" });
 | `new` | 新 | `success` 绿 | 新功能上线是**正面资讯**（Atlassian success 档即覆盖 "added"）。[MUST NOT] 复用红——会与 `count` 撞色，扫视时分不清「有新东西」和「有待办」 |
 | `updated` | 更新 | `primary` 主色 | 中性被动通知，不喧宾夺主 |
 | `beta` | 内测 | `warning` 橙 | 能用但**不稳定需谨慎**，正是 warning 语义 |
-| `wip` | 开发 | `info` 灰 | 不可用，中性、不引导点击 |
+| `wip` | 开发 | `info` 灰 | 尚不完善，中性、不引导点击。**仅提示，不拦点击** |
 | `custom` | 自定 | 缺省 `primary` | 内置档不够用时才用；`type` 只收语义档 |
+| `anchor` | —— | —— | **伪标 / 纯锚点**：不渲染角标，只留 DOM 挂点供引导等消费方定位 |
+
+### `anchor`：只要挂点、不要角标
+
+想给某个菜单项 / 按钮做新手引导，但它本身没有「新 / 更新」之类的标要显示时用它。
+[MUST NOT] 为此硬挂一个 `new` —— 那会在界面上多出一个用户看不懂的角标。
+
+🔴 实现上走 `ElBadge` 的 `hidden`（藏角标、留挂点），**[MUST NOT] 改成「不渲染」**：
+本组件是 `v-if="resolved"`，不渲染会连 `data-dc-badge-key` 一起没掉，
+消费方反而**定位不到**，与这档的用途正好相反。
+
+## 遮挡：只有 `locked` 一档拦点击
+
+挂 `locked` 的宿主会被**铺一层透明遮罩吃掉点击**，同时打 `tabindex="-1"` +
+`aria-disabled="true"`（移出 Tab 序列，但读屏仍能读到该项并报告为不可用 ——
+「未开通」是要让用户知道存在且可申请的功能，不是要藏起来）。
+
+**其余全部 kind 照常可点**，含 `wip`：**开发中 ≠ 不可达** —— 半成品页面让人点进去看是
+正常预期，而未开通是**权限边界**，才必须拦。
+
+点击被拦时走 `entry.onTrigger`；未配则出默认提示「请联系平台开通功能」。
+⚠️ `onTrigger` 只在**拦得住**时才有触发点 ⇒ 给 `wip` 配它不会被调用。
+要拦某项就改挂 `locked`，[MUST NOT] 指望用 `onTrigger` 把可点档变成不可点。
 
 ## 反模式 / 注意
 

package/src/components/page-layout/docs/README-AppPageListDetailLayout.md

@@ -103,7 +103,7 @@ watch(isOutOfSync, (v) => v && refreshList());
 | `autoActiveFirst` | `boolean`                                                    | 跟随形态                   | 列表出数后自动激活第一条。**split 默认 `true`**（宽屏右半屏不该空着）、**sheet 默认 `false`**（窄屏自动弹抽屉是打扰）。⚠️ 详情若有副作用（如「打开即标记已读」）[MUST] 显式关掉                                                                                                                                                                                                                                                                                                             |
 | `queryKey`        | `string`                                                     | 无                         | 传了才把 `activeId` 同步进 URL query（**`replace` 不 `push`**）。复原仍走不变式校验                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `detailApi`       | `(params?: { id }) => Promise<R>`                            | 无                         | 传了则内置 `ViewLayout`（零配置拿到内置导航 + `refreshToken` 接线）；不传则 `#detail` 原样渲染、门面零请求                                                                                                                                                                                                                                                                                                                                                                                  |
-| `detailTitle`     | `string \| ((detailData, record) => string)`                 | 无                         | 详情区标题。字符串固定 / 函数按数据算：`detailData` = 详情接口数据（**未传 `detailApi` 时恒 `undefined`**）、`record` = 当前项的列表 item（「详情即列表数据」形态靠它出标题）。⚠️ 渲染在**详情区顶部**（两形态一致），**不是** sheet 弹层的 header —— 详情数据只在详情区内部可得，弹层那层拿不到。不传则不渲染，业务照旧可在 `#detail` 自绘                                                                                                                                                 |
+| `detailTitle`     | `string \| ((detailData, record) => string)`                 | 无                         | 详情区标题。字符串固定 / 函数按数据算：`detailData` = 详情接口数据（**未传 `detailApi` 时恒 `undefined`**）、`record` = 当前项的列表 item（「详情即列表数据」形态靠它出标题）。⚠️ **两形态落点不同**（v0.28.0 ⓤⓤ②：标题一律归「最外层容器的标题位」）：split 档渲染在**详情区顶部**；sheet 档渲染进**弹层自己的 header**（不再重复出现在正文里）。由此 sheet 档的函数形态**只拿得到 `record`、`detailData` 恒 `undefined`**（详情数据在 `ViewLayout` 内部，弹层壳那层拿不到）——需要详情数据驱动的标题，[MUST] 改在 `#detail` 内自绘。不传则不渲染，业务照旧可在 `#detail` 自绘                                                                                                                                                 |
 | `viewLayoutProps` | `Omit<ViewLayoutProps, "api" \| "params" \| "refreshToken">` | 无                         | 透传给内置 `ViewLayout` 的 props——**详情侧的业务操作按钮走这里**：`{ leftExtraButtons: [...] }` 落到 ViewLayout 工具条左侧、与右侧刷新按钮组同一行（`rightExtraButtons` 则置于 `AutoRefreshGroup` 之前）。🔴 `api` / `params` / `refreshToken` 三键被 `Omit`：它们分别由 `detailApi` / `{ id: activeId }` / `activeId` 占位，是「详情跟着当前项走」这条不变式的载体，放开任一个都能让主干**静默失效**（页面看着正常，详情停在上一条）。**未传 `detailApi` 时无内置 ViewLayout，本项无落点** |
 | `sheetLayerType`  | `"drawer" \| "modal"`                                        | `"drawer"`                 | sheet 形态的弹层承载：抽屉 / 居中弹窗。透传 `ModalConfirm.layerType`                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `sheetSize`       | `string \| number`                                           | `"70%"`                    | sheet 弹层尺寸（透传 `ModalConfirm.width`）：drawer 下是抽屉尺寸、modal 下是弹窗宽度                                                                                                                                                                                                                                                                                                                                                                                                        |

package/src/components/view-layout/docs/README-ViewLayout.md

@@ -75,8 +75,14 @@
 「内容的第一行」而非「容器的标题位」——位置与 `ListLayout` 对不齐，主题也无从定向。
 `AppPageDetail` 原先即如此，已归位（见 migrations）。
 
-样式口径同 `ListLayout` 的 header：**露底不成面**（两卡模型里 header 不是卡），
-只给字号 / 字重 / 外距，[MUST NOT] 加背景与描边。
+标题本身只给字号 / 字重，[MUST NOT] 自带背景与描边 —— 它坐在 toolbar 这条**分区条**里，
+底色由条统一给。
+
+**toolbar 是「条」(bar) 不是「卡」(card)**（甲方 2026-09-16 定性）：底色取「面与底的中点」
+（`color-mix(in srgb, --dc-core-surface 50%, --dc-core-ground)`，亮暗自动跟随），
+但守三条纪律 —— **贴边**（零左右呼吸，否则按钮与下方内容区左边界错位，而内容区的面由
+消费方自持、padding 不受本组件控制）· **通栏**（零圆角）· **不加高**（只留既有的 8px 下呼吸）。
+此前「工具条成卡」被否的根因不是「有面」，而是面顺带塞进 12px 内呼吸把 32px 的条撑到 56px。
 
 ## API
 > ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。

package/types/bridge/badge.d.ts

@@ -53,12 +53,12 @@ export type BadgeEntry = {
     /**
      * 被遮挡的标被触发时的回调（点宿主 / 点角标都算触发）。
      *
-     * **[MUST] 只有 `wip` / `locked` 两档会调用它**——只有这两档会遮挡宿主交互，
-     * 其余 kind 是纯展示、宿主照常可点，没有"被拦下的那次点击"可供回调。
-     * 字段放在共享段（而非收窄进那两个 kind）是甲方口径：所有 kind 都可配、非必传。
+     * **[MUST] 只有 `locked` 一档会调用它**——只有这一档会遮挡宿主交互，
+     * 其余 kind（含 `wip`）是纯展示、宿主照常可点，没有"被拦下的那次点击"可供回调。
+     * 字段放在共享段（而非收窄进 `locked`）是甲方口径：所有 kind 都可配、非必传。
      *
-     * 缺省时由 core 出默认提示（`locked` →「请联系平台开通功能」/ `wip` →
-     * 「功能正在加紧开发中」）。要改文案就自己配本回调去弹，core [MUST NOT] 再开覆盖字段。
+     * 缺省时由 core 出默认提示（`locked` →「请联系平台开通功能」）。
+     * 要改文案就自己配本回调去弹，core [MUST NOT] 再开覆盖字段。
      */
     onTrigger?: (entry: BadgeEntry) => void;
     /**
@@ -72,6 +72,23 @@ export type BadgeEntry = {
      * 聚合与数据来源全在 app（同本文件开头的分工）。
      */
     bizKey?: string;
+    /**
+     * 本条标的版本号——**core 不消费、纯透传**，供消费方做「版本化的已读记录」。
+     *
+     * 典型用法（`forge-plugin-guide`）：引导弹窗被用户关掉后记一条「看过了」，
+     * 进度 key 取 **`key@version`**；不填版本时退化为裸 `key`。
+     * ⇒ **功能有实质更新时改一下版本号，引导就会对所有人重新出现一次**，
+     * 而不改版本则关过的人永远不再被打扰。
+     *
+     * [MUST NOT] 拿它做灰度 / 权限判断——它只是「这条标的第几版」，
+     * 与 {@link BadgeEntry.expireAt}（时效）、{@link BadgeEntry.bizKey}（业务标识）三者正交。
+     *
+     * 收 `number` 是刻意的：后端常直接发数字版本，强制消费方转字符串是无谓摩擦；
+     * 拼 key 时统一走模板串，`1` 与 `"1"` 拼出同一个 key、无歧义。
+     *
+     * @example { kind: "new", description: "批量导出…", version: 2 }
+     */
+    version?: string | number;
 } & ({
     /** 数字角标 */
     kind: "count";
@@ -91,6 +108,20 @@ export type BadgeEntry = {
     kind: "deprecated";
 } | {
     kind: "locked";
+}
+/**
+ * **伪标 / 纯锚点**：不渲染任何角标，只在 DOM 上留一个带 key 的挂点，
+ * 供 `forge-plugin-guide` 这类消费方**定位**到这个宿主。
+ *
+ * 用途：想给某个菜单项 / 按钮做新手引导，但它本身**没有**「新 / 更新」之类的标要显示。
+ * [MUST NOT] 为此硬挂一个 `new` 标——那会在界面上多出一个用户看不懂的角标。
+ *
+ * 🔴 它**不进自动串**：guide 的 `badgeKinds` 默认只收资讯档（`new` / `updated`），
+ * 本档要由**显式 `steps`** 用 `badgeKey` 引用才会成为一步 —— 这正是它的定位，
+ * 「我只提供锚点，跑不跑、什么时候跑由编排决定」。
+ */
+ | {
+    kind: "anchor";
 } | {
     /** 自定义标：内置五档不够用时才用 */
     kind: "custom";
@@ -104,8 +135,14 @@ export type BadgeEntry = {
 });
 /** 内置标（非 count / custom）的 kind 联合——文案与语义色由 core 统一定，保证跨 app 一致 */
 export type BadgeBuiltinKind = "new" | "updated" | "beta" | "wip" | "deprecated" | "locked";
-/** 会遮挡宿主交互的 kind——[MUST] 与 `use-badge-mask` 的判据同源，[MUST NOT] 两处各写一份 */
-export declare const BADGE_MASK_KINDS: readonly ["wip", "locked"];
+/**
+ * 会遮挡宿主交互的 kind——[MUST] 与 `use-badge-mask` 的判据同源，[MUST NOT] 两处各写一份。
+ *
+ * 🔴 **只有 `locked` 一档**（甲方 2026-09-16：「我期望只有未开通才点不进去」）：
+ * `wip`「开发中」**不拦** —— 开发中 ≠ 不可达，半成品页面让人点进去看是正常预期；
+ * 未开通是**权限边界**，才必须拦。要拦某项就改挂 `locked`。
+ */
+export declare const BADGE_MASK_KINDS: readonly ["locked"];
 /** bridge 徽标 hook 工厂入参 */
 export interface BridgeBadgeInit {
     /** 初始标记表（如随版本发布的静态 NEW 标）；缺省空表 */

package/types/components/app-layout/app-page-geometry.d.ts

@@ -82,7 +82,14 @@ export declare function computeAppPageSlotStyles(rect: AppPageRectInset, slotSiz
  * - **朝内容侧**：间隔改由**默认槽**让出（见 {@link appPageSlotInset}），
  *   槽这边 [MUST] 归零，否则两边各让一份 = 双份。
  *
- * 保留本函数而非删掉挂点：槽内层 shim 仍是布局盒（`left/right` 靠它填满竖轨），
- * 且留一个显式的「四边为 0 是刻意的」出口，比让下一个人从空 div 里猜要好。
+ * 保留本函数而非删掉挂点：槽内层 shim 仍是布局盒（`left/right` 靠它填满竖轨）。
+ *
+ * 🔴 **2026-09-16 起改为四边 `8px`**（甲方定）：槽拿到自己的背景色与圆角之后，它已经是
+ * 一个**有形的块**而非纯占位轨 —— 内容贴着块边缘（还会被圆角切角）不成样子，故给块内呼吸。
+ *
+ * ⚠️ 这**不构成上文的「双份」**：让位量取槽的**实测尺寸**（`clientWidth/Height` 含 padding），
+ * 槽变胖多少默认内容就多让多少 ⇒「槽边缘 ↔ 默认内容」恒为一个外圈档不变，新增的 8px 落在
+ * **槽内**（槽边缘 ↔ 槽内内容）。上文「朝内容侧 [MUST] 归零」针对的是旧式做法 ——
+ * 那时槽无背景、padding 直接充当间隔，才会与让位叠成双份。
  */
 export declare function computeAppPageSlotShimStyles(): AppPageSlotStyles;