@optima-chat/dev-skills 0.7.38 → 0.7.40

package/.claude/skills/grant-balance/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: "grant-balance"
-description: "当用户请求赠送余额、充值 USD 余额、grant balance、加余额、奖励、补偿、推荐奖励、运营发放时，使用此技能。支持 Stage、Prod 两个环境。"
+description: "当用户请求赠送余额、充值 USD 余额、grant balance、加余额、奖励、补偿、推荐奖励、运营发放时，使用此技能。支持 Stage、Prod、cn-prod 三个环境。"
 allowed-tools: ["Bash"]
 ---
 
 # 赠送 USD 余额（Grant Balance）
 
-当你需要为用户赠送 wallet USD 余额时，使用这个场景。金额会加到 `usd_wallets.granted_balance_micros`，billing 服务在扣费时会优先消费 granted balance。
+当你需要为用户赠送 wallet USD 余额时，使用这个场景。金额按 $1=700 积分换算，经 billing API 入 **bonus 积分桶（30 天有效期）**（P15 钱包退役后语义），billing 服务在扣费时会优先消费 granted balance。
 
 ## 执行方式：使用 CLI 工具
 
@@ -17,8 +17,8 @@ optima-grant-balance <email> --amount <usd> [options]
 **为什么使用 CLI 工具**：
 - 自动通过 email 查找 userId（跨 user-auth 数据库）
 - 自动处理 SSH 隧道和数据库连接
-- 不会影响现有订阅和已有余额（纯追加到 granted balance）
-- 自动写入 audit trail（`usd_wallet_topups` source=admin_grant）
+- 不会影响现有订阅和已有余额（发放 bonus 积分（30 天有效期，重复执行会叠加发放））
+- 自动留审计痕迹（credit_lot 行，幂等键前缀 `dev-skills-grant:`）
 
 ## 适用情况
 
@@ -41,7 +41,7 @@ optima-grant-balance user@example.com --amount 20 --description "服务中断补
 ```
 
 > **单位是美元（USD）**。`--amount 5` 即赠送 $5.00 到 granted balance。
-> 数据库底层用 micro-USD 精度（1 USD = 1,000,000 micros），CLI 自动换算。
+> 数据库底层用 micro-USD 精度（1 USD = 700 积分（P15 统一账本口径）
 
 ### 参数说明
 
@@ -50,7 +50,9 @@ optima-grant-balance user@example.com --amount 20 --description "服务中断补
 | `<email>` | 用户邮箱（必填） | - |
 | `--amount <usd>` | USD 金额（必填，> 0） | - |
 | `--description <text>` | 描述/原因（仅 console 输出） | - |
-| `--env <env>` | 环境：stage, prod | stage |
+| `--env <env>` | 环境：stage, prod, cn-prod | stage |
+
+> **cn-prod（国内环境）**：全程 HTTPS（auth-cn/billing-cn.optima.chat），email 查找走 user-auth internal lookup API（无 SSH 隧道）。金额输入仍是 USD（$1 = 700 积分，与 CN ¥1 = 100 积分同一账本单位）。例：`optima-grant-balance user@example.com --amount 1 --env cn-prod`
 
 ## 与 grant-subscription 的区别
 
@@ -93,10 +95,10 @@ optima-grant-balance xxx@gmail.com --amount 20 --env stage
 1. **Stage 优先**：默认操作 Stage 环境
 2. **Prod 谨慎**：操作 Prod 前确认邮箱和金额
 3. **纯追加**：不会影响现有余额和订阅（累加到 granted balance）
-4. **Audit trail**：每次赠送会插入一条 `usd_wallet_topups` 记录（source=`admin_grant`）
+4. **Audit trail**：每次赠送对应一个 credit_lot（幂等键前缀 `dev-skills-grant:`，type=bonus）
 
 ## 相关命令
 
 - `optima-grant-balance` - 赠送 USD 余额（主要方式）
 - `optima-grant-subscription` - 开通订阅计划
-- `optima-query-db` - 查询数据库验证结果（`SELECT granted_balance_micros FROM usd_wallets WHERE user_id=...`）
+- `optima-query-db` - 查询数据库验证结果（`GET /api/billing/balance（credits.byType.bonus）或 query-db credit_lot

