开发者指南

第三方接入指南 v1.1

Microcosm 第三方接入指南

版本: v1.1 | 日期: 2026-02-15

本文档是第三方项目接入 Microcosm 生态的唯一指南。

快速开始（5 分钟）

1. 安装 SDK

bash

npm install @microcosmmoney/auth-core @microcosmmoney/auth-react @microcosmmoney/portal-react

2. 后端: Token Exchange（1 个文件）

typescript

// app/api/auth/exchange/route.ts
import { createTokenExchangeHandler } from '@microcosmmoney/auth-react/server'

export const POST = createTokenExchangeHandler({
  clientId: process.env.OAUTH_CLIENT_ID!,
  clientSecret: process.env.OAUTH_CLIENT_SECRET!,
})

3. 前端: Provider（1 个文件）

tsx

// app/providers.tsx
'use client'
import { MicrocosmAuthProvider } from '@microcosmmoney/auth-react'

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <MicrocosmAuthProvider
      clientId={process.env.NEXT_PUBLIC_OAUTH_CLIENT_ID!}
      redirectUri="/auth/callback"
    >
      {children}
    </MicrocosmAuthProvider>
  )
}

4. 回调页（1 个文件）

tsx

// app/auth/callback/page.tsx
import { AuthCallback } from '@microcosmmoney/auth-react'
export default () => <AuthCallback redirectTo="/dashboard" />

5. 使用（任意组件）

tsx

import { useAuth, useMCC, useMCD } from '@microcosmmoney/auth-react'

const { user, login, logout, isLoading } = useAuth()
const { balance: mccBalance, price: mccPrice } = useMCC()
const { balance: mcdBalance } = useMCD()

完成。 4 个文件，不到 30 行代码。

认证模型

层级	认证方式	说明
公开	无	价格、统计、拍卖列表、领地集合 — 谁都能调
用户	OAuth Bearer Token	余额、交易记录、挖矿数据 — 登录就能看
项目	API Key + HMAC	写操作（挖矿提交、资金管理） — 大多数项目不需要

OAuth 流程

用户点击登录 → 跳转 microcosm.money → 用户登录 → 带 code 回调
→ 项目后端用 code + client_secret 换 token → 返回 access_token + user

当前仅支持 Confidential Client 模式（需要 client_secret，后端必须参与 Token Exchange）。

Token 规格

属性	值
有效期	1 小时
刷新	SDK 自动处理
存储	localStorage（`mc_` 前缀）
刷新机制	Token 轮换（每次刷新返回新 refresh_token）

项目注册

流程

登录 microcosm.money → 开发者中心 → 申请项目接入
填写：项目名称、描述、OAuth Redirect URIs、前端域名、MCD 钱包地址
管理员审批
审批通过 → 获得 client_id + client_secret + api_key
前端域名自动加入 CORS 白名单

凭证说明

凭证	用途	存放位置
`client_id`	OAuth 登录标识	前端环境变量
`client_secret`	Token Exchange	仅后端（K8s Secret）
`api_key`	调用写操作 API	后端（大多数项目不需要）

用户来源追踪: 用户首次通过你的项目 OAuth 登录时，source_project_id = client_id 永久绑定。该用户挖矿产生的伴生矿中 10% MCD 分配给你的开发者钱包。

SDK 配置参考

tsx

<MicrocosmAuthProvider
  clientId="your-client-id"           // (必填) OAuth Client ID
  redirectUri="/auth/callback"         // (必填) 回调路径
  // scope={['openid', 'profile', 'email']}  // 默认值，通常无需改
  // authEndpoint="https://microcosm.money"  // 默认值
  // tokenExchangeUri="/api/auth/exchange"   // 默认值
  // profileUri="/api/users/profile"         // 默认值
  // storage="localStorage"                  // 默认值
  // autoRefresh={true}                      // 默认值
  // debug={false}                           // 开发时可开启
>

SDK Hooks 完整列表

认证 & 用户

Hook	说明	需登录
`useAuth()`	认证状态：`{ user, login, logout, isAuthenticated, isLoading, error, getAccessToken }`	—
`useProfile()`	用户资料 + 更新 + 头像上传	✅

资产数据

Hook	说明	需登录
`useMCC()`	MCC 余额（多钱包聚合）+ 价格	✅
`useMCD()`	MCD 余额 + 交易记录 + 奖励	✅
`useMCCPrice()`	MCC 实时价格（30s 刷新）	❌
`useMCCStats()`	MCC 全局统计（5min 缓存）	❌
`useMCDStats()`	MCD 全局统计（5min 缓存）	❌

钱包管理

Hook	说明	需登录
`useWallets()`	用户绑定的所有钱包列表	✅
`useTokenPortfolio(address)`	指定钱包的完整代币组合（SOL/MCC/USDT）	❌
`useMCCLocks()`	MCC 锁仓期列表	✅

挖矿 & 轮回

