feat(account): 实现双因素认证与密码重置功能

新增双因素认证(2FA)功能，支持TOTP验证器和恢复码
添加密码重置流程，包含邮件发送与密码修改页面
完善用户注册流程，增加邮箱字段验证
引入django-otp依赖并配置相关中间件
统一前端UI组件样式，使用DaisyUI规范
新增开发者API Token生成功能
优化用户设置中心，增加会话管理与安全设置

Author: Deali-Axy

pyproject.toml

@@ -8,6 +8,7 @@ authors = [
 dependencies = [
     "django[argon2]>=6.0",
     "django-ninja>=1.5.3",
+    "django-otp>=1.6.1",
     "django-multi-captcha-admin>=2.0.0",
     "django-simple-captcha>=0.6.3",
     "django-cors-headers>=4.9.0",
@@ -26,6 +27,7 @@ dependencies = [
     "requests>=2.32.5",
     "redis>=7.1.0",
     "pillow>=12.1.0",
+    "qrcode>=8.0",
     "pydantic>=2.12.5",
     "django-simple-history>=3.11.0",
     "django-jazzmin>=3.0.1",

src/apps/account/UI.md

@@ -0,0 +1,41 @@
+# Account 前端 UI 规范（DaisyUI）
+
+本文件用于固定 account 应用的 UI 组件选型与类名组合，避免模板与表单样式分散。
+
+## 表单（Form）
+
+- 输入框：`input input-bordered w-full`
+- 输入框错误态：`input input-bordered input-error w-full`
+- 下拉：`select select-bordered w-full`
+- 上传：`file-input file-input-bordered w-full`
+- 开关：`toggle toggle-primary`
+- 校验：在控件上追加 `validator`，错误提示使用 `validator-hint`
+
+## 按钮（Button）
+
+- 主按钮：`btn btn-primary`
+- 次按钮：`btn btn-secondary`
+- 轻量按钮：`btn btn-ghost`
+- 链接按钮：`btn btn-link`
+- 禁用：`btn btn-disabled` 或 `aria-disabled="true"`
+
+## 提示（Alert / Toast）
+
+- Alert：`alert` + `alert-success|alert-info|alert-warning|alert-error`
+- Toast 容器：`toast toast-top toast-end`
+
+## 对话框（Modal）
+
+- 统一使用 `dialog.modal` + `div.modal-box` + `form.modal-backdrop`
+
+## 导航（Menu / Tabs / Breadcrumbs）
+
+- 设置中心侧边栏：`ul.menu menu-md`
+- Tabs：`div.tabs` + `button.tab`，当前项加 `tab-active`
+
+## 布局（Card / Table / Steps）
+
+- 内容卡片：`card bg-base-100 shadow-sm border border-base-200`
+- 表格：`table table-zebra`，外层包 `div.overflow-x-auto`
+- 步骤：`ul.steps steps-vertical lg:steps-horizontal`，激活项加 `step-primary`
+

src/apps/account/apis/auth/apis.py

@@ -40,6 +40,9 @@ def register(request, data: RegisterSchema):
     if User.objects.filter(username=data.username).exists():
         return _resp.bad_request(request, '用户名已存在！')
 
+    if User.objects.filter(email=data.email).exists():
+        return _resp.bad_request(request, '邮箱已存在！')
+
     if data.phone:
         phone_pattern = '^(13[0-9]|14[5|7]|15[0|1|2|3|5|6|7|8|9]|18[0|1|2|3|5|6|7|8|9])\\d{8}$'
         if not re.match(phone_pattern, data.phone):
@@ -51,7 +54,7 @@ def register(request, data: RegisterSchema):
     if data.password != data.confirm_password:
         return _resp.bad_request(request, '密码不一致！')
 
-    user_obj: User = User.objects.create_user(data.username, None, data.password)
+    user_obj: User = User.objects.create_user(data.username, data.email, data.password)
 
     if data.phone:
         user_obj.profile.phone = data.phone

src/apps/account/apis/auth/schemas.py

@@ -15,6 +15,7 @@ class LoginToken(Schema):
 
 
 class RegisterSchema(Schema):
+    email: str
     username: str
     password: str
     confirm_password: str

src/apps/account/forms.py

@@ -13,13 +13,15 @@ class Meta:
         }
         widgets = {
             'full_name': forms.TextInput(attrs={
-                'class': 'bg-gray-50 border border-gray-300 text-gray-900 text-sm rounded-lg focus:ring-blue-500 focus:border-blue-500 block w-full p-2.5 dark:bg-gray-700 dark:border-gray-600 dark:placeholder-gray-400 dark:text-white dark:focus:ring-blue-500 dark:focus:border-blue-500'
+                'class': 'input input-bordered w-full',
+                'autocomplete': 'name',
             }),
             'gender': forms.Select(attrs={
-                'class': 'bg-gray-50 border border-gray-300 text-gray-900 text-sm rounded-lg focus:ring-blue-500 focus:border-blue-500 block w-full p-2.5 dark:bg-gray-700 dark:border-gray-600 dark:placeholder-gray-400 dark:text-white dark:focus:ring-blue-500 dark:focus:border-blue-500'
+                'class': 'select select-bordered w-full',
             }),
             'phone': forms.TextInput(attrs={
-                'class': 'bg-gray-50 border border-gray-300 text-gray-900 text-sm rounded-lg focus:ring-blue-500 focus:border-blue-500 block w-full p-2.5 dark:bg-gray-700 dark:border-gray-600 dark:placeholder-gray-400 dark:text-white dark:focus:ring-blue-500 dark:focus:border-blue-500'
+                'class': 'input input-bordered w-full',
+                'autocomplete': 'tel',
             }),
         }
 
@@ -28,43 +30,58 @@ class LoginForm(forms.Form):
     username = forms.CharField(
         label='用户名',
         widget=forms.TextInput(attrs={
-            'class': 'bg-gray-50 border border-gray-300 text-gray-900 rounded-lg focus:ring-primary-600 focus:border-primary-600 block w-full p-2.5 dark:bg-gray-700 dark:border-gray-600 dark:placeholder-gray-400 dark:text-white dark:focus:ring-blue-500 dark:focus:border-blue-500',
+            'class': 'input input-bordered w-full',
             'placeholder': '请输入用户名',
+            'autocomplete': 'username',
         }),
         min_length=4,
     )
     password = forms.CharField(
         label='密码',
         widget=forms.PasswordInput(attrs={
-            'class': 'bg-gray-50 border border-gray-300 text-gray-900 rounded-lg focus:ring-primary-600 focus:border-primary-600 block w-full p-2.5 dark:bg-gray-700 dark:border-gray-600 dark:placeholder-gray-400 dark:text-white dark:focus:ring-blue-500 dark:focus:border-blue-500',
+            'class': 'input input-bordered w-full',
             'placeholder': '请输入密码',
+            'autocomplete': 'current-password',
         }),
         min_length=4,
     )
 
 
 class RegisterForm(forms.Form):
+    email = forms.EmailField(
+        label='邮箱',
+        widget=forms.EmailInput(attrs={
+            'class': 'input input-bordered w-full',
+            'placeholder': 'name@example.com',
+            'autocomplete': 'email',
+        }),
+    )
     username = forms.CharField(
         label='用户名',
         widget=forms.TextInput(attrs={
-            'class': 'bg-gray-50 border border-gray-300 text-gray-900 rounded-lg focus:ring-primary-600 focus:border-primary-600 block w-full p-2.5 dark:bg-gray-700 dark:border-gray-600 dark:placeholder-gray-400 dark:text-white dark:focus:ring-blue-500 dark:focus:border-blue-500',
+            'class': 'input input-bordered w-full',
             'placeholder': '请输入用户名',
+            'autocomplete': 'username',
         }),
         min_length=4,
     )
     password = forms.CharField(
         label='密码',
         widget=forms.PasswordInput(attrs={
-            'class': 'bg-gray-50 border border-gray-300 text-gray-900 rounded-lg focus:ring-primary-600 focus:border-primary-600 block w-full p-2.5 dark:bg-gray-700 dark:border-gray-600 dark:placeholder-gray-400 dark:text-white dark:focus:ring-blue-500 dark:focus:border-blue-500',
+            'class': 'input input-bordered w-full',
             'placeholder': '请输入密码',
+            'autocomplete': 'new-password',
+            'x-model': 'pw',
         }),
         min_length=4,
     )
     confirm_password = forms.CharField(
         label='确认密码',
         widget=forms.PasswordInput(attrs={
-            'class': 'bg-gray-50 border border-gray-300 text-gray-900 rounded-lg focus:ring-primary-600 focus:border-primary-600 block w-full p-2.5 dark:bg-gray-700 dark:border-gray-600 dark:placeholder-gray-400 dark:text-white dark:focus:ring-blue-500 dark:focus:border-blue-500',
+            'class': 'input input-bordered w-full',
             'placeholder': '请输入确认密码',
+            'autocomplete': 'new-password',
+            'x-model': 'confirm',
         }),
         min_length=4,
     )

src/apps/account/migrations/0004_historicaluserprofile.py

@@ -0,0 +1,42 @@
+# Generated by Django 6.0.1 on 2026-01-22 18:51
+
+import django.db.models.deletion
+import simple_history.models
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('account', '0003_alter_userprofile_is_deleted'),
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='HistoricalUserProfile',
+            fields=[
+                ('id', models.BigIntegerField(auto_created=True, blank=True, db_index=True, verbose_name='ID')),
+                ('is_deleted', models.BooleanField(default=False, verbose_name='软删除标志')),
+                ('created_time', models.DateTimeField(blank=True, editable=False, verbose_name='创建时间')),
+                ('updated_time', models.DateTimeField(blank=True, editable=False, verbose_name='更新时间')),
+                ('full_name', models.CharField(default='', max_length=200, verbose_name='姓名')),
+                ('gender', models.CharField(choices=[('male', '男'), ('female', '女'), ('unknown', '未知')], default='unknown', max_length=20, verbose_name='性别')),
+                ('phone', models.CharField(default='', max_length=11, verbose_name='手机号')),
+                ('history_id', models.AutoField(primary_key=True, serialize=False)),
+                ('history_date', models.DateTimeField(db_index=True)),
+                ('history_change_reason', models.CharField(max_length=100, null=True)),
+                ('history_type', models.CharField(choices=[('+', 'Created'), ('~', 'Changed'), ('-', 'Deleted')], max_length=1)),
+                ('history_user', models.ForeignKey(null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='+', to=settings.AUTH_USER_MODEL)),
+                ('user', models.ForeignKey(blank=True, db_constraint=False, null=True, on_delete=django.db.models.deletion.DO_NOTHING, related_name='+', to=settings.AUTH_USER_MODEL)),
+            ],
+            options={
+                'verbose_name': 'historical 用户资料',
+                'verbose_name_plural': 'historical 用户资料',
+                'ordering': ('-history_date', '-history_id'),
+                'get_latest_by': ('history_date', 'history_id'),
+            },
+            bases=(simple_history.models.HistoricalChanges, models.Model),
+        ),
+    ]

