docs: initialize domestic VOC project

README.md

@@ -0,0 +1,224 @@
+# 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`
+