@allbluecn/web-app 0.11.0 → 0.11.2

package/src/routes/api/cron/subscription-reminders.ts

@@ -0,0 +1,110 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+import { createFileRoute } from '@tanstack/react-router'
+import { prisma } from '@allbluecn/database'
+import { sendTemplateEmail } from '@/server/email'
+
+const DAY_MS = 24 * 60 * 60 * 1000
+
+const WINDOWS = [
+  { days: 7, offsetMs: 7 * DAY_MS },
+  { days: 3, offsetMs: 3 * DAY_MS },
+  { days: 1, offsetMs: 1 * DAY_MS },
+] as const
+
+function startOfDay(d: Date): Date {
+  return new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()))
+}
+
+function dateOnly(d: Date): string {
+  return d.toISOString().slice(0, 10)
+}
+
+async function isAuthorized(request: Request): Promise<boolean> {
+  const secret = process.env.CRON_SECRET
+  if (!secret) {
+    return process.env.NODE_ENV !== 'production'
+  }
+  return (request.headers.get('authorization') ?? '') === `Bearer ${secret}`
+}
+
+export const Route = createFileRoute('/api/cron/subscription-reminders')({
+  server: {
+    handlers: {
+      GET: async ({ request }) => {
+        if (!(await isAuthorized(request))) {
+          return Response.json({ error: 'Forbidden' }, { status: 403 })
+        }
+
+        const todayStart = startOfDay(new Date())
+        const wideUntil = new Date(todayStart.getTime() + WINDOWS[0].offsetMs)
+
+        const subs = await prisma.subscription.findMany({
+          where: {
+            OR: [
+              {
+                status: 'ACTIVE',
+                cancelAtPeriodEnd: true,
+                currentPeriodEnd: { gte: todayStart, lte: wideUntil },
+              },
+              {
+                status: 'TRIALING',
+                trialEndsAt: { gte: todayStart, lte: wideUntil },
+              },
+            ],
+          },
+          include: {
+            user: { select: { email: true, locale: true } },
+            plan: { select: { displayName: true } },
+          },
+        })
+
+        const appUrl = process.env.VITE_APP_URL ?? 'http://localhost:3000'
+        let processed = 0
+
+        for (const sub of subs) {
+          if (!sub.user?.email || !sub.plan) continue
+          const endDate = sub.status === 'TRIALING' ? sub.trialEndsAt : sub.currentPeriodEnd
+          if (!endDate) continue
+          const endDateStr = dateOnly(endDate)
+
+          for (const w of WINDOWS) {
+            const until = new Date(todayStart.getTime() + w.offsetMs)
+            if (endDate < todayStart || endDate > until) continue
+            const dedupeKey = `sub-reminder:${sub.id}:${endDateStr}:${w.days}`
+            const res = await sendTemplateEmail({
+              key: 'billing.subscription-ending',
+              to: sub.user.email,
+              locale: sub.user.locale ?? 'zh',
+              userId: sub.userId,
+              dedupeKey,
+              vars: {
+                planName: sub.plan.displayName,
+                endDate: endDateStr,
+                dashboardUrl: `${appUrl}/settings/billing`,
+              },
+            })
+            if (res.sent) processed++
+          }
+        }
+
+        return Response.json({ processed })
+      },
+    },
+  },
+})

package/src/routes/api.auth.$.ts

@@ -16,16 +16,14 @@
 // along with this program. If not, see <https://www.gnu.org/licenses/>.
 
 import { createFileRoute } from '@tanstack/react-router'
-import { authConfig } from '@/lib/auth/auth.config'
+import { getAuthConfig } from '@/lib/auth/auth.config'
 import { StartAuthJS } from 'start-authjs'
 
-const authHandlers = StartAuthJS(authConfig)
-
 export const Route = createFileRoute('/api/auth/$')({
   server: {
     handlers: {
-      GET: ({ request }) => authHandlers.GET({ request }),
-      POST: ({ request }) => authHandlers.POST({ request }),
+      GET: async ({ request }) => (await StartAuthJS(await getAuthConfig())).GET({ request }),
+      POST: async ({ request }) => (await StartAuthJS(await getAuthConfig())).POST({ request }),
     },
   },
 })

