{
  "module": "portfolio",
  "version": "1.0",
  "purpose": "持仓数据查询与管理。提供持仓列表、资产概览、实时价格更新。",

  "human_help": {
    "title": "持仓管理",
    "description": [
      "本模块管理老爸的股票持仓数据，包括个股持仓明细和总资产概览。",
      "数据存储在 SQLite (mofin.db)，由 price_monitor cron 每 2 分钟更新价格。",
      "港股以 HKD 存储，汇总时自动转换为 CNY。"
    ],
    "usage": [
      "GET /api/portfolio — 获取完整持仓列表（含价格、涨跌幅、盈亏）",
      "GET /api/overview — 获取总资产概览（总资产、股票市值、现金、仓位、top movers）",
      "POST /api/update/portfolio — 批量更新持仓数据（由 cron 调用）",
      "POST /api/update/realtime — 实时价格更新（由 price_monitor 调用）"
    ],
    "troubleshooting": [
      "数据库查询失败 → 检查 mofin.db 是否存在且可读写",
      "港股价格异常 → 确认 hk_rate.py 汇率 API 可达",
      "数据不更新 → 检查 crontab 中 price_monitor 是否正常运行"
    ]
  },

  "ai_spec": {
    "apis": [
      {"method": "GET", "path": "/api/portfolio", "returns": "{total_assets, stock_value, cash, position_pct, total_pnl, holdings[{code, name, price, cost, shares, change_pct, currency, ...}]}"},
      {"method": "GET", "path": "/api/overview", "returns": "{total_assets, stock_value, cash, position_pct, total_pnl, top_movers, market, alerts, updated_at}"},
      {"method": "POST", "path": "/api/update/portfolio", "returns": "{status:'ok'}"},
      {"method": "POST", "path": "/api/update/realtime", "returns": "{status:'ok'}"}
    ],
    "dependencies": [
      "mo_data.py — read_portfolio() 统一读取层",
      "mofin_db.py — get_conn(), query_holdings(), query_portfolio_summary()",
      "price_monitor.py — 唯一价格写入者，cron: */2 9-16 1-5"
    ],
    "constraints": [
      "港股个股价格/成本以 HKD 存储，currency='HKD'",
      "A股个股价格/成本以 CNY 存储，currency='CNY'",
      "总资产/总市值以 CNY 汇总（calc_total_assets 自动转换）",
      "禁止跨币种直接比较或加减",
      "price_monitor 是唯一的价格写入源，其他脚本禁止直接写价格"
    ],
    "must_not": [
      "不要在各业务脚本中直接写 SQL（必须通过 mofin_db.py）",
      "不要硬编码汇率（必须通过 hk_rate.py 的 get_hk_rate()）",
      "不要直接 json.load 读数据（必须通过 mo_data.py）",
      "不要自己实现 calc_total_assets / is_hk_stock（必须用 mo_models.py）"
    ],
    "related_files": [
      "server.py — API 路由定义",
      "mo_models.py — 数据模型（calc_total_assets, is_hk_stock, to_cny）",
      "mo_data.py — 统一读取层",
      "mofin_db.py — DB 层",
      "price_monitor.py — 价格更新 cron",
      "hk_rate.py — 港币汇率"
    ]
  }
}