docs: reorganize — README index, archive old docs, add status headers
This commit is contained in:
知微
+114
-114
@@ -1,114 +1,114 @@
|
||||
# MoFin 数据模型
|
||||
|
||||
> 数据已从 JSON 迁移到 SQLite。portfolio.json / decisions.json / watchlist.json 不再使用。
|
||||
|
||||
## 核心表
|
||||
|
||||
| 表 | 对应旧 JSON | 用途 |
|
||||
|----|-----------|------|
|
||||
| `holdings` + `portfolio_summary` | portfolio.json | 持仓 + 汇总 |
|
||||
| `holding_strategies` | decisions.json | 策略/决策 |
|
||||
| `watchlist_stocks` | watchlist.json | 自选股 |
|
||||
| `live_prices` | live_prices.json | 实时价格快照 |
|
||||
| `mtf_cache` | multi_tf_cache.json | 多周期缓存 |
|
||||
| `market_snapshots` | market.json | 大盘数据 |
|
||||
| `capital_flow_cache` | capital_flow_cache.json | 资金流缓存 |
|
||||
| `cash_log` | 无 | 现金变更日志 |
|
||||
|
||||
## 总资产公式
|
||||
|
||||
**总资产 = 持仓总市值(CNY) + 可用现金 + 冻结资金**
|
||||
|
||||
`calc_total_assets()` (mo_models.py) 是唯一正确公式。
|
||||
|
||||
## 币种
|
||||
|
||||
### 个股层面
|
||||
|
||||
| 品种 | price | cost | currency | 说明 |
|
||||
|------|-------|------|----------|------|
|
||||
| 港股 | **HKD** | **HKD** | `HKD` | 跟股软显示一致，方便操作 |
|
||||
| A股 | **CNY** | **CNY** | `CNY` | |
|
||||
|
||||
技术位（stop_loss / take_profit / entry_low / entry_high）与 price 同币种。
|
||||
|
||||
### 汇总层面
|
||||
|
||||
`calc_total_mv()` / `calc_total_assets()` 汇总时自动将港股 HKD × `HK_RATE`（实时 API）转为 CNY。
|
||||
|
||||
```python
|
||||
# 个股 P&L：港股用 HKD 算，A股用 CNY 算
|
||||
profit_pct = (price - cost) / cost * 100 # 同币种，无需转换
|
||||
|
||||
# 总资产：港股市值自动转 CNY
|
||||
total_assets = calc_total_assets(pf) # 已处理 HKD→CNY
|
||||
```
|
||||
|
||||
### 禁止
|
||||
|
||||
- ❌ 港股 price(HKD) 和 A 股 price(CNY) 直接比较/相加
|
||||
- ❌ 港股 cost(HKD) 和 CNY price 混算 P&L
|
||||
- ❌ 硬编码汇率（`calc_total_mv` 内部调 `get_hk_rate()` 走实时 API）
|
||||
|
||||
## 数据流
|
||||
|
||||
```
|
||||
price_monitor (cron: */2 9-16)
|
||||
→ 东财/腾讯拉价格
|
||||
→ write_holdings_batch() → holdings 表 (price 更新)
|
||||
→ write_portfolio_summary() → portfolio_summary (total_mv/total_assets 重算)
|
||||
|
||||
regenerate_all (cron: 手动/定时)
|
||||
→ batch_fetch_prices() → 从 DB 读价格
|
||||
→ 技术分析 → 止损/止盈/买入区
|
||||
→ write_holding_strategy() → holding_strategies 表
|
||||
|
||||
server.py API
|
||||
→ 写端点: _save_portfolio / _save_decision / _save_watchlist → DB
|
||||
→ 读端点: mo_data.read_*() → DB
|
||||
```
|
||||
|
||||
## 现金
|
||||
|
||||
- `price_monitor` 只更新价格和汇总，不动现金
|
||||
- 现金变更通过截图导入 / holding.xls 导入 / 手动调整
|
||||
- `cash_log` 表记录每次变更（来源、before/after、备注）
|
||||
|
||||
## 常见错误
|
||||
|
||||
### ❌ 港股价格转 CNY 再存
|
||||
```python
|
||||
# WRONG — 港股个股存 CNY 后股软对不上
|
||||
if is_hk_stock(code):
|
||||
price = price * HK_RATE
|
||||
|
||||
# RIGHT — 存 HKD 原值，汇总时由 calc_total_assets 转 CNY
|
||||
if is_hk_stock(code):
|
||||
currency = 'HKD'
|
||||
```
|
||||
|
||||
### ❌ 混币计算
|
||||
```python
|
||||
# WRONG — price 是 HKD，cost 是 CNY，算出来没意义
|
||||
pnl = (price_hkd - cost_cny) / cost_cny
|
||||
|
||||
# RIGHT — 同币种比较
|
||||
pnl = (price_hkd - cost_hkd) / cost_hkd
|
||||
```
|
||||
|
||||
### ❌ 硬编码汇率
|
||||
```python
|
||||
# WRONG
|
||||
mv = shares * price * 0.87
|
||||
|
||||
# RIGHT — 用 calc_total_assets（内部调实时汇率）
|
||||
mv = calc_total_mv(holdings)
|
||||
```
|
||||
|
||||
## 版本
|
||||
|
||||
| 版本 | 日期 | 变更 |
|
||||
|------|------|------|
|
||||
| 3 | 2026-07-03 | JSON→DB 迁移完成。港股个股存 HKD，汇总时转 CNY。 |
|
||||
| 2 | 2026-06-29 | 明确 cash/frozen_cash 字段含义 |
|
||||
| 1 | - | 无规范 |
|
||||
# MoFin 数据模型
|
||||
|
||||
> 数据已从 JSON 迁移到 SQLite。portfolio.json / decisions.json / watchlist.json 不再使用。
|
||||
|
||||
## 核心表
|
||||
|
||||
| 表 | 对应旧 JSON | 用途 |
|
||||
|----|-----------|------|
|
||||
| `holdings` + `portfolio_summary` | portfolio.json | 持仓 + 汇总 |
|
||||
| `holding_strategies` | decisions.json | 策略/决策 |
|
||||
| `watchlist_stocks` | watchlist.json | 自选股 |
|
||||
| `live_prices` | live_prices.json | 实时价格快照 |
|
||||
| `mtf_cache` | multi_tf_cache.json | 多周期缓存 |
|
||||
| `market_snapshots` | market.json | 大盘数据 |
|
||||
| `capital_flow_cache` | capital_flow_cache.json | 资金流缓存 |
|
||||
| `cash_log` | 无 | 现金变更日志 |
|
||||
|
||||
## 总资产公式
|
||||
|
||||
**总资产 = 持仓总市值(CNY) + 可用现金 + 冻结资金**
|
||||
|
||||
`calc_total_assets()` (mo_models.py) 是唯一正确公式。
|
||||
|
||||
## 币种
|
||||
|
||||
### 个股层面
|
||||
|
||||
| 品种 | price | cost | currency | 说明 |
|
||||
|------|-------|------|----------|------|
|
||||
| 港股 | **HKD** | **HKD** | `HKD` | 跟股软显示一致，方便操作 |
|
||||
| A股 | **CNY** | **CNY** | `CNY` | |
|
||||
|
||||
技术位（stop_loss / take_profit / entry_low / entry_high）与 price 同币种。
|
||||
|
||||
### 汇总层面
|
||||
|
||||
`calc_total_mv()` / `calc_total_assets()` 汇总时自动将港股 HKD × `HK_RATE`（实时 API）转为 CNY。
|
||||
|
||||
```python
|
||||
# 个股 P&L：港股用 HKD 算，A股用 CNY 算
|
||||
profit_pct = (price - cost) / cost * 100 # 同币种，无需转换
|
||||
|
||||
# 总资产：港股市值自动转 CNY
|
||||
total_assets = calc_total_assets(pf) # 已处理 HKD→CNY
|
||||
```
|
||||
|
||||
### 禁止
|
||||
|
||||
- ❌ 港股 price(HKD) 和 A 股 price(CNY) 直接比较/相加
|
||||
- ❌ 港股 cost(HKD) 和 CNY price 混算 P&L
|
||||
- ❌ 硬编码汇率（`calc_total_mv` 内部调 `get_hk_rate()` 走实时 API）
|
||||
|
||||
## 数据流
|
||||
|
||||
```
|
||||
price_monitor (cron: */2 9-16)
|
||||
→ 东财/腾讯拉价格
|
||||
→ write_holdings_batch() → holdings 表 (price 更新)
|
||||
→ write_portfolio_summary() → portfolio_summary (total_mv/total_assets 重算)
|
||||
|
||||
regenerate_all (cron: 手动/定时)
|
||||
→ batch_fetch_prices() → 从 DB 读价格
|
||||
→ 技术分析 → 止损/止盈/买入区
|
||||
→ write_holding_strategy() → holding_strategies 表
|
||||
|
||||
server.py API
|
||||
→ 写端点: _save_portfolio / _save_decision / _save_watchlist → DB
|
||||
→ 读端点: mo_data.read_*() → DB
|
||||
```
|
||||
|
||||
## 现金
|
||||
|
||||
- `price_monitor` 只更新价格和汇总，不动现金
|
||||
- 现金变更通过截图导入 / holding.xls 导入 / 手动调整
|
||||
- `cash_log` 表记录每次变更（来源、before/after、备注）
|
||||
|
||||
## 常见错误
|
||||
|
||||
### ❌ 港股价格转 CNY 再存
|
||||
```python
|
||||
# WRONG — 港股个股存 CNY 后股软对不上
|
||||
if is_hk_stock(code):
|
||||
price = price * HK_RATE
|
||||
|
||||
# RIGHT — 存 HKD 原值，汇总时由 calc_total_assets 转 CNY
|
||||
if is_hk_stock(code):
|
||||
currency = 'HKD'
|
||||
```
|
||||
|
||||
### ❌ 混币计算
|
||||
```python
|
||||
# WRONG — price 是 HKD，cost 是 CNY，算出来没意义
|
||||
pnl = (price_hkd - cost_cny) / cost_cny
|
||||
|
||||
# RIGHT — 同币种比较
|
||||
pnl = (price_hkd - cost_hkd) / cost_hkd
|
||||
```
|
||||
|
||||
### ❌ 硬编码汇率
|
||||
```python
|
||||
# WRONG
|
||||
mv = shares * price * 0.87
|
||||
|
||||
# RIGHT — 用 calc_total_assets（内部调实时汇率）
|
||||
mv = calc_total_mv(holdings)
|
||||
```
|
||||
|
||||
## 版本
|
||||
|
||||
| 版本 | 日期 | 变更 |
|
||||
|------|------|------|
|
||||
| 3 | 2026-07-03 | JSON→DB 迁移完成。港股个股存 HKD，汇总时转 CNY。 |
|
||||
| 2 | 2026-06-29 | 明确 cash/frozen_cash 字段含义 |
|
||||
| 1 | - | 无规范 |
|
||||
|
||||
Reference in New Issue
Block a user