@h-ai/cli 0.1.0-alpha5

package/templates/skills/hai-payment/SKILL.md

@@ -0,0 +1,289 @@
+---
+name: hai-payment
+description: 使用 @h-ai/payment 接入微信支付、支付宝、Stripe 统一支付；支持创建订单、回调验签、订单查询与退款；当需求涉及支付接入、订单创建、支付回调、退款或客户端调起支付时使用。
+---
+
+# hai-payment
+
+> `@h-ai/payment` 是 hai-framework 的统一支付模块，通过 Provider 模式支持微信支付、支付宝、Stripe。服务端处理订单和回调，客户端调起支付。
+
+---
+
+## 依赖
+
+| 模块 | 用途 | 是否必需 | 初始化要求 |
+| --- | --- | --- | --- |
+| `@h-ai/audit` | 审计日志（支付操作自动审计） | 可选 | 已初始化时自动写入审计日志 |
+
+---
+
+## 适用场景
+
+- 接入微信支付（JSAPI / H5 / Native / App）
+- 接入支付宝（H5 / App / PC）
+- 接入 Stripe（Checkout Session）
+- 支付回调验签与通知处理
+- 订单查询与退款
+- 客户端调起支付（Web / H5 / App）
+
+---
+
+## 使用步骤
+
+### 1. 配置
+
+```yaml
+# config/_payment.yml（自行创建）
+wechat:
+  appId: ${HAI_PAYMENT_WECHAT_APP_ID}
+  mchId: ${HAI_PAYMENT_WECHAT_MCH_ID}
+  apiV3Key: ${HAI_PAYMENT_WECHAT_API_V3_KEY}
+  privateKey: ${HAI_PAYMENT_WECHAT_PRIVATE_KEY}
+  serialNo: ${HAI_PAYMENT_WECHAT_SERIAL_NO}
+  platformCert: ${HAI_PAYMENT_WECHAT_PLATFORM_CERT}  # 可选，回调验签需要
+
+alipay:
+  appId: ${HAI_PAYMENT_ALIPAY_APP_ID}
+  privateKey: ${HAI_PAYMENT_ALIPAY_PRIVATE_KEY}
+  alipayPublicKey: ${HAI_PAYMENT_ALIPAY_PUBLIC_KEY}
+  signType: RSA2  # 可选，默认 RSA2
+  sandbox: false   # 可选，默认 false
+
+stripe:
+  secretKey: ${HAI_PAYMENT_STRIPE_SECRET_KEY}
+  webhookSecret: ${HAI_PAYMENT_STRIPE_WEBHOOK_SECRET}
+```
+
+### 2. 初始化（服务端）
+
+```typescript
+import { payment } from '@h-ai/payment'
+
+const initResult = await payment.init({
+  wechat: {
+    appId: 'wx1234567890',
+    mchId: '1600000000',
+    apiV3Key: 'your-api-key-v3',
+    privateKey: '-----BEGIN RSA PRIVATE KEY-----...',
+    serialNo: 'CERT_SERIAL_NO',
+  },
+  alipay: {
+    appId: '2021000000000000',
+    privateKey: '-----BEGIN RSA PRIVATE KEY-----...',
+    alipayPublicKey: '-----BEGIN PUBLIC KEY-----...',
+  },
+})
+if (!initResult.success) {
+  // 处理初始化错误
+}
+```
+
+### 3. 创建订单
+
+```typescript
+const result = await payment.createOrder('wechat', {
+  orderNo: 'ORDER_20250101_001',
+  amount: 9900, // 单位：分
+  description: '商品名称',
+  tradeType: 'jsapi',
+  userId: 'user_openid',
+  notifyUrl: 'https://example.com/payment/notify/wechat',
+  metadata: { source: 'web' },
+})
+
+if (result.success) {
+  // result.data: PaymentOrder { provider, tradeType, clientParams, prepayId? }
+  // clientParams 包含调起支付所需参数
+}
+```
+
+### 4. 处理支付回调
+
+```typescript
+// API 路由：POST /payment/notify/:provider
+const result = await payment.handleNotify('wechat', {
+  body: await request.text(),
+  headers: Object.fromEntries(request.headers),
+})
+
+if (result.success) {
+  // result.data: { orderNo, transactionId, amount, status, paidAt? }
+  // 更新订单状态...
+}
+```
+
+### 5. 查询订单
+
+```typescript
+const result = await payment.queryOrder('wechat', 'ORDER_20250101_001')
+
+if (result.success) {
+  // result.data.status: 'pending' | 'paid' | 'closed' | 'refunded' | 'failed'
+}
+```
+
+### 6. 退款
+
+```typescript
+const result = await payment.refund('wechat', {
+  orderNo: 'ORDER_20250101_001',
+  refundNo: 'REFUND_20250101_001',
+  amount: 9900,
+  totalAmount: 9900, // 微信退款必填
+  reason: '用户退款',
+})
+```
+
+### 7. 客户端调起支付（浏览器）
+
+```typescript
+import { invokePayment } from '@h-ai/payment/client'
+
+// 前端拿到服务端返回的 PaymentOrder 后调起支付
+const payResult = await invokePayment(orderResult.data)
+```
+
+---
+
+## 核心 API（服务端）
+
+| API                                              | 用途     | 返回值                        |
+| ------------------------------------------------ | -------- | ----------------------------- |
+| `payment.init(config)`                           | 初始化   | `HaiResult<void>`                |
+| `payment.close()`                                | 关闭     | `void`                        |
+| `payment.createOrder(providerName, input)`       | 创建订单 | `HaiResult<PaymentOrder>`        |
+| `payment.handleNotify(providerName, request)`    | 处理回调 | `HaiResult<PaymentNotifyResult>` |
+| `payment.queryOrder(providerName, orderNo)`      | 查询订单 | `HaiResult<OrderStatus>`         |
+| `payment.refund(providerName, input)`            | 退款     | `HaiResult<RefundResult>`        |
+| `payment.closeOrder(providerName, orderNo)`      | 关闭订单 | `HaiResult<void>`                |
+| `payment.getProvider(name)`                      | 获取 Provider | `PaymentProvider \| undefined` |
+| `payment.registerProvider(provider)`             | 注册自定义 Provider | `void`              |
+
+## 客户端 API
+
+| API                      | 用途     | 返回值                        |
+| ------------------------ | -------- | ----------------------------- |
+| `invokePayment(options)` | 调起支付 | `HaiResult<InvokePaymentResult>` |
+
+---
+
+## 错误码 — `HaiPaymentError`
+
+| 错误码 | code | 说明 |
+|--------|------|------|
+| `HaiPaymentError.CREATE_ORDER_FAILED` | `hai:payment:001` | 创建订单失败 |
+| `HaiPaymentError.QUERY_ORDER_FAILED` | `hai:payment:002` | 查询订单失败 |
+| `HaiPaymentError.REFUND_FAILED` | `hai:payment:003` | 退款失败 |
+| `HaiPaymentError.CLOSE_ORDER_FAILED` | `hai:payment:004` | 关闭订单失败 |
+| `HaiPaymentError.NOT_INITIALIZED` | `hai:payment:010` | 模块未初始化 |
+| `HaiPaymentError.SIGN_FAILED` | `hai:payment:020` | 签名失败 |
+| `HaiPaymentError.PROVIDER_NOT_FOUND` | `hai:payment:030` | Provider 未注册 |
+| `HaiPaymentError.INVALID_AMOUNT` | `hai:payment:040` | 金额无效 |
+| `HaiPaymentError.NOTIFY_VERIFY_FAILED` | `hai:payment:050` | 回调验签失败 |
+| `HaiPaymentError.NOTIFY_PARSE_FAILED` | `hai:payment:051` | 回调解析失败 |
+| `HaiPaymentError.INVOKE_WEB_FAILED` | `hai:payment:060` | Web 端调起支付失败 |
+| `HaiPaymentError.INVOKE_APP_FAILED` | `hai:payment:061` | App 端调起支付失败 |
+| `HaiPaymentError.CONFIG_ERROR` | `hai:payment:070` | 配置无效 |
+
+---
+
+## Provider 模式
+
+### PaymentProvider 接口
+
+```typescript
+interface PaymentProvider {
+  readonly name: string
+  createOrder: (input: CreateOrderInput) => Promise<HaiResult<PaymentOrder>>
+  handleNotify: (request: PaymentNotifyRequest) => Promise<HaiResult<PaymentNotifyResult>>
+  queryOrder: (outTradeNo: string) => Promise<HaiResult<OrderStatus>>
+  refund: (input: RefundInput) => Promise<HaiResult<RefundResult>>
+  closeOrder: (outTradeNo: string) => Promise<HaiResult<void>>
+}
+```
+
+内置 Provider：
+
+- **wechat** — 微信支付 API v3（RSA-SHA256 签名、AES-256-GCM 回调解密）
+- **alipay** — 支付宝开放平台（RSA2 签名验签）
+- **stripe** — Stripe Checkout Session 模式
+
+### API 契约
+
+```typescript
+import { paymentEndpoints } from '@h-ai/payment/api'
+
+// paymentEndpoints.createOrder    — POST /payment/create
+// paymentEndpoints.queryOrder     — GET  /payment/query
+// paymentEndpoints.notifyWechat   — POST /payment/notify/wechat
+// paymentEndpoints.notifyAlipay   — POST /payment/notify/alipay
+// paymentEndpoints.notifyStripe   — POST /payment/notify/stripe
+// paymentEndpoints.refund         — POST /payment/refund
+```
+
+---
+
+## 常见模式
+
+### 服务端路由（SvelteKit）
+
+```typescript
+import { kit } from '@h-ai/kit'
+// src/routes/api/v1/payment/create/+server.ts
+import { payment } from '@h-ai/payment'
+
+export const POST = kit.handler(async ({ request, locals }) => {
+  const body = await request.json()
+  const result = await payment.createOrder(body.provider, {
+    orderNo: body.orderNo,
+    amount: body.amount,
+    description: body.description,
+    tradeType: body.tradeType,
+    userId: body.userId,
+    notifyUrl: body.notifyUrl,
+  })
+
+  if (!result.success) {
+    return kit.response.internalError(result.error.message)
+  }
+
+  return kit.response.ok(result.data, locals.requestId)
+})
+```
+
+### 完整支付流程
+
+```
+1. 客户端 → 服务端：创建订单（api.call(paymentEndpoints.createOrder, {...})）
+2. 服务端 → 支付平台：调用 Provider 创建预支付
+3. 服务端 → 客户端：返回 providerData（含调起参数）
+4. 客户端：invokePayment(providerData) 调起支付
+5. 支付平台 → 服务端：异步回调通知
+6. 服务端：handleNotify() 验签 + 更新订单状态
+7. 客户端：轮询或回调查询订单状态
+```
+
+---
+
+## 审计日志
+
+关键支付操作成功后自动写入审计日志（依赖 `@h-ai/audit`），无需额外配置。失败仅 warn，不影响支付流程。
+
+| 操作 | `action` | `resource` | `resourceId` | `details` |
+| --- | --- | --- | --- | --- |
+| 创建订单 | `create_order` | `payment` | `orderNo` | `{ provider, amount, tradeType }` |
+| 支付回调 | `payment_notify` | `payment` | `orderNo` | `{ provider, transactionId, status, amount }` |
+| 退款 | `refund` | `payment` | `orderNo` | `{ provider, refundNo, amount }` |
+| 关闭订单 | `close_order` | `payment` | `orderNo` | `{ provider }` |
+
+> `queryOrder` 为只读操作，不写审计日志。
+
+---
+
+## 相关 Skills
+
+- `hai-kit`：服务端 API 路由与契约处理
+- `hai-api-client`：客户端契约调用
+- `hai-reldb`：订单持久化存储
+- `hai-audit`：审计日志（payment 内部自动调用）
+- `hai-core`：HaiResult 类型、日志、配置

