labull-framework 0.1.36 → 1.0.1

package/README.md

@@ -102,6 +102,41 @@ await magicBlock.setTabTitle('订单 SO-42', 'pi pi-file')   // 给所属那条
 🔴 **它故意不 re-export `magic-block`**：`magic-block` 与 `auth` 都导出 `API_BASE`（以及 `setApiBase`），
 两路 `export *` 撞同一个名字是打包器层面的歧义。要块就从 `labull-framework/magic-block` 拿。
 
+## 一个块包长什么样（1.0.0）
+
+后端存的是**一个块 = 一个 uuid + 一整个文件包**，块包在磁盘上就是这个形状：
+
+```
+workspace/<可读名>-<块 uuid>/
+├─ index.open.html        入口（必备件）
+├─ magic-block.open.yaml  清单（必备件）：id / module / name / brief 四个键**必填**，requires 可选
+├─ README.open.md         业务功能说明（Markdown）——管理台里「详情」那一栏写的就是它
+├─ requires.open.yaml     依赖声明的**草稿**（导出铺下来的；改完读回**只合并**清单的 requires）
+├─ 任意 js / css
+├─ excluded/_*            你自己的地盘（测试 / 草稿）：照样进库，执行时忽略
+└─ backend_open.py        块自己的后端（可选；它从不离开服务端）
+```
+
+- 🔴 **`detail` 不在清单里**：那一段正文的家是 `README.open.md`。老块的清单里若还留着
+  `detail: |`，读回时判据**只提示、不硬错**，正文**自动搬进** `README.open.md`
+  （内容一个字都不丢）—— 这是**有意的迁移**，不是还在用的键。
+- 🔴 **依赖声明写在清单的 `requires` 里**（可选，里面再分 `models` / `surface` / `packages` /
+  `settings` / `config` / `routes` / `opaque` 七个可选键）：声明**不授予任何能力**，
+  它只是让平台拿现实去核对；开关 `LABULL_REQUIRES` **默认 `error`**（1.0.1 起：用了却没声明、
+  或声明的东西不存在 ⇒ 拦住保存），`warn`（只提示不拦）与 `off`（整段不跑）要**显式**写。
+- 🔴 **怎么改、怎么存**：导出到你自己的文件夹 → 用**你自己的编辑器**改 → 回管理台
+  「读回改动」勾选保存（判据的真源始终是 `POST /magic-blocks/import` 那一次校验）。
+- 🔴 **那两份 `.open.` 文件是"作者改的"**（`.open.` 这个后缀就是判据）：读回时**要认**、
+  会跟着包进库；平台铺下来的生成物（`README.lock.md` / `GUIDE.lock.md` / `api.open.d.ts` /
+  `backend.lock.pyi` / `pages.lock.ts` / `labull.css` / `CONTROLS.lock.html` …）才在
+  "读回时静默跳过"那份名单里。浏览器扫目录时用的是后端下发的 `rules.textExt` / `rules.platformFiles`
+  （`localfs.ts` 一条判据都不自己抄），而 `.md` 与 `.yaml` 都在能读的扩展名里 ——
+  所以这两份**既不会被静默跳过、也不会因为"不是文本"被丢掉**。
+  ⚠️ 唯一会动到它们的是**开发目录顶层**那份名单（`rules.rootSkipFiles`，含 `readme.md`）——
+  那是"这一层直接放着的说明文件"，块文件夹**里面**一个都不跳过。
+- 清单与块包结构的**权威口径在仓库根 [`README.md`](../../README.md)** 的「magic block 怎么用」那一节，
+  判据本身只有一处：`labull-framework/magic-block` 里的 `manifest.ts`（与后端逐字对拍）。
+
 ## 两份东西要知道
 
 - 🔴 **前端不做授权**：`isStaff` / `groups` / `permissions` 只是界面显隐，判据全在后端。
@@ -111,8 +146,13 @@ await magicBlock.setTabTitle('订单 SO-42', 'pi pi-file')   // 给所属那条
 
 ## 样式说明
 
-`dist/style.css` 是**完整层**（≈478 KB，gzip ≈91 KB）：token + PrimeVue 主题层 + `.labull-*`
+`dist/style.css` 是**完整层**（**半兆这个量级**：约 0.5 MB、gzip 约 0.1 MB —— 数字随版本变，
+以 npm 上那个包里的实际体积为准）：token + PrimeVue 主题层 + `.labull-*`
 结构类 + shell + 组件样式 + 内联 primeicons。
 
-单包方案里**没有**"只要 token、不要那 450 KB 主题层"的入口（原来 `@labull/theme` 分两层，
+🔴 **别在这里写死一个确切数字**：这一层会随主题同步与控件增补长大，写进"当前行为"里就一定会漂
+（0.1.x 那几版已经从 450 KB 上下长到半兆了）。要一个准数就 `npm pack` 之后看那个 tarball 里的
+`dist/style.css`，或者看 `labull-framework/package.json` 对应那一版。
+
+单包方案里**没有**"只要 token、不要那半兆主题层"的入口（原来 `@labull/theme` 分两层，
 现在只有一份）。真要精简，就在应用里覆盖 `--sp-*` 变量、不引 `style.css` 而自己写需要的部分。