# Contractor Settings

**Date:** 2026-05-31  
**Status:** Draft  
**Spec:** 148  
**Tier:** All tiers  
**Depends on:** `contractor-payouts`, `contractor-portal`, `time-approval-workflow`, `foundation-auth-rbac`  
**Referenced by:** `contractor-payouts`, `contractor-portal`

---

## Overview

Spec 21 (`contractor-payouts`) defines the contractors and contractor_assignments tables. Spec 87 (`contractor-portal`) defines the portal view. Spec 52 (`time-approval-workflow`) defines the approval flow. No spec defines a `/settings/contractors` page for configuring contractor defaults, portal access rules, and approval policies. This spec fills that gap.

---

## Route

`/settings/contractors` — requires `payouts:write`.

---

## Page Layout

```
┌──────────────────────────────────────────────────────────────┐
│  Settings > Contractors                                      │
│                                                              │
│  ┌── Portal Access ──────────────────────────────────────┐  │
│  │                                                        │  │
│  │  Enable contractor portal                             │  │
│  │  ● Enabled  ○ Disabled                                │  │
│  │  (Business+: portal at /contractor-portal/)           │  │
│  │                                                        │  │
│  │  Contractors can see:                                  │  │
│  │  ☑ Their time entries                                  │  │
│  │  ☑ Their payout bills                                  │  │
│  │  ☑ Assigned projects (name + status only)              │  │
│  │  ☐ Project billing amounts                             │  │
│  └───────────────────────────────────────────────────────┘  │
│                                                              │
│  ┌── Time Entry Approval ────────────────────────────────┐  │
│  │                                                        │  │
│  │  Require approval before payout                        │  │
│  │  ● All contractor time requires approval               │  │
│  │  ○ Auto-approve (no review required)                   │  │
│  │                                                        │  │
│  │  Approval deadline (after submission)                  │  │
│  │  [7____] days  (0 = no deadline)                       │  │
│  │                                                        │  │
│  └───────────────────────────────────────────────────────┘  │
│                                                              │
│  ┌── Payout Defaults ────────────────────────────────────┐  │
│  │                                                        │  │
│  │  Default payment period                                │  │
│  │  [Monthly ▾]  Weekly · Bi-weekly · Monthly             │  │
│  │                                                        │  │
│  │  Default rate currency                                 │  │
│  │  [ILS ▾]                                               │  │
│  │                                                        │  │
│  │  Include withholding tax note on payout bills          │  │
│  │  ● Yes  ○ No                                           │  │
│  │  Note: [לפי ס' 164 לפקודת מס הכנסה, ינוכה מס במקור]  │  │
│  │        (customizable)                                  │  │
│  │                                                        │  │
│  └───────────────────────────────────────────────────────┘  │
│                                                              │
│  [Save changes]                                              │
└──────────────────────────────────────────────────────────────┘
```

---

## Schema Delta

```sql
-- contractor_require_time_approval is owned by time-management (wave 5).
-- This page consumes/edits it but does NOT add it here.
ALTER TABLE tenant_settings
  ADD COLUMN IF NOT EXISTS contractor_portal_enabled BOOLEAN NOT NULL DEFAULT true,
  ADD COLUMN IF NOT EXISTS contractor_portal_show_billing BOOLEAN NOT NULL DEFAULT false,
  ADD COLUMN IF NOT EXISTS contractor_approval_deadline_days INTEGER NOT NULL DEFAULT 7,
  ADD COLUMN IF NOT EXISTS contractor_payout_period TEXT NOT NULL DEFAULT 'monthly'
    CHECK (contractor_payout_period IN ('weekly', 'biweekly', 'monthly')),
  ADD COLUMN IF NOT EXISTS contractor_withholding_note TEXT;
```

---

## Non-Business+ Portal Note

If `contractor_portal_enabled = true` but the tenant is not Business+:

```
⚠ Contractor portal requires Business+.
Contractors will see a "coming soon" message until you upgrade.
[Upgrade to Business+]
```

Portal access is gated at the portal auth layer (spec 87), not here.

---

## API

```
GET /api/settings/contractors
    → get contractor settings
      Returns: { contractor_portal_enabled, contractor_portal_show_billing,
                 contractor_require_time_approval, contractor_approval_deadline_days,
                 contractor_payout_period, contractor_withholding_note }
      Requires: payouts:read

PATCH /api/settings/contractors
      → update contractor settings
        body: { ...any settable fields above }
        Requires: payouts:write
```

---

## Architecture Decisions

| Decision | Choice | Reason |
|----------|--------|--------|
| Extend `tenant_settings` | Not new `contractor_settings` table | Contractor settings are per-tenant scalar config; a separate table adds a join without benefit |
| `contractor_portal_show_billing` | Default false | Billing amounts are sensitive; opt-in rather than opt-out protects against accidental disclosure |
| Approval deadline | Days, not hours | Contractor time review cycles are daily/weekly; hour-level granularity adds precision nobody needs |