package/.claude/skills/grant-subscription/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: "grant-subscription"
-description: "当用户请求开通会员、赠送订阅、grant subscription、开通 Pro/Starter/Enterprise、升级计划、给用户开会员时，使用此技能。支持 Stage、Prod 两个环境。"
+description: "当用户请求开通会员、赠送订阅、grant subscription、开通 Pro/Starter/Enterprise、升级计划、给用户开会员时，使用此技能。支持 Stage、Prod、cn-prod 三个环境。"
 allowed-tools: ["Bash"]
 ---
 
@@ -19,8 +19,8 @@ optima-grant-subscription <email> [options]
 **为什么使用 CLI 工具**：
 - 自动通过 email 查找 userId（跨 user-auth 数据库）
 - 自动处理 SSH 隧道和数据库连接
-- 自动取消旧订阅、重置 wallet granted balance
-- 自动按 plan 配置授予 USD wallet 余额和 token quota
+- 自动取消旧订阅、经 billing API supersede 旧授予（void 旧 subscription lot + 发新）
+- 自动按 plan 配置发放 subscription 积分（期末过期）和 token quota
 - 一条命令完成所有操作
 
 ## 适用情况
@@ -46,6 +46,10 @@ optima-grant-subscription user@example.com --plan starter --months 3
 
 # 开通 Enterprise，Prod 环境
 optima-grant-subscription user@example.com --plan enterprise --env prod
+
+# cn-prod（国内环境）：plan 用 -cn 档，默认 pro-cn
+optima-grant-subscription user@example.com --env cn-prod
+optima-grant-subscription user@example.com --plan starter-cn --env cn-prod
 ```
 
 ### 参数说明
@@ -55,7 +59,9 @@ optima-grant-subscription user@example.com --plan enterprise --env prod
 | `<email>` | 用户邮箱（必填） | - |
 | `--plan <id>` | 计划：trial, starter, pro, enterprise | pro |
 | `--months <n>` | 时长（月） | 1 |
-| `--env <env>` | 环境：stage, prod | stage |
+| `--env <env>` | 环境：stage, prod, cn-prod | stage |
+
+> **cn-prod（国内环境）**：plan 用 CNY 定价的 `-cn` 档（trial / starter-cn / pro-cn / enterprise-cn，默认 pro-cn）；裸 USD 档 id 会被客户端拒绝（防止给 CN 用户误赠 USD 档积分量）。email 查找走 user-auth internal lookup API（无 SSH 隧道）。
 
 ### 计划配置
 
@@ -66,7 +72,7 @@ optima-grant-subscription user@example.com --plan enterprise --env prod
 | pro | $20.00 | 2,000 | 8M | 40M |
 | enterprise | $100.00 | 10,000 | 16M | 80M |
 
-> 1 credit = $0.01 = 10,000 micros。授予额存入 `usd_wallets.granted_balance_micros`。
+> 积分经 billing API 发放（subscription 桶，期末过期；P15 后无 wallet）
 
 ## 常见使用场景
 
@@ -102,7 +108,7 @@ optima-grant-subscription user@example.com --plan starter --env prod
 2. 加载对应 plan 的配置（月授予额、token 限额等）
 3. 取消该用户的所有活跃订阅
 4. 创建新订阅（设置到期时间）
-5. 重置 wallet granted balance 并授予新额度
+5. 经 billing API supersede 旧授予（void 旧 subscription lot + 发新） 并授予新额度
 6. 记录 topup 审计记录（source: subscription_grant）
 7. 更新 token quota 限额
 

package/.codex/skills/grant-balance/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: "grant-balance"
-description: "Use when the user wants to grant USD wallet balance to an Optima user — for promotional grants, compensation, referral rewards, etc. Adds to granted_balance_micros without affecting subscriptions."
+description: "Use when the user wants to grant credits (bonus, 30-day expiry) to an Optima user — for promotional grants, compensation, referral rewards, etc. $1 = 700 credits via billing API; does not affect subscriptions."
 ---
 
 # 赠送 USD 余额（Grant Balance）
 
-当你需要为用户赠送 wallet USD 余额时，使用这个场景。金额会加到 `usd_wallets.granted_balance_micros`，billing 服务在扣费时会优先消费 granted balance。
+当你需要为用户赠送 wallet USD 余额时，使用这个场景。金额按 $1=700 积分换算，经 billing API 入 **bonus 积分桶（30 天有效期）**（P15 钱包退役后语义），billing 服务在扣费时会优先消费 granted balance。
 
 ## 执行方式：使用 CLI 工具
 
@@ -16,8 +16,8 @@ optima-grant-balance <email> --amount <usd> [options]
 **为什么使用 CLI 工具**：
 - 自动通过 email 查找 userId（跨 user-auth 数据库）
 - 自动处理 SSH 隧道和数据库连接
-- 不会影响现有订阅和已有余额（纯追加到 granted balance）
-- 自动写入 audit trail（`usd_wallet_topups` source=admin_grant）
+- 不会影响现有订阅和已有余额（发放 bonus 积分（30 天有效期，重复执行会叠加发放））
+- 自动留审计痕迹（credit_lot 行，幂等键前缀 `dev-skills-grant:`）
 
 ## 适用情况
 
@@ -40,7 +40,7 @@ optima-grant-balance user@example.com --amount 20 --description "服务中断补
 ```
 
 > **单位是美元（USD）**。`--amount 5` 即赠送 $5.00 到 granted balance。