package/src/server/__tests__/auth-registration.test.ts

@@ -0,0 +1,60 @@
+import { describe, it, expect, vi } from 'vitest'
+import { consumeInvitationCode, type ConsumeResult } from '../auth-registration'
+import type { Prisma } from '@allbluecn/database'
+
+type TxMock = {
+  invitationCode: {
+    findUnique: ReturnType<typeof vi.fn>
+    updateMany: ReturnType<typeof vi.fn>
+  }
+}
+
+function makeTx(overrides: Record<string, unknown> = {}): { tx: Prisma.TransactionClient; mock: TxMock } {
+  const mock: TxMock = {
+    invitationCode: {
+      findUnique: vi.fn().mockResolvedValue({ id: 'code_1', maxUses: 2 }),
+      updateMany: vi.fn().mockResolvedValue({ count: 1 }),
+      ...overrides,
+    },
+  }
+  return { tx: mock as unknown as Prisma.TransactionClient, mock }
+}
+
+describe('consumeInvitationCode', () => {
+  it('有效邀请码：占一位并返回 codeId', async () => {
+    const { tx, mock } = makeTx()
+    const r: ConsumeResult = await consumeInvitationCode(tx, 'ABC')
+    expect(r).toEqual({ ok: true, codeId: 'code_1' })
+    expect(mock.invitationCode.updateMany).toHaveBeenCalledWith({
+      where: expect.objectContaining({
+        id: 'code_1',
+        usedCount: { lt: 2 },
+        disabledAt: null,
+        expiresAt: { gt: expect.any(Date) },
+      }),
+      data: { usedCount: { increment: 1 } },
+    })
+  })
+
+  it('邀请码不存在：返回「邀请码无效」', async () => {
+    const { tx, mock } = makeTx({ findUnique: vi.fn().mockResolvedValue(null) })
+    const r = await consumeInvitationCode(tx, 'NOPE')
+    expect(r).toEqual({ ok: false, error: '邀请码无效' })
+    expect(mock.invitationCode.updateMany).not.toHaveBeenCalled()
+  })
+
+  it('配额耗尽/过期/禁用：updateMany count=0 → 返回用尽错误', async () => {
+    const { tx } = makeTx({ updateMany: vi.fn().mockResolvedValue({ count: 0 }) })
+    const r = await consumeInvitationCode(tx, 'FULL')
+    expect(r).toEqual({ ok: false, error: '邀请码已用尽、过期或被禁用' })
+  })
+
+  it('邀请码大小写与首尾空格归一化后匹配', async () => {
+    const { tx, mock } = makeTx()
+    await consumeInvitationCode(tx, '  abc ')
+    expect(mock.invitationCode.findUnique).toHaveBeenCalledWith({
+      where: { code: 'ABC' },
+      select: { id: true, maxUses: true },
+    })
+  })
+})

package/src/server/auth-registration.ts

@@ -0,0 +1,40 @@
+import { prisma } from '@allbluecn/database'
+import type { Prisma } from '@allbluecn/database'
+
+export type RegistrationMode = 'invite' | 'open'
+
+export async function getRegistrationMode(): Promise<RegistrationMode> {
+  const setting = await prisma.systemSetting.findUnique({ where: { key: 'auth.registrationMode' } })
+  return setting?.value === 'open' ? 'open' : 'invite'
+}
+
+export type ConsumeResult = { ok: true; codeId: string } | { ok: false; error: string }
+
+/**
+ * 事务内占用邀请码配额（不写 InvitationUse——调用时用户尚未创建，拿不到 userId）。
+ * 成功即配额已扣；调用方事务回滚则配额占用一并回滚，无泄露。
+ */
+export async function consumeInvitationCode(
+  tx: Prisma.TransactionClient,
+  code: string,
+): Promise<ConsumeResult> {
+  const normalized = code.trim().toUpperCase()
+  const row = await tx.invitationCode.findUnique({
+    where: { code: normalized },
+    select: { id: true, maxUses: true },
+  })
+  if (!row) return { ok: false, error: '邀请码无效' }
+  const affected = await tx.invitationCode.updateMany({
+    where: {
+      id: row.id,
+      usedCount: { lt: row.maxUses },
+      disabledAt: null,
+      expiresAt: { gt: new Date() },
+    },
+    data: { usedCount: { increment: 1 } },
+  })
+  if (affected.count === 0) {
+    return { ok: false, error: '邀请码已用尽、过期或被禁用' }
+  }
+  return { ok: true, codeId: row.id }
+}

