Halalbooking项目开发文档

1. 项目概述和主要用途

本文档为Halalbooking项目的开发环境配置与使用指南，旨在帮助开发人员快速搭建本地开发环境、配置依赖、运行测试及管理后台任务。该项目基于Ruby on Rails、Clojure/ClojureScript构建，集成PostgreSQL数据库，支持多语言开发、自动化测试和后台任务处理，适用于旅游服务类应用的开发与维护。

2. 核心功能和特性

• 多技术栈支持：融合Ruby on Rails（前端/后端）、Clojure/ClojureScript（后端逻辑/前端交互）
• 数据库管理：集成PostgreSQL，支持生产数据库 dump 自动拉取与恢复
• 自动化测试：提供RSpec（Ruby）、ClojureScript测试、Capybara特性测试等多维度测试框架
• 开发效率工具：支持CSS热重载、SVG精灵图生成、代码 linting 等开发辅助功能
• 后台任务处理：基于QueueClassic（QC）的后台任务队列管理，支持开发/测试/生产环境适配

3. 使用场景和适用范围

3.1 适用环境

• 开发环境：本地开发与调试，支持 macOS（10.13+）及 Linux 系统
• 测试环境：自动化测试执行，包括单元测试、集成测试、截图测试
• 性能分析：通过profiling环境进行代码性能基准测试

3.2 限制条件

• macOS 10.13 以下版本在Puma集群模式下可能存在Ethon库兼容性问题（需特殊环境变量配置）
• 数据库 dump 拉取需SSH访问指定服务器（当前为oscar服务器）

4. 环境依赖和前置条件

4.1 核心依赖工具

4.2 Ruby版本别名配置

若.ruby-version文件中指定主版本（如3.1），需为本地安装的具体版本（如3.1.2）创建别名：

• rbenv用户：ln -s ~/.rbenv/versions/3.1.2 ~/.rbenv/versions/3.1
• rvm用户：rvm alias create ruby-3.1.0 3.1.2

4.3 macOS特有配置（10.13+）

在Puma集群模式下，Web Worker可能因Ethon库问题崩溃，需禁用fork安全检查：

bash
export OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES

建议将该变量添加至.pumaenv（Puma-dev）、~/.profile或等效环境配置文件中，确保启动Puma前生效。

5. 详细使用方法和配置说明

5.1 项目初始化

5.1.1 基础环境搭建

bash
make setup  # 执行项目初始化（依赖安装、配置生成等）

5.1.2 数据库初始化

需获取生产环境"development"版本数据库 dump 并恢复：

bash
make fetchdb  # 自动拉取生产数据库dump并恢复为本地`halalbooking`数据库

数据库dump生成与刷新说明

通过以下make命令可管理本地数据库样本数据（需SSH访问服务器）：

• make refreshdb：在服务器生成新dump文件（保存为last.dump），并同步至本地hb.dump
• make fetch-dump：仅下载服务器last.dump至本地hb.dump（仓库根目录）
• make restore-dump：从本地hb.dump恢复数据至数据库，并应用本地变更后删除dump文件
• make refresh-and-fetchdb：依次执行refreshdb和fetchdb

当前数据库操作服务器为oscar，需确保SSH访问权限。

5.2 ClojureScript配置

5.2.1 开发环境设置

1. 安装Leiningen：参考***指南
2. 启动CLJS构建与热重载：

   bash
   lein fig  # 启动热重载构建
   

3. 浏览器访问任意CLJS驱动页面即可加载。

5.2.2 性能优化配置

若需使用合并文件模式（提升性能）：

bash
# 监听并自动构建（front-whitespace或extranet-whitespace目标）
lein cljsbuild auto front-whitespace
# 单次构建
lein cljsbuild once front-whitespace
# 清理输出目录
lein clean

5.2.3 Devcards配置

1. 安装Leiningen后，启动lein fig
2. 浏览器访问/dev/cards查看组件开发卡片

5.3 Clojure后端配置

5.3.1 开发环境启动

1. 安装Clojure CLI：参考***指南
2. 启动开发服务器：

   bash
   clj -M:dev  # 启动REPL
   (start)     # 在REPL中执行以启动服务（默认端口8090）
   

3. 浏览器访问http://localhost:8090验证服务。

5.3.2 数据库连接配置

默认连接参数：

• 用户名：同当前shell用户（与psql行为一致）
• 数据库名：halalbooking（可通过PGDATABASE环境变量覆盖）

自定义配置方式：

bash
# 临时覆盖数据库名
PGDATABASE=hb clj -M:dev
# 全局配置（添加至~/.bash_profile）
export PGDATABASE=hb

5.3.3 Rails与Clojure集成

Rails默认在开发环境中 stub 所有Clojure请求，需配置环境变量启用代理：

bash
export HANDLE_CLOJURE_REQUESTS=proxy  # 添加至~/.profile或项目环境文件

5.3.4 代码Linting

使用clj-kondo进行Clojure代码静态检查，参考编辑器集成指南配置实时linting。

6. 测试方法

6.1 RSpec测试（Ruby代码）

