61 lines
3.0 KiB
JSON
61 lines
3.0 KiB
JSON
{
|
||
"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 — 港币汇率"
|
||
]
|
||
}
|
||
}
|