npm - @atomm-developer/generator-material-purchase - Versions diffs - 0.1.0 - Mend

@atomm-developer/generator-material-purchase 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/README.md ADDED Viewed

@@ -0,0 +1,80 @@
+# @atomm-developer/generator-material-purchase
+Atomm Generator 平台的耗材购买弹窗 SDK，框架无关，支持 Vue / React / 原生 JS 项目通过 `<script src>` 或 `import` 引入。
+> **完整接入文档**：[docs/USAGE.md](./docs/USAGE.md)
+## 安装与使用
+### CDN（UMD）
+```html
+<script src="https://static-res.atomm.com/scripts/js/generator-sdk/generator-material-purchase/index.umd.js"></script>
+<script>
+  GeneratorMaterialPurchase.init({
+    generatorId: 'light-sign',
+    accessoryType: 'default',
+  });
+  document.querySelector('#buyBtn').addEventListener('click', () => {
+    GeneratorMaterialPurchase.open();
+  });
+</script>
+```
+### ESM / npm
+```ts
+import GeneratorMaterialPurchase from '@atomm-developer/generator-material-purchase';
+GeneratorMaterialPurchase.init({
+  generatorId: 'light-sign',
+  accessoryType: 'default',
+});
+GeneratorMaterialPurchase.open();
+```
+## API
+```ts
+init(options: {
+  generatorId: string;     // 必填
+  accessoryType: string;   // 必填
+  locale?: 'en' | 'zh';    // 默认 en
+  zIndex?: number;         // 默认 9999
+  apiBaseUrl?: string;     // 默认 https://xcs-api.xtool.com
+  messages?: Record<string, Record<string, string>>;
+  onCheckoutSuccess?(url): void;
+  onClose?(): void;
+  onError?(err): void;
+}): void;
+open(): Promise<void>;
+close(): void;
+destroy(): void;
+```
+`open()` 后弹窗会被插入 `document.body`，固定右侧滑入，宽 320px、满屏高度、带半透明蒙层，点击蒙层或右上角 X 关闭。
+## 鉴权
+每次请求都会带上下面两个 header：
+- `uToken`：从 `document.cookie.utoken` 或 `localStorage.utoken` 读取
+- `lang`：从 `localStorage.LANG_KEY` 读取，默认 `en`
+## 开发
+```bash
+# 在子目录内
+pnpm install
+pnpm dev        # 启动 demo（http://localhost:5174）
+pnpm build      # 构建 dist
+# 或在 generator-sdk 根目录
+pnpm dev:material-purchase
+pnpm build:material-purchase   # 同时把 index.umd.js 复制到 docs/public
+```
+## Shopify 站点
+SDK 内置 8 个 prod 站点（US/CA/EU/UK/FR/DE/JP/AU）的 `shopDomain` 与 Storefront Token。当前站点选择：优先读 `localStorage.xtool_current_shop_name`，否则调用 `/community/v2/web/ip/location` 探测 IP。

package/dist/README.md ADDED Viewed

