# web-root

**Repository Path**: tillfall/web-root

## Basic Information

- **Project Name**: web-root
- **Description**: No description available
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-22
- **Last Updated**: 2026-08-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# web-root

个人一站式工具集 Flask 应用。围绕"基金 + 股票 + 照片/电影/视频 + 思维导图/流程图 + 地图足迹 + 日历"几个生活/投资场景,把数据采集、可视化、配置管理都装进一个 Web 入口,跑在 `0.0.0.0:5555` 上。

> 本 README 面向 AI 助手:用来理解代码、优化建议、新增功能时快速对齐项目约定。

---

## 1. 技术栈

| 层 | 选型 |
|---|---|
| Web 框架 | **Flask** (蓝图式但未用 `Blueprint`,全部路由在 `main.py`) |
| WSGI 服务器 | **gevent.pywsgi** (单进程异步,无线程池) |
| 日志 | **loguru** (统一接管 stdlib logging / Werkzeug) |
| 数据处理 | **pandas**, **numpy** |
| 数学/统计 | **scipy.stats** (百分位计算) |
| 机器学习 | **scikit-learn** (RandomForestRegressor + RandomizedSearchCV) + **joblib** (模型持久化) |
| 数据源 | **akshare** (指数/ETF 实时 + 历史 K 线 + PE)、`requests` 直连东方财富 / 天天基金 / 新浪 / 腾讯 |
| 模板 | Jinja2 (Flask 内置),前端无框架,原生 HTML + 原生 JS + ECharts (回测页) |
| 拼音 | **pypinyin** (分类排序、拼音首字母) |
| 部署 | Windows `.bat` 启动脚本,内含 `git pull` + `pip install` + 重启进程 |

`requirements.txt` 一共 11 个依赖,无 Webpack/Vite 等前端工程化工具,所有 JS/CSS 静态资源放 `static/`。

---

## 2. 目录结构

```
web-root/
├── main.py                   # Flask 入口,所有路由 (~450 行)
├── requirements.txt
├── start-flask.bat           # Windows 启动:git pull → pip install → kill python → run
├── .gitignore                # 忽略 local/、.idea/、__pycache__、/py_debug_local
│
├── pyutils/                  # 业务工具模块
│   ├── __init__.py
│   ├── log_util.py           # loguru 接管 + 文件轮转 (1MB)
│   ├── calendar_util.py      # 日历 CSV 读写,单元格格式: month|value|color|tip
│   ├── fund_util.py          # 自选基金实时估值/历史净值/回撤 + 持仓基金实时市值/收益/回撤(原 fund_hold_util.py 已合并) + 基金交易模块(标签/天数/总估值/涨幅/回撤,文本存储),8 线程并发
│   ├── fund_trade_util.py    # 交易记账:positions + capital + sell_records 合并 JSON
│   ├── fund_monitor.py       # 指数买卖点信号监控 (akshare 双源),生成 text/html
│   ├── fund_backtest.py      # 基金定投回测,输出供 ECharts 渲染的数据
│   ├── stock_util.py         # 自选股票 PE 百分位 + 多空天数 + 5日量比,输出 stock.xlsx
│   ├── stock_select_util.py  # 选股监控 CSV:次日涨幅、多头天数、持仓状态
│   ├── mindmap_util.py       # 缩进文本 ↔ 树形 JSON 互转,2 空格一级
│   ├── flowchat_util.py      # Mermaid flowchart 文本读写
│   ├── image_py.py           # 照片/电影分类管理器 (基于文件名约定的 tag1/tag2/tag3)
│   ├── visit_utils.py        # 地图足迹:文件名带"📍地名📍经度📍纬度"自动入图
│   ├── txt_util.py           # .txt 渲染成 HTML
│   └── invest/               # 机器学习子模块 (未集成到 Web,本地脚本)
│       ├── __init__.py
│       ├── stock_info_getter.py   # 5min K 线拉取,日内 42 时点 + 量比
│       └── stock_train_and_predict.py  # 随机森林 + 特征工程 + 超参调优
│
├── templates/                # Jinja2 模板
│   ├── index.html            # 首页,带启动时间
│   ├── fund.html / fund_config.html
│   ├── fund_hold.html
│   ├── fund_trade.html
│   ├── fund_manage.html       # 基金交易模块(买入弹窗/持仓列表/卖出弹窗,手机适配)
│   ├── fund_invest.html      # 信号监控 (数据来自 fund_monitor.analyze)
│   ├── fund_backtest.html    # ECharts 4 曲线 + 买卖点
│   ├── calendar2.html
│   ├── flowchat_list.html / flowchat_edit.html   # Mermaid 在线编辑
│   ├── mindmap_list.htm / mindmap_edit.htm       # markmap 在线编辑
│   ├── video.html
│   ├── visit.html            # 高德地图 (前端 JS 直连,后端只给 markers JSON)
│   ├── image_list.html / image_gallery.html      # 瀑布流 (masonry + lazyload)
│   ├── stock_select.html     # 选股监控前端
│   └── ...
│
├── static/
│   ├── url.htm / route_list.htm / route_map.htm
│   └── masonry/              # jQuery + masonry + lazyload
│
├── doc/                      # 文档 (如 2026日历.xlsx)
├── my_knowledge/
│   └── fund_api.txt          # 关键 API 备忘 (天天基金 / 东方财富)
└── local/                    # 运行时数据,被 .gitignore
    ├── calendar.csv
    ├── fund.txt              # 自选基金配置
    ├── fund_hold.txt         # 持仓配置
    ├── fund_trade.json       # {positions, capital, sell_records}
    ├── fund_manage.txt       # 基金交易模块持仓(标签,代码,简称,金额,份额,日期)
    ├── stock.xlsx
    ├── stock_select.txt
    ├── photo/                # 照片(文件名约定)
    ├── movie/                # 电影封面(文件名约定)
    ├── video/                # 视频文件
    ├── visit/                # 足迹照片
    ├── text/                 # 任意 .txt
    ├── mindmaps/             # .txt (缩进格式)
    ├── flowcharts/           # .txt (mermaid)
    └── log/
        └── log.txt           # loguru 轮转
```

