feat(wm-revenue): #51 账单生成+多支付渠道收费

wm-revenue/src/main/java/com/water/revenue/controller/BillController.java

@@ -0,0 +1,79 @@
+package com.water.revenue.controller;
+
+import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
+import com.water.common.core.result.R;
+import com.water.revenue.entity.WaterBill;
+import com.water.revenue.mapper.WaterBillMapper;
+import com.water.revenue.service.BillService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import lombok.RequiredArgsConstructor;
+import org.springframework.web.bind.annotation.*;
+
+import java.util.List;
+import java.util.Map;
+
+@Tag(name = "账单管理")
+@RestController
+@RequestMapping("/api/revenue/bill")
+@RequiredArgsConstructor
+public class BillController {
+
+    private final BillService billService;
+    private final WaterBillMapper waterBillMapper;
+
+    @PostMapping("/auto-generate")
+    @Operation(summary = "按抄表周期自动生成账单")
+    public R<Map<String, Object>> autoGenerateBills(
+            @RequestParam(required = false) String billPeriod) {
+        return R.ok(billService.autoGenerateBills(billPeriod));
+    }
+
+    @PostMapping("/manual-generate/{readingId}")
+    @Operation(summary = "手动为指定抄表记录生成账单")
+    public R<WaterBill> manualGenerateBill(@PathVariable Long readingId) {
+        return R.ok(billService.manualGenerateBill(readingId));
+    }
+
+    @GetMapping("/list")
+    @Operation(summary = "账单分页查询")
+    public R<Page<WaterBill>> listBills(
+            @RequestParam(required = false) String customerNo,
+            @RequestParam(required = false) String billPeriod,
+            @RequestParam(required = false) String status,
+            @RequestParam(defaultValue = "1") int pageNum,
+            @RequestParam(defaultValue = "10") int pageSize) {
+        return R.ok(billService.queryBills(customerNo, billPeriod, status, pageNum, pageSize));
+    }
+
+    @GetMapping("/detail/{billId}")
+    @Operation(summary = "账单明细（含缴费记录）")
+    public R<Map<String, Object>> getBillDetail(@PathVariable Long billId) {
+        return R.ok(billService.getBillDetail(billId));
+    }
+
+    @GetMapping("/customer/{customerNo}")
+    @Operation(summary = "按客户查询账单列表")
+    public R<List<WaterBill>> getBillsByCustomer(@PathVariable String customerNo) {
+        return R.ok(billService.getBillsByCustomer(customerNo));
+    }
+
+    @GetMapping("/stats/{billPeriod}")
+    @Operation(summary = "按周期统计账单")
+    public R<List<Map<String, Object>>> getBillStats(@PathVariable String billPeriod) {
+        return R.ok(billService.getBillStatsByPeriod(billPeriod));
+    }
+
+    @PostMapping("/cancel/{billId}")
+    @Operation(summary = "作废账单")
+    public R<String> cancelBill(@PathVariable Long billId) {
+        billService.cancelBill(billId);
+        return R.ok("账单已作废");
+    }
+
+    @GetMapping("/info/{billId}")
+    @Operation(summary = "获取账单基本信息")
+    public R<WaterBill> getBillInfo(@PathVariable Long billId) {
+        return R.ok(waterBillMapper.selectById(billId));
+    }
+}

wm-revenue/src/main/java/com/water/revenue/controller/PaymentController.java

@@ -0,0 +1,94 @@
+package com.water.revenue.controller;
+
+import com.water.common.core.result.R;
+import com.water.revenue.entity.PaymentChannel;
+import com.water.revenue.entity.PaymentRecord;
+import com.water.revenue.service.PaymentService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import lombok.RequiredArgsConstructor;
+import org.springframework.web.bind.annotation.*;
+
+import java.math.BigDecimal;
+import java.util.List;
+import java.util.Map;
+
+@Tag(name = "收费管理")
+@RestController
+@RequestMapping("/api/revenue/payment")
+@RequiredArgsConstructor
+public class PaymentController {
+
+    private final PaymentService paymentService;
+
+    @PostMapping("/counter")
+    @Operation(summary = "柜台现金收费")
+    public R<PaymentRecord> payByCounter(@RequestParam Long billId,
+                                          @RequestParam BigDecimal amount,
+                                          @RequestParam(required = false) Long operatorId,
+                                          @RequestParam(required = false) String operatorName) {
+        return R.ok(paymentService.payByCounter(billId, amount, operatorId, operatorName));
+    }
+
+    @PostMapping("/pos")
+    @Operation(summary = "POS刷卡收费")
+    public R<PaymentRecord> payByPos(@RequestParam Long billId,
+                                      @RequestParam BigDecimal amount,
+                                      @RequestParam(required = false) Long operatorId,
+                                      @RequestParam(required = false) String operatorName) {
+        return R.ok(paymentService.payByPos(billId, amount, operatorId, operatorName));
+    }
+
+    @PostMapping("/alipay")
+    @Operation(summary = "支付宝统一下单")
+    public R<Map<String, Object>> payByAlipay(@RequestParam Long billId,
+                                               @RequestParam BigDecimal amount) {
+        return R.ok(paymentService.payByAlipay(billId, amount));
+    }
+
+    @PostMapping("/wechat")
+    @Operation(summary = "微信统一下单")
+    public R<Map<String, Object>> payByWechat(@RequestParam Long billId,
+                                               @RequestParam BigDecimal amount) {
+        return R.ok(paymentService.payByWechat(billId, amount));
+    }
+
+    @PostMapping("/alipay/callback")
+    @Operation(summary = "支付宝支付回调")
+    public R<String> alipayCallback(@RequestParam String paymentNo,
+                                     @RequestParam String tradeNo,
+                                     @RequestParam String tradeStatus) {
+        return R.ok(paymentService.alipayCallback(paymentNo, tradeNo, tradeStatus));
+    }
+
+    @PostMapping("/wechat/callback")
+    @Operation(summary = "微信支付回调")
+    public R<String> wechatCallback(@RequestParam String paymentNo,
+                                     @RequestParam String transactionId,
+                                     @RequestParam String resultCode) {
+        return R.ok(paymentService.wechatCallback(paymentNo, transactionId, resultCode));
+    }
+
+    @PostMapping("/refund")
+    @Operation(summary = "退费")
+    public R<PaymentRecord> refund(@RequestParam Long paymentId,
+                                    @RequestParam BigDecimal refundAmount,
+                                    @RequestParam(required = false) Long operatorId,
+                                    @RequestParam(required = false) String operatorName) {
+        return R.ok(paymentService.refund(paymentId, refundAmount, operatorId, operatorName));
+    }
+
+    @GetMapping("/channels")
+    @Operation(summary = "查询支付渠道配置")
+    public R<List<PaymentChannel>> listChannels() {
+        return R.ok(paymentService.listChannels());
+    }
+
+    @PostMapping("/channel/toggle")
+    @Operation(summary = "启用/禁用支付渠道")
+    public R<String> toggleChannel(@RequestParam Long channelId,
+                                    @RequestParam Integer enabled) {
+        paymentService.toggleChannel(channelId, enabled);
+        return R.ok(enabled == 1 ? "已启用" : "已禁用");
+    }
+}

wm-revenue/src/main/java/com/water/revenue/controller/PaymentQueryController.java

