@optima-chat/dev-skills 0.7.36 → 0.7.38

package/.claude/commands/logs.md

@@ -50,6 +50,7 @@
   - `ci` - CI 持续集成环境（开发环境，默认）
   - `stage` - Stage 预发布环境（ECS Fargate）
   - `prod` - 生产环境（ECS Fargate）
+  - `cn-prod`（别名 `cn`）- 阿里云 cn-prod 环境（SAE，cn-beijing，经 buildbox 取日志）
 
 ## 示例
 
@@ -71,6 +72,7 @@
 - `ci` 或未指定 → 使用 SSH + Docker Compose（第 0 节，默认）
 - `stage` → 使用 AWS CloudWatch Logs - ECS（第 1 节）
 - `prod` → 使用 AWS CloudWatch Logs - ECS（第 2 节）
+- `cn-prod` / `cn` → 阿里云 SAE，经 buildbox 调 `DescribeInstanceLog`（第 3 节）
 
 ### 0. CI 环境（environment = "ci" 或默认）
 
@@ -209,6 +211,59 @@ aws logs get-log-events --log-group-name /ecs/commerce-backend-prod --log-stream
 
 **注意**: `optima-store` 仅在 Stage 环境部署
 
+### 3. cn-prod 环境（environment = "cn-prod" 或 "cn"）
+
+**部署方式**: 阿里云 **SAE**（Serverless App Engine，cn-beijing），不是 ECS/CloudWatch。
+**访问方式**: 经 buildbox（`root@47.94.105.163`，唯一装了 `aliyun-optima` profile + VPC 可达的机器）调 SAE OpenAPI。
+
+> ⚠️ SAE **未配 SLS**，stdout 日志只能用 `DescribeInstanceLog` 取实例**当前缓冲**（非历史检索；重启/滚动后旧日志丢）。要历史检索需给 SAE 配 SLS。
+
+**日志链**: service → AppId → GroupId → InstanceId → `DescribeInstanceLog`
+
+**关键坑**（实测）:
+- API 是 RPC-style `aliyun sae DescribeInstanceLog`，ROA 路径是 `/pop/v1/sam/**instance**/describeInstanceLog`（不是 `/sam/app/...`，写错报 "can not find api by path"）。
+- buildbox 密码在 1P `op://Optima/gdmixcizjci5bvuu3nuvgg4ooe/password`（标题带括号必须用 item ID）。
+
+**service → AppId 映射**（cn-prod，2026-06-01；新增/变动用 `aliyun sae ListApplications` 重查）:
+
+| service | AppId |
+|---|---|
+| `gateway-core` | `a08ce23f-3d3e-4d89-a2cf-53c8adba614e` |
+| `agentic-chat` | `6e290c73-a646-43ef-9da5-ad0b2e7eff73` |
+| `gw-admin` | `c6bc5a78-b27f-46e2-825a-eaa338c23645` |
+| `user-auth` | `d6fbf9de-fed6-4165-978f-7b3a0a456acc` |
+| `user-auth-admin` | `54093f99-37bf-4354-abd7-f6e76abdbcb6` |
+| `optima-scout` | `f5bb7e82-e57c-4bd4-83ae-2c25f8d38647` |
+| `optima-skills` | `55a63ee7-fb75-46e4-99f3-20854a699237` |
+| `infisical` | `52b33fc6-b26d-495a-8885-225d38b3d42f` |
+
+**完整脚本**（本地跑、经 buildbox 中转；改 `SERVICE`/`LINES`）:
+```bash
+SERVICE=gateway-core; LINES=80
+BBPW=$(op-win read "op://Optima/gdmixcizjci5bvuu3nuvgg4ooe/password")
+declare -A APPID=(
+  [gateway-core]=a08ce23f-3d3e-4d89-a2cf-53c8adba614e
+  [agentic-chat]=6e290c73-a646-43ef-9da5-ad0b2e7eff73
+  [gw-admin]=c6bc5a78-b27f-46e2-825a-eaa338c23645
+  [user-auth]=d6fbf9de-fed6-4165-978f-7b3a0a456acc
+  [user-auth-admin]=54093f99-37bf-4354-abd7-f6e76abdbcb6
+  [optima-scout]=f5bb7e82-e57c-4bd4-83ae-2c25f8d38647
+  [optima-skills]=55a63ee7-fb75-46e4-99f3-20854a699237
+  [infisical]=52b33fc6-b26d-495a-8885-225d38b3d42f )
+AID=${APPID[$SERVICE]}
+sshpass -p "$BBPW" ssh -o StrictHostKeyChecking=no root@47.94.105.163 "bash -s" <<REMOTE | tail -n $LINES
+P="--region cn-beijing --profile aliyun-optima"
+GID=\$(aliyun sae GET /pop/v1/sam/app/describeApplicationGroups --AppId $AID \$P 2>/dev/null | python3 -c "import sys,json;print(json.load(sys.stdin)['Data'][0]['GroupId'])")
+IID=\$(aliyun sae GET /pop/v1/sam/app/describeApplicationInstances --AppId $AID --GroupId \$GID \$P 2>/dev/null | python3 -c "import sys,json;d=json.load(sys.stdin)['Data'];print((d if isinstance(d,list) else d['Instances'])[0]['InstanceId'])")
+aliyun sae DescribeInstanceLog --InstanceId "\$IID" \$P 2>/dev/null | python3 -c "import sys,json;print(json.load(sys.stdin).get('Data',''))"
+REMOTE
+```
+
+**局限 / 提示**:
+- 只取第 1 个 InstanceId；多副本要遍历 `Data` 里全部 instance。
+- `agent-runtime` 不在 SAE（是 ECI 动态容器）——它的日志看 `gateway-core` 里 `eci-bridge` 的转发/错误行，或单独查对应 ECI。
+- 过滤：把上面输出 `| grep -iE 'error|eci|fail'` 即可（例：排 agentic-chat 链路 ECI 失败就 grep `gateway-core` 日志的 `eci-bridge`）。
+
 ## 完整示例脚本
 
 ### Stage 环境

