快速开始

> **文档版本**: v1.0.0
> **创建日期**: 2026-02-12
> **最后更新**: 2026-02-12
> **维护人**: 未来鸟FutureBird码巢企业服务引擎开发组
> **状态**: [最新]

> **搜索标签**: 快速开始, 新手指南, 入门, 安装, 配置, 启动, 部署, 开发环境
---

# 快速开始指南

欢迎使用企业管理数字化中台！本指南将帮助你快速启动和运行项目。

---

## &#128640; 快速启动（开发环境）

### 前置要求

确保你的系统已安装以下软件：
- ✅ Node.js 18.x 或更高版本
- ✅ pnpm 9.0.0 或更高版本
- ✅ PostgreSQL 12.x 或更高版本
- ✅ Git

### 1. 克隆代码

```bash
git clone <your-repository-url> payroll
cd payroll
```

### 2. 安装依赖

```bash
pnpm install
```

### 3. 配置环境变量

```bash
cp .env.example .env.local
```

编辑 `.env.local` 文件：

```bash
# 数据库配置
DATABASE_URL=postgresql://your_user:your_password@localhost:5432/payroll_dev?sslmode=disable

# 应用配置
NEXT_PUBLIC_APP_URL=http://localhost:5000
NODE_ENV=development

# JWT密钥（开发环境可以使用简单字符串）
JWT_SECRET=development-secret-key-change-in-production

# 管理员账号
ADMIN_USERNAME=admin
ADMIN_PASSWORD=admin123
ADMIN_EMAIL=admin@example.com
```

### 4. 初始化数据库

```bash
# 运行数据库迁移
pnpm db:migrate

# 导入初始数据
pnpm db:seed
```

### 5. 启动开发服务器

```bash
pnpm dev
```

访问 http://localhost:5000 查看应用。

### 6. 登录系统

使用以下账号登录：
- 用户名: `admin`
- 密码: `admin123`

⚠️ **重要**：生产环境请务必修改默认密码！

---

## &#128051; 使用 Docker 快速启动

### 1. 克隆代码

```bash
git clone <your-repository-url> payroll
cd payroll
```

### 2. 配置环境变量

```bash
cp .env.docker .env
```

编辑 `.env` 文件，修改数据库密码等配置。

### 3. 启动服务

```bash
docker compose up -d
```

### 4. 初始化数据库

```bash
docker exec -it payroll-app pnpm db:migrate
docker exec -it payroll-app pnpm db:seed
```

### 5. 访问应用

访问 http://localhost:5000

---

## &#128230; 项目结构

```
payroll/
├── src/                          # 源代码目录
│   ├── app/                      # Next.js App Router
│   │   ├── admin/                # 管理后台
│   │   │   ├── dashboard/        # 仪表盘
│   │   │   ├── employees/        # 人事管理
│   │   │   ├── payroll/          # 工资表管理
│   │   │   └── settings/         # 系统设置
│   │   ├── api/                  # API 路由
│   │   │   ├── v1/               # API v1
│   │   │   └── system/           # 系统 API
│   │   └── login/                # 登录页面
│   ├── components/               # React 组件
│   │   ├── ui/                   # UI 组件
│   │   └── features/             # 功能组件
│   ├── lib/                      # 工具库
│   ├── types/                    # TypeScript 类型
│   └── styles/                   # 样式文件
├── prisma/                       # Prisma ORM
│   └── schema.prisma             # 数据库模型
├── public/                       # 静态资源
├── scripts/                      # 脚本文件
├── docs/                         # 文档
└── tests/                        # 测试文件
```

---

## &#128295; 常用命令

### 开发命令

```bash
# 启动开发服务器
pnpm dev

# 构建生产版本
pnpm build

# 启动生产服务器
pnpm start

# 代码格式化
pnpm format

# 代码检查
pnpm lint

# 类型检查
pnpm type-check
```

### 数据库命令

```bash
# 运行数据库迁移
pnpm db:migrate

# 创建新迁移
pnpm db:migrate:dev

# 重置数据库
pnpm db:push

# 导入初始数据
pnpm db:seed

# 打开 Prisma Studio
pnpm db:studio
```

### 测试命令

```bash
# 运行所有测试
pnpm test

# 运行单元测试
pnpm test:unit

# 运行集成测试
pnpm test:integration

# 生成测试覆盖率
pnpm test:coverage
```

---

## &#128221; 核心功能

### 1. 仪表盘
- 实时数据概览
- 快捷操作入口
- 系统状态监控

### 2. 人事管理
- 员工信息管理
- 部门组织架构
- 员工权限管理

### 3. 工资表管理
- 工资表创建
- 工资条生成
- 工资发放记录
- Excel 导入导出

### 4. 集成配置
- 邮件服务配置
- 对象存储配置
- 短信服务配置
- 微信集成配置

### 5. 系统设置
- 基础信息配置
- 系统参数管理
- 操作日志查看
- 数据备份恢复

---

## &#128272; 安全配置

### 修改默认密码

1. 登录系统后，进入"系统设置" → "用户管理"
2. 找到管理员账号，点击"修改密码"
3. 输入新密码并保存

### 配置 JWT_SECRET

```bash
# 生成强随机密钥
openssl rand -base64 32
```

将生成的密钥复制到 `.env` 文件的 `JWT_SECRET` 中。

### 配置数据库连接

```bash
# 使用加密连接
DATABASE_URL=postgresql://user:password@host:5432/dbname?sslmode=require

# 使用证书验证
DATABASE_URL=postgresql://user:password@host:5432/dbname?sslmode=verify-full&sslrootcert=/path/to/cert.pem
```

---

## &#128218; 更多文档

- [部署指南](../02-部署指南/部署指南.md)
- [数据持久化指南](../05-数据库/README.md)
- [SMTP 配置指南](../09-配置指南/SMTP配置指南.md)
- [API 文档](../04-API文档/API接口文档.md)
- [服务器部署环境清单](../02-部署指南/部署指南.md)

---

## &#127384; 常见问题

### Q: 数据库连接失败
A: 检查 `.env` 文件中的 `DATABASE_URL` 配置，确保数据库服务已启动。

### Q: 无法启动开发服务器
A: 确保已安装 Node.js 18+ 和 pnpm，运行 `node --version` 和 `pnpm --version` 检查版本。

### Q: 迁移失败
A: 尝试重置数据库：
```bash
pnpm db:push
pnpm db:seed
```

### Q: 构建失败
A: 清理缓存后重新构建：
```bash
rm -rf .next node_modules
pnpm install
pnpm build
```

### Q: 邮件发送失败
A: 检查邮件配置，特别是 SMTP 授权码（163 和 QQ 邮箱需要使用授权码而非密码）。

---

## &#127919; 下一步

1. ✅ 完成系统初始化
2. ✅ 配置邮件服务
3. ✅ 配置对象存储
4. ✅ 创建第一个企业用户
5. ✅ 导入员工数据
6. ✅ 创建工资表
7. ✅ 测试工资发放流程

---

## &#128222; 获取帮助

如果遇到问题：
1. 查看 [常见问题](#-常见问题) 部分
2. 查看 [部署指南](../02-部署指南/部署指南.md)
3. 查看 [GitHub Issues](https://github.com/your-repo/payroll/issues)
4. 联系技术支持

---

祝使用愉快！&#127881;