Add mail/inbox system with broadcast & multicast (#13)

Virtual mailbox design: one row per message plus lazily-written
mail_user_states for per-user read/claim state, joined at query time.
Avoids fan-out writes for broadcasts (endUserId has no registry) and
keeps rare interactions sparse.

Server module follows the 7-file pattern (types/errors/validators/
service/routes/client-routes/index). Admin routes under /api/mail,
client routes under /api/client/mail. Reward claim reuses
itemService.grantItems with (source="mail_claim", sourceId) for
idempotency. Programmatic callers get originSource/originSourceId
partial-unique dedup so retried activity-settlement emits one mail.

Admin UI: list/create/detail pages with reward picker, broadcast vs
multicast target switch, requireRead gate, expiry, revoke.

Also extract ItemRewardRow shared component and replace inline UUID
rendering in check-in, exchange detail, and exchange execute panel
so all reward displays show icon + name + quantity uniformly.

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: dengzhaofun

apps/admin/messages/en.json

@@ -222,7 +222,68 @@
   "nav_checkin": "Check-in",
   "nav_item": "Item",
   "nav_exchange": "Exchange",
+  "nav_mail": "Mail",
   "nav_api_keys": "API Keys",
   "nav_go_to_dashboard": "Go to Dashboard",
-  "nav_about_starter": "About This Starter"
+  "nav_about_starter": "About This Starter",
+
+  "mail_title": "Mail",
+  "mail_new_message": "New Mail",
+  "mail_send": "Send",
+  "mail_sent": "Mail sent",
+  "mail_failed_send": "Failed to send mail",
+  "mail_failed_load": "Failed to load mail:",
+  "mail_not_found": "Mail not found",
+  "mail_empty": "No mail yet.",
+  "mail_all_users": "All users",
+  "mail_no_rewards": "No rewards attached.",
+  "mail_stats": "Stats",
+  "mail_stat_targets": "Targets",
+  "mail_stat_reads": "Reads",
+  "mail_stat_claims": "Claims",
+  "mail_origin_source": "Origin",
+
+  "mail_col_title": "Title",
+  "mail_col_target": "Target",
+  "mail_col_recipients": "Recipients",
+  "mail_col_require_read": "Read Required",
+  "mail_col_sent_at": "Sent At",
+
+  "mail_status_active": "Active",
+  "mail_status_expired": "Expired",
+  "mail_status_revoked": "Revoked",
+
+  "mail_target_broadcast": "Broadcast",
+  "mail_target_multicast": "Multicast",
+  "mail_target_unicast": "Unicast",
+
+  "mail_require_read_yes": "Read required",
+
+  "mail_field_title": "Title",
+  "mail_field_content": "Content",
+  "mail_field_target_type": "Target type",
+  "mail_field_target_hint": "Broadcast reaches every user in the org. Multicast only reaches the listed IDs.",
+  "mail_field_recipients": "Recipient end user IDs",
+  "mail_field_recipients_hint": "One per line or comma-separated. Max 5000.",
+  "mail_field_rewards": "Rewards",
+  "mail_field_rewards_hint": "Rewards are granted atomically when the user taps Claim. Empty list = announcement-only.",
+  "mail_field_add_reward": "Add Reward",
+  "mail_field_select_item": "Select item...",
+  "mail_field_require_read": "Require read before claim",
+  "mail_field_require_read_hint": "When on, users must open the mail before Claim becomes active.",
+  "mail_field_expires_at": "Expires at",
+  "mail_field_expires_at_hint": "After this time the mail is hidden and unclaimable. Leave blank for no expiry.",
+
+  "mail_error_title_content_required": "Title and content are required.",
+  "mail_error_recipients_required": "At least one recipient is required for multicast.",
+
+  "mail_revoke": "Revoke",
+  "mail_revoked": "Mail revoked",
+  "mail_failed_revoke": "Failed to revoke mail",
+  "mail_revoke_confirm_title": "Revoke this mail?",
+  "mail_revoke_confirm_desc": "Users will no longer see this mail. Claim history is preserved.",
+  "mail_deleted": "Mail deleted",
+  "mail_failed_delete": "Failed to delete mail",
+  "mail_delete_confirm_title": "Permanently delete this mail?",
+  "mail_delete_confirm_desc": "This removes the message and every user's read/claim state for it. Cannot be undone."
 }

apps/admin/messages/zh.json

@@ -222,7 +222,68 @@
   "nav_checkin": "签到",
   "nav_item": "物品",
   "nav_exchange": "兑换",
+  "nav_mail": "邮件",
   "nav_api_keys": "API 密钥",
   "nav_go_to_dashboard": "进入仪表盘",