package/src/server/billing-email.ts

@@ -0,0 +1,39 @@
+import { prisma } from '@allbluecn/database'
+import { sendTemplateEmail } from '@/server/email'
+
+interface CreemEvent {
+  eventType?: string
+  /** Creem webhook payload：subscription 对象挂在 `object` 上，订阅 id 用 `object.id`。 */
+  object?: { id?: string; subscriptionId?: string; metadata?: Record<string, string> }
+}
+
+export async function sendBillingEmailForEvent(rawBody: string): Promise<void> {
+  try {
+    const evt = JSON.parse(rawBody) as CreemEvent
+    // 官方路径 `object.id`；保留 `object.subscriptionId` fallback 兜底旧版/非标准 payload。
+    const subId = evt.object?.id ?? evt.object?.subscriptionId
+    const type = evt.eventType
+    if (!subId || (type !== 'subscription.paid' && type !== 'subscription.canceled')) return
+    const sub = await prisma.subscription.findUnique({
+      where: { providerSubscriptionId: subId },
+      select: { userId: true, currentPeriodEnd: true, plan: { select: { displayName: true } } },
+    })
+    if (!sub) return
+    const user = await prisma.user.findUnique({
+      where: { id: sub.userId },
+      select: { email: true, locale: true },
+    })
+    if (!user?.email) return
+    const appUrl = process.env.VITE_APP_URL ?? 'http://localhost:3000'
+    const periodEnd = (sub.currentPeriodEnd ?? new Date()).toISOString().slice(0, 10)
+    await sendTemplateEmail({
+      key: type === 'subscription.paid' ? 'billing.payment-receipt' : 'billing.subscription-canceled',
+      to: user.email,
+      locale: user.locale ?? 'zh',
+      userId: sub.userId,
+      vars: type === 'subscription.paid'
+        ? { planName: sub.plan.displayName, periodEnd, dashboardUrl: `${appUrl}/settings/billing` }
+        : { planName: sub.plan.displayName, endDate: periodEnd, dashboardUrl: `${appUrl}/settings/billing` },
+    })
+  } catch { /* 计费邮件失败不影响 webhook 200 */ }
+}

package/src/server/email/__tests__/deliverability.test.ts