---

## 3. 主要功能及实现

### 3.1 自选基金实时估值 `/fund`
- 数据源:天天基金 `fundgz.1234567.com.cn/js/<code>.js`
- 额外计算:历史净值回撤 (`fund.eastmoney.com/pingzhongdata/<code>.js` → `Data_ACWorthTrend`)、指定日期起算的期间涨幅
- 8 线程并发 (`ThreadPoolExecutor`),按拼音首字母排序
- 配置: `local/fund.txt`,每行 `基金代码,分类,监控日期(可选)`,`#` 开头为注释

### 3.2 持仓基金 `/fund_hold` `/fund_trade`
- 代码位置:`pyutils/fund_util.py::show_fund_hold()`(原 `fund_hold_util.py` 已合并到 `fund_util.py`,`main.py` 统一从 `fund_util` import)
- `/fund_hold`:支持三种特殊类型 ——
  - `000000xxxx` 开头:**现金**,份额字段当作"当前净值"
  - `999999xxxx` 开头:**其他**,不参与收益计算
  - 第 4 段为日期:**已赎回**,按指定日期的净值结算
- `/fund_trade`:完整交易台账,合并存储 `positions / capital / sell_records` 三部分
- 买卖 API:`/api/fund_trade/buy|sell|clear|capital`
- 实时估算用 `fundgz.1234567.com.cn`,算日内收益用实时估值 − 昨日单位净值

### 3.3 基金买卖信号监控 `/fund_invest`
- `pyutils/fund_monitor.py`,核心是 `analyze()` 返回 `{text, html, results, triggered}`
- **双数据源自动切换**:东方财富 (`ak.stock_zh_index_spot_em`) 优先,失败回退到新浪 (`ak.stock_zh_index_spot_sina`)
- 配置: 模块顶部 `MONITOR_GROUPS` 列表,每个组含:
  ```python
  {
    "index_code": "000001", "index_name": "上证指数",
    "fund_code": "001437",
    "buy_rules":  [(3.0, 95000), (2.5, 50000), (2.0, 20000)],   # (跌幅%, 金额)
    "sell_rules": [(3.0, 0.50, "50%"), (2.0, 0.30, "30%"), (1.5, 0.20, "20%")]  # (涨幅%, 比例, 标签)
  }
  ```
