债务管理 · 完整操作指南 v3.1

已综合2026-07-30前所有实战经验验证

一、债务页面体系

页面	链接	说明
当前欠款	debt.html	未结清欠款一览，按人分块
已结清归档	cleared_debts.html	已结清欠款归档，最新排最上面

二、欠款记录结构

每人一个卡片：

头部：欠款人姓名 + 余额标记
借出（红底）：日期、描述、running-balance（右上角）、-金额（红色）、未结
还款（绿底）：日期、描述、running-balance（右上角）、+金额（绿色）、已转标记
关键：欠款永远是红底 bg-red-50 border-l-4 border-red-400，还款永远是绿底 bg-green-50 border-l-4 border-green-400。不改原欠款颜色和描述。

三、收到付款先查CRM

铁律：用户说"XX转账XX元"→ 先查CRM该人名下是否有unpaid记录。有且金额匹配=还旧账，不是新消费。查不到CRM≠还旧账——再查debt.html上该人是否有同名欠款。

CRM查到	判断	操作
该人有unpaid且金额匹配	还旧账	更新CRM对应ID为paid，debt追加绿底还款→迁入cleared_debts。不追加3.md和CRM新记录
该人无unpaid	新消费	三表联动（3.md+CRM+debt）

四、结清归档流程

保留原欠款红底不动：不改颜色、不改描述、不改金额
追加绿底还款：实际到账日、支付方式、+金额
整块迁入cleared_debts.html顶部：两段式格式（红底欠款+绿底还款），已结清标签不带✅ emoji
从debt.html删除该区块：统计数字对应扣减
更新CRM：对应ID改为paid
git commit + sudo chown -R 1panel:netdev .

cleared_debts.html 格式

<!-- 某人 -->
<div class="bg-white rounded-xl shadow-sm border border-gray-100 mb-3">
  <div class="flex justify-between items-center px-4 py-3 border-b border-gray-100">
    <span class="font-bold text-gray-800 text-base">某人</span>
    <span class="text-sm font-semibold text-green-600 bg-green-50 px-3 py-1 rounded-full">已结清</span>
  </div>
  <div class="p-3">
    <div class="bg-red-50 rounded-lg px-4 py-3 text-sm border-l-4 border-red-400 mb-2">
      <div class="text-xs text-gray-400 mb-1">欠款日期</div>
      <div class="text-gray-700">商品/服务描述</div>
      <span class="running-balance" style="float:right;font-size:11px;color:#888;background:#f0f0f0;padding:1px 6px;border-radius:3px;">欠款余额：金额</span>
      <div class="font-bold text-red-500 text-base mt-1">-金额</div>
      <div class="text-xs text-gray-400 mt-1">未结</div>
    </div>
    <div class="bg-green-50 rounded-lg px-4 py-3 text-sm border-l-4 border-green-400">
      <span class="running-balance" style="float:right;font-size:11px;color:#888;background:#f0f0f0;padding:1px 6px;border-radius:3px;">欠款余额：0</span>
      <div class="text-xs text-gray-400 mb-1">结清日期</div>
      <div class="text-gray-700">支付方式说明</div>
      <div class="font-bold text-green-500 text-base mt-1">+金额</div>
      <div class="text-xs text-gray-400 mt-1">已转王琼 / 微信已转</div>
    </div>
  </div>
</div>

五、编辑铁律

云端优先：改前确认最新版
欠款红底不动：不改颜色不改描述不改金额
还款另起一行绿底：有日期有金额有支付方式
结清=迁走：从debt.html删除，追加到cleared_debts.html顶部
div平衡：改完确认div与/div数量一致
金额千分位：-金额红 +金额绿
人名逐字复制：查name_dict.md或聊天原文
git commit后：sudo chown -R 1panel:netdev .

六、踩坑速查

坑A：收到付款当新销售处理

雷浩扫码3750追加了新CRM记录。实际是还旧账。规则：先查CRM判断新旧。

坑B：cleared_debts缺红底欠款明细

雷浩、尚林归档时只写了绿底。规则：归档必须两段式（红底欠款+绿底还款）。

坑C：git commit后属主错误

CRM报数据加载失败。规则：commit后执行 sudo chown -R 1panel:netdev .

坑D：结清留在debt.html没迁走

刘海洋标记已结清但没移入cleared_debts。规则：结清=从debt删除+迁入cleared_debts。

坑E：把原欠款改成绿色

刘峰前两条欠款被人改成绿底。规则：欠款永远是红底，还款另起一行绿底，不改原记录。

坑F：mt-1">跑到文本里变成乱码符号

cleared_debts.html 张艳冬等共18处 text-gray-400 mb-1" 被旧编辑器写坏成 text-gray-400">mt-1">，📅✅变成乱码。修复：替换为 text-gray-400 mb-1">。

坑G：王琼已转→已转王琼

debt.html 上「王琼已转」需统一改为「已转王琼」。注意 cleared_debts.html 也查一遍。