使用指南

快速了解如何注册和使用 VBank

快速开始

角色指南

平台使用

常见问题

快速开始

环境要求

  • .NET 10.0 SDK - 后端开发框架
  • PostgreSQL 15+ - 数据库服务器
  • Node.js 18+ - 前端资源构建
  • Visual Studio 2022 或 VS Code (可选) - 开发工具

安装步骤

步骤 1: 克隆仓库

git clone https://github.com/your-repo/vbank.git
cd vbank

步骤 2: 配置数据库连接

编辑 VBank.WebHost/appsettings.json:

{
  "ConnectionStrings": {
    "DefaultConnection": "Host=localhost;Database=vbank;Username=postgres;Password=your_password"
  },
  "Jwt": {
    "SecretKey": "your-super-secret-key-change-this-in-production",
    "Issuer": "VBank",
    "Audience": "VBankUsers",
    "ExpiryMinutes": 60
  }
}

步骤 3: 运行数据库迁移

cd VBank.WebHost
dotnet ef database update

步骤 4: 构建前端资源

npm install
npm run build

步骤 5: 启动应用

dotnet run

访问 https://localhost:5001

首次使用

  1. 1
    注册银行用户

    使用 /api/auth/register 注册一个角色为 "Bank" 的用户

  2. 2
    创建银行

    登录后使用 /api/banks 创建一个银行实例

  3. 3
    注册存款人用户

    注册角色为 "Depositor" 的用户

  4. 4
    绑定银行与存款人

    存款人提交绑定申请,银行审批通过

  5. 5
    开始交易

    存款人可以进行存款、取款操作

API 文档

认证接口

POST /api/auth/register

用户注册

查看详情
请求体:
{
  "username": "string",
  "password": "string",
  "role": "Bank" | "Depositor"
}
响应:
{
  "success": true,
  "userId": "uuid",
  "message": "注册成功"
}
POST /api/auth/login

用户登录

查看详情
请求体:
{
  "username": "string",
  "password": "string"
}
响应:
{
  "token": "jwt-token-string",
  "expiresAt": "2026-02-16T12:00:00Z",
  "role": "Bank" | "Depositor"
}
POST /api/auth/wechat/login

微信OAuth登录

银行接口 (需要 Bank 角色)

POST /api/banks

创建银行

查看详情
请求头:
Authorization: Bearer {jwt-token}
请求体:
{
  "name": "工商银行",
  "description": "中国工商银行模拟分行"
}
POST /api/banks/{bankId}/bind

审批存款人绑定请求

PUT /api/banks/{bankId}/interest-rate

设置账户类型利率

查看详情
请求体:
{
  "accountType": "Demand",
  "annualRate": 0.10  // 10% 年利率
}
GET /api/banks/{bankId}/bindings

查看所有绑定的存款人

存款人接口 (需要 Depositor 角色)

GET /api/depositors/me/banks

查看已绑定的银行列表

GET /api/depositors/me/accounts

查看所有账户及余额

POST /api/depositors/me/accounts/{accountId}/deposit

存款操作

查看详情
请求体:
{
  "amount": 1000.00
}
响应:
{
  "success": true,
  "newBalance": 5000.00,
  "transactionId": "uuid",
  "timestamp": "2026-02-16T10:30:00Z"
}
POST /api/depositors/me/accounts/{accountId}/withdraw

取款操作

查看详情
请求体:
{
  "amount": 500.00
}
GET /api/depositors/me/transactions

查看交易历史

架构概览

系统架构

