Add social modules — friend, guild, team, friend-gift (#18)

Four new game SaaS modules for social gameplay features:

- **Friend**: settings, relationships (single-row pair storage), requests
  (send/accept/reject/cancel), blocks (with side effects: unfriend + cancel
  pending). 69 new API endpoints (admin + client).
- **Guild**: settings, guild CRUD, membership (leader/officer/member roles),
  join requests/invitations, contribution tracking with guild XP + level-up.
  One-guild-per-user enforced at service layer.
- **Team**: multi-config (per game mode), ephemeral teams, join/leave/dissolve,
  quick match, invitations. Atomic memberCount with version guards.
- **Friend Gift**: settings, gift packages (admin templates), send/claim flow
  with daily limits, friendship validation, item service integration.

Each module includes:
- Schema (17 new tables) with migrations
- Service layer (protocol-agnostic, no db.transaction)
- Admin routes (OpenAPIHono) + client routes (HMAC auth)
- Comprehensive service tests (129 tests total)
- Admin dashboard pages with i18n (en/zh)

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: dengzhaofun

apps/admin/messages/en.json

@@ -706,5 +706,57 @@
   "collection_rescan_success": "Sync done, newly unlocked",
   "collection_rescan_need_user": "Please enter endUserId",
   "collection_rescan_failed": "Sync failed",
-  "collection_saving": "Saving..."
+  "collection_saving": "Saving...",
+
+  "nav_friend": "Friend",
+  "nav_guild": "Guild",
+  "nav_team": "Team",
+  "nav_gift": "Gift",
+
+  "friend_title": "Friend System",
+  "friend_settings": "Friend Settings",
+  "friend_settings_updated": "Friend settings updated",
+  "friend_max_friends": "Max Friends",
+  "friend_max_blocked": "Max Blocked",
+  "friend_max_pending": "Max Pending Requests",
+  "friend_relationships": "Relationships",
+  "friend_no_settings": "No friend settings configured yet.",
+  "friend_no_relationships": "No friend relationships yet.",
+  "friend_relationship_deleted": "Friendship removed",
+
+  "guild_title": "Guild System",
+  "guild_settings": "Guild Settings",
+  "guild_settings_updated": "Guild settings updated",
+  "guild_max_members": "Max Members",
+  "guild_max_officers": "Max Officers",
+  "guild_join_mode": "Default Join Mode",
+  "guild_guilds": "Guilds",
+  "guild_no_settings": "No guild settings configured yet.",
+  "guild_no_guilds": "No guilds yet.",
+  "guild_disbanded": "Guild disbanded",
+
+  "team_title": "Team Configs",
+  "team_new_config": "New Config",
+  "team_config_created": "Team config created",
+  "team_config_updated": "Team config updated",
+  "team_config_deleted": "Team config deleted",
+  "team_no_configs": "No team configs yet.",
+  "team_max_members": "Max Members",
+  "team_auto_dissolve": "Auto Dissolve on Leader Leave",
+  "team_quick_match": "Quick Match",
+
+  "gift_title": "Friend Gift",
+  "gift_settings": "Gift Settings",
+  "gift_settings_updated": "Gift settings updated",
+  "gift_daily_send_limit": "Daily Send Limit",
+  "gift_daily_receive_limit": "Daily Receive Limit",
+  "gift_timezone": "Timezone",
+  "gift_packages": "Gift Packages",
+  "gift_new_package": "New Package",
+  "gift_package_created": "Gift package created",
+  "gift_package_updated": "Gift package updated",
+  "gift_package_deleted": "Gift package deleted",
+  "gift_no_settings": "No gift settings configured yet.",
+  "gift_no_packages": "No gift packages yet.",
+  "gift_items_count": "Items"
 }

apps/admin/messages/zh.json

@@ -706,5 +706,57 @@
   "collection_rescan_success": "同步成功，新解锁",
   "collection_rescan_need_user": "请输入 endUserId",
   "collection_rescan_failed": "同步失败",
