@sparkerp/plugin-sdk 0.1.0 → 1.0.0

package/bundle/docs/applications/hcm/organizations.md

@@ -0,0 +1,81 @@
+---
+title: Organizations
+audience: tenant
+---
+
+# Organizations (HCM)
+
+This page documents the shipped **Organizations** screen (`hcm-organization`)
+— the top-level entity representing each legal/business organization your
+tenant manages, with its own regional and HR configuration (distinct from
+Org Units, which sit underneath it). Not for plugin developers.
+
+## Getting there
+
+Organization → Organizations.
+
+## What you see
+
+- **KPI cards**: Total, Active, Inactive, Pending Approval.
+- **Search**, plus filters for Country, Status, and Organization Type.
+- A grid: Organization, Type, Parent Organization, Country, Currency,
+  Default (whether it's your tenant's default org), Status, Actions
+  (View / Edit / Set as Default).
+- **Bulk actions**: Activate or Deactivate selected organizations — both
+  submit for approval rather than applying instantly (you'll see a hint
+  saying so before you confirm), and there's a bulk **Assign Parent**
+  action too.
+- **Import** — upload a CSV or XLSX with columns `code`, `name`,
+  `legalName`, `organizationType`, `parentCode`, `country`, `currency`
+  (`code` and `name` are required on every row).
+
+## Creating or editing an organization
+
+**New Organization** opens a form with several sections:
+
+- **Basic Information** — Organization Name, Organization Code, Short
+  Name, Legal Name, Organization Type, Parent Organization, Linked Legal
+  Entity, Description.
+- **Regional Settings** — Country, Currency, Language, Time Zone, Date
+  Format, Time Format, Number Format, Week Start Day.
+- **HCM Configuration** — Default Working Hours, Default Work Week,
+  Default Probation Period (Days), Default Employee Number
+  Prefix/Sequence, and the default Attendance Policy, Leave Policy,
+  Payroll Calendar, and Holiday Calendar to use (referenced by ID).
+- **Branding** — Logo and Favicon uploads.
+- **Address** and **Contact Information** — add one during creation, plus
+  whether it's the primary one.
+- **Status** — and whether this is your tenant's default organization.
+
+## Organization detail
+
+Click a row to open a detailed view with nine tabs:
+
+- **Overview** — every field above, plus Corporate Identifier, Tax
+  Identifier, VAT Number, Registration Number/Date/Authority under a
+  **Legal Information** section, and Child Organizations count.
+- **Hierarchy** — where this organization sits in the parent/child tree.
+- **Address** / **Contact** — manage multiple addresses/contacts, each
+  with its own type and a primary flag; **Add Address** / **Add Contact**.
+- **Legal** — edit the Legal Information fields directly.
+- **Locations**, **Cost Centers**, **Employees** — related records for
+  this organization.
+- **Documents** — **Upload Document** with a Title, Document Type, and
+  file.
+- **Settings** — a read-only, curated view of HR-wide settings relevant to
+  this organization, showing the currently effective value and whether it
+  comes from your own tenant override or the platform default (manage the
+  actual values in [HR Settings](./hr-settings.md), not here).
+- **Audit** — change history for this organization.
+
+There's also a **Statutory Registrations** section (Registration Type,
+Number, Country, Effective From/To, Status) for tracking legal
+registrations per jurisdiction, and an **Organization Relationships**
+section (link to a target organization, a relationship type, and its own
+effective dates) for modeling relationships between organizations beyond
+simple parent/child.
+
+## Related
+
+- [Org Units, Legal Entities, Business Units & more](./org-units.md)
+- [HR Settings](./hr-settings.md)

package/bundle/docs/applications/hcm/payroll-analytics.md

@@ -0,0 +1,31 @@
+---
+title: Payroll Dashboard, Reports & Country Rollup
+audience: tenant
+---
+
+# Payroll Dashboard, Reports & Country Rollup (HCM)
+
+This page documents three shipped **Payroll** analytics screens
+(`hcm-payroll`). Not for plugin developers.
+
+## Payroll Dashboard
+
+An organization-wide summary — real totals across your payroll runs,
+results, and locks.
+
+## Payroll Reports
+
+A read-only report viewer with 8 predefined report types. Pick a report
+and the relevant KPI cards, charts, and lists update to match — not a
+report builder, a fixed set of real, pre-built reports.
+
+## Cross-Country Payroll Rollup
+
+If you run payroll in more than one country, this is the one place that
+adds total payroll cost together across all of them into a single
+consolidated number — calculated live, on demand, not a separate stored
+total you have to keep in sync.
+
+## Related
+
+- [Payroll Runs](./payroll-runs.md)

