This application is a mobile-first business system for managing collaborators working for a company with remote operations. It tracks:

• people under contract or eligible to return,
• collaborator work journeys,
• mine-well production,
• gold prices,
• price lists for mercantile goods and services,
• earnings accruals,
• expenses,
• current-account balances in both Real and grams of gold,
• projected earnings through the end of the current journey,
• journey closeout and payout.

The target stack is:

• Backend: Golang + Fiber
• Database: SQLite + GORM
• Frontend: React, mobile-first, desktop-capable
• Architecture style: modular monolith with clean domain boundaries

This system is not a simple CRUD application. It is a hybrid of workforce management, payroll, production-linked commission accounting, mercantile expense tracking, and dual-currency ledger management.

The system must allow an administrator and planner to:

1. Maintain permanent records for people and collaborator journeys.
2. Track collaborator assignments and planning by work period.
3. Accrue earnings based on daily wages, salary, or production commission.
4. Record collaborator expenses in either Real or grams of gold.
5. View current-account summaries and details in both currencies.
6. Estimate projected earnings through the projected end of a collaborator’s current journey.
7. Support sick-day and license substitution rules involving daily wagers and commissioned collaborators.
8. Revert erroneous ledger transactions without destructive deletion.
9. Zero out gold balances on request during a journey.
10. Close a work journey and compute payout obligations.

The source requirements are strong, but several operational rules must be made explicit for implementation.

The following records are never physically deleted:

• Person
• Collaborator
• Current Account Entry
• Mine Well Production
• Gold Price
• Price List Items
• Reference Data

Instead, records are managed with status flags, activity flags, effective dates, or reversal records.

The recommended architecture is a modular monolith, not microservices, because:

• business rules are tightly coupled,
• SQLite is the requested database,
• deployment simplicity matters for remote operations,
• transaction safety across accounting workflows is easier in one process,
• future extraction to services remains possible.

Balances are derived from immutable current-account entries and reversals, not from mutable balance fields.

The system tracks accounting in two units:

• BRL (Real)
• Gold grams

A current-account entry belongs to exactly one currency. Summaries compute balances separately for each currency.

Because salary is specified as a monthly salary, but work planning operates in daily work periods, the design assumes:

• monthly salary is normalized to a daily accrual rate for daily projected earning calculations,
• the normalization formula is configurable,
• the default formula is monthly_salary / 30.

Mine-well production is recorded by:

• date
• period
• well

Each period is a 12-hour shift. The plan/accrual engine uses a formal work_period entity to anchor planning and earnings.

Commissioned collaborators earn based on:

• assigned work well,
• work period,
• recorded well production,
• collaborator commission percentage.

If required production is missing, accrual status remains pending until production is recorded.

The specification implies substitution-based earnings transfer logic. The implementation will support explicit substitution links so every exception is auditable.

A collaborator journey has:

• start date,
• default end date = start date + 90 days,
• extension days,
• projected end date = default end + extension days,
• status transitions,
• closure workflow.

Initial recommended roles:

• Administrator: full access
• Planner: planning, accrual, production support
• Mercantile Operator: expense entry, read summaries
• Finance Viewer: read-only reports and ledgers

React Mobile-First Frontend
        |
        v
Fiber HTTP API
        |
        v
Application Layer / Use Cases
        |
        v
Domain Modules
  - Auth
  - People
  - Collaborators
  - Reference Data
  - Work Period Planning
  - Mine Production
  - Gold Pricing
  - Price List
  - Expenses
  - Earnings
  - Current Account Ledger
  - Journey Closure
  - Reports
        |
        v
GORM Repositories
        |
        v
SQLite

1. auth
2. people
3. collaborators
4. reference_data
5. work_periods
6. planning
7. mine_production
8. gold_prices
9. price_list
10. expenses
11. earnings
12. ledger
13. journey_closure
14. reports
15. audit

Permanent identity and contact record.

• id
• name
• address
• phone
• email
• cpf
• bank_data
• pix_key
• emergency_contact_name
• emergency_contact_phone
• emergency_contact_notes
• status
• created_at
• updated_at
• archived_at nullable

• unique(name)
• unique(phone)
• unique(email)
• unique(cpf)
• unique(pix_key)

A person may have many collaborator journeys over time.

Represents a specific contractual work journey for a person.

• id
• person_id
• journey_start_date
• default_end_date
• extension_days
• projected_end_date
• payment_method_id
• payment_value
• sector_id
• location_id
• task_id
• status_id
• notes
• created_at
• updated_at
• closed_at nullable

• default_end_date = journey_start_date + 90 days
• projected_end_date = default_end_date + extension_days

• no physical deletion
• one person may have multiple journeys across time
• optional rule: only one active collaborator journey per person at a time

Production recorded for a specific well and period.

• id
• work_date
• period_code
• location_id
• grams_produced
• comments
• created_by
• created_at
• updated_at

• unique(work_date, period_code, location_id)
• location must be a mine-well type location

Daily gold reference price.

• id
• quote_date
• quoted_at_time
• price_brl_per_gram
• source_name
• comments
• created_by
• created_at
• updated_at

• unique(quote_date)

Default rule: use most recent quote at time of transaction.

Catalog of goods and services.

• id
• code
• name
• description
• category
• price_brl
• active
• created_at
• updated_at

• price_gold_grams = price_brl / latest_gold_price_brl_per_gram

Gold price equivalent is usually computed dynamically and optionally snapshot into expense line items.

Immutable ledger entry representing a credit or debit in one currency.

• id
• reverted_entry_id nullable
• collaborator_id
• entry_date
• source_type
• source_id nullable
• method_id nullable
• currency_code
• cd_flag
• item_description
• quantity
• unit_price
• total_price
• comments
• status
• created_by
• created_at

• earning_accrual
• expense
• reversal
• zero_out
• journey_close
• manual_adjustment

• BRL
• GOLD_GRAMS

• CREDIT
• DEBIT

• quantity > 0
• total_price >= 0
• reversal entries reference original entry
• original entries are not edited after posting

A plan/accrual anchor for operational periods.

• id
• work_date
• period_code
• starts_at
• ends_at
• status
• created_at
• updated_at

• planned
• informed
• accrued
• locked

• unique(work_date, period_code)

Operational assignment of a collaborator for a work period.

• id
• work_period_id
• collaborator_id
• include_flag
• sector_id
• location_id
• task_id
• method_id
• payment_value_snapshot
• assignment_status
• substituted_for_collaborator_id nullable
• exception_type nullable
• comments
• created_at
• updated_at

• planned
• worked
• sick
• license
• absent
• excluded

• none
• sick_substitution
• license_substitution

Header record for an expense operation.

• id
• collaborator_id
• expense_date
• currency_code
• total_amount
• category
• collaborator_agreement
• comments
• created_by
• created_at
• updated_at

• canteen
• pix
• flights
• pay_daily_wager
• diverse

Line item under an expense transaction.

• id
• expense_id
• price_list_item_id nullable
• item_name_snapshot
• quantity
• unit_price
• total_price
• comments
• created_at

Tracks the accrual operation for a work period.

• id
• work_period_id
• accrual_status
• comments
• created_by
• created_at
• updated_at

• draft
• pending_production
• posted
• partially_posted
• reverted

One collaborator’s earnings computation for a period.

• id
• accrual_batch_id
• collaborator_id
• method_id
• currency_code
• calculation_basis_json
• gross_amount
• transfer_amount
• net_amount
• ledger_entry_id nullable
• status
• comments
• created_at

Configurable lookup tables.

Recommended generic table structure:

• id
• type
• code
• label
• description
• active
• sort_order
• metadata_json
• created_at
• updated_at

Supported types:

• sector
• location
• task
• method
• person_status
• collaborator_status
• expense_category
• period_code
• ledger_currency
• ledger_cd_flag

• Person records are permanent.
• Name, phone, email, CPF, and PIX must be unique if present.
• A person can move across statuses without deleting history.

• A collaborator journey is created from a person.
• Default journey length is 90 days.
• Extension days may be added by the administrator.
• Projected end date is recalculated on extension change.
• One person should generally have at most one active journey.
• After journey end, business policy may enforce a minimum 30-day wait before a new journey. This should be configurable as a validation rule, with override permission for administrators.

• Earns daily rate for each worked period/day according to plan/accrual rules.
• Currency is BRL unless business later adds another rule.

• Earns daily normalized value based on monthly salary.
• Currency is BRL.

• Earns in gold grams.
• Amount is tied to recorded production for assigned well and period.
• Formula: grams_produced * collaborator_percentage.
• Accrual waits if production is missing.

For commissioned collaborator:

• May take up to 3 sick days.
• Still earns full daily commission.
• Pays 1 gram gold to substitute daily wager.
• Substitute daily wager also earns normal daily wages.

System interpretation:

• one commission credit for sick collaborator,
• one gold debit for sick collaborator labeled Pay Daily Wager - Sick Substitution,
• one gold credit for substitute daily wager labeled Sick Substitution Payment,
• one BRL wage credit for substitute daily wager.

For commissioned collaborator:

• May take a license through default end of journey.
• Earns half of daily commission.
• Other half goes to substitute daily wager.
• Substitute daily wager does not earn normal daily wages for that substitution period.

System interpretation:

• commissioned collaborator gets half commission credit,
• substitute gets half commission credit,
• substitute receives no daily wage credit for those substituted periods.

• Expenses can be recorded in BRL or gold grams.
• Expense line items snapshot unit and total prices at entry time.
• Gold-priced expenses use current quote basis at transaction time.
• PIX expenses are BRL-only.
• Daily wager substitution payments may be generated automatically by earnings/accrual rules rather than manually entered.

• Every financial effect becomes one or more immutable ledger entries.
• Reversal is additive, never destructive.
• Balances are computed as sum(credits) - sum(debits) per currency.
• Reversed entries remain visible with status markers.

• Zeroing gold means paying out current positive gold balance during an active journey.
• A zero operation creates a debit entry that offsets the available gold credit balance.
• Zero cannot exceed available positive gold balance unless admin override is allowed.

• Closing a journey computes current BRL and gold balances.
• Positive balances are payable.
• Closing creates payout ledger entries to offset balances.
• After close, collaborator status becomes finished.

1. users
2. roles
3. user_roles
4. people
5. collaborator_journeys
6. reference_data
7. work_periods
8. work_plan_items
9. mine_well_productions
10. gold_prices
11. price_list_items
12. expense_transactions
13. expense_items
14. earning_accrual_batches
15. earning_accrual_items
16. current_account_entries
17. audit_logs
18. attachments (optional future)

• id TEXT PK
• name TEXT NOT NULL UNIQUE
• address TEXT
• phone TEXT UNIQUE
• email TEXT UNIQUE
• cpf TEXT UNIQUE
• bank_data TEXT
• pix_key TEXT UNIQUE
• emergency_contact_name TEXT
• emergency_contact_phone TEXT
• emergency_contact_notes TEXT
• status_id TEXT NOT NULL
• created_at DATETIME NOT NULL
• updated_at DATETIME NOT NULL

• id TEXT PK
• person_id TEXT NOT NULL FK people(id)
• journey_start_date DATE NOT NULL
• default_end_date DATE NOT NULL
• extension_days INTEGER NOT NULL DEFAULT 0
• projected_end_date DATE NOT NULL
• payment_method_id TEXT NOT NULL FK reference_data(id)
• payment_value NUMERIC NOT NULL
• sector_id TEXT NOT NULL FK reference_data(id)
• location_id TEXT NOT NULL FK reference_data(id)
• task_id TEXT NOT NULL FK reference_data(id)
• status_id TEXT NOT NULL FK reference_data(id)
• notes TEXT
• closed_at DATETIME NULL
• created_at DATETIME NOT NULL
• updated_at DATETIME NOT NULL

• id TEXT PK
• work_date DATE NOT NULL
• period_code TEXT NOT NULL
• starts_at DATETIME NULL
• ends_at DATETIME NULL
• status TEXT NOT NULL
• created_at DATETIME NOT NULL
• updated_at DATETIME NOT NULL
• UNIQUE(work_date, period_code)

• id TEXT PK
• work_period_id TEXT NOT NULL FK work_periods(id)
• collaborator_id TEXT NOT NULL FK collaborator_journeys(id)
• include_flag BOOLEAN NOT NULL DEFAULT true
• sector_id TEXT NOT NULL
• location_id TEXT NOT NULL
• task_id TEXT NOT NULL
• method_id TEXT NOT NULL
• payment_value_snapshot NUMERIC NOT NULL
• assignment_status TEXT NOT NULL
• substituted_for_collaborator_id TEXT NULL
• exception_type TEXT NULL
• comments TEXT
• created_at DATETIME NOT NULL
• updated_at DATETIME NOT NULL

• id TEXT PK
• work_date DATE NOT NULL
• period_code TEXT NOT NULL
• location_id TEXT NOT NULL
• grams_produced NUMERIC NOT NULL
• comments TEXT
• created_by TEXT NOT NULL
• created_at DATETIME NOT NULL
• updated_at DATETIME NOT NULL
• UNIQUE(work_date, period_code, location_id)

• id TEXT PK
• quote_date DATE NOT NULL UNIQUE
• quoted_at_time TEXT
• price_brl_per_gram NUMERIC NOT NULL
• source_name TEXT
• comments TEXT
• created_by TEXT NOT NULL
• created_at DATETIME NOT NULL
• updated_at DATETIME NOT NULL

