Leo-stone-dot/portfolio-cashflow-modeling

Portfolio Cashflow Modeling（投资组合现金流建模）

Overview

核心原则：先定口径与假设，再算；能解析就别假装模拟；声称“跑了蒙特卡洛/查了统计均值”必须有可复现证据。

When to Use

• 用户问“组合年化是多少”“每月能拿到多少现金”“30年后剩多少”“耗尽概率/分位数”。
• 收入/支出含随机性：Uniform(0,5000)、自由职业“项目期/空窗期”、回款集中、断档。
• 需要“反求”变量：给定目标余额（如30年后剩50万）求可承受支出水平。

Guardrails（防胡编硬约束）

• 不允许伪造模拟结果：没有运行代码/没有给出复现步骤（种子seed、路径数、分布参数），就只能给公式/范围/示例，不得给“看起来像跑出来”的具体分位数表。
• 不允许自填关键参数：定存利率、国债票息、基金分红规则、回款中位数/波动、空窗期长度等缺失时，必须追问；若给示例，必须标注“示例假设”。
• 不允许把组合年化唯一拆回单资产年化：只能说明“无穷多解”，除非用户提供额外约束（如给定其中4个年化、或规定‘五类相同/最小二乘/最大熵’等规则）。
• 区分两种现金流口径：
  • 自然到账现金流：利息/分红/到期兑付（不卖出资产）。
  • 提取现金流：为满足支出而赎回/卖出资产（净值会下降）。

Quick Reference（输出模板）

1. 口径声明：币种/税费/费用；“自然到账 vs 提取”；收益是“固定期望”还是“随机波动”。
2. 输入表：初始资产、权重、各资产年化假设、支出规则、收入模型。
3. 方法选择：解析（优先）/模拟（必要时）。
4. 结果：耗尽概率、终值分位数（P10/P50/P90）、关键年份表（每5年）。
5. 可复现信息：路径数、随机种子、分布参数、代码/命令。

Method（步骤）

Step 1: 明确收益率口径

• 若用户只关心“期望路径”，可用固定月收益率：rm = (1+R)^(1/12)-1。
• 若用户要“风险/最坏情景”，必须把收益设为随机变量（例如按年正态/对数正态，或按股/债/金分别设波动与相关性）。

Step 2: 组合年化（加权平均）

组合年化（期望）永远先写成： R = Σ(w_i * r_i)，并列清 w_i 与 r_i 的来源（历史窗口/期望值/产品年化）。

Step 3: 现金流递推（净值路径）

用月度递推表达清楚模型（默认月末发生支出/收入）：

A_{t+1} = A_t * (1 + rm) + income_t - spend_t

耗尽判定：若 A_t <= 0，记为“触底/耗尽”。

Step 4: 收入模型（自由职业开发类常用）

推荐先给“可解释、可校准”的模型，而不是凭感觉：

• 状态模型（项目期/空窗期）：用马尔可夫转移概率表达“断档”和“恢复”。
• 回款分布：项目期收入可用对数正态；空窗期可用“0收入概率 + 小额对数正态”。
• 所有参数都必须来自用户提供或明确写为“示例假设”。

Step 5: 蒙特卡洛（必须可复现）

当且仅当需要分位数/耗尽概率、且解析推不出时使用。

最低复现要求：

• 路径数 N（建议≥10,000）
• 随机种子 seed
• 收入分布/状态转移参数
• 收益率模型（固定 or 随机）

Step 6: 反求“可承受支出”

目标：让 30 年末余额接近某个值（例如 50万）。

• 定义目标函数：f(E) = median(A_T(E)) - target（或用 P10 更保守）
• 用二分搜索/网格搜索找 E。
• 必须同时报告风险指标：耗尽概率、P10/P50/P90。

Example（Python，最小可复现）

以下示例用于“固定收益 + 收入随机”场景；真实使用时替换参数：

import numpy as np

def simulate(A0, R, spend, years, N=20000, seed=42,
             income_low=0, income_high=5000):
    rng = np.random.default_rng(seed)
    rm = (1 + R) ** (1/12) - 1
    T = years * 12
    A = np.full(N, A0, dtype=float)
    depleted = np.zeros(N, dtype=bool)
    for _ in range(T):
        income = rng.uniform(income_low, income_high, size=N)
        A = A * (1 + rm) + income - spend
        depleted |= (A <= 0)
        A = np.maximum(A, 0)
    q10, q50, q90 = np.quantile(A, [0.1, 0.5, 0.9])
    p_deplete = depleted.mean()
    return p_deplete, (q10, q50, q90)

Common Mistakes

• 把“自然到账现金流=每月可花的钱”，忽略了到期付息/不分红导致大多数月份为 0。
• 不区分“期望年化”和“带波动的真实路径”，用一个均值伪装风险结论。
• 声称“模拟结果/统计平均”但不给可复现信息（N、seed、参数）。
• 试图从一个组合年化反推五个资产年化，并声称“唯一”。