nxxmdata/bank-backend/README.md

# 银行管理后台系统

一个基于 Node.js 和 Express 的现代化银行管理后台系统，提供完整的用户管理、账户管理、交易管理等功能。

## 🚀 功能特性

### 核心功能
- **用户管理**: 用户注册、登录、权限管理
- **账户管理**: 账户创建、状态管理、余额查询
- **交易管理**: 存款、取款、转账、交易记录查询
- **权限控制**: 基于角色的访问控制(RBAC)
- **安全防护**: JWT认证、密码加密、请求限流

### 技术特性
- **RESTful API**: 标准化的API设计
- **数据库ORM**: Sequelize ORM支持
- **API文档**: Swagger自动生成文档
- **日志系统**: Winston日志管理
- **安全中间件**: 多层安全防护
- **错误处理**: 完善的错误处理机制

## 🛠 技术栈

- **运行环境**: Node.js 16+
- **Web框架**: Express.js 4.18+
- **数据库**: MySQL 8.0+
- **ORM**: Sequelize 6.35+
- **认证**: JWT (jsonwebtoken)
- **密码加密**: bcryptjs
- **API文档**: Swagger
- **日志**: Winston
- **安全**: Helmet, CORS, Rate Limiting

## 📦 安装部署

### 环境要求
- Node.js 16.0+
- MySQL 8.0+
- npm 8.0+

### 安装步骤

1. **克隆项目**
```bash
git clone <repository-url>
cd bank-backend
```

2. **安装依赖**
```bash
npm install
```

3. **环境配置**
```bash
cp env.example .env
# 编辑 .env 文件，配置数据库连接等信息
```

4. **数据库初始化**
手动或脚本方式，避免自动建表：
```powershell
# PowerShell（推荐，自动生成管理员bcrypt哈希）
cd scripts
./setup-bank-db.ps1 -AdminPlain 'Admin123456'
```
或在数据库手工执行：
```sql
-- 1) 执行建表
-- scripts/create-bank-schema.sql
-- 2) 执行测试数据（将 REPLACE_ADMIN_BCRYPT 替换为真实 bcrypt 哈希）
-- scripts/seed-bank-demo.sql
```

5. **启动服务**
```bash
# 开发环境
npm run dev

# 生产环境
npm start
```

## ⚙️ 环境配置

创建 `.env` 文件并配置以下环境变量：

```env
# 服务器配置
PORT=5351
NODE_ENV=development

# 数据库配置
DB_HOST=localhost
DB_PORT=3306
DB_NAME=bank_management
DB_USER=root
DB_PASSWORD=your_password
DB_DIALECT=mysql

# JWT配置
JWT_SECRET=your_jwt_secret_key_here
JWT_EXPIRES_IN=24h

# 安全配置
BCRYPT_ROUNDS=10
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX_REQUESTS=100

# 银行系统配置
BANK_CODE=001
BANK_NAME=示例银行
CURRENCY=CNY
TIMEZONE=Asia/Shanghai
```

## 📚 API文档

启动服务后，访问以下地址查看API文档：
- 开发环境: http://localhost:5351/api-docs
- 生产环境: https://your-domain.com/api-docs

## 🗄️ 数据库设计

### 主要数据表

#### 用户表 (users)
- 用户基本信息
- 身份认证信息
- 角色关联

#### 角色表 (roles)
- 角色定义
- 权限级别
- 系统角色标识

#### 账户表 (accounts)
- 账户基本信息
- 余额管理
- 账户状态

#### 交易记录表 (transactions)
- 交易详情
- 余额变化
- 交易状态

## 🔐 安全特性

### 认证与授权
- JWT令牌认证
- 基于角色的权限控制
- 会话超时管理
- 登录失败锁定

### 数据安全
- 密码bcrypt加密
- SQL注入防护
- XSS攻击防护
- 请求频率限制

### 传输安全
- HTTPS支持
- CORS配置
- 安全头部设置
- 输入数据验证

## 📊 系统监控

### 健康检查
```bash
curl http://localhost:5351/health
```

### 日志查看
```bash
# 查看错误日志
tail -f logs/error.log

# 查看所有日志
tail -f logs/combined.log
```

## 🧪 测试

```bash
# 运行测试
npm test

# 测试覆盖率
npm run test:coverage

# 监听模式
npm run test:watch
```

## 📝 开发指南

### 项目结构
```
bank-backend/
├── config/          # 配置文件
├── controllers/     # 控制器
├── models/          # 数据模型
├── routes/          # 路由定义
├── middleware/      # 中间件
├── utils/           # 工具类
├── services/        # 业务服务
├── migrations/      # 数据库迁移
├── seeds/           # 种子数据
├── logs/            # 日志文件
├── uploads/         # 上传文件
└── scripts/         # 脚本文件
```

### 代码规范
- 使用ESLint进行代码检查
- 遵循RESTful API设计规范
- 统一的错误处理格式
- 完整的API文档注释

### 开发命令
```bash
# 代码检查
npm run lint

# 代码修复
npm run lint:fix

# 数据库连接测试
npm run test-connection

# 清理临时文件
npm run clean
```

## 🚀 部署指南

### Docker部署
```bash
# 构建镜像
docker build -t bank-backend .

# 运行容器
docker run -p 5351:5351 bank-backend
```

### PM2部署
```bash
# 安装PM2
npm install -g pm2

# 启动应用
pm2 start server.js --name bank-backend

# 查看状态
pm2 status
```

## 🤝 贡献指南

1. Fork 项目
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开 Pull Request

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 📞 联系方式

- 项目维护者: 银行开发团队
- 邮箱: dev@bank.com
- 项目地址: https://github.com/bank-management/bank-backend

## 🙏 致谢

感谢所有为这个项目做出贡献的开发者和开源社区。

---

**注意**: 这是一个演示项目，请勿在生产环境中使用默认的密码和密钥。