ai-chatbot/docs/商品策划工具迁移评估与实施方案-2026-03-25.md

商品策划工具迁移评估与实施方案

1. 结论摘要

“旧由壹点源码”中的“商品策划工具”可以迁移到当前项目，且推荐迁移。

但它不适合直接把旧的 HTML + 全局 JS + Express 路由 原封不动搬进当前项目。当前项目是 Next.js App Router + React 19 + NextAuth + Drizzle/Postgres + 现有对象存储能力，旧模块则严重依赖：

• 大量页面级全局变量
• DOMContentLoaded 初始化链
• 直接操作 DOM
• 旧系统的 /api/auth/me、/api/cloud-storage/*、/api/evaluation/analyze
• 旧系统的 token/管理员权限判断方式

所以最稳妥的方案不是“复制页面”，而是：

• 复用旧模块的业务逻辑、字段结构、处理流程
• 重写页面层、状态管理层、接口层
• 统一接入当前项目的鉴权、导航、存储和 API 规范

整体可行性评估：高

• 页面迁移可行性：高
• 前端逻辑迁移可行性：中高
• 后端接口迁移可行性：高
• 直接无改造搬运可行性：低

2. 已识别的旧模块范围

旧模块入口：

• 旧由壹点源码/public/keyword-analyzer.html

旧模块实际不是单页小工具，而是一个“商品策划工作台”，至少包含以下能力：

1. 关键词拆词与需求分层分析
2. 云端模板/源数据选择与上传
3. 评价分析
4. 问大家分析
5. 竞品分析
6. 关键词洞察
7. ID 销量查询

关键旧前端文件：

• 旧由壹点源码/public/js/word-segmentation.js
• 旧由壹点源码/public/js/data-processing.js
• 旧由壹点源码/public/js/ui-interaction.js
• 旧由壹点源码/public/js/cloud-storage-manager.js
• 旧由壹点源码/public/js/taobao-data-viewer.js
• 旧由壹点源码/public/js/taobao-rate-analyzer.js
• 旧由壹点源码/public/js/taobao-qa-analyzer.js
• 旧由壹点源码/public/js/taobao-competitor-analyzer.js
• 旧由壹点源码/public/js/keyword-insight.js
• 旧由壹点源码/public/js/id-sales-query.js

关键旧后端文件：

• 旧由壹点源码/server/routes/api/taobao-proxy.js
• 旧由壹点源码/server/routes/api/jd-proxy.js
• 旧由壹点源码/server/routes/evaluation.js
• 旧由壹点源码/server/routes/cloud-storage.js

3. 当前项目适配情况

当前项目已有的基础能力：

• 页面框架：Next.js App Router
• UI 组件：components/ui/*
• 鉴权：app/(auth)/auth.ts，基于 NextAuth
• 导航壳：app/(chat)/layout.tsx、components/chat-shell.tsx、components/top-navbar.tsx
• 服务端 API 约定：app/api/**/route.ts
• 对象存储能力：lib/storage/service.ts
• CSV 处理能力：papaparse

当前项目缺失但迁移所需的能力：

• 商品策划工具专用页面
• 淘宝/京东代理 API
• 问大家/评价聚合 API
• AI 文本分析 API
• 关键词洞察代理 API
• 模板文件管理接口
• Excel 读写依赖和导出能力

4. 为什么不能直接复制旧页面

4.1 页面组织方式不兼容

旧页面是传统静态页模式：

• 页面内联大量样式和脚本
• 使用 window.XXX = ...
• 多个 DOMContentLoaded 重复初始化
• 依赖固定 DOM id 与插入顺序

当前项目是组件化模式：

• Server Component + Client Component 分层
• 由 React 控制状态和生命周期
• 由 route.ts 承接后端 API

直接复制会导致：

• 初始化顺序不可控
• 维护成本极高
• 与现有导航壳、主题、权限体系脱节
• 后续很难继续迭代

4.2 鉴权方式不兼容

旧模块依赖：

• localStorage token
• /api/auth/me
• Express 中间件 requireAuth

当前项目依赖：

• NextAuth session
• 服务器端 auth()

所以模板上传、AI 分析、代理接口权限都需要重写。

