# Saas VOC

基于现有 `msq-voc-web` 前端框架打包出的国内电商 VOC 通用模板，首个案例为德玛仕京东商品。项目保留原系统的 Angular App Shell、顶部搜索、侧边导航、共享组件、VOC 页面结构和 ECharts 能力，只替换最小闭环所需的数据入口与国内商品语义。

> 当前状态（2026-07-23）：原项目 App Shell、共享组件体系、经营分析、市场与竞品、VOC 全局监测和 VOC 深度洞察框架已完成迁入；已启用页面均使用国内商品语义和统一状态组件。

## 迁入基线

- 来源仓库：`E:\workspace\msq-voc-web`
- 固定来源提交：`9326c20`
- 迁入方式：从固定 Git 提交提取，不复制来源仓库未提交的本地修改
- 目标仓库：`https://git.fmode.cn/18307996893/Saas-voc.git`
- 目标仓库不会连接或写入原跨境系统线上数据库

当前启用路由：

- `/domestic/overview`：国内经营概览、核心指标、经营趋势、类目贡献和成交商品
- `/domestic/product`：单商品经营详情、流量转化、退款表现和商品档案
- `/domestic/categories`：二级/三级类目经营对比
- `/domestic/competitors`：竞品关系、映射覆盖率、搜索和本品跳转
- `/domestic/voc-overview`：VOC 核心指标、情绪健康度、问题与热词总览
- `/domestic/category-voc`：类目 VOC 四象限、下钻维度与诊断摘要
- `/domestic/risk-alerts`：商品风险、场景化投诉与异常激增预警框架
- `/voc-insight/products`：德玛仕商品列表、搜索、排序和商品选择
- `/voc-insight/voice`：用户声音分类；无评论时展示真实空状态
- `/voc-insight/pain-point`：痛点深度洞察
- `/voc-insight/feature`：功能满足度
- `/voc-insight/scenario`：使用场景
- `/data-status`：导入结果、待接依赖和数据质量问题

`/login` 保留为独立 Parse 应用接入后的入口，但当前路由未启用 `AuthGuard`。

## 最小闭环

当前可以完成：

1. 加载德玛仕 Excel 的规范化结果。
2. 展示 2,817 个有经营数据的商品。
3. 查看经营概览、商品经营详情、二级/三级类目分析和竞品关系。
4. 按商品 ID、型号或名称搜索并选择商品，先进入经营详情，再进入 VOC 洞察。
5. 在原 VOC 页面中保持商品上下文。
6. 对当前真实的 0 条评论展示空状态，不伪造情绪、痛点或分析结果。
7. 查看 VOC 趋势总览、类目 VOC 和风险预警的完整页面结构与真实空状态。
8. 查看导入统计和数据质量问题。

德玛仕数据摘要：

- 日指标记录：9,717 条
- 经营商品：2,817 个
- 竞品关系：40 条
- 唯一竞品商品：37 个
- 评论正文：0 条
- 指标日期：2026-07-14 至 2026-07-20

源文件：

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

规范化结果位于 `src/assets/data/demashi-summary.json`。

## 复用策略

国内商品的标准身份是 `platform + productId`，唯一键为 `platform:productId`。原框架大量组件使用 `asin` 表示商品唯一字符串，为控制首版改动量，适配层暂时提供 `asin = productId`：

- 页面统一显示“商品ID”，不显示 ASIN。
- 国内平台商品 ID 始终按字符串保存。
- 新增领域模型使用 `platform`、`productId` 和 `productKey`。
- `asin` 只作为复用原组件的兼容字段，后续再逐步移除。

## 环境隔离

浏览器默认只访问同源地址：

- Parse：`/parse`
- 国内电商中转：`/api/voc-e-commerce`
- 德玛仕本地数据：`/assets/data/demashi-summary.json`

运行时配置定义在 `src/app/core/config/runtime-config.ts`，部署环境可以在 Angular 脚本加载前注入 `window.__SAAS_VOC_CONFIG__` 覆盖同源路径。

禁止将以下内容写入浏览器代码或 Git：

- Fmode API Key
- JustOneAPI token
- Parse master key
- PostgreSQL 连接串

Fmode Key 只能由服务端或 Worker 持有。前端通过同源服务端调用：

```text
/api/voc-e-commerce/{platform}/{upstream-path}
```

参考中转模块：

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

## 本地运行

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

```bash
npm ci
npm run verify:data
npm run build
npm test
npm start
```

默认开发地址为 `http://localhost:4200/`。本地 `/api/voc-e-commerce` 通过 `proxy.conf.json` 转发到 `http://127.0.0.1:3000`，API Key 仍应只配置在该服务端进程中。

从 Excel 重新生成规范化数据：

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

## 当前验证

- `npm run build`：通过
- `npm test`：5 项 Jasmine 测试通过
- `npm run verify:data`：通过
- 桌面端：13 个启用入口的页面身份、主内容、导航、空状态和交互通过
- 移动端：13 个启用入口无页面级横向溢出，导航抽屉展开/收起、标题和控件布局通过
- 浏览器控制台：启用入口无 Angular 运行时错误、警告或失败请求
- 运行时请求：当前激活闭环只请求同源德玛仕 JSON，没有访问旧 Parse 或旧跨境域名
- `npm audit --omit=dev`：17 项原框架依赖公告（1 critical、11 high、5 moderate），正式公网部署前必须升级处理

## 尚未完成

- 创建独立 PostgreSQL 数据库和独立 Parse 应用
- 验证 JustOneAPI 京东商品详情、评论接口和真实字段契约
- 将商品、日指标、竞品关系和评论幂等写入新 Parse 应用
- 将前端主数据源从静态 JSON 切换为新 Parse 应用
- 部署独立环境并完成端到端验收
- 升级原框架的 Angular 17、`xlsx`、ECharts、Parse 依赖基线并处理安全公告

完整任务顺序见 [TASKS.md](TASKS.md)。

## 明确不包含

- 原 Amazon、Sorftime、SP-API 和跨境订单链路
- 直接复用原跨境线上数据库
- 浏览器直接持有 Fmode 或 JustOneAPI 密钥
- 在没有评论正文时生成虚假 VOC 分析
- 首版多租户计费、复杂权限、定时全量采集和 AI 自动报告