@@ -0,0 +1,94 @@
+package com.water.revenue.controller;
+
+import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
+import com.water.common.core.result.R;
+import com.water.revenue.entity.PaymentRecord;
+import com.water.revenue.service.PaymentQueryService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import lombok.RequiredArgsConstructor;
+import org.springframework.format.annotation.DateTimeFormat;
+import org.springframework.web.bind.annotation.*;
+
+import java.time.LocalDate;
+import java.util.List;
+import java.util.Map;
+
+@Tag(name = "缴费记录查询")
+@RestController
+@RequestMapping("/api/revenue/payment-query")
+@RequiredArgsConstructor
+public class PaymentQueryController {
+
+    private final PaymentQueryService paymentQueryService;
+
+    @GetMapping("/by-customer")
+    @Operation(summary = "按客户查询缴费记录")
+    public R<Page<PaymentRecord>> queryByCustomer(@RequestParam String customerNo,
+                                                    @RequestParam(defaultValue = "1") int pageNum,
+                                                    @RequestParam(defaultValue = "10") int pageSize) {
+        return R.ok(paymentQueryService.queryByCustomer(customerNo, pageNum, pageSize));
+    }
+
+    @GetMapping("/by-time")
+    @Operation(summary = "按时间范围查询")
+    public R<Page<PaymentRecord>> queryByTimeRange(
+            @RequestParam @DateTimeFormat(pattern = "yyyy-MM-dd") LocalDate startDate,
+            @RequestParam @DateTimeFormat(pattern = "yyyy-MM-dd") LocalDate endDate,
+            @RequestParam(defaultValue = "1") int pageNum,
+            @RequestParam(defaultValue = "10") int pageSize) {
+        return R.ok(paymentQueryService.queryByTimeRange(startDate, endDate, pageNum, pageSize));
+    }
+
+    @GetMapping("/by-channel")
+    @Operation(summary = "按渠道查询")
+    public R<Page<PaymentRecord>> queryByChannel(@RequestParam String channel,
+                                                   @RequestParam(defaultValue = "1") int pageNum,
+                                                   @RequestParam(defaultValue = "10") int pageSize) {
+        return R.ok(paymentQueryService.queryByChannel(channel, pageNum, pageSize));
+    }
+
+    @GetMapping("/by-status")
+    @Operation(summary = "按状态查询")
+    public R<Page<PaymentRecord>> queryByStatus(@RequestParam String status,
+                                                  @RequestParam(defaultValue = "1") int pageNum,
+                                                  @RequestParam(defaultValue = "10") int pageSize) {
+        return R.ok(paymentQueryService.queryByStatus(status, pageNum, pageSize));
+    }
+
+    @GetMapping("/list")
+    @Operation(summary = "综合条件查询缴费记录")
+    public R<Page<PaymentRecord>> queryPayments(
+            @RequestParam(required = false) String customerNo,
+            @RequestParam(required = false) String channel,
+            @RequestParam(required = false) String status,
+            @RequestParam(required = false) @DateTimeFormat(pattern = "yyyy-MM-dd") LocalDate startDate,
+            @RequestParam(required = false) @DateTimeFormat(pattern = "yyyy-MM-dd") LocalDate endDate,
+            @RequestParam(defaultValue = "1") int pageNum,
+            @RequestParam(defaultValue = "10") int pageSize) {
+        return R.ok(paymentQueryService.queryPayments(customerNo, channel, status,
+                startDate, endDate, pageNum, pageSize));
+    }
+
+    @GetMapping("/stats/channel")
+    @Operation(summary = "按渠道统计")
+    public R<List<Map<String, Object>>> statsByChannel() {
+        return R.ok(paymentQueryService.statsByChannel());
+    }
+
+    @GetMapping("/stats/date")
+    @Operation(summary = "按日统计")
+    public R<List<Map<String, Object>>> statsByDate(
+            @RequestParam @DateTimeFormat(pattern = "yyyy-MM-dd") LocalDate startDate,
+            @RequestParam @DateTimeFormat(pattern = "yyyy-MM-dd") LocalDate endDate) {
+        return R.ok(paymentQueryService.statsByDate(startDate, endDate));
+    }
+
+    @GetMapping("/summary")
+    @Operation(summary = "收费汇总")
+    public R<Map<String, Object>> summary(
+            @RequestParam @DateTimeFormat(pattern = "yyyy-MM-dd") LocalDate startDate,
+            @RequestParam @DateTimeFormat(pattern = "yyyy-MM-dd") LocalDate endDate) {
+        return R.ok(paymentQueryService.summary(startDate, endDate));
+    }
+}

wm-revenue/src/main/java/com/water/revenue/entity/PaymentChannel.java

@@ -0,0 +1,37 @@
+package com.water.revenue.entity;
+
+import com.baomidou.mybatisplus.annotation.*;
+import lombok.Data;
+
+import java.math.BigDecimal;
+import java.time.LocalDateTime;
+
+@Data
+@TableName("wm_payment_channel")
+public class PaymentChannel {
+
+    @TableId(type = IdType.AUTO)
+    private Long id;
+
+    /** 渠道编码: counter/pos/alipay/wechat */
+    private String channelCode;
+
+    /** 渠道名称 */
+    private String channelName;
+
+    /** 是否启用: 1=启用 0=禁用 */
+    private Integer enabled;
+
+    /** 手续费率（百分比，如 0.6 表示 0.6%） */
+    private BigDecimal feeRate;
+
+    /** 渠道描述 */
+    private String description;
+
+    /** 排序 */
+    private Integer sortOrder;
+
+    private LocalDateTime createdAt;
+
+    private LocalDateTime updatedAt;
+}

wm-revenue/src/main/java/com/water/revenue/entity/PaymentRecord.java

@@ -0,0 +1,67 @@
+package com.water.revenue.entity;
+
+import com.baomidou.mybatisplus.annotation.*;
+import lombok.Data;
+
+import java.math.BigDecimal;
+import java.time.LocalDateTime;
+
+@Data
+@TableName("wm_payment_record")
+public class PaymentRecord {
+
+    @TableId(type = IdType.AUTO)
+    private Long id;
+
+    /** 支付流水号 */
+    private String paymentNo;
+
+    /** 账单ID */
+    private Long billId;
+
+    /** 账单编号（冗余） */
+    private String billNo;
+
+    /** 客户编号 */
+    private String customerNo;
+
+    /** 客户名称 */
+    private String customerName;
+
+    /** 支付金额 */
+    private BigDecimal amount;
+
+    /** 支付渠道编码: counter/pos/alipay/wechat */
+    private String channel;
+
+    /** 支付渠道名称 */
+    private String channelName;
+
+    /** 支付状态: pending/success/failed/refunded */
+    private String status;
+
+    /** 操作员ID */
+    private Long operatorId;
+
+    /** 操作员姓名 */
+    private String operatorName;
+
+    /** 支付时间 */
+    private LocalDateTime payTime;
+
+    /** 第三方支付交易号 */
+    private String tradeNo;
+
+    /** 退款单号 */
+    private String refundNo;
+
+    /** 退款金额 */
+    private BigDecimal refundAmount;
+
+    /** 备注 */
+    private String remark;
+
+    private LocalDateTime createdAt;
+
+    private LocalDateTime updatedAt;
+}

wm-revenue/src/main/java/com/water/revenue/entity/WaterBill.java

@@ -0,0 +1,65 @@
+package com.water.revenue.entity;
+
+import com.baomidou.mybatisplus.annotation.*;
+import lombok.Data;
+
+import java.math.BigDecimal;
+import java.time.LocalDate;
+import java.time.LocalDateTime;
+
+@Data
+@TableName("wm_water_bill")
+public class WaterBill {
+
+    @TableId(type = IdType.AUTO)
+    private Long id;
+
+    /** 账单编号 */
+    private String billNo;
+
+    /** 客户编号 */
+    private String customerNo;
+
+    /** 客户名称 */
+    private String customerName;
+
+    /** 账单周期（如 2026-06） */
+    private String billPeriod;
+
+    /** 用水量（吨） */
+    private BigDecimal waterUsage;
+
+    /** 单价（元/吨） */
+    private BigDecimal unitPrice;
+
+    /** 总金额 */
+    private BigDecimal totalAmount;
+
+    /** 已付金额 */
+    private BigDecimal paidAmount;
+
+    /** 状态: pending/paid/partial/overdue/cancelled */
+    private String status;
+
+    /** 出账日期 */
+    private LocalDate issueDate;
+
+    /** 到期日期 */
+    private LocalDate dueDate;
+
+    /** 水表编号 */
+    private String meterNo;
+
+    /** 上次读数 */
+    private BigDecimal prevReading;
+
+    /** 本次读数 */
+    private BigDecimal currReading;
+
+    /** 备注 */
+    private String remark;
+
+    private LocalDateTime createdAt;
+
+    private LocalDateTime updatedAt;
+}

wm-revenue/src/main/java/com/water/revenue/mapper/PaymentChannelMapper.java

@@ -0,0 +1,9 @@
+package com.water.revenue.mapper;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.water.revenue.entity.PaymentChannel;
+import org.apache.ibatis.annotations.Mapper;
+
+@Mapper
+public interface PaymentChannelMapper extends BaseMapper<PaymentChannel> {
+}

wm-revenue/src/main/java/com/water/revenue/mapper/PaymentRecordMapper.java

@@ -0,0 +1,9 @@
+package com.water.revenue.mapper;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.water.revenue.entity.PaymentRecord;
+import org.apache.ibatis.annotations.Mapper;
+
+@Mapper
+public interface PaymentRecordMapper extends BaseMapper<PaymentRecord> {
+}

wm-revenue/src/main/java/com/water/revenue/mapper/WaterBillMapper.java

@@ -0,0 +1,9 @@
+package com.water.revenue.mapper;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.water.revenue.entity.WaterBill;
+import org.apache.ibatis.annotations.Mapper;
+
+@Mapper
+public interface WaterBillMapper extends BaseMapper<WaterBill> {
+}

wm-revenue/src/main/java/com/water/revenue/service/BillService.java