• id TEXT PK
• code TEXT UNIQUE
• name TEXT NOT NULL UNIQUE
• description TEXT
• category TEXT NOT NULL
• price_brl NUMERIC NOT NULL
• active BOOLEAN NOT NULL DEFAULT true
• created_at DATETIME NOT NULL
• updated_at DATETIME NOT NULL

• id TEXT PK
• collaborator_id TEXT NOT NULL FK collaborator_journeys(id)
• expense_date DATE NOT NULL
• currency_code TEXT NOT NULL
• total_amount NUMERIC NOT NULL
• category TEXT NOT NULL
• collaborator_agreement BOOLEAN NOT NULL DEFAULT false
• comments TEXT
• created_by TEXT NOT NULL
• created_at DATETIME NOT NULL
• updated_at DATETIME NOT NULL

• id TEXT PK
• expense_id TEXT NOT NULL FK expense_transactions(id)
• price_list_item_id TEXT NULL FK price_list_items(id)
• item_name_snapshot TEXT NOT NULL
• quantity NUMERIC NOT NULL
• unit_price NUMERIC NOT NULL
• total_price NUMERIC NOT NULL
• comments TEXT
• created_at DATETIME NOT NULL

• id TEXT PK
• work_period_id TEXT NOT NULL FK work_periods(id)
• accrual_status TEXT NOT NULL
• comments TEXT
• created_by TEXT NOT NULL
• created_at DATETIME NOT NULL
• updated_at DATETIME NOT NULL

• id TEXT PK
• accrual_batch_id TEXT NOT NULL FK earning_accrual_batches(id)
• collaborator_id TEXT NOT NULL FK collaborator_journeys(id)
• method_id TEXT NOT NULL
• currency_code TEXT NOT NULL
• calculation_basis_json TEXT NOT NULL
• gross_amount NUMERIC NOT NULL
• transfer_amount NUMERIC NOT NULL DEFAULT 0
• net_amount NUMERIC NOT NULL
• ledger_entry_id TEXT NULL
• status TEXT NOT NULL
• comments TEXT
• created_at DATETIME NOT NULL

• id TEXT PK
• reverted_entry_id TEXT NULL FK current_account_entries(id)
• collaborator_id TEXT NOT NULL FK collaborator_journeys(id)
• entry_date DATE NOT NULL
• source_type TEXT NOT NULL
• source_id TEXT NULL
• method_id TEXT NULL
• currency_code TEXT NOT NULL
• cd_flag TEXT NOT NULL
• item_description TEXT NOT NULL
• quantity NUMERIC NOT NULL DEFAULT 1
• unit_price NUMERIC NOT NULL
• total_price NUMERIC NOT NULL
• comments TEXT
• status TEXT NOT NULL DEFAULT 'active'
• created_by TEXT NOT NULL
• created_at DATETIME NOT NULL

• id TEXT PK
• actor_user_id TEXT NOT NULL
• action TEXT NOT NULL
• entity_type TEXT NOT NULL
• entity_id TEXT NOT NULL
• before_json TEXT
• after_json TEXT
• created_at DATETIME NOT NULL

All APIs should be versioned under /api/v1.

• POST /auth/login
• POST /auth/logout
• GET /auth/me

• GET /people
• POST /people
• GET /people/:id
• PUT /people/:id
• GET /people/:id/journeys

• GET /collaborators
• POST /collaborators
• GET /collaborators/:id
• PUT /collaborators/:id
• POST /collaborators/:id/extend
• POST /collaborators/:id/finish
• GET /collaborators/:id/projection

• GET /reference-data/:type
• POST /reference-data/:type
• PUT /reference-data/:type/:id

• GET /work-periods
• POST /work-periods
• GET /work-periods/:id
• POST /work-periods/:id/seed-from-previous
• GET /work-periods/:id/plan
• PUT /work-periods/:id/plan-items/:planItemId
• POST /work-periods/:id/inform
• POST /work-periods/:id/accrue

• GET /mine-productions
• POST /mine-productions
• PUT /mine-productions/:id

• GET /gold-prices
• POST /gold-prices
• PUT /gold-prices/:id
• GET /gold-prices/latest

• GET /price-list
• POST /price-list
• PUT /price-list/:id
• GET /price-list/:id/price-preview?currency=BRL|GOLD_GRAMS

• GET /expenses
• POST /expenses
• GET /expenses/:id
• POST /expenses/:id/revert

• GET /current-accounts/:collaboratorId/summary
• GET /current-accounts/:collaboratorId/entries
• GET /current-accounts/:collaboratorId/entries?currency=BRL
• GET /current-accounts/:collaboratorId/entries?currency=GOLD_GRAMS
• POST /current-accounts/entries/:id/revert
• POST /current-accounts/:collaboratorId/zero-gold
• POST /current-accounts/:collaboratorId/close

• GET /reports/dashboard
• GET /reports/collaborator-balances
• GET /reports/journeys-ending-soon
• GET /reports/pending-production-accruals
• GET /reports/mercantile-sales

The frontend should be a React SPA optimized for:

• phone-first usage,
• touch-friendly actions,
• readable cards and summaries,
• desktop expansion into split panes/tables.

1. Dashboard
2. People
3. Collaborators
4. Planning
5. Production
6. Gold Price
7. Mercantile / Expenses
8. Current Accounts
9. Reports
10. Settings

• card-based layouts on small screens,
• bottom-safe action bars for primary actions,
• sticky summary panels,
• large tap targets,
• progressive disclosure for complex forms,
• desktop upgrades to table/grid views.

• username/email
• password
• sign in button

Widgets:

• active collaborators count
• journeys ending soon
• pending accruals due to missing production
• latest gold quote
• today’s expenses total
• negative balance alerts

• search
• status filter
• add person
• person cards/table

• person profile
• contact info
• status
• journey history
• create collaborator journey action

• active/finished filter
• payment method filter
• location filter
• projected-end range filter

Sections:

• identity summary
• journey dates
• payment model
• assignment info
• status
• BRL balance summary
• gold balance summary
• projected earnings
• actions: extend, zero gold, close journey, open ledger, create expense

Three-stage workflow:

• load previous period plan
• include/exclude toggles
• add collaborators not in previous period
• assign sector/location/task/method
• mark sick/license/substitute

• print-friendly formatted assignment roster
• filter included collaborators only

• compare plan vs actual
• mark worked/sick/license/absent
• show production dependency warnings
• post accrual batch

• date
• period
• well
• grams produced
• comments
• list of recorded productions

• date
• price BRL/gram
• source
• comments
• latest price card
• price history list

• list items
• create/edit item
• dynamic gold equivalent preview based on latest quote

This is one of the key screens.

• collaborator name
• projected journey end
• payment method
• BRL balance
• gold balance
• projected earnings
• substitution recipient information if relevant

• currency selector
• category selector
• multi-line item entry
• quantity
• unit price
• total price
• comments
• collaborator agreement checkbox
• save action

• summary shown first,
• form stacked below,
• sticky running total.

• BRL credits
• BRL debits
• BRL balance
• Gold credits
• Gold debits
• Gold balance
• projected earnings
• payout estimate

• filter by currency
• filter by date
• filter by source type
• transaction timeline/cards on mobile
• table on desktop
• revert action for authorized users

• collaborator summary
• current balances
• projected end info
• zero history
• payout preview
• confirm close action

• collaborator balances
• negative balances
• production-linked commissions pending
• mercantile sales by category
• collaborator journey calendar

1. Admin opens People.
2. Creates permanent person record.
3. Validation checks unique fields.
4. Person is saved with status.

1. Admin selects Person.
2. Creates Collaborator Journey.
3. System computes default end date.
4. Admin sets payment method, value, sector, location, task.
5. Collaborator becomes active.

1. Admin opens Collaborator Detail.
2. Adds extension days.
3. System recalculates projected end date.
4. Audit log captures change.

1. Planner creates/selects work period.
2. System seeds from previous period plan.
3. Previous included collaborators default to include.
4. Collaborators not in previous period default to exclude.
5. Planner adjusts statuses and substitutions.
6. Plan is saved.

1. Planner opens Inform stage.
2. System renders print-friendly included list only.
3. Planner prints or exports the assignment roster.

1. Planner opens Accrual stage.
2. Marks actual work outcomes.
3. System computes earnings by collaborator.
4. If commission production missing, related accrual items are pending.
5. Post accrual creates ledger entries.

1. Admin searches collaborator.
2. System displays summary and projected balances.
3. Admin chooses expense currency.
4. Admin adds one or more items.
5. System validates prices and totals.
6. Save posts expense header, lines, and debit ledger entries.

1. Authorized user selects active ledger entry.
2. System creates opposite entry with reverted_entry_id.
3. Original entry remains visible.
4. Audit log is recorded.

1. Admin views collaborator gold balance.
2. System computes available positive gold credit.
3. Admin confirms payout.
4. System posts offsetting debit ledger entry.

1. Admin opens close screen.
2. System calculates final BRL and gold balances.
3. System previews payout amounts.
4. Admin confirms.
5. System posts close entries and marks journey finished.

Implement strategy pattern by payment method:

• DailyWageCalculator
• SalaryCalculator
• CommissionCalculator

Each receives:

• collaborator journey
• plan item
• work period
• production data if needed
• latest relevant rules

Returns:

• currency
• gross amount
• transfer amount
• net amount
• basis metadata
• hold reason if pending

net_amount = configured daily wage amount
currency = BRL

daily_rate = monthly_salary / configured_salary_divisor
net_amount = daily_rate
currency = BRL

gross_amount = well_production_grams * collaborator_percentage
currency = GOLD_GRAMS

For commissioned collaborator on sick day:

• commissioned collaborator earns full commission credit,
• commissioned collaborator receives a gold debit of 1 gram,
• substitute daily wager receives gold credit of 1 gram,
• substitute daily wager also receives BRL wage credit.

For commissioned collaborator on license day:

• commissioned collaborator receives half commission credit,
• substitute daily wager receives half commission credit,
• substitute daily wager receives no BRL wage credit for that substituted work.

• canteen
• pix
• flights
• pay_daily_wager
• diverse

• BRL entries use entered or catalog BRL price.
• Gold entries use either entered gold price or gold-equivalent from current quote.
• Every line stores a snapshot of quantity, unit price, and total price.

• currency required
• at least one item
• total must equal sum of lines
• PIX only in BRL
• agreement checkbox required

For each currency independently:

credits = sum(total_price where cd_flag = CREDIT and active)
debits  = sum(total_price where cd_flag = DEBIT and active)
balance = credits - debits

Projected earnings should be computed separately from posted balances and shown as an estimate.

Recommended formula:

projected_earnings = posted_earnings_to_date + estimated_remaining_earnings_to_projected_end

• daily wages: remaining eligible workdays × daily rate
• salary: remaining days × normalized daily salary
• commission: estimated based on configurable rolling average production or last known average

Because commission projection is uncertain, the UI should label it explicitly as estimated and show basis.

• original entry stays immutable
• reversal entry mirrors source, currency, quantity, and amount
• reversal flips credit/debit
• both entries become linked

• Fiber JWT authentication for API
• Refresh token support optional later
• Password-based login for internal users
• Role-based authorization middleware

• full CRUD on everything
• close journey
• zero gold
• revert entries
• manage reference data

• work periods
• planning
• inform
• accrual
• view collaborator summaries

• create expenses
• view collaborator summaries
• view price list
• cannot close journey or revert accruals

• read-only access to balances and reports

Audit all:

• login/logout
• journey creation/extension/close
• accrual posting
• expense posting
• reversals
• zero operations
• reference-data changes

/backend
  /cmd/server
    main.go
  /internal
    /app
      router.go
      middleware.go
      config.go
    /auth
      entity.go
      repository.go
      service.go
      handler.go
      middleware.go
    /people
      entity.go
      dto.go
      repository.go
      service.go
      handler.go
    /collaborators
      entity.go
      dto.go
      repository.go
      service.go
      handler.go
    /referencedata
      entity.go
      repository.go
      service.go
      handler.go
    /workperiods
      entity.go
      repository.go
      service.go
      handler.go
    /planning
      entity.go
      repository.go
      service.go
      handler.go
    /mineproduction
      entity.go
      repository.go
      service.go
      handler.go
    /goldprices
      entity.go
      repository.go
      service.go
      handler.go
    /pricelist
      entity.go
      repository.go
      service.go
      handler.go
    /expenses
      entity.go
      repository.go
      service.go
      handler.go
    /earnings
      calculators.go
      service.go
      accrual_service.go
    /ledger
      entity.go
      repository.go
      service.go
      projections.go
      handler.go
    /journeyclosure
      service.go
      handler.go
    /reports
      service.go
      handler.go
    /audit
      entity.go
      repository.go
      service.go
    /shared
      errors.go
      pagination.go
      money.go
      dates.go
      ids.go
  /migrations
  /test

/frontend
  /src
    /app
      router.tsx
      store.ts
      api.ts
      auth.ts
    /components
      /layout
      /forms
      /cards
      /tables
      /modals
      /summary
    /features
      /auth
      /dashboard
      /people
      /collaborators
      /planning
      /production
      /gold-prices
      /price-list
      /expenses
      /current-accounts
      /reports
      /settings
    /hooks
    /utils
    /types
    /styles

Recommended UI stack:

• React + TypeScript
• React Router
• TanStack Query
• React Hook Form + Zod
• Tailwind CSS or Bootstrap 5

Because you asked for React and mobile-first, React + TypeScript + Tailwind is the cleanest modern option.

• required: name
• unique: name, phone, email, cpf, pix_key