@@ -0,0 +1,68 @@
+import { describe, it, expect, vi, afterEach } from 'vitest'
+import { signUnsubscribeToken, verifyUnsubscribeToken, buildUnsubscribeHeaders } from '../deliverability'
+
+describe('unsubscribe HMAC token', () => {
+  it('签名后可验签还原 payload', () => {
+    const token = signUnsubscribeToken({ userId: 'u1', email: 'a@b.com', category: 'notification' })
+    const payload = verifyUnsubscribeToken(token)
+    expect(payload).toMatchObject({ userId: 'u1', email: 'a@b.com', category: 'notification' })
+  })
+
+  it('篡改 token 验签失败返回 null', () => {
+    const token = signUnsubscribeToken({ userId: 'u1', email: 'a@b.com', category: 'notification' })
+    expect(verifyUnsubscribeToken(token.slice(0, -2) + 'xx')).toBeNull()
+  })
+
+  it('过期 token（exp 过去）返回 null', () => {
+    const token = signUnsubscribeToken({ userId: 'u1', email: 'a@b.com', category: 'notification' }, -1000)
+    expect(verifyUnsubscribeToken(token)).toBeNull()
+  })
+
+  it('buildUnsubscribeHeaders 输出标准 List-Unsubscribe 双通道与 One-Click 声明', () => {
+    const headers = buildUnsubscribeHeaders({
+      appUrl: 'http://localhost:3000',
+      userId: 'u1',
+      email: 'a@b.com',
+      category: 'notification',
+    })
+    expect(headers['List-Unsubscribe']).toContain('<mailto:unsubscribe@allblue.local?subject=unsubscribe>')
+    expect(headers['List-Unsubscribe']).toContain('/email-unsubscribe?token=')
+    expect(headers['List-Unsubscribe'].trim().startsWith('<')).toBe(true)
+    expect(headers['List-Unsubscribe-Post']).toBe('One-Click=List-Unsubscribe')
+  })
+
+  it('空 token / 无分隔符 / 非法 base64 均返回 null', () => {
+    expect(verifyUnsubscribeToken('')).toBeNull()
+    expect(verifyUnsubscribeToken('nodot')).toBeNull()
+    expect(verifyUnsubscribeToken('.')).toBeNull()
+    const valid = signUnsubscribeToken({ userId: 'u1', email: 'a@b.com', category: 'notification' })
+    const [body] = valid.split('.')
+    expect(verifyUnsubscribeToken(`${body}.${'!!!'}`)).toBeNull()
+  })
+
+  it('过期 token 边界：exp 等于当前时间仍有效', () => {
+    const now = signUnsubscribeToken({ userId: 'u1', email: 'a@b.com', category: 'notification' }, 1000)
+    expect(verifyUnsubscribeToken(now)).not.toBeNull()
+  })
+
+  it('篡改 body 后验签失败', () => {
+    const valid = signUnsubscribeToken({ userId: 'u1', email: 'a@b.com', category: 'notification' })
+    const [, sig] = valid.split('.')
+    const tampered = Buffer.from(
+      JSON.stringify({ userId: 'attacker', email: 'a@b.com', category: 'notification', exp: Date.now() + 1000 }),
+      'utf8',
+    ).toString('base64url')
+    expect(verifyUnsubscribeToken(`${tampered}.${sig}`)).toBeNull()
+  })
+})
+
+describe('unsubscribe HMAC token - key isolation', () => {
+  afterEach(() => vi.unstubAllEnvs())
+
+  it('不同密钥签名的 token 无法互验', () => {
+    vi.stubEnv('AUTH_SECRET', 'secret-a')
+    const token = signUnsubscribeToken({ userId: 'u1', email: 'a@b.com', category: 'notification' })
+    vi.stubEnv('AUTH_SECRET', 'secret-b')
+    expect(verifyUnsubscribeToken(token)).toBeNull()
+  })
+})

package/src/server/email/__tests__/index.test.ts

@@ -0,0 +1,32 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+vi.mock('../outbox', () => ({
+  outboxSend: vi.fn().mockResolvedValue({ sent: true }),
+  generateEmailToken: vi.fn().mockReturnValue('tok-123'),
+}))
+
+import { sendTemplateEmail, generateEmailToken } from '../index'
+import { outboxSend } from '../outbox'
+
+beforeEach(() => {
+  vi.clearAllMocks()
+})
+
+describe('sendTemplateEmail', () => {
+  it('locale=en 归一为 en', async () => {
+    await sendTemplateEmail({ key: 'auth.welcome', to: 'a@b.com', locale: 'en', vars: {} })
+    expect(outboxSend).toHaveBeenCalledWith(expect.objectContaining({ locale: 'en' }))
+  })
+
+  it('locale=zh / undefined / 未知语言均归一为 zh', async () => {
+    for (const locale of ['zh', undefined, 'fr'] as const) {
+      vi.clearAllMocks()
+      await sendTemplateEmail({ key: 'auth.welcome', to: 'a@b.com', locale, vars: {} })
+      expect(outboxSend).toHaveBeenCalledWith(expect.objectContaining({ locale: 'zh' }))
+    }
+  })
+
+  it('generateEmailToken 透传 outbox 实现', () => {
+    expect(generateEmailToken()).toBe('tok-123')
+  })
+})

package/src/server/email/__tests__/outbox.test.tsx