-  "collection_saving": "保存中..."
+  "collection_saving": "保存中...",
+
+  "nav_friend": "好友",
+  "nav_guild": "公会",
+  "nav_team": "组队",
+  "nav_gift": "赠礼",
+
+  "friend_title": "好友系统",
+  "friend_settings": "好友设置",
+  "friend_settings_updated": "好友设置已更新",
+  "friend_max_friends": "好友上限",
+  "friend_max_blocked": "拉黑上限",
+  "friend_max_pending": "待处理请求上限",
+  "friend_relationships": "好友关系",
+  "friend_no_settings": "尚未配置好友设置。",
+  "friend_no_relationships": "暂无好友关系。",
+  "friend_relationship_deleted": "已解除好友关系",
+
+  "guild_title": "公会系统",
+  "guild_settings": "公会设置",
+  "guild_settings_updated": "公会设置已更新",
+  "guild_max_members": "成员上限",
+  "guild_max_officers": "干部上限",
+  "guild_join_mode": "默认加入模式",
+  "guild_guilds": "公会列表",
+  "guild_no_settings": "尚未配置公会设置。",
+  "guild_no_guilds": "暂无公会。",
+  "guild_disbanded": "公会已解散",
+
+  "team_title": "组队配置",
+  "team_new_config": "新建配置",
+  "team_config_created": "组队配置已创建",
+  "team_config_updated": "组队配置已更新",
+  "team_config_deleted": "组队配置已删除",
+  "team_no_configs": "暂无组队配置。",
+  "team_max_members": "队伍人数上限",
+  "team_auto_dissolve": "队长离开时自动解散",
+  "team_quick_match": "快速匹配",
+
+  "gift_title": "好友赠礼",
+  "gift_settings": "赠礼设置",
+  "gift_settings_updated": "赠礼设置已更新",
+  "gift_daily_send_limit": "每日发送上限",
+  "gift_daily_receive_limit": "每日接收上限",
+  "gift_timezone": "时区",
+  "gift_packages": "礼包模板",
+  "gift_new_package": "新建礼包",
+  "gift_package_created": "礼包已创建",
+  "gift_package_updated": "礼包已更新",
+  "gift_package_deleted": "礼包已删除",
+  "gift_no_settings": "尚未配置赠礼设置。",
+  "gift_no_packages": "暂无礼包模板。",
+  "gift_items_count": "物品数"
 }

apps/admin/src/components/AppSidebar.tsx

@@ -5,13 +5,17 @@ import {
   BookOpen,
   CalendarCheck,
   GalleryHorizontal,
+  Gift,
   KeyRound,
   LayoutDashboard,
   Mail,
   MessagesSquare,
   Package,
+  Shield,
   ShoppingCart,
+  Swords,
   Ticket,
+  Users,
 } from "lucide-react"
 
 import {
@@ -42,6 +46,10 @@ function getNavItems() {
     { title: m.nav_banner(), to: "/banner" as const, icon: GalleryHorizontal },
     { title: m.nav_dialogue(), to: "/dialogue" as const, icon: MessagesSquare },
     { title: m.nav_collection(), to: "/collection" as const, icon: BookOpen },
+    { title: m.nav_friend(), to: "/friend" as const, icon: Users },
+    { title: m.nav_guild(), to: "/guild" as const, icon: Shield },
+    { title: m.nav_team(), to: "/team" as const, icon: Swords },
+    { title: m.nav_gift(), to: "/friend-gift" as const, icon: Gift },
     { title: m.nav_api_keys(), to: "/api-keys" as const, icon: KeyRound },
   ]
 }

apps/admin/src/hooks/use-friend-gift.ts

@@ -0,0 +1,90 @@
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query"
+
+import { api } from "#/lib/api-client"
+import type {
+  CreateFriendGiftPackageInput,
+  FriendGiftPackage,
+  FriendGiftSend,
+  FriendGiftSettings,
+  UpdateFriendGiftPackageInput,
+  UpsertFriendGiftSettingsInput,
+} from "#/lib/types/friend-gift"
+
+const SETTINGS_KEY = ["friend-gift-settings"] as const
+const PACKAGES_KEY = ["friend-gift-packages"] as const
+const SENDS_KEY = ["friend-gift-sends"] as const
+
+export function useFriendGiftSettings() {
+  return useQuery({
+    queryKey: SETTINGS_KEY,
+    queryFn: () => api.get<FriendGiftSettings>("/api/friend-gift/settings"),
+  })
+}
+
+export function useUpsertFriendGiftSettings() {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: (input: UpsertFriendGiftSettingsInput) =>
+      api.put<FriendGiftSettings>("/api/friend-gift/settings", input),
+    onSuccess: () => qc.invalidateQueries({ queryKey: SETTINGS_KEY }),
+  })
+}
+
+export function useFriendGiftPackages() {
+  return useQuery({
+    queryKey: PACKAGES_KEY,
+    queryFn: () =>
+      api.get<{ items: FriendGiftPackage[] }>("/api/friend-gift/packages"),
+    select: (data) => data.items,
+  })
+}
+
+export function useFriendGiftPackage(id: string) {
+  return useQuery({
+    queryKey: [...PACKAGES_KEY, id],
+    queryFn: () =>
+      api.get<FriendGiftPackage>(`/api/friend-gift/packages/${id}`),
+    enabled: !!id,
+  })
+}
+
+export function useCreateFriendGiftPackage() {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: (input: CreateFriendGiftPackageInput) =>
+      api.post<FriendGiftPackage>("/api/friend-gift/packages", input),
+    onSuccess: () => qc.invalidateQueries({ queryKey: PACKAGES_KEY }),
+  })
+}
+
+export function useUpdateFriendGiftPackage() {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: ({
+      id,
+      input,
+    }: {
+      id: string
+      input: UpdateFriendGiftPackageInput
+    }) => api.patch<FriendGiftPackage>(`/api/friend-gift/packages/${id}`, input),
+    onSuccess: () => qc.invalidateQueries({ queryKey: PACKAGES_KEY }),
+  })
+}
+
+export function useDeleteFriendGiftPackage() {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: (id: string) =>
+      api.delete(`/api/friend-gift/packages/${id}`),
+    onSuccess: () => qc.invalidateQueries({ queryKey: PACKAGES_KEY }),
+  })
+}
+
+export function useFriendGiftSends() {
+  return useQuery({
+    queryKey: SENDS_KEY,
+    queryFn: () =>
+      api.get<{ items: FriendGiftSend[] }>("/api/friend-gift/sends"),
+    select: (data) => data.items,
+  })
+}

