feat: scaffold Django multi-tenant project with 5 of 9 apps

Phase 1 scaffolding: config/, core/, base models, AES-256-GCM phone encryption, enums mirror

apps.tenant: Tenant + Domain (django-tenants)

apps.org: 11 models (OrgUnit hierarchy, Staff, audit logs)

apps.account: 4 models (UserAccount as AUTH_USER_MODEL, login/password tracking)

apps.permission: 7 models (RBAC + overrides + datascope + append-only changelog)

apps.region: 5 models (District, BusinessArea, MetroLine, MetroStation, School)

All migrations generated, manage.py check passes

apps/permission/apps.py

@@ -0,0 +1,7 @@
+from django.apps import AppConfig
+
+
+class PermissionConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "apps.permission"
+    label = "fonrey_permission"

apps/permission/migrations/0001_initial.py

@@ -0,0 +1,249 @@
+# Generated by Django 4.2.16 on 2026-04-29 08:47
+
+import django.contrib.postgres.fields
+from django.db import migrations, models
+import django.db.models.deletion
+import uuid
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+        ('org', '0001_initial'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='PermissionChangeLog',
+            fields=[
+                ('id', models.UUIDField(default=uuid.uuid4, editable=False, primary_key=True, serialize=False)),
+                ('target_type', models.CharField(choices=[('role', '角色'), ('role_permission', '角色权限'), ('staff_role', '员工角色'), ('staff_override', '员工权限覆盖'), ('staff_scope', '员工数据范围')], max_length=30)),
+                ('target_id', models.UUIDField()),
+                ('permission_code', models.CharField(blank=True, default='', max_length=150)),
+                ('action', models.CharField(choices=[('create', '创建'), ('update', '更新'), ('delete', '删除'), ('assign', '分配'), ('revoke', '撤销')], max_length=20)),
+                ('old_value', models.JSONField(blank=True, null=True)),
+                ('new_value', models.JSONField(blank=True, null=True)),
+                ('operator_ip', models.GenericIPAddressField(blank=True, null=True)),
+                ('user_agent', models.TextField(blank=True, default='')),
+                ('reason', models.TextField(blank=True, default='')),
+                ('operated_at', models.DateTimeField(auto_now_add=True)),
+            ],
+            options={
+                'db_table': 'permission_change_logs',
+                'ordering': ['-operated_at'],
+            },
+        ),
+        migrations.CreateModel(
+            name='PermissionDef',
+            fields=[
+                ('id', models.UUIDField(default=uuid.uuid4, editable=False, primary_key=True, serialize=False)),
+                ('created_at', models.DateTimeField(auto_now_add=True, db_index=True)),
+                ('updated_at', models.DateTimeField(auto_now=True)),
+                ('code', models.CharField(max_length=150, unique=True)),
+                ('module', models.CharField(choices=[('home', '首页'), ('property', '房源'), ('new_house', '新房'), ('client', '客源'), ('transaction', '交易'), ('data', '数据'), ('marketing', '营销'), ('hr', '人事OA'), ('contract', '合同'), ('trinet', '三网'), ('system', '系统'), ('mobile', '移动端'), ('smart_store', '智能门店'), ('recharge', '在线充值')], max_length=50)),
+                ('sub_module', models.CharField(blank=True, default='', max_length=50)),
+                ('group_name', models.CharField(max_length=100)),
+                ('name', models.CharField(max_length=200)),
+                ('description', models.TextField(blank=True, default='')),
+                ('value_type', models.CharField(choices=[('boolean', '开关型'), ('scope', '范围型'), ('integer', '数值型')], max_length=20)),
+                ('scope_choices', models.JSONField(blank=True, default=list)),
+                ('integer_min', models.IntegerField(blank=True, null=True)),
+                ('integer_max', models.IntegerField(blank=True, null=True)),
+                ('default_value', models.JSONField(default=dict)),
+                ('max_allowed_categories', django.contrib.postgres.fields.ArrayField(base_field=models.CharField(max_length=50), blank=True, default=list, size=None)),
+                ('sort_order', models.PositiveIntegerField(default=0)),
+                ('is_active', models.BooleanField(default=True)),
+                ('is_deprecated', models.BooleanField(default=False)),
+                ('version', models.PositiveIntegerField(default=1)),
+            ],
+            options={
+                'db_table': 'permission_defs',
+            },
+        ),
+        migrations.CreateModel(
+            name='Role',
+            fields=[
+                ('id', models.UUIDField(default=uuid.uuid4, editable=False, primary_key=True, serialize=False)),
+                ('created_at', models.DateTimeField(auto_now_add=True, db_index=True)),
+                ('updated_at', models.DateTimeField(auto_now=True)),
+                ('deleted_at', models.DateTimeField(blank=True, db_index=True, null=True)),
+                ('name', models.CharField(max_length=100)),
+                ('category', models.CharField(choices=[('agent', '置业顾问'), ('store_manager', '店管'), ('director', '总经'), ('operator', '运营/行政'), ('custom', '自定义')], max_length=30)),
+                ('description', models.TextField(blank=True, default='')),
+                ('is_system_builtin', models.BooleanField(default=False)),
+                ('is_active', models.BooleanField(default=True)),
+                ('created_by', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='permission_roles_created', to='org.staff')),
+                ('template_role', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='derived_roles', to='fonrey_permission.role')),
+                ('updated_by', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='permission_roles_updated', to='org.staff')),
+            ],
+            options={
+                'db_table': 'roles',
+            },
+        ),
+        migrations.CreateModel(
+            name='StaffRole',
+            fields=[
+                ('id', models.UUIDField(default=uuid.uuid4, editable=False, primary_key=True, serialize=False)),
+                ('is_primary', models.BooleanField(default=False)),
+                ('assigned_at', models.DateTimeField(auto_now_add=True)),
+                ('valid_from', models.DateField(blank=True, null=True)),
+                ('valid_until', models.DateField(blank=True, null=True)),
+                ('assigned_by', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='staff_role_assignments_made', to='org.staff')),
+                ('role', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='staff_links', to='fonrey_permission.role')),
+                ('staff', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='staff_roles', to='org.staff')),
+            ],
+            options={
+                'db_table': 'staff_roles',
+            },
+        ),
+        migrations.CreateModel(
+            name='StaffPermissionOverride',
+            fields=[
+                ('id', models.UUIDField(default=uuid.uuid4, editable=False, primary_key=True, serialize=False)),
+                ('value', models.JSONField()),
+                ('override_mode', models.CharField(choices=[('replace', '覆盖'), ('restrict', '限制'), ('grant', '授予')], default='replace', max_length=10)),
+                ('reason', models.TextField(blank=True, default='')),
+                ('modified_at', models.DateTimeField(auto_now=True)),
+                ('modified_by', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='staff_overrides_modified', to='org.staff')),
+                ('permission_def', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='staff_overrides', to='fonrey_permission.permissiondef')),
+                ('staff', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='permission_overrides', to='org.staff')),
+            ],
+            options={
+                'db_table': 'staff_permission_overrides',
+            },
+        ),
+        migrations.CreateModel(
+            name='StaffDataScope',
+            fields=[
+                ('id', models.UUIDField(default=uuid.uuid4, editable=False, primary_key=True, serialize=False)),
+                ('scope_type', models.CharField(choices=[('self', '本人'), ('group', '本组'), ('store', '本门店'), ('area', '本区域'), ('region', '本大区'), ('company', '全公司'), ('custom_unit', '自定义组织单元')], max_length=20)),
+                ('is_readable', models.BooleanField(default=True)),
+                ('is_writable', models.BooleanField(default=False)),
+                ('granted_at', models.DateTimeField(auto_now_add=True)),
+                ('expires_at', models.DateTimeField(blank=True, null=True)),
+                ('reason', models.TextField(blank=True, default='')),
+                ('granted_by', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='data_scopes_granted', to='org.staff')),
+                ('org_unit', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.PROTECT, related_name='data_scope_grants', to='org.orgunit')),
+                ('staff', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='data_scopes', to='org.staff')),
+            ],
+            options={
+                'db_table': 'staff_data_scopes',
+            },
+        ),
+        migrations.CreateModel(
+            name='RolePermission',
+            fields=[
+                ('id', models.UUIDField(default=uuid.uuid4, editable=False, primary_key=True, serialize=False)),
+                ('created_at', models.DateTimeField(auto_now_add=True, db_index=True)),
+                ('updated_at', models.DateTimeField(auto_now=True)),
+                ('value', models.JSONField()),
+                ('permission_def', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='role_assignments', to='fonrey_permission.permissiondef')),
+                ('role', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='permissions', to='fonrey_permission.role')),
+                ('updated_by', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='role_permissions_updated', to='org.staff')),
+            ],
+            options={
+                'db_table': 'role_permissions',
+            },
+        ),
+        migrations.AddIndex(
+            model_name='permissiondef',
+            index=models.Index(condition=models.Q(('is_active', True)), fields=['module', 'sub_module', 'sort_order'], name='idx_perm_defs_module'),
+        ),
+        migrations.AddIndex(
+            model_name='permissiondef',
+            index=models.Index(condition=models.Q(('is_active', True)), fields=['is_active'], name='idx_perm_defs_active'),
+        ),
+        migrations.AddField(
+            model_name='permissionchangelog',
+            name='operator',
+            field=models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='permission_changes_operated', to='org.staff'),
+        ),
+        migrations.AddField(
+            model_name='permissionchangelog',
+            name='role',
+            field=models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='change_logs', to='fonrey_permission.role'),
+        ),
+        migrations.AddField(
+            model_name='permissionchangelog',
+            name='staff',
+            field=models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='permission_change_logs_affecting', to='org.staff'),
+        ),
+        migrations.AddIndex(
+            model_name='staffrole',
+            index=models.Index(fields=['role'], name='idx_staff_roles_role'),
+        ),
+        migrations.AddConstraint(
+            model_name='staffrole',
+            constraint=models.UniqueConstraint(fields=('staff', 'role'), name='uq_staff_roles'),
+        ),
+        migrations.AddConstraint(
+            model_name='staffrole',
+            constraint=models.UniqueConstraint(condition=models.Q(('is_primary', True)), fields=('staff',), name='uq_staff_roles_primary'),
+        ),
+        migrations.AddIndex(
+            model_name='staffpermissionoverride',
+            index=models.Index(fields=['staff'], name='idx_staff_overrides_staff'),
+        ),
+        migrations.AddConstraint(
+            model_name='staffpermissionoverride',
+            constraint=models.UniqueConstraint(fields=('staff', 'permission_def'), name='uq_staff_overrides'),
+        ),
+        migrations.AddIndex(
+            model_name='staffdatascope',
+            index=models.Index(fields=['staff'], name='idx_data_scopes_staff'),
+        ),
+        migrations.AddIndex(
+            model_name='staffdatascope',
+            index=models.Index(fields=['org_unit'], name='idx_data_scopes_org'),
+        ),
+        migrations.AddIndex(
+            model_name='staffdatascope',
+            index=models.Index(condition=models.Q(('expires_at__isnull', False)), fields=['expires_at'], name='idx_data_scopes_expires'),
+        ),
+        migrations.AddIndex(
+            model_name='rolepermission',
+            index=models.Index(fields=['role'], name='idx_role_permissions_role'),
+        ),
+        migrations.AddIndex(
+            model_name='rolepermission',
+            index=models.Index(fields=['permission_def'], name='idx_role_permissions_def'),
+        ),
+        migrations.AddConstraint(
+            model_name='rolepermission',
+            constraint=models.UniqueConstraint(fields=('role', 'permission_def'), name='uq_role_permissions'),
+        ),
+        migrations.AddIndex(
+            model_name='role',
+            index=models.Index(condition=models.Q(('deleted_at__isnull', True)), fields=['category'], name='idx_roles_category'),
+        ),
+        migrations.AddIndex(
+            model_name='role',
+            index=models.Index(fields=['template_role'], name='idx_roles_template'),
+        ),
+        migrations.AddConstraint(
+            model_name='role',
+            constraint=models.UniqueConstraint(condition=models.Q(('deleted_at__isnull', True)), fields=('name',), name='uq_roles_name_active'),
+        ),
+        migrations.AddIndex(
+            model_name='permissionchangelog',
+            index=models.Index(condition=models.Q(('staff__isnull', False)), fields=['staff', '-operated_at'], name='idx_perm_log_staff'),
+        ),
+        migrations.AddIndex(
+            model_name='permissionchangelog',
+            index=models.Index(condition=models.Q(('role__isnull', False)), fields=['role', '-operated_at'], name='idx_perm_log_role'),
+        ),
+        migrations.AddIndex(
+            model_name='permissionchangelog',
+            index=models.Index(fields=['target_type', 'target_id', '-operated_at'], name='idx_perm_log_target'),
+        ),
+        migrations.AddIndex(
+            model_name='permissionchangelog',
+            index=models.Index(fields=['operator', '-operated_at'], name='idx_perm_log_operator'),
+        ),
+        migrations.AddIndex(
+            model_name='permissionchangelog',
+            index=models.Index(fields=['-operated_at'], name='idx_perm_log_time'),
+        ),
+    ]