4.3 后端接口契约不完整复用

旧接口虽然能作为参考，但存在这些问题：

• 有旧系统专用中间件
• 有硬编码或半硬编码外部 API 依赖
• 有一部分接口路径当前项目根本不存在
• evaluation.js 体量很大，包含旧系统上下文，不适合整体照搬

5. 推荐迁移策略

推荐采用：

业务逻辑迁移 + React 页面重构 + Next API 重建

5.1 可直接迁移的部分

• 关键词拆词算法
• 文件字段识别逻辑
• 结果分组与导出字段结构
• 淘宝/京东外部接口字段映射
• AI 分析 prompt 结构

5.2 需要重写的部分

• 整个页面 UI
• 所有弹窗/Tab/表格展示层
• 所有旧式 DOM 操作
• 所有旧 Express 路由
• 所有旧鉴权逻辑
• 云模板上传和列表管理

6. 推荐的新项目落地结构

建议新增如下结构：

6.1 页面

• app/(chat)/product-planning/page.tsx

6.2 组件

• components/product-planning/ProductPlanningPage.tsx
• components/product-planning/KeywordAnalyzerPanel.tsx
• components/product-planning/ReviewQaPanel.tsx
• components/product-planning/CompetitorPanel.tsx
• components/product-planning/KeywordInsightPanel.tsx
• components/product-planning/IdSalesPanel.tsx
• components/product-planning/TemplateLibraryPanel.tsx

6.3 业务逻辑

• lib/product-planning/types.ts
• lib/product-planning/schemas.ts
• lib/product-planning/keyword-segmentation.ts
• lib/product-planning/data-processing.ts
• lib/product-planning/formatters.ts
• lib/product-planning/taobao.ts
• lib/product-planning/jd.ts
• lib/product-planning/analysis.ts

6.4 API

• app/api/product-planning/taobao/item/route.ts
• app/api/product-planning/taobao/item-pro/route.ts
• app/api/product-planning/taobao/reviews/route.ts
• app/api/product-planning/taobao/qa/route.ts
• app/api/product-planning/taobao/month-sale/route.ts
• app/api/product-planning/jd/item/route.ts
• app/api/product-planning/jd/desc/route.ts
• app/api/product-planning/keyword-insight/route.ts
• app/api/product-planning/analyze/route.ts
• app/api/product-planning/templates/route.ts
• app/api/product-planning/templates/[id]/route.ts

6.5 测试

• tests/routes/product-planning-apis.test.ts
• tests/e2e/product-planning-page.test.ts

7. 模块级迁移建议

7.1 关键词拆词

迁移优先级：最高

原因：

• 这是页面主能力
• 旧逻辑大多是纯前端算法，最容易拆成 TS 模块复用

建议做法：

• 将 word-segmentation.js 和 data-processing.js 拆成纯函数
• 去除对 window、DOM、全局变量的依赖
• 输入统一改为：
  • 上传文件
  • 模板文件
  • 手动分词结果
• 输出统一改为 TS 类型对象，再交给 React 表格组件渲染

7.2 评价分析 / 问大家分析

迁移优先级：最高

建议做法：

• 前端不再从 DOM 里读表格
• 改为：
  • 直接通过 API 获取结构化数据
  • 或上传 Excel/CSV 后解析为结构化数组
• AI 分析通过新的 app/api/product-planning/analyze/route.ts

分析接口建议入参：

• type: "review" | "qa" | "image"
• payload: object
• promptMode?: string

7.3 竞品分析

迁移优先级：高

建议做法：

• 第一版只支持淘宝
• 第二版补京东
• 图片分析不要沿用旧 /api/ai/analyze-image
• 改成统一接入当前项目的 AI 能力

建议前端能力：

• 批量输入商品链接/ID
• 返回基础信息、主图、SKU、销量、店铺、属性
• 导出对比表
• 单图/多图 AI 解析

7.4 关键词洞察

迁移优先级：中高

风险点：

• 旧实现里有直接请求外部接口的痕迹
• 当前项目必须改成服务端代理，不能在前端暴露密钥

建议：

• 单独做 keyword-insight API 代理
• 前端只接当前项目自己的接口

7.5 ID 销量查询