- 规则按"从大到小"匹配,**第一个命中**生效
- 卖出前会校验"当前价 > 平均成本",否则标记 `sell_skipped` 给出"收益为负不建议卖出"提示

### 3.4 基金回测 `/fund_backtest`
- `pyutils/fund_backtest.py::run_backtest_analysis()`
- 默认参数:基准 `sh000001`、基金 `001437`、起始 `2021-07-01`、初始资金 100 万
- 规则字符串: `"3.0:95000,2.5:50000,2.0:20000"` (买入) / `"3.0:50,2.0:30,1.5:20"` (卖出)
- 输出指标:策略总收益、买入持有收益、最大回撤、峰值成本、买卖次数、跳过的卖出(因收益为负)
- 前端用 ECharts 4 曲线:指数累计收益、基金累计收益、累计成本、持仓收益

### 3.5 自选股票 `/stock`
- `pyutils/stock_util.py` 一次性脚本(被 `start-flask.bat` 调用)
- 从新浪 K 线计算:多头天数 (close>MA5>MA10>MA20 全上涨)、5 日量比、最高点回撤
- 从 akshare 计算:PE 百分位 (近 5 年)
- 结果写 `local/stock.xlsx`,Web 端 pandas 直接读 + 高亮渲染

### 3.6 选股监控 `/stock_select`
- `pyutils/stock_select_util.py`,CSV 存储
- 字段:代码、名称、监控时间、次日涨幅、多头天数、收盘价、次日最高、环比、次日收盘、持仓状态
- 新增/更新/删除/改持仓状态 都有 API,前端 JS 调用
- 涨幅为空时一键回填 (`/api/stock_select/update`),5 线程并发

### 3.7 照片/电影 `/photo` `/movie` `/gallery`
- `pyutils/image_py.py::ImageManager / MovieImageManager`
- **文件名即元数据**(无 EXIF/IPTC 依赖):
  - 照片:`YY_地点.子地点_人物1人物2.jpg` (tag1=年, tag2=地点, tag3=人物)
  - 电影:`电影名.年份.评分.类型.jpg`
- 分类页用 jQuery masonry + lazyload 瀑布流
- 搜索:文件名包含关键词(忽略大小写)

### 3.8 地图足迹 `/visit`
- `pyutils/visit_utils.py`
- 文件名约定:`前缀📍地点名📍经度📍纬度.jpg`,运行期首次解析时写入 `LOCATION_COORDS` 内存字典
- 前端高德地图 (`https://webapi.amap.com/...`) 直接根据 markers JSON 渲染
- 关键词"想去"→ 蓝色,默认"去过"→ 橙色

### 3.9 视频 `/video` `/play/<filename>` `/stream/<filename>`
- 列目录 → 选文件 → 用 `<video>` 标签流式播放 (`send_from_directory` + `conditional=True` 支持 Range)
- 允许扩展名写在 `CONFIG['VIDEO_EXT']`:mp4/avi/mov/mkv/flv/wmv/webm

### 3.10 思维导图 `/mindmap` `/mm_editor/<filename>`
- `pyutils/mindmap_util.py`
- 存储:缩进文本 `.txt` (2 空格一级)
- 解析为树形 JSON,前端用 markmap 渲染
- 保存时先调 `parse_indented_text` 校验,失败返回 400

### 3.11 流程图 `/chart` `/chart/<filename>`
- `pyutils/flowchat_util.py`
- 存储:Mermaid 源码 `.txt`,前端用 mermaid.js 渲染
- 新建自动用 `DEFAULT_FLOWCHART`(示例电商架构)

### 3.12 日历 `/calendar2`
- `pyutils/calendar_util.py`
- 存储:`local/calendar.csv`,单元格格式 `月|值|颜色|tip`
- 单元格 tip 通过 `?row=&col=&tip=` 保存 (GET,有 CSRF 风险,见下)

### 3.13 文本查看 `/txt?f_name=xxx`
- `pyutils/txt_util.py`,目录页直接列出所有 .txt

### 3.14 自动部署 `/webhook`
- Gitee Webhook 接收端点,收到 POST 后**异步**执行 `start-flask.bat` (即 `git pull` + 重启)
- 返回 `{"status": "updating"}` 不等子进程
- 注意:`start-flask.bat` 包含 `taskkill /f /im python.exe`——Webhook 触发后当前进程也会被杀掉