apps/permission/models/__init__.py

@@ -0,0 +1,18 @@
+from apps.permission.models.permission_def import PermissionDef
+from apps.permission.models.role import Role, RolePermission
+from apps.permission.models.staff_perm import (
+    PermissionChangeLog,
+    StaffDataScope,
+    StaffPermissionOverride,
+    StaffRole,
+)
+
+__all__ = [
+    "PermissionChangeLog",
+    "PermissionDef",
+    "Role",
+    "RolePermission",
+    "StaffDataScope",
+    "StaffPermissionOverride",
+    "StaffRole",
+]

apps/permission/models/permission_def.py

@@ -0,0 +1,46 @@
+from django.contrib.postgres.fields import ArrayField
+from django.db import models
+
+from core.enums import PermissionModule, PermissionValueType
+from core.models.base import TimeStampedModel
+
+
+class PermissionDef(TimeStampedModel):
+    code = models.CharField(max_length=150, unique=True)
+    module = models.CharField(max_length=50, choices=PermissionModule.choices)
+    sub_module = models.CharField(max_length=50, blank=True, default="")
+    group_name = models.CharField(max_length=100)
+    name = models.CharField(max_length=200)
+    description = models.TextField(blank=True, default="")
+    value_type = models.CharField(max_length=20, choices=PermissionValueType.choices)
+    scope_choices = models.JSONField(default=list, blank=True)
+    integer_min = models.IntegerField(null=True, blank=True)
+    integer_max = models.IntegerField(null=True, blank=True)
+    default_value = models.JSONField(default=dict)
+    max_allowed_categories = ArrayField(
+        models.CharField(max_length=50),
+        default=list,
+        blank=True,
+    )
+    sort_order = models.PositiveIntegerField(default=0)
+    is_active = models.BooleanField(default=True)
+    is_deprecated = models.BooleanField(default=False)
+    version = models.PositiveIntegerField(default=1)
+
+    class Meta:
+        db_table = "permission_defs"
+        indexes = [
+            models.Index(
+                fields=["module", "sub_module", "sort_order"],
+                name="idx_perm_defs_module",
+                condition=models.Q(is_active=True),
+            ),
+            models.Index(
+                fields=["is_active"],
+                name="idx_perm_defs_active",
+                condition=models.Q(is_active=True),
+            ),
+        ]
+
+    def __str__(self) -> str:
+        return f"{self.code} ({self.value_type})"