package/.claude/skills/discount-codes/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: "discount-codes"
+description: "当用户请求创建优惠码、发优惠码、生成折扣码、promo code、discount code、批量生成优惠码、停用优惠码、查看优惠码时，使用此技能。支持 Stage、Prod 两个环境。"
+allowed-tools: ["Bash"]
+---
+
+# 优惠码管理
+
+为 billing 结账（技能包 / 会员）创建和管理百分比优惠码。
+
+## 执行方式：使用 CLI 工具
+
+无论用户用 `/discount-codes` 还是直接请求，都使用 `optima-discount` CLI（thin HTTP client，调 billing admin 端点）：
+
+```bash
+optima-discount <subcommand> [options]
+```
+
+## 子命令
+
+```bash
+# 建共享码：LAUNCH20 = 8 折，限 scout，6/30 截止，最多核销 100 次
+optima-discount create   --code LAUNCH20 --percent 20 --products scout --ends 2026-06-30 --max 100 --env prod
+
+# 批量唯一码（每码用一次）—— 码写入本地文件，不打屏
+optima-discount generate --count 100 --percent 50 --campaign partner-q3 --products scout --env prod
+#   → ./discount-codes-partner-q3-<ts>.txt
+
+# 查看（按 campaign / code 过滤）
+optima-discount list     --campaign partner-q3 --env prod
+
+# 停用
+optima-discount disable  --code LAUNCH20 --env prod
+```
+
+## 参数
+
+| 参数 | 说明 |
+|------|------|
+| `--code` | 优惠码（存为大写） |
+| `--percent` | 折扣百分比 1-100 |
+| `--products` | 逗号分隔的 productKey；省略 = 所有商品 |
+| `--starts` / `--ends` | 有效期（`YYYY-MM-DD` 或 ISO datetime） |
+| `--max` | 总核销上限（省略 = 不限；`1` = 一次性） |
+| `--campaign` | 分组标签（generate 时也是码前缀） |
+| `--count` | generate 生成数量 1-1000 |
+| `--limit` | list 返回上限（默认 500，最大 1000） |
+| `--env` | `stage` / `prod`（默认 `stage`） |
+| `--yes` | 跳过 prod 二次确认 |
+
+## 安全提醒
+
+1. **Stage 优先**：默认 `stage`。
+2. **Prod 谨慎**：`create` / `generate` / `disable` 在 prod 会要求输入 "yes" 确认（`--yes` 跳过）。
+3. **唯一码写文件**：`generate` 的码写入当前目录文件（`mode 0600`），不打屏——避免复制时被终端 padding 破坏。
+4. 依赖 billing 已部署对应环境（admin 端点存在）。越界值（如 `--percent 0`）由 billing 服务端校验返 400。
+
+## 相关
+
+- `optima-product` — 管理付费商品（优惠码作用于其结账）
+- `optima-query-db` — 查 `discount_codes` / `discount_redemptions` 表核对