• person required
• start date required
• payment method required
• payment value > 0
• location/task/sector required

• date required
• period required
• well required
• grams produced >= 0

• one quote per date
• price > 0

• collaborator required
• currency required
• at least one item
• quantity > 0
• unit price >= 0
• total must reconcile

• original entry must be active and not already fully reversed unless partial reversal is intentionally supported later

Recommended initial reports:

1. Active collaborators
2. Collaborators with negative BRL balance
3. Collaborators with negative gold balance
4. Journeys ending in next 7/15/30 days
5. Pending commission accrual due to missing production
6. Mercantile sales by category and period
7. Gold payouts by period
8. BRL payouts by period
9. Expense totals by collaborator and category
10. Production totals by well and period

• unit tests for calculators and services
• repository tests against SQLite test DB
• Fiber handler tests with httptest
• golden JSON responses for critical endpoints if useful

1. 90-day journey default end calculation
2. extension recalculates projected end
3. 30-day return eligibility validation
4. daily wage accrual
5. salary daily normalization accrual
6. commission accrual from well production
7. accrual remains pending when production missing
8. sick substitution postings
9. license substitution postings
10. expense posting in BRL
11. expense posting in gold
12. reversal creation
13. zero gold operation
14. close journey ledger posting
15. projected earnings calculations

• component tests for summary cards and forms
• integration tests for key workflows
• responsive layout checks

Recommended Playwright scenarios:

1. create person → create collaborator
2. plan period → accrue earnings
3. record gold price → price list preview → expense entry
4. view current account summary/detail
5. revert expense
6. zero gold
7. close journey

Use a single deployable service:

• Fiber backend serving API
• React frontend built as static assets
• SQLite file stored on durable disk
• daily backups

• one app container
• one mounted volume for SQLite DB
• one mounted volume for backups/logs

Because SQLite is requested and operations are financially important:

• nightly DB backup
• pre-deploy backup
• exportable CSV/Excel reports for finance audit

If the system grows, extract these first:

• reporting
• auth
• pricing/integration adapters

To ship safely, the MVP should include:

• auth
• people
• collaborator journeys
• reference data

• work periods
• planning
• mine production
• gold prices

• earnings accrual engine
• expense entry
• ledger summary/detail

• reversals
• zero gold
• close journey
• reports

Handled via explicit calculator strategies and audit metadata.

Handled by one-currency-per-ledger-entry and independent balance summaries.

Handled by reversal-based accounting, not deletion.

Handled via pending accrual batches.

Handled by modular monolith first.

Build this as a modular monolith with:

• Fiber backend
• SQLite + GORM
• React + TypeScript frontend
• immutable ledger design
• explicit planning/accrual workflow
• reversible financial postings
• strong audit trail

This is the right architecture for the current requirements and leaves room for future extraction and scaling.

The best immediate follow-up is:

1. ERD + relational schema
2. OpenAPI-style REST contract
3. production folder skeleton with starter code
4. database migrations + GORM models
5. React route/page skeleton

That would turn this blueprint into an implementation-ready package.

Below is the recommended logical ERD for the first production version.

users ──< user_roles >── roles

people ──< collaborator_journeys ──< work_plan_items >── work_periods
   │                │                       │
   │                │                       └──── references reference_data for sector/location/task/method
   │                │
   │                ├──< expense_transactions ──< expense_items >── price_list_items
   │                │
   │                ├──< earning_accrual_items >── earning_accrual_batches >── work_periods
   │                │
   │                └──< current_account_entries >── current_account_entries (self via reverted_entry_id)
   │
   └── status via reference_data(person_status)

mine_well_productions >── work_periods
mine_well_productions ──> reference_data(location)

gold_prices

price_list_items

reference_data

audit_logs ──> users

• Person 1:N CollaboratorJourney
  • One person can have many work journeys over time.
  • Only one active journey per person is recommended.

• WorkPeriod 1:N WorkPlanItem
• CollaboratorJourney 1:N WorkPlanItem
• CollaboratorJourney 0..N substitute roles in WorkPlanItem via substituted_for_collaborator_id

• WorkPeriod 1:N MineWellProduction
• WorkPeriod 1:N EarningAccrualBatch
• EarningAccrualBatch 1:N EarningAccrualItem
• CollaboratorJourney 1:N EarningAccrualItem

• CollaboratorJourney 1:N ExpenseTransaction
• ExpenseTransaction 1:N ExpenseItem
• PriceListItem 0..N ExpenseItem

• CollaboratorJourney 1:N CurrentAccountEntry
• CurrentAccountEntry 0..N self-reference through reverted_entry_id

The following entities point to reference_data rows:

• people.status_id
• collaborator_journeys.payment_method_id
• collaborator_journeys.sector_id
• collaborator_journeys.location_id
• collaborator_journeys.task_id
• collaborator_journeys.status_id
• work_plan_items.sector_id
• work_plan_items.location_id
• work_plan_items.task_id
• work_plan_items.method_id

This section defines the implementation-grade schema for SQLite + GORM.

Use string IDs (ULID recommended) for all primary keys:

• good for offline-safe generation,
• sortable by time,
• easier than auto-increment merges if imports happen later.

All mutable business tables should have:

• created_at
• updated_at

Do not soft-delete financial or historical records.

Use:

• status
• active
• closed_at
• reversal records

instead of deletion.

SQLite foreign keys must be enabled explicitly at connection time.

For SQLite, GORM will map decimal-like values to numeric/text depending on implementation. For accounting safety, the app layer should use fixed-precision decimal handling.

Recommended handling:

• Go type: decimal library or integer minor units where appropriate
• DB type labels: NUMERIC

For this schema document, all accounting amounts are shown as NUMERIC(18,6) conceptually.

Purpose: internal application users.

Indexes:

• unique(username)
• unique(email)

Suggested seed values:

• ADMIN
• PLANNER
• MERCANTILE_OPERATOR
• FINANCE_VIEWER

Indexes:

• unique(user_id, role_id)

Purpose: extensible lookup storage.

Indexes:

• unique(type, code)
• index(type, active, sort_order)

Suggested seeded type values:

• sector
• location
• task
• method
• person_status
• collaborator_status
• expense_category
• period_code
• ledger_currency
• ledger_cd_flag

Indexes:

• unique(name)
• unique(phone)
• unique(email)
• unique(cpf)
• unique(pix_key)
• index(status_id)

Purpose: a contractual work journey for one person.

Indexes:

• index(person_id)
• index(status_id)
• index(projected_end_date)
• index(location_id)
• index(payment_method_id)
• recommended partial uniqueness in app logic: one active journey per person

Important application constraint:

• a person should not have more than one active collaborator journey at the same time.

Because SQLite partial uniqueness is awkward in portable GORM migrations, enforce this in service logic.

Purpose: operational 12-hour periods used for planning, informing, accrual, and production alignment.

Indexes:

• unique(work_date, period_code)
• index(status)

Purpose: collaborator assignments for a work period.

Indexes:

• index(work_period_id)
• index(collaborator_id)
• index(location_id)
• index(substituted_for_collaborator_id)
• recommended unique(work_period_id, collaborator_id)

Purpose: recorded production per well for a given date/period.

Indexes:

• unique(work_date, period_code, location_id)
• index(work_period_id)
• index(location_id)

Note:

• location_id should point only to mine-well-capable locations. This is best enforced in application rules or metadata_json on reference_data.

Purpose: daily BRL per gram quote.

Indexes:

• unique(quote_date)
• index(quote_date desc)

Purpose: mercantile catalog.

Indexes:

• unique(name)
• unique(code)
• index(category_id, active)

Note:

• Gold price equivalent is computed dynamically or snapshotted at expense time, not stored here as a permanent column.

Purpose: expense header.

Indexes:

• index(collaborator_id)
• index(expense_date)
• index(category_id)
• index(currency_code)

Purpose: expense lines.

Indexes:

• index(expense_id)
• index(price_list_item_id)

Purpose: posting run for one work period.

Indexes:

• index(work_period_id)
• index(accrual_status)
• recommended unique(work_period_id) for one principal batch per period in MVP

Purpose: collaborator-by-collaborator accrual results.

Indexes:

• index(accrual_batch_id)
• index(collaborator_id)
• index(status)
• index(work_plan_item_id)

Note:

• special sick/license cases can create more than one ledger entry, so ledger_entry_id here is optional convenience only. The authoritative financial data remains in current_account_entries.

Purpose: immutable dual-currency ledger.

Indexes:

• index(collaborator_id, entry_date)
• index(currency_code, cd_flag)
• index(source_type, source_id)
• index(ledger_group_id)
• index(reverted_entry_id)

Important rules:

• no updates to financial meaning after posting
• reversal must create a new opposite entry
• status marks visibility state but does not remove the row

Purpose: operational and financial audit trail.

Indexes:

• index(actor_user_id)
• index(entity_type, entity_id)
• index(created_at)

These are not mandatory for v1, but I recommend reserving them in the design.

Purpose: optional posting batch header for multi-line postings.

This helps for grouping multiple entries generated from one accrual or expense.

Purpose: configurable operational rules.

Recommended keys:

• journey_default_days = 90
• return_wait_days = 30
• salary_daily_divisor = 30
• max_sick_days = 3
• commission_projection_basis = rolling_average

1. Unique person identity/contact keys.
2. Unique work period (work_date, period_code).
3. Unique mine-well production (work_date, period_code, location_id).
4. Unique gold price per date.
5. Unique reference (type, code).
6. Unique plan item per (work_period_id, collaborator_id).

1. Only one active collaborator journey per person.
2. New journey should respect 30-day wait after prior finished journey unless override.
3. Only valid mine-well locations may be used for production-based commission.
4. PIX expenses must be BRL.
5. Zero-out cannot exceed positive available gold balance without override.
6. Reversal cannot be applied twice to the same posting unless partial reversals are later introduced.
7. Closed journey should not accept new expenses/accruals except authorized adjustments.

• has many CollaboratorJourneys

• belongs to Person
• has many WorkPlanItems
• has many ExpenseTransactions
• has many EarningAccrualItems
• has many CurrentAccountEntries

• has many WorkPlanItems
• has many MineWellProductions
• has one or many EarningAccrualBatches

• belongs to CollaboratorJourney
• has many ExpenseItems

• belongs to WorkPeriod
• has many EarningAccrualItems

• belongs to CollaboratorJourney
• optionally belongs to a reverted original entry

For implementation, the schema should use these v1 canonical tables:

1. users
2. roles
3. user_roles
4. reference_data
5. people
6. collaborator_journeys
7. work_periods
8. work_plan_items
9. mine_well_productions
10. gold_prices
11. price_list_items
12. expense_transactions
13. expense_items
14. earning_accrual_batches
15. earning_accrual_items
16. current_account_entries
17. audit_logs
18. system_settings

This gives enough structure to build the backend cleanly without premature complexity.

To keep v1 stable, the schema does not yet include:

• payroll export tables
• file attachments
• offline sync conflict tables
• multiple companies/tenants
• accounting journal export to external finance systems
• approval workflows beyond role authorization

Those can be added later without breaking the main ledger design.

The best next step is now:

1. GORM model definitions
2. initial SQL migrations
3. Fiber route map and request/response DTOs
4. React page/route skeleton

That sequence will move the project from architecture to implementable code.

Below is a practical first-pass model set for Go + GORM + SQLite.

/internal/db/models
  base.go
  user.go
  reference_data.go
  person.go
  collaborator_journey.go
  work_period.go
  work_plan_item.go
  mine_well_production.go
  gold_price.go
  price_list_item.go
  expense_transaction.go
  earning_accrual.go
  current_account_entry.go
  audit_log.go
  system_setting.go

package models

import "time"

type BaseModel struct {
	ID        string    `gorm:"type:text;primaryKey" json:"id"`
	CreatedAt time.Time `gorm:"not null" json:"createdAt"`
	UpdatedAt time.Time `gorm:"not null" json:"updatedAt"`
}

Recommended supporting conventions in application code:

• generate ULIDs in a GORM BeforeCreate hook or in service layer
• enable SQLite foreign keys on connection open
• use a decimal library in DTO/service logic for financial arithmetic

package models

import "time"

type User struct {
	BaseModel
	Username     string     `gorm:"type:text;not null;uniqueIndex" json:"username"`
	Email        string     `gorm:"type:text;not null;uniqueIndex" json:"email"`
	PasswordHash string     `gorm:"type:text;not null" json:"-"`
	DisplayName  string     `gorm:"type:text;not null" json:"displayName"`
	Active       bool       `gorm:"not null;default:true" json:"active"`
	LastLoginAt  *time.Time `gorm:"type:datetime" json:"lastLoginAt,omitempty"`
	Roles        []Role     `gorm:"many2many:user_roles;" json:"roles,omitempty"`
}

type Role struct {
	BaseModel
	Code  string `gorm:"type:text;not null;uniqueIndex" json:"code"`
	Label string `gorm:"type:text;not null" json:"label"`
}

type UserRole struct {
	ID        string    `gorm:"type:text;primaryKey" json:"id"`
	UserID    string    `gorm:"type:text;not null;uniqueIndex:ux_user_role" json:"userId"`
	RoleID    string    `gorm:"type:text;not null;uniqueIndex:ux_user_role" json:"roleId"`
	CreatedAt time.Time `gorm:"not null" json:"createdAt"`

	User User `gorm:"foreignKey:UserID;constraint:OnUpdate:Restrict,OnDelete:Restrict;" json:"-"`
	Role Role `gorm:"foreignKey:RoleID;constraint:OnUpdate:Restrict,OnDelete:Restrict;" json:"-"`
}