-> 数据库底层用 micro-USD 精度（1 USD = 1,000,000 micros），CLI 自动换算。
+> 数据库底层用 micro-USD 精度（1 USD = 700 积分（P15 统一账本口径）
 
 ### 参数说明
 
@@ -49,7 +49,9 @@ optima-grant-balance user@example.com --amount 20 --description "服务中断补
 | `<email>` | 用户邮箱（必填） | - |
 | `--amount <usd>` | USD 金额（必填，> 0） | - |
 | `--description <text>` | 描述/原因（仅 console 输出） | - |
-| `--env <env>` | 环境：stage, prod | stage |
+| `--env <env>` | 环境：stage, prod, cn-prod | stage |
+
+> **cn-prod**：走 HTTPS（auth-cn/billing-cn.optima.chat），email 查找经 user-auth internal lookup API（无 SSH 隧道）。金额输入仍是 USD（$1 = 700 积分 = ¥7 档积分口径一致）。
 
 ## 与 grant-subscription 的区别
 
@@ -92,10 +94,10 @@ optima-grant-balance xxx@gmail.com --amount 20 --env stage
 1. **Stage 优先**：默认操作 Stage 环境
 2. **Prod 谨慎**：操作 Prod 前确认邮箱和金额
 3. **纯追加**：不会影响现有余额和订阅（累加到 granted balance）
-4. **Audit trail**：每次赠送会插入一条 `usd_wallet_topups` 记录（source=`admin_grant`）
+4. **Audit trail**：每次赠送对应一个 credit_lot（幂等键前缀 `dev-skills-grant:`，type=bonus）
 
 ## 相关命令
 
 - `optima-grant-balance` - 赠送 USD 余额（主要方式）
 - `optima-grant-subscription` - 开通订阅计划
-- `optima-query-db` - 查询数据库验证结果（`SELECT granted_balance_micros FROM usd_wallets WHERE user_id=...`）
+- `optima-query-db` - 查询数据库验证结果（`GET /api/billing/balance（credits.byType.bonus）或 query-db credit_lot

package/.codex/skills/grant-subscription/SKILL.md

@@ -21,9 +21,16 @@ optima-grant-subscription user@example.com --plan starter --months 3
 optima-grant-subscription user@example.com --plan enterprise --env prod
 ```
 
+```bash
+# cn-prod（国内环境）：plan 用 -cn 档，默认 pro-cn
+optima-grant-subscription user@example.com --env cn-prod
+optima-grant-subscription user@example.com --plan starter-cn --env cn-prod
+```
+
 ## Guidance
 
 - Default to `stage`.
-- Confirm the user email before running on `prod`.
+- Confirm the user email before running on `prod` / `cn-prod`.
+- `cn-prod` plans are the CNY-priced `-cn` ids (`starter-cn`, `pro-cn`, `enterprise-cn`, plus `trial`); bare USD ids are rejected client-side to avoid granting a USD-priced plan to a CN user.
 - This operation replaces existing subscription state and resets the wallet granted balance according to the selected plan.
 - Use `optima-query-db` afterward if the user asks for verification.