Hook	说明	需登录
`useMiningStats()`	用户挖矿统计	✅
`useMiningRecords()`	挖矿历史记录（分页）	✅
`useMiningRatio()`	挖矿比率/阶段/速率	❌
`useMiningDistribution({ page })`	伴生矿分配历史（分页）	✅
`useMiningConfig()`	挖矿合约配置（地址/比例/限额）	❌
`useMiningHistory({ limit, offset })`	x402 挖矿详细历史	✅
`useReincarnationPool()`	轮回池余额 + 回购价格（公开）	❌
`useReincarnationConfig()`	轮回合约配置（地址/限额/溢价率）	❌
`useBuybackQuote(amount)`	回购报价计算（输入 MCC 数量）	❌
`useBuybackHistory({ page })`	用户回购记录（分页）	✅
`useCycleHistory({ page })`	月度轮回历史记录	❌
`useMCCHistory({ tx_type, page })`	MCC 综合历史（mining/buyback/transfer 筛选）	✅

MCD 详情

Hook	说明	需登录
`useMCDTransactions({ page, type })`	MCD 交易记录（分页 + 类型筛选）	✅
`useMCDRewards({ page, startDate, endDate })`	MCD 每日奖励（分页 + 日期筛选）	✅

领地管理

Hook	说明	需登录
`useTerritories({ unitType, parentId, page })`	领地列表（类型/层级筛选）	✅
`useTerritorySummary()`	领地汇总统计（总数/成员/金库）	✅
`useTerritoryDetail(id)`	领地详情	✅
`useTerritoryStats(id)`	领地统计（成员/容量/金库）	✅
`useTerritoryMembers(id, { page })`	领地成员列表（分页）	✅
`useTerritoryIncome(id, period)`	领地收入图表（7d/30d/90d）	✅
`useTerritoryKPI(id)`	领地 KPI 历史	✅
`useTerritoryRanking(id, { page })`	领地成员 MCD 排名	✅

社区投票

Hook	说明	需登录
`useProposals({ status, page })`	提案列表（状态筛选）	✅
`useProposalDetail(id)`	提案详情 + 投票结果	✅
`useVotePower()`	用户投票权	✅

拍卖市场

Hook	说明	需登录
`useAuctions()`	活跃拍卖列表	❌
`useAuctionDetail(id)`	拍卖详情（竞价历史）	❌
`useMyBids()`	我的竞价记录	✅
`useAuctionHistory({ page })`	拍卖历史记录	❌

领地 & 生态

Hook	说明	需登录
`useUserLevel()`	用户等级 + 升级进度	✅
`useTerritoryNFTs()`	用户领地 NFT 列表	❌
`useOrganizations()`	用户组织列表	❌
`useTechTree()`	科技树配置 + 用户进度 + 加成	部分

聚合 & 图表

Hook	说明	需登录
`usePriceHistory()`	MCC 价格走势（1D/7D/30D）	❌
`useDashboardSummary()`	总览页聚合数据	部分
`useUserStats()`	用户等级分布统计	❌

操作 Hooks（写操作/交互）

Hook	说明	需登录
`useMiningAction()`	挖矿执行：`{ createRequest, confirm, loading, error }`	✅
`usePublicMining()`	公开挖矿请求（无需用户认证，需 Provider）：`{ createRequest, verify, loading, error }`	❌
`useBuybackAction()`	回购记录：`{ record, loading, error }`	✅
`useTerritoryUpdate()`	领地编辑：`{ update, updateName, loading, error }`	✅
`useAuctionBid()`	拍卖出价：`{ placeBid, loading, error }`	✅
`useAuctionCancel()`	取消竞价：`{ prepareCancelBid, loading, error }`	✅
`useVoteAction()`	投票操作：`{ createProposal, castVote, loading, error }`	✅
`useCreateAuction()`	创建拍卖：`{ createAuction, loading, error }`	✅
`useAuctionRefund()`	退还保证金：`{ refund, loading, error }`	✅
`useAuctionEnd()`	管理员结束拍卖：`{ endAuction, loading, error }`	✅
`useProposalSettle()`	管理员结算提案：`{ settle, loading, error }`	✅
`useNotificationAction()`	通知操作：`{ markRead, markAllRead, loading, error }`	✅
`useTerritoryNFTMint()`	管理员铸造 NFT：`{ mint, loading, error }`	✅
`useTerritoryNFTAction()`	NFT 转移/销毁：`{ transferNFT, burnNFT, loading, error }`	✅

Solana 钱包 & 完整流程

Hook	说明	需登录
`useSolanaWallet()`	Phantom 钱包：`{ connect, disconnect, signTransaction, signAllTransactions, publicKey, connected }`	❌
`useMiningFlow()`	铸造完整流程（状态机）：`{ step, startMining, confirmMining, reset }`	✅
`useBuybackFlow()`	回购完整流程（状态机）：`{ step, getQuote, executeBuyback, reset }`	✅

新增数据 Hooks (v1.0.5+)

