# Omniledger 架构与开发记忆 (Memory)

## 基础设施与底层架构
- 完成根目录的 Next.js 初始化、基础依赖安装与环境变量配置。
- 完成基于单例模式的数据库连接配置，并设定 Drizzle 迁移工具。
- 修复网络连接，成功将 tables 推送至 PostgreSQL 数据库。
- 统一规范 Git 全量提交机制 (`git add -A`)，确立了严谨的代码版本控制防腐层。

## 数据库设计 (Schema)
- 成功定义资产枚举与 `assets` 表，支持跨资产标识。
- 完成核心 `transactions` (交易流水) 表的建立，并严格运用了 `numeric(36,18)` 的高精度配置。
- `assets` 表完成多次业务演进：新增 `latestPrice` (支持现价追踪)、`exchange` (显式交易所绑定) 以及 `name` (中文名称解析) 字段。
- `exchange_rates` (汇率表) 已建立，支持联合主键与跨币种交叉汇率架构。

## 核心业务与服务端逻辑 (Server Actions)
- 完成高精度交易流水与资产的 Server Actions 开发，成功实现字符串级别的高精度防腐层拦截（基于 Zod & Big.js）。
- 补全资产与流水的全栈增删改查 (CRUD) 操作，`createTransaction` 现已支持根据 `exchange` 自动判定并锁定 `txCurrency`。
- **估值与 P&L 引擎：** 完成底层估值引擎升级，打通交叉汇率换算逻辑；实现原币种 (Native) 与本位币 (CNY Base) 双轨制的历史成本追溯与真实盈亏 (P&L) 计算引擎。

## 外部行情接口与网络 (Market Data Engines)
- **股票行情引擎：** 彻底抛弃低效海外接口，自主研发智能路由接入腾讯财经 (`qt.gtimg.cn`) 极速接口。引入原生 `ArrayBuffer` 与 `TextDecoder(gbk)` 彻底解决历史中文乱码问题，实现沪、深、港、美四大市场毫秒级实时同步。
- **Crypto 行情引擎：** 接入币安 (Binance) 公共 API，构建全市场（股票+加密货币）双轨双擎驱动架构。
- **网络防腐层：** 引入 `undici` 底层网络库并配置 `setGlobalDispatcher`，成功突破境内防火墙对境外 API 的直连封锁 (Timeout)。

## 前端架构与 UI/UX 体验
- 完成 shadcn/ui 初始化，集成 next-themes 支持暗黑模式，并拉取核心组件库。
- 完成 `/dashboard` 基础布局架构，接管根路由。
- 打通 `/dashboard/assets` 与 `/dashboard/transactions` 页面前后端数据流转，修复早期录入与 404 缺陷。
- 完成 UI 层高精度数据格式化，针对不同资产类型实现动态精度展示，清理因数据库 `numeric` 导致的尾随零问题。
- 引入 `recharts` 图表引擎，构建了基于实时 CNY 估值的资产分布环形图。
- 优化表单交互：实装了交易所与币种的智能联动逻辑，并运用 `disabled` 属性实现了表单字段的只读防腐锁定。

## UX 与全局交互 (UI/UX)
- 引入 `sonner` 构建全局 Toast 消息通知系统，覆盖行情同步、CRUD 操作的成功与异常提示。
- 重构 `<SyncButton />` 并将其提升至 Dashboard 首页，实现总资产大盘的全局一键实盘刷新。

## 修复记录
- 解决了日期选择控件的时区偏移 Bug，确保全球通用：在 `src/libs/utils.ts` 中重写 `formatDateForDatetimeLocal()` 与 `parseDateTimeLocalToUTC_v2()` 函数，采用 `Intl.DateTimeFormat` 动态获取 `Asia/Shanghai` 时区偏移量，确保 UTC 时间到本地时间的双向转换精确无误，修复了用户选 10 点展示为 2 点的问题。修正了前端数据格式化逻辑，在 `src/lib/formatters.ts` 中增加空值/NaN 兜底处理，在 `src/app/dashboard/page.tsx` 中将平均成本与摊薄成本的显示条件从 `.gt(0)` 改为 `.ne(0)`，支持英特尔负成本等极端场景下的精确数字展示。

## 资产分布图表按市场维度升级 (Task 32)
- 优化资产分布图表，升级为按市场维度聚合展示，并增强了 Tooltip 的颜色指代与明细交互。
- 在 `portfolio.ts` 中新增 `getMarketFromExchange()` 函数，将资产按交易所归类为 A股 (SSE/SZSE)、港股 (HKEX)、美股 (US)、虚拟币 (CRYPTO)。
- 新增 `marketAllocation` 聚合数据，按市场维度汇总 `totalCnyValue` 并计算占比，自动过滤已清仓资产。
- 升级 `AllocationChart` 组件：数据源改为市场聚合数据，为各市场设定固定品牌色（A股红、港股黄、美股蓝、虚拟币绿），并自定义 Tooltip 渲染内容，悬停时清晰展示 `[市场名称] [对应颜色块] [CNY 金额] [占比%]`。

## 盈亏引擎重构 (Task 31)
- 重构盈亏计算引擎，支持已实现盈亏统计：交易按时间正序处理，SELL 时基于当时平均成本计算该笔卖出的利润并累加至 `realizedPnlCny`。
- 引入摊薄成本与平均成本双重指标：`avgCost = totalBuyCost / totalBuyQuantity`（平均成本）；`dilutedCost = (totalBuyCost - realizedPnlCny) / currentQuantity`（摊薄成本，已实现盈亏会摊低持仓成本）。
- 新增持仓天数统计：`holdingDays = today - 第一次 BUY 的日期`（基于上海时区）。
- Dashboard 首页总览区分展示『持仓盈亏 (Unrealized P&L)』和『总盈亏 (Total P&L)』。
- 持仓卡片新增『平均成本』、『摊薄成本』和『持仓天数』展示。

## 分紅業務邏輯與成本算法修復 (Task 33)
- 重構了分紅的會計處理邏輯，將其正確計入已實現盈虧：DIVIDEND 不再增加持倉數量，而是按 `quantity * price * exchangeRate` 計算分紅金額並累加至 `realizedPnlCny`。
- 新增 `totalDividendCny` 字段追蹤累計分紅金額。
- 修正攤薄成本算法：`dilutedCost = (totalBuyCostCny - realizedPnlCny - totalDividendCny) / currentQuantity`，確保極端情況下攤薄成本為負數時精確返回負數，絕不兜底為 0。
- 平均成本 `avgCost = totalBuyCostCny / totalBuyQuantity` 保持不變，僅在遍歷結束後計算。