docs: reorder & testing

backend/internal/user/account.go

@@ -12,19 +12,35 @@ import (
 
 // ActorRef identifies the principal that produced an audit-bearing
 // mutation. The wire shape mirrors the OpenAPI ActorRef schema. Type is
-// a free-form string ("user", "admin", "system" in MVP); ID is opaque
-// (a user UUID, an admin username, or empty for system).
+// one of "user", "admin", "system" in MVP. ID carries a user UUID for
+// Type=="user", an admin username for Type=="admin", and is empty for
+// Type=="system".
 type ActorRef struct {
 	Type string
-	ID string
+	ID   string
 }
 
-// Validate rejects empty actor types. Admin handlers always populate
-// Type; user-side mutations supply Type internally.
+// Validate rejects empty actor types and enforces the per-type shape
+// of ID: a user actor requires a UUID id, a system actor must have an
+// empty id. Other types pass through with no further check.
 func (a ActorRef) Validate() error {
-	if strings.TrimSpace(a.Type) == "" {
+	t := strings.TrimSpace(a.Type)
+	if t == "" {
 		return ErrInvalidActor
 	}
+	switch t {
+	case "user":
+		if strings.TrimSpace(a.ID) == "" {
+			return fmt.Errorf("%w: user actor requires id", ErrInvalidActor)
+		}
+		if _, err := uuid.Parse(a.ID); err != nil {
+			return fmt.Errorf("%w: user actor id must be a uuid: %v", ErrInvalidActor, err)
+		}
+	case "system":
+		if strings.TrimSpace(a.ID) != "" {
+			return fmt.Errorf("%w: system actor must have an empty id", ErrInvalidActor)
+		}
+	}
 	return nil
 }