package models

type ReferenceData struct {
	BaseModel
	Type         string `gorm:"type:text;not null;uniqueIndex:ux_reference_type_code;index:idx_reference_type_active_sort,priority:1" json:"type"`
	Code         string `gorm:"type:text;not null;uniqueIndex:ux_reference_type_code" json:"code"`
	Label        string `gorm:"type:text;not null" json:"label"`
	Description  string `gorm:"type:text" json:"description,omitempty"`
	Active       bool   `gorm:"not null;default:true;index:idx_reference_type_active_sort,priority:2" json:"active"`
	SortOrder    int    `gorm:"not null;default:0;index:idx_reference_type_active_sort,priority:3" json:"sortOrder"`
	MetadataJSON string `gorm:"type:text" json:"metadataJson,omitempty"`
}

package models

type Person struct {
	BaseModel
	Name                  string                 `gorm:"type:text;not null;uniqueIndex" json:"name"`
	Address               string                 `gorm:"type:text" json:"address,omitempty"`
	Phone                 *string                `gorm:"type:text;uniqueIndex" json:"phone,omitempty"`
	Email                 *string                `gorm:"type:text;uniqueIndex" json:"email,omitempty"`
	CPF                   *string                `gorm:"column:cpf;type:text;uniqueIndex" json:"cpf,omitempty"`
	BankData              string                 `gorm:"type:text" json:"bankData,omitempty"`
	PIXKey                *string                `gorm:"column:pix_key;type:text;uniqueIndex" json:"pixKey,omitempty"`
	EmergencyContactName  string                 `gorm:"type:text" json:"emergencyContactName,omitempty"`
	EmergencyContactPhone string                 `gorm:"type:text" json:"emergencyContactPhone,omitempty"`
	EmergencyContactNotes string                 `gorm:"type:text" json:"emergencyContactNotes,omitempty"`
	StatusID              string                 `gorm:"type:text;not null;index" json:"statusId"`
	Notes                 string                 `gorm:"type:text" json:"notes,omitempty"`
	Status                ReferenceData          `gorm:"foreignKey:StatusID;constraint:OnUpdate:Restrict,OnDelete:Restrict;" json:"status,omitempty"`
	Journeys              []CollaboratorJourney  `gorm:"foreignKey:PersonID" json:"journeys,omitempty"`
}

package models

import "time"

type CollaboratorJourney struct {
	BaseModel
	PersonID          string        `gorm:"type:text;not null;index" json:"personId"`
	JourneyStartDate  time.Time     `gorm:"type:date;not null" json:"journeyStartDate"`
	DefaultEndDate    time.Time     `gorm:"type:date;not null" json:"defaultEndDate"`
	ExtensionDays     int           `gorm:"not null;default:0" json:"extensionDays"`
	ProjectedEndDate  time.Time     `gorm:"type:date;not null;index" json:"projectedEndDate"`
	PaymentMethodID   string        `gorm:"type:text;not null;index" json:"paymentMethodId"`
	PaymentValue      float64       `gorm:"type:numeric;not null" json:"paymentValue"`
	SectorID          string        `gorm:"type:text;not null" json:"sectorId"`
	LocationID        string        `gorm:"type:text;not null;index" json:"locationId"`
	TaskID            string        `gorm:"type:text;not null" json:"taskId"`
	StatusID          string        `gorm:"type:text;not null;index" json:"statusId"`
	Notes             string        `gorm:"type:text" json:"notes,omitempty"`
	ClosedAt          *time.Time    `gorm:"type:datetime" json:"closedAt,omitempty"`

	Person            Person        `gorm:"foreignKey:PersonID;constraint:OnUpdate:Restrict,OnDelete:Restrict;" json:"person,omitempty"`
	PaymentMethod     ReferenceData `gorm:"foreignKey:PaymentMethodID;constraint:OnUpdate:Restrict,OnDelete:Restrict;" json:"paymentMethod,omitempty"`
	Sector            ReferenceData `gorm:"foreignKey:SectorID;constraint:OnUpdate:Restrict,OnDelete:Restrict;" json:"sector,omitempty"`
	Location          ReferenceData `gorm:"foreignKey:LocationID;constraint:OnUpdate:Restrict,OnDelete:Restrict;" json:"location,omitempty"`
	Task              ReferenceData `gorm:"foreignKey:TaskID;constraint:OnUpdate:Restrict,OnDelete:Restrict;" json:"task,omitempty"`
	Status            ReferenceData `gorm:"foreignKey:StatusID;constraint:OnUpdate:Restrict,OnDelete:Restrict;" json:"status,omitempty"`
}

package models

import "time"

type WorkPeriod struct {
	BaseModel
	WorkDate               time.Time  `gorm:"type:date;not null;uniqueIndex:ux_work_period_date_code" json:"workDate"`
	PeriodCode             string     `gorm:"type:text;not null;uniqueIndex:ux_work_period_date_code;index" json:"periodCode"`
	StartsAt               *time.Time `gorm:"type:datetime" json:"startsAt,omitempty"`
	EndsAt                 *time.Time `gorm:"type:datetime" json:"endsAt,omitempty"`
	Status                 string     `gorm:"type:text;not null;index" json:"status"`
	SeededFromWorkPeriodID *string    `gorm:"type:text" json:"seededFromWorkPeriodId,omitempty"`
	SeededFromWorkPeriod   *WorkPeriod `gorm:"foreignKey:SeededFromWorkPeriodID;constraint:OnUpdate:Restrict,OnDelete:Restrict;" json:"seededFromWorkPeriod,omitempty"`
	PlanItems              []WorkPlanItem `gorm:"foreignKey:WorkPeriodID" json:"planItems,omitempty"`
}

type WorkPlanItem struct {
	BaseModel
	WorkPeriodID                 string        `gorm:"type:text;not null;uniqueIndex:ux_work_period_collaborator;index" json:"workPeriodId"`
	CollaboratorID               string        `gorm:"type:text;not null;uniqueIndex:ux_work_period_collaborator;index" json:"collaboratorId"`
	IncludeFlag                  bool          `gorm:"not null;default:true" json:"includeFlag"`
	SectorID                     string        `gorm:"type:text;not null" json:"sectorId"`
	LocationID                   string        `gorm:"type:text;not null;index" json:"locationId"`
	TaskID                       string        `gorm:"type:text;not null" json:"taskId"`
	MethodID                     string        `gorm:"type:text;not null" json:"methodId"`
	PaymentValueSnapshot         float64       `gorm:"type:numeric;not null" json:"paymentValueSnapshot"`
	AssignmentStatus             string        `gorm:"type:text;not null" json:"assignmentStatus"`
	SubstitutedForCollaboratorID *string       `gorm:"type:text;index" json:"substitutedForCollaboratorId,omitempty"`
	ExceptionType                *string       `gorm:"type:text" json:"exceptionType,omitempty"`
	Comments                     string        `gorm:"type:text" json:"comments,omitempty"`

	WorkPeriod                   WorkPeriod          `gorm:"foreignKey:WorkPeriodID;constraint:OnUpdate:Restrict,OnDelete:Restrict;" json:"workPeriod,omitempty"`
	Collaborator                 CollaboratorJourney `gorm:"foreignKey:CollaboratorID;constraint:OnUpdate:Restrict,OnDelete:Restrict;" json:"collaborator,omitempty"`
	Sector                       ReferenceData       `gorm:"foreignKey:SectorID;constraint:OnUpdate:Restrict,OnDelete:Restrict;" json:"sector,omitempty"`
	Location                     ReferenceData       `gorm:"foreignKey:LocationID;constraint:OnUpdate:Restrict,OnDelete:Restrict;" json:"location,omitempty"`
	Task                         ReferenceData       `gorm:"foreignKey:TaskID;constraint:OnUpdate:Restrict,OnDelete:Restrict;" json:"task,omitempty"`
	Method                       ReferenceData       `gorm:"foreignKey:MethodID;constraint:OnUpdate:Restrict,OnDelete:Restrict;" json:"method,omitempty"`
	SubstitutedForCollaborator   *CollaboratorJourney `gorm:"foreignKey:SubstitutedForCollaboratorID;constraint:OnUpdate:Restrict,OnDelete:Restrict;" json:"substitutedForCollaborator,omitempty"`
}

package models

import "time"

type MineWellProduction struct {
	BaseModel
	WorkPeriodID   string     `gorm:"type:text;not null;index" json:"workPeriodId"`
	WorkDate       time.Time  `gorm:"type:date;not null;uniqueIndex:ux_production_date_period_location" json:"workDate"`
	PeriodCode     string     `gorm:"type:text;not null;uniqueIndex:ux_production_date_period_location" json:"periodCode"`
	LocationID     string     `gorm:"type:text;not null;uniqueIndex:ux_production_date_period_location;index" json:"locationId"`
	GramsProduced  float64    `gorm:"type:numeric;not null" json:"gramsProduced"`
	Comments       string     `gorm:"type:text" json:"comments,omitempty"`
	CreatedBy      string     `gorm:"type:text;not null" json:"createdBy"`

	WorkPeriod     WorkPeriod    `gorm:"foreignKey:WorkPeriodID;constraint:OnUpdate:Restrict,OnDelete:Restrict;" json:"workPeriod,omitempty"`
	Location       ReferenceData `gorm:"foreignKey:LocationID;constraint:OnUpdate:Restrict,OnDelete:Restrict;" json:"location,omitempty"`
	Creator        User          `gorm:"foreignKey:CreatedBy;constraint:OnUpdate:Restrict,OnDelete:Restrict;" json:"creator,omitempty"`
}

type GoldPrice struct {
	BaseModel
	QuoteDate         time.Time `gorm:"type:date;not null;uniqueIndex" json:"quoteDate"`
	QuotedAtTime      string    `gorm:"type:text" json:"quotedAtTime,omitempty"`
	PriceBRLPerGram   float64   `gorm:"column:price_brl_per_gram;type:numeric;not null" json:"priceBRLPerGram"`
	SourceName        string    `gorm:"type:text" json:"sourceName,omitempty"`
	Comments          string    `gorm:"type:text" json:"comments,omitempty"`
	CreatedBy         string    `gorm:"type:text;not null" json:"createdBy"`

	Creator           User      `gorm:"foreignKey:CreatedBy;constraint:OnUpdate:Restrict,OnDelete:Restrict;" json:"creator,omitempty"`
}

package models

import "time"

type PriceListItem struct {
	BaseModel
	Code        *string       `gorm:"type:text;uniqueIndex" json:"code,omitempty"`
	Name        string        `gorm:"type:text;not null;uniqueIndex" json:"name"`
	Description string        `gorm:"type:text" json:"description,omitempty"`
	CategoryID  string        `gorm:"type:text;not null;index:idx_price_list_category_active,priority:1" json:"categoryId"`
	PriceBRL    float64       `gorm:"column:price_brl;type:numeric;not null" json:"priceBRL"`
	Active      bool          `gorm:"not null;default:true;index:idx_price_list_category_active,priority:2" json:"active"`

	Category    ReferenceData `gorm:"foreignKey:CategoryID;constraint:OnUpdate:Restrict,OnDelete:Restrict;" json:"category,omitempty"`
}

type ExpenseTransaction struct {
	BaseModel
	CollaboratorID         string               `gorm:"type:text;not null;index" json:"collaboratorId"`
	ExpenseDate            time.Time            `gorm:"type:date;not null;index" json:"expenseDate"`
	CurrencyCode           string               `gorm:"type:text;not null;index" json:"currencyCode"`
	TotalAmount            float64              `gorm:"type:numeric;not null" json:"totalAmount"`
	CategoryID             string               `gorm:"type:text;not null;index" json:"categoryId"`
	GoldPriceID            *string              `gorm:"type:text" json:"goldPriceId,omitempty"`
	CollaboratorAgreement  bool                 `gorm:"not null;default:false" json:"collaboratorAgreement"`
	Comments               string               `gorm:"type:text" json:"comments,omitempty"`
	PostedLedgerGroupID    *string              `gorm:"type:text" json:"postedLedgerGroupId,omitempty"`
	CreatedBy              string               `gorm:"type:text;not null" json:"createdBy"`

	Collaborator           CollaboratorJourney  `gorm:"foreignKey:CollaboratorID;constraint:OnUpdate:Restrict,OnDelete:Restrict;" json:"collaborator,omitempty"`
	Category               ReferenceData        `gorm:"foreignKey:CategoryID;constraint:OnUpdate:Restrict,OnDelete:Restrict;" json:"category,omitempty"`
	GoldPrice              *GoldPrice           `gorm:"foreignKey:GoldPriceID;constraint:OnUpdate:Restrict,OnDelete:Restrict;" json:"goldPrice,omitempty"`
	Creator                User                 `gorm:"foreignKey:CreatedBy;constraint:OnUpdate:Restrict,OnDelete:Restrict;" json:"creator,omitempty"`
	Items                  []ExpenseItem        `gorm:"foreignKey:ExpenseID" json:"items,omitempty"`
}

