Saas-voc

Saas VOC

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

当前阶段：独立前端 MVP 已可运行，使用德玛仕 Excel 规范化结果完成商品、竞品、经营概览、VOC 空状态和数据质量闭环；独立数据库与 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。

总体架构

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 }。

服务端调用示意：

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. 经营概览：7 日经营指标、成交趋势、类目贡献和成交商品。
2. 商品与竞品：类目筛选、SKU 搜索、分页、经营指标和竞品映射。
3. VOC 分析：评论样本量、评分/情绪空状态，以及自有商品与竞品采集状态。
4. 数据状态：规范化结果、数据链路、外部依赖和质量问题。

首版不伪造评论、评分、情绪或问题标签。评论接入后，情绪可先按评分计算：4 至 5 星为正向，3 星为中性，1 至 2 星为负向。

本地运行

建议使用 Node.js 20 LTS。当前 Angular 17 工作区声明支持 >=18.13 <23。

npm ci
npm run verify:data
npm run build
npm test
npm run dev

开发地址默认为 http://localhost:4200/。如果端口已占用，可在 apps/web 工作区传入其他端口。

规范化数据位于 apps/web/src/assets/data/demashi-summary.json。需要从原始 Excel 重新生成时执行：

npm run import:demashi -- "E:\xwechat_files\wxid_ay08t6ugo2h922_df4f\msg\file\2026-07\德玛仕产品及竟品收集0721.xlsx"

当前进度

• 新 Git 仓库初始化
• 现有跨境前端、后端和数据库模型盘点
• 德玛仕 Excel 结构和数据量核对
• voc-e-commerce 路由、鉴权、计费、缓存和重试逻辑核对
• 本机 Fmode API Key 存在性和格式核对，未输出密钥
• 确定新数据库隔离方案
• 确定 productId 标准字段和 asin 临时兼容方案
• 建立 Angular 17 独立前端与共享领域模型
• 实现德玛仕 Excel 可重复规范化和结果校验
• 接通经营概览、商品与竞品、VOC 空状态、数据状态页面
• 完成生产构建、3 项单测、桌面与移动端浏览器验收
• 创建新 PostgreSQL 数据库和 Parse 应用
• 验证 JustOneAPI 京东商品详情与评论接口路径和返回字段
• 将规范化商品、指标、关系和评论持久化到新 Parse 应用
• 完成独立环境部署验收

已知问题

生产 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、评分、正文和评论时间。

前端依赖基线

当前保持 Angular 17，以便与现有跨境前端兼容并控制首版改动量。npm audit --omit=dev 仍报告 8 项 Angular 17 高危公告，官方修复需要跨大版本升级；正式公网发布前应升级到受支持的 Angular 版本并完成回归。开发和 CI 使用 Node.js 20 LTS，不使用当前 Angular 17 未声明支持的 Node.js 24。

截止日前任务顺序

1. 创建新数据库和 Parse 应用，验证完全隔离。
2. 修复或确认 Fmode 生产域名 TLS 入口。
3. 用一个德玛仕京东 SKU 验证搜索、详情、评论三个上游接口。
4. 接通评论采集或评论文件导入。
5. 将现有规范化结果幂等写入新 Parse 应用。
6. 把前端数据源从本地 JSON 切换到新 Parse 应用。
7. 完成独立环境部署和端到端验收。

暂不包含

• 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