sky-ui-kit 0.1.0 → 0.1.2

package/docs/GLOBAL-ADAPTATION.md

@@ -0,0 +1,38 @@
+# 原项目全局适配与组件库融合
+
+## 已读取的实际链路
+
+- main.ts：createFitScale，target #app，设计尺寸 1920×912，scaleMode auto；注册 Pinia / router，注册 SVG sprite。
+- App.vue：useFitScale → watch → document.documentElement 的 --cp-vfit-scale；主题 store 的 deep watch 调用 applyCssVars，卸载释放 watch 并移除 scale。根 ElConfigProvider 保留中文 locale。
+- styles/vfit-vars.scss：--cp-size-1…360 与 --cp-font-1…40 按缩放值计算；部分图表高度使用 clamp 与视口约束。
+- styles/theme.css / stores/theme.ts：六色与派生主题、--header-height / --sidebar-width / --rightpanel-width / --layout-gutter，以及 Element Plus 变量；主题 store 保留为唯一控制者。
+- styles/base.css / MainLayout：html/body/#app 的高度链、box-sizing、字体继承、workspace 扣除 header 高度。
+- MainLayoutMap / TemplateLayout：地图与 pointer-events:none 覆盖层分离，交互区域恢复事件；右栏开关影响浮层位置，ResizeObserver 测量时间轴和图例并在卸载释放。map/index.vue 挂载后 nextTick 调用 map.resize。
+
+## 融合分工
+
+| 内容 | 原项目维护 | 组件库消费 |
+|---|---|---|
+| 视口与设计尺寸 | VFit 单次注册，1920×912 auto | 不注册 VFit，不管理窗口缩放 |
+| 全局缩放 | App.vue 写根 --cp-vfit-scale | 局部尺寸 token 根据该变量计算，缺失按 1 |
+| 主题 | 原主题 store、六色、暗色、字体与 localStorage | 读取变量并提供缺失默认值；不迁入预览站 store |
+| 页面结构 | RouterView、权限、ui store、布局开关 | Ui 容器及项目展示组件组合 |
+| 地图与图表 | 地图实例、resize、图层订阅、图表 resize、释放 | 工具、菜单、时间轴事件由页面接回原逻辑 |
+| 浮层 | 根主题变量与现有弹窗配置 | 默认主题范围；显式 body 浮层另核对主题和缩放 |
+
+默认 style.css 的 scoped-vfit.scss 不把 --cp-vfit-scale 重置为 1；其低优先级默认 token 在 .userssite-theme 内计算。原项目根节点已有的六色与布局变量由 --userssite-* 桥接读取。库没有全局 html/body reset，保留原 base.css。ElScrollbar 直接从 element-plus 使用；它的主题来自应用已有作用域，不额外包装。
+
+## 接入步骤
+
+1. 保留原 main.ts 的 VFit、Pinia、路由、SVG、字体与主题导入，公共库 CSS 追加一次；默认不引入 global.css。原项目已有 VFit，不重新安装、注册或另设设计尺寸。
+2. 保留 App.vue 的 scale 和 theme 两个 watch；不要在单个页面重复写根变量或引入组件库预览 store。复制代码见 AI-GUIDE.md 的全局适配示例，布局页面也提供相同代码。
+3. 页面容器用 --header-height / --sidebar-width / --rightpanel-width / --layout-gutter，内容 min-width/min-height:0。系统页内部滚动用 ElScrollbar；地图页面保持地图与覆盖层分离，避免整层拦截鼠标。
+4. 组件已通过 --cp-font-* / --cp-size-* 消费比例时，不再添加第二套 transform:scale / zoom。原项目 VFit 本身的行为保留；这里只禁止迁移时额外引入新的缩放层。
+5. 右栏、左栏或底部过程区改变地图宿主尺寸时，由应用在 DOM 更新/过渡完成后调用地图 resize；ECharts 在容器尺寸变化时调用实例 resize。原 map/index.vue 的挂载 resize 不等于已覆盖所有后续布局变化，不把这项能力宣称为库自动处理。
+6. body 上的 dialog / drawer / select / image preview 不能读取局部容器独有变量。原项目根 scale/theme 可被它们继承；局部主题需显式传 class/style 或保持浮层在容器内，并检查 overflow 裁剪。
+
+## 窄屏与验证
+
+全局比例适配解决设计尺寸缩放，内容重排仍由布局负责；必要时收起侧栏、把业务面板改为抽屉、允许表格水平滚动。演示布局的紧凑宽度为预览用途，不等于原生产布局参数；真实页面优先使用原布局变量。地图色带、业务阈值和图片点位不随六色替换。
+
+在 1920×912、较小桌面和窄屏下核对：根 scale 值、控件字体和高度、左右面板避让、时间轴/图例重叠、地图/图表 resize、弹窗与图片预览、键盘焦点和滚动。明暗主题分别验证，关闭页面确认 watch / ResizeObserver / 地图图表监听释放。当前只读审查与文档示例不替代原项目运行回归；本次未修改原项目。

package/docs/INTEGRATION.md