迁移优先级：中高

建议：

• 走 item_get + item_month_sale 组合查询
• 提供批量输入和导出
• 第一版最多支持 50 个，避免前端超长耗时

7.6 云模板管理

迁移优先级：中

这是旧模块里和当前系统差异最大的部分。

旧实现：

• 依赖旧 /api/cloud-storage/*
• 依赖旧管理员角色接口
• 使用旧 S3/MinIO 元数据方案

新实现建议：

• 直接复用当前项目 lib/storage/service.ts
• 模板元数据放数据库表或 SystemSettings
• 权限通过 NextAuth 判断管理员

不建议继续保留旧接口模型。

8. 推荐实施顺序

阶段一：先做“可用版”

目标：先把核心业务搬进当前项目并可实际使用。

范围：

1. 新建 商品策划工具 页面
2. 完成关键词拆词
3. 完成评价/问大家分析
4. 完成淘宝商品基础代理接口
5. 完成 AI 分析接口
6. 完成基础导出

这一步做完后，用户已经可以进入新页面并完成主流程。

阶段二：补齐分析工作台

范围：

1. 竞品分析
2. 关键词洞察
3. ID 销量查询
4. 京东代理接口
5. 导出表格优化

阶段三：补齐管理能力与体验

范围：

1. 模板库上传/下载/删除
2. 管理员权限控制
3. 历史记录/最近使用
4. 页面细节打磨
5. E2E 回归测试

9. 依赖与环境变量建议

建议新增或确认以下环境变量：

• TAOBAO_API_KEY
• TAOBAO_API_SECRET
• TAOBAO_SALE_API_TOKEN
• PRODUCT_PLANNING_QA_TOKEN
• JD_API_KEY 与 JD_API_SECRET（如果后续与淘宝分离）

建议新增依赖：

• xlsx
• exceljs

原因：

• 当前项目虽然已有 papaparse，但对旧模块的 Excel 上传和复杂导出不够

10. 风险与阻塞项

高风险

1. 外部商品数据接口稳定性
2. 旧页面某些隐藏联动逻辑散落在多个 JS/内联脚本中
3. 云模板功能和旧鉴权体系耦合较深

中风险

1. 旧拆词算法体量大，迁移后需要回归验证
2. 竞品分析涉及淘宝与京东双通道，字段差异大
3. AI 分析结果格式需要重新统一

低风险

1. 页面入口新增
2. 新建内部 API 命名空间
3. 使用现有 UI 组件重构工作台

11. 我的推荐方案

如果以“稳、快、能上线”为目标，推荐这样执行：

方案 A：分阶段迁移，先核心后扩展

这是最推荐的方案。

第一批上线：

• 新页面
• 关键词拆词
• 评价/问大家分析
• 淘宝基础代理
• AI 结果总结

第二批上线：

• 竞品分析
• 关键词洞察
• ID 销量查询

第三批上线：

• 模板库管理
• 管理员运营能力

优点：

• 风险最低
• 最容易快速产出可用版本
• 不会被云模板和旧权限逻辑拖慢

方案 B：整页一次性全量迁移

不推荐。

原因：

• 旧模块分散、脚本多、联动多
• 一次性重做很容易周期失控
• 测试面太大

12. 建议的验收标准

第一阶段验收标准建议定义为：

1. 用户能从当前项目进入“商品策划工具”新页面
2. 可以上传 Excel/TXT 并完成关键词拆词
3. 可以输入商品链接/ID 获取评价和问大家数据
4. 可以对评价/问大家执行 AI 分析
5. 可以导出核心分析结果
6. 全流程使用当前项目的登录态，不依赖旧 token
7. 所有外部 API 密钥都只在服务端使用

13. 最终建议

这个迁移项目值得做，而且可以做好。

推荐执行方式：

• 不做旧页面直拷
• 以当前项目为主，重建一个新的 商品策划工具 工作台页面
• 优先迁移“关键词拆词 + 评价/问大家分析 + 淘宝代理 + AI 分析”
• 将云模板、竞品、销量、关键词洞察拆成后续阶段补齐

这样做，既能尽量保留旧功能价值，也不会把当前项目拉回到旧系统的技术包袱里。