rails_curd_base 0.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 45ac1efb0de272c8bfc202ab29ec4f216582e23fcd16cfc85dbe1ce3bfbb9534
+  data.tar.gz: 64dcac6b6270ce247d77192370a306f683c3d1b04df6b54fb0b32a86d5c8919b
+SHA512:
+  metadata.gz: 9da65048981078282d064ad920534a761a1bd33932571ba74d5cfe89e1726d15d5e9f0cb6a13e7942eea08f2623e058ef955f3f6bdfe2e2c0d17bcf244a65c2b
+  data.tar.gz: e2d92aba652e4a9cb808e3af848666515fbf4a61dc2cb35565ddae0ea10ba5682118b6fe84a5a6b579c93fd21155e80921aa06438ead5b02389d562db4b1cff5

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright aric.zheng
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,550 @@
+# RailsCurdBase
+
+> RailsCurdBase 是一个用于 Ruby on Rails 的 CRUD 基础控制器 gem，提供开箱即用的增删改查功能、查询能力、分页、排序、搜索和过滤。它使用 RailsWarp 提供统一的 JSON 响应格式，并使用 Kaminari 处理分页。
+
+## 特性
+
+- 🔥 **零配置 CRUD** - 继承 `CurdController` 即可获取完整的增删改查功能
+- 🔍 **强大查询** - 内置分页、排序、搜索、过滤功能，通过 `supports_query` 轻松配置
+- 📦 **统一响应** - 基于 RailsWarp 的统一 JSON 响应格式
+- 🎣 **生命周期钩子** - 提供 `before_create`, `after_create`, `before_update`, `after_update` 四个钩子
+- 🤖 **AI 友助** - 配备完整的 LLM 提示文档 (`llms.txt`)，方便 AI 辅助编程
+- ⚙️ **零依赖蓝图** - 不依赖任何序列化 gem，使用 Rails 原生 `as_json`
+- 🔧 **高度可定制** - 轻松覆盖 `collection`、序列化方法等实现自定义逻辑
+
+## 兼容性
+
+- ✅ Rails 6.0+
+- ✅ Ruby 2.7+
+- ✅ API 模式 (`ActionController::API`)
+
+## 安装
+
+将这行添加到你的应用的 Gemfile 中：
+
+```ruby
+gem "rails_curd_base"
+```
+
+然后执行：
+
+```bash
+$ bundle install
+```
+
+或者手动安装：
+
+```bash
+$ gem install rails_curd_base
+```
+
+## 快速开始
+
+### 1. 创建模型
+
+```ruby
+# app/models/post.rb
+class Post < ApplicationRecord
+  validates :title, presence: true
+  validates :content, presence: true
+end
+```
+
+### 2. 创建控制器
+
+```ruby
+# app/controllers/api/posts_controller.rb
+class Api::PostsController < RailsCurdBase::CurdController
+  # 启用查询功能
+  supports_query(
+    pagination: { enabled: true, default_per: 10, max_per: 50 },
+    sorting: { enabled: true, allowed_fields: [:id, :title, :created_at] },
+    searching: { enabled: true, searchable_fields: [:title, :content] },
+    filtering: { enabled: true, filterable_fields: [:status] }
+  )
+end
+```
+
+### 3. 配置路由
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  namespace :api do
+    resources :posts
+  end
+end
+```
+
+就这么简单！现在你拥有了完整的 CRUD API：
+
+- `GET /api/posts` - 列表（支持分页、排序、搜索、过滤）
+- `GET /api/posts/1` - 详情
+- `POST /api/posts` - 创建
+- `PUT /api/posts/1` - 更新
+- `DELETE /api/posts/1` - 删除
+
+## API 使用示例
+
+### 获取列表（基础）
+
+```bash
+GET /api/posts
+```
+
+**响应：**
+```json
+{
+  "success": true,
+  "code": 200,
+  "msg": "Retrieved successfully",
+  "data": {
+    "rows": [...],
+    "total": 100
+  }
+}
+```
+
+### 分页查询
+
+```bash
+GET /api/posts?page=1&size=20
+```
+
+### 排序
+
+```bash
+# 升序
+GET /api/posts?sort=title
+
+# 降序（使用 - 前缀）
+GET /api/posts?sort=-created_at
+```
+
+### 搜索
+
+```bash
+GET /api/posts?q=hello
+```
+
+在 `title` 和 `content` 字段中模糊搜索 "hello"。
+
+### 过滤
+
+```bash
+# 等于
+GET /api/posts?filter[status]=published
+
+# 大于等于
+GET /api/posts?filter[views][gte]=100
+
+# 在数组中
+GET /api/posts?filter[category_id][in]=1,2,3
+```
+
+支持的过滤操作符：`eq`（默认）, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`
+
+### 组合查询
+
+```bash
+GET /api/posts?page=1&size=20&sort=-created_at&q=rails&filter[status]=published
+```
+
+### 创建记录
+
+```bash
+POST /api/posts
+Content-Type: application/json
+
+{
+  "post": {
+    "title": "Hello World",
+    "content": "My first post",
+    "status": "published"
+  }
+}
+```
+
+### 更新记录
+
+```bash
+PUT /api/posts/1
+Content-Type: application/json
+
+{
+  "post": {
+    "title": "Updated Title"
+  }
+}
+```
+
+### 删除记录
+
+```bash
+DELETE /api/posts/1
+```
+
+## 高级用法
+
+### 生命周期钩子
+
+```ruby
+class Api::PostsController < RailsCurdBase::CurdController
+  supports_query(
+    pagination: { enabled: true, default_per: 10 }
+  )
+
+  # 创建前钩子
+  def before_create(resource)
+    resource.author = current_user
+    resource.published_at = Time.current if resource.status == 'published'
+    true  # 必须返回 true，否则会中止保存
+  end
+
+  # 创建后钩子
+  def after_create(resource)
+    NotificationService.notify_followers(resource)
+  end
+
+  # 更新前钩子
+  def before_update(resource)
+    resource.editor = current_user
+    true
+  end
+
+  # 更新后钩子
+  def after_update(resource)
+    CacheService.invalidate(resource)
+  end
+end
+```
+
+### 自定义数据范围
+
+```ruby
+class Api::PostsController < RailsCurdBase::CurdController
+  # 只返回当前用户的文章
+  def collection
+    current_user.posts
+  end
+end
+```
+
+### 嵌套资源
+
+```ruby
+class Api::UserPostsController < RailsCurdBase::CurdController
+  def collection
+    user.posts  # 假设 params[:user_id] 存在
+  end
+end
+```
+
+### 自定义序列化
+
+```ruby
+class Api::PostsController < RailsCurdBase::CurdController
+  private
+
+  def serialize_resource(resource)
+    {
+      id: resource.id,
+      title: resource.title,
+      summary: resource.content.truncate(100),
+      author_name: resource.author.name,
+      created_at: resource.created_at.iso8601
+    }
+  end
+
+  def serialize_collection(collection)
+    collection.map { |resource| serialize_resource(resource) }
+  end
+end
+```
+
+### 添加认证和授权
+
+```ruby
+class Api::PostsController < RailsCurdBase::CurdController
+  before_action :authenticate_user!
+  before_action :set_post, only: [:show, :update, :destroy]
+
+  private
+
+  def authenticate_user!
+    head :unauthorized unless current_user
+  end
+
+  def set_post
+    @post = current_user.posts.find_by(id: params[:id])
+  end
+end
+```
+
+## Queryable 配置详解
+
+`supports_query` 方法接受四个配置项：
+
+### 分页配置
+
+```ruby
+pagination: {
+  enabled: true,              # 是否启用
+  default_per: 20,             # 默认每页数量
+  max_per: 100,                # 最大每页数量
+  page_param: :page,            # 页码参数名
+  per_param: :size              # 每页数量参数名
+}
+```
+
+### 排序配置
+
+```ruby
+sorting: {
+  enabled: true,                    # 是否启用
+  allowed_fields: [:id, :title],      # 允许排序的字段
+  sort_param: :sort,                # 排序参数名
+  default_direction: :asc            # 默认排序方向
+}
+```
+
+使用：`?sort=title`（升序）或 `?sort=-title`（降序）
+
+### 搜索配置
+
+```ruby
+searching: {
+  enabled: true,                      # 是否启用
+  searchable_fields: [:title, :content],  # 可搜索的字段
+  search_param: :q                     # 搜索参数名
+}
+```
+
+搜索会对所有 `searchable_fields` 执行 `LIKE %term%` 查询。
+
+### 过滤配置
+
+```ruby
+filtering: {
+  enabled: true,                        # 是否启用
+  filterable_fields: [:status, :category_id],  # 可过滤的字段
+  filter_param: :filter                 # 过滤参数名
+}
+```
+
+支持的过滤操作符：
+- `?filter[field]=value` - 等于 (eq)
+- `?filter[field][neq]=value` - 不等于 (neq)
+- `?filter[field][gt]=value` - 大于 (gt)
+- `?filter[field][gte]=value` - 大于等于 (gte)
+- `?filter[field][lt]=value` - 小于 (lt)
+- `?filter[field][lte]=value` - 小于等于 (lte)
+- `?filter[field][in]=1,2,3` - 在数组中 (in)
+- `?filter[field][nin]=1,2,3` - 不在数组中 (nin)
+
+## 资源自推导
+
+`CurdController` 会自动从控制器名称推导资源类：
+
+| 控制器 | 资源类 | 参数键 | 实例变量 |
+|---------|---------|---------|-----------|
+| `Api::PostsController` | `Post` | `:post` | `@post` |
+| `Api::UsersController` | `User` | `:user` | `@user` |
+| `Api::CommentsController` | `Comment` | `:comment` | `@comment` |
+
+如需自定义，可覆盖以下方法：
+
+```ruby
+def resource_class
+  CustomPost  # 覆盖自动推导
+end
+
+def resource_key
+  :article  # 覆盖 :post
+end
+```
+
+## 响应格式
+
+所有 API 响应都遵循统一的格式（基于 RailsWarp）：
+
+### 成功响应
+
+```json
+{
+  "success": true,
+  "code": 200,
+  "msg": "Retrieved successfully",
+  "data": { ... }
+}
+```
+
+### 错误响应
+
+```json
+{
+  "success": false,
+  "code": 422,
+  "msg": "Validation failed",
+  "data": {
+    "errors": ["Title can't be blank"]
+  }
+}
+```
+
+### HTTP 状态码
+
+| 场景 | 状态码 |
+|------|---------|
+| 获取列表 | 200 |
+| 获取详情 | 200 |
+| 创建成功 | 201 |
+| 更新成功 | 200 |
+| 删除成功 | 204 |
+| 验证失败 | 422 |
+| 未找到 | 404 |
+| 未授权 | 401 |
+
+## 示例应用
+
+完整的示例应用请查看 `test/dummy/` 目录：
+
+```bash
+cd test/dummy
+bin/rails db:migrate
+bin/rails db:seed
+bin/rails server
+```
+
+然后访问 `http://localhost:3000/api/posts`
+
+详细文档请查看 [test/dummy/EXAMPLE_USAGE.md](test/dummy/EXAMPLE_USAGE.md)
+
+## AI 辅助编程
+
+本项目包含完整的 LLM 提示文档 `llms.txt`，帮助 Claude、ChatGPT 等 AI 更好地理解和使用本项目。
+
+## 依赖项
+
+- **rails** >= 6.0
+- **kaminari** >= 0.16 - 分页功能
+- **rails_warp** >= 0.1.0 - 统一响应格式
+
+## 性能优化建议
+
+1. **数据库索引** - 在排序和过滤的字段上添加索引
+   ```ruby
+   add_index :posts, :status
+   add_index :posts, :created_at
+   add_index :posts, :author_id
+   ```
+
+2. **限制查询字段** - 通过覆盖 `serialize_resource` 只返回需要的字段
+
+3. **使用缓存** - 在钩子方法中实现缓存逻辑
+
+4. **优化 SQL** - 覆盖 `collection` 方法优化复杂查询
+
+## 常见问题
+
+### 1. 如何添加额外的查询逻辑？
+
+```ruby
+def collection
+  base = super
+  base = base.where(published: true) unless current_user&.admin?
+  base
+end
+```
+
+### 2. 如何实现软删除？
+
+```ruby
+def destroy
+  resource.update!(deleted_at: Time.current)
+  ok message: "Deleted successfully", code: 204
+end
+```
+
+### 3. 如何添加版本控制？
+
+```ruby
+# config/routes.rb
+namespace :api do
+  namespace :v1 do
+    resources :posts
+  end
+end
+
+# app/controllers/api/v1/posts_controller.rb
+module Api
+  module V1
+    class PostsController < RailsCurdBase::CurdController
+      # ...
+    end
+  end
+end
+```
+
+### 4. 如何自定义错误处理？
+
+```ruby
+rescue_from ActiveRecord::RecordNotFound, with: :handle_not_found
+rescue_from StandardError, with: :handle_error
+
+private
+
+def handle_not_found
+  fail message: "Record not found", code: 404
+end
+
+def handle_error(e)
+  Rails.logger.error "Error: #{e.class} - #{e.message}"
+  fail message: "Internal server error", code: 500
+end
+```
+
+## 开发
+
+欢迎贡献！请遵循以下步骤：
+
+1. Fork 本仓库
+2. 创建你的特性分支 (`git checkout -b my-amazing-feature`)
+3. 提交你的修改 (`git commit -am 'Add some amazing feature'`)
+4. 推送到分支 (`git push origin my-amazing-feature`)
+5. 创建新的 Pull Request
+
+### 运行测试
+
+```bash
+cd test/dummy
+bin/rails db:migrate RAILS_ENV=test
+bin/rails test
+```
+
+## 路线图
+
+![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)
+![Rails](https://img.shields.io/badge/rails-%3E%206.0-red.svg)
+![Ruby](https://img.shields.io/badge/ruby-%3E%3D2.7-red.svg)
+
+## 作者
+
+- **aric.zheng** - 1290657123@qq.com
+
+## 许可证
+
+本 gem 以 MIT 许可证开源 - 详见 [MIT-LICENSE](MIT-LICENSE) 文件。
+
+## 致谢
+
+- [RailsWarp](https://github.com/afeiship/rails_warp) - 统一的响应格式
+- [Kaminari](https://github.com/kaminari/kaminari) - 分页功能
+- [rails_api_base](https://github.com/afeiship/rails_api_base) - 参考实现
+
+## 支持
+
+如有问题或建议，请：
+- 提交 [Issue](https://github.com/afeiship/rails_curd_base/issues)
+- 发送 Pull Request
+- 联系作者：1290657123@qq.com

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+require "bundler/gem_tasks"

data/app/controllers/concerns/rails_curd_base/queryable.rb

@@ -0,0 +1,178 @@
+module RailsCurdBase
+  module Queryable
+    extend ActiveSupport::Concern
+
+    DEFAULT_CONFIG = {
+      pagination: {
+        enabled: false,
+        page_param: :page,
+        per_param: :size,
+        default_per: 10,
+        max_per: 100
+      },
+      sorting: {
+        enabled: false,
+        sort_param: :sort,
+        default_direction: :asc,
+        allowed_fields: []
+      },
+      searching: {
+        enabled: false,
+        search_param: :q,
+        searchable_fields: []
+      },
+      filtering: {
+        enabled: false,
+        filter_param: :filter,
+        filterable_fields: []
+      },
+      meta: {
+        enabled: true,
+        rows_key: :rows,
+        total_key: :total
+      }
+    }.freeze
+
+    class_methods do
+      def supports_query(user_config = {})
+        config = DEFAULT_CONFIG.deep_dup
+        user_config.each do |key, value|
+          if config.key?(key) && value.is_a?(Hash)
+            config[key].merge!(value)
+          else
+            config[key] = value
+          end
+        end
+
+        define_method(:query_config) { config }
+        include InstanceMethods
+      end
+    end
+
+    module InstanceMethods
+      def apply_query_with_meta(scope)
+        config = query_config
+        meta = {}
+
+        # 应用过滤、搜索、排序（不分页）
+        base_scope = scope
+        base_scope = apply_filtering(base_scope)    if config[:filtering][:enabled]
+        base_scope = apply_searching(base_scope)    if config[:searching][:enabled]
+        base_scope = apply_sorting(base_scope)      if config[:sorting][:enabled]
+
+        # 获取总数（用于 meta）
+        if config[:meta][:enabled]
+          meta[config[:meta][:total_key]] = base_scope.count
+        end
+
+        # 应用分页
+        paginated_scope = base_scope
+        if config[:pagination][:enabled]
+          paginated_scope = apply_pagination(base_scope)
+        end
+
+        {
+          collection: paginated_scope,
+          meta: config[:meta][:enabled] ? meta : nil
+        }
+      end
+
+      private
+
+      def apply_pagination(scope)
+        config = query_config[:pagination]
+        page = [params[config[:page_param]].to_i, 1].max
+        per_input = params[config[:per_param]].to_i
+        per = per_input <= 0 ? config[:default_per] : [per_input, config[:max_per]].min
+        per = [per, 1].max
+        scope.page(page).per(per)
+      end
+
+      def apply_sorting(scope)
+        config = query_config[:sorting]
+        sort_param = params[config[:sort_param]]
+        return scope unless sort_param.present?
+
+        direction = sort_param.start_with?('-') ? :desc : :asc
+        field = sort_param.delete_prefix('-').to_sym
+        connection = scope.connection
+
+        if config[:allowed_fields].empty? || config[:allowed_fields].include?(field)
+          quoted_field = connection.quote_column_name(field)
+          return scope.order(Arel.sql("#{quoted_field} #{direction}"))
+        else
+          return scope
+        end
+      end
+
+      def apply_searching(scope)
+        config = query_config[:searching]
+        term = params[config[:search_param]]&.strip
+        return scope unless term.present?
+
+        searchable_fields = config[:searchable_fields]
+        return scope if searchable_fields.empty?
+
+        connection = scope.connection
+
+        terms = Array.new(searchable_fields.size, "%#{term}%")
+        conditions = searchable_fields.map do |f|
+          "LOWER(#{connection.quote_column_name(f)}) LIKE LOWER(?)"
+        end.join(' OR ')
+        scope.where(conditions, *terms)
+      end
+
+      def apply_filtering(scope)
+        config = query_config[:filtering]
+        raw_filters = params[config[:filter_param]]
+        return scope if raw_filters.blank?
+
+        # 1. 获取允许过滤的字段名（字符串数组）
+        filterable_fields = config[:filterable_fields].map(&:to_s)
+
+        # 2. permit 这些字段（包括嵌套操作符）
+        # 支持两种格式：filter[status]=published 或 filter[status][eq]=published
+        permitted = raw_filters.permit(
+          *filterable_fields.map { |f| f.to_sym },
+          *filterable_fields.map { |f| { f.to_sym => [:eq, :neq, :gt, :gte, :lt, :lte, :in, :nin] } }
+        )
+
+        # 3. 转为普通 Hash
+        filters = permitted.to_h
+
+        connection = scope.connection
+
+        filters.inject(scope) do |s, (field, value)|
+          if value.is_a?(Hash)
+            op = value.keys.first&.to_sym
+            val = value.values.first
+            apply_filter_operation(s, field, op, val)
+          else
+            s.where("#{connection.quote_column_name(field)} = ?", val_or_array(value))
+          end
+        end
+      end
+
+      def apply_filter_operation(scope, field, op, value)
+        connection = scope.connection
+        quoted = connection.quote_column_name(field)
+        case op
+        when :eq  then scope.where("#{quoted} = ?", val_or_array(value))
+        when :neq then scope.where("#{quoted} != ?", val_or_array(value))
+        when :gt  then scope.where("#{quoted} > ?", value)
+        when :gte then scope.where("#{quoted} >= ?", value)
+        when :lt  then scope.where("#{quoted} < ?", value)
+        when :lte then scope.where("#{quoted} <= ?", value)
+        when :in  then scope.where(quoted => Array(value))
+        when :nin then scope.where.not(quoted => Array(value))
+        else scope
+        end
+      end
+
+      def val_or_array(val)
+        return val unless val.is_a?(String) && val.include?(',')
+        val.split(',').map(&:strip)
+      end
+    end
+  end
+end

data/app/controllers/rails_curd_base/application_controller.rb

@@ -0,0 +1,4 @@
+module RailsCurdBase
+  class ApplicationController < ActionController::Base
+  end
+end

data/app/controllers/rails_curd_base/curd_controller.rb

@@ -0,0 +1,103 @@
+module RailsCurdBase
+  class CurdController < ActionController::API
+    include Queryable
+
+    # === CRUD 基础动作 ===
+    before_action :set_resource, only: %i[show update destroy]
+
+    def index
+      result = apply_query_with_meta(collection)
+      data = {
+        query_config[:meta][:rows_key] => serialize_collection(result[:collection]),
+      }
+      data.merge!(result[:meta]) if result[:meta]
+      ok data: data, message: "Retrieved successfully"
+    end
+
+    def show
+      data = serialize_resource(resource)
+      ok data: data
+    end
+
+    def create
+      @resource = resource_class.new(resource_params)
+      if before_save(@resource) && @resource.save
+        after_save(@resource)
+        data = serialize_resource(@resource)
+        ok data: data, message: "Created successfully", code: 201
+      else
+        fail message: "Validation failed", code: 422, data: { errors: @resource.errors.full_messages }
+      end
+    end
+
+    def update
+      if before_save(resource) && resource.update(resource_params)
+        after_save(resource)
+        data = serialize_resource(resource)
+        ok data: data, message: "Updated successfully"
+      else
+        fail message: "Validation failed", code: 422, data: { errors: resource.errors.full_messages }
+      end
+    end
+
+    # === 可选：通用钩子（默认调用 create/update 钩子）===
+    def before_save(resource)
+      action_name == "create" ? before_create(resource) : before_update(resource)
+    end
+
+    def after_save(resource)
+      action_name == "create" ? after_create(resource) : after_update(resource)
+    end
+
+    # === 子类覆盖这些 ===
+    def before_create(resource); true; end
+    def after_create(resource); end
+
+    def before_update(resource); true; end
+    def after_update(resource); end
+
+    def destroy
+      resource.destroy
+      ok message: "Deleted successfully", code: 204
+    end
+
+    private
+
+    # === 序列化逻辑 ===
+    def serialize_resource(resource)
+      resource.as_json
+    end
+
+    def serialize_collection(collection)
+      collection.as_json
+    end
+
+    # === 资源推导 ===
+    def resource_class
+      controller_name.singularize.classify.constantize
+    end
+
+    def resource_key
+      controller_name.singularize.underscore.to_sym
+    end
+
+    def resource
+      instance_variable_get("@#{controller_name.singularize}")
+    end
+
+    def set_resource
+      instance_variable_set("@#{controller_name.singularize}", resource_class.find(params[:id]))
+    rescue ActiveRecord::RecordNotFound
+      fail message: "Record not found", code: 404
+    end
+
+    def collection
+      resource_class.all
+    end
+
+    def resource_params
+      permitted_params = params.require(resource_key)
+      permitted_params.permit!
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,2 @@
+RailsCurdBase::Engine.routes.draw do
+end

data/lib/rails_curd_base/engine.rb

@@ -0,0 +1,5 @@
+module RailsCurdBase
+  class Engine < ::Rails::Engine
+    isolate_namespace RailsCurdBase
+  end
+end

data/lib/rails_curd_base/version.rb

@@ -0,0 +1,3 @@
+module RailsCurdBase
+  VERSION = "0.1.2"
+end

data/lib/rails_curd_base.rb

@@ -0,0 +1,8 @@
+require "rails_curd_base/version"
+require "rails_curd_base/engine"
+require "kaminari"
+require "rails_warp"
+
+module RailsCurdBase
+  # Your code goes here...
+end

data/lib/tasks/rails_curd_base_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :rails_curd_base do
+#   # Task goes here
+# end

data/llms.txt

@@ -0,0 +1,369 @@
+# RailsCurdBase - AI Assistant Guide
+
+> RailsCurdBase is a Ruby on Rails CRUD base controller gem providing ready-to-use Create, Read, Update, Delete functionality with advanced query capabilities including pagination, sorting, searching, and filtering. It integrates RailsWarp for unified JSON responses and Kaminari for pagination.
+
+**IMPORTANT NOTES FOR AI ASSISTANTS:**
+- RailsCurdBase inherits from ActionController::API for Rails API applications
+- All responses use RailsWarp unified format: { success: boolean, code: integer, msg: string, data: object }
+- Controllers automatically derive resource class from controller name (Api::PostsController => Post model)
+- Built-in Queryable concern provides pagination, sorting, searching, filtering
+- Four lifecycle hooks: before_create, after_create, before_update, after_update
+- Resource automatically derived: controller_name.singularize.classify.constantize
+
+## DOCUMENTATION LINKS
+
+- Repository: https://github.com/afeiship/rails_curd_base
+- Usage Guide: test/dummy/EXAMPLE_USAGE.md (complete API documentation and examples)
+- Test/Demo App: test/dummy/ directory (fully working example)
+
+## CORE FEATURES
+
+### 1. Zero-Configuration CRUD
+Inherit from CurdController to get complete CRUD:
+- index: List with pagination, sorting, searching, filtering
+- show: Single record retrieval
+- create: Create new records
+- update: Update existing records
+- destroy: Delete records
+
+### 2. Queryable Module (supports_query)
+Configure via supports_query:
+- Pagination: page, size parameters (Kaminari)
+- Sorting: sort parameter (supports -field for desc)
+- Searching: q parameter (multi-field LIKE search)
+- Filtering: filter parameter (eq, neq, gt, gte, lt, lte, in, nin operators)
+
+### 3. Unified Response Format (RailsWarp)
+- ok: success response with data, message, code
+- fail: error response with message, code, errors data
+
+### 4. Lifecycle Hooks
+- before_create(resource): called before create, return false to abort
+- after_create(resource): called after successful create
+- before_update(resource): called before update, return false to abort
+- after_update(resource): called after successful update
+
+### 5. Automatic Resource Derivation
+- resource_class: Model class (auto-derived from controller name)
+- resource_key: Parameter symbol (:post, :user, etc.)
+- resource: Current resource instance (@post, @user, etc.)
+
+## INSTALLATION
+
+Add to Gemfile:
+```ruby
+gem 'rails_curd_base'
+```
+
+Run:
+```bash
+bundle install
+```
+
+## BASIC USAGE
+
+### Create Controller
+```ruby
+class Api::PostsController < RailsCurdBase::CurdController
+  supports_query(
+    pagination: { enabled: true, default_per: 10, max_per: 50 },
+    sorting: { enabled: true, allowed_fields: [:id, :title, :created_at] },
+    searching: { enabled: true, searchable_fields: [:title, :content] },
+    filtering: { enabled: true, filterable_fields: [:status] }
+  )
+end
+```
+
+### API Endpoints
+```bash
+# List (with pagination, sorting, searching, filtering)
+GET /api/posts?page=1&size=10&sort=-created_at&q=rails&filter[status]=published
+
+# Show single
+GET /api/posts/1
+
+# Create
+POST /api/posts
+{"post": {"title": "Hello", "content": "World", "status": "published"}}
+
+# Update
+PUT /api/posts/1
+{"post": {"title": "Updated"}}
+
+# Delete
+DELETE /api/posts/1
+```
+
+### Response Format
+Success:
+```json
+{
+  "success": true,
+  "code": 200,
+  "msg": "Retrieved successfully",
+  "data": {
+    "rows": [...],
+    "total": 100
+  }
+}
+```
+
+Error:
+```json
+{
+  "success": false,
+  "code": 422,
+  "msg": "Validation failed",
+  "data": {
+    "errors": ["Title can't be blank"]
+  }
+}
+```
+
+## QUERYABLE CONFIGURATION
+
+### Pagination
+```ruby
+supports_query(
+  pagination: {
+    enabled: true,
+    default_per: 20,
+    max_per: 100,
+    page_param: :page,
+    per_param: :size
+  }
+)
+```
+
+### Sorting
+```ruby
+supports_query(
+  sorting: {
+    enabled: true,
+    allowed_fields: [:id, :title, :created_at],
+    sort_param: :sort
+  }
+)
+# Usage: ?sort=field or ?sort=-field (desc)
+```
+
+### Searching
+```ruby
+supports_query(
+  searching: {
+    enabled: true,
+    searchable_fields: [:title, :content],
+    search_param: :q
+  }
+)
+# Usage: ?q=search_term
+# Performs: WHERE field LIKE '%term%' OR field2 LIKE '%term%'
+```
+
+### Filtering
+```ruby
+supports_query(
+  filtering: {
+    enabled: true,
+    filterable_fields: [:status, :category_id],
+    filter_param: :filter
+  }
+)
+# Usage:
+# ?filter[status]=published (eq)
+# ?filter[status][neq]=draft (not equals)
+# ?filter[views][gte]=100 (greater than or equal)
+# ?filter[views][lte]=1000 (less than or equal)
+# ?filter[category_id][in]=1,2,3 (in array)
+# ?filter[status][nin]=draft,archived (not in array)
+```
+
+## CUSTOMIZATION
+
+### Override Collection (Scope Data)
+```ruby
+class Api::PostsController < RailsCurdBase::CurdController
+  def collection
+    current_user.posts  # Only current user's posts
+  end
+end
+```
+
+### Lifecycle Hooks
+```ruby
+class Api::PostsController < RailsCurdBase::CurdController
+  before_action :authenticate_user!
+
+  def before_create(resource)
+    resource.author = current_user
+    resource.published_at = Time.current if resource.status == 'published'
+    true  # Must return true to continue
+  end
+
+  def after_create(resource)
+    NotificationService.notify(resource)
+  end
+end
+```
+
+### Custom Resource Class
+```ruby
+class Api::PostsController < RailsCurdBase::CurdController
+  def resource_class
+    CustomPost  # Override auto-derivation
+  end
+end
+```
+
+### Custom Serialization
+```ruby
+class Api::PostsController < RailsCurdBase::CurdController
+  private
+
+  def serialize_resource(resource)
+    {
+      id: resource.id,
+      title: resource.title,
+      summary: resource.content.truncate(100)
+    }
+  end
+
+  def serialize_collection(collection)
+    collection.map { |r| serialize_resource(r) }
+  end
+end
+```
+
+### Add Authentication/Authorization
+```ruby
+class Api::PostsController < RailsCurdBase::CurdController
+  before_action :authenticate_user!
+  before_action :set_post, only: [:show, :update, :destroy]
+
+  private
+
+  def authenticate_user!
+    head :unauthorized unless current_user
+  end
+
+  def set_post
+    @post = current_user.posts.find(params[:id])
+  end
+end
+```
+
+## NAMING CONVENTIONS
+
+- Controller: Api::ResourcesController or ResourcesController
+- Model: Resource (auto-derived)
+- Parameter: :resource (auto-derived)
+- Instance: @resource (auto-derived)
+
+Examples:
+- Api::UsersController => User model, :user param, @user instance
+- Api::PostsController => Post model, :post param, @post instance
+- Api::CommentsController => Comment model, :comment param, @comment instance
+
+## COMMON PATTERNS
+
+### Nested Resources
+```ruby
+def collection
+  user.posts  # Assumes params[:user_id] or set_user before_action
+end
+```
+
+### Add Query Scopes
+```ruby
+def collection
+  base = super
+  base = base.where(published: true) unless current_user.admin?
+  base
+end
+```
+
+### Custom Error Handling
+```ruby
+rescue_from ActiveRecord::RecordNotFound, with: :not_found
+
+private
+
+def not_found
+  fail message: 'Record not found', code: 404
+end
+```
+
+### Soft Deletes
+```ruby
+def destroy
+  resource.update!(deleted_at: Time.current)
+  ok message: 'Deleted successfully', code: 204
+end
+```
+
+## TESTING
+
+Run the dummy application:
+```bash
+cd test/dummy
+bin/rails db:migrate
+bin/rails db:seed
+bin/rails server
+```
+
+Test API:
+```bash
+curl http://localhost:3000/api/posts
+curl http://localhost:3000/api/posts/1
+curl -X POST http://localhost:3000/api/posts -H 'Content-Type: application/json' -d '{"post":{"title":"Test"}}'
+```
+
+## DEPENDENCIES
+
+- rails >= 6.0
+- kaminari >= 0.16 (pagination)
+- rails_warp >= 0.1.0 (unified responses)
+
+## IMPORTANT NOTES FOR AI ASSISTANTS
+
+1. ALWAYS inherit from RailsCurdBase::CurdController for API controllers
+2. Use supports_query for query configuration (pagination, sorting, searching, filtering)
+3. Use ok() for success responses, fail() for error responses
+4. Resource is auto-derived: controller_name.singularize.classify.constantize
+5. Override collection() to scope data (current_user.posts, etc.)
+6. Use hooks (before_create, after_create, etc.) for callbacks
+7. Parameters via resource_params() method (auto-permits :resource param)
+8. Query parameters: page, size, sort, q, filter[field]
+9. All query features are optional (enable/disable in supports_query)
+10. Filter operators: eq (default), neq, gt, gte, lt, lte, in, nin
+
+## PERFORMANCE TIPS
+
+- Add database indexes on filtered/sorted fields
+- Use select() to limit fields in queries
+- Override serialize_resource for custom JSON output
+- Use caching in hooks for expensive operations
+- Optimize collection() for complex queries
+
+## FILE STRUCTURE
+
+```
+app/controllers/rails_curd_base/
+  curd_controller.rb       # Main controller
+  application_controller.rb
+
+app/controllers/concerns/rails_curd_base/
+  queryable.rb             # Query functionality
+```
+
+## CONTRIBUTE
+
+Contributions welcome! Please:
+- Follow existing code style
+- Add tests for new features
+- Update documentation
+- Submit PR with clear description
+
+## LICENSE
+
+MIT

metadata

@@ -0,0 +1,108 @@
+--- !ruby/object:Gem::Specification
+name: rails_curd_base
+version: !ruby/object:Gem::Version
+  version: 0.1.2
+platform: ruby
+authors:
+- aric.zheng
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-02-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: kaminari
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.16'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.16'
+- !ruby/object:Gem::Dependency
+  name: rails_warp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+description: |
+  RailsCurdBase provides a ready-to-use CRUD base controller for Ruby on Rails API applications.
+  It offers zero-configuration CRUD operations, powerful query capabilities (pagination, sorting,
+  searching, filtering), unified JSON response format via RailsWarp, and flexible lifecycle hooks.
+  Perfect for building RESTful APIs quickly with Rails 6.0+.
+email:
+- 1290657123@qq.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/controllers/concerns/rails_curd_base/queryable.rb
+- app/controllers/rails_curd_base/application_controller.rb
+- app/controllers/rails_curd_base/curd_controller.rb
+- config/routes.rb
+- lib/rails_curd_base.rb
+- lib/rails_curd_base/engine.rb
+- lib/rails_curd_base/version.rb
+- lib/tasks/rails_curd_base_tasks.rake
+- llms.txt
+homepage: https://github.com/aferic/rails_curd_base
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/aferic/rails_curd_base
+  source_code_uri: https://github.com/aferic/rails_curd_base
+  changelog_uri: https://github.com/aferic/rails_curd_base/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/aferic/rails_curd_base/issues
+  documentation_uri: https://github.com/aferic/rails_curd_base/blob/main/README.md
+  wiki_uri: https://github.com/aferic/rails_curd_base/wiki
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: A Rails CRUD base controller with query capabilities, pagination, sorting,
+  searching, and filtering
+test_files: []