type ExpenseItem struct {
	BaseModel
	ExpenseID          string         `gorm:"type:text;not null;index" json:"expenseId"`
	PriceListItemID    *string        `gorm:"type:text;index" json:"priceListItemId,omitempty"`
	ItemNameSnapshot   string         `gorm:"type:text;not null" json:"itemNameSnapshot"`
	Quantity           float64        `gorm:"type:numeric;not null" json:"quantity"`
	UnitPrice          float64        `gorm:"type:numeric;not null" json:"unitPrice"`
	TotalPrice         float64        `gorm:"type:numeric;not null" json:"totalPrice"`
	Comments           string         `gorm:"type:text" json:"comments,omitempty"`

	Expense            ExpenseTransaction `gorm:"foreignKey:ExpenseID;constraint:OnUpdate:Restrict,OnDelete:Restrict;" json:"expense,omitempty"`
	PriceListItem      *PriceListItem     `gorm:"foreignKey:PriceListItemID;constraint:OnUpdate:Restrict,OnDelete:Restrict;" json:"priceListItem,omitempty"`
}

package models

type EarningAccrualBatch struct {
	BaseModel
	WorkPeriodID   string               `gorm:"type:text;not null;uniqueIndex;index" json:"workPeriodId"`
	AccrualStatus  string               `gorm:"type:text;not null;index" json:"accrualStatus"`
	Comments       string               `gorm:"type:text" json:"comments,omitempty"`
	CreatedBy      string               `gorm:"type:text;not null" json:"createdBy"`

	WorkPeriod     WorkPeriod           `gorm:"foreignKey:WorkPeriodID;constraint:OnUpdate:Restrict,OnDelete:Restrict;" json:"workPeriod,omitempty"`
	Creator        User                 `gorm:"foreignKey:CreatedBy;constraint:OnUpdate:Restrict,OnDelete:Restrict;" json:"creator,omitempty"`
	Items          []EarningAccrualItem `gorm:"foreignKey:AccrualBatchID" json:"items,omitempty"`
}

type EarningAccrualItem struct {
	BaseModel
	AccrualBatchID       string               `gorm:"type:text;not null;index" json:"accrualBatchId"`
	CollaboratorID       string               `gorm:"type:text;not null;index" json:"collaboratorId"`
	WorkPlanItemID       *string              `gorm:"type:text;index" json:"workPlanItemId,omitempty"`
	MethodID             string               `gorm:"type:text;not null" json:"methodId"`
	CurrencyCode         string               `gorm:"type:text;not null" json:"currencyCode"`
	CalculationBasisJSON string               `gorm:"type:text;not null" json:"calculationBasisJson"`
	GrossAmount          float64              `gorm:"type:numeric;not null" json:"grossAmount"`
	TransferAmount       float64              `gorm:"type:numeric;not null;default:0" json:"transferAmount"`
	NetAmount            float64              `gorm:"type:numeric;not null" json:"netAmount"`
	HoldReason           *string              `gorm:"type:text" json:"holdReason,omitempty"`
	LedgerEntryID        *string              `gorm:"type:text;index" json:"ledgerEntryId,omitempty"`
	Status               string               `gorm:"type:text;not null;index" json:"status"`
	Comments             string               `gorm:"type:text" json:"comments,omitempty"`

	AccrualBatch         EarningAccrualBatch  `gorm:"foreignKey:AccrualBatchID;constraint:OnUpdate:Restrict,OnDelete:Restrict;" json:"accrualBatch,omitempty"`
	Collaborator         CollaboratorJourney  `gorm:"foreignKey:CollaboratorID;constraint:OnUpdate:Restrict,OnDelete:Restrict;" json:"collaborator,omitempty"`
	WorkPlanItem         *WorkPlanItem        `gorm:"foreignKey:WorkPlanItemID;constraint:OnUpdate:Restrict,OnDelete:Restrict;" json:"workPlanItem,omitempty"`
	Method               ReferenceData        `gorm:"foreignKey:MethodID;constraint:OnUpdate:Restrict,OnDelete:Restrict;" json:"method,omitempty"`
}

package models

import "time"

type CurrentAccountEntry struct {
	BaseModel
	RevertedEntryID  *string               `gorm:"type:text;index" json:"revertedEntryId,omitempty"`
	CollaboratorID   string                `gorm:"type:text;not null;index:idx_ledger_collaborator_entry_date,priority:1" json:"collaboratorId"`
	EntryDate        time.Time             `gorm:"type:date;not null;index:idx_ledger_collaborator_entry_date,priority:2" json:"entryDate"`
	SourceType       string                `gorm:"type:text;not null;index:idx_ledger_source,priority:1" json:"sourceType"`
	SourceID         *string               `gorm:"type:text;index:idx_ledger_source,priority:2" json:"sourceId,omitempty"`
	LedgerGroupID    *string               `gorm:"type:text;index" json:"ledgerGroupId,omitempty"`
	MethodID         *string               `gorm:"type:text" json:"methodId,omitempty"`
	CurrencyCode     string                `gorm:"type:text;not null;index:idx_ledger_currency_cd,priority:1" json:"currencyCode"`
	CDFlag           string                `gorm:"column:cd_flag;type:text;not null;index:idx_ledger_currency_cd,priority:2" json:"cdFlag"`
	ItemDescription  string                `gorm:"type:text;not null" json:"itemDescription"`
	Quantity         float64               `gorm:"type:numeric;not null;default:1" json:"quantity"`
	UnitPrice        float64               `gorm:"type:numeric;not null" json:"unitPrice"`
	TotalPrice       float64               `gorm:"type:numeric;not null" json:"totalPrice"`
	Comments         string                `gorm:"type:text" json:"comments,omitempty"`
	Status           string                `gorm:"type:text;not null;default:active" json:"status"`
	CreatedBy        string                `gorm:"type:text;not null" json:"createdBy"`

	RevertedEntry    *CurrentAccountEntry  `gorm:"foreignKey:RevertedEntryID;constraint:OnUpdate:Restrict,OnDelete:Restrict;" json:"revertedEntry,omitempty"`
	Collaborator     CollaboratorJourney   `gorm:"foreignKey:CollaboratorID;constraint:OnUpdate:Restrict,OnDelete:Restrict;" json:"collaborator,omitempty"`
	Method           *ReferenceData        `gorm:"foreignKey:MethodID;constraint:OnUpdate:Restrict,OnDelete:Restrict;" json:"method,omitempty"`
	Creator          User                  `gorm:"foreignKey:CreatedBy;constraint:OnUpdate:Restrict,OnDelete:Restrict;" json:"creator,omitempty"`
}

package models

type AuditLog struct {
	BaseModel
	ActorUserID string `gorm:"type:text;not null;index" json:"actorUserId"`
	Action      string `gorm:"type:text;not null" json:"action"`
	EntityType  string `gorm:"type:text;not null;index:idx_audit_entity,priority:1" json:"entityType"`
	EntityID    string `gorm:"type:text;not null;index:idx_audit_entity,priority:2" json:"entityId"`
	BeforeJSON  string `gorm:"type:text" json:"beforeJson,omitempty"`
	AfterJSON   string `gorm:"type:text" json:"afterJson,omitempty"`

	Actor       User   `gorm:"foreignKey:ActorUserID;constraint:OnUpdate:Restrict,OnDelete:Restrict;" json:"actor,omitempty"`
}

type SystemSetting struct {
	ID          string `gorm:"type:text;primaryKey" json:"id"`
	Key         string `gorm:"type:text;not null;uniqueIndex" json:"key"`
	Value       string `gorm:"type:text;not null" json:"value"`
	Description string `gorm:"type:text" json:"description,omitempty"`
	UpdatedBy   string `gorm:"type:text;not null" json:"updatedBy"`
	UpdatedAt   int64  `gorm:"not null" json:"updatedAt"`

	Updater     User   `gorm:"foreignKey:UpdatedBy;constraint:OnUpdate:Restrict,OnDelete:Restrict;" json:"updater,omitempty"`
}

Recommended improvement in actual code: make UpdatedAt a time.Time instead of int64 if you want consistency with the rest of the models.

A cleaner version is:

type SystemSetting struct {
	ID          string    `gorm:"type:text;primaryKey" json:"id"`
	Key         string    `gorm:"type:text;not null;uniqueIndex" json:"key"`
	Value       string    `gorm:"type:text;not null" json:"value"`
	Description string    `gorm:"type:text" json:"description,omitempty"`
	UpdatedBy   string    `gorm:"type:text;not null" json:"updatedBy"`
	UpdatedAt   time.Time `gorm:"not null" json:"updatedAt"`

	Updater     User      `gorm:"foreignKey:UpdatedBy;constraint:OnUpdate:Restrict,OnDelete:Restrict;" json:"updater,omitempty"`
}

models := []any{
	&User{},
	&Role{},
	&UserRole{},
	&ReferenceData{},
	&Person{},
	&CollaboratorJourney{},
	&WorkPeriod{},
	&WorkPlanItem{},
	&MineWellProduction{},
	&GoldPrice{},
	&PriceListItem{},
	&ExpenseTransaction{},
	&ExpenseItem{},
	&EarningAccrualBatch{},
	&EarningAccrualItem{},
	&CurrentAccountEntry{},
	&AuditLog{},
	&SystemSetting{},
}

For production, prefer SQL migrations as the source of truth and use AutoMigrate sparingly.

Recommended migration folder:

/migrations
  000001_init_schema.up.sql
  000001_init_schema.down.sql
  000002_seed_reference_data.up.sql
  000002_seed_reference_data.down.sql
  000003_seed_roles_and_settings.up.sql
  000003_seed_roles_and_settings.down.sql

PRAGMA foreign_keys = ON;

CREATE TABLE users (
  id TEXT PRIMARY KEY,
  username TEXT NOT NULL UNIQUE,
  email TEXT NOT NULL UNIQUE,
  password_hash TEXT NOT NULL,
  display_name TEXT NOT NULL,
  active INTEGER NOT NULL DEFAULT 1,
  last_login_at DATETIME NULL,
  created_at DATETIME NOT NULL,
  updated_at DATETIME NOT NULL
);

CREATE TABLE roles (
  id TEXT PRIMARY KEY,
  code TEXT NOT NULL UNIQUE,
  label TEXT NOT NULL,
  created_at DATETIME NOT NULL,
  updated_at DATETIME NOT NULL
);

CREATE TABLE user_roles (
  id TEXT PRIMARY KEY,
  user_id TEXT NOT NULL,
  role_id TEXT NOT NULL,
  created_at DATETIME NOT NULL,
  CONSTRAINT fk_user_roles_user FOREIGN KEY (user_id) REFERENCES users(id) ON UPDATE RESTRICT ON DELETE RESTRICT,
  CONSTRAINT fk_user_roles_role FOREIGN KEY (role_id) REFERENCES roles(id) ON UPDATE RESTRICT ON DELETE RESTRICT
);
CREATE UNIQUE INDEX ux_user_roles_user_role ON user_roles(user_id, role_id);

CREATE TABLE reference_data (
  id TEXT PRIMARY KEY,
  type TEXT NOT NULL,
  code TEXT NOT NULL,
  label TEXT NOT NULL,
  description TEXT NULL,
  active INTEGER NOT NULL DEFAULT 1,
  sort_order INTEGER NOT NULL DEFAULT 0,
  metadata_json TEXT NULL,
  created_at DATETIME NOT NULL,
  updated_at DATETIME NOT NULL
);
CREATE UNIQUE INDEX ux_reference_data_type_code ON reference_data(type, code);
CREATE INDEX idx_reference_data_type_active_sort ON reference_data(type, active, sort_order);

CREATE TABLE people (
  id TEXT PRIMARY KEY,
  name TEXT NOT NULL,
  address TEXT NULL,
  phone TEXT NULL,
  email TEXT NULL,
  cpf TEXT NULL,
  bank_data TEXT NULL,
  pix_key TEXT NULL,
  emergency_contact_name TEXT NULL,
  emergency_contact_phone TEXT NULL,
  emergency_contact_notes TEXT NULL,
  status_id TEXT NOT NULL,
  notes TEXT NULL,
  created_at DATETIME NOT NULL,
  updated_at DATETIME NOT NULL,
  CONSTRAINT fk_people_status FOREIGN KEY (status_id) REFERENCES reference_data(id) ON UPDATE RESTRICT ON DELETE RESTRICT
);
CREATE UNIQUE INDEX ux_people_name ON people(name);
CREATE UNIQUE INDEX ux_people_phone ON people(phone) WHERE phone IS NOT NULL;
CREATE UNIQUE INDEX ux_people_email ON people(email) WHERE email IS NOT NULL;
CREATE UNIQUE INDEX ux_people_cpf ON people(cpf) WHERE cpf IS NOT NULL;
CREATE UNIQUE INDEX ux_people_pix_key ON people(pix_key) WHERE pix_key IS NOT NULL;
CREATE INDEX idx_people_status_id ON people(status_id);