package/bin/helpers/billing-http.ts

@@ -5,8 +5,14 @@ import { getInfisicalConfig, getInfisicalToken } from './db-utils';
 const USER_AUTH_URLS: Record<string, string> = {
   stage: 'https://auth.stage.optima.onl',
   prod: 'https://auth.optima.onl',
+  'cn-prod': 'https://auth-cn.optima.chat',
 };
 
+// cn-prod URLs are hardcoded: cn Infisical (secrets-cn.optima.chat) is a
+// separate instance dev-skills has no machine identity for, and these domains
+// are stable. AWS envs keep reading /shared-secrets/domain-urls.
+const CN_PROD_BILLING_URL = 'https://billing-cn.optima.chat';
+
 /**
  * Validate the --env flag value at command entry, before any I/O.
  *
@@ -24,6 +30,20 @@ export function validateEnv(env: string): 'stage' | 'prod' {
   return env;
 }
 
+/**
+ * Variant for commands that also support cn-prod — currently grant-balance /
+ * grant-subscription, which reach billing + user-auth over HTTPS only.
+ * Other commands resolve users via the AWS RDS SSH tunnel, which does not
+ * exist for cn-prod (Aliyun VPC-internal RDS) — keep them on validateEnv so a
+ * cn-prod typo fails fast instead of dying inside the tunnel setup.
+ */
+export function validateEnvCnProd(env: string): 'stage' | 'prod' | 'cn-prod' {
+  if (env !== 'stage' && env !== 'prod' && env !== 'cn-prod') {
+    throw new Error(`--env must be "stage", "prod" or "cn-prod" (got: ${env})`);
+  }
+  return env;
+}
+
 // T1 discovered: client_id differs per env (stage=dev-skills-ubd3qz6n,
 // prod=dev-skills-hinxa0rs). Both stored in Infisical alongside the
 // secret at /shared-secrets/oauth-clients/.
@@ -31,6 +51,21 @@ const DEV_SKILLS_OAUTH_PATH = '/shared-secrets/oauth-clients';
 const DEV_SKILLS_CLIENT_ID_KEY = 'DEV_SKILLS_OAUTH_CLIENT_ID';
 const DEV_SKILLS_CLIENT_SECRET_KEY = 'DEV_SKILLS_OAUTH_CLIENT_SECRET';
 
+// cn-prod: the client (dev-skills-ecee51qo) lives in cn user-auth, but its
+// credentials are mirrored into AWS Infisical (prod environment, same path)
+// under CN_PROD-prefixed keys so we reuse the existing Infisical access —
+// zero new credential chain. Canonical copy lives in cn Infisical
+// /shared-secrets/oauth-clients (DEV_SKILLS_OAUTH_CLIENT_ID/SECRET).
+const DEV_SKILLS_CN_CLIENT_ID_KEY = 'DEV_SKILLS_CN_PROD_OAUTH_CLIENT_ID';
+const DEV_SKILLS_CN_CLIENT_SECRET_KEY = 'DEV_SKILLS_CN_PROD_OAUTH_CLIENT_SECRET';
+
+// cn-prod tokens must carry this scope: resolveUserIdByEmail calls cn
+// user-auth POST /api/v1/internal/users/lookup, whose guard
+// (verify_internal_service_token) requires it. user-auth issues
+// request∩allowed_scopes and an unscoped request yields scope="" (verified
+// against cn-prod 2026-06-12), so the request must name it explicitly.
+const CN_PROD_TOKEN_SCOPE = 'internal:users:write';
+
 // ───── Cache (process-lifetime) ─────────────────────────────────────────────
 // One CLI invocation does at most a handful of HTTP calls. We mint the M2M
 // token once and reuse it. Cross-invocation re-mint is fine — JWT TTL is
