thatcher 1.0.85 → 1.0.87

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thatcher",
-  "version": "1.0.85",
+  "version": "1.0.87",
   "description": "A config-driven application framework for building data-intensive web apps without code.",
   "main": "src/index.js",
   "type": "module",

package/src/lib/demand-forecast.js

@@ -0,0 +1,58 @@
+// Single source of truth for CRM demand-planning math, shared with any
+// future forecast summary view -- the same small pure-computation module
+// shape as contract-expiry.js and inventory-forecast.js. Forward-looking
+// (open pipeline -> future revenue), the mirror image of
+// inventory-forecast.js's backward-looking (movement history -> stockout).
+const OPEN_STAGE_EXCLUSIONS = new Set(['won', 'lost']);
+
+function monthBucketKey(dateSeconds) {
+  const d = new Date(dateSeconds * 1000);
+  return `${d.getUTCFullYear()}-${String(d.getUTCMonth() + 1).padStart(2, '0')}`;
+}
+
+// The stage field alone decides "still open" -- not the presence of a
+// weighted_value or any date math, so a caller can't accidentally count a
+// won/lost opportunity by omission.
+function isOpenStage(opportunity) {
+  return !OPEN_STAGE_EXCLUSIONS.has(opportunity.stage);
+}
+
+// A record already carries weighted_value if it passed through
+// busybase/store.js's list()/get() (which now computes formula fields on
+// every read) -- reused directly rather than recomputed, so this module
+// never drifts from the same formula the opportunity entity itself defines.
+// Falls back to computing value*probability/100 independently only if the
+// field is genuinely absent (e.g. a deployment whose opportunity entity
+// doesn't define weighted_value), never silently treating a present-but-null
+// value as "compute it myself" -- null still means the formula ran and
+// legitimately produced nothing.
+function weightedValueOf(opportunity) {
+  if (opportunity.weighted_value !== undefined) return opportunity.weighted_value ?? 0;
+  const value = Number(opportunity.value) || 0;
+  const probability = Number(opportunity.probability) || 0;
+  return (value * probability) / 100;
+}
+
+export function projectDemandByMonth(opportunities, nowSeconds = Math.floor(Date.now() / 1000)) {
+  const currentBucketKey = monthBucketKey(nowSeconds);
+  const buckets = new Map();
+
+  for (const opp of opportunities) {
+    if (!isOpenStage(opp)) continue;
+    if (opp.expected_close_date == null) continue;
+
+    const bucketKey = monthBucketKey(Number(opp.expected_close_date));
+    // A future bucket sorts >= the current month's key lexicographically
+    // (YYYY-MM strings compare correctly as dates); a past-due open
+    // opportunity's bucket key is strictly less than the current one and is
+    // excluded entirely rather than folded into the nearest future bucket --
+    // silently reassigning it would misrepresent when the demand was
+    // actually expected.
+    if (bucketKey < currentBucketKey) continue;
+
+    const weighted = weightedValueOf(opp);
+    buckets.set(bucketKey, (buckets.get(bucketKey) || 0) + weighted);
+  }
+
+  return [...buckets.entries()].sort((a, b) => a[0].localeCompare(b[0]));
+}

package/src/lib/resource-capacity.js

@@ -0,0 +1,28 @@
+// Single source of truth for resource-allocation load math, extracted from
+// entity-validators.js's checkResourceCapacity so the over-allocation
+// PREVENTION check and the resource-optimizer's SUGGESTION ranking compute a
+// user's committed load identically -- two independently-maintained copies
+// of the same overlap/sum formula would inevitably drift.
+export const DEFAULT_WEEKLY_CAPACITY_HOURS = 40;
+
+// Two date ranges overlap unless one entirely precedes the other -- the
+// standard interval-intersection test, not a same-day/exact-match check.
+export function rangesOverlap(startA, endA, startB, endB) {
+  return Number(startA) <= Number(endB) && Number(startB) <= Number(endA);
+}
+
+// Sum of allocated_hours_per_week across every existing allocation for
+// userId whose date range overlaps [startDate, endDate], excluding
+// excludeAllocationId (the record being updated, if any, so it doesn't
+// double-count itself). Reads via list('resource_allocation', {user_id}),
+// the same unscoped-internal lookup pattern every other entity-specific
+// check this session (checkStockBalance/checkContractDateOrder) already
+// uses -- no user context threaded through this layer.
+export async function userCommittedHours(userId, startDate, endDate, excludeAllocationId = null) {
+  const { list } = await import('./busybase/store.js');
+  const existingAllocations = await list('resource_allocation', { user_id: userId });
+  const overlapping = existingAllocations.filter(a =>
+    a.id !== excludeAllocationId && rangesOverlap(startDate, endDate, a.start_date, a.end_date)
+  );
+  return overlapping.reduce((sum, a) => sum + (Number(a.allocated_hours_per_week) || 0), 0);
+}