Hook	说明	需登录
`useMarketData()`	市场概览数据	❌
`useOrganizationTree()`	组织层级树形结构	❌
`useOrganizationSummary()`	组织全局统计	❌
`useMultiWalletBalance()`	多钱包余额聚合	✅
`useAuctionBids(id)`	特定拍卖出价列表	❌
`useStationJoin()`	加入空间站	✅
`useStationLeave()`	离开空间站	✅
`useStationQueue()`	空间站分配队列	✅
`useTechTreeAction()`	科技树解锁/升级	✅
`useTechTreeConfig()`	科技树节点配置	❌
`useTechTreeBonus()`	科技树加成	✅
`useTerritoryNFTCollection()`	领地 NFT 集合	❌
`useTerritoryNameStatus(id)`	名称修改冷却	✅
`useTerritoryDistributionPlan(id)`	分配方案查询/设置	✅
`useTerritoryDetailedStats(id)`	领地详细统计(含 KPI+科技加成)	✅
`useManagerIncome()`	政务官分成收入	✅
`useTeamCustody()`	代管钱包汇总	✅
`useNotifications()`	用户通知列表	✅
`useFragmentVaults()`	碎片金库列表	❌
`useFragmentVaultDetail(id)`	碎片金库详情	❌
`useLendingPool()`	借贷池信息	❌
`useLendingPosition(wallet)`	用户借贷仓位	✅
`useMCCHolders()`	MCC 持有者列表	❌
`usePlatformStats()`	平台统计	❌
`useDashboardMiningHistory()`	全局铸造趋势	❌
`useDashboardUserStats()`	Dashboard 用户统计	❌
`useDashboardTerritoryStats()`	Dashboard 领地统计	❌
`useAuctionConfig()`	拍卖全局配置	❌
`useFragmentConfig()`	碎片系统配置	❌
`useLendingStats()`	借贷统计	❌
`useMCCMiningHistory(days?)`	MCC 铸造历史(按天)	❌

通用

Hook	说明
`useApiQuery({ path, requireAuth?, refetchInterval?, skip? })`	通用 API 查询，支持认证 + 轮询 + 条件跳过

所有 Hook 支持覆盖默认刷新间隔：useMCCPrice({ refetchInterval: 10_000 })

菜单嵌入（可选）

tsx

import { MicrocosmMenuSection } from '@microcosmmoney/portal-react'

<MicrocosmMenuSection
  basePath="/v2"
  currentPath={pathname}
  onNavigate={(path) => router.push(path)}
/>

菜单内容：

组	菜单项	路径
Overview	Dashboard	`/user-system/dashboard`
Blockchain	Mining	`/mcc/mining`
	Reincarnation	`/mcc/reincarnation`
	Wallet	`/mcc/wallet`
	MCD Credits	`/mcc/mcd`
Web3 OS	Auctions	`/mcc/auctions`
	Territories	`/user-system/territory`
	Voting	`/mcc/voting`
	Organization	`/user-system/organization`

增强 Props：onItemClick / filterItems / extraItems / badge / renderItem / renderSectionHeader

导出菜单组：dashboardMenu / blockchainMenu / web3OsMenu / microcosmMenuGroups

UI 组件 (`@microcosmmoney/portal-react`)

基础组件

组件	说明
`TerminalCard`	卡片容器（macOS 标题栏风格）
`StatBox`	统计数值展示盒（label + value + unit）
`TerminalCommand`	终端命令行 (`$ command`)
`TerminalPageHeader`	页面标题（command + title + description）
`TerminalLoading`	加载状态（旋转动画）
`TerminalError`	错误提示（红色 error 前缀）
`TerminalEmpty`	空状态占位
`TerminalBadge`	状态徽章（5 种 variant）
`TerminalDataRow`	键值对数据行
`TerminalProgress`	进度条（百分比 + 自定义颜色）

交互组件

组件	说明
`TerminalTable<T>`	暗色数据表格（泛型列定义）
`TerminalTabs`	标签页切换（受控/非受控）
`TerminalDialog`	模态对话框（ESC 关闭 + macOS 标题栏）
`TerminalInput`	终端风格输入框（prefix + suffix + error）
`TerminalTooltip`	悬浮提示（top/bottom/left/right）
`TerminalCountdown`	倒计时组件（支持 full/compact 格式）

业务组件

组件	说明
`TerritoryCard`	领地信息卡片（类型 + 成员 + 进度条）
`MiningProgressBar`	铸造进度条（减半标记 + 统计）
`VoteResultBar`	投票结果可视化（多选项 + 百分比）
`KPIRadialChart`	KPI 径向图（SVG 圆环进度）

类型系统

新增 UnitType = 'station' | 'matrix' | 'sector' | 'system' 统一类型，用于 Territory / Organization / Auction / AuctionCreateInput 等接口。

路由守卫

tsx

// HOC 方式
import { withAuth } from '@microcosmmoney/auth-react'
export default withAuth(DashboardPage)

// 组件方式
import { RequireRole } from '@microcosmmoney/auth-react'
<RequireRole roles={['admin']} fallback={<div>无权限</div>}>
  <AdminPanel />
</RequireRole>

环境变量