@sparkerp/plugin-sdk 0.1.0 → 1.0.0

package/bundle/docs/applications/hcm/talent-competencies-skills.md

@@ -0,0 +1,30 @@
+---
+title: Competencies & Skills
+audience: tenant
+---
+
+# Competencies & Skills (HCM)
+
+This page documents two shipped **Talent** screens (`hcm-talent`). Not for
+plugin developers.
+
+## Competencies
+
+Define and manage the competency catalog talent processes reference. New
+competencies go through a real publish approval before they're usable
+elsewhere.
+
+## Skills
+
+This screen doesn't maintain its own separate skill master — it points at
+the same real skill catalog the [Learning module](./learning-certifications.md)
+owns, and adds talent-specific classification on top: whether a skill is
+**Critical** (talent's own judgment call, independent of Learning's own
+criticality rating), whether it's an **Emerging** skill (and since when),
+its business relevance, and talent-specific notes. The underlying skill
+itself (its name, category, publish status) is still managed in Learning
+— this screen only adds the talent lens on top of it.
+
+## Related
+
+- [Talent Profiles, High Potential Employees & Talent Pools](./talent-profiles.md)

package/bundle/docs/applications/hcm/talent-profiles.md

@@ -0,0 +1,40 @@
+---
+title: Talent Profiles, High Potential Employees & Talent Pools
+audience: tenant
+---
+
+# Talent Profiles, High Potential Employees & Talent Pools (HCM)
+
+This page documents three shipped **Talent** screens (`hcm-talent`). Not
+for plugin developers.
+
+**Who this is for:** `TALENT_ADMINISTRATOR` has full control; `TALENT_MANAGER_ROLE`
+can view and create but not see potential/risk ratings or
+activate/delete/admin — talent classification is confidential by default,
+not visible to every manager.
+
+## Talent Profiles
+
+A talent-focused profile per employee. Its **talent category** — Default,
+High-Performer, High-Potential, or both High-Potential + High-Performer —
+is calculated automatically from underlying data as you create or update
+the profile, not something you set by hand.
+
+## High Potential Employees
+
+This isn't a separate list you maintain — it's Talent Profiles, filtered
+to `talent_category = HIGH_POTENTIAL` (you can change the filter). If it
+shows zero rows, that means no profile has actually been classified as
+high-potential yet, not a broken screen.
+
+## Talent Pools
+
+Group employees into talent pools for future opportunities. Both the pool
+itself and each membership go through a real, two-step approval
+(activate the pool; approve someone's membership in it) — this isn't just
+a status flag you flip.
+
+## Related
+
+- [Career Development & Career Paths](./talent-career.md)
+- [Succession Planning, Successor Candidates & Talent Reviews](./talent-succession.md)

package/bundle/docs/applications/hcm/talent-succession.md

@@ -0,0 +1,42 @@
+---
+title: Succession Planning, Successor Candidates & Talent Reviews
+audience: tenant
+---
+
+# Succession Planning, Successor Candidates & Talent Reviews (HCM)
+
+This page documents three shipped **Talent** screens (`hcm-talent`). Not
+for plugin developers.
+
+## Succession Planning
+
+Plan succession for a critical role — role name/code, department,
+criticality, business impact if it goes unfilled, vacancy risk, the
+current incumbent, and a plan owner. Activating a plan is the one
+genuinely two-step approval in this whole module: **Talent Manager, then
+Talent Administrator** must both sign off — reflecting that a critical-role
+succession plan needs more scrutiny than an everyday talent record.
+
+## Successor Candidates
+
+A separate, tenant-wide pool of people being considered as potential
+successors for one or more roles — each candidate can be linked to
+multiple succession plans, and each of those pairings tracks its own
+readiness, priority, and match score, so the same person can be "ready
+now" for one role and "developing" for another.
+
+## Talent Reviews
+
+Run a calibration cycle — name, type, period — with each employee being
+reviewed as their own row inside the cycle, not a separate screen per
+person.
+
+## Known gaps
+
+- **Talent Reports has no real report builder or export engine** — it's a
+  catalog of labeled links, each one taking you into the relevant
+  screen's own grid (already filtered), not a bespoke rendering system.
+
+## Related
+
+- [Talent Profiles, High Potential Employees & Talent Pools](./talent-profiles.md)

package/bundle/docs/applications/hcm/teams-and-tags.md

@@ -0,0 +1,46 @@
+---
+title: Teams & Organization Tags
+audience: tenant
+---
+
+# Teams & Organization Tags (HCM)
+
+This page documents two shipped, standalone **Organization** screens
+(`hcm-organization`). Not for plugin developers.
+
+## Teams
+
+Unlike Departments/Divisions/etc. (one employee belongs to one org unit),
+Teams support **many-to-many, percentage-allocated** membership — an
+employee can belong to more than one team at once, each with a percentage
+of their time/allocation, useful for matrix or project-based structures.
+
+### What you see
+
+Search, plus filters for Department, Team Type, and Status. The grid:
+Team Name, Type, Department, Team Lead, Members (count), End Date,
+Status, Actions.
+
+### Creating or editing a team
+
+The form covers Team Name, Team Code, Department, Team Lead, Deputy Team
+Lead, Parent Team, Max Members, Effective From/To, and Description.
+
+### Team detail
+
+Click a team to see its full detail — Code, Type, Department, Team Lead,
+Deputy Team Lead, Parent Team, Max Members, Visibility, Effective
+From/To, Status — plus its **Members** section: **Add Member**, and for
+each existing member, **Change Role / Allocation** or **Remove**.
+**Deactivate** retires the team.
+
+## Organization Tags
+
+A small, tenant-extensible tagging system for organizational entities,
+built on the platform's generic Entity Engine — attach free-form tags for
+your own categorization needs beyond the built-in hierarchy. **New Tag**
+opens a simple form: Name, Code, Color.
+
+## Related
+
+- [Org Units, Legal Entities, Business Units & more](./org-units.md)

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

@@ -0,0 +1,33 @@
+---
+title: Timesheets
+audience: tenant
+---
+
+# Timesheets (HCM)
+
+This page documents the shipped **Timesheets** screen (`hcm-timesheets`).
+Not for plugin developers.
+
+## What it does
+
+Log a timesheet for a pay/reporting period, with line entries per
+project/task/cost-center. Each employee can only have one timesheet per
+period — the platform enforces this for real, not just by convention.
+**Submit for Approval** starts a real approval workflow; **Approve** and
+**Reject** decide it for real, the same way every other approval in HCM
+works.
+
+## Known gaps
+
+- **Total hours (regular/overtime) are entered or summed by hand**, not
+  automatically calculated from the line entries.
+- **Entries don't auto-populate from your real attendance data** — you
+  fill in a timesheet's lines yourself, they aren't pulled from
+  [Attendance](./attendance-core.md) automatically.
+- **No separate approval-history table beyond the workflow engine's own
+  history**, no exception detection, no tenant-defined pay-period
+  templates, no dedicated audit trail beyond the platform's standard one.
+
+## Related
+
+- [Attendance — Dashboard, Daily Attendance, Register, Biometric & Devices](./attendance-core.md)

package/bundle/docs/applications/hcm/travel-advances-expenses.md

@@ -0,0 +1,34 @@
+---
+title: Travel Advances & Travel Expenses
+audience: tenant
+---
+
+# Travel Advances & Travel Expenses (HCM)
+
+This page documents two shipped **Travel** screens (`hcm-travel`). Not for
+plugin developers.
+
+## Travel Advances
+
+**Travel Advance** — link to the Travel Request, set an Advance Type,
+Purpose, Destination, Travel Start/End dates, Required By Date, Payment
+Method, Currency, and a real breakdown of **Advance Components** (e.g.
+separate amounts for meals, lodging, incidentals) rather than one flat
+figure, plus the total Requested Amount. Status: Pending Approval →
+Approved → Disbursed → Settled. KPIs: Total Advances, Pending, Approved,
+Disbursed, Settled, and a real **Outstanding Amount** sum across
+unsettled advances.
+
+## Travel Expenses
+
+**Travel Expense Claim** — link to the Travel Request (and, if
+applicable, the specific Advance it should offset), Expense Date, and
+real Expense Lines making up the Gross Amount and Tax Amount. The KPI row
+calls out **Missing Receipts** specifically — a real count of claim lines
+still needing a receipt attached, not just buried in the grid. Status:
+Submitted → Approved (or Rejected) → Reimbursed. KPIs: Total Claims,
+Submitted, Approved, Rejected, Reimbursed, Missing Receipts.
+
+## Related
+
+- [Travel Bookings & Accommodation](./travel-bookings.md)

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

@@ -0,0 +1,28 @@
+---
+title: Travel Dashboard & Reports
+audience: tenant
+---
+
+# Travel Dashboard & Reports (HCM)
+
+This page documents two shipped **Travel** analytics screens
+(`hcm-travel`). Not for plugin developers.
+
+## Travel Dashboard
+
+An operational view: Total Travel Requests, Pending Approvals, Rejected
+Requests, Active Policies, Active/Upcoming/Completed Trips, Approved
+Travel Spend, Outstanding Advances, and Policy Exceptions — a real
+at-a-glance read on who's traveling right now and what still needs your
+attention.
+
+## Travel Reports
+
+A cost-focused view: Total Trips (split into Domestic and International),
+Total Bookings, Booking Spend, Accommodation Spend, Total Travel Expenses,
+Approved Travel Spend, Outstanding Advances, and Policy Exceptions — for
+understanding where your travel budget is actually going.
+
+## Related
+
+- [Travel Policies, Travel Requests & Travel Approval](./travel-requests.md)

package/bundle/docs/applications/hcm/travel-bookings.md

@@ -0,0 +1,35 @@
+---
+title: Travel Bookings & Accommodation
+audience: tenant
+---
+
+# Travel Bookings & Accommodation (HCM)
+
+This page documents two shipped **Travel** screens (`hcm-travel`),
+covering the logistics of an approved trip. Not for plugin developers.
+
+## Travel Bookings
+
+**Travel Booking** — link it to the approved Travel Request, pick a
+Booking Type (Flight/Train/Bus/Car Rental/Ground Transport), Provider/
+Airline, Booking Agency, Origin/Destination, Departure/Return Dates, and
+real itinerary segments for multi-leg trips. The cost breaks down into
+Base Amount, Tax Amount, Fee Amount, and Discount Amount separately, not
+one lump sum — useful when reconciling against what the airline actually
+charged. Status moves through Draft → Confirmed → Ticketed → Completed
+(or Cancelled). KPIs: Total Bookings, Draft, Confirmed, Ticketed,
+Completed, Cancelled.
+
+## Accommodation
+
+**Accommodation** — link to the Travel Request, set Hotel Name/Address,
+City/Country, Room Type, number of Rooms, Guests, Meal Plan, Check-In/
+Check-Out dates, and Rate Per Night — Nights and Room Subtotal are worked
+out for you. Same cost breakdown (Tax/Fee/Discount) as Bookings. Status:
+Requested → Reserved → Confirmed → Checked In → (Cancelled). KPIs: Total
+Stays, Requested, Reserved, Confirmed, Checked In, Cancelled.
+
+## Related
+
+- [Travel Policies, Travel Requests & Travel Approval](./travel-requests.md)
+- [Travel Advances & Expenses](./travel-advances-expenses.md)

package/bundle/docs/applications/hcm/travel-requests.md

@@ -0,0 +1,38 @@
+---
+title: Travel Policies, Travel Requests & Travel Approval
+audience: tenant
+---
+
+# Travel Policies, Travel Requests & Travel Approval (HCM)
+
+This page documents three shipped **Travel** screens (`hcm-travel`)
+covering how a business trip gets requested and approved. Not for plugin
+developers.
+
+## Travel Policies
+
+Define your company's travel policies through a single, straightforward
+create/edit form. KPIs: Total Policies, Draft, Pending Approval,
+Scheduled, Active, Expired — so you can see at a glance which policies
+are actually live vs. still being drafted.
+
+## Travel Requests
+
+Request a trip — destination, dates, itinerary — through a single-form
+create/edit. Each request is checked against your active Travel Policy as
+it moves through Draft → Pending Approval → Approved → Active Trips →
+Completed (or Rejected). The KPI row includes a genuinely useful
+**Policy Exceptions** count — requests that fell outside policy, worth
+reviewing specifically rather than hunting through the full list.
+
+## Travel Approval
+
+A focused approver workspace for reviewing and approving travel requests
+inline, without needing to leave for the general approvals inbox. KPIs:
+Pending Approvals, Approved This Period, Rejected This Period, Policy
+Exceptions — a real per-period view of your own approval activity, not
+just a static backlog count.
+
+## Related
+
+- [Travel Bookings & Accommodation](./travel-bookings.md)

package/bundle/docs/applications/hcm/workforce-org-design.md

@@ -0,0 +1,22 @@
+---
+title: Org Design
+audience: tenant
+---
+
+# Org Design (HCM)
+
+This page documents the shipped **Org Design** screen
+(`hcm-workforce-planning`) — a live editing view over your real
+Organization Unit data. Not for plugin developers.
+
+## What it does
+
+**Select Org Unit**, then edit its Department/Unit Notes, its Reporting
+Line (which parent unit it sits under), and Status — **Save Changes**
+writes back to the same real org unit data
+[Org Units](./org-units.md) manages, deliberately built on top of your
+existing structure rather than a separate, duplicate one to maintain.
+
+## Related
+
+- [Reporting Structure & Organization Structure](./org-structure.md)

package/bundle/docs/applications/hcm/workforce-planning-analytics.md

@@ -0,0 +1,26 @@
+---
+title: Workforce Dashboard & Reports
+audience: tenant
+---
+
+# Workforce Dashboard & Reports (HCM)
+
+This page documents two shipped **Workforce Planning** analytics screens
+(`hcm-workforce-planning`). Not for plugin developers.
+
+## Workforce Dashboard
+
+Real live KPIs pulled from across the module — active headcount, org
+units, positions, and more.
+
+## Workforce Reports
+
+A department-level rollup: Current Headcount vs. Planned Headcount, a
+real **Gap Capacity** figure, Skill and its Coverage %, Risk Level, and
+which Scenario the numbers are drawn from — the one screen that pulls
+Headcount Planning and Skill Gap Analysis together into a single
+per-department view.
+
+## Related
+
+- [Headcount Planning, Demand Forecasting & Budget Planning](./workforce-planning-core.md)

package/bundle/docs/applications/hcm/workforce-planning-core.md

@@ -0,0 +1,36 @@
+---
+title: Headcount Planning, Demand Forecasting & Budget Planning
+audience: tenant
+---
+
+# Headcount Planning, Demand Forecasting & Budget Planning (HCM)
+
+This page documents three shipped **Workforce Planning** screens
+(`hcm-workforce-planning`). Not for plugin developers.
+
+## Headcount Planning
+
+Plan headcount by Department, Fiscal Year, and Scenario: enter Current HC
+(headcount), Planned HC, Planned Hiring, Planned Reduction, and Estimated
+Cost/Currency. New plans go through **Submit for Approval** →
+**Approve**/**Reject**.
+
+## Demand Forecasting
+
+Forecast the headcount you'll need, by department and period: Forecast
+Name/Code, Forecast Type, Current HC, Required HC, and a Growth Rate % —
+the screen calculates a **Suggested HC** for you from that growth rate
+rather than making you do the math, alongside a Confidence % and Cost
+Amount for the forecast. Same submit → approve/reject flow as Headcount
+Planning.
+
+## Budget Planning
+
+Plan workforce budget lines: Budget Type, Fiscal Year, Department, Budget
+Amount, Forecast Amount, and (once actuals come in) Actual Amount — so
+you can compare planned vs. forecast vs. actual spend in one place. Same
+submit → approve/reject flow.
+
+## Related
+
+- [Scenario Planning & Skill Gap Analysis](./workforce-planning-scenarios.md)

package/bundle/docs/applications/hcm/workforce-planning-scenarios.md

@@ -0,0 +1,29 @@
+---
+title: Scenario Planning & Skill Gap Analysis
+audience: tenant
+---
+
+# Scenario Planning & Skill Gap Analysis (HCM)
+
+This page documents two shipped **Workforce Planning** screens
+(`hcm-workforce-planning`). Not for plugin developers.
+
+## Scenario Planning
+
+Model a workforce scenario: Scenario Name/Code, Scenario Type, Org Scope,
+Planning Period, and a Projected HC/Cost — the screen shows a real
+**Variance %** comparing your scenario against the baseline from
+[Headcount Planning](./workforce-planning-core.md). Same submit → approve/
+reject flow as the other planning screens.
+
+## Skill Gap Analysis
+
+For a given Skill, Job Family, and Department, record the Required Level
+vs. the Available Level you currently have — the screen calculates a
+**Gap Level**, **Gap Severity**, **Coverage %**, and a **Risk Level** from
+those two numbers, and you can record a **Recommended Action** against
+each gap. Same submit → approve/reject flow.
+
+## Related
+
+- [Headcount Planning, Demand Forecasting & Budget Planning](./workforce-planning-core.md)

package/bundle/docs/guides/add-app-owned-roles-and-permissions.md

@@ -0,0 +1,144 @@
+---
+title: Add your own app-owned roles & permissions
+audience: tenant
+---
+
+# Add your own app-owned roles & permissions
+
+If your plugin needs its own admin-configurable roles (not the tenant-wide
+Roles Studio designer, and not a hand-rolled permission check scattered
+across your controllers), the platform has a small, reusable, already-proven
+shape for it: **your own `role`/`permission`/`role_permission`/`user_role`
+tables, one real Java repository + REST controller, and two shared
+enforcement classes** (`ApplicationRoleChecker`, `ApplicationAccessGate`)
+every app using this pattern instantiates against its own schema. `hcm-foundation`
+and `crm-foundation` both ship a real copy of this — read either one's
+`ApplicationRoleRestContribution.java` alongside this guide.
+
+This is **not** the tenant-wide `erp_core.role`/`actor_role` system the
+Permission Designer manages — that's a separate, generic mechanism. Build
+this pattern when your plugin wants its *own* concept of roles that only
+make sense inside your own application (e.g. "Payroll Administrator" only
+means something in `hcm-payroll`).
+
+## 1. Ship the four tables
+
+A migration in your plugin's own `spk-assembly/database/`:
+
+```sql
+create table role (
+    id bigserial primary key,
+    tenant_id bigint not null,
+    name text not null,
+    description text,
+    is_system boolean not null default false,
+    is_admin boolean not null default false,
+    created_by text,
+    unique (tenant_id, name)
+);
+
+create table permission (
+    id bigserial primary key,
+    tenant_id bigint not null,
+    role_id bigint not null references role(id),
+    resource text not null,
+    action text not null,
+    scope text not null default 'ALL',
+    scope_field text
+);
+
+create table user_role (
+    id bigserial primary key,
+    tenant_id bigint not null,
+    tenant_user_id bigint not null,
+    role_id bigint not null references role(id),
+    assigned_by text,
+    assigned_at timestamptz not null default now(),
+    unique (tenant_id, tenant_user_id, role_id)
+);
+```
+
+(`role_permission` is folded into `permission` above — one row per
+resource+action grant, same shape `hcm-foundation`'s own V7 migration uses.)
+
+## 2. Wire the two shared enforcement classes
+
+In your REST controller (a PF4J `@Extension` + `@RestController`):
+
+```java
+public MyRestContribution(JdbcTemplate jdbcTemplate,
+                           @Qualifier("platformRegistryJdbcTemplate") JdbcTemplate platformRegistryJdbcTemplate) {
+    this.roles = new MyRoleRepository(jdbcTemplate);
+    this.accessGate = new ApplicationAccessGate(
+        jdbcTemplate.getDataSource(), platformRegistryJdbcTemplate.getDataSource(), "my-app-code");
+}
+```
+
+Then gate every mutation:
+
+```java
+if (!accessGate.allowsAdmin(tenantId, actor)) {
+    throw new ResponseStatusException(HttpStatus.FORBIDDEN, "administrator role required");
+}
+```
+
+`ApplicationRoleChecker` (used internally by the gate) is what actually
+answers "can this user do `resource`+`action`" for read/write checks that
+aren't admin-only — see `ApplicationRoleChecker.resolveGrant`'s own doc
+comment for the real query, including role-hierarchy inheritance and
+`status='ACTIVE'` enforcement.
+
+## 3. The bootstrap problem — read this before you hit it live
+
+Every admin-surface endpoint (create role, assign, grant/revoke) calls
+`accessGate.allowsAdmin(...)`, which requires the caller to **already** hold
+an `is_admin` role. On a brand-new tenant+application, nobody does — so
+nobody can ever create the first one through your own REST surface. This
+is not a bug to work around ad hoc; it's a real chicken-and-egg problem
+every app using this pattern hits, and the platform already has a correct,
+narrow fix for it: **ship a one-time seed migration that grandfathers
+whoever already holds this tenant's own `TENANT_ADMIN`/`"Tenant Owner"`
+role onto your app's `is_admin` role.**
+
+```sql
+-- V10__my_app_admin_role_bootstrap.sql (adjust the version number)
+insert into role (tenant_id, name, description, is_system, is_admin, created_by)
+select distinct u.tenant_id, 'My App Administrator',
+       'Full administrative access to My App roles, permissions, and configuration.',
+       true, true, 'system-migration'
+from erp_core.users u
+join erp_core.actor_role ar on ar.tenant_id = u.tenant_id and ar.actor = u.username
+where ar.role in ('TENANT_ADMIN', 'Tenant Owner')
+on conflict (tenant_id, name) do update set is_admin = true, is_system = true;
+
+insert into user_role (tenant_id, tenant_user_id, role_id, assigned_by)
+select distinct u.tenant_id, u.platform_user_id, r.id, 'system-migration'
+from erp_core.users u
+join erp_core.actor_role ar on ar.tenant_id = u.tenant_id and ar.actor = u.username
+join role r on r.tenant_id = u.tenant_id and r.name = 'My App Administrator'
+where ar.role in ('TENANT_ADMIN', 'Tenant Owner')
+  and u.platform_user_id is not null
+on conflict (tenant_id, tenant_user_id, role_id) do nothing;
+```
+
+**Do not** "fix" this by widening `ApplicationAccessGate.hasAdminRole` itself
+(e.g. "any authenticated user is admin while none exists yet") — that was
+tried and reverted the same day it shipped (2026-09-22): it's a strictly
+broader security change than the migration above, it's a shared class every
+app using this pattern depends on, and it duplicates a mechanism that
+already existed. If a real tenant somehow still has zero `is_admin` rows
+despite shipping this migration, the fix is to confirm that user actually
+holds `TENANT_ADMIN`/`"Tenant Owner"` in `erp_core.actor_role` (grant it
+there), not to loosen the app-level gate.
+
+## Where the real code lives
+
+- `backend/platform-runtime/common/.../schema/ApplicationRoleChecker.java` —
+  shared grant-resolution, hierarchy, status enforcement.
+- `backend/platform-runtime/common/.../schema/ApplicationAccessGate.java` —
+  identity resolution + application-access denial + the admin gate.
+- `backend/modules/hcm-foundation/.../ApplicationRoleRestContribution.java`
+  and its `V10__hcm_admin_role_bootstrap.sql` — a complete, working example.
+- `backend/modules/crm-foundation/` ships an independent second copy of the
+  exact same shape, for a second application — proof this is meant to be
+  copied per-app, not shared/inherited.