437 lines
22 KiB
Markdown
437 lines
22 KiB
Markdown
# AI 数字销售助手 — AI 开发者快速指南
|
||
|
||
> **本文档面向 AI 编程助手**，帮助你在最短时间内理解项目全貌并继续开发。
|
||
|
||
---
|
||
|
||
## 项目目标（务必理解）
|
||
|
||
**构建一个能完全模仿真人销售在微信上与客户对话的 AI 系统。**
|
||
|
||
核心差异：
|
||
1. **数字销售分身**：上传销售真实聊天记录，AI 提取其个人风格（方言/句式/语气/性格），构建"数字分身"
|
||
2. **四维画像驱动**：基于 **销售风格 / 项目资料 / 聊天技巧 / 客户画像** 综合理解场景后生成回复
|
||
3. **自主运营**：自动回复（按客户等级分策略）、主动触达（生日/活动）、画像自迭代、等级动态评估
|
||
4. **最终愿景**：销售只处理 AI 搞不定的关键对话，日常维护/跟进/促单全部由 AI 代劳
|
||
|
||
**你写的每一行代码都应服务于：让 AI 更像那个销售、更懂那个客户、更专业地推进销售进程。**
|
||
|
||
---
|
||
|
||
## 技术栈
|
||
|
||
```
|
||
Go 1.26 + Fiber v2 + GORM(MySQL) + MongoDB + Redis + Wire DI + 原生前端(零构建)
|
||
```
|
||
|
||
调用链：
|
||
```
|
||
HTTP → Fiber中间件(JWT) → Router → Service → Biz → Impl/Mongo → LLM
|
||
↓
|
||
registerCommon 统一包装 {code:0, message, data}
|
||
```
|
||
|
||
---
|
||
|
||
## 目录结构（★ 标注当前活跃开发区域）
|
||
|
||
```
|
||
ai_scheduler/
|
||
├── cmd/server/
|
||
│ ├── main.go # 启动入口
|
||
│ ├── wire.go # Wire DI 声明（//go:build wireinject）
|
||
│ └── wire_gen.go # Wire 自动生成（禁止手动编辑）
|
||
├── config/config.yaml # MySQL/Mongo/Redis/JWT/微信协议地址
|
||
├── internal/
|
||
│ ├── biz/ # ★ 业务逻辑层
|
||
│ │ ├── advice_wx.go # 微信回调处理 + 消息流水 + 会话聚合 + ★ 托管自动注册
|
||
│ │ ├── advice_wx_send.go # 微信消息发送（含模拟真人打字延迟）
|
||
│ │ ├── advice_strategy.go # 智能策略（四级回复/主动对话）
|
||
│ │ ├── advice_client.go # 客户管理 + 等级评估
|
||
│ │ ├── advice_customer_new.go # ★ 微信好友 CRUD + 差集同步（ai_advice_customer）
|
||
│ │ ├── advice_label.go # ★ 标签同步（与 DB 比对增删改）
|
||
│ │ ├── advice_chat.go # AI 对话（LLM 调用 + ChatWithSession 复用优化）
|
||
│ │ ├── advice_evaluate.go # 客户等级评估
|
||
│ │ ├── advice_proactive.go # 主动触达
|
||
│ │ ├── advice_iterate.go # 画像自迭代
|
||
│ │ ├── handle/、llm_service/ # ⚠️ 历史死代码，忽略
|
||
│ │ └── provider_set.go
|
||
│ ├── services/advice/ # ★ HTTP Handler 层
|
||
│ │ ├── wxhook.go # 回调 + 会话 Handler
|
||
│ │ ├── wx_proxy.go # 微信 API 代理（分发到 wxDispatchMap）
|
||
│ │ ├── wx_ws_hub.go # WebSocket Hub（实时推送）
|
||
│ │ ├── customer_new.go # ★ 好友 CRUD Handler（Diff 同时返回标签）
|
||
│ │ ├── label.go # ★ 标签 Handler（List/Sync）
|
||
│ │ └── provider_set.go
|
||
│ ├── server/
|
||
│ │ ├── router/router.go # 路由总装 + registerCommon 中间件
|
||
│ │ ├── router/advicer.go # 全部业务路由（~80 个接口）
|
||
│ │ └── http.go # NewHTTPServer 参数列表需同步
|
||
│ ├── entitys/advicer_data.go # ★ 核心 DTO（最频繁修改）
|
||
│ ├── data/
|
||
│ │ ├── model/ # MySQL GORM 模型（*.gen.go 禁止手动编辑）
|
||
│ │ │ ├── ai_advice_customer.gen.go # ★ 微信好友表
|
||
│ │ │ └── ai_advice_label.gen.go # ★ 标签表
|
||
│ │ ├── impl/ # MySQL 数据访问（继承 DataTempBase[T]）
|
||
│ │ │ ├── advice_customer_impl.go
|
||
│ │ │ └── advice_label_impl.go
|
||
│ │ ├── mongo_model/ # MongoDB 集合模型
|
||
│ │ └── constants/ # Prompt 模板、模型映射
|
||
│ ├── middleware/ # JWT 认证
|
||
│ ├── jobs/advice_task.go # 定时任务（cron）
|
||
│ └── pkg/wx/ # 微信协议封装（100+ API 端点）
|
||
├── web/ # ★ 前端（零构建，静态托管）
|
||
│ ├── project.html # ★ 版本号管理（修改 JS 后必须更新 ?v=N）
|
||
│ └── assets/
|
||
│ ├── css/theme.css # 深色科技风设计系统
|
||
│ └── js/
|
||
│ ├── core.js # 核心库（Core.api / Core.wxApi / Toast / Modal）
|
||
│ ├── wx.js # ★ 微信工作台核心（state/通讯录/标签/WS/好友同步）
|
||
│ ├── wx_login.js # ★ 登录模块（二维码/在线检测/登出）
|
||
│ └── wx_chat.js # ★ 聊天模块（会话/消息/联系人详情气泡）
|
||
└── sql/ # 数据库 DDL
|
||
├── 04_ai_advice_customer.sql
|
||
└── 05_ai_advice_label.sql
|
||
```
|
||
|
||
---
|
||
|
||
## 数据模型
|
||
|
||
### MySQL 核心表
|
||
|
||
| 表名 | 说明 | 关键字段 |
|
||
|---|---|---|
|
||
| `ai_advice_customer` | ★ 微信好友（`self_wxid` + `user_name` 唯一键） | label_list, session_id（当前活跃会话） |
|
||
| `ai_advice_label` | ★ 微信标签（`self_wxid` + `label_id` 唯一键） | label_id, label_name |
|
||
| `ai_advice_advicer` | 销售基本信息 | wx_device_id（即 appId） |
|
||
| `ai_advice_project` | 项目信息 | wx_token |
|
||
| `ai_advice_admin` | 管理员账号 | |
|
||
| `ai_advice_session` | AI 对话会话 | advicer_id（托管场景动态取最新版本） |
|
||
|
||
### MongoDB 核心集合
|
||
|
||
| 集合名 | 说明 | 关键字段 |
|
||
|---|---|---|
|
||
| `advicer_wx_msg` | ★ 微信消息流水 | appId, selfWxid, wxid, direction, msgType, content, read |
|
||
| `advicer_version` | 销售画像 | dialectFeatures, sentencePatterns, toneTags, personalityTags |
|
||
| `advicer_client` | 客户画像 | clientLevel, personalInfo, purchasePurpose, coreDemands |
|
||
| `advicer_project` | 项目资料维度（结构化） | regionValue, competitionComparison, coreSellingPoints, supportingFacilities, developerBacking |
|
||
| `advicer_project_data` | ★ 项目资料（扁平栏目） | projectId + 动态栏目（key=栏目名, value=内容），与 advicer_project 是**两个独立的集合** |
|
||
| `advicer_talk_skill` | 聊天技巧维度 | needsMining, painPointResponse, closingTechniques, communicationRhythm, valueBuilding |
|
||
| `advicer_activity` | 产品活动 | name, content, startAt, endAt |
|
||
|
||
### 命名差异
|
||
- MySQL：蛇形（`user_name`）
|
||
- MongoDB：驼峰 bson（`userName`）
|
||
- 前端 JS：驼峰（`userName`）
|
||
- API 响应：snake_case（`user_name`），前端手动映射
|
||
|
||
---
|
||
|
||
## 前端架构
|
||
|
||
### 核心机制
|
||
- **零构建**：`<script>` 标签按序引入，无打包工具
|
||
- **IIFE 模式**：每个 JS 文件 `(function(global){...})(window)` 包裹
|
||
- **版本号**：`<script src="xxx.js?v=42">` — **修改 JS/CSS 后必须更新 `project.html` 中的版本号**
|
||
- **全局命名空间**：`Core`（核心库）、`WxN`（微信模块共享）、`Wx`（挂载点）
|
||
|
||
### 微信工作台模块（WxN 命名空间）
|
||
|
||
| 文件 | 职责 |
|
||
|---|---|
|
||
| `wx.js` | state 管理 / 生命周期 / 通讯录 / 标签 / WebSocket / 好友差集同步 |
|
||
| `wx_login.js` | 二维码登录 / 在线检测 / 登出 |
|
||
| `wx_chat.js` | 会话列表 / 消息渲染 / 发送 / 联系人详情悬浮气泡 |
|
||
|
||
**架构要点**：
|
||
- `wx.js` 创建 `WxN` 命名空间，通过 `Object.defineProperty` 暴露 `state` getter
|
||
- 子模块通过 `WxN.state` 访问最新状态（不在闭包中缓存 state 引用）
|
||
- 子模块通过 `WxN.xxx = fn` 导出函数
|
||
- 加载顺序：`wx.js` → `wx_login.js` → `wx_chat.js`
|
||
|
||
### Core.js 速查
|
||
|
||
```javascript
|
||
Core.api(path, params) // 管理后台 API（POST JSON，JWT，自动解包 data）
|
||
// 完整路径：/api/v1/admin/advice/admin/{path}
|
||
Core.wxApi(path, params) // 微信代理 API（自动注入 projectId）
|
||
// 完整路径：/api/v1/admin/advice/admin/wx/{path}
|
||
Core.toast(msg, type) // type: "ok"|"err"|"warn"|"info"
|
||
Core.modal({title, body}) // 模态框
|
||
Core.confirm(msg) // 确认对话框，返回 Promise<boolean>
|
||
Core.esc(str) // HTML 转义
|
||
```
|
||
|
||
---
|
||
|
||
## 关键流程
|
||
|
||
### 初始化流程
|
||
|
||
```
|
||
页面加载 → mount() → freshState()
|
||
→ 解析 URL hash (#wx-advicer=advicerId)
|
||
→ fetchDeviceAndCheck(advicerId)
|
||
→ Core.api("advicer/info", {advicerId}) 获取 wx_device_id
|
||
→ state.app = { appId: wx_device_id } ← 始终从 API 获取，不缓存
|
||
→ checkOnline()
|
||
→ 在线 → checkOnlineLoop()（内含 connectWs()）
|
||
loadProfile().then(loadConversations()) ← 需要 wxid
|
||
loadContacts() → syncCustomerDiff() ← diff 同时返回标签
|
||
loadLabels() ← 与微信同步标签到 DB
|
||
→ 离线 → getQrCode() 显示二维码
|
||
```
|
||
|
||
### 好友 + 标签同步流程
|
||
|
||
```
|
||
loadContacts() → syncCustomerDiff()
|
||
→ POST advicer/customer/diff { selfWxid, userNames: friends }
|
||
→ 后端返回 { list: [已有好友], diff: [缺失userName], labels: [标签列表] }
|
||
→ 用 list 填充 state.brief（联系人简要）
|
||
→ 用 labels 填充 state.labels + state.labelMap
|
||
→ diff 不为空时：分批 getBriefInfo → batch_add 入库
|
||
|
||
loadLabels()（并行）
|
||
→ Core.wxApi("label/list") 获取微信标签
|
||
→ POST advicer/label/sync 同步到 DB（比对增删改）
|
||
→ loadLabelsFromDb() 重新加载
|
||
```
|
||
|
||
### 消息回调流程
|
||
|
||
```
|
||
上游协议服务 → POST /api/v1/advicer/wx/callback
|
||
→ advice_wx.go：解析 AddMsg → 过滤 gh_ 公众号/msgType=other
|
||
→ 去重（AppId + NewMsgId）→ 入库 MongoDB advicer_wx_msg
|
||
→ WebSocket 广播 new_message（按 appId 匹配推送）
|
||
→ 触发智能策略（客户文本消息异步 AI 决策）
|
||
→ 触发托管自动注册（文本私聊消息异步检查）
|
||
```
|
||
|
||
### 托管自动注册流程
|
||
|
||
```
|
||
消息回调 → 文本私聊 → goroutine tryHostingAutoRegis
|
||
→ (1) 查 advicer（FindByWxDeviceId）→ hosting_enabled=1?
|
||
→ (2) 查 projectInfo → 取项目级 wxToken
|
||
→ (3) 若 peerWxid == "filehelper" 且 advicer.reply_filehelper=1 → 跳过标签检查，直接进入回复流程
|
||
否则调微信 contacts/getDetailInfo 取好友 labelList（"1,2,3" 形式）
|
||
labelList 为空 → 直接 return，不做回复
|
||
→ (4) 取 ai_advice_label 中该销售 hosting=1 的标签 ID 列表
|
||
→ (5) 判断好友 labelList 与托管标签是否有交集，无交集 → return
|
||
→ (6) 查 ai_advice_customer 取 session_id
|
||
→ (7) 无会话 → autoRegisSession 全量加载数据并注册：
|
||
- 加载版本数据（advicer_version）
|
||
- 加载销售技巧（advicer_talk_skill，有 HostingSkillId 按 ID 取，无则按 projectId 取最新）
|
||
- 加载客户画像（advicer_client，按 projectId+advicerId+wxid 查）
|
||
- 加载项目资料（advicer_project 结构化 + advicer_project_data 扁平栏目）
|
||
- 构建 ChatData → Regis 存入 Redis（key=chatdata:{sessionId}）
|
||
→ (8) hostingChatAndSend：
|
||
- 从 Redis 取 ChatData → buildChatPromptResponse 全量注入提示词
|
||
- Chat 生成 AI 回复 → 拆段 → 模拟打字延迟 → 分段发送
|
||
```
|
||
|
||
**关键设计**：
|
||
- 标签判断改用微信实时返回的 labelList，不再依赖 customer 表缓存的标签
|
||
- projectInfo 提前到步骤 2 查询（后续 getDetailInfo 和 Chat 都需要 wxToken）
|
||
- 客户昵称优先使用微信备注名（Remark），回退到 NickName，最后才用 customer 表中的昵称
|
||
- customer 表仅用于存取 session_id，不再承担标签判断职责
|
||
- 文件传输助手（filehelper）特殊路径：销售开启 `reply_filehelper` 后，跳过标签检查，直接作为客户进行 AI 回复
|
||
|
||
### ChatData 与全量提示词注入
|
||
|
||
**ChatData 结构**（`entitys/advicer.go`）：
|
||
```go
|
||
type ChatData struct {
|
||
ClientInfo *AdvicerClientMongoEntity // 客户画像（advicer_client）
|
||
TalkSkill *AdvicerTalkSkillMongoEntity // 销售技巧（advicer_talk_skill）
|
||
ProjectInfo *AdvicerProjectMongoEntity // 项目资料-结构化（advicer_project）
|
||
ProjectData map[string]interface{} // 项目资料-扁平栏目（advicer_project_data）
|
||
AdvicerInfo *AiAdviceAdvicerEntity // 销售信息（MySQL）
|
||
AdvicerVersion map[string]interface{} // 销售人设维度数据（advicer_version）
|
||
RuleDimension string // 项目风控红线
|
||
}
|
||
```
|
||
|
||
**提示词构建流程**（`buildChatPromptResponse`）：
|
||
```
|
||
System Prompt = BasePrompt + Mission + RuleDimension + BasePrompt2
|
||
+ [项目信息] (advicer_project JSON)
|
||
+ [项目资料] (advicer_project_data JSON)
|
||
+ [销售信息] (advicer MySQL JSON)
|
||
+ [销售人设风格] (advicer_version JSON)
|
||
+ [客户信息] (advicer_client JSON)
|
||
+ [销售技巧] (advicer_talk_skill JSON)
|
||
+ [输出格式] (永远在最后)
|
||
---
|
||
System Prompt = 聊天记录（客户/我 对话格式）
|
||
---
|
||
User Message = 当前消息
|
||
```
|
||
|
||
**数据流**：
|
||
- Regis 时：`autoRegisSession` 全量加载所有数据 → 构建 ChatData → `json.Marshal` 存入 Redis（key=`chatdata:{sessionId}`，TTL 1h）
|
||
- Chat 时：从 Redis 取 ChatData → `compactJSON`（递归去空值省 token）→ 注入 system prompt
|
||
- `compactJSON`：序列化前递归去除空字符串、null、空数组、空对象，减少无效 token
|
||
|
||
**注意**：`advicer_project` 和 `advicer_project_data` 是**两个独立的 MongoDB 集合**，前者存结构化维度（区域价值/竞品对比等），后者存扁平栏目数据（key=栏目名）。两者都需要加载。
|
||
|
||
**模拟真人发送算法**：
|
||
- AI 回复拆分为多条短消息（每条 ≤80 字，按换行/句末标点拆分）
|
||
- 初始延迟 3~8 秒（模拟阅读 + 思考）
|
||
- 每条消息间延迟 = 思考时间(2~5s) + 打字时间(每字 300~500ms)
|
||
- 提示词约束：每条消息 10~30 字，用 `\n` 分隔
|
||
|
||
### WebSocket 实时通信
|
||
|
||
```
|
||
前端 connectWs() → /api/v1/advicer/ws?token=JWT
|
||
→ onopen 发送 {"action":"subscribe","appId": state.app.appId}
|
||
→ 后端 Broadcast(appId, event, data) → 匹配 client.appId → 推送
|
||
→ 前端 onmessage → handleWsEvent()
|
||
→ "new_message" → WxN.handleNewMessage(data)
|
||
→ "online_status" → WxN.handleOnlineStatus(data)
|
||
```
|
||
|
||
---
|
||
|
||
## 当前开发状态（截至 2026-09-27）
|
||
|
||
### 已完成
|
||
|
||
- [x] 微信工作台：登录（二维码/在线检测）、通讯录、会话、聊天、AI 建议
|
||
- [x] 好友差集同步：`ai_advice_customer` 表 + `customer/diff` + `batch_add/batch_update`
|
||
- [x] 标签同步：`ai_advice_label` 表 + `label/sync` + `label/list`
|
||
- [x] 标签在 diff 接口一并返回（进入工作台时一次请求拿到好友 + 标签）
|
||
- [x] 标签 tab：展开/折叠、好友计数、loading 状态
|
||
- [x] 好友/会话列表展示联系人标签小标签
|
||
- [x] 联系人详情悬浮气泡（hover popup，含视口边界检测）
|
||
- [x] WebSocket 实时推送新消息 + 在线状态
|
||
- [x] 去掉 localStorage 缓存（brief/labels 全部内存 state）
|
||
- [x] 托管标签自动会话注册：检查标签交集 → 自动注册 AI 会话 → 回写 session_id
|
||
- [x] 托管自动回复：注册会话 → Chat → 拆段 → 模拟真人打字延迟 → 分段发送
|
||
- [x] 项目级 wx_token 支持：SendTextWithToken 方法，托管场景使用项目级 token
|
||
- [x] 查询优化：消除重复查询（projectInfo/advicer/session），新注册路径从 ~16 次降至 ~10 次 DB
|
||
- [x] 文件传输助手自动回复：销售级开关 `reply_filehelper`，开启后跳过标签检查直接 AI 回复
|
||
- [x] filehelper 普通客户化改造：走标准 customer 流程复用 session_id
|
||
- [x] ChatData 全量数据注入：Regis 时加载全部数据（项目/销售/客户/技巧/人设），Chat 时从 Redis 取出全量注入提示词
|
||
- [x] 提示词 token 优化：`compactJSON` 递归去空值，减少无效 token
|
||
|
||
### 待开发（下一步）
|
||
|
||
#### 1. 聊天算法深度优化
|
||
|
||
**目标**：进一步提升 AI 回复的真实感，让对话更自然、更像真人销售。
|
||
|
||
**优化方向**：
|
||
- **回复节奏优化**：根据消息内容复杂度动态调整延迟（简单问候快一些，复杂问题慢一些）
|
||
- **上下文感知回复**：结合客户画像、历史对话、当前时间段等因素调整回复风格
|
||
- **多轮对话连贯性**：确保多轮对话中话题过渡自然，不重复、不突兀
|
||
- **情绪感知**：识别客户情绪（犹豫/急迫/不满），动态调整回复语气和节奏
|
||
- **回复长度自适应**：根据客户消息长度调整回复长度（客户发短句，AI 也回短句）
|
||
- **提示词迭代**：根据实际对话效果持续优化 BasePrompt，减少 AI 味、增强人味
|
||
|
||
**涉及文件**：
|
||
- `internal/data/constants/prompt.go`（提示词模板）
|
||
- `internal/biz/advice_wx.go`（splitReplyToChunks / hostingChatAndSend）
|
||
- `internal/biz/advice_wx_send.go`（typingDelay 算法）
|
||
- `internal/biz/advice_chat.go`（Chat / ChatWithSession）
|
||
- `internal/biz/advice_strategy.go`（智能策略回复）
|
||
|
||
#### 2. 标签标记为客户标签 → 客户管理联动
|
||
|
||
**目标**：给标签打上"客户标记"，被标记标签下的好友自动识别为客户，在客户管理模块体现，并在销售托管（自动回复）开启时仅对这些客户生效。
|
||
|
||
**设计思路**：
|
||
- `ai_advice_label` 表新增 `is_customer_tag TINYINT(1) DEFAULT 0` 字段（1=客户标签）
|
||
- 新增 API：`advicer/label/mark_customer` { selfWxid, labelId, isCustomerTag: bool }
|
||
- 前端标签 tab：每个标签右侧增加"客户标签"开关/标记按钮
|
||
- 客户管理模块（`advice_client.go` / `client.go`）：
|
||
- 查询客户时，筛选 `ai_advice_customer.label_list` 包含已标记标签 ID 的记录
|
||
- 客户列表展示来源标签名称
|
||
- 智能策略（`advice_strategy.go`）：
|
||
- 自动回复/主动触达判断时，仅对"客户标签下的好友"生效（非客户标签的好友不触发 AI 自动回复）
|
||
- 读取 `ai_advice_label` 中 `is_customer_tag=1` 的标签 ID 集合，与消息发送者的 `label_list` 取交集
|
||
|
||
**涉及文件**：
|
||
- 后端：`ai_advice_label.gen.go`（加字段）、`advice_label_impl.go`（加 MarkCustomer 方法）、`advice_label.go`（加 MarkCustomer biz）、`label.go`（加 handler）、`advicer_data.go`（加 DTO）、`advice_strategy.go`（过滤逻辑）
|
||
- 前端：`wx.js`（标签 tab 渲染标记按钮）、`theme.css`（标记样式）
|
||
- SQL：`06_ai_advice_label_customer_tag.sql`（ALTER TABLE 或迁移脚本）
|
||
|
||
#### 3. 好友/会话列表 → 给好友打标签
|
||
|
||
**目标**：在好友列表和会话列表中，可以对好友（非 chatroom）添加到指定标签，类似微信原生标签管理。
|
||
|
||
**设计思路**：
|
||
- 利用微信协议 API `contacts/modifyFriendLabel`（或类似端点）修改好友的标签
|
||
- 前端：联系人详情悬浮气泡（popup）中增加"管理标签"入口，点击弹出标签选择弹窗
|
||
- 展示当前好友已有的标签（从 `state.brief[wxid].labelList` 解析）
|
||
- 展示所有可用标签（`state.labels`）
|
||
- 支持勾选/取消，确认后调用微信 API 修改，再更新 DB（`ai_advice_customer.label_list`）
|
||
- 修改后需同步更新 `state.brief[wxid].labelList` 并重新渲染
|
||
|
||
**涉及文件**：
|
||
- 后端：可能需要新增微信代理 API（`pkg/wx/qs_*.go` + `api.go` + `wx_proxy.go` wxDispatchMap）
|
||
- 前端：`wx_chat.js`（popup 中加"管理标签"按钮 + 标签选择弹窗）、`wx.js`（标签更新逻辑）
|
||
- DB：更新 `ai_advice_customer.label_list` 字段
|
||
|
||
---
|
||
|
||
## Wire 依赖注入须知
|
||
|
||
新增模块后必须：
|
||
1. 各层 `provider_set.go` 添加 Provider
|
||
2. `http.go` 的 `NewHTTPServer` 参数列表添加 Service
|
||
3. `router.go` 的 `SetupRoutes` 参数列表添加 Service
|
||
4. `router/advicer.go` 的 `AdvicerRouterRegist` 参数列表添加 Service
|
||
5. 执行 `cd cmd/server && wire` 重新生成 `wire_gen.go`
|
||
6. `go build ./cmd/server` 编译验证
|
||
|
||
---
|
||
|
||
## 避坑清单
|
||
|
||
1. **`*.gen.go` 和 `wire_gen.go` 禁止手动编辑**
|
||
2. **Mongo 全量更新是 `$set` 语义** — 必须"先读后合并再写"，否则清空未提交字段
|
||
3. **微信代理响应必须设 `skip_response_wrap`** — 否则被 `registerCommon` 二次包装成 `{data:{code,data}}`
|
||
4. **前端修改必须更新版本号** — `project.html` 中 `?v=N`，不更新则浏览器用旧缓存
|
||
5. **`state.app.appId` 不缓存** — 每次 mount 从 `advicer/info` API 实时获取
|
||
6. **`checkOnlineLoop()` 已内含 `connectWs()`** — 不要额外调用，否则连接级联断开
|
||
7. **`loadProfile()` 返回 Promise** — 依赖 `state.app.wxid` 的操作必须在其 `.then()` 中执行
|
||
8. **子模块通过 `WxN.state` getter 访问状态** — 不要在闭包中缓存 state 引用
|
||
9. **`builder.Cond` 查询用指针** — DataTemp 方法接受 `*builder.Cond` 指针
|
||
10. **`dataTemp.ReqPageBo` 分页字段是 `Limit`** — 不是 `PageSize`
|
||
11. **新增 Service 后同步三个文件** — `http.go`、`router.go`、`advicer.go` 函数签名都要加参数
|
||
12. **会话/消息查询用 `selfWxid` 筛选** — 不用 `appId`（appId 会变）
|
||
13. **WebSocket 订阅 appId 必须与广播 appId 一致** — 前端用 `wx_device_id`，后端用回调的 `Appid` 字段
|
||
14. **历史遗留代码**（`internal/biz/handle`、`llm_service`）是死代码，可忽略
|
||
15. **`advicer_project` 和 `advicer_project_data` 是两个独立的 MongoDB 集合** — 前者存结构化维度（RegionValue/CompetitionComparison 等），后者存扁平栏目数据（key=栏目名, value=内容）。加载项目数据时两者都要查
|
||
16. **HostingSkillId 为空时取最新** — 用 `VersionList(projectId)` 取第一条，不是跳过
|
||
17. **PreviousResponseID 续写不继承 system prompt** — Chat 时必须从 Redis 取 ChatData 重新注入全部数据，不能依赖 context cache 续写
|
||
18. **修改 JS/CSS 后必须更新版本号** — 否则浏览器用旧缓存，看起来像没改
|
||
|
||
---
|
||
|
||
## 编译与部署
|
||
|
||
```bash
|
||
# 编译（仅验证业务代码）
|
||
go build ./internal/entitys/ ./internal/services/advice/ ./cmd/server/
|
||
|
||
# 本地运行
|
||
go run cmd/server/main.go
|
||
|
||
# Wire 重新生成
|
||
cd cmd/server && wire
|
||
|
||
# Docker 部署
|
||
docker-compose up -d
|
||
```
|
||
|
||
---
|
||
|
||
*最后更新：2026-09-27*
|