-  "nav_about_starter": "关于此模板"
+  "nav_about_starter": "关于此模板",
+
+  "mail_title": "邮件",
+  "mail_new_message": "发送邮件",
+  "mail_send": "发送",
+  "mail_sent": "邮件已发送",
+  "mail_failed_send": "邮件发送失败",
+  "mail_failed_load": "邮件加载失败：",
+  "mail_not_found": "未找到该邮件",
+  "mail_empty": "暂无邮件。",
+  "mail_all_users": "全部玩家",
+  "mail_no_rewards": "该邮件未附带奖励。",
+  "mail_stats": "统计",
+  "mail_stat_targets": "投递对象",
+  "mail_stat_reads": "已读数",
+  "mail_stat_claims": "领取数",
+  "mail_origin_source": "来源",
+
+  "mail_col_title": "标题",
+  "mail_col_target": "投递方式",
+  "mail_col_recipients": "收件人数",
+  "mail_col_require_read": "需先阅读",
+  "mail_col_sent_at": "发送时间",
+
+  "mail_status_active": "有效",
+  "mail_status_expired": "已过期",
+  "mail_status_revoked": "已撤回",
+
+  "mail_target_broadcast": "全服广播",
+  "mail_target_multicast": "组播",
+  "mail_target_unicast": "单播",
+
+  "mail_require_read_yes": "需先阅读",
+
+  "mail_field_title": "标题",
+  "mail_field_content": "正文",
+  "mail_field_target_type": "投递方式",
+  "mail_field_target_hint": "广播覆盖组织下全部玩家；组播仅投递给列表中的 endUserId。",
+  "mail_field_recipients": "收件人 endUserId 列表",
+  "mail_field_recipients_hint": "每行一个或用逗号分隔，最多 5000 个。",
+  "mail_field_rewards": "奖励",
+  "mail_field_rewards_hint": "奖励在玩家点击领取时原子发放。留空表示仅公告，无奖励。",
+  "mail_field_add_reward": "添加奖励",
+  "mail_field_select_item": "选择物品...",
+  "mail_field_require_read": "领取前必须先阅读",
+  "mail_field_require_read_hint": "开启后，玩家必须先打开邮件才能领取奖励。",
+  "mail_field_expires_at": "过期时间",
+  "mail_field_expires_at_hint": "到期后邮件对玩家隐藏且不可领取。留空表示永不过期。",
+
+  "mail_error_title_content_required": "标题和正文不能为空。",
+  "mail_error_recipients_required": "组播至少需要一个收件人。",
+
+  "mail_revoke": "撤回",
+  "mail_revoked": "邮件已撤回",
+  "mail_failed_revoke": "撤回失败",
+  "mail_revoke_confirm_title": "撤回此邮件？",
+  "mail_revoke_confirm_desc": "玩家将不再看到此邮件，领取记录会被保留。",
+  "mail_deleted": "邮件已删除",
+  "mail_failed_delete": "删除失败",
+  "mail_delete_confirm_title": "彻底删除此邮件？",
+  "mail_delete_confirm_desc": "将同时删除消息本体及所有玩家对该邮件的已读/领取状态，且无法恢复。"
 }

apps/admin/src/components/AppSidebar.tsx

@@ -6,6 +6,7 @@ import {
   Dices,
   KeyRound,
   LayoutDashboard,
+  Mail,
   Package,
 } from "lucide-react"
 
@@ -31,6 +32,7 @@ function getNavItems() {
     { title: m.nav_checkin(), to: "/check-in" as const, icon: CalendarCheck },
     { title: m.nav_item(), to: "/item" as const, icon: Package },
     { title: m.nav_exchange(), to: "/exchange" as const, icon: ArrowLeftRight },
+    { title: m.nav_mail(), to: "/mail" as const, icon: Mail },
     { title: m.nav_api_keys(), to: "/api-keys" as const, icon: KeyRound },
   ]
 }

apps/admin/src/components/check-in/RewardsSection.tsx

@@ -30,7 +30,7 @@ import {
   useUpdateCheckInReward,
   useDeleteCheckInReward,
 } from "#/hooks/use-check-in-rewards"
-import { useItemDefinitions } from "#/hooks/use-item"
+import { ItemRewardRow } from "#/components/item/ItemRewardRow"
 import { ApiError } from "#/lib/api-client"
 import type { CheckInReward } from "#/lib/types/check-in-reward"
 
