# Saas VOC

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

> 当前状态（2026-07-29）：国内 VOC 前端框架、本地后端、AI 分析闭环、商品知识库和国内竞品采集已经接通。原项目 App Shell、共享组件体系、经营分析、市场与竞品、VOC 监测、退款分析、新品开发、生命周期复盘、行动建议、AI 可视化报告与多轮追问均已迁入；演示环境统一由前端请求本地后端，浏览器不直连数据库或外部数据服务。

## 迁入基线

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

当前启用路由：

- `/feedback-inbox`：统一反馈收件箱，支持来源/评分筛选、真实评价证据审阅、主题置信度判断与行动项创建
- `/voc-insight/ai`：AI VOC 洞察工作台，支持评价范围/情感筛选、证据覆盖审计、结构化洞察生成、引用回跳、风险与追问及行动项创建
- `/domestic/overview`：国内经营概览、核心指标、经营趋势、类目贡献和成交商品
- `/domestic/product`：兼容入口，统一重定向到复用后的 `/voc-insight/detail` 商品 VOC 详情
- `/domestic/categories`：二级/三级类目经营对比
- `/domestic/competitors`：竞品关系、映射覆盖率、搜索和本品跳转
- `/domestic/competitors/:productId`：竞品实图、商品档案、关联本品、评分分布、评论证据、AI 可视化报告和多轮追问
- `/domestic/voc-overview`：VOC 核心指标、情绪健康度、问题与热词总览
- `/domestic/category-voc`：类目 VOC 四象限、下钻维度与诊断摘要
- `/domestic/risk-alerts`：商品风险、场景化投诉与异常激增预警框架
- `/domestic/voc-trend`：VOC 数据就绪状态与经营背景趋势
- `/domestic/emotion`：情绪极性分布框架；无评论时展示真实空态
- `/domestic/store-monitoring`：店铺经营、类目结构和退款表现
- `/voc-insight/products`：德玛仕商品列表、搜索、排序和商品选择
- `/voc-insight/detail?productId=11266507445`：复用原商品详情框架的国内 VOC 详情、评论空状态、经营建议和趋势
- `/voc-insight/voice`：用户声音分类；无评论时展示真实空状态
- `/voc-insight/pain-point`：痛点深度洞察
- `/voc-insight/feature`：功能满足度
- `/voc-insight/scenario`：使用场景
- `/return-analysis/overview|attribution|correlation`：退款概况、归因和特征关联三层框架
- `/product-development/trend|requirement|competitor-benchmark|product-definition|lifecycle`：新品开发五环节
- `/action-suggestion/kanban|experience|iteration|strategy`：行动建议四页
- `/data-status`：导入结果、待接依赖和数据质量问题
- `/system/api`：本地 AI 网关配置状态与真实连通性测试
- `/system/ai-prompts`：复用原系统的 AI 提示词、输出风格和追问配置管理
- `/knowledge-center`：复用原知识库信息结构，统一管理本店商品、重点商品、竞品资料、标签、备注和负责人

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

## 最小闭环

当前可以完成：

1. 加载德玛仕 Excel 的规范化结果。
2. 展示 2,817 个有经营数据的商品。
3. 查看经营概览、商品经营详情、二级/三级类目分析和竞品关系。
4. 按商品 ID、型号或名称搜索并选择商品，进入复用原系统布局的商品 VOC 详情。
5. 在商品 VOC 详情、经营详情、竞品关系和深度洞察页面之间保持商品上下文。
6. 自有商品仍按真实的 0 条评论展示空状态；竞品详情使用当前采集的 206 条评论样本，不伪造情绪、痛点或价格销量趋势。
7. 查看 VOC 趋势总览、类目 VOC 和风险预警的完整页面结构与真实空状态。
8. 查看退款汇总、高退款商品和等待订单级原因的归因/关联空态。
9. 查看趋势、需求、竞品、产品定义和生命周期五个新品开发环节。
10. 查看基于真实经营规则的行动建议，并与等待评论证据的体验建议分开。
11. 查看导入统计和数据质量问题。
12. 基于已入库竞品评论生成原版视觉报告，并在同一证据上下文中继续追问。
13. 在系统设置中检查 AI 网关状态、执行真实连通性测试并管理提示词配置。
14. 在商品知识库中查询 2,817 个本店商品和 96 个竞品，将真实商品加入重点库并维护标签、备注和负责人。
15. 在反馈收件箱按来源、评分和关键词筛选评价，审阅原声及证据口径，并将确认后的反馈创建为行动中心任务。
16. 在 AI VOC 洞察工作台筛选真实评价，生成带 evidence ID 引用的用户需求、机会状态、建议动作和验证指标，并将人工确认后的洞察转入行动中心。

德玛仕数据摘要：