@@ -0,0 +1,234 @@
+package com.water.revenue.service;
+
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
+import com.water.revenue.entity.WaterBill;
+import com.water.revenue.mapper.WaterBillMapper;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+import org.springframework.util.StringUtils;
+
+import java.math.BigDecimal;
+import java.time.LocalDate;
+import java.time.LocalDateTime;
+import java.time.YearMonth;
+import java.time.format.DateTimeFormatter;
+import java.util.*;
+
+@Slf4j
+@Service
+@RequiredArgsConstructor
+public class BillService {
+
+    private final WaterBillMapper waterBillMapper;
+    private final JdbcTemplate jdbcTemplate;
+
+    /**
+     * 按抄表周期自动生成账单
+     * 查询已审核但未生成账单的抄表记录，按周期批量生成
+     */
+    @Transactional
+    public Map<String, Object> autoGenerateBills(String billPeriod) {
+        String period = StringUtils.hasText(billPeriod)
+                ? billPeriod
+                : YearMonth.now().format(DateTimeFormatter.ofPattern("yyyy-MM"));
+
+        log.info("Auto generating bills for period: {}", period);
+
+        // 查询该周期已审核但未生成账单的抄表记录
+        List<Map<String, Object>> readings = jdbcTemplate.queryForList(
+                "SELECT r.id AS reading_id, r.consumption, r.prev_reading, r.curr_reading, " +
+                "r.reading_period, m.meter_no, m.customer_id, " +
+                "c.customer_no, c.customer_name, c.customer_type " +
+                "FROM rev_reading r " +
+                "JOIN rev_meter m ON r.meter_id = m.id " +
+                "JOIN rev_customer c ON m.customer_id = c.id " +
+                "WHERE r.verified = 1 AND r.reading_period = ? " +
+                "AND NOT EXISTS (SELECT 1 FROM wm_water_bill b WHERE b.meter_no = m.meter_no AND b.bill_period = ?)",
+                period, period);
+
+        int generated = 0;
+        List<String> errors = new ArrayList<>();
+
+        for (Map<String, Object> reading : readings) {
+            try {
+                generateSingleBill(reading, period);
+                generated++;
+            } catch (Exception e) {
+                log.error("Failed to generate bill for reading {}: {}", reading.get("reading_id"), e.getMessage());
+                errors.add("Reading#" + reading.get("reading_id") + ": " + e.getMessage());
+            }
+        }
+
+        log.info("Auto bill generation completed: period={}, generated={}, errors={}", period, generated, errors.size());
+        Map<String, Object> result = new LinkedHashMap<>();
+        result.put("period", period);
+        result.put("generatedCount", generated);
+        result.put("totalReadings", readings.size());
+        result.put("errors", errors);
+        return result;
+    }
+
+    /**
+     * 手动为指定抄表记录生成账单
+     */
+    @Transactional
+    public WaterBill manualGenerateBill(Long readingId) {
+        Map<String, Object> reading = jdbcTemplate.queryForMap(
+                "SELECT r.id AS reading_id, r.consumption, r.prev_reading, r.curr_reading, " +
+                "r.reading_period, m.meter_no, m.customer_id, " +
+                "c.customer_no, c.customer_name, c.customer_type " +
+                "FROM rev_reading r " +
+                "JOIN rev_meter m ON r.meter_id = m.id " +
+                "JOIN rev_customer c ON m.customer_id = c.id " +
+                "WHERE r.id = ?", readingId);
+
+        String period = (String) reading.get("reading_period");
+
+        // 检查是否已存在
+        Long existCount = waterBillMapper.selectCount(
+                new LambdaQueryWrapper<WaterBill>()
+                        .eq(WaterBill::getMeterNo, reading.get("meter_no"))
+                        .eq(WaterBill::getBillPeriod, period));
+        if (existCount > 0) {
+            throw new RuntimeException("该抄表记录已生成账单，周期: " + period);
+        }
+
+        return generateSingleBill(reading, period);
+    }
+
+    /**
+     * 账单分页查询
+     */
+    public Page<WaterBill> queryBills(String customerNo, String billPeriod, String status,
+                                       int pageNum, int pageSize) {
+        LambdaQueryWrapper<WaterBill> wrapper = new LambdaQueryWrapper<>();
+        if (StringUtils.hasText(customerNo)) {
+            wrapper.like(WaterBill::getCustomerNo, customerNo);
+        }
+        if (StringUtils.hasText(billPeriod)) {
+            wrapper.eq(WaterBill::getBillPeriod, billPeriod);
+        }
+        if (StringUtils.hasText(status)) {
+            wrapper.eq(WaterBill::getStatus, status);
+        }
+        wrapper.orderByDesc(WaterBill::getCreatedAt);
+
+        return waterBillMapper.selectPage(new Page<>(pageNum, pageSize), wrapper);
+    }
+
+    /**
+     * 账单明细
+     */
+    public Map<String, Object> getBillDetail(Long billId) {
+        WaterBill bill = waterBillMapper.selectById(billId);
+        if (bill == null) {
+            throw new RuntimeException("账单不存在: " + billId);
+        }
+
+        // 查询该账单的缴费记录
+        List<Map<String, Object>> payments = jdbcTemplate.queryForList(
+                "SELECT payment_no, amount, channel, channel_name, status, pay_time, operator_name " +
+                "FROM wm_payment_record WHERE bill_id = ? ORDER BY pay_time DESC", billId);
+
+        Map<String, Object> detail = new LinkedHashMap<>();
+        detail.put("bill", bill);
+        detail.put("payments", payments);
+        detail.put("remainingAmount", bill.getTotalAmount().subtract(bill.getPaidAmount()));
+        return detail;
+    }
+
+    /**
+     * 按客户查询账单列表
+     */
+    public List<WaterBill> getBillsByCustomer(String customerNo) {
+        return waterBillMapper.selectList(
+                new LambdaQueryWrapper<WaterBill>()
+                        .eq(WaterBill::getCustomerNo, customerNo)
+                        .orderByDesc(WaterBill::getBillPeriod));
+    }
+
+    /**
+     * 按周期统计账单
+     */
+    public List<Map<String, Object>> getBillStatsByPeriod(String billPeriod) {
+        return jdbcTemplate.queryForList(
+                "SELECT status, COUNT(*) AS count, " +
+                "COALESCE(SUM(total_amount), 0) AS total_amount, " +
+                "COALESCE(SUM(paid_amount), 0) AS paid_amount " +
+                "FROM wm_water_bill WHERE bill_period = ? GROUP BY status",
+                billPeriod);
+    }
+
+    /**
+     * 作废账单
+     */
+    @Transactional
+    public void cancelBill(Long billId) {
+        WaterBill bill = waterBillMapper.selectById(billId);
+        if (bill == null) {
+            throw new RuntimeException("账单不存在: " + billId);
+        }
+        if (!"pending".equals(bill.getStatus())) {
+            throw new RuntimeException("只能作废 pending 状态的账单，当前状态: " + bill.getStatus());
+        }
+        bill.setStatus("cancelled");
+        bill.setUpdatedAt(LocalDateTime.now());
+        waterBillMapper.updateById(bill);
+        log.info("Bill cancelled: {}", bill.getBillNo());
+    }
+
+    // ---- private helpers ----
+
+    private WaterBill generateSingleBill(Map<String, Object> reading, String period) {
+        BigDecimal consumption = reading.get("consumption") != null
+                ? new BigDecimal(reading.get("consumption").toString()) : BigDecimal.ZERO;
+
+        // 查询水价（取该客户类型的第一条有效价格）
+        BigDecimal unitPrice = BigDecimal.valueOf(3.5); // 默认单价
+        try {
+            String customerType = (String) reading.get("customer_type");
+            if (customerType != null) {
+                BigDecimal dbPrice = jdbcTemplate.queryForObject(
+                        "SELECT water_price FROM rev_water_price WHERE customer_type = ? " +
+                        "AND effective_date <= CURRENT_DATE ORDER BY tier_no LIMIT 1",
+                        BigDecimal.class, customerType);
+                if (dbPrice != null) {
+                    unitPrice = dbPrice;
+                }
+            }
+        } catch (Exception e) {
+            log.warn("Failed to query water price, using default: {}", unitPrice);
+        }
+
+        BigDecimal totalAmount = consumption.multiply(unitPrice);
+        String billNo = "BILL-" + System.currentTimeMillis() + "-" + new Random().nextInt(1000);
+
+        WaterBill bill = new WaterBill();
+        bill.setBillNo(billNo);
+        bill.setCustomerNo((String) reading.get("customer_no"));
+        bill.setCustomerName((String) reading.get("customer_name"));
+        bill.setBillPeriod(period);
+        bill.setWaterUsage(consumption);
+        bill.setUnitPrice(unitPrice);
+        bill.setTotalAmount(totalAmount);
+        bill.setPaidAmount(BigDecimal.ZERO);
+        bill.setStatus("pending");
+        bill.setIssueDate(LocalDate.now());
+        bill.setDueDate(LocalDate.now().plusDays(30));
+        bill.setMeterNo((String) reading.get("meter_no"));
+        bill.setPrevReading(reading.get("prev_reading") != null
+                ? new BigDecimal(reading.get("prev_reading").toString()) : BigDecimal.ZERO);
+        bill.setCurrReading(reading.get("curr_reading") != null
+                ? new BigDecimal(reading.get("curr_reading").toString()) : BigDecimal.ZERO);
+        bill.setCreatedAt(LocalDateTime.now());
+        bill.setUpdatedAt(LocalDateTime.now());
+
+        waterBillMapper.insert(bill);
+        log.info("Bill generated: {} customer={} amount={}", billNo, bill.getCustomerNo(), totalAmount);
+        return bill;
+    }
+}

