portfolio

用途

Portfolio 是一个投资组合（Portfolio）系统的知识库技能，用于在涉及持仓查询、路由策略和提供商集成等场景时提供领域知识支持。其触发关键词包括 Portfolio、portfolio、position、{PRIMARY_PROVIDER}、protocol、lending、staking、liquidity。

主要能力

该技能围绕投资组合系统的核心模块组织知识，涵盖以下文件类型：

• Controller：src/entity/portfolio/portfolio.controller.ts，提供 REST API。
• Router：src/service/portfolio/source-router/*.service.ts，负责路由编排。
• Client：src/service/portfolio/providers/{provider}/*.ts，负责 {PRIMARY_PROVIDER} 集成。
• Aggregator：src/service/portfolio/aggregation/*.service.ts，负责聚合计算。
• DTO：src/dto/portfolio/position.types.ts，定义持仓模型。

API 概览（基础路径：/onchain/v1/portfolio）：

• POST /positions：获取投资组合持仓。
• GET /chains：获取支持的链列表。
• GET /protocols：获取支持的协议列表。

输出形式为带代码引用的领域查询结果，以及基于当前架构的分析与建议。

使用方式

该技能通过关键词触发，在用户提出持仓查询、路由策略或提供商集成相关问题时启用。典型示例：

• 输入“如何查询投资组合持仓？”时，解释 POST /positions API 及路由策略。
• 输入“{PRIMARY_PROVIDER} 集成如何工作？”时，解释 {PRIMARY_PROVIDER}Client 与 {PRIMARY_PROVIDER}Adapter 流程。

开发指南方面，添加协议支持时需先确认 {PRIMARY_PROVIDER} 是否支持；若需自定义构建，则实现 PortfolioPositionExtractor、注册并配置路由。添加数据源时需实现 ProviderClient 与 Adapter，注册到 SourceRouter 并配置路由策略。

调试方式包括：

• redis-cli keys "portfolio:{provider}:*"
• redis-cli get "portfolio:{provider}:positions:0x...:v2:..."
• curl -X POST /positions -d '{"isForceRefresh": true, ...}'

验证要点包括：持仓数据是否正确归一化、缓存命中/未命中是否正常工作、聚合计算是否准确。

适用场景

适用于投资组合持仓数据查询、路由策略咨询、提供商集成说明，以及围绕该系统的开发与调试指导。

限制

不适用于通用代币查询（非 Portfolio 持仓）、交易构建（应使用对应提供商）以及非投资组合相关的 API 问题。

参考资料与测试

参考资料包括 references/architecture.md（系统架构与缓存策略）、references/api.md（API 参考与数据模型）以及 @docs/features/portfolio/（详细文档）。测试分为单元测试（test/unit/service/portfolio/）与集成测试（test/integration/portfolio/）。