CREATE TABLE collaborator_journeys (
  id TEXT PRIMARY KEY,
  person_id TEXT NOT NULL,
  journey_start_date DATE NOT NULL,
  default_end_date DATE NOT NULL,
  extension_days INTEGER NOT NULL DEFAULT 0,
  projected_end_date DATE NOT NULL,
  payment_method_id TEXT NOT NULL,
  payment_value NUMERIC NOT NULL,
  sector_id TEXT NOT NULL,
  location_id TEXT NOT NULL,
  task_id TEXT NOT NULL,
  status_id TEXT NOT NULL,
  notes TEXT NULL,
  closed_at DATETIME NULL,
  created_at DATETIME NOT NULL,
  updated_at DATETIME NOT NULL,
  CONSTRAINT fk_collab_person FOREIGN KEY (person_id) REFERENCES people(id) ON UPDATE RESTRICT ON DELETE RESTRICT,
  CONSTRAINT fk_collab_payment_method FOREIGN KEY (payment_method_id) REFERENCES reference_data(id) ON UPDATE RESTRICT ON DELETE RESTRICT,
  CONSTRAINT fk_collab_sector FOREIGN KEY (sector_id) REFERENCES reference_data(id) ON UPDATE RESTRICT ON DELETE RESTRICT,
  CONSTRAINT fk_collab_location FOREIGN KEY (location_id) REFERENCES reference_data(id) ON UPDATE RESTRICT ON DELETE RESTRICT,
  CONSTRAINT fk_collab_task FOREIGN KEY (task_id) REFERENCES reference_data(id) ON UPDATE RESTRICT ON DELETE RESTRICT,
  CONSTRAINT fk_collab_status FOREIGN KEY (status_id) REFERENCES reference_data(id) ON UPDATE RESTRICT ON DELETE RESTRICT
);
CREATE INDEX idx_collab_person_id ON collaborator_journeys(person_id);
CREATE INDEX idx_collab_status_id ON collaborator_journeys(status_id);
CREATE INDEX idx_collab_projected_end_date ON collaborator_journeys(projected_end_date);
CREATE INDEX idx_collab_location_id ON collaborator_journeys(location_id);
CREATE INDEX idx_collab_payment_method_id ON collaborator_journeys(payment_method_id);

CREATE TABLE work_periods (
  id TEXT PRIMARY KEY,
  work_date DATE NOT NULL,
  period_code TEXT NOT NULL,
  starts_at DATETIME NULL,
  ends_at DATETIME NULL,
  status TEXT NOT NULL,
  seeded_from_work_period_id TEXT NULL,
  created_at DATETIME NOT NULL,
  updated_at DATETIME NOT NULL,
  CONSTRAINT fk_work_period_seeded_from FOREIGN KEY (seeded_from_work_period_id) REFERENCES work_periods(id) ON UPDATE RESTRICT ON DELETE RESTRICT
);
CREATE UNIQUE INDEX ux_work_periods_date_period ON work_periods(work_date, period_code);
CREATE INDEX idx_work_periods_status ON work_periods(status);

CREATE TABLE work_plan_items (
  id TEXT PRIMARY KEY,
  work_period_id TEXT NOT NULL,
  collaborator_id TEXT NOT NULL,
  include_flag INTEGER NOT NULL DEFAULT 1,
  sector_id TEXT NOT NULL,
  location_id TEXT NOT NULL,
  task_id TEXT NOT NULL,
  method_id TEXT NOT NULL,
  payment_value_snapshot NUMERIC NOT NULL,
  assignment_status TEXT NOT NULL,
  substituted_for_collaborator_id TEXT NULL,
  exception_type TEXT NULL,
  comments TEXT NULL,
  created_at DATETIME NOT NULL,
  updated_at DATETIME NOT NULL,
  CONSTRAINT fk_plan_work_period FOREIGN KEY (work_period_id) REFERENCES work_periods(id) ON UPDATE RESTRICT ON DELETE RESTRICT,
  CONSTRAINT fk_plan_collaborator FOREIGN KEY (collaborator_id) REFERENCES collaborator_journeys(id) ON UPDATE RESTRICT ON DELETE RESTRICT,
  CONSTRAINT fk_plan_sector FOREIGN KEY (sector_id) REFERENCES reference_data(id) ON UPDATE RESTRICT ON DELETE RESTRICT,
  CONSTRAINT fk_plan_location FOREIGN KEY (location_id) REFERENCES reference_data(id) ON UPDATE RESTRICT ON DELETE RESTRICT,
  CONSTRAINT fk_plan_task FOREIGN KEY (task_id) REFERENCES reference_data(id) ON UPDATE RESTRICT ON DELETE RESTRICT,
  CONSTRAINT fk_plan_method FOREIGN KEY (method_id) REFERENCES reference_data(id) ON UPDATE RESTRICT ON DELETE RESTRICT,
  CONSTRAINT fk_plan_substituted_for FOREIGN KEY (substituted_for_collaborator_id) REFERENCES collaborator_journeys(id) ON UPDATE RESTRICT ON DELETE RESTRICT
);
CREATE UNIQUE INDEX ux_work_plan_items_work_period_collaborator ON work_plan_items(work_period_id, collaborator_id);
CREATE INDEX idx_work_plan_items_location_id ON work_plan_items(location_id);
CREATE INDEX idx_work_plan_items_substituted_for ON work_plan_items(substituted_for_collaborator_id);

CREATE TABLE mine_well_productions (
  id TEXT PRIMARY KEY,
  work_period_id TEXT NOT NULL,
  work_date DATE NOT NULL,
  period_code TEXT NOT NULL,
  location_id TEXT NOT NULL,
  grams_produced NUMERIC NOT NULL,
  comments TEXT NULL,
  created_by TEXT NOT NULL,
  created_at DATETIME NOT NULL,
  updated_at DATETIME NOT NULL,
  CONSTRAINT fk_production_work_period FOREIGN KEY (work_period_id) REFERENCES work_periods(id) ON UPDATE RESTRICT ON DELETE RESTRICT,
  CONSTRAINT fk_production_location FOREIGN KEY (location_id) REFERENCES reference_data(id) ON UPDATE RESTRICT ON DELETE RESTRICT,
  CONSTRAINT fk_production_created_by FOREIGN KEY (created_by) REFERENCES users(id) ON UPDATE RESTRICT ON DELETE RESTRICT
);
CREATE UNIQUE INDEX ux_production_date_period_location ON mine_well_productions(work_date, period_code, location_id);
CREATE INDEX idx_production_work_period_id ON mine_well_productions(work_period_id);
CREATE INDEX idx_production_location_id ON mine_well_productions(location_id);

CREATE TABLE gold_prices (
  id TEXT PRIMARY KEY,
  quote_date DATE NOT NULL,
  quoted_at_time TEXT NULL,
  price_brl_per_gram NUMERIC NOT NULL,
  source_name TEXT NULL,
  comments TEXT NULL,
  created_by TEXT NOT NULL,
  created_at DATETIME NOT NULL,
  updated_at DATETIME NOT NULL,
  CONSTRAINT fk_gold_prices_created_by FOREIGN KEY (created_by) REFERENCES users(id) ON UPDATE RESTRICT ON DELETE RESTRICT
);
CREATE UNIQUE INDEX ux_gold_prices_quote_date ON gold_prices(quote_date);
CREATE INDEX idx_gold_prices_quote_date_desc ON gold_prices(quote_date DESC);

CREATE TABLE price_list_items (
  id TEXT PRIMARY KEY,
  code TEXT NULL,
  name TEXT NOT NULL,
  description TEXT NULL,
  category_id TEXT NOT NULL,
  price_brl NUMERIC NOT NULL,
  active INTEGER NOT NULL DEFAULT 1,
  created_at DATETIME NOT NULL,
  updated_at DATETIME NOT NULL,
  CONSTRAINT fk_price_list_category FOREIGN KEY (category_id) REFERENCES reference_data(id) ON UPDATE RESTRICT ON DELETE RESTRICT
);
CREATE UNIQUE INDEX ux_price_list_items_name ON price_list_items(name);
CREATE UNIQUE INDEX ux_price_list_items_code ON price_list_items(code) WHERE code IS NOT NULL;
CREATE INDEX idx_price_list_category_active ON price_list_items(category_id, active);

CREATE TABLE expense_transactions (
  id TEXT PRIMARY KEY,
  collaborator_id TEXT NOT NULL,
  expense_date DATE NOT NULL,
  currency_code TEXT NOT NULL,
  total_amount NUMERIC NOT NULL,
  category_id TEXT NOT NULL,
  gold_price_id TEXT NULL,
  collaborator_agreement INTEGER NOT NULL DEFAULT 0,
  comments TEXT NULL,
  posted_ledger_group_id TEXT NULL,
  created_by TEXT NOT NULL,
  created_at DATETIME NOT NULL,
  updated_at DATETIME NOT NULL,
  CONSTRAINT fk_expense_collaborator FOREIGN KEY (collaborator_id) REFERENCES collaborator_journeys(id) ON UPDATE RESTRICT ON DELETE RESTRICT,
  CONSTRAINT fk_expense_category FOREIGN KEY (category_id) REFERENCES reference_data(id) ON UPDATE RESTRICT ON DELETE RESTRICT,
  CONSTRAINT fk_expense_gold_price FOREIGN KEY (gold_price_id) REFERENCES gold_prices(id) ON UPDATE RESTRICT ON DELETE RESTRICT,
  CONSTRAINT fk_expense_created_by FOREIGN KEY (created_by) REFERENCES users(id) ON UPDATE RESTRICT ON DELETE RESTRICT
);
CREATE INDEX idx_expense_transactions_collaborator_id ON expense_transactions(collaborator_id);
CREATE INDEX idx_expense_transactions_expense_date ON expense_transactions(expense_date);
CREATE INDEX idx_expense_transactions_category_id ON expense_transactions(category_id);
CREATE INDEX idx_expense_transactions_currency_code ON expense_transactions(currency_code);

CREATE TABLE expense_items (
  id TEXT PRIMARY KEY,
  expense_id TEXT NOT NULL,
  price_list_item_id TEXT NULL,
  item_name_snapshot TEXT NOT NULL,
  quantity NUMERIC NOT NULL,
  unit_price NUMERIC NOT NULL,
  total_price NUMERIC NOT NULL,
  comments TEXT NULL,
  created_at DATETIME NOT NULL,
  updated_at DATETIME NOT NULL,
  CONSTRAINT fk_expense_item_expense FOREIGN KEY (expense_id) REFERENCES expense_transactions(id) ON UPDATE RESTRICT ON DELETE RESTRICT,
  CONSTRAINT fk_expense_item_price_list FOREIGN KEY (price_list_item_id) REFERENCES price_list_items(id) ON UPDATE RESTRICT ON DELETE RESTRICT
);
CREATE INDEX idx_expense_items_expense_id ON expense_items(expense_id);
CREATE INDEX idx_expense_items_price_list_item_id ON expense_items(price_list_item_id);

CREATE TABLE earning_accrual_batches (
  id TEXT PRIMARY KEY,
  work_period_id TEXT NOT NULL,
  accrual_status TEXT NOT NULL,
  comments TEXT NULL,
  created_by TEXT NOT NULL,
  created_at DATETIME NOT NULL,
  updated_at DATETIME NOT NULL,
  CONSTRAINT fk_accrual_batch_work_period FOREIGN KEY (work_period_id) REFERENCES work_periods(id) ON UPDATE RESTRICT ON DELETE RESTRICT,
  CONSTRAINT fk_accrual_batch_created_by FOREIGN KEY (created_by) REFERENCES users(id) ON UPDATE RESTRICT ON DELETE RESTRICT
);
CREATE UNIQUE INDEX ux_accrual_batches_work_period_id ON earning_accrual_batches(work_period_id);
CREATE INDEX idx_accrual_batches_status ON earning_accrual_batches(accrual_status);

CREATE TABLE earning_accrual_items (
  id TEXT PRIMARY KEY,
  accrual_batch_id TEXT NOT NULL,
  collaborator_id TEXT NOT NULL,
  work_plan_item_id TEXT NULL,
  method_id TEXT NOT NULL,
  currency_code TEXT NOT NULL,
  calculation_basis_json TEXT NOT NULL,
  gross_amount NUMERIC NOT NULL,
  transfer_amount NUMERIC NOT NULL DEFAULT 0,
  net_amount NUMERIC NOT NULL,
  hold_reason TEXT NULL,
  ledger_entry_id TEXT NULL,
  status TEXT NOT NULL,
  comments TEXT NULL,
  created_at DATETIME NOT NULL,
  updated_at DATETIME NOT NULL,
  CONSTRAINT fk_accrual_item_batch FOREIGN KEY (accrual_batch_id) REFERENCES earning_accrual_batches(id) ON UPDATE RESTRICT ON DELETE RESTRICT,
  CONSTRAINT fk_accrual_item_collaborator FOREIGN KEY (collaborator_id) REFERENCES collaborator_journeys(id) ON UPDATE RESTRICT ON DELETE RESTRICT,
  CONSTRAINT fk_accrual_item_work_plan FOREIGN KEY (work_plan_item_id) REFERENCES work_plan_items(id) ON UPDATE RESTRICT ON DELETE RESTRICT,
  CONSTRAINT fk_accrual_item_method FOREIGN KEY (method_id) REFERENCES reference_data(id) ON UPDATE RESTRICT ON DELETE RESTRICT
);
CREATE INDEX idx_accrual_items_batch_id ON earning_accrual_items(accrual_batch_id);
CREATE INDEX idx_accrual_items_collaborator_id ON earning_accrual_items(collaborator_id);
CREATE INDEX idx_accrual_items_status ON earning_accrual_items(status);
CREATE INDEX idx_accrual_items_work_plan_item_id ON earning_accrual_items(work_plan_item_id);

