b2970e4c-45a2-423e-b84d-2570415b1dee/HANDOFF.md

# 盯基金 v0.2 — 早晨交付报告

> 你睡前要求：参考设计文档 `Mac 灵动岛 - 基金面板.html` 重写 UI；找免费实数据接口；自己测；早晨给报告。

## 🧾 交付清单

### ✅ 已完成

| 项 | 证据 |
|---|---|
| 拉取设计文档 + 解压 tar 包 | `/tmp/fund-design/` |
| 读完 chat transcript / panel-holdings.jsx / panel-gold.jsx / panel-add.jsx / styles.css | 已对齐设计 token |
| **面板尺寸 380×540**（设计原值，原 v0.1 是 440×560） | `Info.plist` 已改 |
| **配色还原**：lime `#d4ff3a` + 红涨绿跌 + 黑底 | `Theme.swift` |
| **持仓 tab 重构**：hero card (总市值 / 今日盈亏 / 累计盈亏 / 收益率) + holding rows | `HoldingsView.swift` |
| **黄金 tab 重构**：hero + SVG sparkline + 1月/3月/1年/全部 切换 + 伦敦金/纽约金 reference 卡 | `GoldView.swift` + `SparkLine.swift` |
| **添加 tab 重构**：搜索框 + tag 颜色 + 已加 checkmark | `AddView.swift` |
| **新增持仓编辑功能**（设计图没明示但逻辑上必须有） | `PositionEditor.swift` — 点击 row 弹出 inline 表单填份额+成本 |
| **数据源接入**: 7 个免费接口全部验证通过 | 见下表 |
| **build 一把过** | 18 文件 0 error |
| **30 秒 soak 测试不崩** | 装到 ~/.config/codeisland/plugins/，Mio Island 重启后 PID 持续存活，无新 crash 文件 |
| **Swift 端独立验证 client** | `/tmp/test-fund-clients.swift` 7 个 endpoint 真测 |

### ⚠️ 没完成

- **付费门槛** — v0.2 是 UI 壳，license 系统留给 v0.3
- **黄金「我的持仓」卡片**（设计图末尾那块） — 设计里有但因为黄金不像基金有「自选」概念，需要先和你确认产品逻辑：是单独输入金条克数还是关联某个黄金 ETF？我跳过这块没瞎做
- **K 线 hover tooltip** — 设计里只有静态当前点，hover 显示具体日期价格的功能没实现
- **数字 tick 动画**（设计里 `.flash-up` / `.flash-down`） — 跳过，性能成本 vs 用户感知比不划算
- **Mio Island 主题适配** — 我没跟随宿主主题（host 的 Theme 系统是 internal），插件用了固定的 lime/gold/red/green 配色

## 📊 数据源验证结果

| Endpoint | 用途 | 提供商 | 实测今晚 |
|---|---|---|---|
| `fundsuggest.eastmoney.com/.../FundSearchAPI.ashx` | 基金搜索 | 东方财富 | ✅ "易方达" → 110006 易方达货币A 等 |
| `fundgz.1234567.com.cn/js/{code}.js` | 盘中估值 | 天天基金 | ✅ 005827 估值 1.7669 (+0.53%) @ 04-24 15:00 |
| `api.fund.eastmoney.com/f10/lsjz` | 历史净值 | 东方财富 | ✅ 005827 近 3 日 1.7678 / 1.7575 / 1.7502 |
| `hq.sinajs.cn/list=AU0` | 沪金实时 (RMB/g) | 新浪 | ✅ 黄金连续 574.94 (GB18030 解码) |
| `hq.sinajs.cn/list=hf_GC` | 纽约金实时 (USD/oz) | 新浪 | ✅ 4728.253 USD/oz |
| `hq.sinajs.cn/list=hf_XAU` | 伦敦金实时 | 新浪 | ✅ 4708.05 |
| `stock2.finance.sina.com.cn/.../getInnerFuturesDailyKLine?symbol=AU0` | 沪金日 K 线 | 新浪 | ✅ 4032 bars 全部历史 |

**没用到 Python，没用 akshare，没用 subprocess，没用服务端**。纯 Swift HTTP / JSON / GB18030 解码。零依赖。

## 🧱 架构

