nxxmdata/bank-backend/routes/transactions.js

const express = require('express');
const { verifyToken, requireRole } = require('../middleware/auth');
const { 
  validateAmount,
  validateAccountNumber,
  handleValidationErrors 
} = require('../middleware/security');
const router = express.Router();
const transactionController = require('../controllers/transactionController');

/**
 * @swagger
 * tags:
 *   name: Transactions
 *   description: 交易管理
 */

/**
 * @swagger
 * components:
 *   schemas:
 *     Transaction:
 *       type: object
 *       required:
 *         - account_id
 *         - transaction_type
 *         - amount
 *       properties:
 *         id:
 *           type: integer
 *           description: 交易ID
 *         transaction_number:
 *           type: string
 *           description: 交易流水号
 *         account_id:
 *           type: integer
 *           description: 账户ID
 *         transaction_type:
 *           type: string
 *           enum: [deposit, withdrawal, transfer_in, transfer_out, interest, fee, loan, repayment]
 *           description: 交易类型
 *         amount:
 *           type: integer
 *           description: 交易金额（分）
 *         balance_before:
 *           type: integer
 *           description: 交易前余额（分）
 *         balance_after:
 *           type: integer
 *           description: 交易后余额（分）
 *         counterparty_account:
 *           type: string
 *           description: 对方账户号
 *         counterparty_name:
 *           type: string
 *           description: 对方户名
 *         description:
 *           type: string
 *           description: 交易描述
 *         status:
 *           type: string
 *           enum: [pending, completed, failed, cancelled, reversed]
 *           description: 交易状态
 */

/**
 * @swagger
 * /api/transactions:
 *   get:
 *     summary: 获取交易记录列表
 *     tags: [Transactions]
 *     security:
 *       - bearerAuth: []
 *     parameters:
 *       - in: query
 *         name: page
 *         schema:
 *           type: integer
 *           default: 1
 *         description: 页码
 *       - in: query
 *         name: limit
 *         schema:
 *           type: integer
 *           default: 20
 *         description: 每页数量
 *       - in: query
 *         name: account_id
 *         schema:
 *           type: integer
 *         description: 账户ID（管理员）
 *       - in: query
 *         name: transaction_type
 *         schema:
 *           type: string
 *           enum: [deposit, withdrawal, transfer_in, transfer_out, interest, fee, loan, repayment]
 *         description: 交易类型
 *       - in: query
 *         name: status
 *         schema:
 *           type: string
 *           enum: [pending, completed, failed, cancelled, reversed]
 *         description: 交易状态
 *       - in: query
 *         name: start_date
 *         schema:
 *           type: string
 *           format: date
 *         description: 开始日期
 *       - in: query
 *         name: end_date
 *         schema:
 *           type: string
 *           format: date
 *         description: 结束日期
 *       - in: query
 *         name: amount_min
 *         schema:
 *           type: number
 *         description: 最小金额（元）
 *       - in: query
 *         name: amount_max
 *         schema:
 *           type: number
 *         description: 最大金额（元）
 *     responses:
 *       200:
 *         description: 获取成功
 *       401:
 *         description: 未授权
 */
router.get('/',
  verifyToken,
  transactionController.getTransactions
);

/**
 * @swagger
 * /api/transactions/{transactionId}:
 *   get:
 *     summary: 获取交易详情
 *     tags: [Transactions]
 *     security:
 *       - bearerAuth: []
 *     parameters:
 *       - in: path
 *         name: transactionId
 *         required: true
 *         schema:
 *           type: integer
 *         description: 交易ID
 *     responses:
 *       200:
 *         description: 获取成功
 *       401:
 *         description: 未授权
 *       403:
 *         description: 权限不足
 *       404:
 *         description: 交易记录不存在
 */
router.get('/:transactionId',
  verifyToken,
  transactionController.getTransactionDetail
);

/**
 * @swagger
 * /api/transactions/transfer:
 *   post:
 *     summary: 转账
 *     tags: [Transactions]
 *     security:
 *       - bearerAuth: []
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             required:
 *               - from_account_id
 *               - to_account_number
 *               - amount
 *             properties:
 *               from_account_id:
 *                 type: integer
 *                 description: 转出账户ID
 *               to_account_number:
 *                 type: string
 *                 description: 转入账户号码
 *               amount:
 *                 type: number
 *                 description: 转账金额（元）
 *               description:
 *                 type: string
 *                 description: 转账描述
 *     responses:
 *       200:
 *         description: 转账成功
 *       400:
 *         description: 输入数据验证失败、账户状态异常或余额不足
 *       401:
 *         description: 未授权
 *       403:
 *         description: 权限不足
 *       404:
 *         description: 账户不存在
 */
router.post('/transfer',
  verifyToken,
  validateAmount,
  validateAccountNumber,
  transactionController.transfer
);

/**
 * @swagger
 * /api/transactions/{transactionId}/reverse:
 *   post:
 *     summary: 撤销交易
 *     tags: [Transactions]
 *     security:
 *       - bearerAuth: []
 *     parameters:
 *       - in: path
 *         name: transactionId
 *         required: true
 *         schema:
 *           type: integer
 *         description: 交易ID
 *     responses:
 *       200:
 *         description: 撤销成功
 *       400:
 *         description: 该交易无法撤销
 *       401:
 *         description: 未授权
 *       403:
 *         description: 权限不足
 *       404:
 *         description: 交易记录不存在
 */
router.post('/:transactionId/reverse',
  verifyToken,
  requireRole(['admin', 'manager']),
  transactionController.reverseTransaction
);

/**
 * @swagger
 * /api/transactions/stats:
 *   get:
 *     summary: 获取交易统计
 *     tags: [Transactions]
 *     security:
 *       - bearerAuth: []
 *     parameters:
 *       - in: query
 *         name: start_date
 *         schema:
 *           type: string
 *           format: date
 *         description: 开始日期
 *       - in: query
 *         name: end_date
 *         schema:
 *           type: string
 *           format: date
 *         description: 结束日期
 *       - in: query
 *         name: account_id
 *         schema:
 *           type: integer
 *         description: 账户ID（管理员）
 *     responses:
 *       200:
 *         description: 获取成功
 *       401:
 *         description: 未授权
 */
router.get('/stats',
  verifyToken,
  transactionController.getTransactionStats
);

module.exports = router;