@@ -40,15 +40,10 @@ interface RewardsSectionProps {
 
 export function RewardsSection({ configKey }: RewardsSectionProps) {
   const { data: rewards, isPending } = useCheckInRewards(configKey)
-  const { data: definitions } = useItemDefinitions()
   const createMutation = useCreateCheckInReward()
   const updateMutation = useUpdateCheckInReward()
   const deleteMutation = useDeleteCheckInReward()
 
-  const defNameMap = new Map(
-    (definitions ?? []).map((d) => [d.id, d.name]),
-  )
-
   const [createOpen, setCreateOpen] = useState(false)
   const [editingReward, setEditingReward] = useState<CheckInReward | null>(null)
 
@@ -111,17 +106,14 @@ export function RewardsSection({ configKey }: RewardsSectionProps) {
               className="flex items-center gap-3 rounded-lg border bg-card px-4 py-3"
             >
               <Badge variant="secondary">Day {reward.dayNumber}</Badge>
-              <div className="flex-1 text-sm">
+              <div className="flex flex-wrap items-center gap-x-3 gap-y-1 flex-1 text-sm">
                 {reward.rewardItems.map((item, i) => (
-                  <span key={i}>
-                    {i > 0 && ", "}
-                    {item.quantity}x{" "}
-                    {defNameMap.get(item.definitionId) ?? (
-                      <code className="rounded bg-muted px-1 py-0.5 text-xs">
-                        {item.definitionId.slice(0, 8)}...
-                      </code>
-                    )}
-                  </span>
+                  <ItemRewardRow
+                    key={i}
+                    size="sm"
+                    definitionId={item.definitionId}
+                    quantity={item.quantity}
+                  />
                 ))}
               </div>
 

apps/admin/src/components/exchange/ExecutePanel.tsx

@@ -8,6 +8,7 @@ import { Input } from "#/components/ui/input"
 import { Label } from "#/components/ui/label"
 import { Badge } from "#/components/ui/badge"
 import { useExecuteExchange } from "#/hooks/use-exchange"
+import { ItemRewardRow } from "#/components/item/ItemRewardRow"
 import { ApiError } from "#/lib/api-client"
 import type { ExchangeResult } from "#/lib/types/exchange"
 
@@ -84,20 +85,28 @@ export function ExecutePanel({ optionId }: ExecutePanelProps) {
             </span>
           </div>
           <div className="grid gap-2 text-sm sm:grid-cols-2">
-            <div>
+            <div className="space-y-1">
               <p className="text-xs font-medium text-muted-foreground">Consumed</p>
               {result.costItems.map((item, i) => (
-                <p key={i}>
-                  {item.quantity}x {item.definitionId.slice(0, 8)}...
-                </p>
+                <div key={i}>
+                  <ItemRewardRow
+                    size="sm"
+                    definitionId={item.definitionId}
+                    quantity={item.quantity}
+                  />
+                </div>
               ))}
             </div>
-            <div>
+            <div className="space-y-1">
               <p className="text-xs font-medium text-muted-foreground">Granted</p>
               {result.rewardItems.map((item, i) => (
-                <p key={i}>
-                  {item.quantity}x {item.definitionId.slice(0, 8)}...
-                </p>
+                <div key={i}>
+                  <ItemRewardRow
+                    size="sm"
+                    definitionId={item.definitionId}
+                    quantity={item.quantity}
+                  />
+                </div>
               ))}
             </div>
           </div>

apps/admin/src/components/item/ItemRewardRow.tsx

@@ -0,0 +1,46 @@
+import { useItemDefinitions } from "#/hooks/use-item"
+
+interface Props {
+  definitionId: string
+  quantity: number
+  /** sm: size-4 icon, tighter gap (for inline / tables). md: size-6 icon (for detail cards). */
+  size?: "sm" | "md"
+  className?: string
+}
+
+/**
+ * Renders a single reward entry as: [icon] Name × quantity.
+ * Falls back to a muted square + truncated id when the definition can't be resolved
+ * (e.g. the item was deleted). Uses `useItemDefinitions` which is react-query-cached.
+ */
+export function ItemRewardRow({
+  definitionId,
+  quantity,
+  size = "md",
+  className,
+}: Props) {
+  const { data: definitions } = useItemDefinitions()
+  const def = (definitions ?? []).find((d) => d.id === definitionId)
+
+  const iconClass =
+    size === "sm" ? "size-4 shrink-0" : "size-6 shrink-0"
+  const gapClass = size === "sm" ? "gap-1.5" : "gap-2"
+
+  return (
+    <span className={`inline-flex items-center ${gapClass} ${className ?? ""}`}>
+      {def?.icon ? (
+        <img src={def.icon} alt="" className={`${iconClass} rounded object-cover`} />
+      ) : (
+        <span className={`${iconClass} rounded bg-muted`} aria-hidden />
+      )}
+      {def ? (
+        <span className="font-medium">{def.name}</span>
+      ) : (
+        <code className="rounded bg-muted px-1 py-0.5 text-xs">
+          {definitionId.slice(0, 8)}…
+        </code>
+      )}
+      <span className="text-muted-foreground">× {quantity}</span>
+    </span>
+  )
+}