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

## 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 分析”
- 将云模板、竞品、销量、关键词洞察拆成后续阶段补齐

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