Document System Actor pattern in code guidelines

Add section explaining when and how to use system actor for systemic operations.
Include examples and distinction between user mode and system mode.
This commit is contained in:
Moritz 2026-01-20 22:09:22 +01:00 committed by Simon
parent 481e82d541
commit 8eb05c8a6a
Signed by: simon
GPG key ID: 40E7A58C4AA1EDB2
3 changed files with 73 additions and 8 deletions

View file

@ -641,7 +641,54 @@ def card(assigns) do
end
```
### 3.3 Ash Framework
### 3.3 System Actor Pattern
**When to Use System Actor:**
Some operations must always run regardless of user permissions. These are **systemic operations** that are mandatory side effects:
- **Email synchronization** (Member ↔ User)
- **Email uniqueness validation** (data integrity requirement)
- **Cycle generation** (if defined as mandatory side effect)
- **Background jobs**
- **Seeds**
**Implementation:**
Use `Mv.Helpers.SystemActor.get_system_actor/0` for all systemic operations:
```elixir
# Good - Email sync uses system actor
def get_linked_member(user) do
system_actor = SystemActor.get_system_actor()
opts = Helpers.ash_actor_opts(system_actor)
case Ash.get(Mv.Membership.Member, id, opts) do
{:ok, member} -> member
{:error, _} -> nil
end
end
# Bad - Using user actor for systemic operation
def get_linked_member(user, actor) do
opts = Helpers.ash_actor_opts(actor) # May fail if user lacks permissions!
# ...
end
```
**System Actor Details:**
- System actor is a user with admin role (email: "system@mila.local")
- Cached in Agent for performance
- Falls back to admin user from seeds if system user doesn't exist
- Should NEVER be used for user-initiated actions (only systemic operations)
**User Mode vs System Mode:**
- **User Mode**: User-initiated actions use the actual user actor, policies are enforced
- **System Mode**: Systemic operations use system actor, bypass user permissions
### 3.4 Ash Framework
**Resource Definition Best Practices:**