package/.claude/skills/logs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: "logs"
-description: "当用户请求查看日志、查看服务日志、排查问题、看看日志、检查日志、商品服务日志、后端日志、API日志、正式环境日志、生产环境日志、CI环境日志、开发环境日志时，使用此技能。支持 CI、Stage、Prod 三个环境的 commerce-backend、user-auth、agentic-chat、bi-backend、session-gateway 等服务。"
+description: "当用户请求查看日志、查看服务日志、排查问题、看看日志、检查日志、商品服务日志、后端日志、API日志、正式环境日志、生产环境日志、CI环境日志、开发环境日志、阿里云日志、cn-prod 日志、SAE 日志时，使用此技能。支持 CI、Stage、Prod（AWS ECS/CloudWatch）以及 cn-prod（阿里云 SAE，经 buildbox）四个环境的 commerce-backend、user-auth、agentic-chat、gateway-core、optima-scout、optima-skills 等服务。"
 allowed-tools: ["Bash", "SlashCommand"]
 ---
 
@@ -175,6 +175,19 @@ INFO - Database query took 3200ms: SELECT * FROM products WHERE...
 - 通过 CloudWatch Logs 查看
 - 日志保留 7 天
 
+### cn-prod 环境（阿里云）
+
+```
+/logs gateway-core 100 cn-prod
+/logs agentic-chat 80 cn
+```
+
+**特点**：
+- 阿里云 **SAE**（cn-beijing），不是 AWS
+- 经 buildbox（`root@47.94.105.163`）调 SAE `DescribeInstanceLog`
+- SAE 未配 SLS → 只取实例**当前 stdout 缓冲**（非历史检索）
+- 技术细节 + service→AppId 映射见 `/logs --help`（第 3 节）
+
 ## 支持的服务列表
 
 | 服务 | 说明 | CI | Stage | Prod |

package/README.md

@@ -42,6 +42,7 @@ Optima Dev Skills 让 Claude Code 能够直接在 **CI、Stage、Prod** 三个
 - **generate-test-token** - 生成测试 Access Token 用于 API 测试
 - **use-commerce-cli** - 使用 Commerce CLI 管理电商店铺
 - **read-code** - 阅读 Optima-Chat 组织下任意仓库的代码
+- **discount-codes** - 创建/生成/查看/停用 billing 优惠码（Stage/Prod）
 
 ## 👤 用户故事
 
@@ -103,6 +104,7 @@ Claude:
 | `optima-query-db` | 数据库查询工具 | `optima-query-db user-auth "SELECT COUNT(*) FROM users" prod` |
 | `optima-show-env` | 查看服务环境变量 | `optima-show-env commerce-backend stage --filter DATABASE` |
 | `optima-generate-test-token` | 生成测试 token | `optima-generate-test-token --business-name "测试店铺"` |
+| `optima-discount` | 优惠码管理 | `optima-discount create --code LAUNCH20 --percent 20 --env stage` |
 
 **特点**：
 - ✅ 支持 CI、Stage、Prod 三个环境（query-db）

package/bin/cli.js