### 3.15 机器学习子模块 `pyutils/invest/`
- 独立实验模块,**未接入 Web**
- 工作目录硬编码 `c:/data/260503` (Windows 风格)
- 流程:5min K 线 → 42 时点涨幅 + 量比 → 特征工程 (50+ 衍生特征) → RandomForest + 特征选择 + 超参调优 → 预测次日涨幅
- `BaseStockPredictor / EnhancedStockPredictor` 通过重写 `gen_train_data_and_model / gen_predict_data` 实现钩子模式

### 3.16 基金交易模块 `/fund_manage`
- 代码位置:`pyutils/fund_util.py`(`load/save_fund_manage_positions`、`show_fund_manage`、`buy/sell_fund_manage`、纯计算 `_calc_manage_metrics`),复用 `_get_fund_hist_unit_netvalue` 获取单位净值、最新确认净值日涨幅(`Data_netWorthTrend[-1].equityReturn`)与买入后最大净值；东方财富净值时间戳需按北京时间转换交易日，不能直接按 UTC normalize
- 页面右上角"买入"弹窗:输入 `基金编码、简称、金额(元)、份额、日期、标签(可空或1字符)`
- 持仓列表列:`标签、编码、简称、金额、天数、总估值、涨幅、回撤、操作(卖出)`
  - 天数 = 当前日期 − 买入日期;**小于30天单元格标红**
  - 总估值 = 当前估值(API) × 份额;涨幅 = (总估值 − 买入金额) / 买入金额 × 100
  - 回撤 = 买入后最大涨幅 − 最新估值涨幅;最新估值涨幅为负时也按相同差值逻辑计算
  - 金额/总估值以万元为单位保留1位小数;涨幅/回撤保留1位小数;**上涨红、下跌绿**;回撤 ≤8% 绿、>8% 红
  - 点击表格行可查看该笔买入详情:编码、简称、买入日期、总金额、份额、买入单价、最新净值、最新估值、当日净值/估值涨幅、累计净值/估值涨幅、买入后最高价及日期、最大涨幅和回撤，并说明计算方法；其中当日净值涨幅取东方财富 `Data_netWorthTrend[-1].equityReturn`,当日估值涨幅取新浪实时估值字段 `gszzl`
  - 按**涨幅、天数倒序**排列;`table-layout:fixed` + 小字号,手机无需横向滚动
- 买入弹窗默认日期为前一交易日(前一天若为周末则向前取最近工作日)
- 卖出弹窗:默认填入该行份额,可修改;提交后 `金额 = 买入净值 × 剩余份额`,总估值按当前估值重算;**剩余金额 <1万 或份额≤0 → 清仓删除该行**
- 存储:`local/fund_manage.txt`,全角逗号分隔 `标签,代码,简称,金额,份额,日期`,**按名称、日期排序**
- API:`/api/fund_manage/buy|sell`(JSON)

---

## 4. 外部接口依赖

| 接口 | 用途 | 客户端 | 备注 |
|---|---|---|---|
| `http://fundgz.1234567.com.cn/js/<code>.js` | 基金实时估值 | `urllib.request` / `requests` | 基金名/单位净值/估算涨幅 |
| `http://fund.eastmoney.com/pingzhongdata/<code>.js` | 基金历史净值 / 名称 | `requests` | 解析 `Data_ACWorthTrend` / `Data_NetWorthTrend` / `fS_name` |
| `https://qt.gtimg.cn/q=<sh/sz/bj><code>` | A 股名称 | `requests` (gbk) | |
| `http://money.finance.sina.com.cn/quotes_service/api/json_v2.php/CN_MarketData.getKLineData` | A 股 K 线 | `requests` (需 Referer) | `scale=240` 日线,`scale=5` 5min |
| `ak.stock_zh_index_spot_em` / `stock_zh_index_spot_sina` | 全市场指数实时 | akshare | fund_monitor 双源 |
| `ak.stock_zh_index_daily` | 指数日线 | akshare | 回测 |
| `ak.stock_zh_value_em` | 个股 PE-TTM | akshare | 5 年百分位 |
| `ak.stock_zh_index_hist_csindex` | 指数 PE | akshare | 中证指数公司 |
| 高德地图 JS API | 足迹地图 | 前端 | 后端只喂 markers JSON |
| Gitee Webhook | 触发自动部署 | POST /webhook | |