package/bundle/docs/applications/hcm/payroll-post-run.md

@@ -0,0 +1,40 @@
+---
+title: Payslips, Bank Transfer, Payroll Accounting & Lock
+audience: tenant
+---
+
+# Payslips, Bank Transfer, Payroll Accounting & Lock (HCM)
+
+This page documents four shipped **Payroll** screens (`hcm-payroll`) that
+all work from a finalized [Payroll Run](./payroll-runs.md) — what happens
+after payroll is calculated. Not for plugin developers.
+
+## Payslips
+
+Generates a real, immutable PDF payslip for each employee once a run is
+finalized and published — a snapshot of that run, not something that
+changes later even if other data changes.
+
+## Bank Transfer
+
+Builds disbursement batches from a finalized run's real net pay figures —
+the actual instruction set for paying people — with an approval workflow
+and per-line reconciliation tracking (so you can confirm each payment
+actually went through).
+
+## Payroll Accounting
+
+Generates balanced accounting journals from a finalized run, using each
+salary component's own debit/credit account mapping. You can **post** a
+journal, or **reverse** it if something needs correcting.
+
+## Payroll Lock
+
+Locks a finalized run at the period or run level so it can't be changed
+further. If you genuinely need to reopen a locked run, there's a real
+unlock process — it goes through a single-stage approval, opens for a
+limited, time-boxed window, and then re-locks automatically.
+
+## Related
+
+- [Payroll Runs](./payroll-runs.md)

package/bundle/docs/applications/hcm/payroll-runs.md

@@ -0,0 +1,30 @@
+---
+title: Payroll Runs
+audience: tenant
+---
+
+# Payroll Runs (HCM)
+
+This page documents the shipped **Payroll Runs** screen (`hcm-payroll`) —
+the actual payroll calculation engine, and the one screen every other
+Payroll screen's data feeds into. Not for plugin developers.
+
+**Who this is for:** payroll administrators running payroll each period.
+
+## What it does
+
+Runs the real payroll calculation for a period, pulling in every
+employee's salary structure, earnings, deductions, bonuses, incentives,
+overtime, adjustments, and tax — and produces each employee's actual net
+pay for that run.
+
+Everything downstream — [Payslips](./payroll-post-run.md), [Bank
+Transfer](./payroll-post-run.md), [Payroll Accounting](./payroll-post-run.md),
+and [Payroll Lock](./payroll-post-run.md) — works off a finalized run from
+this screen.
+
+## Related
+
+- [Employee Compensation, Bonuses, Incentives, Overtime & Adjustments](./payroll-transactions.md)
+- [Tax Management](./payroll-tax.md)
+- [Payslips, Bank Transfer, Payroll Accounting & Lock](./payroll-post-run.md)

package/bundle/docs/applications/hcm/payroll-setup.md

@@ -0,0 +1,38 @@
+---
+title: Salary Components, Salary Structures, Earnings & Deductions
+audience: tenant
+---
+
+# Salary Components, Salary Structures, Earnings & Deductions (HCM)
+
+This page documents four shipped **Payroll** setup screens (`hcm-payroll`)
+— the master data everything else in Payroll is built from. Not for
+plugin developers.
+
+**Who this is for:** payroll administrators setting these up (and
+revisiting them when compensation rules change).
+
+## Salary Components
+
+The building blocks of pay — define each individual component (e.g. Basic
+Pay, HRA, Provident Fund) with its own calculation rule and versioning.
+Changing a component goes through a single-stage approval before it takes
+effect.
+
+## Earnings & Deductions
+
+Two focused views over the exact same Salary Components data — Earnings
+shows only the components that add to pay, Deductions shows only the ones
+that subtract from it. Same create/edit/versioning/approval behavior as
+Salary Components; just filtered by type.
+
+## Salary Structures
+
+Combine components into a named structure (a template you assign to
+employees), so you don't have to pick components one by one for every
+person.
+
+## Related
+
+- [Employee Compensation, Bonuses, Incentives, Overtime & Adjustments](./payroll-transactions.md)
+- [Payroll Runs](./payroll-runs.md)