apps/permission/models/role.py

@@ -0,0 +1,91 @@
+from django.db import models
+
+from core.enums import PermissionRoleCategory
+from core.models.base import SoftDeleteModel, TimeStampedModel
+
+
+class Role(SoftDeleteModel):
+    name = models.CharField(max_length=100)
+    category = models.CharField(max_length=30, choices=PermissionRoleCategory.choices)
+    description = models.TextField(blank=True, default="")
+    template_role = models.ForeignKey(
+        "fonrey_permission.Role",
+        null=True,
+        blank=True,
+        on_delete=models.SET_NULL,
+        related_name="derived_roles",
+    )
+    is_system_builtin = models.BooleanField(default=False)
+    is_active = models.BooleanField(default=True)
+    created_by = models.ForeignKey(
+        "org.Staff",
+        null=True,
+        blank=True,
+        on_delete=models.SET_NULL,
+        related_name="permission_roles_created",
+    )
+    updated_by = models.ForeignKey(
+        "org.Staff",
+        null=True,
+        blank=True,
+        on_delete=models.SET_NULL,
+        related_name="permission_roles_updated",
+    )
+
+    class Meta:
+        db_table = "roles"
+        constraints = [
+            models.UniqueConstraint(
+                fields=["name"],
+                name="uq_roles_name_active",
+                condition=models.Q(deleted_at__isnull=True),
+            ),
+        ]
+        indexes = [
+            models.Index(
+                fields=["category"],
+                name="idx_roles_category",
+                condition=models.Q(deleted_at__isnull=True),
+            ),
+            models.Index(fields=["template_role"], name="idx_roles_template"),
+        ]
+
+    def __str__(self) -> str:
+        return f"{self.name} ({self.category})"
+
+
+class RolePermission(TimeStampedModel):
+    role = models.ForeignKey(
+        "fonrey_permission.Role",
+        on_delete=models.CASCADE,
+        related_name="permissions",
+    )
+    permission_def = models.ForeignKey(
+        "fonrey_permission.PermissionDef",
+        on_delete=models.PROTECT,
+        related_name="role_assignments",
+    )
+    value = models.JSONField()
+    updated_by = models.ForeignKey(
+        "org.Staff",
+        null=True,
+        blank=True,
+        on_delete=models.SET_NULL,
+        related_name="role_permissions_updated",
+    )
+
+    class Meta:
+        db_table = "role_permissions"
+        constraints = [
+            models.UniqueConstraint(
+                fields=["role", "permission_def"],
+                name="uq_role_permissions",
+            ),
+        ]
+        indexes = [
+            models.Index(fields=["role"], name="idx_role_permissions_role"),
+            models.Index(fields=["permission_def"], name="idx_role_permissions_def"),
+        ]
+
+    def __str__(self) -> str:
+        return f"{self.role.name} → {self.permission_def.code}"

