# bx2app_app

**Repository Path**: webtm/bx2app_app

## Basic Information

- **Project Name**: bx2app_app
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-02
- **Last Updated**: 2026-02-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 公司报销系统

基于 NestJS 开发的公司报销服务端系统，支持文件上传和多级审批流程。

## 功能特性

- **用户管理**：创建、查询、更新、删除用户
- **用户认证**：登录、注册、JWT认证
- **指纹登录**：支持通过生物识别（如指纹、面部识别）进行登录，提升用户体验和安全性
- **报销单管理**：创建、查询、更新、删除报销单
- **报销明细管理**：支持多种报销类型
- **文件上传**：支持上传发票、收据等凭证，关联到报销单和报销项
- **多级审批流程**：支持根据报销单金额和类型分配审批流程，包括审批记录和流转
- **审批管理**：审批、拒绝、标记已支付
- **状态流转**：待审批 -> 已批准/已拒绝 -> 已支付
- **部门管理**：创建、查询、更新、删除部门，支持部门树结构
- **项目管理**：创建、查询、更新、删除项目，技术部报销必须绑定项目

## 技术栈

- **核心框架**：NestJS
- **数据库**：MySQL + TypeORM
- **认证**：JWT + Passport
- **密码加密**：bcrypt
- **数据验证**：class-validator + class-transformer
- **文件上传**：multer
- **其他**：reflect-metadata, rxjs, uuid

## 项目结构

```
bx-backend/
├── src/
│   ├── entities/           # 数据实体
│   │   ├── user.entity.ts
│   │   ├── expense.entity.ts
│   │   ├── expense-item.entity.ts
│   │   ├── file.entity.ts
│   │   ├── approval-flow.entity.ts
│   │   ├── approval-step.entity.ts
│   │   ├── approval-record.entity.ts
│   │   ├── device-credential.entity.ts
│   │   ├── department.entity.ts
│   │   └── project.entity.ts
│   ├── auth/               # 认证模块
│   │   ├── dto/
│   │   ├── strategies/
│   │   ├── auth.controller.ts
│   │   ├── auth.service.ts
│   │   └── auth.module.ts
│   ├── users/              # 用户模块
│   │   ├── dto/
│   │   ├── users.controller.ts
│   │   ├── users.service.ts
│   │   └── users.module.ts
│   ├── expenses/           # 报销单模块
│   │   ├── dto/
│   │   ├── expenses.controller.ts
│   │   ├── expenses.service.ts
│   │   └── expenses.module.ts
│   ├── approvals/          # 审批模块
│   │   ├── approvals.controller.ts
│   │   ├── approvals.service.ts
│   │   └── approvals.module.ts
│   ├── files/              # 文件管理模块
│   │   ├── files.controller.ts
│   │   ├── files.service.ts
│   │   └── files.module.ts
│   ├── approval-flows/     # 审批流程管理模块
│   │   ├── approval-flows.controller.ts
│   │   ├── approval-flows.service.ts
│   │   └── approval-flows.module.ts
│   ├── departments/        # 部门管理模块
│   │   ├── dto/
│   │   ├── departments.controller.ts
│   │   ├── departments.service.ts
│   │   └── departments.module.ts
│   ├── projects/           # 项目管理模块
│   │   ├── dto/
│   │   ├── projects.controller.ts
│   │   ├── projects.service.ts
│   │   └── projects.module.ts
│   ├── config/             # 配置文件
│   │   ├── database.config.ts
│   │   └── file.config.ts
│   ├── app.module.ts
│   └── main.ts
├── .env                    # 环境变量配置
├── .env.example            # 环境变量示例
├── package.json
└── README.md
```

## 快速开始

### 1. 安装依赖

```bash
cd bx-backend
pnpm install
```

### 2. 配置数据库

复制 `.env.example` 为 `.env` 并修改数据库配置：

```env
DB_HOST=localhost
DB_PORT=3306
DB_USERNAME=root
DB_PASSWORD=your_password
DB_DATABASE=expense_system
NODE_ENV=development
PORT=3000
```

### 3. 启动服务

```bash
# 开发模式
pnpm run start:dev

# 生产模式
pnpm run build
pnpm run start:prod
```

## API 接口

### 认证管理

