docs(config): 补 .env.example 并修正 .gitignore 误伤模板

.gitignore 的 `.env.*` 会把 `.env.example` 一起排除，等于把变量清单挡在仓库外，
接手的人只能翻 application.yml 逐个猜要配什么。加 `!.env.example`（含
`.sample`、`.template`）例外，规则顺序放在忽略之后。

同时补 .env.example：从 application.yml 与代码里实际提取 20 个变量，分组注明
默认值与是否必须替换。三个必改项（DB_PASS 无默认、GATEWAY_TOKEN 占位、
BIZ_TOKEN_SECRET 与 BIZ_PII_KEY 为 dev-only）单独标出。

本文件只放占位值；真实的 .env 仍不入库。另注明工程不自动读 .env
（未引入 dotenv），必须由启动脚本加载或 docker compose --env-file 注入——
这一条不说清，会有人建了 .env 直接启动然后发现 DB_PASS 还是缺。

.env.example

@@ -0,0 +1,76 @@
+# =============================================================
+# 环境变量清单（模板）
+#
+# 用法：复制成 .env，按需修改，然后由启动脚本注入。
+#     cp .env.example .env
+#
+# 注意：本工程**不会自动读取 .env 文件**（未引入 dotenv），
+# Spring Boot 只认进程环境变量。所以 .env 必须被"加载"进去：
+#
+#     Linux/macOS:  set -a; . ./.env; set +a; java -jar target/aomin-gateway-*.jar
+#     Windows cmd:  for /f "usebackq tokens=1,* delims==" %i in (".env") do set %i=%j
+#     容器:         docker compose --env-file .env up -d
+#
+# 真实的 .env **不入库**（.gitignore 已挡）。本文件只放占位值。
+# 新增变量时同步本文件，否则接手的人不知道要配什么。
+# =============================================================
+
+# ---------- 数据库 ----------
+# DB_PASS 是唯一必填项。留空或缺失时应用立即退出（退出码 1），
+# 不会带空口令去连库，也不会回退到任何内置口令。填了真实值也别提交。
+DB_PASS=
+DB_HOST=127.0.0.1
+DB_PORT=3306
+DB_NAME=aomin_dev
+# 开发机常用 root；生产必须换成只有 DML 权限的业务账号
+DB_USER=root
+
+# ---------- Redis（仅作锁与缓存，非数据源） ----------
+REDIS_HOST=127.0.0.1
+REDIS_PORT=6379
+
+# ---------- 日志 ----------
+LOG_DIR=./logs
+
+# ---------- 内部接口鉴权（/internal/**） ----------
+# 默认关闭签名校验，仅靠来源网络闸防护。上线前必须改为 true。
+GATEWAY_AUTH_ENABLED=false
+# 共享密钥。J-00 §1.2 的签名公式里 key 就是它。
+# 当前值是占位值，生产必须替换；留空则签名校验必然失败。
+GATEWAY_TOKEN=
+# 来源网络闸，与签名开关独立，默认开。
+# 签名可以晚点开，网络闸必须一开始就有——两个都关，/internal/** 就是裸奔。
+GATEWAY_NETWORK_GUARD=true
+
+# ---------- 业务安全 ----------
+# 家属端 token 的签名密钥。占位值 dev-only-change-me-2026 仅用于本机。
+BIZ_TOKEN_SECRET=
+# 身份证等 PII 字段的加密密钥。占位值 dev-only-pii-key-2026 仅用于本机。
+# 换密钥会导致已入库的密文无法解密，上线后不要再改。
+BIZ_PII_KEY=
+
+# ---------- 短信 ----------
+# demo=true 时不真发短信，只落库并在响应里回显验证码
+BIZ_SMS_DEMO=true
+BIZ_SMS_ECHO=true
+# 同一手机号在此窗口内的短信合并为一条
+BIZ_SMS_MERGE_SECONDS=60
+
+# ---------- 演示数据 ----------
+# true 会向数据库播种演示账号与样例数据。**生产环境严禁开启。**
+BIZ_DEMO_ENABLED=false
+
+# ---------- 告警 ----------
+# 单条告警最大重试次数
+ALARM_MAX_TRY=3
+# 同一设备此窗口内的推送合并为一次
+ALARM_PUSH_MERGE_SECONDS=5
+
+# ---------- 分区维护 ----------
+# 定时任务，依赖 Redis 取锁；Redis 不可用时跳过并告警，不影响告警主链
+PARTITION_MAINTAIN_ENABLED=true
+
+# ---------- 设备模拟器（demo/sim，仅本地联调用） ----------
+# 不属于后端配置，只被 sim_device.py 读取
+SIM_BASE=http://127.0.0.1:8080
+SIM_PORT=9901

.gitignore

@@ -14,8 +14,13 @@ out/
 *.ear
 
 # ---------- 本地配置（可能含口令，绝不入库） ----------
