# super-agent

**Repository Path**: wpkaizxr/super-agent

## Basic Information

- **Project Name**: super-agent
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-17
- **Last Updated**: 2026-08-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# super-agent · 基于对话的极简购物推荐系统（一期可运行脚手架）

> 对应实施蓝图④（PRD v2.3）与实施蓝图⑦（开发规格书）。本仓库为**可运行全栈脚手架**：
> 微信小程序 + Spring Boot 3 模块化单体 + Vue3 管理端 + Docker 部署。外部依赖全部可 mock，密钥到账后替换实现。

## 目录结构

```
super-agent/
├── server/                    # Spring Boot 3 多模块（JDK17 编译，本机 21 亦可）
│   ├── server-common/         # Result/错误码/JWT/AES-256-GCM/KV 抽象/拦截器
│   ├── server-system/         # 登录(微信 mock)/画像/埋点/账号/注销/管理端账号
│   ├── server-sku/            # SKU 池/导入五硬门槛/选品工作台/联盟归因(mock)
│   ├── server-recommend/      # 意图识别/规则层/LLM 排序(mock+降级)/反馈/跳转/问卷
│   ├── server-chat/           # 对话流/内容安全(mock)/偏好抽取(异步)
│   ├── server-admin/          # 管理端 API（M1-M7）+ 操作日志切面 + 权限
│   └── server-app/            # 启动入口 + Flyway(DDL) + 配置
├── miniprogram/               # 微信小程序（原生）：survey / index / me + sku-card
├── admin-web/                 # Vue3 + Element Plus + Vite + ECharts（M1-M7）
├── deploy/                    # docker-compose / Dockerfile / nginx / 备份脚本
└── docs/                      # 蓝图快照与说明
```

## 快速开始

### 1. 后端（零依赖即可跑：H2 内存库 + 内存 KV）

```bash
cd server
mvn -DskipTests package
java -jar server-app/target/super-agent-app.jar          # 默认 dev profile（H2）
```

- 默认端口 `8080`，Flyway 自动建表并灌入 14 条演示 SKU。
- 管理端默认超管：`admin / Admin@123`（首次登录后请修改）。

### 2. 后端连真实 MySQL/Redis（Docker）

```bash
docker compose -f deploy/docker-compose.dev.yml up -d    # 起 MySQL8 + Redis7
SPRING_PROFILES_ACTIVE=docker java -jar server-app/target/super-agent-app.jar
```

### 3. 管理端

```bash
cd admin-web
npm install
npm run dev        # http://localhost:5173 （已配置 /api /admin 代理到 8080）
```

### 4. 小程序

用「微信开发者工具」导入 `miniprogram/` 目录。
- 开发期勾选「不校验合法域名」；`miniprogram/config.js` 中 BASE_URL 指向 `http://localhost:8080`。
- AppID 用测试号（`touristappid`）或替换为真实 AppID。

## 冒烟流程

1. `POST /api/v1/auth/wx-login {"code":"any"}` → 拿 token（mock 登录，同 code 同用户）
2. `POST /api/v1/survey/answers` 填 q1-q4 → 生成画像 + 首推
3. `POST /api/v1/chat/messages` 发"想囤点纸巾，50元以内的" → 三段式回复 + 候选
4. `POST /api/v1/rec/{itemId}/feedback {"type":"dislike|owned|price"}` → 反馈生效
5. `POST /api/v1/rec/{itemId}/jump` → mock 联盟链接 + jump_out 埋点
6. `POST /admin/login admin/Admin@123` → 管理端 API（G1 仪表盘 / SKU / 用户 / 监控 / 系统）

## 环境变量（生产必须注入，开发有占位）