package/bundle/docs/applications/hcm/payroll-tax.md

@@ -0,0 +1,21 @@
+---
+title: Tax Management
+audience: tenant
+---
+
+# Tax Management (HCM)
+
+This page documents the shipped **Tax Management** screen (`hcm-payroll`)
+— income tax slabs, regimes, and employee declarations. Not for plugin
+developers.
+
+## What it does
+
+Configure tax slabs and regimes, and manage employee tax declarations.
+This is the real engine behind payroll's tax calculation — before this
+screen existed, every payroll run simply calculated zero tax; now real tax
+is computed as part of each [Payroll Run](./payroll-runs.md).
+
+## Related
+
+- [Payroll Runs](./payroll-runs.md)

package/bundle/docs/applications/hcm/payroll-transactions.md

@@ -0,0 +1,43 @@
+---
+title: Employee Compensation, Bonuses, Incentives, Overtime & Adjustments
+audience: tenant
+---
+
+# Employee Compensation, Bonuses, Incentives, Overtime & Adjustments (HCM)
+
+This page documents five shipped, per-employee **Payroll** transaction
+screens (`hcm-payroll`) — the things that affect what one specific person
+gets paid, on top of their base structure. Not for plugin developers.
+
+## Employee Compensation
+
+Assign a Salary Structure to an employee and set their actual compensation
+amounts against it.
+
+## Bonuses
+
+One-off bonus payments for an employee.
+
+## Incentives
+
+Incentive payouts against a reusable incentive plan — fixed amount,
+percentage, formula-based, or tiered, depending on how the plan is set up.
+
+## Overtime (Payroll)
+
+Overtime pay against a reusable overtime policy — either a flat rate or a
+tiered-hours multiplier. (This is the payroll side of overtime; see
+[Late & Early Records, Overtime & Regularization](./attendance-exceptions.md)
+for where the overtime hours themselves are tracked and approved.)
+
+## Payroll Adjustments
+
+The simplest of these five: a generic, ad-hoc correction for one employee
+— just a signed amount (positive adds to pay, negative deducts), no plan
+or policy behind it, for one-off corrections that don't fit any of the
+above.
+
+## Related
+
+- [Salary Components, Salary Structures, Earnings & Deductions](./payroll-setup.md)
+- [Payroll Runs](./payroll-runs.md)

package/bundle/docs/applications/hcm/performance-analytics.md

@@ -0,0 +1,23 @@
+---
+title: Performance Dashboard & Reports
+audience: tenant
+---
+
+# Performance Dashboard & Reports (HCM)
+
+This page documents two shipped **Performance** analytics screens
+(`hcm-performance`). Not for plugin developers.
+
+## Performance Dashboard
+
+Real KPI cards: Active Cycles, Total Goals, Goal Completion %, Reviews
+Completed, Appraisals Completed, Average Rating, and High Performers —
+all live counts for your tenant, not sample data.
+
+## Performance Reports
+
+A reporting view over the same real Performance data.
+
+## Related
+
+- [Performance Cycles, Goals, Goal Plans & KPIs](./performance-cycles-and-goals.md)

package/bundle/docs/applications/hcm/performance-appraisals.md

