feat: batch update - gift card breakdown spec, backend APIs, miniprogram pages, ETL finance recharge, docs & migrations

.kiro/steering/cli-env.md

@@ -0,0 +1,38 @@
+---
+inclusion: always
+---
+# CLI 环境规范（Windows PowerShell）
+
+本项目运行在 Windows + PowerShell 环境。以下是构造命令时必须掌握的前置知识。
+
+## PowerShell 语法要点
+- 环境变量：`$env:VAR_NAME`（不是 `$VAR_NAME`）
+- 命令连接符：`;`（不是 `&&`）
+- `where` 是 `Where-Object` 别名，查可执行文件用 `Get-Command <name>`
+- 删除文件/目录：`Remove-Item`（不是 `rm -rf`）
+- 路径分隔符 `\`，但 Python/Node 工具也接受 `/`
+
+## Python 调用
+- 项目虚拟环境：`uv run python` 或 `.venv\Scripts\python.exe`
+- 安装依赖：`uv sync`（不是 `pip install`）
+- 运行模块：`uv run python -m <module>`
+- 系统 Python：`python`（来自 miniconda3）
+
+## Shell 隔离与 REPL 防护（强制）
+
+> 背景：Kiro 的 `executePwsh` 复用同一个 shell session。若意外进入 Python REPL，后续所有命令被吞掉，表现为"无输出 + exit code 0"。
+
+### 核心原则
+- 禁止裸调 `python`/`node`/`ipython`——必须带 `-c`、`-m` 或脚本路径
+- 优先写脚本文件再执行，避免 `-c` 内联引号地狱
+- 禁止管道喂给 python（如 `echo "code" | python`）
+
+### 长时间命令
+- 预估 > 30s 的命令，提前告知用户
+- pytest hypothesis 建议设 `timeout` 为预估时间 3 倍
+- 超时后不要立即重试，先确认前一个进程状态
+
+### REPL 劫持
+症状：exit code 0 但无输出、连续命令无输出、出现 `>>>` 提示符。检测与自动恢复由 `repl-hijack-guard` hook 在命令执行后自动处理。
+
+> cwd 校验和命令语法检查由 `cwd-guard-shell` hook 在执行前自动拦截，此处不再重复。