package/templates/skills/hai-reach/SKILL.md

@@ -0,0 +1,325 @@
+---
+name: hai-reach
+description: 使用 @h-ai/reach 进行邮件、短信和 API 回调发送；当需求涉及用户触达、消息通知、验证码发送、多渠道模板管理时使用。
+---
+
+# hai-reach
+
+> `@h-ai/reach` 提供统一的用户触达接口，支持同时注册多个 Provider（SMTP 邮件、短信、API 回调），内置模板引擎与免打扰（DND）机制。
+
+---
+
+## 依赖
+
+| 模块 | 用途 | 是否必需 | 初始化要求 |
+| --- | --- | --- | --- |
+| `@h-ai/reldb` | 数据库（发送日志与模板持久化） | 可选 | 已初始化时自动启用持久化 |
+| `@h-ai/cache` | 缓存（DND delay 策略分布式锁） | 可选 | 已初始化时自动启用分布式锁 |
+
+---
+
+## 适用场景
+
+- 同时使用邮件、短信、API 回调发送通知
+- 发送邮件通知（注册欢迎、密码重置、告警等）
+- 发送短信验证码或通知
+- 通过 HTTP API 回调触发第三方通知
+- 定义和管理消息模板（模板绑定到具体 Provider，支持配置文件定义）
+- 免打扰时段控制
+- 基于 `HaiReachError` 做错误分支处理
+
+---
+
+## 使用步骤
+
+### 1. 配置
+
+```yaml
+# config/_reach.yml
+providers:
+  - name: email
+    type: smtp
+    host: ${HAI_REACH_SMTP_HOST:smtp.example.com}
+    port: ${HAI_REACH_SMTP_PORT:465}
+    secure: true
+    user: ${HAI_REACH_SMTP_USER:}
+    pass: ${HAI_REACH_SMTP_PASS:}
+    from: ${HAI_REACH_SMTP_FROM:noreply@example.com}
+  - name: sms
+    type: aliyun-sms
+    accessKeyId: ${HAI_REACH_SMS_ACCESS_KEY:}
+    accessKeySecret: ${HAI_REACH_SMS_SECRET_KEY:}
+    signName: ${HAI_REACH_SMS_SIGN_NAME:}
+  - name: webhook
+    type: api
+    url: ${HAI_REACH_WEBHOOK_URL:}
+
+# 模板（可选，也可通过代码注册）
+templates:
+  - name: verification_code
+    provider: email
+    subject: '验证码: {code}'
+    body: '您的验证码是 {code}，有效期 {minutes} 分钟。'
+  - name: sms_code
+    provider: sms
+    body: '验证码: {code}，{minutes} 分钟内有效。'
+
+# 免打扰（可选）
+dnd:
+  enabled: true
+  strategy: delay # discard（丢弃）或 delay（延时，DND 结束后集中发送）
+  start: '22:00'
+  end: '08:00'
+```
+
+### 2. 初始化与关闭
+
+```typescript
+import { cache } from '@h-ai/cache'
+import { core } from '@h-ai/core'
+import { reach } from '@h-ai/reach'
+import { reldb } from '@h-ai/reldb'
+
+// 先初始化可选依赖（按需）
+await reldb.init(core.config.get('db')) // 可选，启用发送日志与模板持久化
+await cache.init(core.config.get('cache')) // 可选，启用 DND delay 策略分布式锁
+
+// 再初始化触达模块（自动检测已初始化的 reldb/cache 单例）
+await reach.init(core.config.get('reach'))
+// ... 使用触达服务
+await reach.close()
+```
+
+### 3. 保存模板（模板绑定 Provider）
+
+```typescript
+// 通过代码保存（配置文件中的模板在 init 时自动注册）
+await reach.template.save({
+  name: 'verification_code',
+  provider: 'email',
+  subject: '验证码: {code}',
+  body: '您的验证码是 {code}，有效期 {minutes} 分钟。',
+})
+
+await reach.template.saveBatch([
+  { name: 'welcome', provider: 'email', subject: '欢迎 {userName}', body: '亲爱的 {userName}，欢迎使用 {appName}！' },
+  { name: 'sms_code', provider: 'sms', body: '验证码: {code}，{minutes} 分钟内有效。' },
+])
+```
+
+### 4. 发送消息
+
+```typescript
+// 使用模板发送邮件（指定 provider）
+const result = await reach.send({
+  provider: 'email',
+  to: 'user@example.com',
+  template: 'verification_code',
+  vars: { code: '123456', minutes: '5' },
+})
+
+// 直接发送邮件（无模板）
+await reach.send({
+  provider: 'email',
+  to: 'user@example.com',
+  subject: '通知',
+  body: '<h1>Hello</h1>',
+})
+
+// 发送短信（通过 extra 传递 Provider 特有参数）
+await reach.send({
+  provider: 'sms',
+  to: '13800138000',
+  extra: { templateCode: 'SMS_123456' },
+  vars: { code: '654321' },
+})
+
+// API 回调
+await reach.send({
+  provider: 'webhook',
+  to: 'user@example.com',
+  body: '{"event":"signup"}',
+})
+```
+
+---
+
+## 核心 API
+
+### reach 对象
+
+| 方法 / 属性           | 签名                                                     | 说明                               |
+| --------------------- | -------------------------------------------------------- | ---------------------------------- |
+| `reach.init`          | `(config: ReachConfigInput) => Promise<HaiResult<void>>`    | 初始化（注册多个 Provider）        |
+| `reach.send`          | `(message: ReachMessage) => Promise<HaiResult<SendResult>>` | 发送消息（通过 provider 字段路由） |
+| `reach.template`      | `ReachTemplateRegistry`                                  | 模板注册表                         |
+| `reach.config`        | `ReachConfig \| null`                                    | 当前配置                           |
+| `reach.isInitialized` | `boolean`                                                | 是否已初始化                       |
+| `reach.close`         | `() => Promise<void>`                                    | 关闭所有连接                       |
+
+### ReachConfigInput
+
+```typescript
+interface ReachConfigInput {
+  providers: ProviderConfig[] // 多个 Provider 配置
+  templates?: TemplateConfig[] // 通过配置文件定义的模板
+  dnd?: {
+    enabled: boolean // 是否启用
+    strategy: 'discard' | 'delay' // discard 丢弃 / delay 延时发送
+    start: string // 开始时间 HH:mm
+    end: string // 结束时间 HH:mm
+  }
+}
+```
+
+### ReachMessage
+
+| 字段       | 类型                      | 必填 | 说明                                |
+| ---------- | ------------------------- | ---- | ----------------------------------- |
+| `provider` | `string`                  | ✅   | 目标 Provider 名称                  |
+| `to`       | `string`                  | ✅   | 接收方（邮箱或手机号）              |
+| `subject`  | `string`                  | —    | 邮件主题（直接发送时）              |
+| `body`     | `string`                  | —    | 消息正文（直接发送时）              |
+| `template` | `string`                  | —    | 模板名称（模板发送时）              |
+| `vars`     | `Record<string, string>`  | —    | 模板变量                            |
+| `extra`    | `Record<string, unknown>` | —    | Provider 扩展参数（如短信模板编码） |
+
+### ReachTemplate（模板绑定 Provider）
+
+| 字段       | 类型     | 必填 | 说明                 |
+| ---------- | -------- | ---- | -------------------- |
+| `name`     | `string` | ✅   | 模板名称             |
+| `provider` | `string` | ✅   | 绑定的 Provider 名称 |
+| `subject`  | `string` | —    | 邮件主题模板         |
+| `body`     | `string` | ✅   | 正文模板             |
+
+---
+
+## 错误码
+
+| 错误码 | code | 说明 |
+|--------|------|------|
+| `HaiReachError.SEND_FAILED`            | `hai:reach:001`   | 发送失败        |
+| `HaiReachError.TEMPLATE_NOT_FOUND`     | `hai:reach:002`   | 模板未找到      |
+| `HaiReachError.TEMPLATE_RENDER_FAILED` | `hai:reach:003`   | 模板渲染失败    |
+| `HaiReachError.INVALID_RECIPIENT`      | `hai:reach:004`   | 无效接收方      |
+| `HaiReachError.PROVIDER_NOT_FOUND`     | `hai:reach:005`   | Provider 未找到 |
+| `HaiReachError.DND_BLOCKED`            | `hai:reach:006`   | 免打扰丢弃      |
+| `HaiReachError.DND_DEFERRED`           | `hai:reach:007`   | 免打扰延时暂存  |
+| `HaiReachError.NOT_INITIALIZED`        | `hai:reach:010`   | 模块未初始化    |
+| `HaiReachError.UNSUPPORTED_TYPE`       | `hai:reach:011`   | 不支持的类型    |
+| `HaiReachError.CONFIG_ERROR`           | `hai:reach:012`   | 配置错误        |
+
+---
+
+## 常见模式
+
+### 多渠道验证码发送
+
+```typescript
+reach.template.save({
+  name: 'email_code',
+  provider: 'email',
+  subject: '验证码: {code}',
+  body: '您的验证码是 {code}，有效期 {minutes} 分钟。',
+})
+
+reach.template.save({
+  name: 'sms_code',
+  provider: 'sms',
+  body: '验证码: {code}，{minutes} 分钟内有效。',
+})
+
+// 根据用户选择的渠道发送
+async function sendCode(channel: 'email' | 'sms', target: string, code: string) {
+  const template = channel === 'email' ? 'email_code' : 'sms_code'
+  return reach.send({
+    provider: channel,
+    to: target,
+    template,
+    vars: { code, minutes: '5' },
+  })
+}
+```
+
+### 与 IAM 集成（密码重置 / OTP 验证码）
+
+```typescript
+import { iam } from '@h-ai/iam'
+import { reach } from '@h-ai/reach'
+
+// 初始化 reach（注册 email 和 sms Provider）
+await reach.init({
+  providers: [
+    { name: 'email', type: 'smtp', host: 'smtp.example.com', from: 'noreply@example.com' },
+    { name: 'sms', type: 'aliyun-sms', accessKeyId: '...', accessKeySecret: '...', signName: '...' },
+  ],
+  templates: [
+    { name: 'password_reset', provider: 'email', subject: 'Password Reset', body: 'Token: {token}, expires: {expiresAt}' },
+    { name: 'otp_email', provider: 'email', subject: 'Code: {code}', body: 'Your code is {code}' },
+    { name: 'otp_sms', provider: 'sms', body: 'Your code is {code}' },
+  ],
+})
+
+// 初始化 IAM，使用 reach 发送通知
+await iam.init({
+  db,
+  cache,
+  onPasswordResetRequest: async (user, token, expiresAt) => {
+    await reach.send({ provider: 'email', to: user.email ?? '', template: 'password_reset', vars: { token, expiresAt: expiresAt.toISOString() } })
+  },
+  onOtpSendEmail: async (email, code) => {
+    await reach.send({ provider: 'email', to: email, template: 'otp_email', vars: { code } })
+  },
+  onOtpSendSms: async (phone, code) => {
+    await reach.send({ provider: 'sms', to: phone, template: 'otp_sms', vars: { code } })
+  },
+})
+```
+
+### 错误处理
+
+```typescript
+import { HaiReachError } from '@h-ai/reach'
+
+const result = await reach.send(message)
+if (!result.success) {
+  switch (result.error.code) {
+    case HaiReachError.NOT_INITIALIZED.code:
+      break
+    case HaiReachError.PROVIDER_NOT_FOUND.code:
+      break
+    case HaiReachError.DND_BLOCKED.code:
+      // 免打扰时段（discard 策略），消息已丢弃
+      break
+    case HaiReachError.TEMPLATE_NOT_FOUND.code:
+      break
+    case HaiReachError.SEND_FAILED.code:
+      break
+  }
+}
+```
+
+### 分布式锁（DND flush 保护）
+
+> 多节点部署时，DND（delay 策略）的 pending 消息 flush 通过 `@h-ai/cache` 分布式锁保护，确保同一时刻只有一个节点执行 flush。
+
+```typescript
+import { cache } from '@h-ai/cache'
+
+// 初始化 cache 后，reach 自动使用分布式锁保护 flush 操作
+await cache.init({ type: 'redis', host: 'localhost', port: 6379 })
+await reach.init({ /* ... */ })
+```
+
+- 锁键：`reach:flush-pending`，TTL 60 秒
+- 若 cache 未初始化，分布式锁自动禁用，不影响单节点运行
+- 使用稳定的进程级 owner 标识，防止误释放他人锁
+
+---
+
+## 相关 Skills
+
+- `hai-core` — 配置加载、日志、HaiResult 模式
+- `hai-reldb` — 数据库操作（存储发送记录等）
+- `hai-cache` — 缓存操作、分布式锁（DND flush 互斥）