Land & Expand — 小さく入って大きく育てる

# db/migrate/20260628_create_customer_health_scores.rb
class CreateCustomerHealthScores < ActiveRecord::Migration[7.2]
  def change
    create_table :customer_health_scores do |t|
      t.references :customer, null: false, foreign_key: true
      t.integer :overall_score, null: false, default: 0
      t.integer :usage_score, null: false, default: 0
      t.integer :engagement_score, null: false, default: 0
      t.integer :support_score, null: false, default: 0
      t.integer :expansion_potential, null: false, default: 0
      t.string :health_status, null: false, default: "neutral"
      t.jsonb :score_breakdown, null: false, default: {}
      t.jsonb :expansion_signals, null: false, default: []
      t.date :scored_on, null: false
      t.timestamps
    end
 
    add_index :customer_health_scores, %i[customer_id scored_on], unique: true
    add_index :customer_health_scores, :health_status
    add_index :customer_health_scores, :expansion_potential
  end
end

# app/models/customer_health_score.rb
class CustomerHealthScore < ApplicationRecord
  belongs_to :customer
 
  HEALTH_STATUSES = %w[critical at_risk neutral healthy thriving].freeze
 
  validates :health_status, inclusion: { in: HEALTH_STATUSES }
  validates :overall_score, :usage_score, :engagement_score,
            :support_score, :expansion_potential,
            inclusion: { in: 0..100 }
 
  scope :latest, -> { order(scored_on: :desc).limit(1) }
  scope :thriving, -> { where(health_status: "thriving") }
  scope :high_expansion, -> { where("expansion_potential >= ?", 70) }
 
  def expansion_ready?
    health_status.in?(%w[healthy thriving]) && expansion_potential >= 60
  end
 
  def risk?
    health_status.in?(%w[critical at_risk])
  end
end

# app/services/health_score_calculator.rb
class HealthScoreCalculator
  WEIGHTS = { usage: 0.35, engagement: 0.30, support: 0.20, expansion: 0.15 }.freeze
 
  def initialize(customer)
    @customer = customer
    @period = 30.days.ago..Time.current
  end
 
  def calculate
    scores = {
      usage_score: calculate_usage_score,
      engagement_score: calculate_engagement_score,
      support_score: calculate_support_score,
      expansion_potential: calculate_expansion_potential
    }
 
    overall = WEIGHTS.sum { |key, weight| scores[:"#{key}_score"] || scores[:"#{key}"] || 0 * weight }
    overall = (scores[:usage_score] * WEIGHTS[:usage] +
               scores[:engagement_score] * WEIGHTS[:engagement] +
               scores[:support_score] * WEIGHTS[:support] +
               scores[:expansion_potential] * WEIGHTS[:expansion]).round
 
    CustomerHealthScore.create!(
      customer: @customer, overall_score: overall,
      health_status: determine_status(overall),
      expansion_signals: ExpansionSignalDetector.new(@customer, @period).detect,
      scored_on: Date.current, **scores
    )
  end
 
  private
 
  def calculate_usage_score
    metrics = @customer.api_usage_metrics.where(recorded_at: @period)
    return 0 if metrics.empty?
 
    utilization = (metrics.average(:request_count).to_f /
                   @customer.plan.daily_api_limit.to_f * 100).clamp(0, 100)
 
    case utilization
    when 70..100 then 90
    when 40..69 then 70
    when 20..39 then 50
    else 20
    end
  end
 
  def calculate_engagement_score
    active = @customer.users.where(last_active_at: @period).count
    total = @customer.users.count
    return 0 if total.zero?
 
    adoption = (active.to_f / total * 100).round
    used = @customer.feature_usages.where(used_at: @period).distinct.count(:feature_name)
    available = Feature.available_for(@customer.plan).count
    breadth = available.positive? ? (used.to_f / available * 100).round : 0
 
    [adoption * 0.5 + breadth * 0.5, 100].min.round
  end
 
  def calculate_support_score
    tickets = @customer.support_tickets.where(created_at: @period)
    return 85 if tickets.empty?
 
    resolved = tickets.where(status: "resolved").count
    critical = tickets.where(severity: "critical").count
    rate = tickets.count.positive? ? (resolved.to_f / tickets.count * 100) : 100
 
    [rate - critical * 10, 0].max.round
  end
 
  def calculate_expansion_potential
    signals = ExpansionSignalDetector.new(@customer, @period).detect
    signal_score = [signals.length * 15, 60].min
 
    utilization = ((@customer.api_usage_metrics.where(recorded_at: @period)
                    .average(:request_count).to_f /
                    @customer.plan.daily_api_limit.to_f) * 100).clamp(0, 100)
    growth_bonus = utilization > 80 ? 30 : 0
 
    renewal_bonus = @customer.current_contract&.ends_at&.< (90.days.from_now) ? 10 : 0
 
    [signal_score + growth_bonus + renewal_bonus, 100].min
  end
 
  def determine_status(score)
    case score
    when 80..100 then "thriving"
    when 60..79 then "healthy"
    when 40..59 then "neutral"
    when 20..39 then "at_risk"
    else "critical"
    end
  end