+# 真实的 .env 一律不入库；但"变量清单"模板必须入库，
+# 否则接手的人不知道要配哪些变量。模板里只放占位值，不放真实值。
 .env
 .env.*
+!.env.example
+!.env.sample
+!.env.template
 *.local.yml
 application-local.yml
 application-*-local.yml

CHANGELOG.md

@@ -7,6 +7,18 @@
 
 ---
 
+## [Unreleased]
+
+### Added
+
+- `.env.example`：20 个环境变量的清单模板（数据库、Redis、日志、内部接口鉴权、业务密钥、短信、演示数据、告警、分区维护、设备模拟器），每项注明默认值与是否必须替换。真实 `.env` 不入库。
+
+### Fixed
+
+- `.gitignore` 的 `.env.*` 会把 `.env.example` 一并排除，导致变量清单无法入库。已加 `!.env.example`（以及 `.sample`、`.template`）例外。
+
+---
+
 ## [V1.9-baseline] - 2026-11-13
 
 首次入库，对应周工交付的 `SEC-Z-01 清理后` 源码包。

CONTRIBUTING.md

@@ -59,6 +59,8 @@ rawRef 指向不存在的行时，原先抛 NPE 被全局兜底成 500，
 | 运行产物 | 日志、`*.jsonl`、证据 `raw/`、截图 |
 | 公司无关资料 | 员工绩效、客户名单、采购函、其他项目报价 |
 
+**唯一例外是 `.env.example`。** 它是变量清单模板，必须入库——不入库接手的人就不知道要配哪些变量，只能去翻 `application.yml` 逐个猜。模板里只放占位值，真实值填在本地 `.env` 里。新增环境变量时同步更新它，否则清单很快就不准了。
+
 `.gitignore` 已经覆盖上述路径，但**它只挡新增，不挡已提交**。加文件前先 `git status` 看一眼。
 
 判断标准很简单：**这个文件一旦公开，会不会造成损失？** 会，就不要放进来。Git 的历史是追加式的，删除只影响最新版本，历史里那份永远在。

README.md

@@ -36,6 +36,7 @@
 │   ├── handover/         交付与安全清理材料（Z-01／Z-02）
 │   ├── contract/         接口契约：J-00 规格、OpenAPI、内部五接口、状态机
 │   └── reference/        原始交付包指纹与迁移脚本哈希
+├── .env.example          环境变量清单模板（20 项，真实 .env 不入库）
 ├── .gitattributes        行尾与二进制策略
 ├── .editorconfig         缩进与编码
 ├── CHANGELOG.md          版本记录
@@ -52,15 +53,21 @@ cd aomin-gateway
 mvn -DskipTests clean package
 # 产物：target/aomin-gateway-0.0.1-SNAPSHOT.jar
 
-# 2) 启动（DB_PASS 必填，缺失时应用立即退出，不会回退到任何内置口令）
-export DB_PASS='<口令>'
-export DB_USER=aomin
-java -jar target/aomin-gateway-0.0.1-SNAPSHOT.jar --server.port=8080 --server.address=0.0.0.0
+# 2) 配置环境变量（20 个变量的清单见仓库根 .env.example）
+cd ..
+cp .env.example .env      # 把 DB_PASS 填上，其余按需改
+set -a; . ./.env; set +a  # 工程不会自动读 .env，必须加载进进程环境
 
-# 3) 自检
+# 3) 启动（DB_PASS 必填，缺失时应用立即退出，不会回退到任何内置口令）
+export DB_USER=aomin
+java -jar aomin-gateway/target/aomin-gateway-0.0.1-SNAPSHOT.jar --server.port=8080 --server.address=0.0.0.0
+
+# 4) 自检
 curl -s http://127.0.0.1:8080/health
 ```
 
+`.env.example` 是变量清单模板，含数据库、Redis、内部接口鉴权、业务密钥、短信、告警、分区维护、模拟器共 20 项，每项都注明默认值与是否必须替换。真实的 `.env` 不入库。
+
 正常返回需同时满足 `db: connected`、`tables: 87`、`flyway: 1.0.28`、`status: UP`。
 
 建库、环境变量、systemd 单元、Flyway 校验和不符的处理，全部在 [`aomin-gateway/README.md`](aomin-gateway/README.md)。

SECURITY.md

@@ -15,6 +15,8 @@
 
 口令、token、AK/SK、私钥与证书、`.env` 与 `*.local.yml`、含口令的截图、真实的第三方服务密钥。
 
+**模板文件 `.env.example` 是例外**：它只含变量名与占位值，必须入库，否则接手的人不知道要配哪些变量。往模板里填真实值就不再是模板了。
+
 完整清单与目录约定见 [`CONTRIBUTING.md`](CONTRIBUTING.md) 第三节。
 
 ## 三、发现泄露后的处置顺序