核心组件

相关代码: server/, src/services/, src/hooks/

组件地图

Server 层组件

TokenManager

职责: 管理用户 AccessToken 的创建、缓存、清理

位置: server/tokenManager.ts

方法	作用
init()	初始化，清理上次残留 Token
getOrCreateToken(userId)	获取或创建用户 Token
cleanup()	定时清理过期 Token

存储结构:

// 内存缓存
const tokenCache = new Map<string, {
  userId: string
  aid: string      // Token ID（用于删除）
  token: string    // 实际 Token
  expiry: number   // 过期时间戳
}>()

// 文件持久化（不含 token）
// data/tokens.json
{
  "user123": { "userId": "user123", "aid": "aid456", "expiry": 1234567890 }
}

SessionManager

职责: 管理员登录会话的创建和验证

位置: server/sessionManager.ts

设计亮点: 无状态 session - 不需要 Redis 或数据库

// Token 结构: {payload}.{signature}
// payload: base64url({ username, exp })
// signature: HMAC-SHA256(payload, SECRET)

ProxyRoutes

职责: 用户数据 API 路由，注入动态 Token

位置: server/proxyRoutes.ts

路由清单:

路由	用途
/users/:userId/orders	订单列表
/users/:userId/transactions	收支明细
/users/:userId/bills	账单明细
/users/:userId/wallet/balance	钱包余额
/users/:userId/vouchers	活跃代金券
/users/:userId/monthly-bills	月账单
/users/:userId/members	子账号成员
/users/:userId/export/*	导出接口

Service 层组件

api.ts

职责: Leopard API 调用封装、数据转换

位置: src/services/api.ts

关键函数:

函数	作用
fetchSKUs()	获取 SKU 列表（含 N+1 查询）
fetchSKUDetail()	获取 SKU 详情（编辑用）
createSKU()	创建 SKU（可能需先创建 Spec）
updateSKUStatus()	上下架切换
mapLeopardSkuToFrontend()	EAV → 扁平结构转换

ghippo.ts

职责: 用户管理 API 封装

位置: src/services/ghippo.ts

Hook 层组件

useAuth

职责: 认证状态管理

位置: src/hooks/useAuth.tsx

interface AuthContextType {
  user: User | null
  isAuthenticated: boolean
  login: (credentials) => Promise<boolean>
  logout: () => void
  loading: boolean
}

特点:

• 页面加载时自动检查 /api/v1/auth/check
• Cookie 自动携带，前端无需处理 Token

useSKUs

职责: SKU 数据获取和缓存

位置: src/hooks/useSKUs.ts

useProducts / useRegions

职责: 产品和区域下拉数据

位置: src/hooks/useProducts.ts, src/hooks/useRegions.ts

配置组件

productConfig.ts

职责: 产品类型配置，驱动 SKU 表格列和路由

位置: src/config/productConfig.ts

const PRODUCT_CONFIG: Record<string, ProductConfig> = {
  'zestu-container-instance': {
    label: '容器管理',
    addRoute: '/sku/add/container',
    editRoute: '/sku/edit/container',
    columns: containerColumns,
  },
  'zestu-file-storage': {
    label: '文件存储',
    addRoute: '/sku/add/file-storage',
    // ...
  },
  // ...
}

设计意图: 新增产品类型时，只需添加配置项，无需修改组件代码

下一步

• Token 管理详解 - 缓存策略和清理机制
• 认证流程详解 - 登录和会话管理