apps/permission/models/staff_perm.py

@@ -0,0 +1,200 @@
+from django.db import models
+
+from core.enums import (
+    PermissionChangeAction,
+    PermissionChangeTargetType,
+    PermissionDataScopeType,
+    PermissionOverrideMode,
+)
+from core.models.base import TimeStampedModel, UUIDPrimaryKeyModel
+
+
+class StaffRole(UUIDPrimaryKeyModel):
+    staff = models.ForeignKey(
+        "org.Staff",
+        on_delete=models.CASCADE,
+        related_name="staff_roles",
+    )
+    role = models.ForeignKey(
+        "fonrey_permission.Role",
+        on_delete=models.PROTECT,
+        related_name="staff_links",
+    )
+    is_primary = models.BooleanField(default=False)
+    assigned_at = models.DateTimeField(auto_now_add=True)
+    assigned_by = models.ForeignKey(
+        "org.Staff",
+        null=True,
+        blank=True,
+        on_delete=models.SET_NULL,
+        related_name="staff_role_assignments_made",
+    )
+    valid_from = models.DateField(null=True, blank=True)
+    valid_until = models.DateField(null=True, blank=True)
+
+    class Meta:
+        db_table = "staff_roles"
+        constraints = [
+            models.UniqueConstraint(
+                fields=["staff", "role"],
+                name="uq_staff_roles",
+            ),
+            models.UniqueConstraint(
+                fields=["staff"],
+                condition=models.Q(is_primary=True),
+                name="uq_staff_roles_primary",
+            ),
+        ]
+        indexes = [
+            models.Index(fields=["role"], name="idx_staff_roles_role"),
+        ]
+
+    def __str__(self) -> str:
+        marker = " [primary]" if self.is_primary else ""
+        return f"{self.staff_id} → {self.role_id}{marker}"
+
+
+class StaffPermissionOverride(UUIDPrimaryKeyModel):
+    staff = models.ForeignKey(
+        "org.Staff",
+        on_delete=models.CASCADE,
+        related_name="permission_overrides",
+    )
+    permission_def = models.ForeignKey(
+        "fonrey_permission.PermissionDef",
+        on_delete=models.PROTECT,
+        related_name="staff_overrides",
+    )
+    value = models.JSONField()
+    override_mode = models.CharField(
+        max_length=10,
+        choices=PermissionOverrideMode.choices,
+        default=PermissionOverrideMode.REPLACE,
+    )
+    reason = models.TextField(blank=True, default="")
+    modified_by = models.ForeignKey(
+        "org.Staff",
+        null=True,
+        blank=True,
+        on_delete=models.SET_NULL,
+        related_name="staff_overrides_modified",
+    )
+    modified_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        db_table = "staff_permission_overrides"
+        constraints = [
+            models.UniqueConstraint(
+                fields=["staff", "permission_def"],
+                name="uq_staff_overrides",
+            ),
+        ]
+        indexes = [
+            models.Index(fields=["staff"], name="idx_staff_overrides_staff"),
+        ]
+
+
+class StaffDataScope(UUIDPrimaryKeyModel):
+    staff = models.ForeignKey(
+        "org.Staff",
+        on_delete=models.CASCADE,
+        related_name="data_scopes",
+    )
+    scope_type = models.CharField(
+        max_length=20,
+        choices=PermissionDataScopeType.choices,
+    )
+    org_unit = models.ForeignKey(
+        "org.OrgUnit",
+        null=True,
+        blank=True,
+        on_delete=models.PROTECT,
+        related_name="data_scope_grants",
+    )
+    is_readable = models.BooleanField(default=True)
+    is_writable = models.BooleanField(default=False)
+    granted_by = models.ForeignKey(
+        "org.Staff",
+        null=True,
+        blank=True,
+        on_delete=models.SET_NULL,
+        related_name="data_scopes_granted",
+    )
+    granted_at = models.DateTimeField(auto_now_add=True)
+    expires_at = models.DateTimeField(null=True, blank=True)
+    reason = models.TextField(blank=True, default="")
+
+    class Meta:
+        db_table = "staff_data_scopes"
+        indexes = [
+            models.Index(fields=["staff"], name="idx_data_scopes_staff"),
+            models.Index(fields=["org_unit"], name="idx_data_scopes_org"),
+            models.Index(
+                fields=["expires_at"],
+                name="idx_data_scopes_expires",
+                condition=models.Q(expires_at__isnull=False),
+            ),
+        ]
+
+
+class PermissionChangeLog(UUIDPrimaryKeyModel):
+    target_type = models.CharField(
+        max_length=30,
+        choices=PermissionChangeTargetType.choices,
+    )
+    target_id = models.UUIDField()
+    staff = models.ForeignKey(
+        "org.Staff",
+        null=True,
+        blank=True,
+        on_delete=models.SET_NULL,
+        related_name="permission_change_logs_affecting",
+    )
+    role = models.ForeignKey(
+        "fonrey_permission.Role",
+        null=True,
+        blank=True,
+        on_delete=models.SET_NULL,
+        related_name="change_logs",
+    )
+    permission_code = models.CharField(max_length=150, blank=True, default="")
+    action = models.CharField(max_length=20, choices=PermissionChangeAction.choices)
+    old_value = models.JSONField(null=True, blank=True)
+    new_value = models.JSONField(null=True, blank=True)
+    operator = models.ForeignKey(
+        "org.Staff",
+        on_delete=models.PROTECT,
+        related_name="permission_changes_operated",
+    )
+    operator_ip = models.GenericIPAddressField(null=True, blank=True)
+    user_agent = models.TextField(blank=True, default="")
+    reason = models.TextField(blank=True, default="")
+    operated_at = models.DateTimeField(auto_now_add=True)
+
+    class Meta:
+        db_table = "permission_change_logs"
+        ordering = ["-operated_at"]
+        indexes = [
+            models.Index(
+                fields=["staff", "-operated_at"],
+                name="idx_perm_log_staff",
+                condition=models.Q(staff__isnull=False),
+            ),
+            models.Index(
+                fields=["role", "-operated_at"],
+                name="idx_perm_log_role",
+                condition=models.Q(role__isnull=False),
+            ),
+            models.Index(
+                fields=["target_type", "target_id", "-operated_at"],
+                name="idx_perm_log_target",
+            ),
+            models.Index(
+                fields=["operator", "-operated_at"],
+                name="idx_perm_log_operator",
+            ),
+            models.Index(fields=["-operated_at"], name="idx_perm_log_time"),
+        ]
+
+    def delete(self, *args, **kwargs):
+        raise NotImplementedError("PermissionChangeLog is append-only and cannot be deleted.")

apps/permission/urls.py

@@ -0,0 +1,5 @@
+from django.urls import path
+
+app_name = "permission"
+
+urlpatterns: list = []