Subversion Repositories SmartDukaan

package com.spice.profitmandi.dao.service;

import java.util.List;
import java.util.Map;

/**
 * Read-only Period analytics for the new "Beat Journey" console. Mirrors
 * {@link RouteAnalyticsService} (live cross-schema native SQL) but every query is
 * scoped to a caller-supplied set of user ids so each manager sees only their own
 * downline. The caller resolves the scope (downline → auth_user ids → dtr.users
 * ids via the email bridge) and passes both id sets in.
 *
 * (The "Today / live" payload is assembled in the controller from repositories —
 * it reuses Beat Report's per-user today-assembly rather than duplicating
 * name/beat lookups in SQL.)
 *
 * Identity bridge: planning rows (beat/beat_route/beat_schedule/beat_deferred_visit,
 * cs.position, my_franchisee_visit) key on auth.auth_user.id; execution rows
 * (auth.location_tracking) key on dtr.users.id. No FK exists between them.
 */
public interface BeatJourneyService {

    /**
     * "Period" analytics payload over [startDate, endDate]: KPIs, aggregate funnel,
     * per-executive scorecard, coverage by level, working-hour utilization, deferrals
     * + SLA, travel/route quality, outcomes, and the computed "what to fix" findings.
     *
     * @param startDate range start, 'yyyy-MM-dd'
     * @param endDate   range end (inclusive), 'yyyy-MM-dd'
     * @param today     elapsed boundary for "to-date" comparisons, 'yyyy-MM-dd'
     * @param authIds   in-scope auth_user ids (planning side)
     * @param dtrIds    in-scope dtr.users ids (execution side)
     */
    Map<String, Object> periodAnalytics(String startDate, String endDate, String today,
                                        List<Integer> authIds, List<Integer> dtrIds);
}