- 日指标记录：9,717 条
- 经营商品：2,817 个
- 竞品关系：138 条，其中表格关系 40 条、品牌品类发现 98 条
- 唯一竞品商品：96 个，其中 70 个具有公司中转返回的市场快照
- 评论正文：206 条，覆盖 22 个竞品商品；自有商品评论 0 条
- 采集维度：27 个品牌/品类组合，商品搜索 27/27 成功
- 指标日期：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`。

当前演示数据链为 `德玛仕 Excel + 公司电商数据中转 -> saas-voc-server 本地快照 -> 前端 /api/*`。本地后端提供 2,817 个自有商品、96 个竞品商品、9,717 条日指标、138 条竞品关系和 206 条竞品评论；市场商品按“品牌 + 品类”检索，并经过品牌相关性过滤。自有商品评论仍为真实的 0 条，对应 VOC 页面继续展示可解释空状态。独立 Parse REST 保留为可切换的持久化实现，切换时只需调整后端配置。

## 复用策略

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

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

## 环境隔离

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

- 国内 VOC 后端：`/api/domestic-voc`
- SaaS 工作区：`/api/saas`
- 商品知识库：`/api/knowledge`
- AI 分析网关：`/api/ai`
- 德玛仕本地数据：`/assets/data/demashi-summary.json`

公司电商数据中转、Parse REST 和 AI 上游凭据均由 `saas-voc-server` 持有，前端不直接请求这些服务。

运行时配置定义在 `src/runtime-config.js` 和 `src/app/core/config/runtime-config.ts`。开发环境默认使用 `api` 模式并通过 `/api/domestic-voc` 读取后端快照；部署环境可以在 Angular 脚本加载前覆盖 `window.__SAAS_VOC_CONFIG__`。

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

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

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

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

参考中转模块：

```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 run start:local
```

启动前端前，在 `E:\workspace\server\saas-voc-server` 运行无数据库本地后端：

```powershell
npm run start:local
```

前端地址为 `http://127.0.0.1:4200/`。`/api/domestic-voc` 通过 `proxy.conf.json` 转发到 `http://127.0.0.1:4400`。本地后端读取同一份德玛仕规范化快照，不访问 PostgreSQL、Parse 或外部采集接口。

需要启用 AI 分析时，在后端进程环境中配置 `FMODE_AI_BASE_URL`、`FMODE_AI_TOKEN`、`FMODE_AI_MODEL` 和 `FMODE_AI_TIMEOUT_MS`。前端无需也不得配置 token；`/api/ai/status`、`/api/ai/test`、`/api/ai/chat/completions` 和 `/api/ai/prompts` 均由本地后端提供。

竞品补采通过后端命令执行，API Key 只配置在后端进程中：

```bash
cd E:\workspace\server\saas-voc-server
npm run enrich:competitors:local
```

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

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

## 当前验证

- `npm run build`：通过
- `npm test`：26 项 Jasmine 测试通过
- `npm run verify:data`：通过
- 桌面端：31 个业务入口及竞品详情页的页面身份、主内容、导航、空状态和交互通过
- 移动端：30 个启用入口无页面级横向溢出，导航抽屉展开/收起、标题和控件布局通过
- 浏览器控制台：竞品 AI 报告、继续追问、API 管理和提示词管理闭环无 Angular 运行时错误、警告或失败请求
- AI 闭环：竞品真实评论 -> `/api/ai/chat/completions` -> 原版视觉报告 -> 继续追问通过；API 状态与测试页通过
- 独立 Parse REST 开发库：16/16 `Voc*` Schema、2,817 个本品、37 个竞品、9,717 条指标、40 条关系、355 条评论和 8 条重点商品知识校验通过
- 商品知识库闭环：真实商品读取、三库切换、筛选、列管理、重点标记、标签/备注/负责人编辑、审计记录和商品详情下钻通过；桌面与 390x844 移动端无页面级溢出
- 运行时请求：当前激活闭环请求同源 `/api/*`，本地后端返回 2,817 个自有商品、96 个竞品、9,717 条日指标、138 条竞品关系和 206 条竞品评论；31 个业务入口无失败接口请求
- `npm audit --omit=dev`：13 项原框架依赖公告（0 critical、10 high、3 moderate），正式公网部署前必须升级 Angular、ECharts 并替换无修复版本的 `xlsx`

## 尚未完成

- 创建独立 PostgreSQL 生产数据库；独立 Parse REST 开发应用已完成
- 开始定时积累价格与销量历史；当前已接入单次市场快照，但尚未形成可计算趋势的多期序列
- 部署独立生产环境并完成端到端验收；开发环境已切换至独立 Parse REST
- 升级原框架的 Angular 17、ECharts、Parse 依赖基线，并替换无修复版本的 `xlsx`

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

原框架页面的启用、等价承接和排除边界见 [FRAMEWORK-MIGRATION.md](FRAMEWORK-MIGRATION.md)。

## 明确不包含

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