From b57070f3b3f3eb18dab79205e69098f6720f2e6d Mon Sep 17 00:00:00 2001 From: ishenwei Date: Thu, 30 Apr 2026 09:26:27 +0800 Subject: [PATCH] feat(account): add Chinese verbose_name and help_text to all account fields (Phase 4.1 part 5/9) Sync DATA_MODEL_LOGIN.md field-level Chinese annotations to Django models across 4 account tables (UserAccount, LoginAttempt, PasswordResetToken, PasswordHistory). --- apps/account/models/account.py | 126 +++++++++++++++++++++++++++------ 1 file changed, 106 insertions(+), 20 deletions(-) diff --git a/apps/account/models/account.py b/apps/account/models/account.py index bd73711..70b3f9a 100644 --- a/apps/account/models/account.py +++ b/apps/account/models/account.py @@ -17,37 +17,78 @@ class UserAccountManager(BaseUserManager): class UserAccount(AbstractBaseUser): - username = models.CharField(max_length=30) - email = models.EmailField(null=True, blank=True) + username = models.CharField( + max_length=30, + verbose_name="登录名", + help_text="普通员工=手机号(11位数字) / Tenant Admin=自定义(字母开头6~30位)；创建后不可更改", + ) + email = models.EmailField( + null=True, + blank=True, + verbose_name="绑定邮箱", + help_text="用于找回密码/用户名；为空则无法自助找回；同租户唯一", + ) phone_enc = models.TextField( null=True, blank=True, - help_text="AES-256-GCM ciphertext of phone (core.encryption.PhoneEncryption).", + verbose_name="手机号(加密)", + help_text="AES-256-GCM 加密密文；普通员工必填", + ) + phone_hash = models.CharField( + max_length=64, + null=True, + blank=True, + verbose_name="手机号哈希", + help_text="SHA-256 哈希；用于唯一性校验和查询；不可反推原文", ) - phone_hash = models.CharField(max_length=64, null=True, blank=True) staff = models.OneToOneField( "org.Staff", null=True, blank=True, on_delete=models.SET_NULL, related_name="account", + verbose_name="员工档案", + help_text="员工档案绑定（1:1）；普通员工必须有值；Tenant Admin 可为空", + ) + is_tenant_admin = models.BooleanField( + default=False, + verbose_name="是否租户超管", + help_text="每个租户最多 1 个（应用层约束）", ) - is_tenant_admin = models.BooleanField(default=False) status = models.CharField( max_length=10, choices=UserAccountStatus.choices, default=UserAccountStatus.ACTIVE, + verbose_name="账号状态", + help_text="active=正常 / disabled=停用 / locked=锁定（30 分钟自动恢复）", + ) + is_initial_password = models.BooleanField( + default=True, + verbose_name="是否初始密码", + help_text="True 时登录成功后强制跳转修改密码页，不可跳过", + ) + locked_until = models.DateTimeField( + null=True, + blank=True, + verbose_name="锁定到期时间", + help_text="到期后应用层将 status 恢复 active", + ) + created_at = models.DateTimeField( + auto_now_add=True, + verbose_name="创建时间", + ) + updated_at = models.DateTimeField( + auto_now=True, + verbose_name="最后更新时间", ) - is_initial_password = models.BooleanField(default=True) - locked_until = models.DateTimeField(null=True, blank=True) - created_at = models.DateTimeField(auto_now_add=True) - updated_at = models.DateTimeField(auto_now=True) created_by = models.ForeignKey( "self", null=True, blank=True, on_delete=models.SET_NULL, related_name="created_accounts", + verbose_name="创建人", + help_text="普通员工由 Tenant Admin 创建；Tenant Admin 由平台运营创建（可为 NULL）", ) USERNAME_FIELD = "username" @@ -90,17 +131,37 @@ class UserAccount(AbstractBaseUser): class LoginAttempt(models.Model): - username = models.CharField(max_length=30) - ip_address = models.GenericIPAddressField() - user_agent = models.TextField(null=True, blank=True) - success = models.BooleanField() + username = models.CharField( + max_length=30, + verbose_name="登录用户名", + help_text="冗余存储，即使账号不存在也记录", + ) + ip_address = models.GenericIPAddressField( + verbose_name="来源 IP", + help_text="支持 IPv4/IPv6", + ) + user_agent = models.TextField( + null=True, + blank=True, + verbose_name="客户端 UA", + help_text="Electron 版本信息", + ) + success = models.BooleanField( + verbose_name="是否登录成功", + ) failure_reason = models.CharField( max_length=30, null=True, blank=True, choices=LoginFailureReason.choices, + verbose_name="失败原因", + help_text="wrong_password=密码错误 / wrong_captcha=验证码失败 / account_locked=账号锁定 / account_disabled=账号停用 / tenant_not_found=租户不存在", + ) + attempted_at = models.DateTimeField( + auto_now_add=True, + verbose_name="尝试时间", + help_text="分区键，按月分区", ) - attempted_at = models.DateTimeField(auto_now_add=True) class Meta: db_table = "login_attempts" @@ -122,11 +183,27 @@ class PasswordResetToken(models.Model): "account.UserAccount", on_delete=models.CASCADE, related_name="reset_tokens", + verbose_name="关联账号", + ) + token = models.CharField( + max_length=86, + unique=True, + verbose_name="令牌", + help_text="secrets.token_urlsafe(64) 生成（86 字符），全局唯一", + ) + expires_at = models.DateTimeField( + verbose_name="过期时间", + help_text="created_at + 30 分钟", + ) + is_used = models.BooleanField( + default=False, + verbose_name="是否已使用", + help_text="使用后立即置 True，防止重放攻击", + ) + created_at = models.DateTimeField( + auto_now_add=True, + verbose_name="创建时间", ) - token = models.CharField(max_length=86, unique=True) - expires_at = models.DateTimeField() - is_used = models.BooleanField(default=False) - created_at = models.DateTimeField(auto_now_add=True) class Meta: db_table = "password_reset_tokens" @@ -145,9 +222,18 @@ class PasswordHistory(models.Model): "account.UserAccount", on_delete=models.CASCADE, related_name="password_histories", + verbose_name="关联账号", + ) + password_hash = models.CharField( + max_length=128, + verbose_name="密码哈希", + help_text="PBKDF2+SHA256 哈希值", + ) + created_at = models.DateTimeField( + auto_now_add=True, + verbose_name="记录时间", + help_text="密码修改时间", ) - password_hash = models.CharField(max_length=128) - created_at = models.DateTimeField(auto_now_add=True) class Meta: db_table = "password_histories"