@@ -0,0 +1,50 @@
+---
+title: Appraisals, Self Assessment, Manager Assessment & 360 Feedback
+audience: tenant
+---
+
+# Appraisals, Self Assessment, Manager Assessment & 360 Feedback (HCM)
+
+This page documents four shipped **Performance** screens
+(`hcm-performance`) that together form the formal review lifecycle for one
+employee in one cycle. Not for plugin developers.
+
+## Appraisals
+
+The overall appraisal record, showing Employee, Manager, Cycle, Due Date,
+Self Rating, and overall Progress %. The KPI row shows how many are
+**Pending Self Review**, in **Manager Review**, in **HR Review**, plus the
+**Avg Final Rating** across everyone — so you can see where the bottleneck
+is if appraisals are stuck.
+
+## Self Assessment
+
+The employee-owned first stage. You rate yourself against your goals and
+KPIs for the cycle; the grid tracks your Progress % and Self Rating
+against your Due Date. Status moves through Draft → Submitted → (if a
+manager sends it back for changes) Returned.
+
+## Manager Assessment
+
+The manager's independent rating stage, done after the employee's Self
+Assessment is submitted. The grid shows Self Rating side-by-side with
+**Manager Rating** and a **Variance** column — the gap between the two.
+The KPI row includes a **High Variance** count, so HR can spot appraisals
+where the employee and manager rated things very differently and may want
+a closer look or a calibration conversation, rather than only being
+visible buried in individual records.
+
+## 360 Feedback
+
+Multi-source feedback — self, manager, peers, direct reports, and
+customers, depending on how it's configured. The grid tracks Reviewers
+(how many are involved), Completed (how many have responded), Completion
+%, and an aggregate Score once enough responses are in. The KPI row
+(Total, In Progress, Closed, Avg Completion, Avg Score) gives you a
+program-wide view of how 360 reviews are going.
+
+## Related
+
+- [Performance Cycles, Goals, Goal Plans & KPIs](./performance-cycles-and-goals.md)
+- [Ratings](./performance-ratings.md)
+- [PIPs](./performance-pips.md)

package/bundle/docs/applications/hcm/performance-continuous-feedback.md

@@ -0,0 +1,23 @@
+---
+title: Continuous Feedback
+audience: tenant
+---
+
+# Continuous Feedback (HCM)
+
+This page documents the shipped **Continuous Feedback** screen
+(`hcm-performance`) — always-available, informal feedback, separate from
+the formal cycle-based reviews. Not for plugin developers.
+
+## What it does
+
+Give feedback, request feedback, or recognize a colleague at any time —
+not tied to a review cycle or waiting for a formal appraisal. Each entry
+records who it's From and To, its Type, an optional Rating, and when it
+was Submitted. The KPI row (Given, Received, Requested, Recognition) lets
+you see your own feedback activity at a glance — how much you've given
+vs. received, and how much of it was recognition specifically.
+
+## Related
+
+- [Appraisals, Self Assessment, Manager Assessment & 360 Feedback](./performance-appraisals.md)

package/bundle/docs/applications/hcm/performance-cycles-and-goals.md

@@ -0,0 +1,54 @@
+---
+title: Performance Cycles, Goals, Goal Plans & KPIs
+audience: tenant
+---
+
+# Performance Cycles, Goals, Goal Plans & KPIs (HCM)
+
+This page documents four shipped **Performance** screens (`hcm-performance`)
+— the foundation every other Performance screen builds on. Not for plugin
+developers.
+
+## Performance Cycles
+
+**Create Performance Cycle** — name it, pick a **Cycle Type**, and set an
+**Owner**, plus two separate date ranges: **Goal Start/Due Date** (the
+window for setting goals) and **Performance Start/End Date** (the actual
+review period) — these don't have to line up exactly, since goal-setting
+often needs to happen before the formal review window opens. The KPI row
+(Total Cycles, Draft, Planned, Active, Completed) tracks how a cycle
+moves through its lifecycle. Every other Performance screen references a
+cycle via this Cycle Code.
+
+## Goal Plans
+
+Reusable goal frameworks, not any one person's actual goal. **Create Goal
+Plan** — name it, pick a **Plan Type** and the **Performance Cycle** it
+belongs to, and turn on **Require Approval** if goals created from this
+plan need sign-off. The grid shows how many Templates and how many
+Employees are actually **Assigned** to each plan.
+
+## Goals
+
+An employee's actual goal-setting. **Create Goal** — pick the **Employee**
+and **Performance Cycle**, name the goal, set its **Goal Type**,
+**Priority**, **Target**, **Weight %** (how much this goal counts toward
+the overall rating), and Start/Due dates. New goals go through Employee →
+Manager approval, tracked by the KPI row: Total Goals, On Track, At Risk,
+Completed, Pending Approval — so both employee and manager can see at a
+glance which goals need attention.
+
+## KPIs
+
+A master list of measurable targets you can attach to a Goal that's
+measured by a KPI type, rather than a plain checkbox target. **Create
+KPI** — name it, set its **KPI Type**, **Measurement Type**, **Direction**
+(e.g. higher-is-better vs. lower-is-better), **Unit**, **Target**, and
+**Weight %**. The grid tracks real Actual vs. Target and calculates
+**Achievement %** for you; the KPI row (Total KPIs, On Track, At Risk, Off
+Track, Avg Achievement %) rolls that up across every KPI.
+
+## Related
+
+- [Appraisals, Self Assessment, Manager Assessment & 360 Feedback](./performance-appraisals.md)
+- [OKRs](./performance-okrs.md)