**没有**任何鉴权/登录系统,假设跑在内网。

---

## 5. 持久化

| 数据 | 文件 | 格式 | 写入入口 |
|---|---|---|---|
| 日历 | `local/calendar.csv` | CSV,单元格 `月\|值\|颜色\|tip` | `calendar_util.save_calendar_tip` (GET `/save_cell`) |
| 自选基金 | `local/fund.txt` | 纯文本,`代码,分类,监控日期` | `/fund_config` (POST 整文件覆盖) |
| 持仓 | `local/fund_hold.txt` | 纯文本,`代码,成本,份额,赎回日期(可选)` | `/fund_hold_config`;加载:`fund_util.show_fund_hold` |
| 交易台账 | `local/fund_trade.json` | JSON `{positions, capital, sell_records}` | `/api/fund_trade/*` |
| 基金交易持仓 | `local/fund_manage.txt` | 纯文本,`标签,代码,简称,金额,份额,日期` (全角逗号,按名称/日期排序) | `/api/fund_manage/buy\|sell` (`fund_util.buy_fund_manage`/`sell_fund_manage`) |
| 股票基础信息 | `local/stock.xlsx` | Excel | `stock_util.py` 启动时刷新 |
| 选股记录 | `local/stock_select.txt` | CSV | `/api/stock_select/*` |
| 思维导图 | `local/mindmaps/*.txt` | 缩进文本 | `mm_data_api_save` |
| 流程图 | `local/flowcharts/*.txt` | Mermaid 文本 | `fc_api_save_chart` |
| 文本 | `local/text/*.txt` | 任意 | `txt_util` 只读 |
| 照片/电影 | `local/photo/` `local/movie/` | 文件名约定 | OS 文件操作 |
| 视频 | `local/video/` | 文件本身 | OS 文件操作 |
| 足迹 | `local/visit/` | 文件名带坐标 | OS 文件操作 |
| 日志 | `local/log/log.txt` | loguru 轮转 1MB | `log_util.setup_logging` |
| ML 模型 | `c:/data/260503/*.pkl` | joblib | `EnhancedStockPredictor._save_model` |

`CONFIG` 字典 (`main.py::init_config`) 集中声明所有路径。`local/` 整体被 `.gitignore`。

---

## 6. 编码风格与约定

### 6.1 通用
- **Python 3**,UTF-8,中文注释多
- 函数命名:模块内部私有函数加 `_` 前缀 (`_get_fund_info`),公开 API 走无前缀
- 大量使用 `ThreadPoolExecutor(max_workers=5/8)` + `as_completed`,基本所有外部请求都并发
- 日志:用 `from loguru import logger`,关键路径打 `info`/`error`/`debug`
- 异常:大部分 `try/except` 后只 `logger.error(...)` 然后降级 (返回 None / 默认值 / 占位)
- 中文标点出现在业务代码中(逗号 `,` 是半角,但配置文件中**用全角逗号** `,` 分隔,见下)

### 6.2 配置/数据文件分隔符
- **配置文件** (`.txt`):字段用**全角逗号** `,` 分隔 (因为代码里有 `line.split('，')`)
  - 例:`001437,主动,2025-01-01` / `001437,95000,1000,`
- **CSV**:逗号 (半角) + 引号
- **JSON**:标准 JSON

### 6.3 错误处理模式
- 单个基金/股票查询失败不影响其他:`ThreadPoolExecutor` 内部 `try/except` 后返回 `'ERR'` 占位
- 监控信号获取失败:返回包含 `text`/`html` 错误信息的 dict
- 写操作失败:返回 `{'success': False, 'error': str(e)}`,HTTP 仍 200