package/src/lib/resource-optimizer.js

@@ -0,0 +1,20 @@
+import { userCommittedHours, DEFAULT_WEEKLY_CAPACITY_HOURS } from './resource-capacity.js';
+
+// Ranks a pool of REAL users (queried from the user list, never an arbitrary
+// id range) by remaining weekly capacity in the given date range, using the
+// exact same overlap-based load calculation checkResourceCapacity already
+// enforces -- so a "best fit" suggestion and the prevention check it feeds
+// into can never disagree about how loaded a candidate actually is.
+// Excludes anyone already at or over capacity entirely (not just ranked
+// last), since they are not a valid suggestion regardless of rank.
+export async function suggestBestFitUsers(candidateUserIds, startDate, endDate, hoursNeeded, capacityHours = DEFAULT_WEEKLY_CAPACITY_HOURS) {
+  const results = [];
+  for (const userId of candidateUserIds) {
+    const committedHours = await userCommittedHours(userId, startDate, endDate);
+    const remainingCapacity = capacityHours - committedHours;
+    if (remainingCapacity < hoursNeeded) continue;
+    results.push({ user_id: userId, committed_hours: committedHours, remaining_capacity: remainingCapacity });
+  }
+  results.sort((a, b) => b.remaining_capacity - a.remaining_capacity);
+  return results;
+}

package/src/lib/validation/entity-validators.js

@@ -303,19 +303,14 @@ async function checkCrossEntityRules(entityName, data, existingRecord) {
   return null;
 }
 
-const WEEKLY_CAPACITY_HOURS = 40;
-
-// Two date ranges overlap unless one entirely precedes the other -- the
-// standard interval-intersection test, not a same-day/exact-match check.
-function rangesOverlap(startA, endA, startB, endB) {
-  return Number(startA) <= Number(endB) && Number(startB) <= Number(endA);
-}
-
 // A user's total weekly allocation across every project they're assigned to,
 // for any date range that overlaps the new/changed allocation, must not
 // exceed a configurable weekly capacity. Checked against EVERY OTHER
 // existing allocation for that user (excluding the record being updated, if
