将 NetSuite SuiteScript…

当需要把遗留 SuiteScript 1.0、2.0 或 2.x 代码升级到 SuiteScript 2.1 时，按 analyze→convert→validate 流程执行完整迁移。

适用场景

解决思路

1. 用 analyze 模式扫描脚本：确认版本、识别脚本类型、统计所有 nlapi* 调用与 nlobj* 对象、检查未映射 API 与破坏性变更模式、按复杂度评分矩阵打分并输出迁移报告。
2. 用 convert 模式转换：构建 define() 模块列表、按 api-mapping.json 转换所有 nlapi* 调用、按 object-mapping.json 转换所有 nlobj* 对象、应用破坏性变更、处理未映射 API、添加 @NApiVersion 2.1 与 @NScriptType 的 JSDoc、重构入口点为返回对象模式、现代化 JavaScript（var→const/let、模板字符串、includes）、生成部署 XML 更新说明与迁移记录。
3. 用 explain 模式查询具体 API 映射、对象转换或迁移概念（如 indexing、options-objects、error-handling、module-loading、entry-points、context-object、enums、properties、inverted-booleans、recovery-points、governance、client-vs-server、search-migration、date-handling、subrecords、scheduled-to-mapreduce），输出 SS1.0 与 SS2.1 签名对比、参数变化、破坏性变更与前后代码示例。
4. 用 validate 模式检查转换后脚本：扫描残留 nlapi*/nlobj* 调用、缺失 @NApiVersion/@NScriptType/define()/return 对象、1-based 索引、位置参数、字符串事件类型比较、旧 getter/setter、define() 中缺失模块、反转布尔错误、旧错误处理、全局入口点、var 使用、保留字冲突、@NApiVersion 2.0/2.x 等 20 项检查，按 Critical/High/Medium/Low 分级输出报告。
5. 按 15 个常见转换模式逐一处理：搜索记录、加载记录、保存记录、客户端读写字段、服务端读写字段、创建记录、子列表读值（0-based）、子列表写值（0-based）、HTTP 请求、发送邮件、获取上下文/运行时、日志记录、错误处理、User Event 入口点迁移、Scheduled Script 转 Map/Reduce。
6. 应用 16 类破坏性变更：模块加载改为 AMD define()、位置参数改为选项对象、字符串事件类型改为枚举、子列表索引从 1-based 改为 0-based、getter/setter 改为属性、布尔反转（setVisible→isHidden）、搜索结果改为 ResultSet 可迭代、上下文拆分为 Script+User+Session、错误对象改为 SuiteScriptError、日志方法改为 log.level({title,details})、记录返回类型改为 record.Record、入口点改为 define() 返回对象、firefieldchanged 布尔逻辑反转、子记录自动提交、恢复点/让出改为 Map/Reduce、SubList 大小写改为 Sublist。
7. 处理 13 个未映射 API：日期运算用原生 JS Date 方法、加密用 N/crypto + N/encode、日期时间值用 N/format、恢复点/让出改用 Map/Reduce、刷新行项目由平台自动处理、发送传真改用第三方集成。
8. 按脚本类型处理入口点变更：User Event（beforeLoad/beforeSubmit/afterSubmit 改为 context 对象）、Client Script（pageInit/saveRecord/validateField/fieldChanged/lineInit/validateLine/validateInsert/validateDelete/recalc→sublistChanged/postSourcing）、Suitelet（onRequest）、RESTlet（get/post/put/delete）、Scheduled（execute）、Map/Reduce（getInputData/map/reduce/summarize）、Portlet（render）、Mass Update（each）、Workflow Action（onAction）。
9. 更新部署 XML：将 scriptfile 路径指向 SS2.1 文件、移除入口点函数名字段（SS2.1 从 define() 返回对象读取入口点）、验证脚本参数兼容性、先部署到 Sandbox、保留 SS1.0 文件作为备份、更新 manifest.xml 引用。
10. 按推荐工作流执行：Step 1 analyze → Step 2 convert --annotated → Step 3 validate → Step 4 生成部署 XML → Step 5 按最佳实践审查 → Step 6 在 Sandbox 测试所有入口点与边界情况并与原 SS1.0 行为对比。
11. 批量迁移策略：先 analyze 所有 SS1.0 脚本盘点范围、优先转换低复杂度脚本、按类型分组转换、先转换共享工具模块、分批增量测试、验证阶段保留 SS1.0 作为备份。
12. 转换目标规则：SuiteScript 2.1 是唯一有效输出，将 @NApiVersion 2.0 与模糊的 2.x 升级为 2.1；不创建兼容垫片、适配层、包装器、外观或 polyfill；每个 SS1.0 API 用法必须直接替换为 SS2.1 API、原生 JavaScript 或文档化的 SS2.1 架构变更；不采用共存、RESTlet 桥接、Suitelet 桥接或并排模式作为迁移结果。
13. 处理异常情况：无法检测脚本类型时按辅助模块转为无 @NScriptType 的 AMD 格式；发现未映射 API 时参考 unmapped-apis.md 的变通方案；检测到 SS1.0 与 2.x 混合代码时说明不能混用并需完整转换为 2.1。
14. 与配套技能集成：转换后用 netsuite-sdf-leading-practices 生成部署 XML 并检查 SAFE Guide 合规与 73+ 陷阱；转换中用 netsuite-suitescript-reference 查字段 ID、记录类型与子列表 ID；转换后用 netsuite-sdf-education 添加学习注释、解释新模式、生成测验。

适用边界 · 注意事项

• 目标脚本已经是 SuiteScript 2.1 且无需升级时。
• 脚本不是 NetSuite SuiteScript（如普通 JavaScript 或其他平台脚本）时。
• 需要保留 SS1.0 与 SS2.1 共存、桥接或并排运行而非完整转换时。