### 6.4 已知问题 / 技术债
1. **CSRF 缺失**:`/save_cell` 走 GET 写文件,任何诱导链接都能改
2. **路径遍历**:`mindmap_util`/`flowchat_util` 有 `__safe_filename` 校验,但 `__get_file_path` 在某些情况返回 None 后没 abort
3. **Webhook 杀掉自己**:`start-flask.bat` 的 `taskkill /f /im python.exe` 会把当前 Flask 进程也杀掉,Webhook 处理完后子进程又拉起一个,中间有 1-2 秒 502
4. **ML 模块硬编码**:`WORKSPACE = 'c:/data/260503'` 是 Windows 路径,无法在 Linux 直接跑
5. **`start-flask.bat` 注释乱码**:中文注释在某些终端会乱码
6. **测试覆盖**:`pyutils/fund_util.py` 有 pytest 覆盖(93%,126 用例,见 `tests/test_fund_util.py`),其中基金交易模块新增 27 个用例(纯计算 `_calc_manage_metrics` + 东方财富北京时间日期转换 + 短日期解析/标准化 + 买入/部分卖出/全部卖出/清仓 + 真实接口链路),其他模块(`fund_trade_util` / `fund_monitor` / `fund_backtest` / `stock_util` / `stock_select_util` / `mindmap_util` / `flowchat_util` / `image_py` / `visit_utils` / `txt_util` / `calendar_util` / `log_util`)仍缺测试。`pyutils/invest/` 里被注释掉的 `unittest.TestCase` 是历史遗留
7. **重复的拼音首字母映射**:`fund_util._get_pinyin_initial` 中 `'通信': 'TX'` 出现两次
8. **基金短名提取**:`_extract_fund_short_name` 全靠正则 + 关键词列表维护,新增主题会漏
9. **没有数据库**:所有状态靠文件,大量并发写会有 race condition (例如同时点两次"更新涨幅")
10. **gevent monkey patch 未启用**:`from gevent import pywsgi` 直接用,但没用 `monkey.patch_all()`,`requests` 的网络 IO 仍是阻塞的
11. **TEMPLATES_AUTO_RELOAD 开启**:开发体验 OK,但生产应关掉

### 6.6 `fund_util` 未覆盖的 7% 详细说明

`tests/test_fund_util.py` 当前覆盖率 **93% (494 语句 / 34 未覆盖)**。新增的基金交易模块(`_calc_manage_metrics`/`buy/sell_fund_manage`/`load/_save` 已被 27 个用例覆盖)未覆盖行主要是网络异常分支:`_query_single_manage_position` 的 `except`(净值/估值查询失败兜底,需无效基金代码触发)、`show_fund_manage` 内 `ThreadPoolExecutor` 的 `except`。原有未覆盖行分布如下,按"覆盖难度"从低到高排:

| 行号 | 行数 | 代码内容 | 未覆盖原因 | 怎么才能覆盖 |
|---|---|---|---|---|
| 349 | 1 | `_query_single_hold` 中 `redeem_date_short = dt.strftime(...)` 的 `except:` 兜底 | 测试全用合法日期 (`'2024-06-15'`),`datetime.strptime` 不会失败 | 用 `redeem_date='invalid-date'` 触发 `strptime` 失败,验证 `redeem_date_short` 走 except 用原值 |
| 210 | 1 | `_get_fund_netvalue` 赎回日期 nearby 兜底 (`±7 天`) | 测试用 `'2099-01-01'` 直接进 raise 路径,nearby 没机会跑 | 用"7 天附近但非交易日"的日期(例如基金休市日) |
| 250-251 | 2 | `_get_fund_netvalue` 赎回日期 except 重抛 | `datetime.strptime` 已被 349 兜底接住,except 段没异常可走 | 几乎无法触发(需 `strptime` 成功 + `redeem_dt.date()` 抛异常),可视为不可达分支 |
| 391-392 | 2 | `show_fund_hold` 的 ERR 占位 dict 部分字段 | 代码在 `ThreadPoolExecutor` 子线程里执行,coverage.py 默认只跟踪主线程 | **coverage 工具的局限**,不是测试问题。要正确统计需 `coverage run --concurrency=thread` 或 `coverage.process_startup()` |
| 591-593 | 3 | `show_fund_info` 的 ERR 占位 row 部分字段 | 同上,子线程 + coverage 局限 | 同上 |
| 14-15 | 2 | `try: from pypinyin ...` 的 `try` 行(只有 import 失败时 except 走) | 装了 pypinyin 后,except 块不执行 | 临时 `pip uninstall pypinyin` 后跑测试 |
| 50-89 | 40 | `_get_pinyin_initial` 的 fallback 字典(40+ 关键词)+ 遍历逻辑 | 同上,pypinyin 装上后,fallback 路径从不走 | 同上。可加 1 个参数化测试,临时 monkey-patch `HAS_PINYIN = False` |
| 290-298 | 9 | `_get_fund_realtime_data` 的"第一次失败 + 0.5s sleep + 第二次重试"逻辑 | 网络一直成功,第一次直接 return 没进 except | **难以无 mock 触发**。需让 `requests.get` 第一次抛异常第二次成功 —— 实际生产中几乎不会发生,可考虑改写为不重试或用 `tenacity` 库 |