@@ -4,8 +4,22 @@
 
 # 发布与反向接入
 
+## 图标替换
+
+原 components/global/SvgIcon.vue 可替换为从 sky-ui-kit 导入 SvgIcon，保留 name / size / title / decorative。库内置 274 个项目 SVG，自动按需注册到 sky-icon- 命名空间；不依赖业务项目 Vite 插件。暂时保留旧 sprite 时传 prefix="icon-"，资源仍由原 virtual:svg-icons-register 提供。完成所有旧引用检查后才移除旧全局组件和插件，地图 PNG / Logo 的注册不变。子目录名称改为目录前缀以避免重名，按 projectIcons.source 与 name 对照迁移。Element Plus 图标仍从 @element-plus/icons-vue 导入，用 UiIcon 包裹。图标操作事件、路由和权限继续由业务方绑定。
+
 ## 当前交付范围
 
+全局适配融合见 [GLOBAL-ADAPTATION.md](GLOBAL-ADAPTATION.md)：保留原 VFit 注册、根缩放/主题变量桥接和页面高度链，库只读取变量。地图/图表 resize、浮层主题与窄屏重排仍由业务方接入，完整共享代码在布局页和 AI-GUIDE.md。
+
+最新只读使用清单见 [COMPONENT-USAGE.md](COMPONENT-USAGE.md)，逐模块适配见 [ADAPTATION.md](ADAPTATION.md)。原项目接入页面同步展示清单和替换边界。图标 Vite 完整配置和页面调用见 AI-GUIDE.md 的图标接入示例；原项目已经配置插件，保留旧 sprite 时不重复配置。
+
+预览站左侧按 Element Plus 全量目录分类，并独立保留项目选择、时间、菜单和地图组件。标准组件已提供出口与 API 索引，但不能据此认为所有独立示例或业务回归均已完成；替换时仍应核对公开出口、API 与下文路径映射。预览站 SiteNavigation 无需迁入业务项目。
+
+## 全量标准组件替换
+
+使用新增组件前确认实际安装的 Element Plus 至少为 2.14.7；原业务项目目前声明 ^2.14.2，该范围可包含 2.14.7，先检查 lockfile 与安装版本，再决定是否安排升级和回归，本次未修改原项目。标准组件通常把 El 名称换为 Ui 名称并从 sky-ui-kit 导入，属性、事件、插槽和实例方法沿用对应安装版本 API。结构子组件搭配对应 Ui 父组件，特别是轮播项、引导步骤、选项、表格列、标签页面板。服务使用 UiMessage / UiMessageBox / UiNotification / UiLoading.service；指令使用 vUiLoading / vUiInfiniteScroll / vUiPopover。组件库不承接地图请求、上传接口、路由或权限逻辑。
+
 本包是现有项目公共主题及组件的独立快照，不是原平台业务 SDK。全页面盘点见 PAGE-INVENTORY.md；全部原组件依赖见 COMPONENT-INVENTORY.md。扫描是完整源码静态读取，业务页面尚未逐页运行验证。尚未发布，不应现在把主项目全部替换。
 
 ## 默认视觉
@@ -51,7 +65,7 @@ Header / SideMenu / MainLayout 的路由、权限、用户和布局状态；Laye
 
 ## 按步骤反向接入
 
-1. 样式确认后确定 npm 包名 / scope、版本和许可证，删除 private，执行 typecheck、build、pack --dry-run 后发布。预览站用暂定包名，发布后更新文档示例。
+1. 包名已确定为 sky-ui-kit；先完成模块与样式确认并记录版本。仅明确安排打包/发布时执行构建与发布检查；当前源码未发布，npm latest 不会包含工作区的新修改。
 2. 主项目安装精确版本，保留 Vue / Pinia / Element Plus / motion-v / icons 依赖。先在独立分支接入一个非核心页面验证，不修改所有页面。
 3. main.ts 保持 Element Plus CSS 在前，包 style.css 在后。默认隔离；只有主动整站换肤时才额外引入 global.css。
 4. 选择原 theme store 继续作为单一主题控制者（推荐首轮）：先只迁组件和 CSS；保持原 `app-theme` 配置、RightPanel 和 App.vue 的 watch。不在此阶段引入包 store。
@@ -69,3 +83,7 @@ Header / SideMenu / MainLayout 的路由、权限、用户和布局状态；Laye
 ## 验收门槛
 
 包：typecheck / build / npm pack 内容、公开导出及依赖清单。应用：typecheck / build、每个迁移页面运行核对、实际 API 和地图事件接线、明暗截图与业务回归。当前自动扫描与预览站构建不能替代实际业务验收。
+
+## TemplateLayout 地图业务布局
+
+原 TemplateLayout 保留在业务应用中，组件库布局页提供独立区域说明和组合轮廓示例。替换其子组件时保留 ui store 右栏状态、地图工具事件、图层与区域逻辑、默认图例和主题弹窗；保留图例/时间轴 ResizeObserver 测量及卸载释放。不能直接从 sky-ui-kit 导入 TemplateLayout。