项目简介与设计理念

定位

Skyroc Admin 是一个工程化的后台管理系统脚手架，但它的野心不止于「一个能跑的 admin」。它的目标是：

把后台系统里反复出现的能力（请求、状态、主题、布局、菜单、权限、i18n、通知…）抽象成独立、可复用、可跨端的包，应用层只负责装配与业务。

这意味着当你打开 apps/admin，会发现它出奇地「薄」——大量逻辑并不在应用里，而在 @skyroc/* 包中。这是刻意的设计。

三条核心原则

1. 分层（Layering）

包之间存在严格的依赖层级：类型层 → 基础设施层 → 平台能力层 → 应用层。上层可以依赖下层，反之与同层互相依赖都被禁止。这保证了：

底层包（如 @skyroc/types、@skyroc/utils）稳定、零或极轻依赖；
重构上层不会波及下层；
任何一个包都能被单独理解、测试、发布。

详见包分层与依赖方向。

2. 平台优先（Platform-first）

packages/ 的顶层目录按平台切分，而不是按功能：

packages/
├── @core/      # 跨端运行时基础（不绑定具体平台）
├── shared/     # 跨端纯类型 / 设计 token（零或极轻依赖）
├── hooks/      # 跨端 React hooks
├── web/        # ← Web 端一整棵（UI / 主题 / 布局 / vite…）
├── native/     # ← React Native 端（预留）
└── miniapp/    # ← 小程序端（预留）

原因：每个平台的 peerDependencies 完全不同（antd / nativewind / Taro），与其强行抽象一个「通用 UI」，不如让平台目录各自完整。真正跨端共享的只有 token 与类型，放在 shared/ 的薄包里就够了。

3. 适配器解耦（Adapter Pattern）

基础设施包不直接依赖具体 UI / 路由 / 认证实现，而是定义适配器接口，由应用注入。最典型的是 @skyroc/service：它定义了 RequestAdapter（包含 token、刷新、导航、提示等能力），应用通过实现这个接口把 antd 的 message、TanStack Router 的导航接进来。这样同一套请求基础设施可以同时服务 Web 与 Native。

设计哲学（来自仓库规范）

项目对 React 组件代码有一套强制工作流（并非建议）：

组件必须是箭头函数 + PascalCase；
props 必须定义独立 interface，且在函数体第一行解构，不在参数上解构；
禁用 useCallback；useMemo 仅用于「派生值」或「昂贵计算」；
useState 只放影响渲染的状态，useRef 放命令式/可变值；
useEffect 必须有明确意图（生命周期 / 外部系统同步 / DOM 集成）。

完整规则见 React 编码规范。

适合谁

想要一套可生长的后台基础设施，而不是一次性模板；
需要在多端复用同一套业务逻辑与设计系统；
重视类型安全、工程纪律与 AI 协作下的可维护性（测试即契约，见测试）。