apps/admin/src/hooks/use-friend.ts

@@ -0,0 +1,46 @@
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query"
+
+import { api } from "#/lib/api-client"
+import type {
+  FriendRelationship,
+  FriendSettings,
+  UpsertFriendSettingsInput,
+} from "#/lib/types/friend"
+
+const SETTINGS_KEY = ["friend-settings"] as const
+const RELATIONSHIPS_KEY = ["friend-relationships"] as const
+
+export function useFriendSettings() {
+  return useQuery({
+    queryKey: SETTINGS_KEY,
+    queryFn: () => api.get<FriendSettings>("/api/friend/settings"),
+  })
+}
+
+export function useUpsertFriendSettings() {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: (input: UpsertFriendSettingsInput) =>
+      api.put<FriendSettings>("/api/friend/settings", input),
+    onSuccess: () => qc.invalidateQueries({ queryKey: SETTINGS_KEY }),
+  })
+}
+
+export function useFriendRelationships() {
+  return useQuery({
+    queryKey: RELATIONSHIPS_KEY,
+    queryFn: () =>
+      api.get<{ items: FriendRelationship[] }>("/api/friend/relationships"),
+    select: (data) => data.items,
+  })
+}
+
+export function useDeleteFriendRelationship() {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: (id: string) =>
+      api.delete(`/api/friend/relationships/${id}`),
+    onSuccess: () =>
+      qc.invalidateQueries({ queryKey: RELATIONSHIPS_KEY }),
+  })
+}

apps/admin/src/hooks/use-guild.ts

@@ -0,0 +1,51 @@
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query"
+
+import { api } from "#/lib/api-client"
+import type {
+  Guild,
+  GuildSettings,
+  UpsertGuildSettingsInput,
+} from "#/lib/types/guild"
+
+const SETTINGS_KEY = ["guild-settings"] as const
+const GUILDS_KEY = ["guilds"] as const
+
+export function useGuildSettings() {
+  return useQuery({
+    queryKey: SETTINGS_KEY,
+    queryFn: () => api.get<GuildSettings>("/api/guild/settings"),
+  })
+}
+
+export function useUpsertGuildSettings() {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: (input: UpsertGuildSettingsInput) =>
+      api.put<GuildSettings>("/api/guild/settings", input),
+    onSuccess: () => qc.invalidateQueries({ queryKey: SETTINGS_KEY }),
+  })
+}
+
+export function useGuilds() {
+  return useQuery({
+    queryKey: GUILDS_KEY,
+    queryFn: () => api.get<{ items: Guild[] }>("/api/guild/guilds"),
+    select: (data) => data.items,
+  })
+}
+
+export function useGuild(id: string) {
+  return useQuery({
+    queryKey: [...GUILDS_KEY, id],
+    queryFn: () => api.get<Guild>(`/api/guild/guilds/${id}`),
+    enabled: !!id,
+  })
+}
+
+export function useDeleteGuild() {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: (id: string) => api.delete(`/api/guild/guilds/${id}`),
+    onSuccess: () => qc.invalidateQueries({ queryKey: GUILDS_KEY }),
+  })
+}