@@ -32,6 +32,7 @@ switch (command) {
     log('Available Commands:', 'yellow');
     log('  optima-query-db <service> "<sql>" [env]              Query database', 'cyan');
     log('  optima-show-env <service> [env]                      Show service env vars', 'cyan');
+    log('  optima-verify-health <service> [--env cn|prod|all]   Probe L1-L5 上线健康', 'cyan');
     log('  optima-generate-test-token [--env production]        Generate test token', 'cyan');
     log('  optima-grant-balance <email> --amount <usd> [--env]  Grant USD wallet balance', 'cyan');
     log('  optima-grant-subscription <email> --plan <p> [--env] Grant subscription', 'cyan');

package/bin/helpers/db-utils.ts

@@ -1,5 +1,6 @@
-import { execSync } from 'child_process';
+import { execSync, spawn } from 'child_process';
 import * as fs from 'fs';
+import * as os from 'os';
 
 // ─── Types ──────────────────────────────────────────────────────────────────
 export interface InfisicalConfig { url: string; clientId: string; clientSecret: string; projectId: string }
@@ -18,6 +19,11 @@ export const RDS_HOSTS: Record<string, string> = {
   prod:  'optima-prod-postgres.ctg866o0ehac.ap-southeast-1.rds.amazonaws.com',
 };
 
+// Shared bastion (optima-bi-data EC2, shared-services stack). Reached via SSM —
+// no public port 22 dependency, so it is immune to the MaxStartups throttling that
+// the open-to-world sshd suffers under internet scan load. SSH path kept as fallback.
+const AWS_REGION = 'ap-southeast-1';
+const BASTION_INSTANCE_ID = 'i-03286fb0a9ce7e6b1';
 const EC2_HOST = '3.0.210.113';
 
 // ─── SQL escaping ───────────────────────────────────────────────────────────
@@ -114,6 +120,75 @@ export function setupSSHTunnel(dbHost: string, localPort: number): void {
   );
 }
 
