# skeleton

**Repository Path**: zfworkspace/skeleton

## Basic Information

- **Project Name**: skeleton
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-20
- **Last Updated**: 2026-07-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 企业后台管理模板

这是一个基于 shadcn/ui 的 AI-first 企业后台工程底座。项目不仅提供后台界面，还通过架构、规范、参考模块和自动检查，为后续 AI 持续开发提供稳定路径。

## 当前状态

当前模板已达到 `1.0.1` 稳定基线，包含基础工程、shadcn/ui 设计系统、可持久化的运行时品牌色、官方 Sidebar 后台外壳、本地页面注册表、静态/远程双模式层级导航、权限感知的动态默认页、全局搜索、工作台页签、图表工作台、身份绑定状态清理、项目级访问控制与 API 协议适配基础设施、高频表格工作流，以及用户、部门、岗位、角色权限、数据字典和系统参数六类可裁剪参考模块。通过 `VITE_PROJECT_PROFILE` 可选择 `core` 最小外壳或 `reference` 完整参考配置。访问策略与请求协议通过 `src/project` 适配，后端字段差异由领域 Mapper 隔离；当前字符串 RBAC、组织结构和参考接口不是新项目必须采用的模型。详细范围见 [建设路线图](docs/roadmap.md)。

## 环境要求

- Node.js 20.19.0 或更高版本
- pnpm 10.5.0 或更高版本

建议使用仓库内 `.nvmrc` 指定的 Node.js 版本。

## 快速开始

```bash
pnpm install
pnpm dev
```

默认开发地址由 Vite 输出。首次启动前无需准备后端服务，后续参考模块将通过 MSW 提供模拟接口。

## 常用命令

```bash
pnpm dev           # 启动开发服务器
pnpm build         # 类型检查并生成生产构建
pnpm bundle:check  # 检查生产 JavaScript 分包体积预算
pnpm format:check  # 检查代码格式
pnpm lint          # 执行静态检查
pnpm typecheck     # 执行 TypeScript 检查
pnpm test          # 执行单元与集成测试
pnpm test:e2e      # 执行真实浏览器端到端测试
pnpm test:e2e:core # 验证 core 最小配置的真实浏览器流程
pnpm api:generate  # 根据 OpenAPI 契约生成接口类型
pnpm api:check     # 检查生成类型是否与 OpenAPI 契约同步
pnpm msw:init      # 更新并压缩 MSW 工作线程
pnpm knip          # 检查未使用代码和依赖
pnpm check         # 执行当前阶段的完整质量检查
```

## 技术方向

- React、TypeScript、Vite 和 pnpm
- shadcn/ui、Tailwind CSS 和 Lucide
- React Router、TanStack Query 和 TanStack Table
- React Hook Form、Zod 和 Zustand
- OpenAPI 类型生成与统一请求客户端
- Vitest、Testing Library、MSW 和 Playwright

## 项目规范

开始修改代码前必须阅读：

- [AI 开发规范](AGENTS.md)
- [架构说明](docs/architecture.md)
- [核心、项目适配与参考业务边界](docs/decisions/0002-core-project-reference-boundary.md)
- [API 协议适配与领域 DTO 映射](docs/decisions/0003-backend-adaptation-boundary.md)
- [设计系统](docs/design-system.md)
- [2026-07 开源后台设计审查](docs/design-audit-2026-07.md)
- [开发约定](docs/development/conventions.md)
- [AI 开发流程](docs/development/ai-workflow.md)
- [导航与主题](docs/development/navigation-and-theme.md)
- [接口与模拟服务](docs/development/api-and-mocks.md)
- [真实接口与生产部署](docs/deployment.md)
- [认证与权限](docs/development/auth-and-permissions.md)
- [新增业务模块](docs/development/create-feature.md)
- [用户管理参考模块](docs/reference/user-management.md)
- [部门管理参考模块](docs/reference/department-management.md)
- [岗位管理参考模块](docs/reference/position-management.md)
- [角色管理参考模块](docs/reference/role-management.md)
- [数据字典参考模块](docs/reference/dictionary-management.md)
- [系统参数参考模块](docs/reference/system-parameter-management.md)
- [测试与质量门禁](docs/testing.md)

所有注释、日志和项目文档使用 UTF-8 编码的简体中文。核心逻辑、状态变化和异常路径必须通过统一日志模块记录。