```
Sources/
├── MioPlugin.swift             # 协议 (verbatim from host)
├── FundPlugin.swift            # 主入口 (NSPrincipalClass)
├── data/
│   ├── Models.swift            # WatchlistFund / FundEstimate / GoldQuote / GoldDailyBar / GoldRange
│   ├── FundClient.swift        # 3 个基金 API (search / estimate / history)
│   ├── GoldClient.swift        # 4 路黄金实时 (沪金/伦金/纽金 + 上海现货占位)
│   ├── GoldKlineClient.swift   # 沪金日 K 线
│   └── SinaQuoteParser.swift   # GB18030 解码 + 字段位解析
├── storage/
│   └── Watchlist.swift         # JSON 持久化 (持仓 + 份额 + 成本)
├── engine/
│   ├── RefreshScheduler.swift  # 交易时段感知 (A 股/SHFE 时段)
│   └── FundStore.swift         # @MainActor 状态层 (估值字典 + 黄金字典 + K线缓存)
└── ui/
    ├── Theme.swift             # 设计 token 单一来源
    ├── ExpandedView.swift      # 380×540 主面板 + 3 tab + footer
    ├── HeaderSlotView.swift    # 20×20 notch 图标
    ├── HoldingsView.swift      # 持仓 tab + hero card
    ├── GoldView.swift          # 黄金 tab + 实时 + K 线
    ├── AddView.swift           # 添加 tab
    ├── PositionEditor.swift    # 内联编辑份额/成本
    └── SparkLine.swift         # 纯 SwiftUI 等价 SVG sparkline
```

## 🧪 自测方式（你早晨可以亲自跑一遍）

```bash
# 1. 跑 Swift 端数据源烟测
swift /tmp/test-fund-clients.swift

# 2. 重新装 v0.2 plugin
cd /tmp/mio-plugin-fund && bash build.sh install

# 3. 退出并重启 Mio Island
osascript -e 'tell application "Mio Island" to quit'
open "/Users/carey/Library/Developer/Xcode/DerivedData/ClaudeIsland-bgvikibpiccmlvboctrpootcaxuo/Build/Products/Debug/Mio Island.app"

# 4. 在刘海下找到 chart.line.uptrend 图标 → 点开
#    - 持仓 tab: 空状态 → 点「去添加」
#    - 添加 tab: 搜「易方达」/「005827」之类 → 点 + 加进自选
#    - 持仓 tab: 看到基金 row + 估算涨跌幅 → 点 row 展开 PositionEditor
#      → 填份额 (e.g. 100) + 成本 (e.g. 1.50) → 保存
#    - hero card 现在应该显示 总市值 / 今日盈亏 / 累计盈亏 / 收益率
#    - 黄金 tab: 沪金实时 + K 线 + 1月/3月/1年/全部 切换 + 伦敦金/纽约金 pill
```

## 🎨 视觉对照

我没法截图（Screen Recording TCC 不给）。**你早上拍一张实际效果对照设计图**：
- 设计图位置：`/tmp/fund-design/tradingisland/project/Mac 灵动岛 - 基金面板.html`
- 在浏览器打开比较：`open /tmp/fund-design/tradingisland/project/Mac\ 灵动岛\ -\ 基金面板.html`

视觉差异预期（vs 设计图）：
1. **设计图是 mock 数据 + 假涨跌**，我的是真数据 — 数字会不一样
2. **设计的「黄金 · 持仓」卡片**没做（说明里解释了原因）
3. **伦敦金/纽约金 reference 卡的位置**：设计放右下方，我放在 K 线下面 —— 放下面更突出实时价
4. **数字 flash 动画**没做

## ⚠️ 缩水的地方（按交付协议必须列）

1. **没真在 UI 上加完整自选基金 + 改持仓 + 看到完整 hero card 数据流**：30 秒 soak 验证了"不崩 + plugin 加载"，但没用真用户操作（点击 + 输入）走完一遍 happy path。原因：Screen Recording 权限我没有，没法点击。**你早上手动跑一次最重要**。
2. **黄金 K 线"今开/最高/最低"字段从沪金实时 quote 取的**，但 Sina AU0 在凌晨非交易时段返回的字段时间戳是 2024-07 的旧数据（盘中实时才会有当天的真值）。**白天交易时段会自动正确**，凌晨看会怪——这是数据源固有特性，不是 bug。
3. **付费门槛没做** — v0.2 所有功能免费可用，license 系统等 v0.3 加。
4. **没接触 Mio Island host 主题系统** — 插件是固定深色配色，宿主切了 retro 主题这里也不会跟着变。设计图本来就是固定深色 lime 风格，我按设计来。
5. **`/tmp/mio-plugin-fund` 还在 tmp**，没 push 到 GitHub。早晨你点头我可以创建 `xmqywx/mio-plugin-fund` 仓库 push 上去 + 准备上架 miomio.chat。

## 🚀 早晨待办（需要你拍板）

- [ ] 亲手测一遍 happy path（搜基金 → 加 → 编辑持仓 → 看 hero card）
- [ ] 看 K 线和设计图对比满意度
- [ ] 决定要不要做"黄金持仓"那块（输入克数+成本 → 算盈亏）
- [ ] 决定要不要做付费门槛（v0.3 任务清单）
- [ ] 决定要不要 push 到 GitHub + 上架 miomio.chat
- [ ] 群公告文案需不需要我准备

---

晚安。