CREATE TABLE current_account_entries (
  id TEXT PRIMARY KEY,
  reverted_entry_id TEXT NULL,
  collaborator_id TEXT NOT NULL,
  entry_date DATE NOT NULL,
  source_type TEXT NOT NULL,
  source_id TEXT NULL,
  ledger_group_id TEXT NULL,
  method_id TEXT NULL,
  currency_code TEXT NOT NULL,
  cd_flag TEXT NOT NULL,
  item_description TEXT NOT NULL,
  quantity NUMERIC NOT NULL DEFAULT 1,
  unit_price NUMERIC NOT NULL,
  total_price NUMERIC NOT NULL,
  comments TEXT NULL,
  status TEXT NOT NULL DEFAULT 'active',
  created_by TEXT NOT NULL,
  created_at DATETIME NOT NULL,
  updated_at DATETIME NOT NULL,
  CONSTRAINT fk_current_account_reverted_entry FOREIGN KEY (reverted_entry_id) REFERENCES current_account_entries(id) ON UPDATE RESTRICT ON DELETE RESTRICT,
  CONSTRAINT fk_current_account_collaborator FOREIGN KEY (collaborator_id) REFERENCES collaborator_journeys(id) ON UPDATE RESTRICT ON DELETE RESTRICT,
  CONSTRAINT fk_current_account_method FOREIGN KEY (method_id) REFERENCES reference_data(id) ON UPDATE RESTRICT ON DELETE RESTRICT,
  CONSTRAINT fk_current_account_created_by FOREIGN KEY (created_by) REFERENCES users(id) ON UPDATE RESTRICT ON DELETE RESTRICT
);
CREATE INDEX idx_current_account_collaborator_entry_date ON current_account_entries(collaborator_id, entry_date);
CREATE INDEX idx_current_account_currency_cd ON current_account_entries(currency_code, cd_flag);
CREATE INDEX idx_current_account_source ON current_account_entries(source_type, source_id);
CREATE INDEX idx_current_account_ledger_group_id ON current_account_entries(ledger_group_id);
CREATE INDEX idx_current_account_reverted_entry_id ON current_account_entries(reverted_entry_id);

CREATE TABLE audit_logs (
  id TEXT PRIMARY KEY,
  actor_user_id TEXT NOT NULL,
  action TEXT NOT NULL,
  entity_type TEXT NOT NULL,
  entity_id TEXT NOT NULL,
  before_json TEXT NULL,
  after_json TEXT NULL,
  created_at DATETIME NOT NULL,
  updated_at DATETIME NOT NULL,
  CONSTRAINT fk_audit_actor FOREIGN KEY (actor_user_id) REFERENCES users(id) ON UPDATE RESTRICT ON DELETE RESTRICT
);
CREATE INDEX idx_audit_logs_actor_user_id ON audit_logs(actor_user_id);
CREATE INDEX idx_audit_logs_entity ON audit_logs(entity_type, entity_id);
CREATE INDEX idx_audit_logs_created_at ON audit_logs(created_at);

CREATE TABLE system_settings (
  id TEXT PRIMARY KEY,
  key TEXT NOT NULL UNIQUE,
  value TEXT NOT NULL,
  description TEXT NULL,
  updated_by TEXT NOT NULL,
  updated_at DATETIME NOT NULL,
  CONSTRAINT fk_system_settings_updated_by FOREIGN KEY (updated_by) REFERENCES users(id) ON UPDATE RESTRICT ON DELETE RESTRICT
);

PRAGMA foreign_keys = OFF;

DROP TABLE IF EXISTS system_settings;
DROP TABLE IF EXISTS audit_logs;
DROP TABLE IF EXISTS current_account_entries;
DROP TABLE IF EXISTS earning_accrual_items;
DROP TABLE IF EXISTS earning_accrual_batches;
DROP TABLE IF EXISTS expense_items;
DROP TABLE IF EXISTS expense_transactions;
DROP TABLE IF EXISTS price_list_items;
DROP TABLE IF EXISTS gold_prices;
DROP TABLE IF EXISTS mine_well_productions;
DROP TABLE IF EXISTS work_plan_items;
DROP TABLE IF EXISTS work_periods;
DROP TABLE IF EXISTS collaborator_journeys;
DROP TABLE IF EXISTS people;
DROP TABLE IF EXISTS reference_data;
DROP TABLE IF EXISTS user_roles;
DROP TABLE IF EXISTS roles;
DROP TABLE IF EXISTS users;

PRAGMA foreign_keys = ON;