package/bundle/docs/applications/hcm/performance-okrs.md

@@ -0,0 +1,33 @@
+---
+title: OKRs
+audience: tenant
+---
+
+# OKRs (HCM)
+
+This page documents the shipped **OKRs** screen (`hcm-performance`) —
+Objectives and Key Results, as its own tree structure alongside Goals. Not
+for plugin developers.
+
+## Creating an objective
+
+**Create Objective** — name it, pick an **Objective Type** and **Level**
+(so you can build a company → team → individual hierarchy), the
+**Cycle** it belongs to, and optionally a **Parent Objective** to align it
+under. Turn on **Require Approval** if it needs sign-off before it counts.
+
+## How progress works
+
+Each objective's **Progress** is a real weighted roll-up of its Key
+Results — not something you set by hand. Add Key Results underneath an
+objective (shown in the grid's Key Results count), and the objective's own
+progress reflects how those key results are actually tracking. A circular
+alignment (an objective that ends up depending on itself through a chain
+of parent/child links) is actively prevented, not just discouraged.
+
+The KPI row — Objectives, Key Results, On Track, At Risk, Avg Completion —
+gives you a program-wide read on how OKRs are progressing this cycle.
+
+## Related
+
+- [Performance Cycles, Goals, Goal Plans & KPIs](./performance-cycles-and-goals.md)

package/bundle/docs/applications/hcm/performance-pips.md

@@ -0,0 +1,29 @@
+---
+title: PIPs (Performance Improvement Plans)
+audience: tenant
+---
+
+# PIPs — Performance Improvement Plans (HCM)
+
+This page documents the shipped **PIPs** screen (`hcm-performance`) —
+formal improvement plans for underperforming employees. Not for plugin
+developers.
+
+## Creating a PIP
+
+**Create PIP** — pick the **Employee**, a **PIP Type**, and write the
+**Reason** and **Performance Concerns** clearly (these are what the
+employee and manager both work from through the plan). Set **Start Date**
+and **End Date**, and a **Review Frequency** for how often you'll check in
+during the plan.
+
+## Tracking progress
+
+The grid shows Employee, Manager, Type, Start/End Date, Status, and
+Progress % for every PIP. The KPI row (Total PIPs, On Track, At Risk,
+Completed, Pending Approval) gives HR a program-wide view of how many
+active PIPs need attention.
+
+## Related
+
+- [Appraisals, Self Assessment, Manager Assessment & 360 Feedback](./performance-appraisals.md)

package/bundle/docs/applications/hcm/performance-ratings.md

@@ -0,0 +1,25 @@
+---
+title: Ratings
+audience: tenant
+---
+
+# Ratings (HCM)
+
+This page documents the shipped **Ratings** screen (`hcm-performance`) —
+the rating scale configuration used when scoring performance. Not for
+plugin developers.
+
+## Creating a rating scale
+
+**Create Rating Scale** — name it, pick a **Scale Type**, set the
+**Minimum** and **Maximum** values, a Description, and whether this is
+your **Default Scale**. The grid shows every scale's Minimum/Maximum,
+Version, and whether it's currently Default — you can version a scale
+over time rather than editing history away.
+
+Appraisals, Self Assessment, and Manager Assessment all reference a scale
+defined here — set this up before running your first cycle.
+
+## Related
+
+- [Appraisals, Self Assessment, Manager Assessment & 360 Feedback](./performance-appraisals.md)

package/bundle/docs/applications/hcm/positions.md

@@ -0,0 +1,67 @@
+---
+title: Positions
+audience: tenant
+---
+
+# Positions (HCM)
+
+This page documents the shipped **Positions** screen (`hcm-employee`) —
+managing job positions (as distinct from the people who fill them). Not
+for plugin developers.
+
+## Getting there
+
+Under Organization / Job Architecture in the HCM menu ("Positions" and
+"Job Positions" both point to the same screen).
+
+## What you see
+
+- **KPI cards**: Total, Occupied, Vacant, Frozen — all real, live counts.
+  "Occupied" means at least one active employee currently holds that
+  position; it doesn't require the position's own status to say so.
+- **Search and filter** by Department, Status, Employment Type.
+- **Bulk actions**: Change Department, Change Status.
+- A grid with status chips and per-row quick actions.
+
+## Creating and editing a position
+
+**Add/Edit Position** covers the position's department, job structure
+(designation, grade), reporting structure (who this position reports to),
+and workforce details. You can also set a **Position Type** (Regular,
+Temporary, Contract, Project, Seasonal, Internship, Apprentice, Consultant,
+Other).
+
+## Freezing a position
+
+**Freeze Position** — and other status changes (on hold, cancelled, back to
+draft) — goes through an approval gate rather than applying immediately:
+changing status creates a pending request, not an instant change.
+
+## Position detail
+
+Click a position to open a read-only detail view (separate from the Edit
+dialog) with four sections: Organization/Job Structure, Reporting,
+Workforce, and:
+
+- **View Employee** — jumps to the profile of whoever currently holds this
+  position (hidden if it's vacant).
+- **View History** — shows every tracked change to this position (freezes,
+  transfers, reclassifications, closures, manager changes), each with who
+  requested it and its current status.
+- **Edit Position** / **Freeze Position** as above.
+
+## Known gaps
+
+- **No Location field on positions** — even though Location is tracked
+  elsewhere in HCM, it's not yet a field on Position itself.
+- **No budget tracking** — there's no "is this position budgeted" flag or
+  budget-approval integration with Finance.
+- **Occupancy is shown as a simple vacant/occupied split**, not a
+  three-way "fully staffed / partially staffed / vacant" for positions that
+  allow more than one headcount.
+- **View History shows a summary, not a full itemized log** — the latest
+  change and a count, not a scrollable list of every past change.
+
+## Related
+
+- [Reporting Structure & Organization Structure](./org-structure.md)

package/bundle/docs/applications/hcm/recruitment-agencies-and-sources.md

@@ -0,0 +1,26 @@
+---
+title: Recruitment Agencies & Sources
+audience: tenant
+---
+
+# Recruitment Agencies & Sources (HCM)
+
+This page documents two shipped **Recruitment** reference screens
+(`hcm-recruitment`). Not for plugin developers.
+
+## Recruitment Agencies
+
+Manage external recruitment agencies you work with — their contacts,
+which openings you've assigned them, candidate submissions they've sent
+in, and a status workflow (submit → approve, etc.) for the agency
+relationship itself.
+
+## Recruitment Sources
+
+A catalog of where your candidates come from (e.g. referral, agency,
+careers page, job board) — used to tag and report on which channels are
+actually bringing in candidates.
+
+## Related
+
+- [Recruitment Dashboard & Reports](./recruitment-analytics.md)

package/bundle/docs/applications/hcm/recruitment-analytics.md

@@ -0,0 +1,25 @@
+---
+title: Recruitment Dashboard & Reports
+audience: tenant
+---
+
+# Recruitment Dashboard & Reports (HCM)
+
+This page documents two shipped **Recruitment** analytics screens
+(`hcm-recruitment`). Not for plugin developers.
+
+## Recruitment Dashboard
+
+Real KPI counts and chart breakdowns across the whole recruitment pipeline
+— openings, applications, interviews, offers, and more, all live counts.
+
+## Recruitment Reports
+
+A separate, filterable/drill-down tabular reporting screen — deliberately
+not a rebuild of the Dashboard's own charts; use the Dashboard for an
+at-a-glance overview and Reports when you need to filter, sort, and drill
+into the underlying rows.
+
+## Related
+
+- [Job Requisitions, Job Openings & Careers](./recruitment-requisitions-and-openings.md)