end

# app/services/expansion_signal_detector.rb
class ExpansionSignalDetector
  Signal = Data.define(:type, :severity, :description, :detected_at, :metadata)
 
  def initialize(customer, period = 30.days.ago..Time.current)
    @customer = customer
    @period = period
    @signals = []
  end
 
  def detect
    check_rate_limit_proximity
    check_new_access_sources
    check_feature_exploration
    check_usage_growth_trend
 
    @signals.sort_by { |s| %w[low medium high].index(s.severity) }.reverse
  end
 
  private
 
  def check_rate_limit_proximity
    recent = @customer.api_usage_metrics.where(recorded_at: @period)
                      .order(recorded_at: :desc).limit(7)
    return if recent.empty?
 
    limit = @customer.plan.daily_api_limit
    days_over = recent.count { |m| m.request_count > limit * 0.8 }
    return unless days_over >= 3
 
    @signals << Signal.new(
      type: "rate_limit_proximity", severity: "high",
      description: "過去7日間で#{days_over}日がAPIレート制限の80%を超過",
      detected_at: Time.current,
      metadata: { plan_limit: limit, peak_usage: recent.maximum(:request_count) }
    )
  end
 
  def check_new_access_sources
    recent_ips = @customer.access_logs.where(accessed_at: @period).distinct.pluck(:ip_address)
    previous_ips = @customer.access_logs
                            .where(accessed_at: 60.days.ago..@period.first)
                            .distinct.pluck(:ip_address)
    new_ips = recent_ips - previous_ips
    return unless new_ips.size >= 3
 
    @signals << Signal.new(
      type: "new_access_sources", severity: "medium",
      description: "#{new_ips.size}個の新しいIPアドレスからアクセスを検出（新部門の可能性）",
      detected_at: Time.current,
      metadata: { new_ip_count: new_ips.size }
    )
  end
 
  def check_feature_exploration
    premium = Feature.premium_only.pluck(:name)
    explored = @customer.feature_access_attempts
                        .where(attempted_at: @period, feature_name: premium)
                        .distinct.pluck(:feature_name)
    return if explored.empty?
 
    @signals << Signal.new(
      type: "feature_exploration", severity: "high",
      description: "上位プラン機能 #{explored.join(', ')} へのアクセス試行を検出",
      detected_at: Time.current,
      metadata: { explored_features: explored }
    )
  end
 
  def check_usage_growth_trend
    current = @customer.api_usage_metrics.where(recorded_at: 30.days.ago..Time.current).sum(:request_count)
    previous = @customer.api_usage_metrics.where(recorded_at: 60.days.ago..30.days.ago).sum(:request_count)
    return if previous.zero?
 
    growth = ((current - previous).to_f / previous * 100).round
    return unless growth >= 50
 
    @signals << Signal.new(
      type: "usage_growth", severity: growth >= 100 ? "high" : "medium",
      description: "API利用量が前月比 +#{growth}% で成長中",
      detected_at: Time.current,
      metadata: { growth_rate: growth, current: current, previous: previous }
    )
  end
