# Saas VOC

国内电商 VOC（Voice of Customer）通用模板。项目以德玛仕为首个案例，在不影响现有跨境电商系统和线上数据库的前提下，复用现有 Angular VOC 页面、Parse 数据访问模式，以及 Fmode 封装的 JustOneAPI 电商数据中转能力。

> 当前阶段：方案确认与仓库初始化，尚未开始复制或修改业务代码。
>
> 更新时间：2026-07-22

## 项目目标

在 2026-07-25 前优先接通一个最小、可部署、可复用的国内电商 VOC 闭环：

1. 导入德玛仕商品经营数据和竞品映射。
2. 通过 Fmode `voc-e-commerce` 中转接口获取国内电商商品和评论数据。
3. 将商品、评论和竞品关系写入全新的独立数据库。
4. 复用现有 VOC 页面，展示商品列表、情绪分布、负面问题和竞品对比。

## 隔离原则

- 不连接、不写入现有跨境电商线上库。
- 新建独立 PostgreSQL 数据库和独立 Parse 应用配置。
- 现有 `msq-voc-web`、`moshengqi-server` 仅作为代码和数据模型参考。
- JustOneAPI 上游密钥只保留在 Fmode 服务端，本项目只使用 Fmode API Key。
- Fmode API Key、Parse master key、数据库连接串不得进入浏览器代码或 Git。

## 总体架构

```text
Saas VOC Web
  |-- 读取新 Parse 应用中的商品、评论和分析结果
  |-- 调用本项目服务端任务，不直接持有任何私钥
  |
Saas VOC Server / Worker
  |-- 使用 FMODE_API_KEY
  |-- 调用 /api/voc-e-commerce/{platform}/{upstream-path}
  |-- 清洗并写入新 Parse 数据库
  |
Fmode voc-e-commerce
  |-- 鉴权、计费、缓存、重试
  |-- 隐藏 JustOneAPI token
  |
JustOneAPI
```

## 最小复用策略

现有前端大量代码把 `asin` 当作“商品唯一字符串”，而不是执行 ASIN 格式校验。为了在截止日前降低改动量，首版不做全项目全局重命名。

采用兼容层方案：

- 新模型的标准字段使用 `platform` 和 `productId`。
- 唯一商品键使用 `platform:productId`，不能只使用商品 ID。
- 国内平台商品 ID 一律按字符串保存，避免长数字精度丢失。
- 复用旧组件时，由适配器临时提供 `asin = productId` 兼容字段。
- 新增代码只使用 `productId`，后续再逐步移除 `asin` 兼容字段。

这样可以复用商品选择器、VOC 图表、评论情绪统计和部分 Parse 查询封装，同时避免让新数据库继续以 Amazon 为核心语义。

## 新数据库

计划使用独立 Parse 应用和独立 PostgreSQL 数据库。实际连接信息只通过部署环境配置，不写入本仓库。

首版最小数据类：

### Product

- `platform`: `jd`、`taobao`、`tmall`、`pdd`、`douyin`、`1688` 等
- `productId`: 平台商品 ID
- `productKey`: `${platform}:${productId}`
- `asin`: 临时兼容字段，值与 `productId` 相同
- `role`: `own` 或 `competitor`
- `brand`、`title`、`model`
- `category1`、`category2`、`category3`
- `source`: `excel` 或 `justone`
- `rawData`: 必要时保留原始响应

### ProductMetricDaily

- `productKey`、`date`
- 成交金额、成交件数、订单数、客户数
- 曝光、点击、访客、浏览、加购
- 转化率、退款金额、退款件数
- 唯一键：`productKey:date`

### ProductRelation

- `ownProductKey`
- `competitorProductKey`
- `competitorBrand`
- `category`
- 唯一键：`ownProductKey:competitorProductKey`

### ProductReview

- `platform`、`productId`、`productKey`
- `reviewId`、`rating`、`title`、`content`
- `reviewDate`、`helpful`、`verified`
- `role`: `own` 或 `competitor`
- `source`: `justone` 或 `file`
- 唯一键优先使用 `platform:productId:reviewId`，无 reviewId 时使用内容哈希

### ImportBatch

- `fileName`、`fileHash`、`type`
- `status`、`total`、`success`、`failed`
- `errorSummary`、`startedAt`、`finishedAt`

## Fmode 电商中转

后端参考模块：

`E:\workspace\server\future-server\fmode-server\modules\voc-e-commerce`

已确认能力：

- 路由已挂载到 `/api/voc-e-commerce`。
- 支持 `GET /health`、`GET /test` 和任意上游路径透传。
- 平台由路径第一段识别，例如 `jd/...`、`taobao/...`、`1688/...`。
- 支持 GET、POST、PUT、PATCH 参数转发。
- 上游 POST 类接口使用 `application/x-www-form-urlencoded`。
- 支持超时、重试、响应缓存和失败结果不计费。
- Fmode `sk-` Key 可通过 `Authorization: Bearer ...` 或 `x-api-key` 传入。
- 缓存命中和上游成功请求都会按当前规则计费。
- 返回外层统一为 `{ code: 200, data: upstreamResponse }`。