wm-revenue/src/main/java/com/water/revenue/service/PaymentQueryService.java

@@ -0,0 +1,138 @@
+package com.water.revenue.service;
+
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
+import com.water.revenue.entity.PaymentRecord;
+import com.water.revenue.mapper.PaymentRecordMapper;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.stereotype.Service;
+import org.springframework.util.StringUtils;
+
+import java.time.LocalDate;
+import java.time.LocalDateTime;
+import java.time.LocalTime;
+import java.util.*;
+
+@Slf4j
+@Service
+@RequiredArgsConstructor
+public class PaymentQueryService {
+
+    private final PaymentRecordMapper paymentRecordMapper;
+    private final JdbcTemplate jdbcTemplate;
+
+    /**
+     * 按客户查询缴费记录
+     */
+    public Page<PaymentRecord> queryByCustomer(String customerNo, int pageNum, int pageSize) {
+        LambdaQueryWrapper<PaymentRecord> wrapper = new LambdaQueryWrapper<>();
+        wrapper.eq(PaymentRecord::getCustomerNo, customerNo)
+               .orderByDesc(PaymentRecord::getPayTime);
+        return paymentRecordMapper.selectPage(new Page<>(pageNum, pageSize), wrapper);
+    }
+
+    /**
+     * 按时间范围查询
+     */
+    public Page<PaymentRecord> queryByTimeRange(LocalDate startDate, LocalDate endDate,
+                                                  int pageNum, int pageSize) {
+        LambdaQueryWrapper<PaymentRecord> wrapper = new LambdaQueryWrapper<>();
+        if (startDate != null) {
+            wrapper.ge(PaymentRecord::getPayTime, startDate.atStartOfDay());
+        }
+        if (endDate != null) {
+            wrapper.le(PaymentRecord::getPayTime, endDate.atTime(LocalTime.MAX));
+        }
+        wrapper.orderByDesc(PaymentRecord::getPayTime);
+        return paymentRecordMapper.selectPage(new Page<>(pageNum, pageSize), wrapper);
+    }
+
+    /**
+     * 按渠道查询
+     */
+    public Page<PaymentRecord> queryByChannel(String channel, int pageNum, int pageSize) {
+        LambdaQueryWrapper<PaymentRecord> wrapper = new LambdaQueryWrapper<>();
+        wrapper.eq(PaymentRecord::getChannel, channel)
+               .orderByDesc(PaymentRecord::getPayTime);
+        return paymentRecordMapper.selectPage(new Page<>(pageNum, pageSize), wrapper);
+    }
+
+    /**
+     * 按状态查询
+     */
+    public Page<PaymentRecord> queryByStatus(String status, int pageNum, int pageSize) {
+        LambdaQueryWrapper<PaymentRecord> wrapper = new LambdaQueryWrapper<>();
+        wrapper.eq(PaymentRecord::getStatus, status)
+               .orderByDesc(PaymentRecord::getPayTime);
+        return paymentRecordMapper.selectPage(new Page<>(pageNum, pageSize), wrapper);
+    }
+
+    /**
+     * 综合条件查询
+     */
+    public Page<PaymentRecord> queryPayments(String customerNo, String channel, String status,
+                                              LocalDate startDate, LocalDate endDate,
+                                              int pageNum, int pageSize) {
+        LambdaQueryWrapper<PaymentRecord> wrapper = new LambdaQueryWrapper<>();
+        if (StringUtils.hasText(customerNo)) {
+            wrapper.eq(PaymentRecord::getCustomerNo, customerNo);
+        }
+        if (StringUtils.hasText(channel)) {
+            wrapper.eq(PaymentRecord::getChannel, channel);
+        }
+        if (StringUtils.hasText(status)) {
+            wrapper.eq(PaymentRecord::getStatus, status);
+        }
+        if (startDate != null) {
+            wrapper.ge(PaymentRecord::getPayTime, startDate.atStartOfDay());
+        }
+        if (endDate != null) {
+            wrapper.le(PaymentRecord::getPayTime, endDate.atTime(LocalTime.MAX));
+        }
+        wrapper.orderByDesc(PaymentRecord::getPayTime);
+        return paymentRecordMapper.selectPage(new Page<>(pageNum, pageSize), wrapper);
+    }
+
+    /**
+     * 按渠道统计
+     */
+    public List<Map<String, Object>> statsByChannel() {
+        return jdbcTemplate.queryForList(
+                "SELECT channel, channel_name, COUNT(*) AS count, " +
+                "COALESCE(SUM(CASE WHEN amount > 0 THEN amount ELSE 0 END), 0) AS total_amount, " +
+                "COALESCE(SUM(CASE WHEN amount < 0 THEN ABS(amount) ELSE 0 END), 0) AS refund_amount " +
+                "FROM wm_payment_record GROUP BY channel, channel_name ORDER BY count DESC");
+    }
+
+    /**
+     * 按日统计
+     */
+    public List<Map<String, Object>> statsByDate(LocalDate startDate, LocalDate endDate) {
+        return jdbcTemplate.queryForList(
+                "SELECT DATE(pay_time) AS pay_date, COUNT(*) AS count, " +
+                "COALESCE(SUM(CASE WHEN amount > 0 THEN amount ELSE 0 END), 0) AS total_amount " +
+                "FROM wm_payment_record " +
+                "WHERE pay_time >= ? AND pay_time <= ? " +
+                "GROUP BY DATE(pay_time) ORDER BY pay_date",
+                startDate.atStartOfDay(), endDate.atTime(LocalTime.MAX));
+    }
+
+    /**
+     * 收费汇总
+     */
+    public Map<String, Object> summary(LocalDate startDate, LocalDate endDate) {
+        Map<String, Object> result = jdbcTemplate.queryForMap(
+                "SELECT COUNT(*) AS total_count, " +
+                "COALESCE(SUM(CASE WHEN amount > 0 THEN amount ELSE 0 END), 0) AS total_income, " +
+                "COALESCE(SUM(CASE WHEN amount < 0 THEN ABS(amount) ELSE 0 END), 0) AS total_refund, " +
+                "COUNT(DISTINCT customer_no) AS customer_count " +
+                "FROM wm_payment_record WHERE pay_time >= ? AND pay_time <= ?",
+                startDate.atStartOfDay(), endDate.atTime(LocalTime.MAX));
+
+        result.put("startDate", startDate.toString());
+        result.put("endDate", endDate.toString());
+        return result;
+    }
+}

wm-revenue/src/main/java/com/water/revenue/service/PaymentService.java

