folioorg/mod-patron-blocks

FOLIO - mod-patron-blocks 镜像文档

1. 镜像概述和主要用途

1.1 概述

mod-patron-blocks 是 FOLIO（The Future of Libraries Is Open）开源图书馆服务平台的核心功能模块，专注于提供自动化用户屏蔽管理能力。作为 FOLIO 生态的重要组成部分，该模块通过预设规则和条件，实现对图书馆用户借阅权限的自动屏蔽与解除，旨在提升用户违规行为处理的效率和标准化水平。

1.2 主要用途

• 自动化识别用户借阅违规行为（如逾期未还、欠费超额等）
• 基于配置规则自动执行用户借阅权限屏蔽操作
• 支持屏蔽状态的动态管理（自动触发与解除）
• 与 FOLIO 其他模块（如 circulation、users、okapi）协同工作，提供一体化用户权限管理

2. 核心功能和特性

2.1 核心功能

• 规则驱动的自动屏蔽：基于可配置规则（如逾期天数、欠费金额）自动检测并执行用户屏蔽
• 多维度屏蔽策略：支持按借阅、续借、预约等不同操作类型设置屏蔽范围
• 状态联动管理：用户状态变化（如归还逾期图书、缴清欠费）时自动触发屏蔽解除
• 审计日志记录：完整记录屏蔽操作的触发条件、执行时间及操作人员，支持追溯审计

2.2 技术特性

• 微服务架构设计，与 FOLIO 生态无缝集成
• 基于 Java Spring Boot 开发，支持高可用性部署
• 灵活的配置机制，支持通过 Okapi 网关动态调整规则
• 容器化部署，适配云原生环境

3. 使用场景和适用范围

3.1 典型使用场景

• 逾期未还处理：用户借阅图书逾期超过设定天数（如30天）时，自动屏蔽其新借阅权限
• 欠费管理：用户累计欠费金额达到阈值（如100元）时，限制其借阅操作直至欠费结清
• 违规行为管控：对多次违反借阅规则的用户执行阶梯式屏蔽（如临时屏蔽→延长屏蔽→永久屏蔽）
• 批量规则更新：图书馆政策调整后，通过更新全局规则实现所有用户屏蔽策略的统一变更

3.2 适用范围

• 采用 FOLIO 图书馆服务平台的各类图书馆（高校图书馆、公共图书馆、专业图书馆等）
• 需要标准化、自动化处理用户借阅权限的文献信息机构
• 对用户行为管理有精细化、规则化需求的图书馆系统管理员

4. 使用方法和配置说明

4.1 环境要求

• Docker 19.03+ 或 Kubernetes 1.16+ 环境
• 可访问的 PostgreSQL 数据库（FOLIO 推荐版本 12+）
• FOLIO Okapi 网关（版本需与模块兼容，具体参考官方兼容性矩阵）
• 至少 512MB 容器内存（基于元数据参考值 357,913,941 bytes ≈ 341MB，建议预留冗余）

4.2 Docker 部署方案

4.2.1 基础 docker run 命令

bash
docker run -d \
  --name mod-patron-blocks \
  --network folio-network \
  -p 8081:8081 \
  -e SPRING_DATASOURCE_URL=jdbc:postgresql://folio-db:5432/folio \
  -e SPRING_DATASOURCE_USERNAME=folio_user \
  -e SPRING_DATASOURCE_PASSWORD=secure_password \
  -e JAVA_OPTIONS="-XX:MaxRAMPercentage=66.0" \
  -e OKAPI_URL=http://okapi:9130 \
  folioorg/mod-patron-blocks:latest

4.2.2 docker-compose 配置示例

yaml
version: '3.8'

services:
  mod-patron-blocks:
    image: folioorg/mod-patron-blocks:latest
    container_name: mod-patron-blocks
    restart: unless-stopped
    ports:
      - "8081:8081"
    environment:
      - SPRING_DATASOURCE_URL=jdbc:postgresql://db:5432/folio
      - SPRING_DATASOURCE_USERNAME=folio_user
      - SPRING_DATASOURCE_PASSWORD=folio_password
      - SPRING_DATASOURCE_DRIVER_CLASS_NAME=org.postgresql.Driver
      - JAVA_OPTIONS=-XX:MaxRAMPercentage=66.0
      - OKAPI_URL=http://okapi:9130
      - LOG_LEVEL=INFO
    depends_on:
      - db
      - okapi

  db:
    image: postgres:13
    container_name: folio-db
    environment:
      - POSTGRES_DB=folio
      - POSTGRES_USER=folio_user
      - POSTGRES_PASSWORD=folio_password
    volumes:
      - postgres-data:/var/lib/postgresql/data

  okapi:
    image: folioorg/okapi:latest
    container_name: folio-okapi
    ports:
      - "9130:9130"
    volumes:
      - okapi-data:/okapi-data

volumes:
  postgres-data:
  okapi-data:

4.3 核心配置参数

4.3.1 环境变量配置

4.3.2 规则配置（通过 Okapi 管理 API）

模块核心规则通过 Okapi 的 /configurations 端点配置，主要参数包括：

json
{
  "module": "mod-patron-blocks",
  "configName": "block-rules",
  "configs": [
    {
      "name": "overdueThreshold",
      "value": "30",
      "description": "逾期天数阈值"
    },
    {
      "name": "feeThreshold",
      "value": "100.00",
      "description": "欠费金额阈值（元）"
    },
    {
      "name": "blockActions",
      "value": "borrow,renew",
      "description": "屏蔽的操作类型（逗号分隔）"
    },
    {
      "name": "autoRelease",
      "value": "true",
      "description": "是否自动解除屏蔽"
    }
  ]
}

4.4 服务验证

部署完成后，可通过以下方式验证服务状态：

1. 健康检查接口：

   bash
   curl http://<容器IP>:8081/actuator/health
   

   正常响应：{"status":"UP"}

2. 模块注册验证（通过 Okapi）：

   bash
   curl http://<okapi-ip>:9130/_/proxy/tenants/<tenant>/modules/mod-patron-blocks
   

   响应中包含模块版本及状态信息表示注册成功

5. 注意事项

• 数据库初始化：首次部署需确保执行数据库 schema 迁移（可通过 FOLIO mod-configuration 或 Liquibase 执行）
• 版本兼容性：模块版本需与 Okapi 及其他 FOLIO 核心模块版本匹配，具体参考 FOLIO 版本矩阵
• 资源限制：生产环境建议设置容器内存限制（如 --memory=512m），避免资源竞争
• 规则更新：通过 Okapi 更新规则后需重启模块或调用 /admin/reload-config 接口使配置生效

6. 参考资料

• 官方代码仓库：https://github.com/folio-org/mod-patron-blocks
• FOLIO 模块开发文档：[***]
• Okapi 配置管理 API：[***]