服务端调用示意：

```bash
curl "${FMODE_SERVER_URL}/api/voc-e-commerce/jd/search-item-list/v1?keyword=demo&page=1" \
  -H "x-api-key: ${FMODE_API_KEY}"
```

注意：`FMODE_API_KEY` 只能存在于服务端或本地开发环境，不能放入 Angular 环境文件或静态资源。

## 德玛仕案例数据

当前输入文件：

`E:\xwechat_files\wxid_ay08t6ugo2h922_df4f\msg\file\2026-07\德玛仕产品及竟品收集0721.xlsx`

已完成只读分析：

- `德玛仕产品基础数据`：9,717 条日数据，时间范围 2026-07-14 至 2026-07-20。
- 2,817 个有经营数据的唯一 SKU。
- 2 个一级类目、10 个二级类目、49 个三级类目。
- 37 个经营指标字段，包含成交、流量、加购、下单和退款。
- `竟对品牌及编码`：28 个自有 SKU 映射、37 个唯一竞品 SKU、10 个类目。
- 自有 SKU `100204398739` 在经营数据中没有对应记录，需要作为缺失数据标记。
- 两个自有 SKU 尚未填写竞品，不能进入竞品对比。
- 文件没有评论正文，不能单独形成真实 VOC 分析结果。

## 首版页面

只保留最容易接通的页面：

1. 登录页：复用现有 Parse 登录模式。
2. 商品与竞品：类目筛选、SKU 搜索、经营指标和竞品映射。
3. VOC 分析：评分情绪、问题标签、负面评论原声、样本量提示。
4. 商品对比：同类自有商品和竞品的评分、评论量、负面问题对比。
5. 数据状态：导入批次、采集状态、失败原因和最近更新时间。

首版不接入大模型。情绪先按评分计算：4 至 5 星为正向，3 星为中性，1 至 2 星为负向；问题标签使用可配置的商用电器中文词典。

## 当前进度

- [x] 新 Git 仓库初始化
- [x] 现有跨境前端、后端和数据库模型盘点
- [x] 德玛仕 Excel 结构和数据量核对
- [x] `voc-e-commerce` 路由、鉴权、计费、缓存和重试逻辑核对
- [x] 本机 Fmode API Key 存在性和格式核对，未输出密钥
- [x] 确定新数据库隔离方案
- [x] 确定 `productId` 标准字段和 `asin` 临时兼容方案
- [ ] 创建新 PostgreSQL 数据库和 Parse 应用
- [ ] 验证 JustOneAPI 京东商品详情与评论接口路径和返回字段
- [ ] 建立最小前端和服务端目录
- [ ] 实现德玛仕 Excel 幂等导入
- [ ] 接通商品、评论、竞品关系和 VOC 页面
- [ ] 完成构建、部署和验收

## 已知问题

### 生产 API 联调受阻

2026-07-22 使用本机 Fmode API Key 联调时，`server.fmode.cn:443` TCP 可达，但 TLS 握手被连接端重置。业务搜索请求没有成功发出，也没有消耗 API 额度。

在该问题修复前，只能确认模块代码、路由挂载和自动测试覆盖，不能把 JustOneAPI 的实际字段契约标记为已验证。

### 上游凭证需要环境化

参考模块当前存在上游 token 默认值。正式复用前必须删除源码默认凭证，只允许使用 `VOC_E_COMMERCE_TOKEN` 或 `JUSTONE_TOKEN` 环境变量，并轮换已经进入源码历史的旧 token。

### 评论数据尚缺

德玛仕 Excel 只有商品经营数据和竞品编码。真实 VOC 演示还需要：

- 修复 Fmode 生产接口后从 JustOneAPI 采集评论；或
- 提供一份评论 CSV/XLSX，至少包含平台、商品 ID、评分、正文和评论时间。

## 截止日前任务顺序

1. 创建新数据库和 Parse 应用，验证完全隔离。
2. 修复或确认 Fmode 生产域名 TLS 入口。
3. 用一个德玛仕京东 SKU 验证搜索、详情、评论三个上游接口。
4. 建立领域适配器，在 DTO 层提供 `asin` 兼容字段。
5. 导入商品经营数据和竞品关系。
6. 接通评论采集或评论文件导入。
7. 复制并精简商品列表、VOC 分析和竞品对比页面。
8. 完成幂等导入、空数据、错误状态和构建验收。

## 暂不包含

- Amazon、Sorftime、SP-API 和跨境订单链路
- 京东、淘宝、天猫等平台的定时全量采集
- 多租户计费和复杂权限后台
- AI 自动报告、行动建议、研发闭环
- 社媒、退货、订单、库存和广告分析
- 实时预警、消息推送和复杂导出

## 参考代码

- 跨境 VOC 前端：`E:\workspace\msq-voc-web`
- 跨境系统后端：`E:\workspace\server\moshengqi-server`
- 国内电商数据中转：`E:\workspace\server\future-server\fmode-server\modules\voc-e-commerce`