朱子纯 / vibe-erp

feat(security): P4.3 — @RequirePermission + JWT roles claim + AOP enforcement

The framework's authorization layer is now live. Until now, every
authenticated user could do everything; the framework had only an
authentication gate. This chunk adds method-level @RequirePermission
annotations enforced by a Spring AOP aspect that consults the JWT's
roles claim and a metadata-driven role-permission map.

What landed
-----------
* New `Role` and `UserRole` JPA entities mapping the existing
  identity__role + identity__user_role tables (the schema was
  created in the original identity init but never wired to JPA).
  RoleJpaRepository + UserRoleJpaRepository with a JPQL query that
  returns a user's role codes in one round-trip.
* `JwtIssuer.issueAccessToken(userId, username, roles)` now accepts a
  Set<String> of role codes and encodes them as a `roles` JWT claim
  (sorted for deterministic tests). Refresh tokens NEVER carry roles
  by design — see the rationale on `JwtIssuer.issueRefreshToken`. A
  role revocation propagates within one access-token lifetime
  (15 min default).
* `JwtVerifier` reads the `roles` claim into `DecodedToken.roles`.
  Missing claim → empty set, NOT an error (refresh tokens, system
  tokens, and pre-P4.3 tokens all legitimately omit it).
* `AuthService.login` now calls `userRoles.findRoleCodesByUserId(...)`
  before minting the access token. `AuthService.refresh` re-reads
  the user's roles too — so a refresh always picks up the latest
  set, since refresh tokens deliberately don't carry roles.
* New `AuthorizationContext` ThreadLocal in `platform-security.authz`
  carrying an `AuthorizedPrincipal(id, username, roles)`. Separate
  from `PrincipalContext` (which lives in platform-persistence and
  carries only the principal id, for the audit listener). The two
  contexts coexist because the audit listener has no business
  knowing what roles a user has.
* `PrincipalContextFilter` now populates BOTH contexts on every
  authenticated request, reading the JWT's `username` and `roles`
  claims via `Jwt.getClaimAsStringList("roles")`. The filter is the
  one and only place that knows about Spring Security types AND
  about both vibe_erp contexts; everything downstream uses just the
  Spring-free abstractions.
* `PermissionEvaluator` Spring bean: takes a role set + permission
  key, returns boolean. Resolution chain:
  1. The literal `admin` role short-circuits to `true` for every
     key (the wildcard exists so the bootstrap admin can do
     everything from the very first boot without seeding a complete
     role-permission mapping).
  2. Otherwise consults an in-memory `Map<role, Set<permission>>`
     loaded from `metadata__role_permission` rows. The cache is
     rebuilt by `refresh()`, called from `VibeErpPluginManager`
     after the initial core load AND after every plug-in load.
  3. Empty role set is always denied. No implicit grants.
* `@RequirePermission("...")` annotation in `platform-security.authz`.
  `RequirePermissionAspect` is a Spring AOP @Aspect with @Around
  advice that intercepts every annotated method, reads the current
  request's `AuthorizationContext`, calls
  `PermissionEvaluator.has(...)`, and either proceeds or throws
  `PermissionDeniedException`.
* New `PermissionDeniedException` carrying the offending key.
  `GlobalExceptionHandler` maps it to HTTP 403 Forbidden with
  `"permission denied: 'partners.partner.deactivate'"` as the
  detail. The key IS surfaced to the caller (unlike the 401's
  generic "invalid credentials") because the SPA needs it to
  render a useful "your role doesn't include X" message and
  callers are already authenticated, so it's not an enumeration
  vector.
* `BootstrapAdminInitializer` now creates the wildcard `admin`
  role on first boot and grants it to the bootstrap admin user.
* `@RequirePermission` applied to four sensitive endpoints as the
  demo: `PartnerController.deactivate`,
  `StockBalanceController.adjust`, `SalesOrderController.confirm`,
  `SalesOrderController.cancel`. More endpoints will gain
  annotations as additional roles are introduced; v1 keeps the
  blast radius narrow.

End-to-end smoke test
---------------------
Reset Postgres, booted the app, verified:
* Admin login → JWT length 265 (was 241), decoded claims include
  `"roles":["admin"]`
* Admin POST /sales-orders/{id}/confirm → 200, status DRAFT → CONFIRMED
  (admin wildcard short-circuits the permission check)
* Inserted a 'powerless' user via raw SQL with no role assignments
  but copied the admin's password hash so login works
* Powerless login → JWT length 247, decoded claims have NO roles
  field at all
* Powerless POST /sales-orders/{id}/cancel → **403 Forbidden** with
  `"permission denied: 'orders.sales.cancel'"` in the body
* Powerless DELETE /partners/{id} → **403 Forbidden** with
  `"permission denied: 'partners.partner.deactivate'"`
* Powerless GET /sales-orders, /partners, /catalog/items → all 200
  (read endpoints have no @RequirePermission)
* Admin regression: catalog uoms, identity users, inventory
  locations, printing-shop plates with i18n, metadata custom-fields
  endpoint — all still HTTP 2xx

Build
-----
* `./gradlew build`: 15 subprojects, 163 unit tests (was 153),
  all green. The 10 new tests cover:
  - PermissionEvaluator: empty roles deny, admin wildcard, explicit
    role-permission grant, multi-role union, unknown role denial,
    malformed payload tolerance, currentHas with no AuthorizationContext,
    currentHas with bound context (8 tests).
  - JwtRoundTrip: roles claim round-trips through the access token,
    refresh token never carries roles even when asked (2 tests).

What was deferred
-----------------
* **OIDC integration (P4.2)**. Built-in JWT only. The Keycloak-
  compatible OIDC client will reuse the same authorization layer
  unchanged — the roles will come from OIDC ID tokens instead of
  the local user store.
* **Permission key validation at boot.** The framework does NOT
  yet check that every `@RequirePermission` value matches a
  declared metadata permission key. The plug-in linter is the
  natural place for that check to land later.
* **Role hierarchy**. Roles are flat in v1; a role with permission
  X cannot inherit from another role. Adding a `parent_role` field
  on the role row is a non-breaking change later.
* **Resource-aware permissions** ("the user owns THIS partner").
  v1 only checks the operation, not the operand. Resource-aware
  checks are post-v1.
* **Composite (AND/OR) permission requirements**. A single key
  per call site keeps the contract simple. Composite requirements
  live in service code that calls `PermissionEvaluator.currentHas`
  directly.
* **Role management UI / REST**. The framework can EVALUATE
  permissions but has no first-class endpoints for "create a
  role", "grant a permission to a role", "assign a role to a
  user". v1 expects these to be done via direct DB writes or via
  the future SPA's role editor (P3.x); the wiring above is
  intentionally policy-only, not management.