┌─────────────────┐          ┌─────────────────┐
│   Web Client    │          │   H5 Client     │
│  (Razor Pages)  │          │    (React)      │
└────────┬────────┘          └────────┬────────┘
         │                            │
         └────────────┬───────────────┘
                      │
              ┌───────▼────────┐
              │  ASP.NET Core  │
              │   Controllers  │
              └───────┬────────┘
                      │
         ┌────────────┼────────────┐
         │            │            │
    ┌────▼─────┐ ┌───▼────┐ ┌────▼────┐
    │  Auth    │ │ Bank   │ │Depositor│
    │ Service  │ │Service │ │ Service │
    └────┬─────┘ └───┬────┘ └────┬────┘
         │           │            │
         └───────────┼────────────┘
                     │
            ┌────────▼─────────┐
            │ Entity Framework │
            │      Core        │
            └────────┬─────────┘
                     │
            ┌────────▼─────────┐
            │   PostgreSQL     │
            │    Database      │
            └──────────────────┘

数据库架构

主要实体:

  • User: 用户基础信息(用户名、密码、角色)
  • Bank: 银行实体(名称、描述、创建时间)
  • DepositorProfile: 存款人档案
  • DemandAccount: 活期账户(余额、账户号)
  • BankDepositorBinding: 银行-存款人绑定关系
  • AccountTransaction: 交易记录
  • InterestRate: 利率配置
  • InterestSettlementLog: 利息结算日志
  • WeChatOpenIdBinding: 微信账号绑定

认证流程

用户登录
   ↓
验证用户名密码
   ↓
生成 JWT Token (包含 UserId, Role, 过期时间)
   ↓
返回 Token 给客户端
   ↓
客户端在后续请求中携带 Token
   ↓
服务端验证 Token 有效性
   ↓
提取用户信息和角色
   ↓
授权访问特定资源

交易处理流程

存款/取款请求
   ↓
验证用户身份与账户权限
   ↓
检查金额有效性 (取款检查余额)
   ↓
开启数据库事务
   ↓
更新账户余额
   ↓
创建交易记录
   ↓
提交事务
   ↓
返回新余额和交易ID

故障排除

数据库连接失败

问题: 无法连接到 PostgreSQL 数据库

解决方案:

  • 检查 PostgreSQL 服务是否正在运行
  • 验证 appsettings.json 中的连接字符串
  • 确认数据库用户名和密码正确
  • 检查防火墙设置

JWT Token 验证失败

问题: 401 Unauthorized 错误

解决方案:

  • 确认 Token 未过期
  • 检查 Authorization Header 格式: Bearer {token}
  • 验证 appsettings.json 中的 JWT 配置
  • 重新登录获取新 Token

取款失败 - 余额不足

问题: 取款操作被拒绝

解决方案:

  • 检查账户当前余额
  • 确认取款金额不超过可用余额
  • 查看是否有未结算的交易

前端资源未加载

问题: CSS/JS 文件 404

解决方案:

  • 运行 npm run build
  • 确认 wwwroot 目录包含编译后的文件
  • 检查 _Layout.cshtml 中的资源引用路径

常见问题 (FAQ)

利息是如何计算的?

利息按照年利率设置,但每日结算时会转换为日利率。计算公式:
日利率 = 年利率 ÷ 365
每日利息 = 账户余额 × 日利率

一个用户可以同时拥有银行和存款人角色吗?

目前系统设计为一个用户只能拥有一个角色。如需体验两种角色,请注册两个不同的账户。

如何重置密码?

当前版本暂不支持密码重置功能。如需重置,请联系系统管理员直接在数据库中修改。 未来版本将添加密码重置功能。

存款人如何解除与银行的绑定?

银行管理员可以将绑定状态设置为 Inactive 来停用绑定关系。存款人将无法继续对该银行的账户进行操作。

系统支持哪些货币?

当前版本默认使用人民币(CNY)作为唯一货币单位。系统架构支持扩展多货币,可在未来版本中添加。

微信登录需要什么配置?

需要在微信开放平台注册应用,获取 AppId 和 AppSecret,并在 appsettings.json 中配置。 详细步骤请参考微信开放平台文档。

还有疑问?

查看更多资源或联系我们

GitHub 仓库 关于项目 →