TradingAgents-CN 数据库字段标准化实战股票代码统一为 symbol 的渐进式迁移指南【免费下载链接】TradingAgents-CN基于多智能体LLM的中文金融交易框架 - TradingAgents中文增强版项目地址: https://gitcode.com/GitHub_Trending/tr/TradingAgents-CN本文基于 database_field_standardization_completed.md 完成报告结合其前置分析文档与仓库源码模型、路由、服务层、前端工具与迁移脚本完整复盘 TradingAgents-CN 将 MongoDB 各集合中命名混乱的股票代码字段code/stock_code/symbol统一为symbol与full_symbol的迁移全过程。读者读完可掌握问题诊断方法、标准字段模型设计、MongoDB 聚合管道原地迁移、索引重建、前后端渐进式兼容改造以及备份回滚策略并可直接复用仓库中的迁移脚本与字段兼容工具函数。背景为什么需要统一股票代码字段在金融数据系统中股票代码是最核心的关联键一旦命名不一致后续所有查询、关联与分析都会付出隐性维护成本。TradingAgents-CN 在早期演进中不同模块对同一语义采用了不同字段名前置分析文档 database_field_standardization_analysis.md 完整梳理了当时的命名现状集合/模型字段名含义示例stock_basic_infocode6位股票代码000001stock_daily_quotessymbol6位股票代码000001analysis_tasksstock_code6位股票代码000001screening 筛选条件code6位股票代码000001tradingagents.StockBasicInfosymbol6位股票代码000001app.StockBasicInfoExtendedcode6位股票代码000001完整代码带交易所后缀的命名同样割裂tradingagents侧使用exchange_symbol如000001.SZ而app侧模型已有full_symbol字段。这种不一致带来的直接问题包括查询时需要记忆不同集合的字段名、跨集合关联困难、模型层校验口径不一、排查数据问题成本高。分析文档给出了两条候选路线方案一统一使用symbol推荐——符合金融行业惯例与 tradingagents 既有模型一致语义清晰代价是需要改集合、做数据迁移。方案二保留code、追加symbol别名——向后兼容、渐进式迁移代价是字段冗余、维护成本上升。最终项目选择了方案一为主、方案二为过渡手段的组合策略字段标准统一为symbol但在迁移与过渡期内保留旧字段作为兼容层。标准化字段定义如下symbol: str # 6位股票代码如 000001 full_symbol: str # 完整代码如 000001.SZ market: str # 市场代码如 SZ, SH, BJ exchange: str # 交易所代码如 SZSE, SSE exchange_name: str # 交易所名称如 深圳证券交易所可选迁移执行结果两个集合 100% 完成完成报告记录了 2025-10-09 执行的迁移结果影响范围覆盖数据库集合、模型定义与 API 路由整体进度约 95%代码更新 100%。stock_basic_info 集合5,439 条记录迁移前该集合仅使用code字段且缺少完整代码字段迁移后✅ 为全部 5,439 条记录100%添加symbol、full_symbol、market_code字段✅ 创建唯一索引symbol_1_unique✅ 创建唯一索引full_symbol_1_unique✅ 创建复合索引market_symbol_1 备份集合stock_basic_info_backup_20251009_090723analysis_tasks 集合79 条记录迁移前使用stock_code字段迁移后✅ 为全部 79 条记录100%添加symbol字段✅ 创建复合索引symbol_created_at_1✅ 创建复合索引user_symbol_1 备份集合analysis_tasks_backup_20251009_090723迁移脚本dry-run / execute 双模式可复用迁移并非手工操作而是沉淀为可复用的 Python 脚本 standardize_stock_code_fields.py支持三种调用方式python scripts/migration/standardize_stock_code_fields.py --dry-run # 预览模式不修改数据 python scripts/migration/standardize_stock_code_fields.py --execute # 执行迁移 python scripts/migration/standardize_stock_code_fields.py --rollback # 回滚脚本内暂未实现见下文回滚方案脚本默认连接参数来自环境变量MONGODB_HOST默认 localhost、MONGODB_PORT默认 27017、MONGODB_USERNAME默认 admin、MONGODB_PASSWORD、MONGODB_AUTH_SOURCE默认 admin、MONGODB_DATABASE默认 tradingagents。脚本核心流程分四步与完成报告一一对应第 1 步备份集合。通过 MongoDB 聚合管道的$out阶段复制集合pipeline [{$match: {}}, {$out: backup_name}] list(self.db[collection_name].aggregate(pipeline))备份名带时间戳后缀*_backup_20251009_090723backup_suffix在实例化时由datetime.now().strftime(%Y%m%d_%H%M%S)生成确保每次执行互不覆盖。第 2 步添加新字段原地迁移。使用聚合管道更新update_many$set在不重建集合的前提下为存量记录补字段。对stock_basic_infosymbol直接复制自codefull_symbol与market_code则根据market字段中的中文关键字深圳/上海/北京通过$switch推断后缀{ $set: { symbol: $code, full_symbol: { $concat: [ $code, ., { $switch: { branches: [ { case: { $regexMatch: { input: $market, regex: 深圳 } }, then: SZ }, { case: { $regexMatch: { input: $market, regex: 上海 } }, then: SH }, { case: { $regexMatch: { input: $market, regex: 北京 } }, then: BJ } ], default: SZ } } ] }, market_code: { /* 同样的 $switch 推断 */ } } }对analysis_tasks则简单得多{$set: {symbol: $stock_code}}。注意这种写法比应用层逐条读取再写入高效得多且天然原子。第 3 步重建索引。创建新索引前先清理旧索引例如检测到旧的非唯一symbol_1索引时先drop_index再创建唯一索引避免唯一约束冲突collection.create_index([(symbol, ASCENDING)], uniqueTrue, namesymbol_1_unique) collection.create_index([(full_symbol, ASCENDING)], uniqueTrue, namefull_symbol_1_unique) collection.create_index([(market_code, ASCENDING), (symbol, ASCENDING)], namemarket_symbol_1) collection.create_index([(symbol, ASCENDING), (created_at, DESCENDING)], namesymbol_created_at_1) collection.create_index([(user_id, ASCENDING), (symbol, ASCENDING)], nameuser_symbol_1)第 4 步验证完整性。统计symbol/full_symbol字段存在且非空的比例与总数比对后输出✅ 验证通过或❌ 验证失败保证迁移可量化验收。模型层symbol 为主、code 兼容迁移落地的第一道关卡是 Pydantic 模型。在 app/models/stock_models.py 中StockBasicInfoExtended的主字段从code切换为symbol与full_symbol旧字段降级为可选兼容字段# 旧版本 class StockBasicInfoExtended(BaseModel): code: str Field(..., description6位股票代码) symbol: Optional[str] Field(None, description标准化股票代码) # 新版本 class StockBasicInfoExtended(BaseModel): symbol: str Field(..., description6位股票代码, patternr^\d{6}$) full_symbol: str Field(..., description完整标准化代码(如 000001.SZ)) name: str Field(..., description股票名称) code: Optional[str] Field(None, description6位股票代码(已废弃,使用symbol))关键细节有三处格式约束symbol使用patternr^\d{6}$强制 6 位数字full_symbol形如000001.SZ从模型层拦截非法代码。向后兼容Config中extra allow允许额外字段确保老数据中的market、sse、sec等字段不被丢弃同时保留code字段并在描述中明确标记已废弃。市场信息结构化新增MarketInfo子模型market/exchange/exchange_name/currency/timezone/trading_hours配合MarketTypeCN|HK|US与ExchangeTypeSZSE|SSE|SEHK|NYSE|NASDAQ字面量枚举为多市场扩展预留空间。MarketQuotesExtended同样将主字段改为symbol保留code兼容字段。在 app/models/analysis.py 中分析域模型完成对称改造AnalysisTask主字段改为symbolstock_code保留为废弃兼容字段并保留task_id、batch_id、user_id、status、progress、parameters、result、retry_count默认 3 次重试等原有结构。StockInfo主字段改为symbol。SingleAnalysisRequest/BatchAnalysisRequest/AnalysisHistoryQuery请求模型同时接受新旧字段并提供兼容方法统一取码class SingleAnalysisRequest(BaseModel): symbol: Optional[str] Field(None, description6位股票代码) stock_code: Optional[str] Field(None, description股票代码(已废弃,使用symbol)) def get_symbol(self) - str: 获取股票代码(兼容旧字段) return self.symbol or self.stock_code or BatchAnalysisRequest.get_symbols()同样实现symbols or stock_codes的回退逻辑且symbols限制最多 10 个AnalysisTaskResponse则同时返回symbol与新加入的stock_code兼容字段保证旧客户端仍能解析。路由层API 路径参数 code → symbol路由层是外部调用方感知最强的部分app/routers/stock_data.py 中三个核心接口的路径参数全部从{code}改为{symbol}# 旧版本 router.get(/basic-info/{code}) async def get_stock_basic_info(code: str): ... # 新版本 router.get(/basic-info/{symbol}) async def get_stock_basic_info(symbol: str): ...对应端点变更清单/api/stock-data/basic-info/{code}→/api/stock-data/basic-info/{symbol}/api/stock-data/quotes/{code}→/api/stock-data/quotes/{symbol}/api/stock-data/combined/{code}→/api/stock-data/combined/{symbol}同时search接口的搜索条件改为基于symbol字段6 位数字关键词走精确匹配{symbol: keyword}非纯数字走名称/代码模糊匹配$regex并叠加数据源优先级筛选tushare akshare baostock返回前统一经过_standardize_basic_info()标准化。分析路由 app/routers/analysis.py 同步更新get_task_progress()返回symbol与兼容字段、get_analysis_result()查询支持symbol、batch_analyze()走request.get_symbols()、get_analysis_history()查询参数同时接受symbol和stock_code。需要说明的是路径参数的更换属于破坏性变更影响所有调用方完成报告明确指出前端需要更新 API 调用路径而模型字段层面的兼容则属于非破坏性变更两者搭配实现了API 向前、数据向后的渐进式迁移节奏。服务层$or 双字段查询 标准化兜底服务层是兼容策略的真正执行者。在 app/services/stock_data_service.py 中get_stock_basic_info()与get_market_quotes()的查询条件统一写成symbol6 str(symbol).zfill(6) # 自动补零兼容 1 - 000001 query {$or: [{symbol: symbol6}, {code: symbol6}]} doc await db[self.basic_info_collection].find_one(query, {_id: 0})即同一查询同时命中新旧字段无论数据处于迁移前还是迁移后都能读到。get_stock_basic_info()还支持source参数按数据源优先级tushare multi_source akshare baostock逐级探测找不到时回退到无source条件的旧数据查询并打 warning 日志。_standardize_basic_info()与_standardize_market_quotes()承担标准化兜底职责从源码可见其完整逻辑取码优先级doc.get(symbol) or doc.get(code, )优先新字段。完整代码推断full_symbol缺失时按代码前缀推断交易所——60/68/90开头归上交所.SS、SSE00/30/20开头归深交所.SZ、SZSE否则默认深交所若已存在full_symbol则从中解析交易所归属。市场信息装配统一生成market_info对象market: CN、currency: CNY、timezone: Asia/Shanghai、交易时段09:30-15:00含午休11:30-13:00。字段映射board - sse、sector - sec、默认status: L、data_version: 1。日期规范化将整数形式的list_date如YYYYMMDD转换为YYYY-MM-DD字符串。写入侧update_stock_basic_info()/update_market_quotes()则以{symbol: symbol6}为查询条件执行upsertTrue更新确保新数据一律落在新字段上。分析服务层 app/services/analysis_service.py 的改造则体现为内部统一用 symbol、入口兼容旧字段_execute_analysis_with_progress()、_execute_analysis_sync()、_execute_single_analysis_async()、execute_analysis()、_record_usage()全部改用task.symbolsubmit_single_analysis()/submit_batch_analysis()通过request.get_symbol()/request.get_symbols()兼容方法取码get_task_progress()响应同时返回symbol与stock_code两个字段。前端API 类型、视图与兼容工具函数前端改造分为 API 层、类型定义、工具函数与视图组件四部分完成报告中逐项勾选API 层frontend/src/api/stocks.ts 所有接口类型添加symbol/full_symbol字段frontend/src/api/analysis.ts 请求与响应类型支持symbolfrontend/src/api/favorites.ts 收藏接口支持symbol。类型定义frontend/src/types/analysis.ts 所有分析相关类型支持symbol字段。工具函数新增 frontend/src/utils/stock.ts这是前端兼容层的核心从源码可见其导出 11 个工具函数覆盖取码、校验、格式化、推断与批量转换全链路函数职责getStockSymbol(obj)从任意对象兼容symbol/stock_code/code获取股票代码getFullSymbol(obj)获取完整代码createSymbolObject()创建兼容对象normalizeSymbols()标准化代码列表validateSymbol(symbol, market)按市场规则校验代码格式formatSymbol(symbol, market)格式化显示extractSymbol(fullSymbol)从完整代码提取 6 位代码inferMarketCode(symbol)根据代码前缀推断市场代码buildFullSymbol(symbol, marketCode)构建完整代码normalizeStockObject(obj)转换单个对象字段normalizeStockArray(arr)批量转换数组视图组件frontend/src/views/Analysis/SingleAnalysis.vue单股分析表单与结果显示、BatchAnalysis.vue批量分析列表处理、AnalysisHistory.vue历史记录展示、Stocks/Detail.vue股票详情、Screening/index.vue筛选结果处理均完成symbol适配。前端验证命令cd frontend npm run type-check。兼容性策略五层渐进式保障完成报告将兼容性处理总结为五条这与源码实现一一对应数据库查询使用$or同时查询symbol和code字段见 stock_data_service.py 等处的查询条件。模型字段保留code/stock_code为可选字段Pydantic 模型extra allow兜底。兼容方法get_symbol()/get_symbols()统一入口app/models/analysis.py。响应数据同时返回symbol与stock_code字段旧客户端无感。前端工具getStockSymbol等 11 个工具函数屏蔽字段差异。这套新旧并存的过渡设计将破坏性变更限定在 API 路径一层数据库与模型层对存量调用方完全透明。验证、回滚与影响评估验证清单数据库侧stock_basic_info全部记录含symbol与full_symbol、analysis_tasks全部记录含symbol、索引创建成功、数据备份完成——均已通过scripts/validation/验证脚本更新列为 P2 待办。代码侧模型、路由、服务层、前端 API/类型/工具/视图更新全部完成完整测试pytest tests/ -v标记为待执行。兼容性侧旧字段保留、兼容方法就位、查询支持新旧字段均已通过旧 API 是否仍可用的回归测试待补充。回滚方案完成报告给出了两条回滚路径。数据库层面通过备份集合恢复// 1. 恢复集合 db.stock_basic_info.drop() db.stock_basic_info_backup_20251009_090723.renameCollection(stock_basic_info) db.analysis_tasks.drop() db.analysis_tasks_backup_20251009_090723.renameCollection(analysis_tasks) // 2. 恢复旧索引 db.stock_basic_info.createIndex({ code: 1 }, { unique: true }) db.analysis_tasks.createIndex({ stock_code: 1, created_at: -1 })代码层面通过git revert commit-hash回滚具体提交哈希以仓库 Git 历史为准。注意迁移脚本的--rollback参数当前仅打印尚未实现提示回滚请按上述 MongoDB 命令手工执行。破坏性 vs 非破坏性类型内容影响破坏性三个 API 端点路径参数{code}→{symbol}前端需同步更新调用路径非破坏性模型保留旧字段、兼容方法、数据库新旧字段并存、响应双字段影响最小化渐进式迁移下一步行动完成报告按节奏拆分了后续工作立即代码层完成服务层/路由层收尾运行pytest tests/ -v全量回归。本周前端层npm run type-check类型检查、重新生成 OpenAPI 文档、覆盖全部 API 端点与前端功能测试。下周清理层确认功能稳定后可选删除code/stock_code旧字段、更新用户手册与开发文档——对应分析文档中的阶段 4$unset旧字段并dropIndex(code_1)。总结与经验提炼本次迁移的总体进度约 95%数据库迁移、模型定义、路由、服务层、前端 API/类型/工具/视图均 100% 完成文档更新与完整测试待收尾。从工程方法论角度这次标准化实践提炼出几条可复用的经验先分析后动手迁移前用分析文档盘点全部集合与模型的字段命名矩阵database_field_standardization_analysis.md明确统一到什么标准、影响哪些文件避免边改边踩坑。脚本化 双模式迁移逻辑沉淀为--dry-run/--execute双模式的独立脚本standardize_stock_code_fields.py可预览、可执行、可复用而非一次性手工命令。原地聚合更新用 MongoDBupdate_many 聚合管道$set在集合内完成字段复制与后缀推断秒级完成数万条记录迁移无需重建集合。兼容层分五路兜底查询$or、模型可选字段、兼容方法、响应双字段、前端工具函数五层保障让存量调用方在整个过渡期内无感知。索引先行治理唯一索引symbol_1_unique、full_symbol_1_unique保证数据唯一性复合索引market_symbol_1、symbol_created_at_1、user_symbol_1保证查询性能为后续多市场扩展HK/US预留了market/market_code维度。对任何以 MongoDB 为核心存储、且经过多模块迭代演进的金融数据项目而言股票代码字段标准化都是一堂必修课它不只是一次数据改写而是一次贯穿数据库、模型、API、前端与运维脚本的全链路契约统一。本文给出的方案、脚本与兼容策略可直接作为同类迁移的参考模板。文档版本信息本文基于完成报告 v2.0创建与最后更新均为 2025-10-09及分析文档 v1.02024-01-15撰写仓库证据指向 docs/architecture/database/ 目录下两份原始文档。【免费下载链接】TradingAgents-CN基于多智能体LLM的中文金融交易框架 - TradingAgents中文增强版项目地址: https://gitcode.com/GitHub_Trending/tr/TradingAgents-CN创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
TradingAgents-CN 数据库字段标准化实战：股票代码统一为 symbol 的渐进式迁移指南
TradingAgents-CN 数据库字段标准化实战股票代码统一为 symbol 的渐进式迁移指南【免费下载链接】TradingAgents-CN基于多智能体LLM的中文金融交易框架 - TradingAgents中文增强版项目地址: https://gitcode.com/GitHub_Trending/tr/TradingAgents-CN本文基于 database_field_standardization_completed.md 完成报告结合其前置分析文档与仓库源码模型、路由、服务层、前端工具与迁移脚本完整复盘 TradingAgents-CN 将 MongoDB 各集合中命名混乱的股票代码字段code/stock_code/symbol统一为symbol与full_symbol的迁移全过程。读者读完可掌握问题诊断方法、标准字段模型设计、MongoDB 聚合管道原地迁移、索引重建、前后端渐进式兼容改造以及备份回滚策略并可直接复用仓库中的迁移脚本与字段兼容工具函数。背景为什么需要统一股票代码字段在金融数据系统中股票代码是最核心的关联键一旦命名不一致后续所有查询、关联与分析都会付出隐性维护成本。TradingAgents-CN 在早期演进中不同模块对同一语义采用了不同字段名前置分析文档 database_field_standardization_analysis.md 完整梳理了当时的命名现状集合/模型字段名含义示例stock_basic_infocode6位股票代码000001stock_daily_quotessymbol6位股票代码000001analysis_tasksstock_code6位股票代码000001screening 筛选条件code6位股票代码000001tradingagents.StockBasicInfosymbol6位股票代码000001app.StockBasicInfoExtendedcode6位股票代码000001完整代码带交易所后缀的命名同样割裂tradingagents侧使用exchange_symbol如000001.SZ而app侧模型已有full_symbol字段。这种不一致带来的直接问题包括查询时需要记忆不同集合的字段名、跨集合关联困难、模型层校验口径不一、排查数据问题成本高。分析文档给出了两条候选路线方案一统一使用symbol推荐——符合金融行业惯例与 tradingagents 既有模型一致语义清晰代价是需要改集合、做数据迁移。方案二保留code、追加symbol别名——向后兼容、渐进式迁移代价是字段冗余、维护成本上升。最终项目选择了方案一为主、方案二为过渡手段的组合策略字段标准统一为symbol但在迁移与过渡期内保留旧字段作为兼容层。标准化字段定义如下symbol: str # 6位股票代码如 000001 full_symbol: str # 完整代码如 000001.SZ market: str # 市场代码如 SZ, SH, BJ exchange: str # 交易所代码如 SZSE, SSE exchange_name: str # 交易所名称如 深圳证券交易所可选迁移执行结果两个集合 100% 完成完成报告记录了 2025-10-09 执行的迁移结果影响范围覆盖数据库集合、模型定义与 API 路由整体进度约 95%代码更新 100%。stock_basic_info 集合5,439 条记录迁移前该集合仅使用code字段且缺少完整代码字段迁移后✅ 为全部 5,439 条记录100%添加symbol、full_symbol、market_code字段✅ 创建唯一索引symbol_1_unique✅ 创建唯一索引full_symbol_1_unique✅ 创建复合索引market_symbol_1 备份集合stock_basic_info_backup_20251009_090723analysis_tasks 集合79 条记录迁移前使用stock_code字段迁移后✅ 为全部 79 条记录100%添加symbol字段✅ 创建复合索引symbol_created_at_1✅ 创建复合索引user_symbol_1 备份集合analysis_tasks_backup_20251009_090723迁移脚本dry-run / execute 双模式可复用迁移并非手工操作而是沉淀为可复用的 Python 脚本 standardize_stock_code_fields.py支持三种调用方式python scripts/migration/standardize_stock_code_fields.py --dry-run # 预览模式不修改数据 python scripts/migration/standardize_stock_code_fields.py --execute # 执行迁移 python scripts/migration/standardize_stock_code_fields.py --rollback # 回滚脚本内暂未实现见下文回滚方案脚本默认连接参数来自环境变量MONGODB_HOST默认 localhost、MONGODB_PORT默认 27017、MONGODB_USERNAME默认 admin、MONGODB_PASSWORD、MONGODB_AUTH_SOURCE默认 admin、MONGODB_DATABASE默认 tradingagents。脚本核心流程分四步与完成报告一一对应第 1 步备份集合。通过 MongoDB 聚合管道的$out阶段复制集合pipeline [{$match: {}}, {$out: backup_name}] list(self.db[collection_name].aggregate(pipeline))备份名带时间戳后缀*_backup_20251009_090723backup_suffix在实例化时由datetime.now().strftime(%Y%m%d_%H%M%S)生成确保每次执行互不覆盖。第 2 步添加新字段原地迁移。使用聚合管道更新update_many$set在不重建集合的前提下为存量记录补字段。对stock_basic_infosymbol直接复制自codefull_symbol与market_code则根据market字段中的中文关键字深圳/上海/北京通过$switch推断后缀{ $set: { symbol: $code, full_symbol: { $concat: [ $code, ., { $switch: { branches: [ { case: { $regexMatch: { input: $market, regex: 深圳 } }, then: SZ }, { case: { $regexMatch: { input: $market, regex: 上海 } }, then: SH }, { case: { $regexMatch: { input: $market, regex: 北京 } }, then: BJ } ], default: SZ } } ] }, market_code: { /* 同样的 $switch 推断 */ } } }对analysis_tasks则简单得多{$set: {symbol: $stock_code}}。注意这种写法比应用层逐条读取再写入高效得多且天然原子。第 3 步重建索引。创建新索引前先清理旧索引例如检测到旧的非唯一symbol_1索引时先drop_index再创建唯一索引避免唯一约束冲突collection.create_index([(symbol, ASCENDING)], uniqueTrue, namesymbol_1_unique) collection.create_index([(full_symbol, ASCENDING)], uniqueTrue, namefull_symbol_1_unique) collection.create_index([(market_code, ASCENDING), (symbol, ASCENDING)], namemarket_symbol_1) collection.create_index([(symbol, ASCENDING), (created_at, DESCENDING)], namesymbol_created_at_1) collection.create_index([(user_id, ASCENDING), (symbol, ASCENDING)], nameuser_symbol_1)第 4 步验证完整性。统计symbol/full_symbol字段存在且非空的比例与总数比对后输出✅ 验证通过或❌ 验证失败保证迁移可量化验收。模型层symbol 为主、code 兼容迁移落地的第一道关卡是 Pydantic 模型。在 app/models/stock_models.py 中StockBasicInfoExtended的主字段从code切换为symbol与full_symbol旧字段降级为可选兼容字段# 旧版本 class StockBasicInfoExtended(BaseModel): code: str Field(..., description6位股票代码) symbol: Optional[str] Field(None, description标准化股票代码) # 新版本 class StockBasicInfoExtended(BaseModel): symbol: str Field(..., description6位股票代码, patternr^\d{6}$) full_symbol: str Field(..., description完整标准化代码(如 000001.SZ)) name: str Field(..., description股票名称) code: Optional[str] Field(None, description6位股票代码(已废弃,使用symbol))关键细节有三处格式约束symbol使用patternr^\d{6}$强制 6 位数字full_symbol形如000001.SZ从模型层拦截非法代码。向后兼容Config中extra allow允许额外字段确保老数据中的market、sse、sec等字段不被丢弃同时保留code字段并在描述中明确标记已废弃。市场信息结构化新增MarketInfo子模型market/exchange/exchange_name/currency/timezone/trading_hours配合MarketTypeCN|HK|US与ExchangeTypeSZSE|SSE|SEHK|NYSE|NASDAQ字面量枚举为多市场扩展预留空间。MarketQuotesExtended同样将主字段改为symbol保留code兼容字段。在 app/models/analysis.py 中分析域模型完成对称改造AnalysisTask主字段改为symbolstock_code保留为废弃兼容字段并保留task_id、batch_id、user_id、status、progress、parameters、result、retry_count默认 3 次重试等原有结构。StockInfo主字段改为symbol。SingleAnalysisRequest/BatchAnalysisRequest/AnalysisHistoryQuery请求模型同时接受新旧字段并提供兼容方法统一取码class SingleAnalysisRequest(BaseModel): symbol: Optional[str] Field(None, description6位股票代码) stock_code: Optional[str] Field(None, description股票代码(已废弃,使用symbol)) def get_symbol(self) - str: 获取股票代码(兼容旧字段) return self.symbol or self.stock_code or BatchAnalysisRequest.get_symbols()同样实现symbols or stock_codes的回退逻辑且symbols限制最多 10 个AnalysisTaskResponse则同时返回symbol与新加入的stock_code兼容字段保证旧客户端仍能解析。路由层API 路径参数 code → symbol路由层是外部调用方感知最强的部分app/routers/stock_data.py 中三个核心接口的路径参数全部从{code}改为{symbol}# 旧版本 router.get(/basic-info/{code}) async def get_stock_basic_info(code: str): ... # 新版本 router.get(/basic-info/{symbol}) async def get_stock_basic_info(symbol: str): ...对应端点变更清单/api/stock-data/basic-info/{code}→/api/stock-data/basic-info/{symbol}/api/stock-data/quotes/{code}→/api/stock-data/quotes/{symbol}/api/stock-data/combined/{code}→/api/stock-data/combined/{symbol}同时search接口的搜索条件改为基于symbol字段6 位数字关键词走精确匹配{symbol: keyword}非纯数字走名称/代码模糊匹配$regex并叠加数据源优先级筛选tushare akshare baostock返回前统一经过_standardize_basic_info()标准化。分析路由 app/routers/analysis.py 同步更新get_task_progress()返回symbol与兼容字段、get_analysis_result()查询支持symbol、batch_analyze()走request.get_symbols()、get_analysis_history()查询参数同时接受symbol和stock_code。需要说明的是路径参数的更换属于破坏性变更影响所有调用方完成报告明确指出前端需要更新 API 调用路径而模型字段层面的兼容则属于非破坏性变更两者搭配实现了API 向前、数据向后的渐进式迁移节奏。服务层$or 双字段查询 标准化兜底服务层是兼容策略的真正执行者。在 app/services/stock_data_service.py 中get_stock_basic_info()与get_market_quotes()的查询条件统一写成symbol6 str(symbol).zfill(6) # 自动补零兼容 1 - 000001 query {$or: [{symbol: symbol6}, {code: symbol6}]} doc await db[self.basic_info_collection].find_one(query, {_id: 0})即同一查询同时命中新旧字段无论数据处于迁移前还是迁移后都能读到。get_stock_basic_info()还支持source参数按数据源优先级tushare multi_source akshare baostock逐级探测找不到时回退到无source条件的旧数据查询并打 warning 日志。_standardize_basic_info()与_standardize_market_quotes()承担标准化兜底职责从源码可见其完整逻辑取码优先级doc.get(symbol) or doc.get(code, )优先新字段。完整代码推断full_symbol缺失时按代码前缀推断交易所——60/68/90开头归上交所.SS、SSE00/30/20开头归深交所.SZ、SZSE否则默认深交所若已存在full_symbol则从中解析交易所归属。市场信息装配统一生成market_info对象market: CN、currency: CNY、timezone: Asia/Shanghai、交易时段09:30-15:00含午休11:30-13:00。字段映射board - sse、sector - sec、默认status: L、data_version: 1。日期规范化将整数形式的list_date如YYYYMMDD转换为YYYY-MM-DD字符串。写入侧update_stock_basic_info()/update_market_quotes()则以{symbol: symbol6}为查询条件执行upsertTrue更新确保新数据一律落在新字段上。分析服务层 app/services/analysis_service.py 的改造则体现为内部统一用 symbol、入口兼容旧字段_execute_analysis_with_progress()、_execute_analysis_sync()、_execute_single_analysis_async()、execute_analysis()、_record_usage()全部改用task.symbolsubmit_single_analysis()/submit_batch_analysis()通过request.get_symbol()/request.get_symbols()兼容方法取码get_task_progress()响应同时返回symbol与stock_code两个字段。前端API 类型、视图与兼容工具函数前端改造分为 API 层、类型定义、工具函数与视图组件四部分完成报告中逐项勾选API 层frontend/src/api/stocks.ts 所有接口类型添加symbol/full_symbol字段frontend/src/api/analysis.ts 请求与响应类型支持symbolfrontend/src/api/favorites.ts 收藏接口支持symbol。类型定义frontend/src/types/analysis.ts 所有分析相关类型支持symbol字段。工具函数新增 frontend/src/utils/stock.ts这是前端兼容层的核心从源码可见其导出 11 个工具函数覆盖取码、校验、格式化、推断与批量转换全链路函数职责getStockSymbol(obj)从任意对象兼容symbol/stock_code/code获取股票代码getFullSymbol(obj)获取完整代码createSymbolObject()创建兼容对象normalizeSymbols()标准化代码列表validateSymbol(symbol, market)按市场规则校验代码格式formatSymbol(symbol, market)格式化显示extractSymbol(fullSymbol)从完整代码提取 6 位代码inferMarketCode(symbol)根据代码前缀推断市场代码buildFullSymbol(symbol, marketCode)构建完整代码normalizeStockObject(obj)转换单个对象字段normalizeStockArray(arr)批量转换数组视图组件frontend/src/views/Analysis/SingleAnalysis.vue单股分析表单与结果显示、BatchAnalysis.vue批量分析列表处理、AnalysisHistory.vue历史记录展示、Stocks/Detail.vue股票详情、Screening/index.vue筛选结果处理均完成symbol适配。前端验证命令cd frontend npm run type-check。兼容性策略五层渐进式保障完成报告将兼容性处理总结为五条这与源码实现一一对应数据库查询使用$or同时查询symbol和code字段见 stock_data_service.py 等处的查询条件。模型字段保留code/stock_code为可选字段Pydantic 模型extra allow兜底。兼容方法get_symbol()/get_symbols()统一入口app/models/analysis.py。响应数据同时返回symbol与stock_code字段旧客户端无感。前端工具getStockSymbol等 11 个工具函数屏蔽字段差异。这套新旧并存的过渡设计将破坏性变更限定在 API 路径一层数据库与模型层对存量调用方完全透明。验证、回滚与影响评估验证清单数据库侧stock_basic_info全部记录含symbol与full_symbol、analysis_tasks全部记录含symbol、索引创建成功、数据备份完成——均已通过scripts/validation/验证脚本更新列为 P2 待办。代码侧模型、路由、服务层、前端 API/类型/工具/视图更新全部完成完整测试pytest tests/ -v标记为待执行。兼容性侧旧字段保留、兼容方法就位、查询支持新旧字段均已通过旧 API 是否仍可用的回归测试待补充。回滚方案完成报告给出了两条回滚路径。数据库层面通过备份集合恢复// 1. 恢复集合 db.stock_basic_info.drop() db.stock_basic_info_backup_20251009_090723.renameCollection(stock_basic_info) db.analysis_tasks.drop() db.analysis_tasks_backup_20251009_090723.renameCollection(analysis_tasks) // 2. 恢复旧索引 db.stock_basic_info.createIndex({ code: 1 }, { unique: true }) db.analysis_tasks.createIndex({ stock_code: 1, created_at: -1 })代码层面通过git revert commit-hash回滚具体提交哈希以仓库 Git 历史为准。注意迁移脚本的--rollback参数当前仅打印尚未实现提示回滚请按上述 MongoDB 命令手工执行。破坏性 vs 非破坏性类型内容影响破坏性三个 API 端点路径参数{code}→{symbol}前端需同步更新调用路径非破坏性模型保留旧字段、兼容方法、数据库新旧字段并存、响应双字段影响最小化渐进式迁移下一步行动完成报告按节奏拆分了后续工作立即代码层完成服务层/路由层收尾运行pytest tests/ -v全量回归。本周前端层npm run type-check类型检查、重新生成 OpenAPI 文档、覆盖全部 API 端点与前端功能测试。下周清理层确认功能稳定后可选删除code/stock_code旧字段、更新用户手册与开发文档——对应分析文档中的阶段 4$unset旧字段并dropIndex(code_1)。总结与经验提炼本次迁移的总体进度约 95%数据库迁移、模型定义、路由、服务层、前端 API/类型/工具/视图均 100% 完成文档更新与完整测试待收尾。从工程方法论角度这次标准化实践提炼出几条可复用的经验先分析后动手迁移前用分析文档盘点全部集合与模型的字段命名矩阵database_field_standardization_analysis.md明确统一到什么标准、影响哪些文件避免边改边踩坑。脚本化 双模式迁移逻辑沉淀为--dry-run/--execute双模式的独立脚本standardize_stock_code_fields.py可预览、可执行、可复用而非一次性手工命令。原地聚合更新用 MongoDBupdate_many 聚合管道$set在集合内完成字段复制与后缀推断秒级完成数万条记录迁移无需重建集合。兼容层分五路兜底查询$or、模型可选字段、兼容方法、响应双字段、前端工具函数五层保障让存量调用方在整个过渡期内无感知。索引先行治理唯一索引symbol_1_unique、full_symbol_1_unique保证数据唯一性复合索引market_symbol_1、symbol_created_at_1、user_symbol_1保证查询性能为后续多市场扩展HK/US预留了market/market_code维度。对任何以 MongoDB 为核心存储、且经过多模块迭代演进的金融数据项目而言股票代码字段标准化都是一堂必修课它不只是一次数据改写而是一次贯穿数据库、模型、API、前端与运维脚本的全链路契约统一。本文给出的方案、脚本与兼容策略可直接作为同类迁移的参考模板。文档版本信息本文基于完成报告 v2.0创建与最后更新均为 2025-10-09及分析文档 v1.02024-01-15撰写仓库证据指向 docs/architecture/database/ 目录下两份原始文档。【免费下载链接】TradingAgents-CN基于多智能体LLM的中文金融交易框架 - TradingAgents中文增强版项目地址: https://gitcode.com/GitHub_Trending/tr/TradingAgents-CN创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考