@done-coding/admin-core 0.29.0 → 0.29.1-alpha.0

package/es/style.css

@@ -66,14 +66,14 @@
   justify-content: flex-end;
   gap: 8px;
 }
-.badge-mark[data-v-18853ddc] .el-badge__content.is-fixed {
+.badge-mark[data-v-9eb89306] .el-badge__content.is-fixed {
   right: 0;
   transform: translateY(-50%) translateX(calc(100% + 2px));
 }
-.badge-mark_middle[data-v-18853ddc] .el-badge__content.is-fixed {
+.badge-mark_middle[data-v-9eb89306] .el-badge__content.is-fixed {
   top: 50%;
 }
-.badge-mark[data-v-18853ddc] .badge-mark__icon {
+.badge-mark[data-v-9eb89306] .badge-mark__icon {
   display: block;
   font-size: 1em;
   line-height: 1;
@@ -131,7 +131,7 @@ to {
   text-align: center;
   font-variant-numeric: tabular-nums;
 }
-.view-layout-header[data-v-e7dc3f12] {
+.view-layout-header[data-v-3c6fd3fe] {
   flex: 0 1 auto;
   min-width: 0;
   overflow: hidden;
@@ -142,21 +142,21 @@ to {
   white-space: nowrap;
   text-overflow: ellipsis;
 }
-.view-layout[data-v-e7dc3f12] {
+.view-layout[data-v-3c6fd3fe] {
   display: flex;
   flex-direction: column;
 }
-.view-layout-toolbar[data-v-e7dc3f12] {
+.view-layout-toolbar[data-v-3c6fd3fe] {
   display: flex;
   justify-content: space-between;
   align-items: center;
-  padding: 0 8px 8px;
+  padding: 0 var(--v72fb5e44) 0 var(--v7243a29e);
   position: relative;
   gap: 20px;
   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[data-v-e7dc3f12]::before {
+.view-layout-toolbar[data-v-3c6fd3fe]::before {
   content: "";
   position: absolute;
   top: 0;
@@ -166,33 +166,35 @@ to {
   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] {
+.view-layout-toolbar__left[data-v-3c6fd3fe],
+.view-layout-toolbar__right[data-v-3c6fd3fe] {
   display: flex;
   align-items: center;
   gap: 10px;
 }
-.view-layout-toolbar__left[data-v-e7dc3f12] > *,
-.view-layout-toolbar__right[data-v-e7dc3f12] > * {
+.view-layout-toolbar__left[data-v-3c6fd3fe] > *,
+.view-layout-toolbar__right[data-v-3c6fd3fe] > * {
   flex: none;
 }
-.view-layout-toolbar__left .view-layout-header[data-v-e7dc3f12] {
+.view-layout-toolbar__left .view-layout-header[data-v-3c6fd3fe] {
   flex: 1 1 auto;
 }
-.view-layout-toolbar__right[data-v-e7dc3f12] {
+.view-layout-toolbar__right[data-v-3c6fd3fe] {
   flex: none;
 }
-.view-layout-content[data-v-e7dc3f12] {
+.view-layout-content[data-v-3c6fd3fe] {
   overflow: auto;
+  box-sizing: border-box;
+  padding: var(--v72fb5e44) var(--v72fb5e44) var(--v72fb5e44) var(--v7243a29e);
 }
-.dc-app-page-detail__title[data-v-4426d26a] {
+.dc-app-page-detail__title[data-v-1b784d3a] {
   padding-bottom: 12px;
   font-size: 16px;
   font-weight: 600;
   line-height: 24px;
   color: var(--dc-core-text-color, var(--el-text-color-primary));
 }
-.dc-app-page-list-detail-split__list[data-v-e97ba16e] {
+.dc-app-page-list-detail-split__list[data-v-7aa91bcb] {
   box-sizing: border-box;
   height: 100%;
   overflow: hidden;
@@ -555,7 +557,7 @@ to {
   box-shadow: var(--dc-core-shadow, var(--el-box-shadow-lighter));
   border: 1px solid var(--dc-core-border-color, var(--el-border-color-lighter));
 }
-.app-collapse-toggle[data-v-10c7e006] {
+.app-collapse-toggle[data-v-7c080128] {
   position: absolute;
   top: 50%;
   cursor: pointer;
@@ -563,50 +565,51 @@ to {
   height: 44px;
   border-radius: 7px;
   background-color: var(--dc-core-surface, var(--el-bg-color-overlay));
-  border: 1px solid var(--dc-core-border-color, var(--el-border-color-lighter));
-  color: var(--el-text-color-secondary);
+  border: 1px solid var(--dc-core-border-color, var(--el-border-color));
+  color: var(--el-text-color-regular);
   display: flex;
   align-items: center;
   justify-content: center;
   font-size: 12px;
   z-index: 1;
-  opacity: 0.3;
+  opacity: 1;
   box-shadow: none;
   transition: opacity 0.2s ease, color 0.2s ease, border-color 0.2s ease, box-shadow 0.2s ease;
 }
-.app-collapse-toggle--sidebar[data-v-10c7e006] {
+.app-collapse-toggle--sidebar[data-v-7c080128] {
   left: 100%;
   transform: translate(-50%, -50%);
 }
-.app-collapse-toggle--aside[data-v-10c7e006] {
+.app-collapse-toggle--aside[data-v-7c080128] {
   right: 100%;
   transform: translate(50%, -50%);
 }
-.app-collapse-toggle[data-v-10c7e006]:hover,
-.app-collapse-toggle[data-v-10c7e006]:focus-visible {
+.app-collapse-toggle[data-v-7c080128]:hover,
+.app-collapse-toggle[data-v-7c080128]:focus-visible {
   opacity: 1;
   color: var(--el-text-color-primary);
   border-color: var(--dc-core-border-color, var(--el-border-color));
   box-shadow: var(--el-box-shadow-lighter);
 }
-.app-collapse-toggle[data-v-10c7e006]:active {
+.app-collapse-toggle[data-v-7c080128]:active {
   border-color: var(--dc-core-primary-color, var(--el-color-primary));
 }
-.app-collapse-toggle__icon[data-v-10c7e006] {
+.app-collapse-toggle__icon[data-v-7c080128] {
   transition: transform 0.3s;
 }
-.app-aside[data-v-7e17d342] {
+.app-aside[data-v-d6ef7f3d] {
   transition: width var(--dc-core-motion-duration-slow, 300ms) var(--dc-core-motion-easing, ease);
   box-shadow: var(--dc-core-shadow, var(--el-box-shadow));
   overflow: visible;
   z-index: 0;
 }
-.app-aside-clip[data-v-7e17d342] {
+.app-aside-clip[data-v-d6ef7f3d] {
   position: absolute;
   inset: 0;
   overflow: hidden;
+  border-radius: inherit;
 }
-.app-aside-shim[data-v-7e17d342] {
+.app-aside-shim[data-v-d6ef7f3d] {
   position: absolute;
   right: 0;
   top: 0;
@@ -616,8 +619,8 @@ to {
   transition: opacity var(--dc-core-motion-duration, 200ms) var(--dc-core-motion-easing, ease);
 }
 @media (prefers-reduced-motion: reduce) {
-.app-aside[data-v-7e17d342],
-  .app-aside-shim[data-v-7e17d342] {
+.app-aside[data-v-d6ef7f3d],
+  .app-aside-shim[data-v-d6ef7f3d] {
     transition: none;
 }
 }
@@ -637,7 +640,7 @@ to {
   display: flow-root;
   --app-viewport-max-height: var(--ece8e1ac);
 }
-.app-footer[data-v-8960664d] {
+.app-footer[data-v-de6fd086] {
   transition-duration: 0.3s;
   transition-property: height;
   transition-timing-function: linear;
@@ -645,12 +648,11 @@ to {
   width: 100%;
   box-shadow: var(--dc-core-shadow, var(--el-box-shadow));
 }
-.app-footer-shim[data-v-8960664d] {
+.app-footer-shim[data-v-de6fd086] {
   width: 100%;
   height: 100%;
-  padding: 0 20px;
 }
-.app-header[data-v-fe33f01b] {
+.app-header[data-v-6fa13544] {
   transition-duration: 0.3s;
   transition-property: height;
   transition-timing-function: linear;
@@ -658,13 +660,13 @@ to {
   box-shadow: var(--dc-core-shadow, var(--el-box-shadow));
   z-index: 1;
 }
-.app-header-module[data-v-fe33f01b] {
+.app-header-module[data-v-6fa13544] {
   display: flex;
   flex: 1;
   height: 100%;
   overflow-x: auto;
 }
-.app-header-module-item[data-v-fe33f01b] {
+.app-header-module-item[data-v-6fa13544] {
   display: flex;
   justify-content: center;
   align-items: center;
@@ -672,69 +674,74 @@ to {
   white-space: nowrap;
   height: 100%;
 }
-.app-header-module-item[data-v-fe33f01b]:hover,
-.app-header-module-item_active[data-v-fe33f01b] {
-  color: var(--v5a41bfe6);
+.app-header-module-item[data-v-6fa13544]:hover,
+.app-header-module-item_active[data-v-6fa13544] {
+  color: var(--v1c549aee);
 }
-.app-header-module-item_active[data-v-fe33f01b] {
+.app-header-module-item_active[data-v-6fa13544] {
   position: relative;
 }
-.app-header-module-item_active[data-v-fe33f01b]::before {
+.app-header-module-item_active[data-v-6fa13544]::before {
   content: "";
   position: absolute;
   left: 50%;
   top: 0;
   width: 100%;
   height: 3px;
-  background-color: var(--v5a41bfe6);
+  background-color: var(--v1c549aee);
   transform: translateX(-50%);
 }
-.app-header-shim[data-v-fe33f01b] {
+.app-header-shim[data-v-6fa13544] {
   width: 100%;
   height: 100%;
   display: flex;
   align-items: center;
   justify-content: space-between;
-  padding: 0 20px;
   font-size: 18px;
   font-weight: bold;
 }
-.app-header-module-item__icon[data-v-fe33f01b] {
+.app-header-module-item__icon[data-v-6fa13544] {
   margin-right: 8px;
 }
-.app-header-right[data-v-fe33f01b] {
+.app-header-right[data-v-6fa13544] {
   padding-left: 80px;
   display: flex;
   align-items: center;
 }
-.app-sidebar[data-v-6808ecdb] {
+.app-sidebar[data-v-e8e50875] {
   transition-duration: 0.3s;
   transition-property: width;
   transition-timing-function: linear;
   box-shadow: var(--dc-core-shadow, var(--el-box-shadow));
   overflow: visible;
-  z-index: var(--a540a4d0);
+  z-index: var(--v2dcbfdd5);
 }
-.app-sidebar-top[data-v-6808ecdb] {
+.app-sidebar-clip[data-v-e8e50875] {
+  position: absolute;
+  inset: 0;
+  overflow: hidden;
+  border-radius: inherit;
+}
+.app-sidebar-top[data-v-e8e50875] {
   position: absolute;
   left: 0;
   right: 0;
   top: 0;
   overflow: hidden;
 }
-.app-sidebar-bottom[data-v-6808ecdb] {
+.app-sidebar-bottom[data-v-e8e50875] {
   position: absolute;
   left: 0;
   right: 0;
   bottom: 0;
   overflow: hidden;
 }
-.app-sidebar-shim[data-v-6808ecdb] {
+.app-sidebar-shim[data-v-e8e50875] {
   position: absolute;
   left: 0;
   right: 0;
-  top: var(--v4433cc00);
-  bottom: var(--v7d77fda0);
+  top: var(--v78ee9bfd);
+  bottom: var(--v3ef242fa);
   overflow-x: hidden;
   overflow-y: auto;
   --el-menu-border-color: transparent;
@@ -927,22 +934,24 @@ to {
     animation: none;
 }
 }
-.infinite-list-view_surface[data-v-6539caa4] {
+.infinite-list-view_surface[data-v-a62d17f9] {
   box-sizing: border-box;
-  padding: var(--v0d4fd951);
-  background: var(--el-bg-color);
+  padding: var(--v9e087332);
   border-radius: var(--dc-core-radius, var(--el-border-radius-base));
 }
-.infinite-list-view[data-v-6539caa4] {
+.infinite-list-view_surface-bg[data-v-a62d17f9] {
+  background: var(--el-bg-color);
+}
+.infinite-list-view[data-v-a62d17f9] {
   width: 100%;
 }
-.infinite-list-view__viewport[data-v-6539caa4] {
+.infinite-list-view__viewport[data-v-a62d17f9] {
   width: 100%;
 }
-.infinite-list-view__sentinel[data-v-6539caa4] {
+.infinite-list-view__sentinel[data-v-a62d17f9] {
   height: 1px;
 }
-.infinite-list-view__footer[data-v-6539caa4] {
+.infinite-list-view__footer[data-v-a62d17f9] {
   display: flex;
   justify-content: center;
   align-items: center;
@@ -950,17 +959,17 @@ to {
   color: var(--dc-core-text-color-secondary, var(--el-text-color-secondary));
   font-size: 13px;
 }
-.infinite-list-view__json[data-v-6539caa4] {
+.infinite-list-view__json[data-v-a62d17f9] {
   margin: 0;
   font-size: 12px;
   white-space: pre-wrap;
   word-break: break-all;
   color: var(--dc-core-text-color-secondary, var(--el-text-color-secondary));
 }
-.infinite-list-view__tip[data-v-6539caa4] {
+.infinite-list-view__tip[data-v-a62d17f9] {
   color: var(--dc-core-text-color-secondary, var(--el-text-color-secondary));
 }
-.infinite-list-view__retry[data-v-6539caa4] {
+.infinite-list-view__retry[data-v-a62d17f9] {
   border: none;
   background: transparent;
   color: var(--dc-core-primary-color, var(--el-color-primary));
@@ -968,10 +977,10 @@ to {
   cursor: pointer;
   padding: 0;
 }
-.infinite-list-view__retry[data-v-6539caa4]:hover {
+.infinite-list-view__retry[data-v-a62d17f9]:hover {
   opacity: 0.8;
 }
-.infinite-list-view__empty[data-v-6539caa4] {
+.infinite-list-view__empty[data-v-a62d17f9] {
   display: flex;
   justify-content: center;
   align-items: center;
@@ -979,7 +988,7 @@ to {
   min-height: 60px;
   color: var(--dc-core-text-color-secondary, var(--el-text-color-secondary));
 }
-.infinite-list-view__pull-indicator[data-v-6539caa4] {
+.infinite-list-view__pull-indicator[data-v-a62d17f9] {
   display: flex;
   justify-content: center;
   align-items: flex-end;
@@ -988,53 +997,56 @@ to {
   color: var(--dc-core-text-color-secondary, var(--el-text-color-secondary));
   transition: height 0.2s;
 }
-.infinite-list-view__pull-indicator > span[data-v-6539caa4] {
+.infinite-list-view__pull-indicator > span[data-v-a62d17f9] {
   padding-bottom: 6px;
 }
-.data-grid-view[data-v-90c0ccf6] {
+.data-grid-view[data-v-136078cd] {
   width: 100%;
 }
-.data-grid-view_surface[data-v-90c0ccf6] {
-  padding: var(--c829655a);
-  background: var(--el-bg-color);
+.data-grid-view_surface[data-v-136078cd] {
+  padding: var(--e2a8f6ae);
   border-radius: var(--dc-core-radius, var(--el-border-radius-base));
 }
-.data-grid-view__grid[data-v-90c0ccf6] {
+.data-grid-view_surface-bg[data-v-136078cd] {
+  background: var(--el-bg-color);
+}
+.data-grid-view__grid[data-v-136078cd] {
   display: grid;
-  gap: 12px;
-  padding-bottom: 12px;
 }
-.data-grid-view__cell.is-active[data-v-90c0ccf6] {
+.data-grid-view__cell.is-active[data-v-136078cd] {
   /* stylelint-disable-next-line block-no-empty */
 }
-.data-grid-view__cell[data-v-90c0ccf6] {
+.data-grid-view__cell[data-v-136078cd] {
   min-width: 0;
 }
-.data-grid-view__card[data-v-90c0ccf6] {
+.data-grid-view__cell.is-card[data-v-136078cd] {
+  box-sizing: border-box;
+  background: var(--el-bg-color);
   border: 1px solid var(--dc-core-border-color, var(--el-border-color-lighter));
-  border-radius: var(--dc-core-radius, 4px);
-  padding: 10px 12px;
+  border-radius: var(--dc-core-radius, var(--el-border-radius-base));
+}
+.data-grid-view__card[data-v-136078cd] {
   height: 100%;
   box-sizing: border-box;
   overflow: hidden;
 }
-.data-grid-view__field[data-v-90c0ccf6] {
+.data-grid-view__field[data-v-136078cd] {
   display: flex;
   gap: 6px;
   align-items: baseline;
   line-height: 1.6;
   font-size: 13px;
 }
-.data-grid-view__field-label[data-v-90c0ccf6] {
+.data-grid-view__field-label[data-v-136078cd] {
   flex-shrink: 0;
   color: var(--dc-core-text-color-secondary, var(--el-text-color-secondary));
 }
-.data-grid-view__field-value[data-v-90c0ccf6] {
+.data-grid-view__field-value[data-v-136078cd] {
   overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
 }
-.data-grid-view__empty-error[data-v-90c0ccf6] {
+.data-grid-view__empty-error[data-v-136078cd] {
   display: flex;
   justify-content: center;
   align-items: center;
@@ -1409,16 +1421,27 @@ html.dark .form-item-nest-form[data-v-46959572]::before {
 .dc-form-upload-video__thumb_empty[data-v-5eac98bc] {
   background: var(--el-fill-color-light);
 }
-.data-list-view-item.is-selected[data-v-c2a6c6be] {
+.data-list-view-item.is-selected[data-v-4b05138c] {
   /* 选中（勾选）态钩子，具体视觉由消费方覆写 */
 }
-.data-list-view-item.is-active[data-v-c2a6c6be] {
+.data-list-view-item.is-active[data-v-4b05138c] {
   /* 当前项（active）态钩子，具体视觉由消费方覆写 */
 }
-.data-list-view[data-v-0d316a42] {
+.data-list-view-item.is-card[data-v-4b05138c] {
+  box-sizing: border-box;
+  padding: 12px;
+  background: var(--el-bg-color);
+  border: 1px solid var(--dc-core-border-color, var(--el-border-color-lighter));
+  border-radius: var(--dc-core-radius, var(--el-border-radius-base));
+}
+.data-list-view-item.is-masonry[data-v-4b05138c] {
+  align-self: start;
+  grid-row-end: span 125;
+}
+.data-list-view[data-v-f900ae4e] {
   width: 100%;
 }
-.data-list-view-empty[data-v-0d316a42] {
+.data-list-view-empty[data-v-f900ae4e] {
   display: flex;
   justify-content: center;
   align-items: center;
@@ -1426,18 +1449,20 @@ html.dark .form-item-nest-form[data-v-46959572]::before {
   min-height: 60px;
   grid-column: 1 / -1;
 }
-.table-main_surface[data-v-431aac71] {
-  padding: var(--v02eff1c8);
-  background: var(--el-bg-color);
+.table-main_surface[data-v-f5764fe4] {
+  padding: var(--v5308fe58);
   border-radius: var(--dc-core-radius, var(--el-border-radius-base));
 }
-.table-main-pagination[data-v-431aac71] {
+.table-main_surface-bg[data-v-f5764fe4] {
+  background: var(--el-bg-color);
+}
+.table-main-pagination[data-v-f5764fe4] {
   margin-top: 10px;
   display: flex;
   justify-content: flex-end;
 }
-.table-main_fill[data-v-431aac71] .el-table__body-wrapper {
-  min-height: var(--v75a7164e);
+.table-main_fill[data-v-f5764fe4] .el-table__body-wrapper {
+  min-height: var(--v418a0592);
 }
 .dc-slot-layout-flow-aside_separate[data-v-5c6ef74b] {
   position: relative;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@done-coding/admin-core",
-  "version": "0.29.0",
+  "version": "0.29.1-alpha.0",
   "description": "内部前端库",
   "private": false,
   "main": "es/index.mjs",
@@ -83,5 +83,5 @@
   "dependencies": {
     "@tanstack/vue-virtual": "^3.13.35"
   },
-  "gitHead": "e2bd73b54a75a6df469b1ec7916a38998318609a"
+  "gitHead": "428001dd152178576b5f87445148896efdde98c5"
 }

package/src/bridge/docs/README.md

@@ -219,6 +219,37 @@ appCoreBridge.update("APP_LAYOUT_SIDEBAR_CONFIG", { menuGroupMode: true });
 
 适用判据与三级菜单的混合渲染规则见 [menu 族文档](../../components/menu/README.md) 与 [AppSidebar 文档](../../components/app-layout/docs/README-AppSidebar.md)。
 
+## 展开菜单到某路径（`bridge.layout.openMenuTo`）
+
+```ts
+const ok = bridge.layout.openMenuTo("/system/user/detail");
+```
+
+把目标路径**沿途的父级子菜单全部展开**，返回是否成功。缘起是引导（`forge-plugin-guide`）
+要高亮折叠子菜单里的项 —— 那种元素虽在 DOM 里但 `display:none`、rect 全 0，
+引导只能跳过它（插件侧已有 `getClientRects().length` 判空的防御，避免按 `(0,0)` 把弹窗
+摆到屏幕左上角）。防御解决的是「不出坏效果」，本方法解决「到得了那一步」。
+
+**判据是 `getClientRects().length > 0`**（目标项真的占布局），[MUST NOT] 用「没报错」当成功。
+
+### 三种形态下的行为
+
+| 形态 | 行为 |
+| --- | --- |
+| 常规树形菜单 | 逐级 `open()` 沿途父级 → `true` |
+| 分组形态（`menuGroupMode`） | 父级是 section heading、**本就全展开** ⇒ **no-op 返回 `true`** |
+| **侧栏折叠态** | **先展开侧栏**（`setSidebarCollapse(false)`）再展开沿途父级 → `true` |
+
+🔴 **折叠态自动展开侧栏是甲方 2026-09-18 的裁决**，且**事后不还原**：
+
+- 代价知情：折叠态是**持久化到 localStorage 的用户偏好**，本方法等于程序化改写它。
+  依据 = 引导是用户主动发起的流程，为让他看见而展开属正当副作用，且「他刚学会这个入口」
+  留在展开态反而合理。
+- [MUST NOT] 改成「展开后自动还原」：还原时机不可靠（引导弹窗还开着就还原会当场收起菜单），
+  异常路径 / 快速切路由会让状态泄漏 —— 同 `store/app.ts` 的 viewportConfig 为何取派生而非
+  「改真相源 + 还原」。
+- 路径不存在 / 无侧栏（`showSidebar` 为假）→ `false`，且**不动任何状态**。
+
 ## 认证与请求接线
 
 ### 认证 facade（bridge 4 钩子 + userInfoAccess）

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

@@ -33,6 +33,17 @@
 - `show` 显隐基线来自路由 `meta.layout.aside`（store showAside），false 整列不渲染。
 - **完整能力演示**（#aside 锚 + 自供 shell）：`apps/reference/src/App.vue`、`apps/reference/src/pages/app-layout/shell/`
 
+## 面貌（背景 / 圆角 / 无横向内呼吸）
+
+与 `AppSidebar` **同口径**（对称积木，[MUST] 一起改）：背景 `APP_LAYOUT_ASIDE_CONFIG.background ?? 主题 bodyColor`、
+圆角 `var(--dc-core-radius, var(--el-border-radius-base))`，两者同在 `appStore.asideStyle` 这一份 inline style 里，
+默认值写在 `...cfg.style` 展开之前 ⇒ `APP_LAYOUT_ASIDE_CONFIG.style.borderRadius` 可整体覆盖。
+
+- **不给横向内呼吸**：内容由消费方经默认插槽自填，呼吸归内容自己——core 代为让白会与内容自带的 padding 叠成双份。
+- 圆角由既有的 `.app-aside-clip`（`inset: 0` + `overflow: hidden`）承接裁切（已补 `border-radius: inherit`）；
+  根盒 `overflow: visible` 是折叠把手悬挂所需，[MUST NOT] 改。
+- 折叠 / 隐藏态宽收 0 ⇒ 零面积、不留圆角残影。
+
 ## API
 > ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
 

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

@@ -5,7 +5,17 @@
 
 ## 定位
 
-AppFooter 是族内最薄的积木：自身无任何对外接口（无 props / emits / slots / expose），只做一件事——inject 应用 store 窄化实例（`APP_LAYOUT_APP_STORE_KEY`），把 `appStore.footerStyle` 绑到根盒 `:style` 上渲染底部状态条（高度/留白/阴影由 store 驱动，阴影走主题 var）。显隐与高度变化全部由 AppLayout/store 侧控制，消费方不直接挂载、也无可配置项。
+AppFooter 是族内最薄的积木：自身无任何对外接口（无 props / emits / slots / expose），只做一件事——inject 应用 store 窄化实例（`APP_LAYOUT_APP_STORE_KEY`），把 `appStore.footerStyle` 绑到根盒 `:style` 上渲染底部状态条（高度 / 背景 / 圆角 / 横向内呼吸由 store 驱动，阴影走主题 var）。显隐与高度变化全部由 AppLayout/store 侧控制，消费方不直接挂载、也无可配置项。
+
+**面貌三项与 AppHeader 同源同口径**（对称积木，[MUST] 一起改）：
+
+| 项 | 默认 | 覆盖法 |
+| --- | --- | --- |
+| 背景 | `APP_LAYOUT_FOOTER_CONFIG.background ?? 主题 bodyColor` | 配 `background` |
+| 圆角 | `var(--dc-core-radius, var(--el-border-radius-base))` | `APP_LAYOUT_FOOTER_CONFIG.style.borderRadius` |
+| 横向内呼吸 | 间距阶梯**模块档**（默认 **8px**） | `APP_LAYOUT_FOOTER_CONFIG.style.padding` |
+
+圆角 / padding 的默认值在 `...cfg.style` 展开**之前**写入 ⇒ 逃生舱同名键恒赢；`height` / `marginTop` / `background` / `color` 仍是引擎托管键（展开之后，压过外部）。
 
 ## 能力边界 / 按需使用
 

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

@@ -9,6 +9,8 @@
 - #left = 品牌/业务入口（AppLayout `#brand` 锚落位）；#right = userEntry/settings/themeSwitcher 操作区
 - 中间区 = 路由大模块菜单（menus 渲染，点击高亮 activeModulePath）
 - 整体显隐由 AppLayout 间接控制（store headerStyle.height=0 视觉收起 + dom 保留）
+- **面貌（背景 / 圆角 / 横向内呼吸）三项同源** —— 都在 `appStore.headerStyle` 这一份 inline style 里
+  （[MUST NOT] 把其中任何一项挪回 scoped CSS：一半 inline 一半 CSS 会让消费方覆盖时只改得动一半）
 
 ## 模块条徽标（badge）
 
@@ -41,6 +43,19 @@
 - `#left` / `#right` 槽内容来自 AppLayout 内容锚转发（`#brand` → `#left`；`#userEntry` / `#settings` / `#themeSwitcher` → `#right`）——内置 shell 零配置；自供 shell 直引时按槽转发范式接住。
 - **完整能力演示**（自供 shell 积木直引 + NoHeader 变体）：`apps/reference/src/pages/app-layout/shell/`、`apps/reference/src/pages/app-layout/layout/`
 
+## 面貌与覆盖（背景 / 圆角 / 内呼吸）
+
+| 项 | 默认 | 覆盖法 |
+| --- | --- | --- |
+| 背景 | `APP_LAYOUT_HEADER_CONFIG.background ?? 主题 bodyColor` | 配 `background`（支持色 / 渐变 / 背景图） |
+| 圆角 | `var(--dc-core-radius, var(--el-border-radius-base))`（随主题） | `APP_LAYOUT_HEADER_CONFIG.style.borderRadius` |
+| 横向内呼吸 | 间距阶梯**模块档**（`gap.size` × 密度 × 1，默认 **8px**） | `APP_LAYOUT_HEADER_CONFIG.style.padding` |
+
+- 圆角 / padding 的默认值**在 `...cfg.style` 展开之前**写入 ⇒ `style` 逃生舱里的同名键恒赢，可整体覆盖。
+  （`position` / `top` / `left` / `right` / `height` / `background` / `color` 是**引擎托管键**，写在展开之后，
+  外部传了也压不过——这条不变。）
+- `box-sizing: border-box` 由引擎托管：横向 padding 恒收在盒内，[MUST NOT] 指望消费方的全局 reset。
+
 ## API
 > ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
 
@@ -73,6 +88,7 @@
 
 - **`show` 勿用于显隐控制**：声明必填但模板未消费——整体显隐由 AppLayout 经 store 间接控制（headerStyle.height=0 视觉收起 + dom 保留）
 - 主题切换器不属 Header 私有：已解耦为 `AppTheme`，经 shell #right 注入（默认内容仍是 AppTheme，经典布局 1:1 镜像）
+- **[MUST NOT] 在 scoped CSS 里给 `.app-header-shim` 写死横向 padding**：那会与 inline 的一份打架，且消费方覆盖只改得动一半——横向内呼吸的唯一出处是 `headerStyle`
 
 ## 关联
 

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

@@ -47,6 +47,24 @@
 - `show=false` 整栏不渲染（含折叠把手）——「收起但保留把手」场景走折叠态而非 `show=false`。
 - **完整能力演示**（DemoCustomShell 槽转发范式 + NoSidebar 变体）：`apps/reference/src/pages/app-layout/shell/`、`apps/reference/src/pages/app-layout/layout/`
 
+## 面貌（背景 / 圆角 / 无横向内呼吸）
+
+| 项 | 默认 | 覆盖法 |
+| --- | --- | --- |
+| 背景 | `APP_LAYOUT_SIDEBAR_CONFIG.background ?? 主题 bodyColor` | 配 `background` |
+| 圆角 | `var(--dc-core-radius, var(--el-border-radius-base))`（随主题） | `APP_LAYOUT_SIDEBAR_CONFIG.style.borderRadius` |
+| 横向内呼吸 | **无，[MUST NOT] 补** | —— |
+
+- 圆角与背景**同源**（都在 `appStore.sidebarStyle` 这一份 inline style 里），默认值写在
+  `...cfg.style` 展开之前 ⇒ 逃生舱同名键恒赢。
+- 🔴 **为什么不像 header / footer 那样补横向 padding**：侧栏里装的是菜单树，
+  `.el-menu-item` 自带 `padding: 0 var(--el-menu-base-level-padding)`（默认 20px）——
+  外层再让一份就是**双份**，且折叠成图标栏时会把图标挤离中线。
+- 🔴 **圆角要看得见，靠的是内部那层裁切盒**（`.app-sidebar-clip`，`inset: 0` + `overflow: hidden`
+  + `border-radius: inherit`）：根盒 [MUST] 保持 `overflow: visible`（折叠把手悬挂在外缘），
+  故根盒自己裁不了——而 `el-menu` 自带背景色会直接盖住四角。[MUST NOT] 把 clip 层删掉当冗余。
+- 收起态（`showSidebar=false` → 宽收 0）零面积、不留圆角残影。
+
 ## API
 > ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。