@@ -46,6 +81,7 @@ const billingUrlCache: Record<string, string> = {};
 const skillsUrlCache: Record<string, string> = {};
 
 function getBillingUrl(env: string): string {
+  if (env === 'cn-prod') return CN_PROD_BILLING_URL;
   if (billingUrlCache[env]) return billingUrlCache[env];
   const url = fetchInfisicalSecret(env, '/shared-secrets/domain-urls', 'BILLING_URL');
   billingUrlCache[env] = url;
@@ -65,13 +101,20 @@ export function getServiceToken(env: string): string {
   const cfg = getInfisicalConfig();
   const tok = getInfisicalToken(cfg);
   // Fetch BOTH client_id and client_secret from Infisical — they differ per env.
-  const clientId = fetchInfisicalSecret(env, DEV_SKILLS_OAUTH_PATH, DEV_SKILLS_CLIENT_ID_KEY, cfg, tok);
-  const clientSecret = fetchInfisicalSecret(env, DEV_SKILLS_OAUTH_PATH, DEV_SKILLS_CLIENT_SECRET_KEY, cfg, tok);
+  // cn-prod credentials are mirrored in the AWS Infisical *prod* environment
+  // (fetchInfisicalSecret has no cn-prod env slug), under CN-specific keys.
+  const isCn = env === 'cn-prod';
+  const infisicalEnv = isCn ? 'prod' : env;
+  const idKey = isCn ? DEV_SKILLS_CN_CLIENT_ID_KEY : DEV_SKILLS_CLIENT_ID_KEY;
+  const secretKey = isCn ? DEV_SKILLS_CN_CLIENT_SECRET_KEY : DEV_SKILLS_CLIENT_SECRET_KEY;
+  const clientId = fetchInfisicalSecret(infisicalEnv, DEV_SKILLS_OAUTH_PATH, idKey, cfg, tok);
+  const clientSecret = fetchInfisicalSecret(infisicalEnv, DEV_SKILLS_OAUTH_PATH, secretKey, cfg, tok);
 
   const authUrl = USER_AUTH_URLS[env];
   if (!authUrl) throw new Error(`Unknown env: ${env}`);
 
-  const body = `grant_type=client_credentials&client_id=${encodeURIComponent(clientId)}&client_secret=${encodeURIComponent(clientSecret)}`;
+  const scopeParam = isCn ? `&scope=${encodeURIComponent(CN_PROD_TOKEN_SCOPE)}` : '';
+  const body = `grant_type=client_credentials&client_id=${encodeURIComponent(clientId)}&client_secret=${encodeURIComponent(clientSecret)}${scopeParam}`;
   const response = execSync(
     `curl -s -X POST '${authUrl}/api/v1/oauth/token' -H 'Content-Type: application/x-www-form-urlencoded' -d '${body}'`,
     { encoding: 'utf-8' },
@@ -189,3 +232,40 @@ export async function callSkills<T = unknown>(
 ): Promise<ServiceResponse<T>> {
   return callService<T>(getSkillsUrl(env), env, method, path, body);
 }
+
+/**
+ * Resolve a user's id by email via user-auth's internal lookup endpoint
+ * (POST /api/v1/internal/users/lookup). cn-prod only: AWS envs resolve via
+ * the RDS SSH tunnel (db-utils resolveUserId) and their dev-skills clients
+ * don't carry the internal:users:write scope this endpoint requires.
+ */
+export async function resolveUserIdByEmail(env: string, email: string): Promise<string> {
+  console.log(`Looking up user by email: ${email}`);
+  const token = getServiceToken(env);
+  const authUrl = USER_AUTH_URLS[env];
+  if (!authUrl) throw new Error(`Unknown env: ${env}`);
+
+  const res = await fetch(`${authUrl}/api/v1/internal/users/lookup`, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify({ email }),
+  });
+  const text = await res.text();
+  if (res.status === 404) {
+    throw new Error(`User not found (${env}): ${email}`);
+  }
+  if (!res.ok) {
+    throw new Error(formatServiceError(res.status, res.statusText, text));
+  }
+  let parsed: { user_id?: string };
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new Error(`user-auth lookup returned non-JSON 2xx body: ${text.slice(0, 200)}`);
+  }
+  if (!parsed.user_id) {
+    throw new Error(`user-auth lookup response missing user_id: ${text.slice(0, 200)}`);
+  }
+  console.log(`✓ Found user: ${parsed.user_id}`);
+  return parsed.user_id;
+}