| 变量 | 用途 | 默认（仅开发） |
|:---|:---|:---|
| `JWT_SECRET` | JWT 签名（≥32字节） | 开发占位 |
| `AES_KEY` | 画像值 AES-256-GCM（Base64 32字节） | 开发占位 |
| `DB_HOST/DB_USER/DB_PASS` | MySQL | localhost/root/superagent |
| `REDIS_HOST/REDIS_PASS` | Redis | localhost/- |
| `WX_APP_ID/WX_APP_SECRET` | 微信登录 | mock |
| `TAOBAO_APP_KEY/TAOBAO_APP_SECRET` | 淘宝联盟 | mock |
| `JD_APP_KEY/JD_APP_SECRET` | 京东联盟 | mock |
| `LLM_API_KEY` | 智谱 | mock |
| `GREEN_AK/GREEN_SK` | 阿里云内容安全 | mock |
| `OSS_AK/OSS_SK` | OSS 备份 | mock |

## Mock 开关（`app.*`，见 application.yml）

| 配置 | 默认 | 说明 |
|:---|:---|:---|
| `app.mock.wx=true` | 是 | mock 微信登录；`false` 需实现 `RealWxCode2Session` |
| `app.mock.green=true` | 是 | mock 内容安全（命中高危词拦截可测 T12） |
| `app.mock.taobao=true` | 是 | mock 淘宝联盟；`false` 需实现 `RealTaobaoGateway` |
| `app.mock.jd=true` | 是 | mock 京东联盟；`false` 需实现 `RealJdGateway` |
| `app.llm.provider=mock` | 是 | mock 排序/抽取；`zhipu` 需接入智谱 API |
| `app.cache.type=memory` | 是 | 内存 KV；docker 环境切 `redis` |
| `app.db-type=H2` | 是 | dev 用 H2；docker 环境 `MYSQL` |

> 降级链路：LLM 3s 超时 / 返回越界商品 / 全局开关（M7）→ 自动 `rule_only=true` 模板理由，前端无感。

## 双联盟品类分治（v2.4）

- **品类-平台绑定**：纸品→淘宝联盟、手机配件→京东联盟，其余品类默认淘宝；排序**不含平台字段**（平台由品类决定）。
- 每平台 SKU 池 + 各自联盟转链/拉单/归因（`affiliate_orders.platform` 回填）。
- 候选卡跳转按钮按 `sku.platform` 显示「去淘宝/去京东」。
- G1 推荐购买转化率**按平台分层 + 合并双口径**出数（`GET /admin/dashboard/g1` 返回 `cvrByPlatform`）。
- 平台绑定规则见 `server-sku/.../platform/PlatformBinding.java`，网关路由见 `gateway/AffiliateGatewayRouter.java`。

## 模块依赖与边界

```
server-common ← server-system ← server-sku ← server-recommend ← server-chat
                 ↑              ↑              ↑
                 └──────────────┴──────────────┴── server-admin（M1-M7）
server-app 聚合全部，是唯一启动/打包入口
```

## 说明与已知取舍

- Flyway DDL 双份：`db/migration/mysql`（源真本，对齐蓝图⑦ §1）与 `db/migration/h2`（开发用翻译版）。
- 归因/备份/SLS 等真实外部链路用 mock/占位；生产需实现对应 `Real*` Adapter（见 `docs/第三方接入指南.md`，密钥到账后替换）。
- **定时任务用 XXL-Job**（xxl-job-core 2.4.0 已接入）：JobHandler 见 `server-app/.../job/XxlJobHandlers.java`
  （affiliateOrderPull / skuInvalidSync / deleteRequestScan / g1DailyCompute），CRON 在 xxl-job-admin 调度中心配置。
- **LLM 用量已落库**（`llm_usage_logs` 表），M7 看板与后续成本/用量分析均查库。
- **信任分（P1 资产）**：`TrustScoreService` 维护 trust_score(0-100)，survey+5 / jump+1 / owned+2 / price+1 / dislike-3 / 归因成交+10 / 登录惰性衰减；每次变化记 `trust_snapshot`（含收敛），`feedback=dislike` 记 `recovery_seq(err_detected)`；推荐按信任分收敛候选数（≥85→1 / ≥75→2 / ≥60→3 / 其余→4）。
- 压测脚本 `scripts/loadtest.mjs`：本机 dev(H2) 500 并发 P95≈2.3s 通过；详见 `docs/压测说明.md`。
- 微信小程序需在微信公众平台配置合法域名后正式联调（蓝图⑥ A3 时间线）。