@@ -0,0 +1,273 @@
+package com.water.revenue.service;
+
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.water.revenue.entity.PaymentChannel;
+import com.water.revenue.entity.PaymentRecord;
+import com.water.revenue.entity.WaterBill;
+import com.water.revenue.mapper.PaymentChannelMapper;
+import com.water.revenue.mapper.PaymentRecordMapper;
+import com.water.revenue.mapper.WaterBillMapper;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.math.BigDecimal;
+import java.math.RoundingMode;
+import java.time.LocalDateTime;
+import java.util.*;
+
+@Slf4j
+@Service
+@RequiredArgsConstructor
+public class PaymentService {
+
+    private final PaymentRecordMapper paymentRecordMapper;
+    private final PaymentChannelMapper paymentChannelMapper;
+    private final WaterBillMapper waterBillMapper;
+
+    /**
+     * 柜台现金收费
+     */
+    @Transactional
+    public PaymentRecord payByCounter(Long billId, BigDecimal amount, Long operatorId, String operatorName) {
+        return doPay(billId, amount, "counter", "柜台现金", operatorId, operatorName);
+    }
+
+    /**
+     * POS 刷卡收费
+     */
+    @Transactional
+    public PaymentRecord payByPos(Long billId, BigDecimal amount, Long operatorId, String operatorName) {
+        return doPay(billId, amount, "pos", "POS刷卡", operatorId, operatorName);
+    }
+
+    /**
+     * 支付宝统一下单
+     */
+    @Transactional
+    public Map<String, Object> payByAlipay(Long billId, BigDecimal amount) {
+        PaymentRecord record = doPay(billId, amount, "alipay", "支付宝", null, null);
+        // 模拟支付宝下单返回
+        Map<String, Object> result = new LinkedHashMap<>();
+        result.put("paymentRecord", record);
+        result.put("payForm", "模拟支付宝收银台表单 - paymentNo=" + record.getPaymentNo());
+        result.put("tradeNo", "ALI" + System.currentTimeMillis());
+        return result;
+    }
+
+    /**
+     * 微信统一下单
+     */
+    @Transactional
+    public Map<String, Object> payByWechat(Long billId, BigDecimal amount) {
+        PaymentRecord record = doPay(billId, amount, "wechat", "微信支付", null, null);
+        // 模拟微信下单返回
+        Map<String, Object> result = new LinkedHashMap<>();
+        result.put("paymentRecord", record);
+        result.put("prepayId", "WX" + System.currentTimeMillis());
+        result.put("codeUrl", "weixin://wxpay/bizpayurl?pr=" + record.getPaymentNo());
+        return result;
+    }
+
+    /**
+     * 支付宝回调
+     */
+    @Transactional
+    public String alipayCallback(String paymentNo, String tradeNo, String tradeStatus) {
+        PaymentRecord record = paymentRecordMapper.selectOne(
+                new LambdaQueryWrapper<PaymentRecord>().eq(PaymentRecord::getPaymentNo, paymentNo));
+        if (record == null) {
+            log.warn("Alipay callback: payment not found: {}", paymentNo);
+            return "fail";
+        }
+
+        if ("TRADE_SUCCESS".equals(tradeStatus) || "TRADE_FINISHED".equals(tradeStatus)) {
+            record.setStatus("success");
+            record.setTradeNo(tradeNo);
+            record.setPayTime(LocalDateTime.now());
+            paymentRecordMapper.updateById(record);
+            updateBillPaidAmount(record.getBillId(), record.getAmount());
+            log.info("Alipay callback success: paymentNo={}, tradeNo={}", paymentNo, tradeNo);
+            return "success";
+        }
+
+        record.setStatus("failed");
+        paymentRecordMapper.updateById(record);
+        return "fail";
+    }
+
+    /**
+     * 微信回调
+     */
+    @Transactional
+    public String wechatCallback(String paymentNo, String transactionId, String resultCode) {
+        PaymentRecord record = paymentRecordMapper.selectOne(
+                new LambdaQueryWrapper<PaymentRecord>().eq(PaymentRecord::getPaymentNo, paymentNo));
+        if (record == null) {
+            log.warn("Wechat callback: payment not found: {}", paymentNo);
+            return "FAIL";
+        }
+
+        if ("SUCCESS".equals(resultCode)) {
+            record.setStatus("success");
+            record.setTradeNo(transactionId);
+            record.setPayTime(LocalDateTime.now());
+            paymentRecordMapper.updateById(record);
+            updateBillPaidAmount(record.getBillId(), record.getAmount());
+            log.info("Wechat callback success: paymentNo={}, transactionId={}", paymentNo, transactionId);
+            return "SUCCESS";
+        }
+
+        record.setStatus("failed");
+        paymentRecordMapper.updateById(record);
+        return "FAIL";
+    }
+
+    /**
+     * 退费
+     */
+    @Transactional
+    public PaymentRecord refund(Long paymentId, BigDecimal refundAmount, Long operatorId, String operatorName) {
+        PaymentRecord original = paymentRecordMapper.selectById(paymentId);
+        if (original == null) {
+            throw new RuntimeException("支付记录不存在: " + paymentId);
+        }
+        if (!"success".equals(original.getStatus())) {
+            throw new RuntimeException("只能对成功状态的支付进行退费");
+        }
+        if (refundAmount.compareTo(original.getAmount()) > 0) {
+            throw new RuntimeException("退款金额不能大于原支付金额");
+        }
+
+        // 创建退费记录
+        PaymentRecord refundRecord = new PaymentRecord();
+        refundRecord.setPaymentNo("REF-" + System.currentTimeMillis());
+        refundRecord.setBillId(original.getBillId());
+        refundRecord.setBillNo(original.getBillNo());
+        refundRecord.setCustomerNo(original.getCustomerNo());
+        refundRecord.setCustomerName(original.getCustomerName());
+        refundRecord.setAmount(refundAmount.negate()); // 负数表示退费
+        refundRecord.setChannel(original.getChannel());
+        refundRecord.setChannelName(original.getChannelName());
+        refundRecord.setStatus("refunded");
+        refundRecord.setOperatorId(operatorId);
+        refundRecord.setOperatorName(operatorName);
+        refundRecord.setPayTime(LocalDateTime.now());
+        refundRecord.setRefundNo("RF" + System.currentTimeMillis());
+        refundRecord.setRefundAmount(refundAmount);
+        refundRecord.setRemark("退费 - 原支付流水: " + original.getPaymentNo());
+        refundRecord.setCreatedAt(LocalDateTime.now());
+        refundRecord.setUpdatedAt(LocalDateTime.now());
+
+        paymentRecordMapper.insert(refundRecord);
+
+        // 更新原支付记录状态
+        original.setStatus("refunded");
+        original.setRefundNo(refundRecord.getRefundNo());
+        original.setRefundAmount(refundAmount);
+        original.setUpdatedAt(LocalDateTime.now());
+        paymentRecordMapper.updateById(original);
+
+        // 更新账单已付金额（减少）
+        updateBillPaidAmountOnRefund(original.getBillId(), refundAmount);
+
+        log.info("Refund processed: refundNo={}, originalPaymentNo={}, amount={}",
+                refundRecord.getRefundNo(), original.getPaymentNo(), refundAmount);
+        return refundRecord;
+    }
+
+    /**
+     * 查询所有支付渠道配置
+     */
+    public List<PaymentChannel> listChannels() {
+        return paymentChannelMapper.selectList(
+                new LambdaQueryWrapper<PaymentChannel>().orderByAsc(PaymentChannel::getSortOrder));
+    }
+
+    /**
+     * 启用/禁用支付渠道
+     */
+    public void toggleChannel(Long channelId, Integer enabled) {
+        PaymentChannel channel = paymentChannelMapper.selectById(channelId);
+        if (channel == null) {
+            throw new RuntimeException("支付渠道不存在: " + channelId);
+        }
+        channel.setEnabled(enabled);
+        channel.setUpdatedAt(LocalDateTime.now());
+        paymentChannelMapper.updateById(channel);
+    }
+
+    // ---- private helpers ----
+
+    private PaymentRecord doPay(Long billId, BigDecimal amount, String channel, String channelName,
+                                 Long operatorId, String operatorName) {
+        WaterBill bill = waterBillMapper.selectById(billId);
+        if (bill == null) {
+            throw new RuntimeException("账单不存在: " + billId);
+        }
+        if ("paid".equals(bill.getStatus()) || "cancelled".equals(bill.getStatus())) {
+            throw new RuntimeException("账单状态不允许缴费: " + bill.getStatus());
+        }
+
+        BigDecimal remaining = bill.getTotalAmount().subtract(bill.getPaidAmount());
+        if (amount.compareTo(remaining) > 0) {
+            throw new RuntimeException("支付金额超出应缴余额，剩余: " + remaining);
+        }
+
+        PaymentRecord record = new PaymentRecord();
+        record.setPaymentNo("PAY-" + System.currentTimeMillis() + "-" + new Random().nextInt(1000));
+        record.setBillId(billId);
+        record.setBillNo(bill.getBillNo());
+        record.setCustomerNo(bill.getCustomerNo());
+        record.setCustomerName(bill.getCustomerName());
+        record.setAmount(amount);
+        record.setChannel(channel);
+        record.setChannelName(channelName);
+        record.setStatus("success");
+        record.setOperatorId(operatorId);
+        record.setOperatorName(operatorName);
+        record.setPayTime(LocalDateTime.now());
+        record.setCreatedAt(LocalDateTime.now());
+        record.setUpdatedAt(LocalDateTime.now());
+
+        paymentRecordMapper.insert(record);
+
+        // 更新账单已付金额
+        updateBillPaidAmount(billId, amount);
+
+        log.info("Payment processed: paymentNo={}, billId={}, amount={}, channel={}",
+                record.getPaymentNo(), billId, amount, channel);
+        return record;
+    }
+
+    private void updateBillPaidAmount(Long billId, BigDecimal amount) {
+        WaterBill bill = waterBillMapper.selectById(billId);
+        if (bill == null) return;
+
+        BigDecimal newPaid = bill.getPaidAmount().add(amount);
+        bill.setPaidAmount(newPaid);
+
+        if (newPaid.compareTo(bill.getTotalAmount()) >= 0) {
+            bill.setStatus("paid");
+        } else if (newPaid.compareTo(BigDecimal.ZERO) > 0) {
+            bill.setStatus("partial");
+        }
+        bill.setUpdatedAt(LocalDateTime.now());
+        waterBillMapper.updateById(bill);
+    }
+
+    private void updateBillPaidAmountOnRefund(Long billId, BigDecimal refundAmount) {
+        WaterBill bill = waterBillMapper.selectById(billId);
+        if (bill == null) return;
+
+        BigDecimal newPaid = bill.getPaidAmount().subtract(refundAmount);
+        if (newPaid.compareTo(BigDecimal.ZERO) < 0) {
+            newPaid = BigDecimal.ZERO;
+        }
+        bill.setPaidAmount(newPaid);
+        bill.setStatus(newPaid.compareTo(BigDecimal.ZERO) > 0 ? "partial" : "pending");
+        bill.setUpdatedAt(LocalDateTime.now());
+        waterBillMapper.updateById(bill);
+    }
+}