bash
bin/rake spec:all        # 运行所有测试
bin/rspec front/spec     # 仅运行前端测试

6.2 ClojureScript测试

6.2.1 基于CLJS的测试

bash
yarn install  # 首次运行需安装依赖
make cljs-test-auto  # 持续运行测试（文件变更时自动触发）
make cljs-test-once  # 单次运行测试

6.2.2 Capybara特性测试

1. 安装ChromeDriver：

   bash
   brew install chromedriver  # macOS，首次安装
   brew upgrade chromedriver  # 升级现有版本
   

2. 启动依赖服务：lein fig（保持运行）
3. 执行Capybara测试（同RSpec命令，如bin/rspec spec/features）

6.3 Clojure后端测试

1. 准备测试数据库：

   bash
   bin/rake db:test:prepare  # 初始化测试数据库
   

2. 运行测试：

   bash
   make clj-test-once   # 单次运行测试
   make clj-test-auto   # 文件变更时自动重跑测试
   

6.4 截图测试

6.4.1 环境准备

bash
npm install -g selenium-standalone  # 安装Selenium
selenium-standalone install         # 安装浏览器驱动

6.4.2 执行测试

1. 启动依赖服务：

   bash
   rails s  # 启动Rails服务器
   lein fig  # 启动CLJS构建
   selenium-standalone start  # 启动Selenium
   

2. 运行截图测试：

   bash
   yarn run screenshots  # 默认测试本地环境；修改.hermione.conf.js可测试staging环境
   

7. 后台任务管理

7.1 开发环境

默认任务存储于queue_classic_jobs表（QC适配器），但需手动启动worker处理：

bash
make jobs  # 启动QC worker处理后台任务（如邮件发送）

清理积压任务：

bash
bin/rake qc:truncate  # 清空任务队列

7.2 测试环境

任务入队操作被stub，可通过Rails测试框架断言任务是否入队（参考Rails任务测试指南）。

7.3 生产/Staging环境

• Staging：不运行周期性任务（参考任务调度文档）
• 生产：基于QC的多worker处理queue_classic_jobs表任务，周期性任务通过cron调度（参考任务调度文档）

8. 开发辅助功能

8.1 SVG精灵图生成

bash
yarn run svg-sprite  # 更新SVG精灵图

排除文件：文件名以_前缀+.svg（如circle_.svg）将不纳入精灵图。

8.2 CSS热重载

bash
# 方式1：临时启用
CSS_LIVE_RELOAD=true rails s
# 方式2：添加至环境变量（如~/.profile）
export CSS_LIVE_RELOAD=true
# 启动CSS监听
yarn run watch-css  # 实时监控CSS变更并重建

8.3 性能分析

通过profiling环境（类生产配置）运行服务：

bash
RAILS_ENV=profiling bin/rails s  # 注意：代码变更后需重启服务

9. 部署方案示例（Docker Compose）

以下为基于项目技术栈的开发环境Docker Compose配置示例（docker-compose.yml）：

yaml
version: '3.8'

services:
  postgres:
    image: postgres:13
    environment:
      POSTGRES_USER: ${USER}
      POSTGRES_DB: halalbooking
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"

  rails:
    build: .
    command: rails s -b 0.0.0.0
    volumes:
      - .:/app
      - bundle_data:/usr/local/bundle
    ports:
      - "3000:3000"
    environment:
      - HANDLE_CLOJURE_REQUESTS=proxy
      - OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES  # macOS仅需
      - DATABASE_URL=postgres://${USER}@postgres:5432/halalbooking
    depends_on:
      - postgres
      - clojure

  clojure:
    build: .
    command: clj -M:dev
    volumes:
      - .:/app
    ports:
      - "8090:8090"
    environment:
      - PGDATABASE=halalbooking
      - PGUSER=${USER}
      - PGHOST=postgres
    depends_on:
      - postgres

volumes:
  postgres_data:
  bundle_data:

使用说明：

1. 创建Dockerfile（基于Ruby+JDK镜像，安装Node.js、Leiningen等依赖）
2. 启动服务：docker-compose up -d
3. 初始化数据库：docker-compose exec rails make fetchdb

10. 环境变量参考

11. 支持的浏览器

详见项目根目录.browserlistrc文件，包含目标浏览器版本范围（如Chrome 80+、Firefox 75+等）。

12. 常见问题解决

12.1 macOS Puma集群模式崩溃

问题：Puma集群模式下Web Worker因Ethon库问题崩溃。
解决方案：启动Puma前导出环境变量：

bash
export OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES  # 添加至~/.profile或.pumaenv

12.2 数据库连接失败

问题：clj -M:dev或rails c无法连接数据库。
排查：

• 确认PostgreSQL 13.x运行中：pg_isready
• 验证数据库存在：psql -d halalbooking
• 覆盖连接参数：PGDATABASE=hb PGUSER=myuser clj -M:dev

12.3 Clojure请求未被处理

问题：Rails返回404而非代理至Clojure服务。
解决方案：确保环境变量配置：

bash
export HANDLE_CLOJURE_REQUESTS=proxy  # 重启Rails服务生效