بدون توضیح

gangvy eb5628d479 docs: initialize domestic VOC project		2 ماه پیش
README.md	eb5628d479 docs: initialize domestic VOC project	2 ماه پیش

Saas VOC

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

当前阶段：方案确认与仓库初始化，尚未开始复制或修改业务代码。

更新时间：2026-07-22

项目目标

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

导入德玛仕商品经营数据和竞品映射。
通过 Fmode voc-e-commerce 中转接口获取国内电商商品和评论数据。
将商品、评论和竞品关系写入全新的独立数据库。
复用现有 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 分析结果。

首版页面

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

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

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

当前进度

新 Git 仓库初始化
现有跨境前端、后端和数据库模型盘点
德玛仕 Excel 结构和数据量核对
voc-e-commerce 路由、鉴权、计费、缓存和重试逻辑核对
本机 Fmode API Key 存在性和格式核对，未输出密钥
确定新数据库隔离方案
确定 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、评分、正文和评论时间。

截止日前任务顺序

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

暂不包含

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

README.md