src/apps/account/models.py

@@ -14,7 +14,13 @@ class Meta:
         verbose_name_plural = verbose_name
 
 
-# 创建用户的时候自动创建 profile
-# @receiver(signals.post_save, sender=User, dispatch_uid='django_user_post_save')
-# def create_user_profile(sender: User, instance: User, created, **kwargs):
-#     profile, created = UserProfile.objects.get_or_create(user=instance)
+@receiver(signals.post_save, sender=User, dispatch_uid='account_user_post_save_create_profile')
+def create_user_profile(sender: type[User], instance: User, created: bool, **kwargs):
+    """
+    确保 UserProfile 存在。
+
+    账号体系的多处逻辑依赖 `user.profile`，因此在用户创建时创建 profile，
+    并在后续保存时保证其存在。
+    """
+    if created:
+        UserProfile.objects.get_or_create(user=instance)

src/apps/account/templates/account/2fa/disable.html

@@ -0,0 +1,44 @@
+{% extends '_base.html' %}
+{% load page_tags %}
+
+{% block title %}关闭双因素认证{% endblock %}
+
+{% block content %}
+{% page_header title breadcrumbs %}
+
+<div class="mx-auto w-full max-w-md">
+    <div class="card bg-base-100 shadow-sm border border-base-200">
+        <div class="card-body gap-6">
+            <div class="space-y-1">
+                <h1 class="card-title text-2xl">关闭双因素认证</h1>
+                <p class="text-sm opacity-70">需要验证密码与验证码，避免误操作。</p>
+            </div>
+
+            <form method="post" class="space-y-4" novalidate>
+                {% csrf_token %}
+                <div class="space-y-1">
+                    <label class="label" for="password">
+                        <span class="label-text">密码</span>
+                    </label>
+                    <input id="password" name="password" type="password" autocomplete="current-password"
+                           class="input input-bordered w-full" required>
+                </div>
+                <div class="space-y-1">
+                    <label class="label" for="token">
+                        <span class="label-text">验证码 / 恢复码</span>
+                    </label>
+                    <input id="token" name="token" autocomplete="one-time-code"
+                           class="input input-bordered w-full" required>
+                </div>
+
+                <button type="submit" class="btn btn-error btn-block">确认关闭</button>
+            </form>
+
+            <div class="card-actions justify-end">
+                <a class="btn btn-ghost" href="{% url 'account:settings' %}">返回设置</a>
+            </div>
+        </div>
+    </div>
+</div>
+{% endblock %}
+

