aria-code 0.52.0__py3-none-any.whl

aria_code/agents/realty/contract_rules.py

@@ -0,0 +1,210 @@
+"""
+agents/realty/contract_rules.py — 合同规则 Agent
+=================================================
+将业务谈判结果转化为合同条款和分账规则草案。
+
+输入数据（data dict keys）:
+    negotiation     — 谈判结果摘要（保底/分润比例/结算周期/退出条件等）
+    asset_info      — 资产基础信息
+    operator_info   — 经营方信息（资质/历史数据等）
+
+输出:
+    analysis    — 合同条款草案文本
+    signal      — GOOD=条款清晰可执行 / WATCH=需补充条款 / CONCERN=有重大风险条款
+                  （地产健康度尺度，见 signal_scheme.py）
+    key_points  — 关键条款摘要（保底金额/分润比例/结算周期/违约条款）
+"""
+from __future__ import annotations
+
+from decimal import Decimal, ROUND_HALF_UP
+from typing import Any, Dict, List, Optional
+from ..base import BaseAgent, AgentResult
+
+
+class ContractRulesAgent(BaseAgent):
+    name        = "contract_rules"
+    description = "合同规则生成：将谈判结果结构化为可执行的合同条款和分账规则草案"
+
+    _SYSTEM = (
+        "你是一名专业的不动产运营合同起草顾问。\n"
+        "你的任务是根据谈判结果，生成结构化的合同条款草案，包含：\n"
+        "  1. 经营权共创模式说明（资产方不转让产权，基于使用权获得收益）\n"
+        "  2. 收益分配规则：保底收益、流水分润计算方式、阶梯分成规则\n"
+        "  3. 结算周期与结算方式\n"
+        "  4. 保证金条款（金额、用途、退还条件）\n"
+        "  5. 风险准备金（比例、用途）\n"
+        "  6. 平台服务费（比例或固定金额）\n"
+        "  7. 退出条款（提前退出违约金、清算顺序）\n"
+        "  8. 开业义务与履约要求\n\n"
+        "输出要求：\n"
+        "- 每个条款必须包含：条款名称、具体数值、计算公式（如适用）\n"
+        "- 标注 [系统可执行] / [需人工确认] / [建议律师审核]\n"
+        "- 最后给出：合同风险评级 [低/中/高] 及主要风险点"
+    )
+
+    async def analyze(self, symbol: str, data: Dict[str, Any]) -> AgentResult:
+        nego     = data.get("negotiation", {})
+        asset    = data.get("asset_info", {})
+        operator = data.get("operator_info", {})
+
+        # 解析谈判关键数值（兼容多种字段命名）
+        guaranteed    = nego.get("guaranteed_amount",
+                                 nego.get("guaranteed_monthly", 0))
+        revenue_share = nego.get("revenue_share_pct", 0)
+        base_revenue  = nego.get("base_revenue",
+                                 nego.get("revenue_share_base", 0))
+        tiered_rules  = nego.get("tiered_rules", [])
+        settle_cycle  = nego.get("settlement_cycle", "monthly")
+        # 保证金：直接金额 > deposit_months × 保底 > 0
+        deposit_months = nego.get("deposit_months", 0)
+        deposit = nego.get("deposit_amount",
+                           nego.get("deposit",
+                                    guaranteed * deposit_months if deposit_months else 0))
+        risk_reserve  = nego.get("risk_reserve_pct", 3)
+        platform_fee  = nego.get("platform_fee_pct", 5)
+        contract_years= nego.get("contract_years", 1)
+        exit_penalty  = nego.get("exit_penalty_months", 3)
+
+        user_prompt = (
+            f"谈判结果：\n"
+            f"  保底收益: {guaranteed:,}元/月\n"
+            f"  流水分润: 月流水超过{base_revenue:,}元后按{revenue_share}%分润\n"
+            f"  阶梯规则: {tiered_rules or '无阶梯'}\n"
+            f"  结算周期: {settle_cycle}\n"
+            f"  保证金: {deposit:,}元\n"
+            f"  风险准备金: 流水的{risk_reserve}%\n"
+            f"  平台服务费: 流水的{platform_fee}%\n"
+            f"  合同年限: {contract_years}年\n"
+            f"  提前退出违约: {exit_penalty}个月保底金额\n\n"
+            f"资产信息: {asset.get('name','未命名')} ({asset.get('area',0)}m²)\n"
+            f"经营方: {operator.get('name','未知')} "
+            f"(行业: {operator.get('industry','未知')})\n\n"
+            "请生成完整的合同条款草案。"
+        )
+
+        analysis = await self._call_llm(self._SYSTEM, user_prompt, max_tokens=1000)
+        if not analysis:
+            analysis = _template_contract(nego, asset, operator)
+
+        # 结构化规则供系统执行
+        structured = _build_structured_rules(nego)
+        signal     = _contract_signal(nego)
+        confidence = _contract_confidence(nego)
+        key_points = _contract_key_points(nego, structured)
+
+        return AgentResult(
+            agent      = self.name,
+            symbol     = symbol,
+            analysis   = analysis,
+            confidence = confidence,
+            signal     = signal,
+            key_points = key_points,
+            data_used  = {"structured_rules": structured, "negotiation": nego},
+        )
+
+
+# ── 辅助函数 ──────────────────────────────────────────────────────────────────
+
+def _build_structured_rules(nego: Dict) -> Dict:
+    """生成系统可直接执行的分账规则 JSON（兼容多种字段命名）"""
+    _g             = nego.get("guaranteed_amount", nego.get("guaranteed_monthly", 0))
+    guaranteed     = Decimal(str(_g))
+    share_pct      = Decimal(str(nego.get("revenue_share_pct", 0)))
+    base_revenue   = Decimal(str(nego.get("base_revenue", nego.get("revenue_share_base", 0))))
+    risk_reserve   = Decimal(str(nego.get("risk_reserve_pct", 3)))
+    platform_fee   = Decimal(str(nego.get("platform_fee_pct", 5)))
+    _dm            = nego.get("deposit_months", 0)
+    deposit        = Decimal(str(nego.get("deposit_amount",
+                                          nego.get("deposit",
+                                                   float(_g) * _dm if _dm else 0))))
+
+    return {
+        "guaranteed_monthly":   float(guaranteed),
+        "revenue_share_pct":    float(share_pct),
+        "revenue_share_base":   float(base_revenue),
+        "risk_reserve_pct":     float(risk_reserve),
+        "platform_fee_pct":     float(platform_fee),
+        "deposit_amount":       float(deposit),
+        "settlement_cycle":     nego.get("settlement_cycle", "monthly"),
+        "tiered_rules":         nego.get("tiered_rules", []),
+        "contract_years":       nego.get("contract_years", 1),
+        "exit_penalty_months":  nego.get("exit_penalty_months", 3),
+    }
+
+
+def _contract_signal(nego: Dict) -> str:
+    issues = 0
+    if not (nego.get("guaranteed_amount") or nego.get("guaranteed_monthly")): issues += 1
+    if not nego.get("revenue_share_pct"):  issues += 1
+    if not (nego.get("deposit") or nego.get("deposit_amount") or nego.get("deposit_months")): issues += 1
+    if not nego.get("settlement_cycle"):   issues += 1
+    if not nego.get("contract_years"):     issues += 1
+
+    if issues == 0:  return "GOOD"
+    if issues <= 2:  return "WATCH"
+    return "CONCERN"
+
+
+def _contract_confidence(nego: Dict) -> float:
+    keys_pairs = [
+        ("guaranteed_amount", "guaranteed_monthly"),
+        ("revenue_share_pct",),
+        ("base_revenue", "revenue_share_base"),
+        ("deposit", "deposit_amount", "deposit_months"),
+        ("settlement_cycle",),
+        ("contract_years",),
+    ]
+    filled = sum(1 for kp in keys_pairs if any(nego.get(k) for k in kp))
+    return round(0.4 + 0.1 * filled, 2)
+
+
+def _contract_key_points(nego: Dict, rules: Dict) -> List[str]:
+    pts = []
+    g = rules.get("guaranteed_monthly", 0)
+    s = rules.get("revenue_share_pct", 0)
+    b = rules.get("revenue_share_base", 0)
+    d = rules.get("deposit_amount", 0)
+    c = rules.get("settlement_cycle", "monthly")
+    yrs = rules.get("contract_years", 1)
+
+    if g:  pts.append(f"保底收益: {g:,.0f}元/月（年合计 {g*12:,.0f}元）")
+    if s:  pts.append(f"流水分润: 超过{b:,.0f}元后按{s}%分润")
+    if d:  pts.append(f"保证金: {d:,.0f}元（合同结束后退还）")
+    if c:  pts.append(f"结算周期: {c}")
+    if yrs: pts.append(f"合同年限: {yrs}年，到期可续签")
+    return pts[:5]
+
+
+def _template_contract(nego: Dict, asset: Dict, operator: Dict) -> str:
+    g  = nego.get("guaranteed_amount", nego.get("guaranteed_monthly", 0))
+    s  = nego.get("revenue_share_pct", 0)
+    b  = nego.get("base_revenue", nego.get("revenue_share_base", 0))
+    dm = nego.get("deposit_months", 0)
+    d  = nego.get("deposit_amount", nego.get("deposit", g * dm if dm else 0))
+    rf = nego.get("risk_reserve_pct", 3)
+    pf = nego.get("platform_fee_pct", 5)
+    ep = nego.get("exit_penalty_months", 3)
+    c  = nego.get("settlement_cycle", "月结")
+    y  = nego.get("contract_years", 1)
+
+    return (
+        f"经营权共创合同规则草案（模板）\n"
+        f"{'='*40}\n"
+        f"资产方：{asset.get('owner','待确认')}    经营方：{operator.get('name','待确认')}\n"
+        f"标的资产：{asset.get('name','未命名')} ({asset.get('area',0)}m²)\n\n"
+        f"第一条 收益分配规则\n"
+        f"  1.1 保底收益: {g:,}元/月 [系统可执行]\n"
+        f"  1.2 流水分润: 月流水超过{b:,}元后，资产方按{s}%分润 [系统可执行]\n"
+        f"  1.3 平台服务费: 月流水的{pf}% [系统可执行]\n"
+        f"  1.4 风险准备金: 月流水的{rf}%，累计至3个月保底额度后暂停 [系统可执行]\n\n"
+        f"第二条 结算条款\n"
+        f"  2.1 结算周期: {c} [系统可执行]\n"
+        f"  2.2 保底补足: 当月流水分润低于保底金额时，由经营方补足差额 [需人工确认]\n\n"
+        f"第三条 保证金\n"
+        f"  3.1 保证金: {d:,}元，签约时一次性缴纳 [需人工确认]\n"
+        f"  3.2 用途: 用于弥补违约、欠费等损失 [系统可执行]\n\n"
+        f"第四条 合同期限与退出\n"
+        f"  4.1 合同年限: {y}年 [系统可执行]\n"
+        f"  4.2 提前退出违约金: {ep}个月保底金额（即{g*ep:,}元）[需人工确认]\n\n"
+        f"【风险评级: {'低' if g>0 and d>0 else '中'}】[建议律师审核]"
+    )