- `POST /auth/login` - 用户登录
- `POST /auth/register` - 用户注册
- `POST /auth/device/register` - 注册设备，启用指纹登录
- `POST /auth/fingerprint/login` - 指纹登录
- `POST /auth/device/refresh` - 刷新设备凭证令牌
- `GET /auth/devices` - 获取用户已注册设备列表
- `DELETE /auth/devices/:id` - 移除已注册设备

### 用户管理

- `POST /users` - 创建用户
- `GET /users` - 获取所有用户（需要认证）
- `GET /users/:id` - 获取指定用户（需要认证）
- `PATCH /users/:id` - 更新用户信息（需要认证）
- `DELETE /users/:id` - 删除用户（需要认证）

### 报销单管理

- `POST /expenses` - 创建报销单（需要认证）
- `GET /expenses` - 获取所有报销单（可按 userId 筛选，需要认证）
- `GET /expenses/:id` - 获取指定报销单（需要认证）
- `PATCH /expenses/:id` - 更新报销单（需要认证）
- `DELETE /expenses/:id` - 删除报销单（需要认证）

### 审批管理

- `GET /approvals/pending` - 获取待审批报销单（需要认证）
- `GET /approvals/approved` - 获取已批准报销单（需要认证）
- `POST /approvals/:id/approve` - 审批报销单（批准/拒绝，需要认证）
- `POST /approvals/:id/paid` - 标记报销单为已支付（需要认证）

### 文件管理

- `POST /files/expense/:expenseId` - 上传文件到报销单（需要认证）
- `POST /files/item/:itemId` - 上传文件到报销项（需要认证）
- `GET /files/:id/download` - 下载文件（需要认证）
- `DELETE /files/:id` - 删除文件（需要认证）

### 审批流程管理

- `POST /approval-flows` - 创建审批流程（需要认证）
- `GET /approval-flows` - 获取所有审批流程（需要认证）
- `GET /approval-flows/:id` - 获取指定审批流程（需要认证）
- `PUT /approval-flows/:id` - 更新审批流程（需要认证）
- `DELETE /approval-flows/:id` - 删除审批流程（需要认证）
- `POST /approval-flows/:flowId/steps` - 添加审批步骤（需要认证）
- `PUT /approval-flows/:flowId/steps/:stepId` - 更新审批步骤（需要认证）
- `DELETE /approval-flows/:flowId/steps/:stepId` - 删除审批步骤（需要认证）

### 部门管理

- `POST /departments` - 创建部门（需要认证）
- `GET /departments` - 获取所有部门（需要认证）
- `GET /departments/tree` - 获取部门树结构（需要认证）
- `GET /departments/:id` - 获取指定部门（需要认证）
- `PATCH /departments/:id` - 更新部门信息（需要认证）
- `DELETE /departments/:id` - 删除部门（需要认证）

### 项目管理

- `POST /projects` - 创建项目（需要认证）
- `GET /projects` - 获取所有项目（需要认证）
- `GET /projects/:id` - 获取指定项目（需要认证）
- `PATCH /projects/:id` - 更新项目信息（需要认证）
- `DELETE /projects/:id` - 删除项目（需要认证）

## 数据模型

### User（用户）

- `id`: 用户ID
- `username`: 用户名（唯一）
- `name`: 姓名
- `email`: 邮箱
- `password`: 密码
- `phone`: 电话
- `department`: 部门
- `role`: 角色（admin/manager/employee）
- `createdAt`: 创建时间
- `updatedAt`: 更新时间

### Expense（报销单）

- `id`: 报销单ID
- `userId`: 用户ID
- `totalAmount`: 总金额
- `description`: 描述
- `status`: 状态（pending/approved/rejected/paid）
- `approverId`: 审批人ID
- `remark`: 备注
- `approvalFlowId`: 审批流程ID
- `currentStep`: 当前审批步骤
- `createdAt`: 创建时间
- `updatedAt`: 更新时间

### ExpenseItem（报销明细）

- `id`: 明细ID
- `expenseId`: 报销单ID
- `type`: 类型（travel/meal/transport/office/other）
- `description`: 描述
- `amount`: 金额
- `expenseDate`: 费用日期
- `remark`: 备注

### File（文件）