+/** Block the current (sync) call for `ms` without spawning a subprocess. */
+function sleepSync(ms: number): void {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function assertSSMPrereqs(): void {
+  for (const [bin, hint] of [
+    ['session-manager-plugin', 'https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html'],
+    ['aws', 'AWS CLI v2: https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html'],
+  ] as const) {
+    try { execSync(`command -v ${bin}`, { stdio: 'ignore' }); }
+    catch { throw new Error(`${bin} not found — required for the SSM DB tunnel. Install: ${hint}\n(or set OPTIMA_DB_TUNNEL=ssh to fall back to the legacy SSH tunnel)`); }
+  }
+}
+
+/**
+ * Open a local→RDS tunnel through the shared bastion using SSM port forwarding.
+ * No public SSH port is touched. A healthy existing tunnel on the port is reused
+ * (the ~2s SSM cold start is paid once, then every query is just a round-trip).
+ */
+export function setupSSMTunnel(dbHost: string, localPort: number): void {
+  let portInUse = false;
+  try { execSync(`lsof -ti:${localPort}`, { stdio: 'ignore' }); portInUse = true; } catch { /* free */ }
+
+  if (portInUse) {
+    if (isTunnelHealthy(localPort)) return;        // warm reuse — no cold start
+    console.log(`! Tunnel on port ${localPort} not responding (zombie), replacing...`);
+    killOrphanTunnel(localPort);
+  }
+
+  assertSSMPrereqs();
+  console.log(`Creating SSM tunnel: localhost:${localPort} -> ${BASTION_INSTANCE_ID} -> ${dbHost}:5432`);
+
+  const logFile = `${os.tmpdir()}/optima-ssm-tunnel-${localPort}.log`;
+  const out = fs.openSync(logFile, 'w');
+  const child = spawn('aws', [
+    'ssm', 'start-session',
+    '--region', AWS_REGION,
+    '--target', BASTION_INSTANCE_ID,
+    '--document-name', 'AWS-StartPortForwardingSessionToRemoteHost',
+    '--parameters', `host=${dbHost},portNumber=5432,localPortNumber=${localPort}`,
+  ], { detached: true, stdio: ['ignore', out, out] });
+  child.unref();
+
+  // Wait until the remote leg actually forwards (pg_isready probes RDS through the
+  // tunnel). Local port binds instantly; the remote hop needs ~1-2s to come up.
+  const deadlineMs = Date.now() + 20000;
+  while (Date.now() < deadlineMs) {
+    if (isTunnelHealthy(localPort)) { console.log(`✓ SSM tunnel ready on port ${localPort}`); return; }
+    sleepSync(500);
+  }
+
+  let tail = '(no log)';
+  try { tail = fs.readFileSync(logFile, 'utf-8').split('\n').slice(-8).join('\n'); } catch { /* ignore */ }
+  throw new Error(`SSM tunnel on port ${localPort} did not become ready within 20s.\n--- ${logFile} ---\n${tail}`);
+}
+
+/**
+ * Open a DB tunnel through the shared bastion. Defaults to SSM (no public port 22);
+ * set OPTIMA_DB_TUNNEL=ssh to fall back to the legacy SSH tunnel.
+ */
+export function setupTunnel(dbHost: string, localPort: number): void {
+  if ((process.env.OPTIMA_DB_TUNNEL || 'ssm').toLowerCase() === 'ssh') {
+    setupSSHTunnel(dbHost, localPort);
+  } else {
+    setupSSMTunnel(dbHost, localPort);
+  }
+}
+
 // ─── psql ───────────────────────────────────────────────────────────────────
 function findPsqlPath(): string {
   try {
@@ -142,8 +217,7 @@ export async function connectAuthDB(env: string, infisicalConfig: InfisicalConfi
   const host = RDS_HOSTS[env as 'stage' | 'prod'];
   const port = env === 'stage' ? 15432 : 15433;
 
-  setupSSHTunnel(host, port);
-  await new Promise(r => setTimeout(r, 1000));
+  setupTunnel(host, port);
 
   const conn: DBConnection = { host: 'localhost', port, user: secrets['AUTH_DB_USER'], password: secrets['AUTH_DB_PASSWORD'], database: 'optima_auth' };
   return { query: (sql: string) => queryDB(conn, sql) };
@@ -158,8 +232,7 @@ export async function connectBillingDB(env: string, infisicalConfig: InfisicalCo
 
   const parsed = parseDatabaseUrl(dbUrl);
   const port = env === 'stage' ? 15434 : 15435;
-  setupSSHTunnel(parsed.host, port);
-  await new Promise(r => setTimeout(r, 1000));
+  setupTunnel(parsed.host, port);
 
   const conn: DBConnection = { host: 'localhost', port, user: parsed.user, password: parsed.password, database: parsed.database };
   return { query: (sql: string) => queryDB(conn, sql) };

package/bin/helpers/discount/create.ts

@@ -0,0 +1,79 @@
+import { callBilling, validateEnv } from '../billing-http';
+import { confirmIfProd } from '../confirm-prompt';
+
+interface CreateArgs {
+  code: string;
+  percentOff: number;
+  productKeys?: string[];
+  startsAt?: string;
+  endsAt?: string;
+  maxRedemptions?: number;
+  campaign?: string;
+  env: string;
+  yes: boolean;
+}
+
+/** Normalize a date/datetime arg to a full ISO datetime string (billing requires z.iso.datetime). */
+function toIso(v: string): string {
+  const d = new Date(v);
+  if (isNaN(d.getTime())) throw new Error(`Invalid date: ${v} (use YYYY-MM-DD or ISO datetime)`);
+  return d.toISOString();
+}
+
+function parseArgs(argv: string[]): CreateArgs {
+  if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
+    console.log(`Usage: optima-discount create --code <CODE> --percent <1-100> [options]
+
+Required:
+  --code <CODE>            Promo code (stored uppercased)
+  --percent <1-100>        Percentage off
+
+Optional:
+  --products <a,b,...>     Limit to these productKeys (default: all)
+  --starts <date>          Valid-from (YYYY-MM-DD or ISO; default: immediately)
+  --ends <date>            Valid-until
+  --max <N>                Max total redemptions (default: unlimited; 1 = single-use)
+  --campaign <label>       Grouping label
+  --env stage|prod         (default: stage)
+  --yes                    Skip prod confirmation`);
+    process.exit(0);
+  }
+  const out: Partial<CreateArgs> = { env: 'stage', yes: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = argv[i + 1];
+    switch (a) {
+      case '--code': out.code = next; i++; break;
+      case '--percent': out.percentOff = parseInt(next, 10); i++; break;
+      case '--products': if (!next) throw new Error('--products requires a value'); out.productKeys = next.split(',').map((s) => s.trim()).filter(Boolean); i++; break;
+      case '--starts': out.startsAt = toIso(next); i++; break;
+      case '--ends': out.endsAt = toIso(next); i++; break;
+      case '--max': out.maxRedemptions = parseInt(next, 10); i++; break;
+      case '--campaign': out.campaign = next; i++; break;
+      case '--env': out.env = next; i++; break;
+      case '--yes': out.yes = true; break;
+      default: throw new Error(`Unknown arg: ${a}`);
+    }
+  }
+  if (!out.code) throw new Error('--code required');
+  if (out.percentOff === undefined || isNaN(out.percentOff)) throw new Error('--percent required (1-100)');
+  return out as CreateArgs;
+}
+
+export async function runCreate(argv: string[]): Promise<void> {
+  const args = parseArgs(argv);
+  validateEnv(args.env);
+  await confirmIfProd(args.env, `Create discount code ${args.code.toUpperCase()} (${args.percentOff}% off)`, args.yes);
+
+  const body: Record<string, unknown> = { code: args.code, percentOff: args.percentOff };
+  if (args.productKeys) body.productKeys = args.productKeys;
+  if (args.startsAt) body.startsAt = args.startsAt;
+  if (args.endsAt) body.endsAt = args.endsAt;
+  if (args.maxRedemptions !== undefined) body.maxRedemptions = args.maxRedemptions;
+  if (args.campaign) body.campaign = args.campaign;
+
+  console.log(`\n🎟️  Creating discount code on ${args.env.toUpperCase()}...`);
+  const res = await callBilling(args.env, 'POST', '/api/billing/admin/discount-codes', body);
+  console.log(`✓ Created (HTTP ${res.status}):`);
+  console.log(JSON.stringify(res.body, null, 2));
+}

package/bin/helpers/discount/disable.ts

@@ -0,0 +1,44 @@
+import { callBilling, validateEnv } from '../billing-http';
+import { confirmIfProd } from '../confirm-prompt';
+
+interface DisableArgs {
+  code: string;
+  env: string;
+  yes: boolean;
+}
+
+function parseArgs(argv: string[]): DisableArgs {
+  if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
+    console.log(`Usage: optima-discount disable --code <CODE> [options]
+
+Required:
+  --code <CODE>
+
+Optional:
+  --env stage|prod         (default: stage)
+  --yes                    Skip prod confirmation`);
+    process.exit(0);
+  }
+  const out: Partial<DisableArgs> = { env: 'stage', yes: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = argv[i + 1];
+    switch (a) {
+      case '--code': out.code = next; i++; break;
+      case '--env': out.env = next; i++; break;
+      case '--yes': out.yes = true; break;
+      default: throw new Error(`Unknown arg: ${a}`);
+    }
+  }
+  if (!out.code) throw new Error('--code required');
+  return out as DisableArgs;
+}
+
+export async function runDisable(argv: string[]): Promise<void> {
+  const args = parseArgs(argv);
+  validateEnv(args.env);
+  await confirmIfProd(args.env, `Disable discount code ${args.code.toUpperCase()}`, args.yes);
+  const res = await callBilling(args.env, 'PATCH', `/api/billing/admin/discount-codes/${encodeURIComponent(args.code)}`, { status: 'DISABLED' });
+  console.log(`✓ Disabled (HTTP ${res.status}):`);
+  console.log(JSON.stringify(res.body, null, 2));
+}

package/bin/helpers/discount/generate.ts

@@ -0,0 +1,84 @@
+import * as fs from 'fs';
+import { callBilling, validateEnv } from '../billing-http';
+import { confirmIfProd } from '../confirm-prompt';
+
+interface GenArgs {
+  count: number;
+  percentOff: number;
+  campaign: string;
+  productKeys?: string[];
+  startsAt?: string;
+  endsAt?: string;
+  env: string;
+  yes: boolean;
+}
+
+function toIso(v: string): string {
+  const d = new Date(v);
+  if (isNaN(d.getTime())) throw new Error(`Invalid date: ${v} (use YYYY-MM-DD or ISO datetime)`);
+  return d.toISOString();
+}
+
+function parseArgs(argv: string[]): GenArgs {
+  if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
+    console.log(`Usage: optima-discount generate --count <N> --percent <1-100> --campaign <label> [options]
+
+Generates N unique single-use codes (maxRedemptions=1). Codes are written to a
+local file (NOT printed) to keep them copy-paste clean.
+
+Required:
+  --count <N>              How many codes (1-1000)
+  --percent <1-100>        Percentage off
+  --campaign <label>       Grouping label (also the code prefix)
+
+Optional:
+  --products <a,b,...>     Limit to these productKeys
+  --starts <date>          Valid-from (YYYY-MM-DD or ISO)
+  --ends <date>            Valid-until
+  --env stage|prod         (default: stage)
+  --yes                    Skip prod confirmation`);
+    process.exit(0);
+  }
+  const out: Partial<GenArgs> = { env: 'stage', yes: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = argv[i + 1];
+    switch (a) {
+      case '--count': out.count = parseInt(next, 10); i++; break;
+      case '--percent': out.percentOff = parseInt(next, 10); i++; break;
+      case '--campaign': out.campaign = next; i++; break;
+      case '--products': if (!next) throw new Error('--products requires a value'); out.productKeys = next.split(',').map((s) => s.trim()).filter(Boolean); i++; break;
+      case '--starts': out.startsAt = toIso(next); i++; break;
+      case '--ends': out.endsAt = toIso(next); i++; break;
+      case '--env': out.env = next; i++; break;
+      case '--yes': out.yes = true; break;
+      default: throw new Error(`Unknown arg: ${a}`);
+    }
+  }
+  if (out.count === undefined || isNaN(out.count)) throw new Error('--count required (1-1000)');
+  if (out.percentOff === undefined || isNaN(out.percentOff)) throw new Error('--percent required (1-100)');
+  if (!out.campaign) throw new Error('--campaign required');
+  return out as GenArgs;
+}
+
+export async function runGenerate(argv: string[]): Promise<void> {
+  const args = parseArgs(argv);
+  validateEnv(args.env);
+  await confirmIfProd(args.env, `Generate ${args.count} unique discount codes (${args.percentOff}% off, campaign ${args.campaign})`, args.yes);
+
+  const body: Record<string, unknown> = { count: args.count, percentOff: args.percentOff, campaign: args.campaign };
+  if (args.productKeys) body.productKeys = args.productKeys;
+  if (args.startsAt) body.startsAt = args.startsAt;
+  if (args.endsAt) body.endsAt = args.endsAt;
+
+  console.log(`\n🎟️  Generating ${args.count} codes on ${args.env.toUpperCase()}...`);
+  const res = await callBilling<{ codes: string[] }>(args.env, 'POST', '/api/billing/admin/discount-codes/batch', body);
+  const codes = res.body.codes ?? [];
+
+  const safeCampaign = args.campaign.replace(/[^A-Za-z0-9_-]/g, '');
+  const file = `./discount-codes-${safeCampaign}-${Date.now()}.txt`;
+  // mode 0o600: single-use codes are sensitive-ish; written to the operator's CWD.
+  fs.writeFileSync(file, codes.join('\n') + '\n', { encoding: 'utf-8', mode: 0o600 });
+  console.log(`✓ Generated ${codes.length} codes (HTTP ${res.status}). Written to: ${file}`);
+  console.log(`  (codes are in the file, not printed, to keep them copy-paste clean)`);
+}

package/bin/helpers/discount/list.ts

@@ -0,0 +1,46 @@
+import { callBilling, validateEnv } from '../billing-http';
+
+interface ListArgs {
+  campaign?: string;
+  code?: string;
+  limit?: number;
+  env: string;
+}
+
+function parseArgs(argv: string[]): ListArgs {
+  if (argv[0] === '-h' || argv[0] === '--help') {
+    console.log(`Usage: optima-discount list [options]
+
+Optional:
+  --campaign <label>       Filter by campaign
+  --code <CODE>            Filter by exact code
+  --limit <N>              Max rows (default 500, max 1000)
+  --env stage|prod         (default: stage)`);
+    process.exit(0);
+  }
+  const out: Partial<ListArgs> = { env: 'stage' };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = argv[i + 1];
+    switch (a) {
+      case '--campaign': out.campaign = next; i++; break;
+      case '--code': out.code = next; i++; break;
+      case '--limit': { const n = parseInt(next, 10); if (isNaN(n)) throw new Error('--limit requires a number'); out.limit = n; i++; break; }
+      case '--env': out.env = next; i++; break;
+      default: throw new Error(`Unknown arg: ${a}`);
+    }
+  }
+  return out as ListArgs;
+}
+
+export async function runList(argv: string[]): Promise<void> {
+  const args = parseArgs(argv);
+  validateEnv(args.env);
+  const qs = new URLSearchParams();
+  if (args.campaign) qs.set('campaign', args.campaign);
+  if (args.code) qs.set('code', args.code);
+  if (args.limit !== undefined) qs.set('limit', String(args.limit));
+  const suffix = qs.toString() ? `?${qs.toString()}` : '';
+  const res = await callBilling(args.env, 'GET', `/api/billing/admin/discount-codes${suffix}`);
+  console.log(JSON.stringify(res.body, null, 2));
+}

package/bin/helpers/discount.ts

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+
+import { runCreate } from './discount/create';
+import { runGenerate } from './discount/generate';
+import { runList } from './discount/list';
+import { runDisable } from './discount/disable';
+
+function printHelp() {
+  console.log(`Usage: optima-discount <subcommand> [options]
+
+Subcommands:
+  create     Create one discount code (shared or single-use)
+  generate   Generate N unique single-use codes (written to a file)
+  list       List discount codes (filter by campaign/code)
+  disable    Disable a discount code
+
+Run 'optima-discount <subcommand> --help' for subcommand-specific options.`);
+}
+
+async function main() {
+  const [, , subcommand, ...rest] = process.argv;
+  if (!subcommand || subcommand === '-h' || subcommand === '--help') {
+    printHelp();
+    process.exit(0);
+  }
+  switch (subcommand) {
+    case 'create': await runCreate(rest); break;
+    case 'generate': await runGenerate(rest); break;
+    case 'list': await runList(rest); break;
+    case 'disable': await runDisable(rest); break;
+    default:
+      console.error(`Unknown subcommand: ${subcommand}`);
+      printHelp();
+      process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error(err.message);
+  process.exit(1);
+});

package/bin/helpers/query-db.ts

@@ -2,6 +2,7 @@
 
 import { execSync } from 'child_process';
 import * as fs from 'fs';
+import { setupTunnel } from './db-utils';
 
 interface InfisicalConfig {
   url: string;
@@ -96,9 +97,6 @@ const RDS_HOSTS = {
   prod: 'optima-prod-postgres.ctg866o0ehac.ap-southeast-1.rds.amazonaws.com'
 };
 
-// 统一使用 BI Data ARM Host 作为跳板机
-const EC2_HOST = '3.0.210.113';
-
 function parseDatabaseUrl(url: string): { user: string; password: string; host: string; port: number; database: string } {
   // postgresql://user:password@host:port/database?params
   const match = url.match(/^postgresql:\/\/([^:]+):([^@]+)@([^:]+):(\d+)\/([^?]+)/);
@@ -148,29 +146,6 @@ function getInfisicalSecrets(config: InfisicalConfig, token: string, environment
   return secrets;
 }
 
-function setupSSHTunnel(ec2Host: string, dbHost: string, localPort: number): void {
-  // 检查是否已有隧道
-  try {
-    execSync(`lsof -ti:${localPort}`, { stdio: 'ignore' });
-    console.log(`✓ SSH tunnel already exists on port ${localPort}`);
-    return;
-  } catch {
-    // 端口未占用，创建隧道
-  }
-
-  const sshKeyPath = `${process.env.HOME}/.ssh/optima-ec2-key`;
-  if (!fs.existsSync(sshKeyPath)) {
-    throw new Error(`SSH key not found: ${sshKeyPath}. Please obtain optima-ec2-key from xbfool.`);
-  }
-
-  console.log(`Creating SSH tunnel: localhost:${localPort} -> ${ec2Host} -> ${dbHost}:5432`);
-  execSync(
-    `ssh -i ${sshKeyPath} -f -N -o StrictHostKeyChecking=no -L ${localPort}:${dbHost}:5432 ec2-user@${ec2Host}`,
-    { stdio: 'inherit' }
-  );
-  console.log(`✓ SSH tunnel established on port ${localPort}`);
-}
-
 function findPsqlPath(): string {
   // 1. 优先从 PATH 中查找
   const whichCmd = process.platform === 'win32' ? 'where psql' : 'which psql';
@@ -323,10 +298,7 @@ async function main() {
 
     const localPort = environment === 'stage' ? 15432 : 15433;
 
-    setupSSHTunnel(EC2_HOST, dbHost, localPort);
-
-    // 等待隧道建立
-    await new Promise(resolve => setTimeout(resolve, 1000));
+    setupTunnel(dbHost, localPort);
 
     const result = queryDatabase('localhost', localPort, dbUser, dbPassword, database, sql);
     console.log('\n' + result);