end

# app/controllers/api/v1/customer_health_controller.rb
module Api
  module V1
    class CustomerHealthController < ApplicationController
      before_action :authenticate_api_key!
      before_action :set_customer, only: :show
 
      # GET /api/v1/customers/:customer_id/health
      def show
        score = @customer.customer_health_scores.latest.first
        return render json: { error: "ヘルススコアが未計算です" }, status: :not_found unless score
 
        render json: {
          customer_id: @customer.id, customer_name: @customer.name,
          scored_on: score.scored_on, overall_score: score.overall_score,
          health_status: score.health_status,
          scores: { usage: score.usage_score, engagement: score.engagement_score,
                    support: score.support_score, expansion_potential: score.expansion_potential },
          expansion_ready: score.expansion_ready?,
          signals: score.expansion_signals
        }
      end
 
      # GET /api/v1/customers/expansion_opportunities
      def expansion_opportunities
        opportunities = CustomerHealthScore
          .where(scored_on: Date.current).high_expansion
          .joins(:customer).order(expansion_potential: :desc).limit(20)
 
        render json: {
          date: Date.current, count: opportunities.size,
          opportunities: opportunities.map { |s|
            { customer_id: s.customer_id, customer_name: s.customer.name,
              expansion_potential: s.expansion_potential, signals: s.expansion_signals,
              current_plan: s.customer.plan.name, mrr: s.customer.current_mrr }
          }
        }
      end
 
      private
 
      def set_customer
        @customer = Customer.find(params[:customer_id])
      rescue ActiveRecord::RecordNotFound
        render json: { error: "顧客が見つかりません" }, status: :not_found
      end
    end
  end
end

# app/services/usage_metrics_publisher.rb
class UsageMetricsPublisher
  def initialize
    @cloudwatch = Aws::CloudWatch::Client.new(region: "ap-northeast-1")
    @namespace = "ArclightAI/CustomerUsage"
  end
 
  def publish_api_usage(customer_id:, request_count:, plan_limit:)
    utilization = (request_count.to_f / plan_limit * 100).round(2)
    dims = [{ name: "CustomerId", value: customer_id.to_s }]
 
    @cloudwatch.put_metric_data(
      namespace: @namespace,
      metric_data: [
        { metric_name: "ApiRequestCount", dimensions: dims,
          timestamp: Time.current, value: request_count, unit: "Count" },
        { metric_name: "PlanUtilization", dimensions: dims,
          timestamp: Time.current, value: utilization, unit: "Percent" }
      ]
    )
  end
end

# lib/tasks/setup_alarms.rake
namespace :cloudwatch do
  desc "高利用率顧客向けアラームを設定"
  task setup_expansion_alarms: :environment do
    cloudwatch = Aws::CloudWatch::Client.new(region: "ap-northeast-1")
    sns_arn = ENV.fetch("EXPANSION_ALERT_SNS_ARN")
 
    Customer.active.find_each do |customer|
      cloudwatch.put_metric_alarm(
        alarm_name: "HighUtilization-#{customer.id}",
        namespace: "ArclightAI/CustomerUsage",
        metric_name: "PlanUtilization",
        dimensions: [{ name: "CustomerId", value: customer.id.to_s }],
        statistic: "Average", period: 3600, evaluation_periods: 6,
        threshold: 80.0, comparison_operator: "GreaterThanOrEqualToThreshold",
        alarm_description: "#{customer.name}のAPI利用率が80%を超過",
        alarm_actions: [sns_arn], treat_missing_data: "notBreaching"
      )
    end
 
    puts "全アクティブ顧客のアラームを設定完了"
  end
end