-// any) plus the new one -- never trusting a client-supplied total.
+// any) plus the new one -- never trusting a client-supplied total. The
+// overlap/load math itself lives in resource-capacity.js, shared with
+// resource-optimizer.js's suggestion ranking so both compute a user's
+// committed load identically.
 async function checkResourceCapacity(entityName, data, existingRecord) {
   if (entityName !== 'resource_allocation') return null;
   const userId = data.user_id !== undefined ? data.user_id : existingRecord?.user_id;
@@ -324,15 +319,11 @@ async function checkResourceCapacity(entityName, data, existingRecord) {
   const hours = Number(data.allocated_hours_per_week !== undefined ? data.allocated_hours_per_week : existingRecord?.allocated_hours_per_week);
   if (!userId || startDate == null || endDate == null || !Number.isFinite(hours)) return null;
 
-  const { list } = await import('@/lib/busybase/store');
-  const existingAllocations = await list('resource_allocation', { user_id: userId });
-  const overlapping = existingAllocations.filter(a =>
-    a.id !== existingRecord?.id && rangesOverlap(startDate, endDate, a.start_date, a.end_date)
-  );
-  const overlappingTotal = overlapping.reduce((sum, a) => sum + (Number(a.allocated_hours_per_week) || 0), 0);
+  const { userCommittedHours, DEFAULT_WEEKLY_CAPACITY_HOURS } = await import('@/lib/resource-capacity');
+  const overlappingTotal = await userCommittedHours(userId, startDate, endDate, existingRecord?.id);
   const resultingTotal = overlappingTotal + hours;
-  if (resultingTotal > WEEKLY_CAPACITY_HOURS) {
-    return `Over-allocated: this would bring the user's weekly total to ${resultingTotal}h against overlapping allocations, exceeding the ${WEEKLY_CAPACITY_HOURS}h capacity`;
+  if (resultingTotal > DEFAULT_WEEKLY_CAPACITY_HOURS) {
+    return `Over-allocated: this would bring the user's weekly total to ${resultingTotal}h against overlapping allocations, exceeding the ${DEFAULT_WEEKLY_CAPACITY_HOURS}h capacity`;
   }
   return null;
 }

package/src/server/server.js

@@ -151,6 +151,10 @@ export function createServer(options) {
           return await handleChangesSince(req, res, parts[1], parts[2], parts[4]);
         }
 
+        if (req.method === 'GET' && entity === 'resource-optimizer' && id === 'suggest') {
+          return await handleResourceOptimizerSuggest(req, res);
+        }
+
         if (req.method === 'GET' && entity === 'auth' && id === 'google' && !action) {
           return await handleOAuthGoogleStart(req, res);
         }
@@ -1589,6 +1593,46 @@ async function handlePresenceHeartbeat(req, res, entityName, id) {
   res.end(JSON.stringify({ ok: true }));
 }
 
+async function handleResourceOptimizerSuggest(req, res) {
+  const user = await resolveRequestUser(req);
+  if (!user) {
+    res.writeHead(401, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Authentication required' }));
+    return;
+  }
+
+  const url = new URL(req.url, `http://${req.headers.host}`);
+  const startDate = Number(url.searchParams.get('start_date'));
+  const endDate = Number(url.searchParams.get('end_date'));
+  const hoursNeeded = Number(url.searchParams.get('hours_needed'));
+  if (!Number.isFinite(startDate) || !Number.isFinite(endDate) || !Number.isFinite(hoursNeeded)) {
+    res.writeHead(400, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'start_date, end_date, and hours_needed are required numeric query params' }));
+    return;
+  }
+
+  // Self-only unless partner/manager -- the SAME privilege boundary
+  // resource_allocation's own checkTimeEntryOwnership-derived ownership
+  // check already enforces on write. A non-privileged caller asking for
+  // suggestions must not learn how loaded ANY other user is (that leaks
+  // workload/capacity across the org), so their candidate pool is
+  // themselves alone rather than filtered results from a broader query.
+  const isPrivileged = ['partner', 'admin', 'manager'].includes(user.role);
+  let candidateUserIds;
+  if (isPrivileged) {
+    const { list } = await import('../lib/busybase/store.js');
+    const users = await list('user', {});
+    candidateUserIds = users.map(u => u.id);
+  } else {
+    candidateUserIds = [user.id];
+  }
+
+  const { suggestBestFitUsers } = await import('../lib/resource-optimizer.js');
+  const suggestions = await suggestBestFitUsers(candidateUserIds, startDate, endDate, hoursNeeded);
+  res.writeHead(200, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify({ suggestions }));
+}
+
 async function handlePresenceGet(req, res, entityName, id) {
   const user = await verifyRecordAccess(req, res, entityName, id);
   if (!user) return;

package/src/ui/entity-renderer.js

@@ -315,7 +315,10 @@ export function renderEntityForm(entityName, item, spec, user, isNew = false, re
     }
     if (f.type === 'ref' && refOptions[k]) {
       const opts = refOptions[k].map(o => `<option value="${esc(o.value)}" ${val===o.value?'selected':''}>${esc(o.label)}</option>`).join('')
-      return `<div class="form-field">${lbl(k,f,f.required)}<select id="field-${k}" name="${k}" class="form-input" ${req}><option value="">Select ${esc(f.label||k)}...</option>${opts}</select></div>`
+      const suggestBtn = entityName === 'resource_allocation' && k === 'user_id'
+        ? `<button type="button" class="btn-ghost-clean" style="margin-top:4px" data-action="suggestBestFitUser">Suggest best-fit user</button>`
+        : ''
+      return `<div class="form-field">${lbl(k,f,f.required)}<select id="field-${k}" name="${k}" class="form-input" ${req}><option value="">Select ${esc(f.label||k)}...</option>${opts}</select>${suggestBtn}</div>`
     }
     if (f.type === 'textarea') return `<div class="form-field full">${lbl(k,f,f.required)}<textarea id="field-${k}" name="${k}" class="form-input" style="min-height:100px;resize:vertical" ${req} placeholder="Enter ${esc((f.label||k).toLowerCase())}">${esc(val)}</textarea></div>`
     if (f.type === 'bool') return `<div class="form-field"><label style="display:flex;align-items:center;gap:8px;cursor:pointer"><input type="checkbox" id="field-${k}" name="${k}" class="checkbox checkbox-primary" ${val?'checked':''}/><span class="form-label" style="margin:0">${esc(f.label||k)}</span></label></div>`
@@ -361,7 +364,10 @@ export function renderEntityForm(entityName, item, spec, user, isNew = false, re
     <div class="form-actions" style="grid-column:1/-1"><button type="submit" id="submit-btn" class="btn-primary-clean"><span class="btn-text">Save</span><span class="btn-loading-text" style="display:none">Saving...</span></button>
     <a href="/${entityName}${isNew ? '' : '/' + item?.id}" class="btn-ghost-clean">Cancel</a></div></form></div></div>`
   const script = `${TOAST_SCRIPT}const form=document.getElementById('entity-form');const sb=document.getElementById('submit-btn');form.addEventListener('submit',async(e)=>{e.preventDefault();sb.classList.add('btn-loading');sb.querySelector('.btn-text').style.display='none';sb.querySelector('.btn-loading-text').style.display='inline';sb.disabled=true;try{const fileInputs=[...form.querySelectorAll('input[type=file][data-attachment]')];for(const fi of fileInputs){const f=fi.files&&fi.files[0];if(!f)continue;const uf=new FormData();uf.append('file',f);const ures=await fetch('/api/upload',{method:'POST',body:uf});const ud=await ures.json();if(!ures.ok)throw new Error(ud.error||'File upload failed');const hidden=document.getElementById('field-'+fi.dataset.attachment+'-value');hidden.value=JSON.stringify(ud)}const fd=new FormData(form);const data={};for(const[k,v]of fd.entries()){if(k.endsWith('[]'))continue;data[k]=v}form.querySelectorAll('input[type=checkbox]:not([name$="[]"])').forEach(cb=>{data[cb.name]=cb.checked});form.querySelectorAll('[data-multiselect]').forEach(ms=>{const name=ms.dataset.multiselect;data[name]=[...ms.querySelectorAll('input[type=checkbox]:checked')].map(cb=>cb.value)});form.querySelectorAll('input[type=number]:not([data-currency])').forEach(inp=>{if(inp.name&&data[inp.name]!==undefined&&data[inp.name]!=='')data[inp.name]=Number(data[inp.name])});form.querySelectorAll('input[data-currency]').forEach(inp=>{const name=inp.dataset.currency;if(inp.value!=='')data[name]=Math.round(Number(inp.value)*100)});const url=${isNew}?'/api/${entityName}':'/api/${entityName}/${item?.id}';const method=${isNew}?'POST':'PUT';const res=await fetch(url,{method,headers:{'Content-Type':'application/json'},body:JSON.stringify(data)});const result=await res.json();if(res.ok){showToast('${isNew?'Created':'Updated'} successfully!','success');const ed=result.data||result;setTimeout(()=>{window.location='/${entityName}/'+(ed.id||'${item?.id}')},500)}else{showToast(result.message||result.error||'Save failed','error');sb.classList.remove('btn-loading');sb.querySelector('.btn-text').style.display='inline';sb.querySelector('.btn-loading-text').style.display='none';sb.disabled=false}}catch(err){showToast('Error: '+err.message,'error');sb.classList.remove('btn-loading');sb.querySelector('.btn-text').style.display='inline';sb.querySelector('.btn-loading-text').style.display='none';sb.disabled=false}})`
-  return page(user, `${isNew ? 'Create' : 'Edit'} ${label}`, bc, content, [script])
+  const suggestScript = entityName === 'resource_allocation'
+    ? `window.suggestBestFitUser=async function(){const start=document.getElementById('field-start_date');const end=document.getElementById('field-end_date');const hours=document.getElementById('field-allocated_hours_per_week');if(!start.value||!end.value||!hours.value){showToast('Fill in start date, end date, and hours first','error');return}const startTs=Math.floor(new Date(start.value).getTime()/1000);const endTs=Math.floor(new Date(end.value).getTime()/1000);try{const res=await fetch('/api/resource-optimizer/suggest?start_date='+startTs+'&end_date='+endTs+'&hours_needed='+encodeURIComponent(hours.value));const data=await res.json();if(!res.ok){showToast(data.error||'Suggestion failed','error');return}if(!data.suggestions||!data.suggestions.length){showToast('No user has enough remaining capacity','warning');return}const top=data.suggestions[0];const select=document.getElementById('field-user_id');if(select){select.value=top.user_id;showToast('Suggested user selected ('+top.remaining_capacity+'h remaining capacity)','success')}}catch(err){showToast('Error: '+err.message,'error')}}`
+    : ''
+  return page(user, `${isNew ? 'Create' : 'Edit'} ${label}`, bc, content, [script, suggestScript])
 }
 
 export function renderSettings(user, config = {}) {

package/src/ui/page-handler.js

@@ -9,7 +9,7 @@ import { renderEngagementGrid } from '@/ui/engagement-grid-renderer.js';
 import { renderBoardView } from '@/ui/board-view-renderer.js';
 import { renderGridView } from '@/ui/grid-view-renderer.js';
 import { renderCalendarView, renderTimelineView } from '@/ui/calendar-view-renderer.js';
-import { renderCountByFieldReport, renderCountOverTimeReport, renderSumByFieldReport, renderRollupReport, renderInventoryForecastReport } from '@/ui/report-renderer.js';
+import { renderCountByFieldReport, renderCountOverTimeReport, renderSumByFieldReport, renderRollupReport, renderInventoryForecastReport, renderDemandForecastReport } from '@/ui/report-renderer.js';
 import { renderClientProgress } from '@/ui/client-progress-renderer.js';
 import { renderLetterWorkflow } from '@/ui/letter-workflow-renderer.js';
 import { renderAdvancedSearch } from '@/ui/advanced-search-renderer.js';
@@ -392,6 +392,16 @@ export async function handlePage(pathname, req, res) {
       }
       return renderInventoryForecastReport(user, spec, forecastRows);
     }
+    if (report === 'demand-forecast' && entityName === 'opportunity') {
+      // items is already the {user}-scoped opportunity list fetched at the
+      // top of this route (same list(entityName,{},{user}) every other
+      // entity route uses) -- no new unscoped query, and each item already
+      // carries a computed weighted_value from list()'s own formula-field
+      // pass, reused directly rather than recomputed.
+      const { projectDemandByMonth } = await import('@/lib/demand-forecast.js');
+      const buckets = projectDemandByMonth(items);
+      return renderDemandForecastReport(user, spec, buckets, items.length);
+    }
     const view = params.get('view');
     if (view === 'board') return renderBoardView(user, entityName, spec, items);
     if (view === 'grid') return renderGridView(user, entityName, spec, items);

package/src/ui/report-renderer.js

@@ -237,3 +237,23 @@ export function renderInventoryForecastReport(user, spec, forecastRows) {
     </table></div>`;
   return page(user, `Inventory Forecast | Thatcher`, null, content);
 }
+
+// Reuses sumBarChart (already built for sum-by-field's currency-aware bar
+// rendering) rather than inventing a third chart type -- a demand-by-month
+// bucket is the exact same [label, numericValue] shape sum-by-field already
+// renders, just currency-formatted since weighted_value derives from a
+// currency field.
+export function renderDemandForecastReport(user, spec, buckets, totalOpportunities) {
+  const label = getEntityLabel(spec, true) || 'Opportunities';
+  const valueFieldDef = spec.fields?.value || { type: 'currency' };
+  const totalProjected = buckets.reduce((sum, [, v]) => sum + v, 0);
+  const notice = !buckets.length
+    ? `<div class="report-notice">No open opportunities with a future expected close date</div>`
+    : '';
+  const content = `<div class="page-header">
+      <div><h1 class="page-title">${esc(label)}: Demand Forecast</h1><p class="page-subtitle">${totalOpportunities} total opportunities, ${esc(formatSumValue(totalProjected, valueFieldDef))} projected across ${buckets.length} future month${buckets.length === 1 ? '' : 's'}</p></div>
+    </div>
+    ${notice}
+    ${sumBarChart(buckets, valueFieldDef)}`;
+  return page(user, `Demand Forecast | Thatcher`, null, content);
+}