feat: 新增客户对账单功能

管理员后台新增"客户对账单"页面，按客户+时间段汇总订单和欠款明细，
支持逾期高亮和 CSV 导出。

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

backend/app/api/reconciliation.py

@@ -0,0 +1,100 @@
+"""
+对账模块路由模块
+
+提供客户对账单查询接口，按客户+时间段汇总订单和欠款明细。
+支持 CSV 导出对账明细。
+
+URL 前缀：/api/reconciliation
+权限要求：manager/admin 角色
+"""
+
+from datetime import date
+
+from fastapi import APIRouter, Depends, Query
+from sqlalchemy.orm import Session
+
+from backend.app.api.deps import require_permissions, require_roles
+from backend.app.db import get_db_session
+from backend.app.repositories.reminder_repository import ReminderRepository
+from backend.app.schemas.common import success_payload
+
+router = APIRouter(prefix="/api/reconciliation", tags=["reconciliation"])
+reminder_repository = ReminderRepository()
+
+
+@router.get("/customer-statement")
+def get_customer_statement(
+    customer_id: int = Query(..., gt=0),
+    start_date: date | None = Query(default=None),
+    end_date: date | None = Query(default=None),
+    session: Session = Depends(get_db_session),
+    current_user: dict = Depends(require_roles("manager", "admin")),
+    _permission_user: dict = Depends(require_permissions("order:list")),
+) -> dict:
+    """查询客户对账单：指定客户在时间段内的订单和欠款明细。"""
+    from datetime import date as _date
+
+    customer = reminder_repository.get_customer(session, customer_id)
+    if customer is None:
+        from backend.app.core.error_codes import ErrorCode
+        from backend.app.core.exceptions import AppException
+        raise AppException(code=ErrorCode.NOT_FOUND, message="客户不存在", status_code=404)
+
+    rows = reminder_repository.get_customer_statement(session, customer_id, start_date, end_date)
+
+    orders = []
+    total_amount = 0.0
+    total_arrears = 0.0
+    overdue_amount = 0.0
+    overdue_count = 0
+    today = _date.today()
+
+    for order, arrears in rows:
+        amount = float(order.contract_amount or 0)
+        arrears_amount = float(arrears.arrears_amount or 0) if arrears else 0.0
+        arrears_status = arrears.status if arrears else None
+        due_date = arrears.due_date if arrears else None
+
+        # 逾期判定：状态为 overdue 或 pending 但已过到期日
+        is_overdue = False
+        if arrears and arrears_status == "overdue":
+            is_overdue = True
+        elif arrears and arrears_status == "pending" and due_date and due_date <= today:
+            is_overdue = True
+
+        total_amount += amount
+        if arrears_amount > 0:
+            total_arrears += arrears_amount
+        if is_overdue:
+            overdue_amount += arrears_amount
+            overdue_count += 1
+
+        orders.append({
+            "order_id": order.id,
+            "order_no": order.order_no,
+            "order_status": order.order_status,
+            "contract_amount": amount,
+            "created_at": order.created_at.strftime("%Y-%m-%d %H:%M") if order.created_at else "",
+            "arrears_amount": arrears_amount,
+            "due_date": due_date.strftime("%Y-%m-%d") if due_date else "",
+            "arrears_status": arrears_status,
+            "is_overdue": is_overdue,
+        })
+
+    return success_payload({
+        "customer": {
+            "id": customer.id,
+            "customer_name": customer.customer_name,
+            "mobile": customer.mobile,
+            "settlement_type": customer.settlement_type or "",
+            "settlement_days": customer.settlement_days or 0,
+        },
+        "summary": {
+            "total_orders": len(orders),
+            "total_amount": round(total_amount, 2),
+            "total_arrears": round(total_arrears, 2),
+            "overdue_amount": round(overdue_amount, 2),
+            "overdue_count": overdue_count,
+        },
+        "orders": orders,
+    })