- `id`: 文件ID
- `expenseId`: 报销单ID（可选）
- `expenseItemId`: 报销项ID（可选）
- `fileName`: 文件名
- `filePath`: 文件路径
- `fileType`: 文件类型（invoice/receipt/other）
- `mimeType`: MIME类型
- `fileSize`: 文件大小（字节）
- `description`: 描述
- `createdAt`: 创建时间

### ApprovalFlow（审批流程）

- `id`: 流程ID
- `name`: 流程名称
- `type`: 流程类型（default/high_amount/custom）
- `minAmount`: 最小金额（可选）
- `maxAmount`: 最大金额（可选）
- `department`: 部门（可选）
- `description`: 描述（可选）
- `isActive`: 是否激活
- `createdAt`: 创建时间
- `updatedAt`: 更新时间

### ApprovalStep（审批步骤）

- `id`: 步骤ID
- `flowId`: 流程ID
- `type`: 步骤类型（manager/finance/director）
- `role`: 审批角色
- `approverId`: 审批人ID（可选）
- `order`: 步骤顺序
- `description`: 描述（可选）

### ApprovalRecord（审批记录）

- `id`: 记录ID
- `expenseId`: 报销单ID
- `stepId`: 步骤ID
- `approverId`: 审批人ID
- `action`: 操作（pending/approved/rejected）
- `remark`: 备注
- `createdAt`: 创建时间

### DeviceCredential（设备凭证）

- `id`: 凭证ID
- `userId`: 用户ID
- `deviceId`: 设备唯一标识
- `deviceName`: 设备名称
- `platform`: 平台类型（iOS/Android）
- `credentialToken`: 凭证令牌
- `refreshToken`: 刷新令牌
- `isActive`: 是否激活
- `createdAt`: 创建时间
- `updatedAt`: 更新时间

### Department（部门）

- `id`: 部门ID
- `name`: 部门名称
- `code`: 部门编码
- `parentId`: 父部门ID
- `createdAt`: 创建时间
- `updatedAt`: 更新时间

### Project（项目）

- `id`: 项目ID
- `name`: 项目名称
- `code`: 项目编码
- `description`: 项目描述
- `startDate`: 开始时间
- `isActive`: 是否激活
- `createdAt`: 创建时间
- `updatedAt`: 更新时间

## 功能说明

### 文件上传

- 支持上传发票、收据等凭证文件
- 文件会自动保存到服务器的 `uploads` 目录
- 上传的文件会关联到报销单或报销项
- 支持文件下载和删除操作

### 多级审批流程

- 系统会根据报销单的金额和类型自动分配审批流程
- 审批流程支持多个审批步骤，按照顺序依次审批
- 每个审批步骤可以指定审批人或审批角色
- 审批记录会被保存，方便后续查询和审计
- 审批状态会实时更新，支持审批流转

### 指纹登录

- **工作原理**：App 端使用系统原生生物识别 API（如 iOS 的 Touch ID/Face ID，Android 的 Biometric API）完成本地指纹验证，验证成功后生成凭证，后端验证凭证有效性
- **使用流程**：
  1. 首次使用：用户使用密码登录，然后注册设备启用指纹登录
  2. 后续登录：App 调用系统生物识别 API 验证指纹，验证成功后发送登录请求，后端验证凭证并返回 JWT 令牌
- **安全措施**：
  - 生物数据不离开设备，仅在本地验证
  - 凭证令牌使用 bcrypt 加密存储
  - 使用 HTTPS 确保数据传输安全
  - 支持设备管理，用户可以查看和禁用已注册设备

## 后期扩展建议

1. **角色权限**：基于角色的访问控制（RBAC），细化不同角色的权限
2. **报表统计**：报销统计、部门支出分析等
3. **消息通知**：邮件、站内消息通知
4. **日志审计**：操作日志记录和审计
5. **缓存优化**：使用 Redis 缓存热点数据
6. **API 文档**：集成 Swagger 自动生成 API 文档
7. **单元测试**：完善单元测试和集成测试
8. **多语言支持**：国际化（i18n）支持
9. **移动端适配**：提供移动端友好的 API 接口
10. **第三方集成**：集成企业微信、钉钉等办公系统

## 许可证

UNLICENSED


今日TODO:

- [ ] 上传文件 图片 pdf 
- [ ] 下载文件 img pdf 
- [ ] 地图定位
- [ ] 新建报销 提交
- [ ] 审核
- [ ] 审核 签字