docs(M00): 记录模块推送门禁顺序

docs/devlogs/2026-06-16-M00-V5-基线核验.md

@@ -9,6 +9,7 @@
 - 升级 `scripts/dev/wsl/mqtt-smoke.sh`，新增 MQTTX CLI 认证/ACL 冒烟入口、可选 TLS/遗嘱/重复消息探测入口和 Git 忽略的本地账号配置样例。
 - 补齐 `check-emqx.sh`、`start-emqx.sh`、`stop-emqx.sh` 三个 V5.0 点名的 WSL 本地 EMQX 辅助脚本入口。
 - 强化 `scripts/dev/windows/check-repo-completeness.ps1`，将仓库完整性从提示型检查升级为提交前门禁，并接入 `scripts/dev/windows/test-all.ps1`。
+- 调整 `scripts/dev/windows/push-module.ps1`，改为先暂存显式路径、再执行完整性门禁和测试，避免新增文件被门禁误拦截。
 
 ## 复用/改写/弃用判断
 
@@ -28,6 +29,7 @@
 - MQTT 高级探测入口：新增默认关闭的 `QIPAI_MQTT_ENABLE_TLS_SMOKE`、`QIPAI_MQTT_ENABLE_WILL_SMOKE`、`QIPAI_MQTT_ENABLE_IDEMPOTENCY_SMOKE`。无本地账号时仍输出 `SKIP`；有账号后可生成 TLS 发布、遗嘱观测尝试和重复 `idempotencyKey` 发布证据。
 - WSL EMQX 辅助脚本：新增 `check-emqx.sh` 复用服务级基线检查，`start-emqx.sh`/`stop-emqx.sh` 仅管理本地 EMQX systemd 服务；脚本不安装、不降级、不重置 EMQX。
 - 仓库完整性门禁：`check-repo-completeness.ps1` 现会检查必备文件是否 tracked、是否存在意外 untracked、嵌套 Git、`.gitmodules`、被跟踪的秘密/依赖/构建/备份/日志/上传文件，以及 `main...origin/main` 是否一致。
+- 模块推送脚本：`push-module.ps1` 现要求显式 `-Paths` 存在并先暂存，再运行 `test-all.ps1` 和敏感信息检查，随后 commit、push 并校验远端。
 - 敏感信息检查：已调整规则，空示例变量和 shell 参数展开不再误报，真实非占位长值仍会报警；`check-secrets.ps1` 通过。
 - Git 历史敏感模式扫描已执行，只记录命中提交，不输出秘密值。
 

docs/feature-status.md

@@ -6,7 +6,7 @@
 |---|---|---|---|---|---|---|---|
 | ENV-001 | 固定 Windows 工作区 | M00-A/M00-B | DONE | 远端 HEAD | 已确认 `D:\qipai`，Git 根、main 分支、固定 origin 和 push 校验通过。 | - | 后续每模块继续复检。 |
 | REF-001 | 参考资料完整纳管 | M00-A | PARTIAL | `7bb4338` | 已生成哈希清单、脱敏日志、页面地图、接口线索和旧数据库结构清单；含秘密/依赖/真实数据风险的原始包和 SQL 已移出 Git 跟踪；仓库完整性门禁已覆盖意外 untracked、嵌套 Git 和 forbidden tracked 文件。 | 后续仍需按模块生成正式源码/迁移，旧 xjar 需大文件策略。 | 进入 M00-B/M00-C 前继续保持原包忽略和摘要可追溯。 |
-| SCM-001 | 模块完成即完整推送 | M00-B/M00-C | PARTIAL | `7bb4338` | 首次 main push 成功，`HEAD == origin/main` 校验通过；推送脚本已生成；仓库完整性脚本已升级为提交前门禁并接入 `test-all.ps1`。 | 后续模块仍需逐次执行并记录。 | 继续在每轮提交前执行完整性、敏感信息、大文件和远端一致性检查。 |
+| SCM-001 | 模块完成即完整推送 | M00-B/M00-C | PARTIAL | `6052f34` | 首次 main push 成功，`HEAD == origin/main` 校验通过；推送脚本已生成；仓库完整性脚本已升级为提交前门禁并接入 `test-all.ps1`；`push-module.ps1` 已改为先暂存显式路径再运行门禁，支持新增文件提交。 | 后续模块仍需逐次执行并记录。 | 继续在每轮提交前执行完整性、敏感信息、大文件和远端一致性检查。 |
 | WSL-001 | WSL 隔离辅助验证 | M00-C | PARTIAL | `a690e85` | WSL 基础脚本已执行通过；本地 MQTT 服务级核验通过；认证/ACL 冒烟脚本入口、配置自检、可选 TLS/遗嘱/重复消息探测入口已生成；V5.0 点名的 WSL EMQX 检查/启动/停止入口已补齐。 | 正式后端/后台尚未生成，无法执行完整 Linux 构建；MQTT 本地账号未配置，认证/ACL/TLS/遗嘱/幂等未验收；生产 EMQX 不由 WSL 脚本管理。 | M01/M09 生成项目后在 WSL 原生临时副本执行完整构建；配置本地 MQTT 最小权限账号后执行冒烟和可选探测。 |
 | API-001 | 固定 HTTPS API 域名 | M00-E/M01/M08/M10 | PARTIAL | `4cb3ab6` | 已新增 Windows 检查脚本、Ubuntu 菜单检查和固定域名 Nginx 模板。 | DNS/HTTPS 生产验证未执行，后端健康接口未生成。 | 后续接入真实后端健康接口并执行 Windows/WSL/Ubuntu/微信真机验证。 |
 | TLS-001 | Nginx 与证书自动化 | M00-E/M10 | PARTIAL | `4cb3ab6` | 已生成 Nginx 模板、Certbot 命令说明和菜单第 4 项检查，可检查模板、站点启用、TLS、健康端点、证书文件、续期配置和 `certbot.timer`。 | 证书申请/续期 dry-run、80/443 生产验证未执行。 | 在生产 Ubuntu 执行证书签发、续期 dry-run 和 Nginx 安装记录。 |