@@ -0,0 +1,129 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+vi.mock('@allbluecn/database', () => ({
+  prisma: {
+    emailLog: {
+      create: vi.fn().mockResolvedValue({ id: 'log1' }),
+      update: vi.fn().mockResolvedValue({}),
+      count: vi.fn().mockResolvedValue(0),
+      findUnique: vi.fn().mockResolvedValue(null),
+    },
+    emailPreference: { findUnique: vi.fn().mockResolvedValue(null) },
+  },
+}))
+
+vi.mock('../sender', () => ({
+  sendByDriver: vi.fn().mockResolvedValue({ ok: true, messageId: 'm1', bounced: false }),
+  resolveDriver: () => 'console',
+}))
+
+import { outboxSend } from '../outbox'
+import { registerTemplate } from '../registry'
+import { prisma } from '@allbluecn/database'
+
+const GUEST_KEY = `test.guest-${Math.random().toString(36).slice(2, 8)}`
+const TX_KEY = `test.tx-${Math.random().toString(36).slice(2, 8)}`
+const NON_TX_KEY = `test.nontx-${Math.random().toString(36).slice(2, 8)}`
+
+registerTemplate({
+  key: GUEST_KEY,
+  category: 'auth',
+  transactional: true,
+  subject: { zh: 'g', en: 'g' },
+  component: () => <div>g</div>,
+})
+registerTemplate({
+  key: TX_KEY,
+  category: 'auth',
+  transactional: true,
+  subject: { zh: 't', en: 't' },
+  component: () => <div>t</div>,
+})
+registerTemplate({
+  key: NON_TX_KEY,
+  category: 'notification',
+  transactional: false,
+  subject: { zh: 'n', en: 'n' },
+  component: () => <div>n</div>,
+})
+
+beforeEach(() => {
+  vi.clearAllMocks()
+})
+
+describe('outbox 管道', () => {
+  it('guest 身份邮件被短路跳过（不写日志不发送）', async () => {
+    const result = await outboxSend({
+      key: GUEST_KEY,
+      to: 'guest@localhost',
+      locale: 'zh',
+      userId: 'local-guest',
+      vars: {},
+    })
+    expect(result.skipped).toBe(true)
+    expect(result.skipReason).toBe('guest')
+  })
+
+  it('未注册模板抛错', async () => {
+    await expect(
+      outboxSend({ key: 'nope.missing', to: 'a@b.com', locale: 'zh', vars: {} }),
+    ).rejects.toThrow(/not registered/)
+  })
+
+  it('事务性模板跳过退订检查（无 userId 时直接发送）', async () => {
+    const result = await outboxSend({ key: TX_KEY, to: 'a@b.com', locale: 'zh', vars: {} })
+    expect(result.sent).toBe(true)
+  })
+
+  it('dedupeKey 已存在 → 跳过（不发送不写日志）', async () => {
+    vi.mocked(prisma.emailLog.findUnique).mockResolvedValueOnce({ id: 'old' } as never)
+    const result = await outboxSend({ key: TX_KEY, to: 'a@b.com', locale: 'zh', vars: {}, dedupeKey: 'dup-1' })
+    expect(result).toEqual({ sent: false, skipped: true, skipReason: 'dedupe' })
+    expect(prisma.emailLog.create).not.toHaveBeenCalled()
+  })
+
+  it('dedupeKey 并发撞唯一键（P2002）→ 回退跳过而非抛错', async () => {
+    const p2002 = Object.assign(new Error('Unique constraint failed'), { code: 'P2002' })
+    vi.mocked(prisma.emailLog.create).mockRejectedValueOnce(p2002)
+    const result = await outboxSend({ key: TX_KEY, to: 'a@b.com', locale: 'zh', vars: {}, dedupeKey: 'dup-2' })
+    expect(result).toEqual({ sent: false, skipped: true, skipReason: 'dedupe' })
+    expect(prisma.emailLog.update).not.toHaveBeenCalled()
+  })
+
+  it('dedupeKey 非唯一键错误 → 原样抛错', async () => {
+    vi.mocked(prisma.emailLog.create).mockRejectedValueOnce(new Error('db down'))
+    await expect(
+      outboxSend({ key: TX_KEY, to: 'a@b.com', locale: 'zh', vars: {}, dedupeKey: 'dup-3' }),
+    ).rejects.toThrow('db down')
+  })
+
+  it('非事务模板传 unsubscribeUrl → headers 使用覆盖 URL，不调 HMAC', async () => {
+    const customUrl = 'http://localhost:3000/email-unsubscribe?token=db-token'
+    await outboxSend({
+      key: NON_TX_KEY,
+      to: 'a@b.com',
+      locale: 'zh',
+      unsubscribeUrl: customUrl,
+      vars: {},
+    })
+    const { sendByDriver } = await import('../sender')
+    const msg = vi.mocked(sendByDriver).mock.calls.at(-1)?.[0]
+    expect(msg?.headers?.['List-Unsubscribe']).toContain(`<${customUrl}>`)
+    expect(msg?.headers?.['List-Unsubscribe']).toContain('<mailto:unsubscribe@allblue.local?subject=unsubscribe>')
+    expect(msg?.headers?.['List-Unsubscribe-Post']).toBe('One-Click=List-Unsubscribe')
+  })
+
+  it('非事务模板无 unsubscribeUrl 有 userId → 回落 HMAC 路径', async () => {
+    await outboxSend({
+      key: NON_TX_KEY,
+      to: 'a@b.com',
+      locale: 'zh',
+      userId: 'u1',
+      vars: {},
+    })
+    const { sendByDriver } = await import('../sender')
+    const msg = vi.mocked(sendByDriver).mock.calls.at(-1)?.[0]
+    expect(msg?.headers?.['List-Unsubscribe']).toContain('/email-unsubscribe?token=')
+    expect(msg?.headers?.['List-Unsubscribe-Post']).toBe('One-Click=List-Unsubscribe')
+  })
+})

