工程化
工程化总览
仓库的开发约定、工具链、自动化脚本与 CI 全景
工程化的目标
| 目标 | 手段 |
|---|---|
| 一致性 | 共享 tsconfig / oxlintrc / oxfmtrc，全仓库一份配置 |
| 高速反馈 | Oxlint / Oxfmt（Rust）替代 ESLint / Prettier，Vitest 替代 Jest |
| 自动化 | sa 脚手架处理变更日志、发版、模板同步 |
| 可追溯 | 提交规范 + changelog 自动生成 |
| 增量构建 | Turborepo 全任务编排 + 缓存 |
| 类型安全 | strict + verbatimModuleSyntax + 全局类型增强 |
工具栈一览
| 类别 | 工具 | 版本 | 配置 |
|---|---|---|---|
| 包管理 | pnpm | 10.4.1 | pnpm-workspace.yaml |
| 任务编排 | Turborepo | 2.x | turbo.json |
| 编译 | TypeScript | 6.x | internal/tsconfig |
| Web 构建 | Vite | 8.x | apps/admin/vite.config.ts |
| Native 构建 | Expo | — | apps/app 等 |
| 库构建 | tsdown | 0.18 | 各包 tsdown.config.ts |
| Lint | Oxlint | 1.60 | .oxlintrc.json |
| Format | Oxfmt | 0.45 | .oxfmtrc.json |
| 单测 | Vitest | 4.x | @skyroc/config/vitest |
| 组件 / 集成 | Testing Library | 16.x | apps/admin |
| Mock | MSW | 2.x | 已装未启 |
| Git 钩子 | simple-git-hooks | 2.x | 待启用 |
| 自动化 | @skyroc/scripts (sa) | 1.0 | soybean.config.ts |
| CI | GitHub Actions | — | .github/workflows |
工程化文档地图
| 主题 | 文档 |
|---|---|
| 项目约定（命名、组件风格、提交规范） | 开发约定 |
| TypeScript 策略与全局类型 | TypeScript 配置 |
| 构建体系（Turborepo + Vite + tsdown） | 构建体系 |
| package.json exports / 子入口策略 | Exports 策略 |
| 如何新建一个包 | 新建包流程 |
| Lint / Format | Lint 与格式化 |
| 测试理念与方案 | 测试 |
| 提交 / 发版 | Git 提交与发版 |
| CI / CD | CI |
顶层命令
| 命令 | 说明 |
|---|---|
pnpm dev | Turborepo 启动所有 dev 任务 |
pnpm build | 构建所有包 |
pnpm lint | Oxlint 检查所有包 |
pnpm format | Oxfmt 格式化全仓库 |
pnpm format:check | 仅检查格式，CI 用 |
pnpm typecheck | 所有包 tsc --noEmit |
pnpm test | 所有包 vitest |
pnpm test:e2e | Playwright 端到端 |
pnpm test:watch | Vitest watch 模式 |
pnpm test:ui | Vitest UI |
pnpm create:admin | 基于模板新建 admin 应用 |
pnpm sync:admin-template | 把当前 admin 同步到 @skyroc/scripts/templates |
pnpm check:admin-template | 检查 admin 是否与模板一致 |
关键设计
| 约定 | 含义 |
|---|---|
| catalog 集中版本 | 在 pnpm-workspace.yaml 的 catalogs: 集中管理依赖版本，子包 "react": "catalog:core" |
| Internal 配置包 | tsconfig / oxlintrc / vitest 等以独立包形式共享 |
| 平台优先目录 | packages/web、packages/native、packages/miniapp、packages/shared 分层 |
| Adapter Pattern | 跨平台核心包依赖抽象适配器，由 web/RN 各自实现 |
| Strict TS | 全仓库 strict + verbatimModuleSyntax + noUncheckedIndexedAccess |
| No useCallback | 项目代码风格禁用 useCallback，详见 开发约定 |