docs/git-deployment.md

@@ -22,6 +22,16 @@ powershell -ExecutionPolicy Bypass -File scripts/dev/windows/push-module.ps1 `
   -Paths @("scripts/dev/windows/push-module.ps1", "docs/git-deployment.md")
 ```
 
+脚本执行顺序：
+
+1. 检查工作区、分支和固定远端。
+2. 只暂存 `-Paths` 显式列出的文件；路径不存在会失败。
+3. 执行 `test-all.ps1`、仓库完整性门禁和敏感信息检查。
+4. 提交并推送 `origin/main`。
+5. `git fetch origin main` 后校验 `HEAD == origin/main`。
+
+该顺序允许新增文件被显式暂存后再进入完整性门禁，同时避免 `git add .` 混入无关文件。
+
 如出现 `Host key verification failed`，先通过可信渠道确认 `git.txyundm.cn:2222` 的 SSH 主机指纹，再更新 `known_hosts`。Codex 不自动覆盖主机信任记录。
 
 ## SSH 检查
@@ -35,6 +45,7 @@ powershell -ExecutionPolicy Bypass -File scripts/dev/windows/check-gitea-ssh.ps1
 ## 当前记录
 
 - 2026-06-15 首次 `origin/main` push 已成功，且 `HEAD == origin/main` 校验通过。
+- 2026-06-16 `push-module.ps1` 已调整为先暂存显式路径、再运行完整性门禁，支持新增文件进入模块推送流程。
 - 如后续再次出现 `Host key verification failed`，仍应先通过可信渠道确认主机指纹，不自动追加或覆盖 known_hosts。
 
 ## 生产发布

docs/module-status.md

@@ -2,7 +2,7 @@
 
 | 模块 | 状态 | 最近提交 | 最近开发日志 | 备注 |
 |---|---|---|---|---|
-| M00 单仓库与服务器基础骨架 | PARTIAL | `7bb4338` | docs/devlogs/2026-06-16-M00-V5-基线核验.md | V5.0 已接入；已有成果基线、仓库完整性门禁、WSL 本地 MQTT 服务级核验、认证/ACL 冒烟入口、配置自检、可选 TLS/遗嘱/重复消息探测入口和 WSL EMQX 检查/启动/停止入口已补；生产部署、账号配置、真实验收和业务项目仍未完成。 |
+| M00 单仓库与服务器基础骨架 | PARTIAL | `6052f34` | docs/devlogs/2026-06-16-M00-V5-基线核验.md | V5.0 已接入；已有成果基线、仓库完整性门禁、显式路径模块推送脚本、WSL 本地 MQTT 服务级核验、认证/ACL 冒烟入口、配置自检、可选 TLS/遗嘱/重复消息探测入口和 WSL EMQX 检查/启动/停止入口已补；生产部署、账号配置、真实验收和业务项目仍未完成。 |
 | M01 后端 API 基础工程 | TODO | - | - | 等 M00 基线完成后开始。 |
 | M02 登录、租户、权限 | TODO | - | - | - |
 | M03 门店、房间、价格、营业时间 | TODO | - | - | - |

scripts/dev/windows/push-module.ps1

@@ -22,11 +22,6 @@ Run-Step "workspace check" {
   powershell -ExecutionPolicy Bypass -File scripts/dev/windows/check-workspace.ps1
 }
 
-Run-Step "local tests" {
-  powershell -ExecutionPolicy Bypass -File scripts/dev/windows/test-all.ps1
-  powershell -ExecutionPolicy Bypass -File scripts/dev/windows/check-secrets.ps1
-}
-
 Run-Step "git preflight" {
   $branch = & git branch --show-current
   if ($branch -ne "main") {
@@ -41,9 +36,12 @@ Run-Step "git preflight" {
   & git status --short --branch --untracked-files=all
 }
 
-Run-Step "stage files" {
+Run-Step "stage declared files" {
   if ($Paths.Count -gt 0) {
     foreach ($path in $Paths) {
+      if (-not (Test-Path $path)) {
+        throw "Path not found: $path"
+      }
       & git add -- $path
     }
   }
@@ -58,6 +56,11 @@ Run-Step "stage files" {
   }
 }
 
+Run-Step "local tests" {
+  powershell -ExecutionPolicy Bypass -File scripts/dev/windows/test-all.ps1
+  powershell -ExecutionPolicy Bypass -File scripts/dev/windows/check-secrets.ps1
+}
+
 Run-Step "commit" {
   if ($Amend) {
     & git commit --amend --no-edit
@@ -82,4 +85,3 @@ Run-Step "remote verify" {
 }
 
 Write-Host "PASS: module pushed and verified."
-