From 48b69793ce02ab25f69adbc1f697e85cdc007b77 Mon Sep 17 00:00:00 2001
From: Yaosanqi137 <zxc18023571263@outlook.com>
Date: Sun, 5 Apr 2026 14:28:13 +0800
Subject: [PATCH] docs(api-env): improve .env.example comments and grouping

---
 apps/api/.env.example | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/apps/api/.env.example b/apps/api/.env.example
index 68af79c..971b829 100644
--- a/apps/api/.env.example
+++ b/apps/api/.env.example
@@ -1,27 +1,65 @@
+# -----------------------------------------------------------------------------
+# TodoList API 环境变量示例
+# 用法：
+# 1) 复制为 apps/api/.env
+# 2) 按实际环境替换值（尤其是密钥、密码、令牌）
+# -----------------------------------------------------------------------------
+
+# [数据库] PostgreSQL 连接串
+# 格式：postgresql://<user>:<password>@<host>:<port>/<db>?schema=public
 DATABASE_URL="postgresql://postgres:postgres@localhost:5432/todolist?schema=public"
+
+# [鉴权] Access Token 签名密钥（生产环境必须使用高强度随机值）
 AUTH_ACCESS_SECRET="dev-access-secret"
+# [鉴权] Access Token 有效期（秒），默认 15 分钟
 AUTH_ACCESS_EXPIRES_IN_SECONDS="900"
+# [鉴权] Refresh Token 有效期（秒），默认 30 天
 AUTH_REFRESH_EXPIRES_IN_SECONDS="2592000"
+# [鉴权] 邮箱验证码有效期（秒），默认 5 分钟
 AUTH_EMAIL_CODE_TTL_SECONDS="300"
+# [2FA] TOTP 签发方名称（会显示在验证器 App 中）
 AUTH_TOTP_ISSUER="TodoList"
+
+# [OAuth - GitHub] 第三方登录配置
 OAUTH_GITHUB_CLIENT_ID="github-client-id"
 OAUTH_GITHUB_CLIENT_SECRET="github-client-secret"
 OAUTH_GITHUB_CALLBACK_URL="http://localhost:3000/auth/oauth/github/callback"
+
+# [OAuth - QQ] 第三方登录配置
 OAUTH_QQ_CLIENT_ID="qq-client-id"
 OAUTH_QQ_CLIENT_SECRET="qq-client-secret"
 OAUTH_QQ_CALLBACK_URL="http://localhost:3000/auth/oauth/qq/callback"
 OAUTH_QQ_AUTH_URL="https://graph.qq.com/oauth2.0/authorize"
 OAUTH_QQ_TOKEN_URL="https://graph.qq.com/oauth2.0/token"
+
+# [OAuth - 微信] 第三方登录配置
 OAUTH_WECHAT_CLIENT_ID="wechat-client-id"
 OAUTH_WECHAT_CLIENT_SECRET="wechat-client-secret"
 OAUTH_WECHAT_CALLBACK_URL="http://localhost:3000/auth/oauth/wechat/callback"
 OAUTH_WECHAT_AUTH_URL="https://open.weixin.qq.com/connect/qrconnect"
 OAUTH_WECHAT_TOKEN_URL="https://api.weixin.qq.com/sns/oauth2/access_token"
+
+# [对象存储] S3/MinIO 配置（附件上传）
+# 本地开发可使用 MinIO，生产可切换到云厂商 S3 兼容服务
 S3_ENDPOINT="http://127.0.0.1:9000"
 S3_REGION="us-east-1"
 S3_BUCKET="todolist"
 S3_ACCESS_KEY_ID="minioadmin"
 S3_SECRET_ACCESS_KEY="minioadmin"
+# MinIO 常用 true；AWS S3 常用 false
 S3_FORCE_PATH_STYLE="true"
+# 预签名上传 URL 的有效期（秒）
 S3_PRESIGN_EXPIRES_SECONDS="900"
+# 对外访问附件的基础地址（用于拼接公开 URL）
 S3_PUBLIC_BASE_URL="http://127.0.0.1:9000"
+
+# [邮件] SMTP 配置（验证码/DDL 提醒邮件）
+MAIL_SMTP_HOST="smtp.example.com"
+MAIL_SMTP_PORT="465"
+# 465 通常为 true（SSL），587 通常为 false（STARTTLS）
+MAIL_SMTP_SECURE="true"
+MAIL_SMTP_USER="no-reply@example.com"
+MAIL_SMTP_PASS="replace-with-smtp-password"
+# 发件人显示名称与地址
+MAIL_FROM_NAME="TodoList"
+MAIL_FROM_ADDRESS="no-reply@example.com"