magic-dash-pro是适用于多页面、持续扩展的管理型应用模板，内置用户名密码登录、可选的邮件验证码登录、可选的OTP动态口令登录、用户管理、部门管理、角色权限、数据库模型和鉴权能力，适合构建需要复杂用户与部门关系的业务系统。创建时可以选择Flask或FastAPI后端变体。

magic-dash create --name magic-dash-pro

命令会先提示选择后端类型：

• Flask：默认后端，基于flask-login
• FastAPI：可选后端，基于fastapi-login

🚀 后端选择建议：

• 当项目需要更强的并发服务能力、原生异步支持、WebSocket等能力时，推荐选择FastAPI后端。
• 当项目更偏轻量化，且希望代码编写和后续维护更简单时，推荐选择Flask后端。

后端选择完成后，命令会继续提示选择数据库ORM引擎：

• Peewee：默认引擎，保持历史模板行为
• SQLAlchemy：使用SQLAlchemy 2.x模型与Session实现
• SQLModel：使用SQLModel模型定义，并复用SQLAlchemy会话能力

随后会提示输入项目名称。直接回车时，默认生成magic-dash-pro目录。

创建过程中，CLI会自动从内置public_assets复制登录页所需的公共静态资源到生成项目中，并在终端展示复制状态：

assets/videos/login-bg.mp4
assets/imgs/login/gradient-bg.jpg
assets/imgs/login/gradient-bg-side.png

指定项目生成父目录：

magic-dash create --name magic-dash-pro --path ./workspace

直接指定后端类型：

magic-dash create --name magic-dash-pro --backend flask --path ./workspace
magic-dash create --name magic-dash-pro --backend fastapi --path ./workspace

直接指定ORM引擎：

magic-dash create --name magic-dash-pro --backend flask --orm-engine peewee --path ./workspace
magic-dash create --name magic-dash-pro --backend fastapi --orm-engine sqlalchemy --path ./workspace
magic-dash create --name magic-dash-pro --backend fastapi --orm-engine sqlmodel --path ./workspace

如果未传入--orm-engine，会默认生成Peewee版本。生成后的项目只会保留被选中的ORM模型代码与依赖，不会携带其他ORM实现目录。

原始模板的requirements.txt不预置任何ORM依赖。创建项目时，CLI会把当前选择的ORM依赖追加到生成项目requirements.txt末尾：

ORM引擎在项目创建时确定。生成完成后，项目只保留所选引擎对应的模型代码与依赖。

等价的简写形式：

magic-dash create -n magic-dash-pro -b flask -p ./workspace
magic-dash create -n magic-dash-pro -b fastapi -p ./workspace

magic-dash-pro-fastapi是内部后端变体，不能作为顶层模板通过--name直接创建。

cd magic-dash-pro
pip install -r requirements.txt
python -m magic_init
python app.py

默认访问地址：

http://127.0.0.1:8050

若创建时选择FastAPI后端，部署时推荐使用：

uvicorn app:app.server --host 0.0.0.0 --port 8050 --workers 4

FastAPI后端的Swagger UI和ReDoc接口文档默认关闭。如需启用，可在configs/base_config.py中分别设置开关和访问路径：

class BaseConfig:
    enable_fastapi_docs = True
    fastapi_docs_pathname = "/api-docs"
    enable_fastapi_redoc = True
    fastapi_redoc_pathname = "/api-redoc"
    fastapi_docs_offline = True
    fastapi_docs_admin_only = True

重启应用并使用管理员账号登录后，可分别访问http://127.0.0.1:8050/api-docs和http://127.0.0.1:8050/api-redoc。fastapi_docs_offline=True会让两种文档统一使用模板内置的离线静态资源；保留默认值False则继续使用FastAPI默认外部CDN。fastapi_docs_admin_only默认为True，会同时保护两个文档页面、OAuth2 redirect和/openapi.json；如需公开访问，可显式设置为False。两个文档页面共用Dash实例内置的同一个FastAPI服务对象。完整参数规则见配置参数。

初始化时会提示填写可选的初始管理员邮箱，并展示内置数据表创建记录。若计划使用邮件验证码登录，建议在此处设置一个能够接收验证码的邮箱；直接回车则不为管理员关联邮箱。

初始化成功后，默认管理员账号为：

用户名：admin
初始密码：admin123

生产环境请在首次登录后尽快修改默认密码，并替换应用密钥和数据库连接信息。

邮件验证码登录默认关闭。如需启用，请完成以下设置后重新启动应用：

1. 在configs/base_config.py中将BaseConfig.enable_email_login设置为True。
2. 在configs/email_config.py中配置SMTP服务、发件邮箱和授权码。
3. 确认需要使用该方式登录的用户已关联唯一且有效的邮箱。

OTP动态口令登录同样默认关闭。如需启用，请将configs/base_config.py中的BaseConfig.enable_otp_login设置为True，按需调整configs/otp_config.py，重启后用户可在右上角用户菜单中完成OTP绑定，再从登录页“更多登录方式”使用用户名和认证器App中的6位动态口令登录。

详细参数及连接方式见配置参数，已有项目的数据库升级和用户邮箱维护说明见二次开发指南。

magic-dash-pro/
├── app.py
├── server.py
├── magic_init.py
├── requirements.txt
├── assets/
│   ├── css/
│   ├── imgs/
│   ├── js/
│   └── videos/
├── callbacks/
├── components/
├── configs/
├── models/
├── utils/
└── views/

关键目录说明：

为了降低源码仓库和发布包体积，magic-dash-pro与内部magic-dash-pro-fastapi模板共用的登录页视频和背景图片只在magic_dash/public_assets/中保留一份，模板目录下默认不跟踪这些大文件副本。

通常只需要通过magic-dash create创建项目，CLI会自动将公共资源复制到生成项目中。如果你在源码仓库内开发并需要恢复模板目录下的公共资源副本，可以运行：

magic-dash init-assets

如需在提交或发布前移除模板目录下的公共资源副本，可以运行：

magic-dash remove-assets

• 配置参数
• 二次开发指南
• 后端迁移指南
• CLI命令说明