feat: 新增 plugin/ 插件化形态(funjia.print-tag)+ 可选 SN 条码/二维码
把本工程的标签排版能力改造成 FunjiaUI 远端插件,放进 plugin/ 子目录, 与原独立 Web 版并存(两者功能一致,模板/版面/打印行为逐项对齐)。 - 入口从 createApp().mount() 改为 activate(ctx) + ctx.addRoute,注册 1 菜单 / 1 路由 / 2 命令 - 11 个模板的渲染收敛成 SpecTag,差异集中到 templates/registry.ts(字段/选项/默认值原样保留) - 店铺名 / 电话从写死改为可配置,记忆在插件私有存储 - 内置二维码图片改为打包 data URL —— 远端插件没有自己的 public/ - 去掉 @headlessui/vue(换原生 select)与 Tailwind,样式类名统一 pt- 前缀避免污染宿主 - 可选接入宿主 api::sn-code:按 SN 生成真 Code 128 条码与可扫二维码; 关闭时(默认)完全保持原静态二维码行为。领码优先贴到已排版的格子,不够才新建 - 新增 commands: print-tag:issue-sn / print-tag:render-svg(后者纯本地出图,供其它插件复用) - code128.ts 实现真 Code 128 Set B(含校验位);二维码走 qrcode-generator(真 QR) - 自带本地预览器(preview/mock-api.ts 补了 /api/sn-codes mock)与 deploy / verify 脚本 - verify.mjs 修掉一处误报:源码边界判据改为「解析后是否逃出工程根」, 而不是「说明符是否以 .. 开头」(后者会把 src/components/X.vue → ../codes 误判为越界) 已发布到插件仓库:funjia.print-tag@1.0.0
This commit is contained in:
@@ -0,0 +1,146 @@
|
||||
# 标签打印插件(`funjia.print-tag`)
|
||||
|
||||
本目录是 `print-tag-system` 的**插件化形态**:同一套标签排版 / 打印能力,
|
||||
改造成可被 FunjiaUI 宿主装载的远端插件,并加了**可选的 SN 码 → 条码 / 二维码**能力。
|
||||
|
||||
- 插件 id:`funjia.print-tag`
|
||||
- 产物:`dist/PrintTagBundle.iife.js` + `dist/PrintTagBundle.css`(IIFE,自注册)
|
||||
- 上架位置:`funjia-plugin-repository` 插件仓库的 `repository/plugins/funjia.print-tag/1.0.0/`
|
||||
|
||||
仓库根目录那份 `src/` 是**原独立 Web 版**,两者并存、互不影响。
|
||||
|
||||
---
|
||||
|
||||
## 一、和原 Web 版的关系
|
||||
|
||||
| 能力 | 原 Web 版 | 本插件 |
|
||||
| --- | --- | --- |
|
||||
| 启动方式 | `createApp(App).mount('#app')`,自己起 Vite 服务 | 宿主装载 → `activate(ctx)` → `ctx.addRoute` 挂页面 |
|
||||
| 路由 / 菜单 | 无(单页) | 注册到宿主侧边栏(设备管理 → 标签打印) |
|
||||
| 内置模板 | 11 个 `.vue` 文件 | 11 个模板,渲染收敛成 `SpecTag`,差异集中在 `templates/registry.ts` |
|
||||
| 二维码图片 | 站点根目录 `/qrcode.png` | 打包成 data URL 内置(远端插件没有自己的 `public/`) |
|
||||
| 下拉选择 | `@headlessui/vue` Listbox | 原生 `<select>`(少 30KB,且浮层不会进打印流) |
|
||||
| 样式 | Tailwind 4 + 全局 CSS | 纯 CSS,**类名一律 `pt-` 前缀**(插件 CSS 是注入宿主全局的) |
|
||||
| 店铺名 / 电话 | 写死在每个模板里 | 面板可改,记忆到插件私有存储 |
|
||||
| SN 码 / 条码 / 二维码 | 无 | **可选**(见第三节) |
|
||||
|
||||
标签尺寸、44 格版面、模板字段与选项、打印边距、双击隐藏等行为**逐项保持原样**。
|
||||
|
||||
---
|
||||
|
||||
## 二、开发与交付
|
||||
|
||||
```bash
|
||||
cd plugin
|
||||
npm install
|
||||
|
||||
npm run dev # 本地预览(http://127.0.0.1:5310),改 src/** 立刻生效
|
||||
npm run build # 产物落到 dist/
|
||||
npm run typecheck # tsc --noEmit
|
||||
npm run verify # 自检:清单自洽 / 源码边界 / 产物形态 / 预览资产
|
||||
npm run preview # 产物模式预览(http://127.0.0.1:5310/artifact.html),验 external 与 CSS 抽取
|
||||
```
|
||||
|
||||
交付到插件仓库(构建 → 归档 → 重写索引,一步到位):
|
||||
|
||||
```bash
|
||||
node scripts/deploy.mjs --repo ../plugin-repo --no-build
|
||||
```
|
||||
|
||||
> ⚠️ **发布脚本要求 `plugins/dist/` 里齐备 `repo.config.json` 中所有插件的产物**
|
||||
> (那是它的暂存区,已被 gitignore)。仓库里其它插件的产物在 `repository/plugins/`
|
||||
> 下已归档,回填即可:
|
||||
>
|
||||
> ```bash
|
||||
> cd ../plugin-repo
|
||||
> for d in repository/plugins/*/*/; do for f in "$d"*; do
|
||||
> b=$(basename "$f"); [ "$b" = plugin.json ] || cp -n "$f" plugins/dist/
|
||||
> done; done
|
||||
> node scripts/publish-repo.mjs
|
||||
> ```
|
||||
|
||||
---
|
||||
|
||||
## 三、SN 码 / 条码 / 二维码(可选)
|
||||
|
||||
面板「② SN 码 · 条码 / 二维码(可选)」有一个总开关,**默认关闭**。
|
||||
|
||||
| 开关 | 行为 |
|
||||
| --- | --- |
|
||||
| 关闭 | 完全保持原样:左侧用内置静态二维码图,不调用任何接口 |
|
||||
| 开启 | 走宿主后端 `api::sn-code`,按 SN 现场生成**真 Code 128 条码**与**可扫二维码** |
|
||||
|
||||
开启后:
|
||||
|
||||
- **批量领码并填充** —— 优先贴到「已排好版但还没 SN」的格子上,不够才往空格新建标签
|
||||
(顺序很重要:先排版再贴码才是真实用法,否则点一下会多出一堆空壳标签);
|
||||
- 单格编辑面板里可手工填 SN,或「领 1 条」单独取码;
|
||||
- **校验选中格 SN** —— 格式 + 校验位 + 台账存在性,都由后端判定。
|
||||
|
||||
接口(与 `funjia.sn-tools` 插件共用同一套后端):
|
||||
|
||||
```
|
||||
GET /api/sn-codes/meta 业务类型 / 默认前缀 / 码长
|
||||
POST /api/sn-codes/generate 单条发放
|
||||
POST /api/sn-codes/batch 批量发放 → { items: [...] }
|
||||
POST /api/sn-codes/verify 校验 → { valid, reason, exists, record }
|
||||
```
|
||||
|
||||
两个命令也注册给了别的插件:
|
||||
|
||||
- `print-tag:issue-sn` —— 按业务类型领 N 条 SN;
|
||||
- `print-tag:render-svg` —— **纯本地**把文本渲染成条码 / 二维码 SVG(不调接口)。
|
||||
别的插件想在自己的标签上画码,调这一条即可,不必各自引一份条码库、
|
||||
也不必各自踩一遍 Code 128 校验位的坑。
|
||||
|
||||
### 物理尺寸:必须知道的三个数
|
||||
|
||||
标签格是 `48.5mm × 25.4mm`。格子放不下两个「全尺寸」图形,所以:
|
||||
|
||||
| 项 | 值 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| 二维码模块 | 约 0.54mm/模块 | 16 位 SN 在 EC-M 下是 25×25 模块,18mm 出图 → 203dpi 下约 4 个点/模块,很稳 |
|
||||
| 二维码(开条码后) | 约 0.34mm/模块 | 条码条吃掉 6.6mm,二维码被挤到约 11mm |
|
||||
| 条码模块 | 约 0.199mm(7.8 mil) | 46mm 宽塞 211 个模块(16 位 SN)。**这已接近 Code 128 下限 7.5 mil**,203dpi 下每模块不到 2 个点 |
|
||||
|
||||
界面上会把这两个数**实时算出来**并给出建议(换 300dpi / 关掉条码)。
|
||||
|
||||
> 一句话:**二维码是可靠路径,条码在这个格子上是「勉强够用」**。
|
||||
> 需要高可靠条码时应换更大的标签纸,或让标签软件(BarTender 等)去出图。
|
||||
|
||||
---
|
||||
|
||||
## 四、目录结构
|
||||
|
||||
```
|
||||
plugin/
|
||||
├── plugin.config.json ★ 元数据唯一真源(id / 版本 / 产物名 / 扩展点声明)
|
||||
├── postcss.config.js 截断 PostCSS 查找链(否则会加载仓库根目录的 Tailwind 配置)
|
||||
├── src/
|
||||
│ ├── index.ts ★ 插件入口:生命周期 + 注册菜单/路由/2 个命令
|
||||
│ ├── codes.ts Code 128 与真 QR 的 SVG 生成(纯函数,单位 mm)
|
||||
│ ├── sdk.ts / runtime.ts 宿主能力契约与 ctx 持有者
|
||||
│ ├── components/ LabelCell / TagShell / DynamicForm / Input / Select
|
||||
│ ├── templates/ SpecTag / ErrorTag / CustomTag + registry.ts(模板注册表)
|
||||
│ ├── pages/PrintTagPage.vue ★ 主页面:44 格版面 + 面板 + SN 集成
|
||||
│ └── assets/default-qr.ts 内置默认二维码(data URL)
|
||||
├── scripts/ deploy / verify
|
||||
└── preview/ 本地预览器(迷你宿主 + 调试面板 + mock 后端)
|
||||
```
|
||||
|
||||
`preview/mock-api.ts` 里**额外实现了 `/api/sn-codes/*`**(模板原本只有通用 CRUD)。
|
||||
少了它,本地一打开 SN 开关就是 404,只能走「构建 → 发布 → 装进宿主 → 点一遍」,
|
||||
一圈几分钟。注意:mock 的号段与校验位算法是本地自定的,**只验链路、别对号段**。
|
||||
|
||||
---
|
||||
|
||||
## 五、已知边界
|
||||
|
||||
- **`--no-build` 之外的重建**:`dist/` 与 `node_modules/` 已被仓库根 `.gitignore` 忽略,不会进版本库。
|
||||
- **print 样式是临时注入的**:打印时才插 `<style media="print">`,`afterprint` 时移除。
|
||||
常驻的话,用户在宿主里打印**任何别的页面**都会得到一张白纸 —— 插件 CSS 分不清
|
||||
「现在打印的是不是我的页面」。
|
||||
- **`postcss.config.js` 不能删**:本工程住在有 Tailwind 的仓库里,Vite 的 PostCSS
|
||||
配置查找会往上走,加载到那份 Tailwind 配置后构建直接失败。
|
||||
- **预览器做不到的三件事**(没有真 FunjiaUI、`ctx.plugin.repository` 为空、无路由守卫)
|
||||
见 `funjia-plugin-starter` 的 README §3.3。
|
||||
Reference in New Issue
Block a user