src/apps/account/templates/account/2fa/setup.html

@@ -0,0 +1,76 @@
+{% extends '_base.html' %}
+{% load page_tags %}
+
+{% block title %}启用双因素认证{% endblock %}
+
+{% block content %}
+{% page_header title breadcrumbs %}
+
+<div class="mx-auto w-full max-w-3xl space-y-4">
+    <div class="card bg-base-100 shadow-sm border border-base-200">
+        <div class="card-body gap-6">
+            <div class="space-y-1">
+                <h1 class="card-title text-2xl">启用双因素认证（2FA）</h1>
+                <p class="text-sm opacity-70">使用 Google Authenticator、Microsoft Authenticator 等应用扫码添加。</p>
+            </div>
+
+            <div class="grid grid-cols-1 lg:grid-cols-2 gap-6 items-start">
+                <div class="card bg-base-200/40 border border-base-300">
+                    <div class="card-body gap-3">
+                        <h2 class="font-semibold">1）扫码添加</h2>
+                        <div class="flex justify-center">
+                            <img src="{{ qr_data_uri }}" alt="2FA QR Code" class="rounded-lg border border-base-300 bg-base-100 p-2">
+                        </div>
+                        <div class="text-sm opacity-70">
+                            <p class="font-medium">手动输入密钥</p>
+                            <p class="font-mono break-all">{{ secret }}</p>
+                        </div>
+                    </div>
+                </div>
+
+                <div class="card bg-base-200/40 border border-base-300">
+                    <div class="card-body gap-3">
+                        <h2 class="font-semibold">2）输入验证码确认</h2>
+                        <form method="post" class="space-y-3" novalidate>
+                            {% csrf_token %}
+                            <div class="space-y-1">
+                                <label class="label" for="token">
+                                    <span class="label-text">验证码</span>
+                                </label>
+                                <input id="token" name="token" inputmode="numeric" autocomplete="one-time-code"
+                                       class="input input-bordered w-full" placeholder="6 位数字" required>
+                            </div>
+                            <button type="submit" class="btn btn-primary btn-block">确认启用</button>
+                        </form>
+                    </div>
+                </div>
+            </div>
+
+            {% if recovery_codes %}
+                <div class="divider"></div>
+                <div class="card bg-base-200/40 border border-base-300">
+                    <div class="card-body gap-3" x-data="{ copied: false }">
+                        <div class="flex items-center justify-between gap-4">
+                            <h2 class="font-semibold">恢复码（仅显示一次）</h2>
+                            <button type="button" class="btn btn-outline btn-sm"
+                                    @click="navigator.clipboard.writeText(Array.from($el.closest('.card-body').querySelectorAll('code')).map(e => e.innerText).join('\\n')).then(() => { copied = true; setTimeout(() => copied = false, 1200) })">
+                                复制全部
+                            </button>
+                        </div>
+                        <template x-if="copied">
+                            <p class="text-sm text-success">已复制到剪贴板</p>
+                        </template>
+                        <div class="grid grid-cols-1 sm:grid-cols-2 gap-2">
+                            {% for code in recovery_codes %}
+                                <code class="px-3 py-2 rounded-lg bg-base-100 border border-base-300 font-mono text-sm">{{ code }}</code>
+                            {% endfor %}
+                        </div>
+                        <p class="text-sm opacity-70">请妥善保存恢复码，遗失后可能无法找回账号。</p>
+                    </div>
+                </div>
+            {% endif %}
+        </div>
+    </div>
+</div>
+{% endblock %}
+