backend/app/api/routes.py

@@ -22,6 +22,7 @@ from backend.app.api.h5_bind_service import router as h5_bind_router
 from backend.app.api.logistics import router as logistics_router
 from backend.app.api.orders import router as orders_router
 from backend.app.api.pricing import router as pricing_router
+from backend.app.api.reconciliation import router as reconciliation_router
 from backend.app.api.sales_flow import router as sales_flow_router
 from backend.app.api.products import router as products_router
 from backend.app.api.reminders import router as reminders_router
@@ -49,6 +50,7 @@ api_router.include_router(ai_router)
 api_router.include_router(reminders_router)
 api_router.include_router(salesman_router)
 api_router.include_router(reports_router)
+api_router.include_router(reconciliation_router)
 api_router.include_router(configs_router)
 api_router.include_router(pricing_router)
 api_router.include_router(audit_logs_router)

backend/app/repositories/reminder_repository.py

@@ -6,7 +6,7 @@
 """
 
 import re
-from datetime import datetime
+from datetime import date, datetime
 
 from sqlalchemy import and_, func, select
 from sqlalchemy.orm import Session
@@ -445,3 +445,37 @@ class ReminderRepository:
                 results.append((order, "picked_stuck"))
                 seen_ids.add(order.id)
         return results
+
+    def get_customer_statement(
+        self,
+        session: Session,
+        customer_id: int,
+        start_date: date | None = None,
+        end_date: date | None = None,
+    ) -> list[tuple[SalesOrder, CustomerArrears | None]]:
+        """查询指定客户在时间段内的订单及欠款明细，用于生成对账单。
+
+        参数:
+            session: 数据库会话
+            customer_id: 客户 ID
+            start_date: 起始日期（含），为 None 时不限制
+            end_date: 截止日期（含），为 None 时不限制
+
+        返回:
+            (订单对象, 欠款记录或None) 的元组列表，按下单时间升序
+        """
+        stmt = (
+            select(SalesOrder, CustomerArrears)
+            .outerjoin(CustomerArrears, CustomerArrears.order_id == SalesOrder.id)
+            .where(
+                SalesOrder.deleted == 0,
+                SalesOrder.customer_id == customer_id,
+                SalesOrder.order_status.notin_(["draft", "pending_approve", "canceled"]),
+            )
+        )
+        if start_date is not None:
+            stmt = stmt.where(func.date(SalesOrder.created_at) >= start_date)
+        if end_date is not None:
+            stmt = stmt.where(func.date(SalesOrder.created_at) <= end_date)
+        stmt = stmt.order_by(SalesOrder.created_at.asc(), SalesOrder.id.asc())
+        return list(session.execute(stmt).all())

frontend/web-admin/src/App.vue

@@ -185,6 +185,7 @@ const allNavGroups = [
         children: [
           { to: "/reports/performance", label: "报表统计", permission: "report:performance:view" },
           { to: "/reports/audit", label: "报表核对", permission: "report:audit:view" },
+          { to: "/reconciliation", label: "客户对账单", permission: "order:list" },
         ],
       },
     ],

frontend/web-admin/src/mockApi.js

@@ -1753,3 +1753,15 @@ export async function batchDeleteUser(ids, permanent = false) {
 export async function batchDeleteRole(ids, permanent = false) {
   return request("/api/system/roles/batch-delete", { method: "POST", body: JSON.stringify({ ids, permanent }) });
 }
+
+// ========== 对账模块 ==========
+
+export async function fetchCustomerStatement(filters = {}) {
+  const query = buildQuery({
+    customer_id: filters.customer_id || undefined,
+    start_date: filters.start_date || undefined,
+    end_date: filters.end_date || undefined,
+  });
+  if (!query) return null;
+  return await request(`/api/reconciliation/customer-statement?${query}`);
+}

frontend/web-admin/src/router.js

@@ -21,6 +21,7 @@ import ReminderCenterPage from "./views/ReminderCenterPage.vue";
 import ReportAuditPage from "./views/ReportAuditPage.vue";
 import AIRecognitionPage from "./views/AIRecognitionPage.vue";
 import BatchMatchLogisticsPage from "./views/BatchMatchLogisticsPage.vue";
+import ReconciliationPage from "./views/ReconciliationPage.vue";
 
 /** 路由表定义 */
 const routes = [
@@ -67,7 +68,9 @@ const routes = [
   /** 业绩报表页面，按时间段和分类查看销售统计 */
   { path: "/reports/performance", component: ReportsPage },
   /** 审计报表页面，查看审计相关的统计报表 */
-  { path: "/reports/audit", component: ReportAuditPage }
+  { path: "/reports/audit", component: ReportAuditPage },
+  /** 客户对账单页面，按客户查看订单和欠款明细 */
+  { path: "/reconciliation", component: ReconciliationPage }
 ];
 
 /**

frontend/web-admin/src/views/ReconciliationPage.vue

@@ -0,0 +1,222 @@
+<template>
+  <div class="reconciliation-page">
+    <h2>客户对账单</h2>
+
+    <!-- 筛选区 -->
+    <div class="toolbar">
+      <div class="filter-group">
+        <label>客户</label>
+        <select v-model="filters.customer_id" @change="handleSearch" class="filter-input">
+          <option value="">请选择客户</option>
+          <option v-for="c in customerOptions" :key="c.id" :value="c.id">
+            {{ c.customer_name }}（{{ c.mobile }}）
+          </option>
+        </select>
+      </div>
+      <div class="filter-group">
+        <label>起始日期</label>
+        <input type="date" v-model="filters.start_date" @change="handleSearch" class="filter-input" />
+      </div>
+      <div class="filter-group">
+        <label>截止日期</label>
+        <input type="date" v-model="filters.end_date" @change="handleSearch" class="filter-input" />
+      </div>
+      <button class="btn btn-primary" @click="handleSearch" :disabled="!filters.customer_id">查询</button>
+      <button class="btn" @click="handleExport" :disabled="!statementData">导出 CSV</button>
+    </div>
+
+    <!-- 加载中 -->
+    <div v-if="loading" class="loading-tip">加载中...</div>
+
+    <!-- 客户信息 + 汇总卡片 -->
+    <template v-if="statementData">
+      <div class="info-cards">
+        <div class="card customer-info">
+          <h3>客户信息</h3>
+          <div class="card-row"><span class="label">客户名称：</span>{{ statementData.customer.customer_name }}</div>
+          <div class="card-row"><span class="label">联系电话：</span>{{ statementData.customer.mobile }}</div>
+          <div class="card-row"><span class="label">结算方式：</span>{{ mapSettlementType(statementData.customer.settlement_type) }}</div>
+          <div class="card-row"><span class="label">账期天数：</span>{{ statementData.customer.settlement_days }}天</div>
+        </div>
+        <div class="card summary-card">
+          <div class="summary-item">
+            <div class="summary-value">{{ statementData.summary.total_orders }}</div>
+            <div class="summary-label">订单总数</div>
+          </div>
+          <div class="summary-item">
+            <div class="summary-value">¥{{ statementData.summary.total_amount.toFixed(2) }}</div>
+            <div class="summary-label">合同总额</div>
+          </div>
+          <div class="summary-item" :class="{ 'has-overdue': statementData.summary.overdue_amount > 0 }">
+            <div class="summary-value">¥{{ statementData.summary.total_arrears.toFixed(2) }}</div>
+            <div class="summary-label">待收金额</div>
+          </div>
+          <div class="summary-item" :class="{ 'has-overdue': statementData.summary.overdue_amount > 0 }">
+            <div class="summary-value">{{ statementData.summary.overdue_count }}</div>
+            <div class="summary-label">逾期笔数</div>
+          </div>
+        </div>
+      </div>
+
+      <!-- 订单明细表格 -->
+      <table class="data-table">
+        <thead>
+          <tr>
+            <th>订单号</th>
+            <th>下单时间</th>
+            <th>订单状态</th>
+            <th class="text-right">合同金额</th>
+            <th class="text-right">欠款金额</th>
+            <th>到期日</th>
+            <th>欠款状态</th>
+          </tr>
+        </thead>
+        <tbody>
+          <tr v-for="row in statementData.orders" :key="row.order_id"
+              :class="{ 'row-overdue': row.is_overdue }">
+            <td>{{ row.order_no }}</td>
+            <td>{{ row.created_at }}</td>
+            <td><span class="status-badge" :class="'status-' + row.order_status">{{ mapOrderStatus(row.order_status) }}</span></td>
+            <td class="text-right">¥{{ row.contract_amount.toFixed(2) }}</td>
+            <td class="text-right">{{ row.arrears_amount > 0 ? '¥' + row.arrears_amount.toFixed(2) : '-' }}</td>
+            <td>{{ row.due_date || '-' }}</td>
+            <td>
+              <span v-if="row.is_overdue" class="status-badge status-overdue">逾期</span>
+              <span v-else-if="row.arrears_status === 'pending'" class="status-badge status-pending">待收</span>
+              <span v-else-if="row.arrears_status" class="status-badge status-settled">已结</span>
+              <span v-else>-</span>
+            </td>
+          </tr>
+          <tr v-if="statementData.orders.length === 0">
+            <td colspan="7" class="empty-tip">暂无数据</td>
+          </tr>
+        </tbody>
+      </table>
+    </template>
+
+    <div v-if="!loading && !statementData" class="empty-tip">请选择客户后点击"查询"查看对账单</div>
+  </div>
+</template>
+
+<script setup>
+import { onMounted, reactive, ref } from 'vue';
+import { fetchCustomerList, fetchCustomerStatement } from '../mockApi';
+
+const loading = ref(false);
+const customerOptions = ref([]);
+const statementData = ref(null);
+
+const filters = reactive({
+  customer_id: '',
+  start_date: '',
+  end_date: '',
+});
+
+const STATUS_MAP = {
+  draft: '草稿', pending_approve: '待审核', approved: '已审批',
+  pending_driver: '待派单', accepted: '已接单', picked_up: '已揽货',
+  pending_logistics: '待发运', in_transit: '运输中', delivered: '已送达',
+  completed: '已完成', settled: '已结算', canceled: '已取消', rejected: '已退回',
+  pending_settle: '待结算',
+};
+
+const SETTLEMENT_MAP = { monthly: '月结', cash: '现结', delivered: '货到付款' };
+
+function mapOrderStatus(status) { return STATUS_MAP[status] || status; }
+function mapSettlementType(type) { return SETTLEMENT_MAP[type] || type || '未设置'; }
+
+async function loadCustomerOptions() {
+  try {
+    const data = await fetchCustomerList({ page_no: 1, page_size: 500 });
+    customerOptions.value = data.rows || [];
+  } catch { /* ignore */ }
+}
+
+async function handleSearch() {
+  if (!filters.customer_id) return;
+  loading.value = true;
+  statementData.value = null;
+  try {
+    statementData.value = await fetchCustomerStatement(filters);
+  } catch (e) {
+    alert('查询失败：' + e.message);
+  } finally {
+    loading.value = false;
+  }
+}
+
+function handleExport() {
+  if (!statementData.value) return;
+  const rows = statementData.value.orders;
+  const header = ['订单号', '下单时间', '订单状态', '合同金额', '欠款金额', '到期日', '欠款状态'];
+  const lines = [header.join(',')];
+  for (const r of rows) {
+    lines.push([
+      r.order_no,
+      r.created_at,
+      mapOrderStatus(r.order_status),
+      r.contract_amount.toFixed(2),
+      r.arrears_amount > 0 ? r.arrears_amount.toFixed(2) : '',
+      r.due_date || '',
+      r.is_overdue ? '逾期' : (r.arrears_status === 'pending' ? '待收' : (r.arrears_status || '')),
+    ].join(','));
+  }
+  const blob = new Blob(['' + lines.join('\n')], { type: 'text/csv;charset=utf-8;' });
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = `对账单_${statementData.value.customer.customer_name}_${filters.start_date || '全部'}_${filters.end_date || '全部'}.csv`;
+  a.click();
+  URL.revokeObjectURL(url);
+}
+
+onMounted(() => { loadCustomerOptions(); });
+</script>
+
+<style scoped>
+.reconciliation-page { padding: 24px; }
+h2 { margin-bottom: 16px; font-size: 20px; }
+
+.toolbar { display: flex; align-items: flex-end; gap: 12px; margin-bottom: 16px; flex-wrap: wrap; }
+.filter-group { display: flex; flex-direction: column; gap: 4px; }
+.filter-group label { font-size: 12px; color: #666; }
+.filter-input { padding: 6px 10px; border: 1px solid #ddd; border-radius: 4px; font-size: 14px; min-width: 180px; }
+
+.btn { padding: 6px 16px; border: 1px solid #ddd; border-radius: 4px; background: #fff; cursor: pointer; font-size: 14px; }
+.btn-primary { background: #1890ff; color: #fff; border-color: #1890ff; }
+.btn:disabled { opacity: 0.5; cursor: not-allowed; }
+
+.info-cards { display: grid; grid-template-columns: 1fr 2fr; gap: 16px; margin-bottom: 16px; }
+.card { background: #fff; border: 1px solid #e8e8e8; border-radius: 6px; padding: 16px; }
+.card h3 { margin: 0 0 10px; font-size: 14px; color: #333; }
+.card-row { font-size: 13px; line-height: 1.8; }
+.card-row .label { color: #999; }
+
+.summary-card { display: flex; gap: 24px; align-items: center; justify-content: center; }
+.summary-item { text-align: center; }
+.summary-value { font-size: 22px; font-weight: 600; color: #333; }
+.summary-label { font-size: 12px; color: #999; margin-top: 4px; }
+.has-overdue .summary-value { color: #f5222d; }
+
+.data-table { width: 100%; border-collapse: collapse; background: #fff; border: 1px solid #e8e8e8; border-radius: 6px; }
+.data-table th { background: #fafafa; padding: 10px 12px; text-align: left; font-size: 13px; color: #666; border-bottom: 1px solid #e8e8e8; }
+.data-table td { padding: 10px 12px; font-size: 13px; border-bottom: 1px solid #f0f0f0; }
+.text-right { text-align: right; }
+.row-overdue { background: #fff1f0; }
+.empty-tip { text-align: center; padding: 40px; color: #999; }
+
+.status-badge { display: inline-block; padding: 2px 8px; border-radius: 3px; font-size: 12px; }
+.status-in_transit { background: #e6f7ff; color: #1890ff; }
+.status-delivered { background: #f6ffed; color: #52c41a; }
+.status-completed { background: #f6ffed; color: #52c41a; }
+.status-settled { background: #f6ffed; color: #52c41a; }
+.status-pending { background: #fffbe6; color: #faad14; }
+.status-pending_settle { background: #fffbe6; color: #faad14; }
+.status-overdue { background: #fff1f0; color: #f5222d; }
+.status-canceled { background: #f5f5f5; color: #999; }
+.status-rejected { background: #f5f5f5; color: #999; }
+.status-draft { background: #f5f5f5; color: #999; }
+.status-pending_approve { background: #fffbe6; color: #faad14; }
+
+.loading-tip { text-align: center; padding: 40px; color: #999; }
+</style>