Login Register

135dika / analytics_response.md

Last active 1 month ago

Like 0
analytics_response.md Raw

Analytics — Perubahan untuk Tim Frontend

Commit: aca7870 (branch dev). Semua perubahan di tiga layar analytics. Angka desimal sekarang 2 angka di belakang koma (integer ter-render tanpa koma, tipe tetap number).

1. Analytics Action Plan (project)

GET /api/action-plans/projects/:projectId/analytics

Query params

Param Status Nilai Default
layout — detailed | simplified detailed
granularity — daily | weekly | monthly weekly
percentage_by BARU work_weight | completion_of_work | duration_day work_weight
search, activityName, startDate, endDate — sama seperti sebelumnya —

Response

  • BARU echo data.percentageBy (camelCase di layar project).
  • Semua angka (cards, tabular, s-curve) kini round 2 desimal (sebelumnya 3).

Semantik percentage_by

Mode Cara hitung
work_weight Rupiah workWeight sebagai bobot — leaf workWeight kosong/0 tetap tidak dihitung (perilaku lama)
completion_of_work Semua leaf bobot sama (1) — murni rata-rata % progress
duration_day Bobot = jumlah hari startDate→endDate (ceil, min. 1 hari) — leaf tanpa tanggal tidak dihitung

Leaf dengan workWeight kosong tapi startDate+endDate terisi = work berbasis durasi/timeline (penanda: weight 0/kosong). Data workWeight tidak di-unpack dari durasi — hitungannya derived on-the-fly di backend.

2. Analytics Agenda

GET /api/agendas/:agendaId/analytics

Query params

Param Status Nilai Default
granularity DIUBAH hanya weekly | monthly (⚡ daily dihapus → 400) weekly
start_date, end_date — RFC date string, snake_case tanpa batas
project_type BARU all | self_managed | consultant all
percentage_by BARU work_weight | completion_of_work | duration_day work_weight
program_name BARU string; mempersempit SELURUH report (cards + curve + tabel) ke program yang cocok —
activity_name BARU string; khusus memfilter data.action_plan_tabular saja —
q DIHAPUS → diganti activity_name / program_name —

Response

data: {
  "scope": { "id": "...", "name": "...", "type": "agenda" },
  "percentage_by": "work_weight",   // 🆕 echo (camelCase island ada di project analytics)
  "project_type": "all",            // 🆕 echo
  "overview": { "total_children", "total_action_plan", "total_plan", "total_realization", "overall_deviation" },
  "s_curve": { "granularity": "weekly", "plan": [...], "realization": [...] },
  "tabular": {
    "unit": "program",
    "total": { "plan", "realization", "deviation" },
    "rows": [                          // ⚠️ SEMANTIK BARU: lihat §4
      { "id", "name", "plan", "realization", "deviation", "total_action_plan" }
    ]
  },
  "action_plan_tabular": [             // 🆕 KHUSUS agenda (undefined di program)
    {
      "name": "Pondasi",
      "plan": 25.2, "realization": 18.3, "deviation": -6.9,
      "total_action_plan": 22,
      "tasks": [ { "name", "plan", "realization", "deviation", "total_action_plan" } ]
    }
  ]
}
  • action_plan_tabular = action plan 2 level (activity → task), sama seperti tabular di analytics action plan. activity_name hanya memfilter tabel ini; activity yang match membawa semua task-nya.
  • tabular.total / overview = weighted mean 0–100 seluruh node; action_plan_tabular tidak punya baris Total — Total-nya itu (overview.total_plan dst.), jangan cari di dalam tabel.

3. Analytics Program

GET /api/programs/:programId/analytics

Sama seperti agenda, dengan perbedaan:

Perbedaan Nilai
Filter nama project_name (whole-report) menggantikan program_name
Tabular 1 baris per project (unit: "project") — seperti sebelumnya
action_plan_tabular tidak ada (dan activity_name tidak berlaku)

granularity=weekly|monthly (serupa agenda, daily dihapus), start_date/end_date, project_type, percentage_by sama.

4. ⚠️ Perubahan semantik tabular (BREAKING)

Tabular agenda & program sekarang PRORATA (kontribusi), seperti tabular project-tier:

  • Sebelumnya: tiap baris = weighted mean 0–100 leaves program/project itu sendiri (Σ baris bisa melebihi 100).
  • Sekarang: tiap baris = share kontribusi terhadap total node (bobot baris ÷ total bobot seluruh node). Σ baris = total, tidak akan lebih dari 100 — mengakumulasi kumulatif aman.
  • deviation tetap dihitung dari operand RAW lalu di-round.
  • Baris child tanpa action plan → plan/realization/deviation = null (bukan 0).

Jika layar lama menganggap row plan sebagai progress 0–100 child, harus disesuaikan (atau render share).

Contoh

Node dengan 2 program masing-masing leaf 100% : baris kini 50 / 50 (bukan 100 / 100), dan total = 100.

5. Ringkasan breaking changes

  1. q pada agenda/program analytics dihapus → pakai activity_name (agenda) / program_name (agenda) / project_name (program).
  2. granularity=daily di agenda/program → sekarang 400. Gunakan weekly|monthly.
  3. Nilai tabular.rows agenda/program berubah makna (kontribusi, bukan 0–100).
  4. Semua angka rounded 2 desimal (sebelumnya 3).
  5. Echo baru: data.percentageBy (project tier), data.percentage_by + data.project_type (agenda/program).
  6. Field baru: data.action_plan_tabular (agenda).

6. Referensi

  • Contoh payload lengkap per endpoint: .markdown/ANALYTICS_RESPONSE_SHAPES.md
  • Query params ditulis snake_case di agenda/program (start_date, percentage_by, project_type) dan camelCase di project analytics (startDate, percentage_by→percentage_by snake juga tapi activityName/search camelCase) — perhatikan beda konvensi antar endpoint.