**实际可继续提升的优先级**:
1. **349 / 210** (各 1 行):加 1-2 个测试就能覆盖,工作量为零
2. **14-15 / 50-89** (共 42 行):跑两遍测试(装 / 不装 pypinyin),或 monkey-patch `HAS_PINYIN`,能涨到 99%+
3. **391-392 / 591-593** (共 5 行):实际代码执行了,只是 coverage 漏算子线程 —— 加 `--concurrency=thread` 参数能解决
4. **250-251 / 290-298** (共 11 行):不建议花时间,覆盖成本高,实际价值低

**为什么不补完**:严格遵循"不 mock"原则,补 290-298 那 9 行必须 monkey-patch `requests`,会破坏测试真实性。优先级 1-2 已经够用。

### 6.5 命名约定
- 路由:全小写,单词直接连接 (`/fund_hold_config`, `/api/fund_trade/buy`)
- API 函数:`api_xxx_yyy` 形式 (`api_fund_trade_buy`)
- 工具模块导出函数:动词开头 (`show_fund_info`, `get_display_data`, `load_stock_infos`)

---

## 7. 启动

### Windows
```bash
start-flask.bat
# 等价于:git pull → pip install -r requirements.txt → taskkill python → python main.py
```

### 手动
```bash
pip install -r requirements.txt
python main.py
# 访问 http://localhost:5555
```

### 自动部署
Gitee 仓 → Webhook → `http://<host>:5555/webhook` (POST) → 触发 `start-flask.bat` 自更新

### 健康检查
```bash
curl http://localhost:5555/health
# {"status": "ok"}
```

### 跑测试 + 覆盖率
```bash
pip install pytest pytest-cov
python -m pytest tests/ --cov=fund_util --cov-report=term-missing
# 终端会打印每行覆盖情况;html 报告加 --cov-report=html:htmlcov
```
注意:
- `tests/` 下的测试用 `sys.path.insert(0, '..', 'pyutils')` + `from fund_util import ...`,**模块名是 `fund_util` 不是 `pyutils.fund_util`**,所以 `--cov=fund_util` 而不是 `--cov=pyutils.fund_util`
- 外部接口测试**不 mock**,直接访问新浪/东方财富,需要网络可达
- 当前只有 `fund_util` 有测试(93%),详见 6.4 / 6.6 节

---

## 8. 给 AI 助手的快速索引

**想新增一个工具页?**
1. `pyutils/<name>_util.py` 写核心逻辑,导出 `analyze() / show_xxx() / load_xxx()` 之类函数
2. `templates/<name>.html` 写模板
3. `main.py` 加 `@app.route('/<name>')` 视图 + 在 `init_config()` 加路径常量

**想加新数据源?**
- 优先看 `pyutils/fund_util.py` 和 `pyutils/stock_select_util.py`,参考 `HEADERS` + `requests.get(..., timeout=10)` 模式
- 外部 API 备忘写到 `my_knowledge/`

**想加新监控组?**
- 改 `pyutils/fund_monitor.py::MONITOR_GROUPS` 列表即可,无需改 Flask 路由

**想接入 ML 模型?**
- `pyutils/invest/stock_train_and_predict.py` 是现成的,需要先把 `WORKSPACE` 改成环境变量/配置项
- 模型序列化用 `joblib`,加载时 `model_info` 是 dict 还是裸模型要兼容

**想改 Web 框架?**
- `main.py` 集中所有路由,迁移到 FastAPI / Django 难度不大,主要工作是把 `request.form`/`request.get_json()` 替换成对应框架的入参
- 业务函数 (`pyutils/`) 全部纯函数,无 Flask 依赖,直接复用