aria_code/agents/realty/energy_anomaly.py

@@ -0,0 +1,189 @@
+"""
+agents/realty/energy_anomaly.py — 能耗异常 Agent
+=================================================
+用水电、门禁、停车、客流判断经营状态，识别：空置/低效/超范围/欠费/异常经营。
+
+输入数据（data dict keys）:
+    energy_records  — 水电用量历史（按日/周/月）
+    access_records  — 门禁/访客记录
+    parking_records — 停车记录
+    foot_traffic    — 客流数据
+    revenue_data    — 对应期营业流水（用于交叉验证）
+    benchmarks      — 同业基准值（可选）
+
+输出:
+    analysis    — 能耗分析报告
+    signal      — GOOD=正常 / WATCH=轻度异常 / CONCERN=中度异常 / SEVERE=严重异常/疑似空置
+                  （地产健康度尺度，见 signal_scheme.py）
+    key_points  — 异常指标清单
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List
+from ..base import BaseAgent, AgentResult
+
+
+class EnergyAnomalyAgent(BaseAgent):
+    name        = "energy_anomaly"
+    description = "能耗异常：交叉分析水电、门禁、客流与流水，识别空置/低效/异常经营"
+
+    _SYSTEM = (
+        "你是一名商业空间运营监控专家，擅长通过能耗和空间数据识别异常经营行为。\n"
+        "请对能耗分析结果进行解读：\n"
+        "  1. 水电用量是否与营业流水匹配（高流水应有高能耗）\n"
+        "  2. 门禁/客流记录是否与营业时段一致\n"
+        "  3. 是否存在非营业时段用电（可能夜间经营未申报）\n"
+        "  4. 能耗趋势分析（是否逐月下降，可能经营在减少）\n"
+        "  5. 综合判断：[正常经营] / [低效经营] / [空置] / [疑似违规经营] / [超范围经营]\n"
+        "  6. 处置建议（巡检、整改、补缴水电费等）"
+    )
+
+    async def analyze(self, symbol: str, data: Dict[str, Any]) -> AgentResult:
+        energy  = data.get("energy_records", {})
+        access  = data.get("access_records", {})
+        parking = data.get("parking_records", {})
+        traffic = data.get("foot_traffic", {})
+        revenue = data.get("revenue_data", {})
+        bench   = data.get("benchmarks", {})
+
+        check = _analyze_energy(energy, access, parking, traffic, revenue, bench)
+
+        user_prompt = (
+            f"能耗分析数据：\n"
+            f"  本期用电: {energy.get('electricity_kwh',0):.1f} kWh  "
+            f"  用水: {energy.get('water_tons',0):.1f} 吨\n"
+            f"  环比变化: 用电{check['elec_change_pct']:+.1f}%  用水{check['water_change_pct']:+.1f}%\n"
+            f"  门禁进出: {access.get('entry_count',0)}次/期  停车: {parking.get('vehicle_count',0)}辆/期\n"
+            f"  客流量: {traffic.get('total_visits',0)}人次\n"
+            f"  营业流水: {revenue.get('declared',0):,.2f}元\n"
+            f"  每千元流水能耗: {check['energy_per_revenue']:.2f} kWh\n"
+            f"  基准能耗/千元: {bench.get('energy_per_1k_revenue', 2.5):.2f} kWh\n\n"
+            f"发现异常：\n"
+            + "\n".join(f"  - {a}" for a in check["anomalies"])
+            + "\n\n请完成能耗异常分析报告。"
+        )
+
+        analysis = await self._call_llm(self._SYSTEM, user_prompt, max_tokens=600)
+        if not analysis:
+            analysis = _template_energy(check, energy, revenue)
+
+        signal     = _energy_signal(check)
+        confidence = _energy_confidence(check)
+        key_points = _energy_key_points(check, energy)
+
+        return AgentResult(
+            agent      = self.name,
+            symbol     = symbol,
+            analysis   = analysis,
+            confidence = confidence,
+            signal     = signal,
+            key_points = key_points,
+            data_used  = {"energy_check": check},
+        )
+
+
+# ── 核验逻辑 ──────────────────────────────────────────────────────────────────
+
+def _analyze_energy(
+    energy: Dict, access: Dict, parking: Dict,
+    traffic: Dict, revenue: Dict, bench: Dict,
+) -> Dict:
+    elec      = energy.get("electricity_kwh", 0)
+    elec_prev = energy.get("prev_electricity_kwh", elec)
+    water     = energy.get("water_tons", 0)
+    water_prev= energy.get("prev_water_tons", water)
+    rev       = revenue.get("declared", 0)
+    entries   = access.get("entry_count", 0)
+    vehicles  = parking.get("vehicle_count", 0)
+    visits    = traffic.get("total_visits", 0)
+
+    elec_change  = (elec - elec_prev) / elec_prev * 100 if elec_prev else 0
+    water_change = (water - water_prev) / water_prev * 100 if water_prev else 0
+
+    # 每千元流水能耗
+    energy_per_rev = elec / (rev / 1000) if rev > 0 else 0
+    bench_per_rev  = bench.get("energy_per_1k_revenue", 2.5)
+
+    anomalies = []
+
+    # 空置判断（低能耗 + 低流水 + 低门禁）
+    if elec < 10 and rev < 1000 and entries < 5:
+        anomalies.append("水电用量极低且无门禁记录，疑似空置状态")
+
+    # 能耗与流水不匹配
+    if rev > 0 and energy_per_rev > bench_per_rev * 3:
+        anomalies.append(f"能耗/流水比异常偏高（{energy_per_rev:.2f}）,可能有黑账")
+    elif rev > 0 and energy_per_rev < bench_per_rev * 0.3 and elec > 50:
+        anomalies.append("高能耗配合低流水，疑似流水漏报或私账")
+
+    # 能耗持续下降
+    if elec_change < -30:
+        anomalies.append(f"用电量环比下降{abs(elec_change):.1f}%，经营规模可能在萎缩")
+
+    # 非营业时段用电（能耗数据需细化到时段）
+    night_elec = energy.get("night_electricity_kwh", 0)
+    if night_elec > elec * 0.4:
+        anomalies.append(f"夜间用电占比{night_elec/elec*100:.1f}%偏高，可能存在夜间未申报经营")
+
+    # 门禁/客流 vs 流水
+    if visits > 0 and rev > 0:
+        revenue_per_visit = rev / visits
+        bench_rpv = bench.get("revenue_per_visit", 50)
+        if revenue_per_visit < bench_rpv * 0.3:
+            anomalies.append(f"人均消费{revenue_per_visit:.1f}元/人远低于基准{bench_rpv}元，流水疑似偏低")
+
+    # 水费欠缴
+    if energy.get("water_arrears", 0) > 0:
+        anomalies.append(f"水费欠缴: {energy['water_arrears']:,.2f}元")
+    if energy.get("electricity_arrears", 0) > 0:
+        anomalies.append(f"电费欠缴: {energy['electricity_arrears']:,.2f}元")
+
+    return {
+        "elec_kwh":           elec,
+        "water_tons":         water,
+        "elec_change_pct":    elec_change,
+        "water_change_pct":   water_change,
+        "energy_per_revenue": energy_per_rev,
+        "bench_per_revenue":  bench_per_rev,
+        "entries":            entries,
+        "vehicles":           vehicles,
+        "visits":             visits,
+        "anomalies":          anomalies,
+        "anomaly_count":      len(anomalies),
+    }
+
+
+def _energy_signal(check: Dict) -> str:
+    n = check.get("anomaly_count", 0)
+    if n == 0: return "GOOD"
+    if n == 1: return "WATCH"
+    if n == 2: return "CONCERN"
+    return "SEVERE"
+
+
+def _energy_confidence(check: Dict) -> float:
+    sources = sum(1 for k in ["elec_kwh", "entries", "visits"] if check.get(k, 0) > 0)
+    return round(min(0.9, 0.5 + 0.15 * sources), 2)
+
+
+def _energy_key_points(check: Dict, energy: Dict) -> List[str]:
+    pts = [f"用电 {check['elec_kwh']:.1f} kWh（环比{check['elec_change_pct']:+.1f}%）"
+           f"  用水 {check['water_tons']:.1f} 吨"]
+    pts.append(f"门禁进出 {check['entries']} 次  客流 {check['visits']} 人次")
+    for a in check["anomalies"][:3]:
+        pts.append(f"异常: {a}")
+    return pts[:5]
+
+
+def _template_energy(check: Dict, energy: Dict, revenue: Dict) -> str:
+    status = "正常" if check["anomaly_count"] == 0 else f"发现 {check['anomaly_count']} 项异常"
+    return (
+        f"能耗异常分析（模板）：\n"
+        f"  用电: {check['elec_kwh']:.1f} kWh  用水: {check['water_tons']:.1f} 吨\n"
+        f"  门禁: {check['entries']}次  客流: {check['visits']}人次\n"
+        f"  营业流水: {revenue.get('declared',0):,.2f}元\n"
+        f"  每千元能耗: {check['energy_per_revenue']:.2f} kWh（基准{check['bench_per_revenue']:.2f}）\n"
+        f"  核验状态: {status}\n"
+        + ("  异常项目:\n" + "\n".join(f"    • {a}" for a in check["anomalies"])
+           if check["anomalies"] else "  无异常")
+    )

aria_code/agents/realty/exit_settlement.py

@@ -0,0 +1,208 @@
+"""
+agents/realty/exit_settlement.py — 退出清算 Agent
+==================================================
+项目到期、提前终止或换经营方时，生成清算方案。
+
+输入数据（data dict keys）:
+    project_info    — 项目基本信息（合同期限/实际开始结束时间）
+    financials      — 财务数据（未结收入/欠费/保证金/预收款/违约情况）
+    asset_condition — 资产现状（装修状态/设备清单/改造情况）
+    exit_reason     — 退出原因（到期/提前/违约/经营失败/换经营方）
+
+输出:
+    analysis    — 清算方案草案
+    signal      — GOOD=清算顺利无纠纷 / WATCH=有待确认项 / CONCERN=存在较大争议
+                  （地产健康度尺度，见 signal_scheme.py）
+    key_points  — 各方清算金额摘要
+    data_used   — 包含 settlement_result（结构化清算数据）
+"""
+from __future__ import annotations
+
+from decimal import Decimal, ROUND_HALF_UP
+from typing import Any, Dict, List
+from ..base import BaseAgent, AgentResult
+
+
+class ExitSettlementAgent(BaseAgent):
+    name        = "exit_settlement"
+    description = "退出清算：生成退出方案（欠费扣除/保证金处理/设备交接/违约金计算）"
+
+    _SYSTEM = (
+        "你是一名专业的不动产合同清算顾问，处理经营权共创项目的退出和清算。\n"
+        "请根据以下数据生成清算草案：\n"
+        "  1. 未结收入清算（未付保底/分润账单合计）\n"
+        "  2. 保证金处理（全额退还/部分扣除/全额扣除 + 依据）\n"
+        "  3. 违约金计算（若有违约，按合同规则计算金额）\n"
+        "  4. 预收款退还（如有预付款未消耗部分）\n"
+        "  5. 装修与设备处理（保留/赔偿/折旧计算）\n"
+        "  6. 最终各方应收/应付金额汇总\n"
+        "  7. 交接清单（钥匙/设备/合同/数据/账户注销）\n"
+        "  8. 建议处置时间表（7日内/30日内完成）\n\n"
+        "标注每项条款是否为 [系统可计算] / [需人工确认] / [建议律师处理]"
+    )
+
+    async def analyze(self, symbol: str, data: Dict[str, Any]) -> AgentResult:
+        project   = data.get("project_info", {})
+        fin       = data.get("financials", {})
+        asset     = data.get("asset_condition", {})
+        reason    = data.get("exit_reason", "到期终止")
+
+        settlement = _calculate_settlement(project, fin, asset, reason)
+
+        user_prompt = (
+            f"退出清算信息：\n"
+            f"  项目: {project.get('name','未命名')}  退出原因: {reason}\n"
+            f"  合同到期: {project.get('contract_end','未知')}  实际退出: {project.get('actual_exit','未知')}\n\n"
+            f"财务状况：\n"
+            f"  未结账单: {settlement['unpaid_invoices']:,.2f}元\n"
+            f"  保证金: {fin.get('deposit_amount',0):,.2f}元  "
+            f"  可扣除: {settlement['deposit_deductible']:,.2f}元\n"
+            f"  违约金: {settlement['penalty']:,.2f}元（{reason}）\n"
+            f"  预收款退还: {settlement['prepayment_refund']:,.2f}元\n"
+            f"  装修/设备折旧: {settlement['depreciation_deduction']:,.2f}元\n\n"
+            f"最终清算：\n"
+            f"  经营方应付平台/资产方: {settlement['operator_owes']:,.2f}元\n"
+            f"  平台/资产方应退经营方: {settlement['platform_owes']:,.2f}元\n"
+            f"  净结算金额: {settlement['net_settlement']:,.2f}元"
+            f"（{'经营方需支付' if settlement['net_settlement'] > 0 else '平台需退还'}）\n\n"
+            "请生成完整清算草案。"
+        )
+
+        analysis = await self._call_llm(self._SYSTEM, user_prompt, max_tokens=900)
+        if not analysis:
+            analysis = _template_settlement(settlement, project, reason)
+
+        signal     = _settlement_signal(settlement, reason)
+        confidence = _settlement_confidence(fin)
+        key_points = _settlement_key_points(settlement)
+
+        return AgentResult(
+            agent      = self.name,
+            symbol     = symbol,
+            analysis   = analysis,
+            confidence = confidence,
+            signal     = signal,
+            key_points = key_points,
+            data_used  = {"settlement_result": settlement},
+        )
+
+
+# ── 清算计算逻辑 ──────────────────────────────────────────────────────────────
+
+def _calculate_settlement(
+    project: Dict, fin: Dict, asset: Dict, reason: str,
+) -> Dict:
+    D = Decimal
+
+    deposit       = D(str(fin.get("deposit_amount", 0)))
+    unpaid        = D(str(fin.get("unpaid_invoices", 0)))
+    # 兼容 prepayment_received / prepayment 两种命名
+    prepayment    = D(str(fin.get("prepayment_received", fin.get("prepayment", 0))))
+    prepaid_used  = D(str(fin.get("prepayment_used", 0)))
+    guaranteed    = D(str(fin.get("guaranteed_monthly", 0)))
+    exit_penalty_months = D(str(fin.get("exit_penalty_months", 3)))
+
+    # 折旧计算：renovation_cost 可在 financials 或 asset_condition 中
+    reno_cost     = D(str(asset.get("renovation_cost",
+                                    fin.get("renovation_cost", 0))))
+    contract_yrs  = D(str(project.get("contract_years", 1)))
+    used_months   = D(str(project.get("used_months", 12)))
+    contract_months = contract_yrs * 12
+    if contract_months > 0:
+        remaining_ratio = max(D("0"), (contract_months - used_months) / contract_months)
+    else:
+        remaining_ratio = D("0")
+    depreciation  = (reno_cost * remaining_ratio).quantize(D("0.01"), ROUND_HALF_UP)
+
+    # 违约金计算
+    is_breach = reason in ("提前退出", "违约", "经营违规")
+    penalty = (guaranteed * exit_penalty_months
+               ).quantize(D("0.01"), ROUND_HALF_UP) if is_breach else D("0")
+
+    # 预收款退还（未消耗部分）
+    prepayment_refund = max(D("0"), prepayment - prepaid_used)
+
+    # 保证金可扣除项
+    deposit_deductible = min(deposit, unpaid + penalty)
+
+    # 汇总
+    operator_owes = unpaid + penalty + depreciation
+    platform_owes = prepayment_refund + max(D("0"), deposit - deposit_deductible)
+    net = (operator_owes - platform_owes).quantize(D("0.01"), ROUND_HALF_UP)
+
+    return {
+        "unpaid_invoices":      float(unpaid),
+        "deposit_amount":       float(deposit),
+        "deposit_deductible":   float(deposit_deductible),
+        "penalty":              float(penalty),
+        "prepayment_refund":    float(prepayment_refund),
+        "depreciation_deduction": float(depreciation),
+        "operator_owes":        float(operator_owes),
+        "platform_owes":        float(platform_owes),
+        "net_settlement":       float(net),
+        "is_breach":            is_breach,
+    }
+
+
+def _settlement_signal(s: Dict, reason: str) -> str:
+    if s["net_settlement"] > 0 and not s["is_breach"]:
+        return "WATCH"    # 经营方有欠款但无违约，需催收
+    if s["is_breach"] and s["net_settlement"] > 0:
+        return "CONCERN"  # 违约且有欠款
+    if s["operator_owes"] == 0 and s["platform_owes"] == 0:
+        return "GOOD"      # 干净退出
+    return "WATCH"
+
+
+def _settlement_confidence(fin: Dict) -> float:
+    keys = ["deposit_amount", "unpaid_invoices", "guaranteed_monthly", "exit_penalty_months"]
+    filled = sum(1 for k in keys if fin.get(k))
+    return round(0.5 + 0.12 * filled, 2)
+
+
+def _settlement_key_points(s: Dict) -> List[str]:
+    pts = [f"未结账单: {s['unpaid_invoices']:,.2f}元"]
+    if s["penalty"] > 0:
+        pts.append(f"违约金: {s['penalty']:,.2f}元")
+    pts.append(f"保证金: {s['deposit_amount']:,.2f}元  可扣除: {s['deposit_deductible']:,.2f}元")
+    if s["prepayment_refund"] > 0:
+        pts.append(f"预收款退还: {s['prepayment_refund']:,.2f}元")
+    direction = "经营方付" if s["net_settlement"] > 0 else "平台退"
+    pts.append(f"净结算: {abs(s['net_settlement']):,.2f}元（{direction}）")
+    return pts[:5]
+
+
+def _template_settlement(s: Dict, project: Dict, reason: str) -> str:
+    penalty_line = (
+        "违约金: {:,.2f}元".format(s['penalty'])
+        if s['penalty'] > 0 else "无违约金（正常到期）"
+    )
+    return (
+        f"退出清算草案（模板）\n"
+        f"{'='*40}\n"
+        f"项目: {project.get('name','未命名')}  退出原因: {reason}\n\n"
+        f"一、应收账款清算\n"
+        f"  未结账单合计: {s['unpaid_invoices']:,.2f}元 [系统可计算]\n\n"
+        f"二、违约金\n"
+        f"  {penalty_line} [系统可计算]\n\n"
+        f"三、保证金处理\n"
+        f"  保证金总额: {s['deposit_amount']:,.2f}元\n"
+        f"  扣除欠款后退还: {s['deposit_amount'] - s['deposit_deductible']:,.2f}元 [需人工确认]\n\n"
+        f"四、预收款退还\n"
+        f"  应退预收款: {s['prepayment_refund']:,.2f}元 [系统可计算]\n\n"
+        f"五、装修折旧\n"
+        f"  折旧扣除: {s['depreciation_deduction']:,.2f}元 [需人工确认]\n\n"
+        f"六、最终净结算\n"
+        f"  经营方应付: {s['operator_owes']:,.2f}元\n"
+        f"  平台方应退: {s['platform_owes']:,.2f}元\n"
+        f"  净结算: {abs(s['net_settlement']):,.2f}元 "
+        f"({'经营方支付' if s['net_settlement'] > 0 else '平台退还'})\n\n"
+        f"七、交接清单\n"
+        f"  [ ] 场地钥匙及门禁权限\n"
+        f"  [ ] 合同及附件文件\n"
+        f"  [ ] 收款账户注销/变更\n"
+        f"  [ ] 备案收银系统注销\n"
+        f"  [ ] 经营数据存档\n"
+        f"  [ ] 水电气账户过户\n\n"
+        f"[注：以上为草案，请由平台运营人员核实后提交审批]"
+    )