package/src/server/email/__tests__/product-templates.test.tsx

@@ -0,0 +1,106 @@
+import { describe, expect, it, vi } from 'vitest'
+
+vi.mock('@allbluecn/database', () => ({
+  prisma: {
+    emailLog: {
+      create: vi.fn().mockResolvedValue({ id: 'log1' }),
+      update: vi.fn().mockResolvedValue({}),
+      count: vi.fn().mockResolvedValue(0),
+      findUnique: vi.fn().mockResolvedValue(null),
+    },
+    emailPreference: { findUnique: vi.fn().mockResolvedValue(null) },
+  },
+}))
+
+vi.mock('../sender', () => ({
+  sendByDriver: vi.fn().mockResolvedValue({ ok: true, messageId: 'm1', bounced: false }),
+  resolveDriver: () => 'console',
+}))
+
+vi.mock('../preferences', () => ({
+  checkEmailEligibility: vi.fn().mockResolvedValue({ sendable: true }),
+}))
+
+import { createElement } from 'react'
+import { render } from '@react-email/render'
+import { outboxSend } from '../outbox'
+import { getTemplate } from '../registry'
+import { registerChangelogConfirmTemplate } from '../templates/product/changelog-confirm'
+import { registerChangelogReleaseTemplate } from '../templates/product/changelog-release'
+
+registerChangelogConfirmTemplate()
+registerChangelogReleaseTemplate()
+
+describe('product 模板', () => {
+  it('confirm 模板渲染按钮与提示', async () => {
+    const meta = getTemplate('product.changelog-confirm')!
+    const html = await render(createElement(meta.component, {
+      locale: 'zh',
+      confirmUrl: 'http://x/changelog/confirm?token=abc',
+    } as never))
+    expect(html).toContain('确认订阅')
+    expect(html).toContain('24 小时')
+    expect(html).toContain('token=abc')
+    expect(meta.transactional).toBe(false)
+    expect(meta.subject.zh).toBe('确认订阅 AllBlue 开发更新')
+  })
+
+  it('release 模板渲染版本与 highlights', async () => {
+    const meta = getTemplate('product.changelog-release')!
+    const html = await render(createElement(meta.component, {
+      locale: 'zh',
+      version: '1.2.3',
+      highlights: '新编辑器\n更快的搜索',
+      detailUrl: 'http://x/changelog',
+    } as never))
+    expect(html).toContain('v1.2.3')
+    expect(html).toContain('新编辑器')
+    expect(html).toContain('更快的搜索')
+    expect(html).toContain('查看更新日志')
+  })
+
+  it('release 模板 highlights 为空时不渲染该段', async () => {
+    const meta = getTemplate('product.changelog-release')!
+    const html = await render(createElement(meta.component, {
+      locale: 'zh',
+      version: '1.2.3',
+      highlights: '',
+      detailUrl: 'http://x/changelog',
+    } as never))
+    expect(html).toContain('v1.2.3')
+    expect(html).not.toContain('新编辑器')
+  })
+
+  it('release subject 动态插值 version', () => {
+    const meta = getTemplate('product.changelog-release')!
+    expect(typeof meta.subject.zh).toBe('function')
+    expect((meta.subject.zh as (v: Record<string, unknown>) => string)({ version: '9.9.9' })).toBe('AllBlue v9.9.9 发布')
+    expect((meta.subject.en as (v: Record<string, unknown>) => string)({ version: '9.9.9' })).toBe('AllBlue v9.9.9 released')
+  })
+
+  it('outbox 解析函数式 subject 并发送', async () => {
+    const r = await outboxSend({
+      key: 'product.changelog-release',
+      to: 'a@b.com',
+      locale: 'zh',
+      vars: { version: '1.0.0', highlights: '', detailUrl: 'http://x/changelog' },
+    })
+    expect(r).toEqual({ sent: true })
+    const { sendByDriver } = await import('../sender')
+    const msg = vi.mocked(sendByDriver).mock.calls.at(-1)?.[0]
+    expect(msg?.subject).toBe('AllBlue v1.0.0 发布')
+  })
+
+  it('confirm 模板游客路径（无 userId）跳过退订头', async () => {
+    await outboxSend({
+      key: 'product.changelog-confirm',
+      to: 'a@b.com',
+      locale: 'zh',
+      vars: { confirmUrl: 'http://x/c?token=t' },
+    })
+    const { sendByDriver } = await import('../sender')
+    const msg = vi.mocked(sendByDriver).mock.calls.at(-1)?.[0]
+    expect(msg?.headers).toEqual({})
+    expect(msg?.subject).toBe('确认订阅 AllBlue 开发更新')
+  })
+})