-- Person Status
INSERT INTO reference_data (id, type, code, label, description, active, sort_order, metadata_json, created_at, updated_at) VALUES
('ref-person-status-active', 'person_status', 'ACTIVE', 'Active', 'Currently under contract', 1, 10, NULL, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('ref-person-status-inactive', 'person_status', 'INACTIVE', 'Inactive', 'Out of contract but eligible to return', 1, 20, NULL, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('ref-person-status-discontinued', 'person_status', 'DISCONTINUED', 'Discontinued', 'Out of contract and not expected to return', 1, 30, NULL, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP);

-- Collaborator Status
INSERT INTO reference_data (id, type, code, label, description, active, sort_order, metadata_json, created_at, updated_at) VALUES
('ref-collab-status-active', 'collaborator_status', 'ACTIVE', 'Active', 'Available to planning', 1, 10, NULL, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('ref-collab-status-sick', 'collaborator_status', 'SICK', 'Sick', 'Took a sick day', 1, 20, NULL, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('ref-collab-status-license', 'collaborator_status', 'LICENSE', 'License', 'On leave of absence', 1, 30, NULL, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('ref-collab-status-finished', 'collaborator_status', 'FINISHED', 'Finished', 'Journey is finished', 1, 40, NULL, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP);

-- Methods
INSERT INTO reference_data (id, type, code, label, description, active, sort_order, metadata_json, created_at, updated_at) VALUES
('ref-method-daily-wages', 'method', 'DAILY_WAGES', 'Daily Wages', 'Paid per day in BRL', 1, 10, NULL, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('ref-method-salary', 'method', 'SALARY', 'Salary', 'Paid monthly in BRL', 1, 20, NULL, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('ref-method-commission', 'method', 'COMMISSION', 'Commission', 'Paid in grams of gold based on production', 1, 30, NULL, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP);

-- Sectors
INSERT INTO reference_data (id, type, code, label, description, active, sort_order, metadata_json, created_at, updated_at) VALUES
('ref-sector-mine', 'sector', 'MINE', 'Mine', NULL, 1, 10, NULL, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('ref-sector-office', 'sector', 'OFFICE', 'Office', NULL, 1, 20, NULL, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('ref-sector-canteen', 'sector', 'CANTEEN', 'Canteen', NULL, 1, 30, NULL, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('ref-sector-mill', 'sector', 'MILL', 'Mill', NULL, 1, 40, NULL, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP);

-- Locations
INSERT INTO reference_data (id, type, code, label, description, active, sort_order, metadata_json, created_at, updated_at) VALUES
('ref-location-well-1', 'location', 'WELL_1', 'well 1', NULL, 1, 10, '{"mineWell":true}', CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('ref-location-well-2', 'location', 'WELL_2', 'well 2', NULL, 1, 20, '{"mineWell":true}', CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('ref-location-well-3', 'location', 'WELL_3', 'well 3', NULL, 1, 30, '{"mineWell":true}', CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('ref-location-office', 'location', 'OFFICE', 'office', NULL, 1, 40, NULL, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('ref-location-burn-house', 'location', 'BURN_HOUSE', 'burn house', NULL, 1, 50, NULL, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('ref-location-vault-house', 'location', 'VAULT_HOUSE', 'vault house', NULL, 1, 60, NULL, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('ref-location-canteen', 'location', 'CANTEEN', 'canteen', NULL, 1, 70, NULL, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('ref-location-warehouse', 'location', 'WAREHOUSE', 'warehouse', NULL, 1, 80, NULL, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP);

-- Tasks
INSERT INTO reference_data (id, type, code, label, description, active, sort_order, metadata_json, created_at, updated_at) VALUES
('ref-task-administrador', 'task', 'ADMINISTRADOR', 'Administrador', NULL, 1, 10, NULL, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('ref-task-ajudante', 'task', 'AJUDANTE', 'Ajudante', NULL, 1, 20, NULL, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('ref-task-boroquiero', 'task', 'BOROQUIERO', 'Boroquiero', NULL, 1, 30, NULL, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('ref-task-britador', 'task', 'BRITADOR', 'Britador', NULL, 1, 40, NULL, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('ref-task-cozinheiro', 'task', 'COZINHEIRO', 'Cozinheiro', NULL, 1, 50, NULL, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('ref-task-guincheiro', 'task', 'GUINCHEIRO', 'Guincheiro', NULL, 1, 60, NULL, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('ref-task-jeriqueiro', 'task', 'JERIQUEIRO', 'Jeriqueiro', NULL, 1, 70, NULL, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('ref-task-madeirador', 'task', 'MADEIRADOR', 'Madeirador', NULL, 1, 80, NULL, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('ref-task-moinho', 'task', 'MOINHO', 'Moinho', NULL, 1, 90, NULL, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('ref-task-poco', 'task', 'POCO', 'Poço', NULL, 1, 100, NULL, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('ref-task-quebrador-pedra', 'task', 'QUEBRADOR_PEDRA', 'Quebrador Pedra', NULL, 1, 110, NULL, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('ref-task-serrador', 'task', 'SERRADOR', 'Serrador', NULL, 1, 120, NULL, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('ref-task-servicos-gerais', 'task', 'SERVICOS_GERAIS', 'Servicos Gerais', NULL, 1, 130, NULL, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('ref-task-tratorista', 'task', 'TRATORISTA', 'Tratorista', NULL, 1, 140, NULL, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP);

-- Expense Categories
INSERT INTO reference_data (id, type, code, label, description, active, sort_order, metadata_json, created_at, updated_at) VALUES
('ref-expense-canteen', 'expense_category', 'CANTEEN', 'Canteen', NULL, 1, 10, NULL, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('ref-expense-pix', 'expense_category', 'PIX', 'PIX', 'Always in BRL', 1, 20, '{"brlOnly":true}', CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('ref-expense-flights', 'expense_category', 'FLIGHTS', 'Flights', NULL, 1, 30, NULL, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('ref-expense-pay-daily-wager', 'expense_category', 'PAY_DAILY_WAGER', 'Pay Daily Wager', NULL, 1, 40, NULL, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('ref-expense-diverse', 'expense_category', 'DIVERSE', 'Diverse', NULL, 1, 50, NULL, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP);

-- Ledger Currency
INSERT INTO reference_data (id, type, code, label, description, active, sort_order, metadata_json, created_at, updated_at) VALUES
('ref-currency-brl', 'ledger_currency', 'BRL', 'Real', NULL, 1, 10, NULL, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('ref-currency-gold', 'ledger_currency', 'GOLD_GRAMS', 'Gold Grams', NULL, 1, 20, NULL, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP);

-- Ledger C/D
INSERT INTO reference_data (id, type, code, label, description, active, sort_order, metadata_json, created_at, updated_at) VALUES
('ref-cd-credit', 'ledger_cd_flag', 'CREDIT', 'Credit', NULL, 1, 10, NULL, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('ref-cd-debit', 'ledger_cd_flag', 'DEBIT', 'Debit', NULL, 1, 20, NULL, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP);

-- Period codes
INSERT INTO reference_data (id, type, code, label, description, active, sort_order, metadata_json, created_at, updated_at) VALUES
('ref-period-day', 'period_code', 'DAY', 'Day', '12-hour day shift', 1, 10, NULL, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('ref-period-night', 'period_code', 'NIGHT', 'Night', '12-hour night shift', 1, 20, NULL, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP);

DELETE FROM reference_data WHERE type IN (
  'person_status',
  'collaborator_status',
  'method',
  'sector',
  'location',
  'task',
  'expense_category',
  'ledger_currency',
  'ledger_cd_flag',
  'period_code'
);

INSERT INTO roles (id, code, label, created_at, updated_at) VALUES
('role-admin', 'ADMIN', 'Administrator', CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('role-planner', 'PLANNER', 'Planner', CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('role-mercantile-operator', 'MERCANTILE_OPERATOR', 'Mercantile Operator', CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('role-finance-viewer', 'FINANCE_VIEWER', 'Finance Viewer', CURRENT_TIMESTAMP, CURRENT_TIMESTAMP);

-- These assume a bootstrap admin user will be created before or separately.
-- If not, replace 'bootstrap-admin-user-id' after user creation.
INSERT INTO system_settings (id, key, value, description, updated_by, updated_at) VALUES
('setting-journey-default-days', 'journey_default_days', '90', 'Default collaborator journey length in days', 'bootstrap-admin-user-id', CURRENT_TIMESTAMP),
('setting-return-wait-days', 'return_wait_days', '30', 'Minimum wait between journeys', 'bootstrap-admin-user-id', CURRENT_TIMESTAMP),
('setting-salary-daily-divisor', 'salary_daily_divisor', '30', 'Divisor used to normalize monthly salary into daily accrual', 'bootstrap-admin-user-id', CURRENT_TIMESTAMP),
('setting-max-sick-days', 'max_sick_days', '3', 'Maximum sick days allowed for commissioned collaborator rules', 'bootstrap-admin-user-id', CURRENT_TIMESTAMP),
('setting-commission-projection-basis', 'commission_projection_basis', 'rolling_average', 'How projected commission is estimated', 'bootstrap-admin-user-id', CURRENT_TIMESTAMP);

DELETE FROM system_settings WHERE key IN (
  'journey_default_days',
  'return_wait_days',
  'salary_daily_divisor',
  'max_sick_days',
  'commission_projection_basis'
);

DELETE FROM roles WHERE code IN (
  'ADMIN',
  'PLANNER',
  'MERCANTILE_OPERATOR',
  'FINANCE_VIEWER'
);

Even with this schema, these rules should remain in service-layer validation:

1. only one active collaborator journey per person
2. 30-day wait before new journey unless override
3. PIX category must use BRL
4. zero-gold cannot exceed current positive gold balance without override
5. closed journeys should reject new normal postings
6. commission accrual must hold when production is missing
7. sick-day maximum of 3 for commissioned collaborator rules
8. only mine-well locations may be used for mine production
9. reversal should not be allowed twice for the same effective posting

The next best artifact is:

1. Fiber route map
2. request/response DTOs
3. service interfaces
4. repository interfaces

That will let the backend implementation begin cleanly.

All backend endpoints are versioned under:

/api/v1

Recommended route registration layout:

func RegisterRoutes(app *fiber.App, deps Dependencies) {
	api := app.Group("/api")
	v1 := api.Group("/v1")

	RegisterAuthRoutes(v1, deps.AuthHandler)
	RegisterPeopleRoutes(v1, deps.PeopleHandler, deps.AuthMiddleware)
	RegisterCollaboratorRoutes(v1, deps.CollaboratorHandler, deps.AuthMiddleware)
	RegisterReferenceDataRoutes(v1, deps.ReferenceDataHandler, deps.AuthMiddleware)
	RegisterWorkPeriodRoutes(v1, deps.WorkPeriodHandler, deps.AuthMiddleware)
	RegisterPlanningRoutes(v1, deps.PlanningHandler, deps.AuthMiddleware)
	RegisterMineProductionRoutes(v1, deps.MineProductionHandler, deps.AuthMiddleware)
	RegisterGoldPriceRoutes(v1, deps.GoldPriceHandler, deps.AuthMiddleware)
	RegisterPriceListRoutes(v1, deps.PriceListHandler, deps.AuthMiddleware)
	RegisterExpenseRoutes(v1, deps.ExpenseHandler, deps.AuthMiddleware)
	RegisterCurrentAccountRoutes(v1, deps.CurrentAccountHandler, deps.AuthMiddleware)
	RegisterReportRoutes(v1, deps.ReportHandler, deps.AuthMiddleware)
}

POST   /api/v1/auth/login
POST   /api/v1/auth/logout
GET    /api/v1/auth/me

func RegisterAuthRoutes(v1 fiber.Router, h *auth.Handler) {
	r := v1.Group("/auth")
	r.Post("/login", h.Login)
	r.Post("/logout", h.Logout)
	r.Get("/me", h.Me)
}

GET    /api/v1/people
POST   /api/v1/people
GET    /api/v1/people/:id
PUT    /api/v1/people/:id
GET    /api/v1/people/:id/journeys

func RegisterPeopleRoutes(v1 fiber.Router, h *people.Handler, auth fiber.Handler) {
	r := v1.Group("/people", auth)
	r.Get("/", h.List)
	r.Post("/", h.Create)
	r.Get("/:id", h.GetByID)
	r.Put("/:id", h.Update)
	r.Get("/:id/journeys", h.ListJourneys)
}

GET    /api/v1/collaborators
POST   /api/v1/collaborators
GET    /api/v1/collaborators/:id
PUT    /api/v1/collaborators/:id
POST   /api/v1/collaborators/:id/extend
POST   /api/v1/collaborators/:id/finish
GET    /api/v1/collaborators/:id/projection

func RegisterCollaboratorRoutes(v1 fiber.Router, h *collaborators.Handler, auth fiber.Handler) {
	r := v1.Group("/collaborators", auth)
	r.Get("/", h.List)
	r.Post("/", h.Create)
	r.Get("/:id", h.GetByID)
	r.Put("/:id", h.Update)
	r.Post("/:id/extend", h.Extend)
	r.Post("/:id/finish", h.Finish)
	r.Get("/:id/projection", h.GetProjection)
}

GET    /api/v1/reference-data
GET    /api/v1/reference-data/:type
POST   /api/v1/reference-data/:type
PUT    /api/v1/reference-data/:type/:id

func RegisterReferenceDataRoutes(v1 fiber.Router, h *referencedata.Handler, auth fiber.Handler) {
	r := v1.Group("/reference-data", auth)
	r.Get("/", h.ListTypes)
	r.Get("/:type", h.ListByType)
	r.Post("/:type", h.Create)
	r.Put("/:type/:id", h.Update)
}

GET    /api/v1/work-periods
POST   /api/v1/work-periods
GET    /api/v1/work-periods/:id
PUT    /api/v1/work-periods/:id

func RegisterWorkPeriodRoutes(v1 fiber.Router, h *workperiods.Handler, auth fiber.Handler) {
	r := v1.Group("/work-periods", auth)
	r.Get("/", h.List)
	r.Post("/", h.Create)
	r.Get("/:id", h.GetByID)
	r.Put("/:id", h.Update)
}

POST   /api/v1/work-periods/:id/plan/seed-from-previous
GET    /api/v1/work-periods/:id/plan
PUT    /api/v1/work-periods/:id/plan-items/:planItemId
POST   /api/v1/work-periods/:id/inform
POST   /api/v1/work-periods/:id/accrue
GET    /api/v1/work-periods/:id/accrual

func RegisterPlanningRoutes(v1 fiber.Router, h *planning.Handler, auth fiber.Handler) {
	r := v1.Group("/work-periods", auth)
	r.Post("/:id/plan/seed-from-previous", h.SeedFromPrevious)
	r.Get("/:id/plan", h.GetPlan)
	r.Put("/:id/plan-items/:planItemId", h.UpdatePlanItem)
	r.Post("/:id/inform", h.MarkInformed)
	r.Post("/:id/accrue", h.Accrue)
	r.Get("/:id/accrual", h.GetAccrual)
}

GET    /api/v1/mine-productions
POST   /api/v1/mine-productions
GET    /api/v1/mine-productions/:id
PUT    /api/v1/mine-productions/:id

func RegisterMineProductionRoutes(v1 fiber.Router, h *mineproduction.Handler, auth fiber.Handler) {
	r := v1.Group("/mine-productions", auth)
	r.Get("/", h.List)
	r.Post("/", h.Create)
	r.Get("/:id", h.GetByID)
	r.Put("/:id", h.Update)
}

GET    /api/v1/gold-prices
POST   /api/v1/gold-prices
GET    /api/v1/gold-prices/latest
GET    /api/v1/gold-prices/:id
PUT    /api/v1/gold-prices/:id

func RegisterGoldPriceRoutes(v1 fiber.Router, h *goldprices.Handler, auth fiber.Handler) {
	r := v1.Group("/gold-prices", auth)
	r.Get("/", h.List)
	r.Post("/", h.Create)
	r.Get("/latest", h.GetLatest)
	r.Get("/:id", h.GetByID)
	r.Put("/:id", h.Update)
}

GET    /api/v1/price-list
POST   /api/v1/price-list
GET    /api/v1/price-list/:id
PUT    /api/v1/price-list/:id
GET    /api/v1/price-list/:id/price-preview?currency=BRL|GOLD_GRAMS

func RegisterPriceListRoutes(v1 fiber.Router, h *pricelist.Handler, auth fiber.Handler) {
	r := v1.Group("/price-list", auth)
	r.Get("/", h.List)
	r.Post("/", h.Create)
	r.Get("/:id", h.GetByID)
	r.Put("/:id", h.Update)
	r.Get("/:id/price-preview", h.GetPricePreview)
}

GET    /api/v1/expenses
POST   /api/v1/expenses
GET    /api/v1/expenses/:id
POST   /api/v1/expenses/:id/revert

func RegisterExpenseRoutes(v1 fiber.Router, h *expenses.Handler, auth fiber.Handler) {
	r := v1.Group("/expenses", auth)
	r.Get("/", h.List)
	r.Post("/", h.Create)
	r.Get("/:id", h.GetByID)
	r.Post("/:id/revert", h.Revert)
}

GET    /api/v1/current-accounts/:collaboratorId/summary
GET    /api/v1/current-accounts/:collaboratorId/entries
POST   /api/v1/current-accounts/entries/:entryId/revert
POST   /api/v1/current-accounts/:collaboratorId/zero-gold
POST   /api/v1/current-accounts/:collaboratorId/close

func RegisterCurrentAccountRoutes(v1 fiber.Router, h *currentaccounts.Handler, auth fiber.Handler) {
	r := v1.Group("/current-accounts", auth)
	r.Get("/:collaboratorId/summary", h.GetSummary)
	r.Get("/:collaboratorId/entries", h.ListEntries)
	r.Post("/entries/:entryId/revert", h.RevertEntry)
	r.Post("/:collaboratorId/zero-gold", h.ZeroGold)
	r.Post("/:collaboratorId/close", h.CloseJourney)
}

GET    /api/v1/reports/dashboard
GET    /api/v1/reports/collaborator-balances
GET    /api/v1/reports/journeys-ending-soon
GET    /api/v1/reports/pending-production-accruals
GET    /api/v1/reports/mercantile-sales

func RegisterReportRoutes(v1 fiber.Router, h *reports.Handler, auth fiber.Handler) {
	r := v1.Group("/reports", auth)
	r.Get("/dashboard", h.Dashboard)
	r.Get("/collaborator-balances", h.CollaboratorBalances)
	r.Get("/journeys-ending-soon", h.JourneysEndingSoon)
	r.Get("/pending-production-accruals", h.PendingProductionAccruals)
	r.Get("/mercantile-sales", h.MercantileSales)
}

Recommended package:

/internal/shared/dto

package dto

type APIResponse[T any] struct {
	Data  T          `json:"data,omitempty"`
	Error *APIError  `json:"error,omitempty"`
	Meta  *Meta      `json:"meta,omitempty"`
}

type APIError struct {
	Code    string            `json:"code"`
	Message string            `json:"message"`
	Fields  map[string]string `json:"fields,omitempty"`
}

type Meta struct {
	Page       int   `json:"page,omitempty"`
	PageSize   int   `json:"pageSize,omitempty"`
	TotalRows  int64 `json:"totalRows,omitempty"`
	TotalPages int   `json:"totalPages,omitempty"`
}

package dto

type PageRequest struct {
	Page     int    `query:"page" json:"page"`
	PageSize int    `query:"pageSize" json:"pageSize"`
	Search   string `query:"search" json:"search,omitempty"`
	Sort     string `query:"sort" json:"sort,omitempty"`
}

package dto

type DateRangeFilter struct {
	FromDate string `query:"fromDate" json:"fromDate,omitempty"`
	ToDate   string `query:"toDate" json:"toDate,omitempty"`
}

package auth

type LoginRequest struct {
	Username string `json:"username" validate:"required"`
	Password string `json:"password" validate:"required"`
}

type LoginResponse struct {
	AccessToken string       `json:"accessToken"`
	User        CurrentUserDTO `json:"user"`
}

type CurrentUserDTO struct {
	ID          string   `json:"id"`
	Username    string   `json:"username"`
	Email       string   `json:"email"`
	DisplayName string   `json:"displayName"`
	Roles       []string `json:"roles"`
}

package people

type PersonDTO struct {
	ID                    string `json:"id"`
	Name                  string `json:"name"`
	Address               string `json:"address,omitempty"`
	Phone                 string `json:"phone,omitempty"`
	Email                 string `json:"email,omitempty"`
	CPF                   string `json:"cpf,omitempty"`
	BankData              string `json:"bankData,omitempty"`
	PIXKey                string `json:"pixKey,omitempty"`
	EmergencyContactName  string `json:"emergencyContactName,omitempty"`
	EmergencyContactPhone string `json:"emergencyContactPhone,omitempty"`
	EmergencyContactNotes string `json:"emergencyContactNotes,omitempty"`
	StatusID              string `json:"statusId"`
	StatusLabel           string `json:"statusLabel,omitempty"`
	Notes                 string `json:"notes,omitempty"`
	CreatedAt             string `json:"createdAt"`
	UpdatedAt             string `json:"updatedAt"`
}

type CreatePersonRequest struct {
	Name                  string  `json:"name" validate:"required"`
	Address               string  `json:"address,omitempty"`
	Phone                 *string `json:"phone,omitempty"`
	Email                 *string `json:"email,omitempty"`
	CPF                   *string `json:"cpf,omitempty"`
	BankData              string  `json:"bankData,omitempty"`
	PIXKey                *string `json:"pixKey,omitempty"`
	EmergencyContactName  string  `json:"emergencyContactName,omitempty"`
	EmergencyContactPhone string  `json:"emergencyContactPhone,omitempty"`
	EmergencyContactNotes string  `json:"emergencyContactNotes,omitempty"`
	StatusID              string  `json:"statusId" validate:"required"`
	Notes                 string  `json:"notes,omitempty"`
}

type UpdatePersonRequest struct {
	Name                  string  `json:"name" validate:"required"`
	Address               string  `json:"address,omitempty"`
	Phone                 *string `json:"phone,omitempty"`
	Email                 *string `json:"email,omitempty"`
	CPF                   *string `json:"cpf,omitempty"`
	BankData              string  `json:"bankData,omitempty"`
	PIXKey                *string `json:"pixKey,omitempty"`
	EmergencyContactName  string  `json:"emergencyContactName,omitempty"`
	EmergencyContactPhone string  `json:"emergencyContactPhone,omitempty"`
	EmergencyContactNotes string  `json:"emergencyContactNotes,omitempty"`
	StatusID              string  `json:"statusId" validate:"required"`
	Notes                 string  `json:"notes,omitempty"`
}

type PersonListFilter struct {
	Search   string `query:"search"`
	StatusID string `query:"statusId"`
	Page     int    `query:"page"`
	PageSize int    `query:"pageSize"`
}