PortfolioTracker

English

PortfolioTracker 是一个本地股票交易记录和持仓盈亏分析工具。项目面向个人投资复盘场景：使用 Streamlit 提供轻量界面，使用 SQLite 保存交易和价格数据，并在本地完成加权平均成本、已实现盈亏、未实现盈亏和持仓市值计算。

项目不连接券商账户，也不上传交易数据；默认使用手动录入或 CSV 导入，适合作为离线投资流水、持仓复盘和个人资产分析的小型工具。

功能说明

模块	功能
交易流水	记录买入、卖出、数量、成交价、手续费和备注
价格记录	维护每个标的的最新收盘价
CSV 导入	从样例格式导入交易记录和价格记录，并逐行提示错误
盈亏计算	使用加权平均成本法计算持仓成本、已实现盈亏和未实现盈亏
本地存储	使用 SQLite 保存数据，并提供中文只读视图便于查看
可复现检查	基于 sample_data/ 生成结果摘要、结构检查和测试输出

结果展示

项目	样例结果
样例交易记录	4
样例持仓标的	2
样例市值	5,750.00
未实现盈亏	450.30
已实现盈亏	85.00
总盈亏	535.30

样例持仓结果：

symbol,quantity,average_cost,latest_price,market_value,unrealized_pnl
AAPL,11.0,183.5,210.0,2310.0,291.5
MSFT,8.0,410.15,430.0,3440.0,158.8

结果文件：

• docs/results/project_summary.md
• docs/results/project_summary.json
• docs/results/portfolio_summary.csv
• docs/results/structure_check.txt
• docs/images/dashboard-holdings-pnl.png：上表"持仓与盈亏"页面的真实截图，用 sample_data/ 里的样例交易/价格数据在隔离的临时数据库上跑出来的（不是仓库作者本人的真实持仓数据），截图里的数字和上面表格一致，可复现：

bash scripts/setup_env.sh
python -c "
import csv
from profit.db import get_conn, init_db, add_trade, upsert_price
conn = get_conn('demo.db'); init_db(conn)
for row in csv.DictReader(open('sample_data/trades.csv')):
    add_trade(conn, row['date'], row['symbol'], row['side'], row['qty'], row['price'], row.get('fee', 0), row.get('note', ''))
for row in csv.DictReader(open('sample_data/prices.csv')):
    upsert_price(conn, row['date'], row['symbol'], row['close'])
"
# streamlit run app.py 后在侧栏把"数据文件"改成 demo.db，切到"持仓与盈亏"标签页截图

快速上手

bash scripts/setup_env.sh
bash scripts/run_app.sh

复用已有 conda 环境：

conda run -n codex_python bash scripts/run_app.sh

生成 README 对应结果文件：

make results

运行命令行样例摘要：

python -m profit.showcase --format markdown

环境要求

• Python 3.10+
• 依赖见 pyproject.toml
• 浏览器用于打开 Streamlit 页面

数据说明

• 默认数据库文件为 portfolio.db，不会提交到仓库。
• 示例 CSV 位于 sample_data/。
• 交易 CSV 字段：date,symbol,side,qty,price,fee,note
• 价格 CSV 字段：date,symbol,close
• sample_data/ 中的样例数据是合成数据，用于演示计算逻辑，不代表投资建议。

目录结构

app.py                 Streamlit 入口
profit/db.py           SQLite 初始化、写入、查询和中文视图
profit/portfolio.py    加权平均成本和盈亏计算
profit/web.py          Streamlit 中文界面
profit/showcase.py     样例数据结果展示 CLI
sample_data/           示例交易和价格 CSV
docs/results/          可复现结果摘要
tests/                 测试
scripts/               环境配置、运行、检查和结果生成脚本

测试

bash scripts/run_tests.sh
make test
bash scripts/check_project.sh