0.9.0: 按后端给的 sheet 表建/读工作簿(多 sheet)

配 shrimp-server v0.9.0:export 返回 { sheet 名: 行数组 },这边逐 key 建 sheet;
导入把工作簿里所有 sheet 都发回后端(旧版只读第一张、其余静默丢弃),哪张怎么用
由模块的 import 决定。sheet 名按 Excel 限制截断/替换,否则 book_append_sheet 直接抛。

README.md

@@ -20,7 +20,7 @@ shrimp-admin 是**源码 ship**(.ts + .vue 直接发),不带构建产物,由消
     "type": "module",
     "scripts": { "dev": "vite", "build": "vite build" },
     "dependencies": {
-        "shrimp-admin": "git+http://git.zeromvc.com/wc24/shrimp-admin.git#v0.8.4",
+        "shrimp-admin": "git+http://git.zeromvc.com/wc24/shrimp-admin.git#v0.9.0",
 
         // ⚠️ 不能删 —— 下面 7 个是 shrimp-admin 的 peerDependencies,
         // 必须由消费侧显式装进自己的 dependencies,不能指望 npm 提升碰巧能 import 到
@@ -54,6 +54,11 @@ export default defineConfig({
     optimizeDeps: {
         // ⚠️ 不能删 —— 删了整页白屏,报 resolveVue: components/layout.vue not found in sources
         exclude: ['shrimp-admin'],
+        // ⚠️ 也不能删 —— 上面这行让 vite 的依赖扫描停在本包门口,看不见本包 import 的
+        // element-plus / xlsx。消费侧 src/ 下如果没有自己的业务 .vue 顺手 import 到它们,
+        // 它们就一次都没被预打包,内部的 CJS 依赖(dayjs)原样送进浏览器 → 整页白屏,
+        // 控制台只有一行 does not provide an export named 'default'。列的就是下面那份 peer 清单
+        include: ['vue', 'vue-router', 'vue-i18n', 'axios', 'element-plus', '@element-plus/icons-vue', 'xlsx'],
     },
     resolve: {
         // ⚠️ 不能删 —— 删了 element-plus 与 shrimp-admin 各带一份 vue/dayjs,互操作错位
@@ -130,8 +135,10 @@ import { ShrimpTable } from 'shrimp-admin'
 | `resolveVue: components/layout.vue not found in sources`,整页白屏 | shrimp-admin 被 vite 预打包了 | vite.config `optimizeDeps.exclude: ['shrimp-admin']` |
 | `Failed to resolve import "xlsx"`,vite 起不来 | 少装 peerDependency `xlsx` | `npm i xlsx`,模板第 1 节 |
 | 页面出来了但没样式,**图标巨大** | 没引 element-plus 基础样式 | main.ts 加两行 css,模板第 3 节 |
+| 编辑器报 `找不到 'shrimp-admin/style' 的副作用导入的模块或类型声明` | 本包低于 v0.8.6:`./style` 导出没有 types 条件,开了 `noUncheckedSideEffectImports` 的项目解不出类型 | 升到 `v0.8.6` |
 | 能登录、菜单也有,但**所有列表都 404** | 服务端装的是 Express 4 | 服务端升到 `express@^5` |
-| `does not provide an export named 'default'`(dayjs / element-plus) | 依赖被装了两份 | vite.config `resolve.dedupe`,模板第 2 节 |
+| `does not provide an export named 'default'`(dayjs),整页白屏 | element-plus 从没被预打包过,它的 CJS 依赖被原样送进浏览器 | vite.config `optimizeDeps.include`,模板第 2 节 |
+| `does not provide an export named 'default'`(其他包) | 依赖被装了两份 | vite.config `resolve.dedupe`,模板第 2 节 |
 
 ## 验收: 必须在浏览器里打开页面
 
@@ -149,6 +156,20 @@ Vite dev 默认用 **esbuild** 把 node_modules 里的裸导入预打包成 `nod
 - 框架的内置组件表靠 `import.meta.glob('./{components,module}/**/*.vue')` 收集,这是 **Vite 编译期宏**,esbuild 不认识,会原样抄进产物;等它在 `.vite/deps/` 目录下才被展开时,那个目录里一个 `.vue` 都没有 → 内置表变成空对象 `{}` → 内置兜底全部落空。
 - 预打包等于复制出第二份模块实例,`vueAdmin` 单例会分裂成两个,消费侧拿到的和框架内部用的不是同一个。
 
+## `optimizeDeps.include: [...]`
+
+上面那条 `exclude` 的代价:vite 的依赖扫描从 `index.html` 顺着消费侧的源码走,走到 `shrimp-admin` 就停了 —— 被 exclude 的包不进扫描,所以**框架 import 了什么,vite 一无所知**。
+
+以前这不出事:消费侧总要写几个业务模块 `.vue`,里面顺手 `import { ElMessage } from 'element-plus'`,扫描器照样摸得到。而从 v0.8.4 起模块壳可以一个都不写(见「业务模块」一节),于是完全可能出现**消费侧 `src/` 里没有任何一处 import element-plus** —— 它整包从未被预打包,所有 `element-plus/es/**` 被原样送给浏览器,其中的 `import dayjs from 'dayjs'` 指向一个 CJS 文件,当场炸:
+
+    The requested module '/node_modules/dayjs/dayjs.min.js' does not provide an export named 'default'
+
+整页白屏,控制台就这一行,`vite build`(rollup)一路绿灯。
+
+**不要顺着报错一个个补 `dayjs`、`dayjs/plugin/customParseFormat`……** 那是在追症状,换个 element-plus 版本要重列一遍。**也不要用 `optimizeDeps.entries` 指向 `node_modules/shrimp-admin/src/**`** —— 扫描器不认 node_modules 里的入口 glob,实测加了等于没加(`.vite/deps/_metadata.json` 里仍然只有 `vue`)。
+
+正确的做法是把本包用到的运行时依赖点名列出,那份清单就是下面 peerDependencies 本身 —— 消费侧本来就得装它们,这里只是再说一句「请预打包」。
+
 ## element-plus 的两行 css
 
 `shrimp-admin/style` 只包含框架自己的覆盖样式与暗色变量(`fix.scss` / `dark.scss` 等),**不含** element-plus 本体的样式表。element-plus 是 peerDependency、由消费侧安装,它的基础样式自然也该由消费侧引 —— 框架替你引会锁死版本、也挡住你换主题。顺序不能反:覆盖必须在基础之后。
@@ -157,6 +178,8 @@ Vite dev 默认用 **esbuild** 把 node_modules 里的裸导入预打包成 `nod
 
 `ShrimpTable` 的导入/导出按钮是**静态** `import * as XLSX from 'xlsx'`,不是按需加载 —— 就算你的后台从不点那两个按钮,模块解析也绕不过去。它是 peerDependency 而不是 dependency,理由和 element-plus 一样:版本该由消费侧定。
 
+工作簿的形状由**后端**决定(v0.9.0 起):`export` 返回 `{ sheet 名: 行数组 }`,前端按 key 逐张建 sheet;导入则把工作簿里**所有** sheet 原样发回后端(旧版只发第一张),哪张怎么用由模块的 `import` 决定。前端在这条链上只做两件脏活:对象/数组列 `JSON.stringify`,以及把 sheet 名按 Excel 限制(≤31 字符、不含 `[]:*?/\`)截断替换。
+
 # 唯一约定: `sources` 路径后缀覆盖
 
 消费侧把所有要交给框架的 .vue 通过单个 `sources` 入口注入(`import.meta.glob` 必须由消费侧自己调用,vite 静态扫描相对调用文件)。框架按**文件路径后缀**匹配,同后缀消费侧优先,内置兜底。

package.json

@@ -1,6 +1,6 @@
 {
     "name": "shrimp-admin",
-    "version": "0.8.4",
+    "version": "0.9.0",
     "private": true,
     "description": "Shrimp 框架前端 — 消费 ShrimpServer + ShrimpTable 契约的经典 Vue3 + Element Plus 实现",
     "main": "src/index.ts",
@@ -10,7 +10,10 @@
             "types": "./src/index.ts",
             "default": "./src/index.ts"
         },
-        "./style": "./src/style/style.scss",
+        "./style": {
+            "types": "./src/style/style.d.ts",
+            "default": "./src/style/style.scss"
+        },
         "./package.json": "./package.json"
     },
     "files": [

src/IShrimpType.ts

@@ -125,11 +125,20 @@ export interface ITableProto<T> {
     delete(id: string): Promise<boolean>
 }
 
+/**
+ * 导入导出的负载形态：sheet 名 -> 行数组，对应 xlsx 的一个工作簿。
+ *
+ * 普通模块就是一个 sheet（默认以 moduleKey 命名）；模块重写 export/import
+ * 就能自定义多 sheet（如「商品/商店/销售规则」各一张），前端按 key 建/读 sheet。
+ * 兼容：老版本的裸数组负载等价于「单 sheet」，两端都会归一。
+ */
+export type IShrimpSheets = Record<string, any[]>
+
 /** 完整 Table 协议（后端可用，含管理操作） */
 export interface ITableCrudProto<T> extends ITableProto<T> {
     clear(query?: IPageQuery & any): Promise<boolean>
-    export(query?: IPageQuery & any): Promise<T[]>
-    import(data?: T[], ownerId?: string): Promise<void>
+    export(query?: IPageQuery & any): Promise<IShrimpSheets>
+    import(data?: IShrimpSheets | T[], ownerId?: string): Promise<void>
 }
 
 // ============== 预制数据模型 ==============

src/components/ShrimpTable.vue

@@ -449,6 +449,27 @@ function buildFilter(): Record<string, any> | undefined {
     return Object.keys(filter).length > 0 ? filter : undefined
 }
 
+/** 归一成 sheet 表：老后端(或手写 json)发裸数组时,当作以 moduleKey 命名的单张表 */
+function toSheets(data: any): Record<string, any[]> {
+    if (Array.isArray(data)) return { [props.moduleKey]: data }
+    return data || {}
+}
+
+/** xlsx 单元格放不下对象/数组(会变 [object Object]),通用地 JSON 序列化(覆盖 tab 等结构化字段)。
+ *  import 时这些字符串由后端各类型 reqFilter 还原。 */
+function stringifyRow(row: Record<string, any>): Record<string, any> {
+    const out: Record<string, any> = {}
+    for (const [k, v] of Object.entries(row)) {
+        out[k] = (v !== null && typeof v === 'object') ? JSON.stringify(v) : v
+    }
+    return out
+}
+
+/** Excel 的硬限制:sheet 名不得超 31 字符、不得含 []:*?/\ ,越界 book_append_sheet 直接抛 */
+function sheetName(key: string): string {
+    return key.replace(/[[\]:*?/\\]/g, '_').slice(0, 31) || 'Sheet1'
+}
+
 async function handleExport() {
     emit('export')
     try {
@@ -461,19 +482,12 @@ async function handleExport() {
             query.sortOrder = currentSortOrder.value
         }
         if (ownerId.value) query.ownerId = ownerId.value
-        const list = await api.export(query)
-        // 后端只发原始对象；xlsx 单元格放不下对象/数组(会变 [object Object])，这里通用地 JSON 序列化
-        // (覆盖 tab 等结构化字段)。import 时这些字符串由后端各类型 reqFilter 还原。
-        const rows = list.map((row: Record<string, any>) => {
-            const out: Record<string, any> = {}
-            for (const [k, v] of Object.entries(row)) {
-                out[k] = (v !== null && typeof v === 'object') ? JSON.stringify(v) : v
-            }
-            return out
-        })
-        const ws = XLSX.utils.json_to_sheet(rows)
+        const sheets = toSheets(await api.export(query))
         const wb = XLSX.utils.book_new()
-        XLSX.utils.book_append_sheet(wb, ws, props.moduleKey)
+        for (const [name, rows] of Object.entries(sheets)) {
+            const ws = XLSX.utils.json_to_sheet((rows || []).map(stringifyRow))
+            XLSX.utils.book_append_sheet(wb, ws, sheetName(name))
+        }
         XLSX.writeFile(wb, `${props.moduleKey}_export_${Date.now()}.xlsx`)
         ElMessage.success(t('base.success'))
     } catch (e: any) {
@@ -495,17 +509,19 @@ async function handleFileChange(e: Event) {
     const file = target.files?.[0]
     if (!file) return
     try {
-        let data: any[]
+        let sheets: Record<string, any[]>
         if (file.name.endsWith('.json')) {
-            const text = await file.text()
-            data = JSON.parse(text)
+            sheets = toSheets(JSON.parse(await file.text()))
         } else {
+            // 整本工作簿原样交给后端:哪张 sheet 怎么用,由模块的 import 决定(默认取同名/第一张)
             const buf = await file.arrayBuffer()
             const wb = XLSX.read(buf, { type: 'array' })
-            const ws = wb.Sheets[wb.SheetNames[0]]
-            data = XLSX.utils.sheet_to_json(ws)
+            sheets = {}
+            for (const name of wb.SheetNames) {
+                sheets[name] = XLSX.utils.sheet_to_json(wb.Sheets[name])
             }
-        await api.import(data, ownerId.value)
+        }
+        await api.import(sheets, ownerId.value)
         ElMessage.success(t('base.success'))
         await refresh()
     } catch (e: any) {

src/index.ts

@@ -20,6 +20,7 @@ export type {
     IMenuItem,
     ITableProto,
     ITableCrudProto,
+    IShrimpSheets,
     IUser,
     IRole,
     IOperationLog,

src/style/style.d.ts

@@ -0,0 +1,5 @@
+// `shrimp-admin/style` 的类型出口。样式表本身没有类型可言，这里要回答的只是
+// 「这个说明符解析得到东西」——消费侧开了 noUncheckedSideEffectImports 时，
+// import 'shrimp-admin/style' 落到 .scss 上会报 TS2307,因为 TS 不认识 .scss。
+// package.json 的 exports 里用 types 条件指向本文件,bundler 照旧拿 default 那条 .scss。
+export {}