package/src/server/email/__tests__/registry.test.tsx

@@ -0,0 +1,50 @@
+import { describe, it, expect } from 'vitest'
+import { registerTemplate, getTemplate, listTemplates } from '../registry'
+
+const UNIQUE = `test.hello-${Math.random().toString(36).slice(2, 8)}`
+
+describe('email template registry', () => {
+  it('注册后可按 key 取回元数据', () => {
+    const Comp = () => <div>hi</div>
+    registerTemplate({
+      key: UNIQUE,
+      category: 'auth',
+      transactional: true,
+      subject: { zh: '你好', en: 'Hello' },
+      component: Comp,
+    })
+    const meta = getTemplate(UNIQUE)!
+    expect(meta).toBeDefined()
+    expect(meta.subject.zh).toBe('你好')
+    expect(meta.transactional).toBe(true)
+    expect(meta.component).toBe(Comp)
+  })
+
+  it('未注册 key 返回 undefined', () => {
+    expect(getTemplate('test.not-exist')).toBeUndefined()
+  })
+
+  it('重复注册同 key 抛错（防拼写冲突）', () => {
+    const dupKey = `test.dup-${Math.random().toString(36).slice(2, 8)}`
+    registerTemplate({
+      key: dupKey,
+      category: 'auth',
+      transactional: true,
+      subject: { zh: 'a', en: 'a' },
+      component: () => <div />,
+    })
+    expect(() =>
+      registerTemplate({
+        key: dupKey,
+        category: 'auth',
+        transactional: true,
+        subject: { zh: 'a', en: 'a' },
+        component: () => <div />,
+      }),
+    ).toThrow(/already registered/)
+  })
+
+  it('listTemplates 返回全部 key', () => {
+    expect(listTemplates().map((t) => t.key)).toContain(UNIQUE)
+  })
+})