@@ -0,0 +1,424 @@
+# Generator Material Purchase — 接入指南
+你现在拿到的是一个**框架无关的耗材购买弹窗 SDK**。把它丢到任何前端项目里（Vue / React / Angular / 原生 HTML），通过两个方法即可在页面右侧弹出一个 320px 宽、满屏高度、带蒙层的购物面板，用户可以挑选耗材并跳转 Shopify 完成支付。
+> 这份文档同时面向**人类开发者**和 **AI 编程助手**。如果你想把接入工作交给 AI，请把整份文档一起喂给它（[第 11 章](#11-给-ai-编程助手的接入提示词) 提供了现成提示词模板）。
+---
+## 目录
+1. [包内文件清单](#1-包内文件清单)
+2. [60 秒接入（最快路径）](#2-60-秒接入最快路径)
+3. [对外 API](#3-对外-api)
+4. [配置项详解](#4-配置项详解)
+5. [鉴权](#5-鉴权)
+6. [按框架接入示例](#6-按框架接入示例)
+7. [国际化（i18n）](#7-国际化i18n)
+8. [视觉规格](#8-视觉规格)
+9. [事件回调](#9-事件回调)
+10. [常见问题（FAQ）](#10-常见问题faq)
+11. [给 AI 编程助手的接入提示词](#11-给-ai-编程助手的接入提示词)
+---
+## 1. 包内文件清单
+把整个 `dist/` 目录拷到你项目里（一般放 `public/` 或 `assets/` 下），结构如下：
+```
+dist/
+├── index.es.js     # ESM 入口（给 Vite / Webpack / Rollup）
+├── index.umd.js    # UMD 入口（给浏览器 <script src> 或 Node require）
+├── index.*.map     # sourcemap，调试用，可选保留
+├── index.d.ts      # TypeScript 声明文件
+└── README.md       # 本文档
+```
+挑选规则：
+| 你的项目类型 | 用哪个文件 |
+| --- | --- |
+| 纯 HTML / 静态站 | `index.umd.js` |
+| 现代打包工具（Vite/Webpack）+ 需要 `import` | `index.es.js`（ESM）|
+| 老项目用 `require()` | `index.umd.js` |
+> UMD 加载后会在 `window` 上挂一个全局对象 `GeneratorMaterialPurchase`。ESM 通过 `import` 拿到默认导出。
+---
+## 2. 60 秒接入（最快路径）
+复制下面这段 HTML 改两个参数就能跑：
+```html
+<!doctype html>
+<html>
+  <head>
+    <meta charset="UTF-8" />
+    <title>Purchase Modal Demo</title>
+  </head>
+  <body>
+    <button id="buyBtn">购买耗材</button>
+    <!-- 1. 引入 SDK：路径替换为你自己放置 dist 文件的位置 -->
+    <script src="/path/to/dist/index.umd.js"></script>
+    <script>
+      // 2. 初始化（必须最先调用，且只需调一次）
+      GeneratorMaterialPurchase.init({
+        generatorId: 'light-sign',   // 改成你的 generator code
+        accessoryType: 'default',    // 通常保持 'default'
+      })
+      // 3. 在任意时机调用 open() 打开弹窗
+      document.getElementById('buyBtn').onclick = () => {
+        GeneratorMaterialPurchase.open()
+      }
+    </script>
+  </body>
+</html>
+```
+启动后点按钮 → 弹窗从右侧滑入 → 显示耗材列表 → 用户勾选 → 点 "Buy now" → 自动跳转 Shopify 结算页。
+---
+## 3. 对外 API
+SDK 只暴露 4 个方法：
+```ts
+GeneratorMaterialPurchase.init(options)   // 设置参数（先调用一次）
+GeneratorMaterialPurchase.open()          // 打开弹窗
+GeneratorMaterialPurchase.close()         // 关闭弹窗（也可由用户点蒙层 / X 关闭）
+GeneratorMaterialPurchase.destroy()       // 销毁实例并清空内部缓存
+```
+| 方法 | 时机 | 备注 |
+| --- | --- | --- |
+| `init(options)` | 应用启动 / 组件挂载 | 必须最先调；可重复调以更新配置 |
+| `open()` | 用户点击 "购买" 时 | 返回 `Promise<void>`；初始化失败会触发 `onError` |
+| `close()` | 通常不需要手动调 | 弹窗内部点 X 或蒙层都会自动调 |
+| `destroy()` | 组件卸载 / 路由切换 | 可选，但推荐在 SPA 中调用以释放资源 |
+---
+## 4. 配置项详解
+`init(options)` 接受以下参数：
+| 字段 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| `generatorId` | `string` | ✅ | — | 生成器标识，决定后端拉哪个生成器的耗材包 |
+| `accessoryType` | `string` | ✅ | — | 耗材类型，目前线上统一传 `'default'` |
+| `locale` | `'en' \| 'zh'` | ❌ | `'en'` | 弹窗语言 |
+| `zIndex` | `number` | ❌ | `9999` | 当宿主页面有更高层级 UI 时调高 |
+| `apiBaseUrl` | `string` | ❌ | `'https://xcs-api.xtool.com'` | 后端 API 基础地址，一般不用改 |
+| `messages` | `Record<string, Record<string, string>>` | ❌ | — | 覆盖/扩展词条，详见第 7 章 |
+| `onCheckoutSuccess` | `(url: string) => void` | ❌ | `window.open(url, '_blank')` | 拿到 checkoutUrl 后的行为 |
+| `onClose` | `() => void` | ❌ | — | 弹窗关闭时触发 |
+| `onError` | `(err: unknown) => void` | ❌ | — | 接口失败 / 结算失败时触发；SDK 内部会自带 toast，业务方不必再 UI 反馈 |
+---
+## 5. 鉴权
+SDK 调用后端时会**自动**在请求头注入：
+| Header | 来源 |
+| --- | --- |
+| `uToken` | 优先读 `document.cookie.utoken`，没有则读 `localStorage.utoken` |
+| `lang` | 读 `localStorage.LANG_KEY`，没有则默认 `'en'` |
+> 业务方需要保证宿主页面已经把 `utoken` 写入 cookie 或 localStorage（通常登录态完成后已经写入）。
+>
+> 跨域部署时，请确认 `xcs-api.xtool.com` 已允许调用方域名跨域，并允许携带 `uToken / lang` 自定义请求头。
+---
+## 6. 按框架接入示例
+### 6.1 原生 HTML / Vanilla JS
+```html
+<script src="/path/to/dist/index.umd.js"></script>
+<script>
+  GeneratorMaterialPurchase.init({
+    generatorId: 'light-sign',
+    accessoryType: 'default',
+    locale: 'zh',
+    onCheckoutSuccess: (url) => (location.href = url), // 当前页跳转而非新开标签
+    onClose: () => console.log('modal closed'),
+  })
+  document.querySelector('#buyBtn').onclick = () => GeneratorMaterialPurchase.open()
+</script>
+```
+### 6.2 Vue 3（Composition API）
+如果使用打包工具（Vite/Webpack），把 `index.es.js` 放在项目某处（例如 `src/lib/purchase-modal/`），然后：
+```vue
+<script setup lang="ts">
+import { onMounted, onBeforeUnmount } from 'vue'
+import GeneratorMaterialPurchase from '@/lib/purchase-modal/index.es.js'
+onMounted(() => {
+  GeneratorMaterialPurchase.init({
+    generatorId: 'light-sign',
+    accessoryType: 'default',
+  })
+})
+onBeforeUnmount(() => GeneratorMaterialPurchase.destroy())
+function handleBuy() {
+  GeneratorMaterialPurchase.open()
+}
+</script>
+<template>
+  <button @click="handleBuy">购买耗材</button>
+</template>
+```
+如果你的项目用 `<script src>` 引入（如某些 SSR 模板），改成在 mounted 里访问 `window.GeneratorMaterialPurchase` 即可。
+### 6.3 React
+```tsx
+import { useEffect } from 'react'
+import GeneratorMaterialPurchase from './lib/purchase-modal/index.es.js'
+export function BuyButton() {
+  useEffect(() => {
+    GeneratorMaterialPurchase.init({
+      generatorId: 'flower-generator',
+      accessoryType: 'default',
+    })
+    return () => GeneratorMaterialPurchase.destroy()
+  }, [])
+  return <button onClick={() => GeneratorMaterialPurchase.open()}>Buy accessories</button>
+}
+```
+### 6.4 Vue 2（Options API）
+```vue
+<script>
+import GeneratorMaterialPurchase from '@/lib/purchase-modal/index.es.js'
+export default {
+  mounted() {
+    GeneratorMaterialPurchase.init({
+      generatorId: 'light-sign',
+      accessoryType: 'default',
+    })
+  },
+  beforeDestroy() {
+    GeneratorMaterialPurchase.destroy()
+  },
+  methods: {
+    open() {
+      GeneratorMaterialPurchase.open()
+    },
+  },
+}
+</script>
+<template>
+  <button @click="open">购买耗材</button>
+</template>
+```
+### 6.5 ESM 工程的另一种集成方式（推荐）
+不想把 dist 文件复制进 src，可以放在 `public/` 或独立 CDN：
+```ts
+// 动态加载 UMD，从而无关打包工具
+function loadSdk(): Promise<any> {
+  return new Promise((resolve, reject) => {
+    if ((window as any).GeneratorMaterialPurchase) return resolve((window as any).GeneratorMaterialPurchase)
+    const s = document.createElement('script')
+    s.src = '/sdk/index.umd.js'
+    s.onload = () => resolve((window as any).GeneratorMaterialPurchase)
+    s.onerror = reject
+    document.head.appendChild(s)
+  })
+}
+const sdk = await loadSdk()
+sdk.init({ generatorId: 'light-sign', accessoryType: 'default' })
+sdk.open()
+```
+---
+## 7. 国际化（i18n）
+内置 `en` / `zh` 两套完整词条，用 `init({ locale: 'zh' })` 切换。
+### 7.1 覆盖某条 / 新增语言
+```ts
+GeneratorMaterialPurchase.init({
+  generatorId: 'light-sign',
+  accessoryType: 'default',
+  locale: 'en',
+  messages: {
+    en: { buy_now: 'Checkout securely' },       // 覆盖
+    ja: { shopify_supplies_kit: '消耗品キット' }, // 新增日语；未提供的 key 会 fallback 到 en
+  },
+})
+```
+### 7.2 词条键名一览
+| key | 含义 |
+| --- | --- |
+| `shopify_supplies_kit` | 弹窗标题 |
+| `close` | 关闭按钮 aria-label |
+| `current_country_notice` | 国家提示，模板含 `{country}` |
+| `loading` | 加载文案 |
+| `no_items_in_cart` | 空商品状态 |
+| `sold_out` | 售罄角标 |
+| `total` | 合计标签 |
+| `discount_notice` | 折扣码提示 |
+| `buy_now` | 立即购买按钮 |
+| `failed_load_product_list` | 拉取失败 toast |
+| `checkout_failed` | 结算失败 toast |
+| `selected_items_out_of_stock` | 勾选项已售罄 toast |
+| `no_valid_products_selected` | 无可购买商品 toast |
+| `store_us` / `store_ca` / `store_au` / `store_eu` / `store_de` / `store_fr` / `store_uk` / `store_jp` | 站点下拉短名 |
+| `country_usa` / `country_canada` / `country_australia` / `country_eu` / `country_germany` / `country_france` / `country_uk` / `country_japan` | 国家长名 |
+---
+## 8. 视觉规格
+| 维度 | 规格 |
+| --- | --- |
+| 挂载方式 | `document.body.appendChild(host)`，host 使用 **Shadow DOM** 隔离样式 |
+| 蒙层 | `position: fixed; inset: 0; background: rgba(0,0,0,0.4);`，点击关闭 |
+| 弹窗 | `position: fixed; top: 0; right: 0; width: 320px; height: 100vh;` |
+| 动画 | 蒙层 0.2s 透明度淡入，弹窗 0.25s `translateX(100% → 0)` |
+| 主色 | 购买按钮 `#ff0035`，强调 `#070b10`，提示橙 `#ff7c23` |
+| 字体 | `Inter, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif` |
+| CSS 命名 | BEM 风格，前缀 `xpm-` |
+由于使用 Shadow DOM，宿主页面的 CSS reset / Tailwind / 全局样式都不会污染弹窗内部；同时弹窗内部样式也不会泄漏到宿主页面。
+---
+## 9. 事件回调
+如果你需要在用户结算或关闭时做埋点 / 业务联动：
+```ts
+GeneratorMaterialPurchase.init({
+  generatorId: 'light-sign',
+  accessoryType: 'default',
+  onCheckoutSuccess: (url) => {
+    // 上报埋点 + 跳转
+    track('purchase_modal_checkout', { url })
+    location.href = url
+  },
+  onClose: () => track('purchase_modal_close'),
+  onError: (err) => track('purchase_modal_error', { err: String(err) }),
+})
+```
+---
+## 10. 常见问题（FAQ）
+### Q1：调用 `open()` 报错 "call init() before open()"
+没有先调 `init()`。在挂载阶段（Vue `onMounted` / React `useEffect`）调用一次 `init` 即可。
+### Q2：弹窗打开了但商品列表一直转圈 / 显示空
+依次排查：
+1. 浏览器 DevTools → Network 看 `/generator-accessory-pack` 接口是否 200 且返回 `code: 0`；
+2. 401 / 403 → 确认 `utoken` 是否已写入 cookie 或 localStorage；
+3. CORS 报错 → 找后端把调用方域名加入白名单。
+### Q3：结算按钮置灰
+当所有勾选项都被识别为售罄时按钮置灰。换变体或换站点重试。
+### Q4：如何在当前页跳转而不是新开标签
+```ts
+GeneratorMaterialPurchase.init({
+  generatorId: '...',
+  accessoryType: 'default',
+  onCheckoutSuccess: (url) => (window.location.href = url),
+})
+```
+### Q5：切换语言后弹窗没刷新
+若弹窗当前正打开，先 `close()` 再 `init({ locale: 'xx' })` 再 `open()`。
+### Q6：会污染全局变量吗
+UMD 模式仅在 `window` 挂一个 `GeneratorMaterialPurchase`；不会修改 `body` 的样式；只在弹窗存在期间向 `body` 追加一个 host 元素，`close/destroy` 后移除。
+### Q7：Shadow DOM 调试不便
+Chrome DevTools → Settings → Preferences → Elements → 勾选 "Show user agent shadow DOM"。也可以直接在 Console 里 `window.GeneratorMaterialPurchase.open()`。
+### Q8：可以同时打开多个弹窗吗
+不可以。SDK 是单例，第二次 `open()` 会等第一次的退出动画完成才挂载。
+---
+## 11. 给 AI 编程助手的接入提示词
+如果你想把接入工作交给 Claude / Cursor / Copilot / 其他 AI 助手，把下面这段提示词连同**本文档全文**一起喂给它即可：
+```
+你是一个前端集成专家。我需要你帮我把一个第三方弹窗 SDK
+（Purchase Modal SDK）集成到我的项目里。
+【SDK 文档】
+{此处粘贴本 README 全文}
+【我的项目信息】
+- 框架：{Vue 3 / Vue 2 / React / Angular / 纯 HTML，二选一}
+- 构建工具：{Vite / Webpack / 无}
+- TypeScript：{是 / 否}
+- dist 文件存放路径：{例如 public/sdk/ 或 src/lib/purchase-modal/}
+- 触发弹窗的入口：{例如 "右上角购买按钮" / "商品详情页 CTA"}
+- generatorId：{填入你的 generator code，例如 light-sign}
+- accessoryType：{通常填 default}
+- 期望的语言：{en / zh}
+- 结算后行为：{新开标签 / 当前页跳转}
+【你需要做的事】
+1. 告诉我应该把 dist 里哪个文件放到哪个位置；
+2. 给出完整的接入代码（包含 init / open / 卸载清理）；
+3. 如果是 TypeScript 项目，给出类型声明的引入方式；
+4. 给出一段可以在浏览器 Console 里手动测试 open/close 的代码片段；
+5. 列出我接入后应该如何自测（接口是否通、鉴权是否生效、视觉是否正确）。
+【限制】
+- 不要修改 SDK 本身，只做接入。
+- 不要引入额外的 UI 库。
+- 不要把弹窗封装成新的组件（直接调用 SDK 即可）。
+- 优先用项目已有的依赖完成。
+```
+把上面的 `{...}` 占位符替换成你项目的真实信息，然后把整段（包括本 README）一次性发给 AI 助手即可。
+---
+## 附：最简自测清单
+接入后跑一遍下面的清单：
+- [ ] 页面加载后 `console.log(window.GeneratorMaterialPurchase)` 能拿到对象（UMD 引入方式下）；
+- [ ] 点击按钮 → 弹窗从右侧滑入，宽 320px、撑满高度；
+- [ ] 弹窗外有半透明蒙层，点蒙层能关闭；
+- [ ] 商品列表能正常加载，DevTools → Network 看 `generator-accessory-pack` 返回 `code: 0`；
+- [ ] 切换站点（右上角下拉）→ 列表会重新拉取；
+- [ ] 勾选商品 + 调整数量 → 底部合计金额变化正确；
+- [ ] 点 "Buy now" → 浏览器跳转到 Shopify checkout 页（或触发了你自定义的 `onCheckoutSuccess`）。
+完成 ✅。

package/dist/index.d.ts ADDED Viewed

@@ -0,0 +1,81 @@
+declare const api: GeneratorMaterialPurchaseApi;
+export { api as GeneratorMaterialPurchase }
+export default api;
+export declare interface ChangeEventData {
+    uid: string;
+    [key: string]: string;
+}
+export declare interface GeneratorMaterialPurchaseApi {
+    init(options: PurchaseModalInitOptions): void;
+    open(): Promise<void>;
+    close(): void;
+    destroy(): void;
+}
+export declare type Locale = 'en' | 'zh' | string;
+export declare interface ProductDataType {
+    uid: string;
+    id: number | string;
+    title?: string;
+    image?: string;
+    quantity?: number;
+    defaultVariant?: number | string;
+    options?: ProductOptionType[];
+    variants?: ProductVariantType[];
+    displayName?: string;
+}
+export declare interface ProductOptionType {
+    key?: string;
+    value?: string[];
+    values?: string[];
+}
+export declare interface ProductVariantType {
+    id?: number | string;
+    title?: string;
+    image?: string;
+    compareAtPrice?: string;
+    price?: string;
+    isBind?: boolean;
+    availableForSale?: boolean;
+    outOfStock?: boolean;
+    storeUrl?: string;
+    option?: Record<string, string>;
+    displayPrice?: string;
+    displayCompareAtPrice?: string;
+}
+export declare interface PurchaseModalInitOptions {
+    /** 必填：生成器编码，例如 'light-sign'、'flower' 等 */
+    generatorId: string;
+    /** 必填：耗材类型，例如 'default' */
+    accessoryType: string;
+    /** 可选：默认语言，'en' | 'zh'，默认 'en' */
+    locale?: Locale;
+    /** 可选：z-index，默认 9999 */
+    zIndex?: number;
+    /** 可选：覆盖默认 prod apiBaseUrl */
+    apiBaseUrl?: string;
+    /** 可选：覆盖词条（深合并） */
+    messages?: Partial<Record<Locale, Record<string, string>>>;
+    /** 可选：结算完成时回调，默认 window.open(checkoutUrl, '_blank') */
+    onCheckoutSuccess?: (checkoutUrl: string) => void;
+    /** 可选：关闭回调 */
+    onClose?: () => void;
+    /** 可选：错误回调 */
+    onError?: (err: unknown) => void;
+}
+export declare interface StoreOption {
+    label: string;
+    value: string;
+    icon: string;
+    shopDomain: string;
+    storeFrontAccessToken: string;
+}
+export { }