Shopify App (spin-wheel-discount)

Joanna_Na
2 阅读3分钟

项目技术栈

  • 框架: Remix (基于 React Router 7)
  • 开发工具: Shopify CLI
  • 数据库: Prisma + SQLite
  • UI 组件: Shopify Polaris + Custom Web Components
  • 样式: CSS Modules
  • 集成: Shopify App Bridge, App Proxy, Webhooks

项目目录结构

spin-wheel-discount/
├── app/                # 核心业务逻辑（后端路由、API、React 组件）
├── extensions/         # Shopify 扩展（前端主题嵌入插件）
├── prisma/             # 数据库模型与迁移脚本
├── public/             # 静态资源（奖品图标、生成的 SVG）
├── .cursor/            # IDE 配置文件
├── .gemini/            # Gemini 扩展配置
├── package.json        # 项目依赖与脚本
├── shopify.app.toml    # Shopify 应用全局配置
└── vite.config.ts      # Vite 编译配置

详细文件夹与文件说明

1. 根目录 (Root)

  • package.json: 定义了项目的依赖项（如 @shopify/shopify-app-react-router）和运行脚本（dev, build, deploy）。
  • shopify.app.toml: 应用的核心配置文件，包含 client_id、权限范围（scopes）、Webhooks 订阅和 App Proxy 设置。
  • vite.config.ts: Remix/Vite 的构建配置，处理插件加载和路径别名。

2. app/ - 应用核心

这是项目最主要的部分，采用了 Remix 的路由约定。

  • models/: 后端数据交互层。
    • lottery.server.ts: 核心抽奖逻辑。包含：
      • drawPrize: 加权随机抽取算法，检查库存、限制和活动状态。
      • getPrizeConfigs: 获取奖品配置。
      • updateCampaignConfig: 更新活动设置。
    • discount-delivery.server.ts: 处理折扣码的生成与发放逻辑。
  • routes/: 定义了所有 URL 路由。
    • app._index.tsx: 商家后台首页，提供抽奖预览测试功能。
    • app.additional.tsx: 奖品管理页。商家在此设置 8 个奖品槽位、关联 Shopify 折扣、上传图片和调整权重。
    • app.delivery-logs.tsx: 投递日志页。记录所有折扣码发放的状态和详情。
    • app.tsx: 管理后台的主布局文件，包含导航栏。
    • apps.spin-wheel.*.tsx: App Proxy 路由。供 Storefront（客户端）调用的 API：
      • .config.tsx: 获取当前活动的转盘配置（颜色、奖品列表）。
      • .draw.tsx: 执行抽奖请求。
      • .claim.tsx: 领取奖励。
    • webhooks.*.tsx: 处理 Shopify 推送的 Webhook 事件（如卸载应用）。
  • styles/: 存放全局和组件级别的 CSS 模块。
  • db.server.ts: 初始化 Prisma 客户端。
  • entry.server.tsx: 服务端渲染（SSR）入口，当请求到达服务器时，该文件负责将 React 组件树渲染为 HTML 流（Stream）并发送给浏览器。它还集成了 Shopify 的响应头处理，确保安全策略（CSP）正确。
  • root.tsx: 应用的根布局组件，定义了 HTML 的基本结构（ <html> , <head> , <body> ），并引入了全局样式（如 Shopify Polaris 样式）。它是所有页面的父容器，包含了 <Outlet />用于渲染子路由。
  • routes.ts: - 路由映射配置。在最新的 React Router 7 / Remix 中，它配置了如何发现页面文件。如配置使用 flatRoutes() ，意味着它会自动扫描 app/routes 文件夹下的文件并根据文件名生成对应的 URL。
  • shopify.server.ts: 配置 Shopify API 身份验证和上下文。

3. extensions/ - 主题扩展 (Theme Extension)

这部分代码会被注入到 Shopify 店铺的前端页面中。

  • spin-wheel-theme/:
    • blocks/spin-wheel.liquid: 定义了可以在 Shopify 主题编辑器中添加的“块”。它引用了 JS 和 CSS。
    • assets/:
      • spin-wheel.js: 核心前端逻辑。负责渲染转盘、处理点击事件、调用后端 Proxy API 以及执行转盘动画。
      • spin-wheel.css: 转盘的视觉样式。
      • prize-*.svg: 默认的奖品图标。
    • shopify.extension.toml: 扩展的配置文件。

4. prisma/ - 数据库

  • schema.prisma: 核心定义文件

    这是 Prisma 的灵魂文件，定义了数据库的一切。它包含三个主要部分：

    • 数据源 (datasource) ：配置数据库连接。本项目使用的是 sqlite。
    • 生成器 (generator) ：配置要生成的客户端类型。
    • 模型 (models) ：定义了数据库表结构

  • migrations/ - 数据库迁移历史

  • dev.sqlite

    • 它是 Prisma 运行产生的结果。
    • 这是一个轻量级的文件型数据库，存储了所有实际的业务数据。

  • 常用相关指令

    • npx prisma generate : 根据 schema.prisma 更新 TypeScript 类型定义（在 node_modules/.prisma/client 中）。
    • npx prisma migrate dev : 在开发环境下应用 schema 变更并生成新的迁移文件。
    • npx prisma studio : 打开一个可视化的浏览器界面来直接查看和编辑数据库数据。

5. public/ - 静态资源

  • prizes/: 预置的一系列奖品图标（SVG）。
  • prize-generated/: 自动生成的临时图片资源。
avatar
文章
阅读
粉丝