docs: add environment example templates

.env.development.example

@@ -0,0 +1,34 @@
+# 本地开发环境模板
+# 使用方式：cp .env.development.example .env
+# 注意：如果本地连接线上数据库，不要开启 BACKGROUND_TASKS_ENABLED，避免本机抢占线上后台任务。
+
+# 数据库连接配置
+MYSQL_HOST=127.0.0.1
+MYSQL_PORT=3306
+MYSQL_DATABASE=jiaheng_erp
+MYSQL_USER=root
+MYSQL_PASSWORD=change_me
+
+# 应用运行配置
+APP_ENV=development
+APP_TIMEZONE=Asia/Shanghai
+JWT_SECRET=change_me_to_a_long_random_string
+TOKEN_EXPIRE_MINUTES=43200
+AUTO_CREATE_TABLES=false
+BACKGROUND_TASKS_ENABLED=false
+
+# 微信小程序配置
+WECHAT_APP_ID=
+WECHAT_APP_SECRET=
+WECHAT_QR_ENV_VERSION=release
+JH_QR_FONT_PATH=
+
+# 静态资源与公网访问配置
+# 手机真机调试时，PUBLIC_BASE_URL 通常需要改为本机局域网地址，例如 http://192.168.x.x:8020。
+PUBLIC_BASE_URL=http://127.0.0.1:8000
+UPLOAD_DIR=uploads
+
+# ERP 扫码登录配置
+ERP_API_BASE_URL=http://127.0.0.1:8000
+ERP_QR_LOGIN_SHARED_SECRET=replace-with-same-secret-on-erp-backend
+ERP_LOGIN_QRCODE_DIR=erp-login-qrcodes

.env.example

@@ -1,20 +1,58 @@
-MYSQL_HOST=121.40.97.156
+# 完整参数说明模板。
+# 本地开发可复制 .env.development.example 为 .env。
+# 生产部署可复制 .env.production.example 为 .env，并替换其中的占位值。
+
+# 数据库连接配置
+# MySQL 服务地址。生产环境填写阿里云或内网数据库地址；本地开发可填 127.0.0.1。
+MYSQL_HOST=127.0.0.1
+# MySQL 端口。
 MYSQL_PORT=3306
+# MySQL 数据库名。
 MYSQL_DATABASE=jiaheng_erp
+# MySQL 用户名。
 MYSQL_USER=root
+# MySQL 密码。不要在仓库中提交真实密码。
 MYSQL_PASSWORD=change_me
 
+# 应用运行配置
+# 运行环境：development / production。production 默认会启用后台任务。
 APP_ENV=development
+# 系统时区，用于报工、审核、自动提交等时间计算。
 APP_TIMEZONE=Asia/Shanghai
+# JWT 签名密钥。生产环境必须替换成足够长的随机字符串，并妥善保管。
 JWT_SECRET=change_me_to_a_long_random_string
+# 登录令牌有效期，单位：分钟。43200 表示 30 天。
 TOKEN_EXPIRE_MINUTES=43200
+# 是否启动时自动建表。生产环境建议 false，表结构通过迁移脚本维护。
 AUTO_CREATE_TABLES=false
+# 是否启用后台任务。不配置时按 APP_ENV 判断：production 启用，development 不启用。
+# 后台任务包含超时报工自动提交、二维码 ZIP 批量生成等。
+# 本地连接线上数据库时不要随意设为 true，避免本机抢占线上后台任务。
+# BACKGROUND_TASKS_ENABLED=true
 
+# 微信小程序配置
+# 微信小程序 AppID。
 WECHAT_APP_ID=
+# 微信小程序 AppSecret。不要提交真实密钥。
 WECHAT_APP_SECRET=
+# 生成小程序码使用的版本：release / trial / develop。
+WECHAT_QR_ENV_VERSION=release
+# 二维码底部中文标签字体路径。留空时使用系统默认候选字体；服务器缺字体时可指定字体文件绝对路径。
+JH_QR_FONT_PATH=
+
+# 静态资源与公网访问配置
+# 后端对外访问地址，用于拼接二维码、ZIP、ERP 登录码等可下载资源 URL。
+# 生产环境示例：https://api.jiahengsmart.top
+# 本地开发可用：http://127.0.0.1:8000 或局域网地址。
 PUBLIC_BASE_URL=http://127.0.0.1:8000
+# 上传与生成文件目录。相对路径会按后端进程启动目录解析。
+# 二维码图片默认在 UPLOAD_DIR/qrcodes，批量 ZIP 默认在 UPLOAD_DIR/qrcode_zips。
 UPLOAD_DIR=uploads
 
+# ERP 扫码登录配置
+# ERP 后端接口地址，小程序后端会代理调用 ERP 扫码登录相关接口。
 ERP_API_BASE_URL=http://127.0.0.1:8000
+# ERP 扫码登录共享签名密钥，必须和 ERP 后端保持一致。
 ERP_QR_LOGIN_SHARED_SECRET=replace-with-same-secret-on-erp-backend
+# ERP 登录小程序码生成目录，实际路径为 UPLOAD_DIR/ERP_LOGIN_QRCODE_DIR。
 ERP_LOGIN_QRCODE_DIR=erp-login-qrcodes

.env.production.example

@@ -0,0 +1,34 @@
+# 生产环境模板
+# 使用方式：cp .env.production.example .env
+# 注意：生产环境必须替换所有 change_me / replace-with-* 占位值，真实密钥不要提交到仓库。
+
+# 数据库连接配置
+MYSQL_HOST=replace-with-production-mysql-host
+MYSQL_PORT=3306
+MYSQL_DATABASE=jiaheng_erp
+MYSQL_USER=replace-with-production-mysql-user
+MYSQL_PASSWORD=change_me
+
+# 应用运行配置
+APP_ENV=production
+APP_TIMEZONE=Asia/Shanghai
+JWT_SECRET=change_me_to_a_long_random_string
+TOKEN_EXPIRE_MINUTES=43200
+AUTO_CREATE_TABLES=false
+BACKGROUND_TASKS_ENABLED=true
+
+# 微信小程序配置
+WECHAT_APP_ID=replace-with-wechat-app-id
+WECHAT_APP_SECRET=replace-with-wechat-app-secret
+WECHAT_QR_ENV_VERSION=release
+# 服务器缺少中文字体时，填写字体文件绝对路径，例如 /usr/share/fonts/truetype/noto/NotoSansCJK-Regular.ttc。
+JH_QR_FONT_PATH=
+
+# 静态资源与公网访问配置
+PUBLIC_BASE_URL=https://api.jiahengsmart.top
+UPLOAD_DIR=uploads
+
+# ERP 扫码登录配置
+ERP_API_BASE_URL=https://replace-with-erp-api-domain
+ERP_QR_LOGIN_SHARED_SECRET=replace-with-same-secret-on-erp-backend
+ERP_LOGIN_QRCODE_DIR=erp-login-qrcodes