src/apps/account/templates/account/2fa/verify.html

@@ -0,0 +1,36 @@
+{% extends '_base.html' %}
+{% load page_tags %}
+
+{% block title %}双因素认证验证{% endblock %}
+
+{% block content %}
+{% page_header title breadcrumbs %}
+
+<div class="mx-auto w-full max-w-md">
+    <div class="card bg-base-100 shadow-sm border border-base-200">
+        <div class="card-body gap-6">
+            <div class="space-y-1">
+                <h1 class="card-title text-2xl">二次验证</h1>
+                <p class="text-sm opacity-70">输入验证码或恢复码以完成登录。</p>
+            </div>
+
+            <form method="post" class="space-y-4" novalidate>
+                {% csrf_token %}
+                <div class="space-y-1">
+                    <label class="label" for="token">
+                        <span class="label-text">验证码 / 恢复码</span>
+                    </label>
+                    <input id="token" name="token" autocomplete="one-time-code"
+                           class="input input-bordered w-full" placeholder="请输入验证码或恢复码" required>
+                </div>
+                <button type="submit" class="btn btn-primary btn-block">验证并登录</button>
+            </form>
+
+            <p class="text-xs opacity-70">
+                验证成功后将跳转至：{{ next }}
+            </p>
+        </div>
+    </div>
+</div>
+{% endblock %}
+