wm-revenue/src/main/resources/db/V_bill_payment.sql

@@ -0,0 +1,126 @@
+-- =============================================
+-- V_bill_payment.sql
+-- 账单与收费模块 DDL
+-- =============================================
+
+-- 1. 水费账单表
+CREATE TABLE IF NOT EXISTS wm_water_bill (
+    id              BIGSERIAL PRIMARY KEY,
+    bill_no         VARCHAR(64)    NOT NULL,
+    customer_no     VARCHAR(64),
+    customer_name   VARCHAR(128),
+    bill_period     VARCHAR(16)    NOT NULL,
+    water_usage     NUMERIC(12,2)  DEFAULT 0,
+    unit_price      NUMERIC(8,4)   DEFAULT 0,
+    total_amount    NUMERIC(12,2)  NOT NULL DEFAULT 0,
+    paid_amount     NUMERIC(12,2)  NOT NULL DEFAULT 0,
+    status          VARCHAR(16)    NOT NULL DEFAULT 'pending',
+    issue_date      DATE,
+    due_date        DATE,
+    meter_no        VARCHAR(64),
+    prev_reading    NUMERIC(12,2)  DEFAULT 0,
+    curr_reading    NUMERIC(12,2)  DEFAULT 0,
+    remark          VARCHAR(512),
+    created_at      TIMESTAMP      NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at      TIMESTAMP      NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+COMMENT ON TABLE wm_water_bill IS '水费账单表';
+COMMENT ON COLUMN wm_water_bill.bill_no IS '账单编号';
+COMMENT ON COLUMN wm_water_bill.customer_no IS '客户编号';
+COMMENT ON COLUMN wm_water_bill.customer_name IS '客户名称';
+COMMENT ON COLUMN wm_water_bill.bill_period IS '账单周期（如 2026-06）';
+COMMENT ON COLUMN wm_water_bill.water_usage IS '用水量（吨）';
+COMMENT ON COLUMN wm_water_bill.unit_price IS '单价（元/吨）';
+COMMENT ON COLUMN wm_water_bill.total_amount IS '总金额';
+COMMENT ON COLUMN wm_water_bill.paid_amount IS '已付金额';
+COMMENT ON COLUMN wm_water_bill.status IS '状态: pending/paid/partial/overdue/cancelled';
+COMMENT ON COLUMN wm_water_bill.issue_date IS '出账日期';
+COMMENT ON COLUMN wm_water_bill.due_date IS '到期日期';
+COMMENT ON COLUMN wm_water_bill.meter_no IS '水表编号';
+
+-- 2. 缴费记录表
+CREATE TABLE IF NOT EXISTS wm_payment_record (
+    id              BIGSERIAL PRIMARY KEY,
+    payment_no      VARCHAR(64)    NOT NULL,
+    bill_id         BIGINT,
+    bill_no         VARCHAR(64),
+    customer_no     VARCHAR(64),
+    customer_name   VARCHAR(128),
+    amount          NUMERIC(12,2)  NOT NULL,
+    channel         VARCHAR(32)    NOT NULL,
+    channel_name    VARCHAR(64),
+    status          VARCHAR(16)    NOT NULL DEFAULT 'pending',
+    operator_id     BIGINT,
+    operator_name   VARCHAR(64),
+    pay_time        TIMESTAMP,
+    trade_no        VARCHAR(128),
+    refund_no       VARCHAR(64),
+    refund_amount   NUMERIC(12,2),
+    remark          VARCHAR(512),
+    created_at      TIMESTAMP      NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at      TIMESTAMP      NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+COMMENT ON TABLE wm_payment_record IS '缴费记录表';
+COMMENT ON COLUMN wm_payment_record.payment_no IS '支付流水号';
+COMMENT ON COLUMN wm_payment_record.bill_id IS '账单ID';
+COMMENT ON COLUMN wm_payment_record.amount IS '支付金额（负数表示退费）';
+COMMENT ON COLUMN wm_payment_record.channel IS '支付渠道编码: counter/pos/alipay/wechat';
+COMMENT ON COLUMN wm_payment_record.status IS '支付状态: pending/success/failed/refunded';
+COMMENT ON COLUMN wm_payment_record.trade_no IS '第三方支付交易号';
+
+-- 3. 支付渠道配置表
+CREATE TABLE IF NOT EXISTS wm_payment_channel (
+    id              BIGSERIAL PRIMARY KEY,
+    channel_code    VARCHAR(32)    NOT NULL,
+    channel_name    VARCHAR(64)    NOT NULL,
+    enabled         INTEGER        NOT NULL DEFAULT 1,
+    fee_rate        NUMERIC(6,4)   DEFAULT 0,
+    description     VARCHAR(256),
+    sort_order      INTEGER        DEFAULT 0,
+    created_at      TIMESTAMP      NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at      TIMESTAMP      NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+COMMENT ON TABLE wm_payment_channel IS '支付渠道配置表';
+COMMENT ON COLUMN wm_payment_channel.channel_code IS '渠道编码';
+COMMENT ON COLUMN wm_payment_channel.channel_name IS '渠道名称';
+COMMENT ON COLUMN wm_payment_channel.enabled IS '是否启用: 1=启用 0=禁用';
+COMMENT ON COLUMN wm_payment_channel.fee_rate IS '手续费率（百分比）';
+
+-- =============================================
+-- 索引
+-- =============================================
+
+-- 账单表索引
+CREATE INDEX IF NOT EXISTS idx_water_bill_bill_no ON wm_water_bill (bill_no);
+CREATE INDEX IF NOT EXISTS idx_water_bill_customer_no ON wm_water_bill (customer_no);
+CREATE INDEX IF NOT EXISTS idx_water_bill_period ON wm_water_bill (bill_period);
+CREATE INDEX IF NOT EXISTS idx_water_bill_status ON wm_water_bill (status);
+CREATE INDEX IF NOT EXISTS idx_water_bill_due_date ON wm_water_bill (due_date);
+CREATE UNIQUE INDEX IF NOT EXISTS uk_water_bill_bill_no ON wm_water_bill (bill_no);
+
+-- 缴费记录表索引
+CREATE INDEX IF NOT EXISTS idx_payment_record_payment_no ON wm_payment_record (payment_no);
+CREATE INDEX IF NOT EXISTS idx_payment_record_bill_id ON wm_payment_record (bill_id);
+CREATE INDEX IF NOT EXISTS idx_payment_record_customer_no ON wm_payment_record (customer_no);
+CREATE INDEX IF NOT EXISTS idx_payment_record_channel ON wm_payment_record (channel);
+CREATE INDEX IF NOT EXISTS idx_payment_record_status ON wm_payment_record (status);
+CREATE INDEX IF NOT EXISTS idx_payment_record_pay_time ON wm_payment_record (pay_time);
+CREATE UNIQUE INDEX IF NOT EXISTS uk_payment_record_payment_no ON wm_payment_record (payment_no);
+
+-- 支付渠道表索引
+CREATE UNIQUE INDEX IF NOT EXISTS uk_payment_channel_code ON wm_payment_channel (channel_code);
+
+-- =============================================
+-- 默认支付渠道数据
+-- =============================================
+
+INSERT INTO wm_payment_channel (channel_code, channel_name, enabled, fee_rate, description, sort_order)
+VALUES
+    ('counter', '柜台现金', 1, 0.0000, '营业厅柜台现金支付', 1),
+    ('pos', 'POS刷卡', 1, 0.6000, 'POS机刷卡支付（手续费0.6%）', 2),
+    ('alipay', '支付宝', 1, 0.6000, '支付宝APP/网页/二维码支付', 3),
+    ('wechat', '微信支付', 1, 0.6000, '微信APP/小程序/二维码支付', 4)
+ON CONFLICT (channel_code) DO NOTHING;

wm-revenue/src/test/java/com/water/revenue/BillPaymentTest.java

@@ -0,0 +1,389 @@
+package com.water.revenue;
+
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
+import com.water.revenue.entity.PaymentChannel;
+import com.water.revenue.entity.PaymentRecord;
+import com.water.revenue.entity.WaterBill;
+import com.water.revenue.mapper.PaymentChannelMapper;
+import com.water.revenue.mapper.PaymentRecordMapper;
+import com.water.revenue.mapper.WaterBillMapper;
+import com.water.revenue.service.BillService;
+import com.water.revenue.service.PaymentQueryService;
+import com.water.revenue.service.PaymentService;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Nested;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.ArgumentCaptor;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.springframework.jdbc.core.JdbcTemplate;
+
+import java.math.BigDecimal;
+import java.time.LocalDate;
+import java.time.LocalDateTime;
+import java.util.*;
+
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.ArgumentMatchers.*;
+import static org.mockito.Mockito.*;
+
+@ExtendWith(MockitoExtension.class)
+@DisplayName("账单与收费模块测试")
+class BillPaymentTest {
+
+    @Mock
+    private WaterBillMapper waterBillMapper;
+    @Mock
+    private PaymentRecordMapper paymentRecordMapper;
+    @Mock
+    private PaymentChannelMapper paymentChannelMapper;
+    @Mock
+    private JdbcTemplate jdbcTemplate;
+
+    private BillService billService;
+    private PaymentService paymentService;
+    private PaymentQueryService paymentQueryService;
+
+    @BeforeEach
+    void setUp() {
+        billService = new BillService(waterBillMapper, jdbcTemplate);
+        paymentService = new PaymentService(paymentRecordMapper, paymentChannelMapper, waterBillMapper);
+        paymentQueryService = new PaymentQueryService(paymentRecordMapper, jdbcTemplate);
+    }
+
+    // ========== 账单服务测试 ==========
+
+    @Nested
+    @DisplayName("BillService - 账单生成测试")
+    class BillGenerationTests {
+
+        @Test
+        @DisplayName("自动生成账单 - 正常周期")
+        void autoGenerateBills_normalPeriod() {
+            // 模拟抄表记录
+            Map<String, Object> reading = new HashMap<>();
+            reading.put("reading_id", 1L);
+            reading.put("consumption", new BigDecimal("15.5"));
+            reading.put("prev_reading", new BigDecimal("100"));
+            reading.put("curr_reading", new BigDecimal("115.5"));
+            reading.put("reading_period", "2026-06");
+            reading.put("meter_no", "M001");
+            reading.put("customer_id", 100L);
+            reading.put("customer_no", "C001");
+            reading.put("customer_name", "张三");
+            reading.put("customer_type", "residential");
+
+            when(jdbcTemplate.queryForList(anyString(), eq("2026-06"), eq("2026-06")))
+                    .thenReturn(List.of(reading));
+            when(jdbcTemplate.queryForObject(contains("water_price"), eq(BigDecimal.class), eq("residential")))
+                    .thenReturn(new BigDecimal("3.50"));
+            when(waterBillMapper.insert(any(WaterBill.class))).thenReturn(1);
+
+            Map<String, Object> result = billService.autoGenerateBills("2026-06");
+
+            assertNotNull(result);
+            assertEquals("2026-06", result.get("period"));
+            assertEquals(1, result.get("generatedCount"));
+            verify(waterBillMapper, times(1)).insert(any(WaterBill.class));
+        }
+
+        @Test
+        @DisplayName("手动生成账单 - 已存在时抛异常")
+        void manualGenerateBill_alreadyExists() {
+            when(jdbcTemplate.queryForMap(anyString(), eq(1L))).thenReturn(mockReadingMap());
+            when(waterBillMapper.selectCount(any(LambdaQueryWrapper.class))).thenReturn(1L);
+
+            assertThrows(RuntimeException.class, () -> billService.manualGenerateBill(1L));
+        }
+
+        @Test
+        @DisplayName("手动生成账单 - 正常生成")
+        void manualGenerateBill_success() {
+            when(jdbcTemplate.queryForMap(anyString(), eq(1L))).thenReturn(mockReadingMap());
+            when(waterBillMapper.selectCount(any(LambdaQueryWrapper.class))).thenReturn(0L);
+            when(jdbcTemplate.queryForObject(anyString(), eq(BigDecimal.class), anyString()))
+                    .thenReturn(new BigDecimal("4.20"));
+            when(waterBillMapper.insert(any(WaterBill.class))).thenAnswer(inv -> {
+                WaterBill bill = inv.getArgument(0);
+                bill.setId(1L);
+                return 1;
+            });
+
+            WaterBill result = billService.manualGenerateBill(1L);
+            assertNotNull(result);
+            assertEquals("C001", result.getCustomerNo());
+            assertTrue(result.getTotalAmount().compareTo(BigDecimal.ZERO) > 0);
+        }
+
+        @Test
+        @DisplayName("账单明细查询 - 包含缴费记录")
+        void getBillDetail_withPayments() {
+            WaterBill bill = createMockBill(1L, "BILL-001", "C001", new BigDecimal("100"), new BigDecimal("50"));
+            when(waterBillMapper.selectById(1L)).thenReturn(bill);
+
+            List<Map<String, Object>> payments = List.of(
+                    Map.of("payment_no", "PAY-001", "amount", new BigDecimal("50"), "channel", "counter")
+            );
+            when(jdbcTemplate.queryForList(anyString(), eq(1L))).thenReturn(payments);
+
+            Map<String, Object> detail = billService.getBillDetail(1L);
+            assertNotNull(detail);
+            assertEquals(bill, detail.get("bill"));
+            assertEquals(1, ((List<?>) detail.get("payments")).size());
+            assertEquals(new BigDecimal("50"), detail.get("remainingAmount"));
+        }
+
+        @Test
+        @DisplayName("作废账单 - pending状态可作废")
+        void cancelBill_pending_success() {
+            WaterBill bill = createMockBill(1L, "BILL-001", "C001", new BigDecimal("100"), BigDecimal.ZERO);
+            bill.setStatus("pending");
+            when(waterBillMapper.selectById(1L)).thenReturn(bill);
+            when(waterBillMapper.updateById(any(WaterBill.class))).thenReturn(1);
+
+            billService.cancelBill(1L);
+
+            ArgumentCaptor<WaterBill> captor = ArgumentCaptor.forClass(WaterBill.class);
+            verify(waterBillMapper).updateById(captor.capture());
+            assertEquals("cancelled", captor.getValue().getStatus());
+        }
+
+        @Test
+        @DisplayName("作废账单 - 非pending状态抛异常")
+        void cancelBill_notPending_throwsException() {
+            WaterBill bill = createMockBill(1L, "BILL-001", "C001", new BigDecimal("100"), new BigDecimal("100"));
+            bill.setStatus("paid");
+            when(waterBillMapper.selectById(1L)).thenReturn(bill);
+
+            assertThrows(RuntimeException.class, () -> billService.cancelBill(1L));
+        }
+    }
+
+    // ========== 支付服务测试 ==========
+
+    @Nested
+    @DisplayName("PaymentService - 收费测试")
+    class PaymentTests {
+
+        @Test
+        @DisplayName("柜台收费 - 全额支付")
+        void payByCounter_fullPayment() {
+            WaterBill bill = createMockBill(1L, "BILL-001", "C001", new BigDecimal("100"), BigDecimal.ZERO);
+            when(waterBillMapper.selectById(1L)).thenReturn(bill);
+            when(paymentRecordMapper.insert(any(PaymentRecord.class))).thenAnswer(inv -> {
+                PaymentRecord r = inv.getArgument(0);
+                r.setId(1L);
+                return 1;
+            });
+            when(waterBillMapper.updateById(any(WaterBill.class))).thenReturn(1);
+
+            PaymentRecord result = paymentService.payByCounter(1L, new BigDecimal("100"), 10L, "操作员A");
+
+            assertNotNull(result);
+            assertEquals("counter", result.getChannel());
+            assertEquals("success", result.getStatus());
+            assertEquals(new BigDecimal("100"), result.getAmount());
+        }
+
+        @Test
+        @DisplayName("柜台收费 - 部分支付")
+        void payByCounter_partialPayment() {
+            WaterBill bill = createMockBill(1L, "BILL-001", "C001", new BigDecimal("100"), BigDecimal.ZERO);
+            when(waterBillMapper.selectById(1L)).thenReturn(bill);
+            when(paymentRecordMapper.insert(any(PaymentRecord.class))).thenReturn(1);
+            when(waterBillMapper.updateById(any(WaterBill.class))).thenReturn(1);
+
+            PaymentRecord result = paymentService.payByCounter(1L, new BigDecimal("50"), 10L, "操作员A");
+
+            assertNotNull(result);
+            ArgumentCaptor<WaterBill> captor = ArgumentCaptor.forClass(WaterBill.class);
+            verify(waterBillMapper).updateById(captor.capture());
+            assertEquals("partial", captor.getValue().getStatus());
+        }
+
+        @Test
+        @DisplayName("超额支付 - 抛出异常")
+        void payByCounter_overAmount_throwsException() {
+            WaterBill bill = createMockBill(1L, "BILL-001", "C001", new BigDecimal("100"), BigDecimal.ZERO);
+            when(waterBillMapper.selectById(1L)).thenReturn(bill);
+
+            assertThrows(RuntimeException.class,
+                    () -> paymentService.payByCounter(1L, new BigDecimal("200"), 10L, "操作员A"));
+        }
+
+        @Test
+        @DisplayName("支付宝下单 - 返回支付信息")
+        void payByAlipay_returnsPayInfo() {
+            WaterBill bill = createMockBill(1L, "BILL-001", "C001", new BigDecimal("100"), BigDecimal.ZERO);
+            when(waterBillMapper.selectById(1L)).thenReturn(bill);
+            when(paymentRecordMapper.insert(any(PaymentRecord.class))).thenReturn(1);
+            when(waterBillMapper.updateById(any(WaterBill.class))).thenReturn(1);
+
+            Map<String, Object> result = paymentService.payByAlipay(1L, new BigDecimal("100"));
+
+            assertNotNull(result);
+            assertNotNull(result.get("payForm"));
+            assertNotNull(result.get("tradeNo"));
+        }
+
+        @Test
+        @DisplayName("微信下单 - 返回prepay信息")
+        void payByWechat_returnsPrepayInfo() {
+            WaterBill bill = createMockBill(1L, "BILL-001", "C001", new BigDecimal("100"), BigDecimal.ZERO);
+            when(waterBillMapper.selectById(1L)).thenReturn(bill);
+            when(paymentRecordMapper.insert(any(PaymentRecord.class))).thenReturn(1);
+            when(waterBillMapper.updateById(any(WaterBill.class))).thenReturn(1);
+
+            Map<String, Object> result = paymentService.payByWechat(1L, new BigDecimal("100"));
+
+            assertNotNull(result);
+            assertNotNull(result.get("prepayId"));
+            assertNotNull(result.get("codeUrl"));
+        }
+
+        @Test
+        @DisplayName("支付宝回调 - 成功")
+        void alipayCallback_success() {
+            PaymentRecord record = new PaymentRecord();
+            record.setId(1L);
+            record.setPaymentNo("PAY-001");
+            record.setBillId(1L);
+            record.setAmount(new BigDecimal("100"));
+            record.setStatus("pending");
+
+            when(paymentRecordMapper.selectOne(any(LambdaQueryWrapper.class))).thenReturn(record);
+            when(paymentRecordMapper.updateById(any(PaymentRecord.class))).thenReturn(1);
+
+            WaterBill bill = createMockBill(1L, "BILL-001", "C001", new BigDecimal("100"), BigDecimal.ZERO);
+            when(waterBillMapper.selectById(1L)).thenReturn(bill);
+            when(waterBillMapper.updateById(any(WaterBill.class))).thenReturn(1);
+
+            String result = paymentService.alipayCallback("PAY-001", "ALI123", "TRADE_SUCCESS");
+            assertEquals("success", result);
+        }
+
+        @Test
+        @DisplayName("退费 - 正常退费")
+        void refund_success() {
+            PaymentRecord original = new PaymentRecord();
+            original.setId(1L);
+            original.setPaymentNo("PAY-001");
+            original.setBillId(1L);
+            original.setBillNo("BILL-001");
+            original.setCustomerNo("C001");
+            original.setCustomerName("张三");
+            original.setAmount(new BigDecimal("100"));
+            original.setChannel("counter");
+            original.setChannelName("柜台现金");
+            original.setStatus("success");
+
+            when(paymentRecordMapper.selectById(1L)).thenReturn(original);
+            when(paymentRecordMapper.insert(any(PaymentRecord.class))).thenReturn(1);
+            when(paymentRecordMapper.updateById(any(PaymentRecord.class))).thenReturn(1);
+
+            WaterBill bill = createMockBill(1L, "BILL-001", "C001", new BigDecimal("100"), new BigDecimal("100"));
+            when(waterBillMapper.selectById(1L)).thenReturn(bill);
+            when(waterBillMapper.updateById(any(WaterBill.class))).thenReturn(1);
+
+            PaymentRecord result = paymentService.refund(1L, new BigDecimal("50"), 10L, "操作员B");
+
+            assertNotNull(result);
+            assertEquals("refunded", result.getStatus());
+            assertEquals(new BigDecimal("-50"), result.getAmount());
+        }
+
+        @Test
+        @DisplayName("退费 - 金额超限抛异常")
+        void refund_overAmount_throwsException() {
+            PaymentRecord original = new PaymentRecord();
+            original.setId(1L);
+            original.setAmount(new BigDecimal("100"));
+            original.setStatus("success");
+
+            when(paymentRecordMapper.selectById(1L)).thenReturn(original);
+
+            assertThrows(RuntimeException.class,
+                    () -> paymentService.refund(1L, new BigDecimal("200"), 10L, "操作员B"));
+        }
+    }
+
+    // ========== 支付查询服务测试 ==========
+
+    @Nested
+    @DisplayName("PaymentQueryService - 查询测试")
+    class PaymentQueryTests {
+
+        @Test
+        @DisplayName("按渠道统计")
+        void statsByChannel_returnsStats() {
+            List<Map<String, Object>> mockStats = List.of(
+                    Map.of("channel", "counter", "count", 10L, "total_amount", new BigDecimal("5000")),
+                    Map.of("channel", "alipay", "count", 20L, "total_amount", new BigDecimal("8000"))
+            );
+            when(jdbcTemplate.queryForList(anyString())).thenReturn(mockStats);
+
+            List<Map<String, Object>> result = paymentQueryService.statsByChannel();
+            assertEquals(2, result.size());
+        }
+
+        @Test
+        @DisplayName("收费汇总")
+        void summary_returnsCorrectData() {
+            Map<String, Object> mockSummary = new HashMap<>();
+            mockSummary.put("total_count", 30L);
+            mockSummary.put("total_income", new BigDecimal("13000"));
+            mockSummary.put("total_refund", new BigDecimal("500"));
+            mockSummary.put("customer_count", 15L);
+
+            when(jdbcTemplate.queryForMap(anyString(), any(), any())).thenReturn(mockSummary);
+
+            Map<String, Object> result = paymentQueryService.summary(
+                    LocalDate.of(2026, 6, 1), LocalDate.of(2026, 6, 30));
+
+            assertNotNull(result);
+            assertEquals(30L, result.get("total_count"));
+            assertEquals("2026-06-01", result.get("startDate"));
+            assertEquals("2026-06-30", result.get("endDate"));
+        }
+    }
+
+    // ========== Helper Methods ==========
+
+    private WaterBill createMockBill(Long id, String billNo, String customerNo,
+                                      BigDecimal totalAmount, BigDecimal paidAmount) {
+        WaterBill bill = new WaterBill();
+        bill.setId(id);
+        bill.setBillNo(billNo);
+        bill.setCustomerNo(customerNo);
+        bill.setCustomerName("测试客户");
+        bill.setBillPeriod("2026-06");
+        bill.setWaterUsage(new BigDecimal("30"));
+        bill.setUnitPrice(new BigDecimal("3.50"));
+        bill.setTotalAmount(totalAmount);
+        bill.setPaidAmount(paidAmount);
+        bill.setStatus("pending");
+        bill.setIssueDate(LocalDate.now());
+        bill.setDueDate(LocalDate.now().plusDays(30));
+        bill.setCreatedAt(LocalDateTime.now());
+        bill.setUpdatedAt(LocalDateTime.now());
+        return bill;
+    }
+
+    private Map<String, Object> mockReadingMap() {
+        Map<String, Object> reading = new HashMap<>();
+        reading.put("reading_id", 1L);
+        reading.put("consumption", new BigDecimal("20"));
+        reading.put("prev_reading", new BigDecimal("100"));
+        reading.put("curr_reading", new BigDecimal("120"));
+        reading.put("reading_period", "2026-06");
+        reading.put("meter_no", "M001");
+        reading.put("customer_id", 100L);
+        reading.put("customer_no", "C001");
+        reading.put("customer_name", "张三");
+        reading.put("customer_type", "residential");
+        return reading;
+    }
+}