# 销冠平台技术实现方案 ## 1. 文档范围 本文档用于指导“场景化销售话术与 SOP 平台”的第一阶段实现。 第一阶段的核心闭环是： ```text 创建场景 -> 配置自定义字段 -> 编排 SOP -> 审核发布 -> 一线人员执行 -> 记录反馈 ``` 场景不写死在代码中。宠物医生问诊问药只是一个配置示例，后续可以创建保险咨询、房地产销售、教育课程顾问等其他场景。 本阶段暂不实现文件存储、AI 自动生成、CRM 集成和微服务拆分。 ## 2. 技术选型 ### 2.1 后端 - Go：业务服务和流程执行引擎 - Gin：HTTP 路由、中间件和请求处理 - Zap：结构化日志 - cleanenv：YAML 配置解析和环境变量覆盖 - GORM：MySQL 数据访问 - golang-migrate：数据库迁移 - `go-playground/validator`：请求参数校验 - JWT + Refresh Token：登录认证 第一阶段采用模块化单体。所有业务模块运行在一个 Go 服务中，通过清晰的内部边界保持可维护性，后续再根据实际负载拆分服务。 配置加载使用 `github.com/ilyakaznacheev/cleanenv`。它的行为简单明确：先读取 YAML 文件，再读取环境变量，环境变量值覆盖文件中的同名配置。 ### 2.2 前端 - Vue 3 - Vite - TypeScript - Ant Design Vue - Vue Router - Pinia - Axios SOP 编辑器第一版使用步骤卡片和条件配置，不立即引入复杂的画布编辑器。需要图形化节点编排时，使用 Vue 生态的流程图组件，不使用 React Flow。 ### 2.3 数据库和运行环境 - MySQL 8.0+ - Docker Compose：本地开发 - Nginx：生产环境反向代理 - Linux 容器部署 本阶段不引入 Redis。登录会话、场景配置和执行状态先使用 MySQL；只有出现异步任务、缓存或高并发需求时再增加 Redis。 ## 3. 配置管理 配置结构统一放在 `internal/config/`，业务代码不能直接读取环境变量。 配置优先级如下： ```text 结构体默认值 < config.yml < 当前环境配置文件 < 环境变量 ``` 配置文件约定如下： ```text configs/config.example.yml # 配置模板，可提交，不包含敏感信息 configs/config.yml # 基础配置 configs/config.test.yml # 测试环境覆盖配置 configs/config.prod.yml # 生产环境覆盖配置 ``` 运行环境通过 `APP_ENV` 或启动参数 `--env` 选择，优先级为启动参数高于环境变量： ```text 未指定环境 -> config.yml APP_ENV=test -> config.yml + config.test.yml APP_ENV=prod -> config.yml + config.prod.yml ``` `config.yml` 作为基础文件必须存在。`test` 和 `prod` 环境对应的覆盖文件也必须存在；缺失时服务直接退出。环境配置文件只填写与基础配置不同的字段，未填写的字段沿用 `config.yml`。 配置文件路径通过 `--config-dir` 指定，默认使用当前工作目录下的 `configs/`。部署时可以挂载外部配置目录，不需要把真实生产配置提交到代码仓库。 环境变量名称通过结构体标签显式声明，例如： ```text APP_SERVER_HOST APP_SERVER_PORT APP_DATABASE_HOST APP_DATABASE_PORT APP_DATABASE_USER APP_DATABASE_PASSWORD APP_DATABASE_NAME ``` 配置字段约定： - `yaml`：YAML 文件中的字段名。 - `env`：环境变量名称，必须显式声明。 - `env-default`：没有文件值和环境变量时使用的默认值。 - `env-required:"true"`：必须由环境变量提供的敏感或关键配置。 - `env-prefix`：为嵌套配置统一增加环境变量前缀。 - `env-layout`：日期、时间等特殊类型的解析格式。 生产环境中，数据库密码、JWT 密钥等敏感字段必须使用 `env-required:"true"`，不写入 YAML 文件。配置加载失败或必填项缺失时，服务直接退出，不使用不完整配置继续启动。 加载过程必须保持以下顺序：先加载基础配置，再加载当前环境配置，最后执行环境变量覆盖。环境变量不能被后续 YAML 文件覆盖。 ## 4. 目录规划 代码统一放在 `codes/` 目录下。按照 `golang-standards/project-layout` 的组织方式，同时遵循“根目录放置 main.go”和“前端放在 web 目录”的项目约束。 ```text codes/ ├── main.go # Go 服务入口，位于代码根目录 ├── go.mod ├── go.sum ├── internal/ │ ├── config/ # 配置加载 │ ├── logger/ # Zap 初始化和日志字段规范 │ ├── middleware/ # 认证、租户、请求日志、异常恢复 │ ├── router/ # 路由注册 │ ├── handler/ # HTTP 接口层 │ ├── service/ # 业务服务层 │ ├── repository/ # 数据访问层 │ ├── model/ # 数据库模型和请求响应模型 │ ├── engine/ # SOP 流程执行引擎 │ └── webassets/ # 前端嵌入和静态资源处理 ├── pkg/ │ └── response/ # 可被外部复用的通用响应结构 ├── configs/ │ ├── config.yml │ ├── config.test.yml │ ├── config.prod.yml │ └── config.example.yml ├── migrations/ # MySQL 数据库迁移文件 ├── scripts/ # 构建、检查和发布脚本 └── web/ ├── package.json ├── vite.config.ts ├── index.html ├── src/ │ ├── api/ │ ├── components/ │ ├── layouts/ │ ├── router/ │ ├── stores/ │ ├── types/ │ └── views/ └── dist/ # 前端构建产物，由 Go 使用 go:embed 嵌入 ``` 说明：`cmd/` 目录不使用，Go 入口固定为 `codes/main.go`。`codes/web/dist/` 是构建产物目录，前端构建完成后由 Go 服务作为静态资源提供。 ```text 浏览器 ├── 管理端：场景、字段、SOP、知识卡、审核 └── 执行端：按 SOP 执行和记录客户回答 | v Go HTTP 服务 ├── 身份认证与租户权限 ├── 场景配置服务 ├── SOP 版本服务 ├── 流程执行引擎 ├── 知识卡服务 └── 执行记录与统计 | v MySQL ``` ## 5. 系统架构 Go 服务同时承担 API 服务和前端静态资源服务。前端构建后通过 `go:embed` 打入 Go 二进制，生产环境只需要部署一个服务包和配置文件。 ## 6. go:embed 方案 前端构建输出到 `codes/web/dist/`，Go 服务通过 `go:embed` 嵌入该目录。 构建流程为： ```text 进入 codes/web -> 安装依赖 -> 执行前端构建 -> 生成 web/dist -> 回到 codes -> 执行 Go 构建 -> 生成包含前端资源的二进制 ``` 服务端静态资源处理规则： - `/api/` 路径只进入 Go API 路由。 - 静态文件路径优先读取 `web/dist` 中对应文件。 - 非 API 且找不到文件的路径回退到 `index.html`，支持 Vue Router 的 history 模式。 - 前端资源由 Nginx 或应用服务设置长期缓存，`index.html` 不使用长期缓存。 前端 `dist` 不存在时，Go 项目不能完成编译，因此代码仓库需要保留一个可构建的前端产物占位文件，或者在 CI 中强制先执行前端构建。 ## 7. 场景模型 场景是平台的一级可配置对象，不能在代码中写死行业字段。 一个场景至少包含： - 场景名称 - 所属行业 - 适用角色 - 使用目标 - 触发条件 - 可见范围 - 自定义字段 - 一个或多个 SOP - 关联知识卡 - 发布状态 例如宠物医生问诊问药场景可以配置： ```text pet_type 宠物种类 pet_age 年龄 pet_weight 体重 symptom 症状 symptom_duration 症状持续时间 has_emergency_sign 是否存在急症 ``` 保险咨询场景则可以配置客户年龄、职业、预算和保险类型。新增场景只需要增加配置数据，不需要修改业务代码。 ## 8. SOP 模型 SOP 由版本、节点和连线组成。 第一阶段支持以下节点类型： - `start`：流程开始 - `message`：展示标准话术 - `question`：提问并写入一个场景字段 - `form`：一次收集多个字段 - `choice`：让执行人员选择客户回答 - `condition`：根据已收集字段进行分支 - `knowledge`：展示已审核知识卡 - `escalate`：转人工、转医生或线下处理 - `finish`：结束流程 条件必须保存为结构化规则，不能让用户输入或执行任意 JavaScript。条件规则支持等于、不等于、包含、大于、小于、全部满足、任一满足等操作。 发布前需要校验： - 只有一个开始节点 - 所有节点都可从开始节点访问 - 所有分支都有出口 - 不存在无法结束的路径 - 必填字段存在对应采集节点 - 关联知识卡已经审核 - 急症或高风险分支有明确的转人工或转诊动作 ## 9. MySQL 数据表 核心表如下： ```text users 用户 tenants 企业或组织 tenant_members 企业成员和角色 roles 角色权限 scenarios 场景 scenario_fields 场景自定义字段 sops SOP 基础信息 sop_versions SOP 版本 sop_nodes SOP 节点 sop_edges SOP 连线和条件 knowledge_cards 话术或知识卡 knowledge_card_versions 知识卡版本 sop_runs SOP 执行实例 sop_run_events SOP 节点执行事件 sop_feedback 执行反馈 audit_logs 操作审计 ``` 关键设计： - 所有租户相关数据必须能追溯到 `tenant_id`。 - 场景字段使用行记录保存，避免把场景字段写死在表结构中。 - 节点配置和条件规则使用 MySQL JSON 字段保存。 - 已发布版本不可直接修改，修改时复制为新的草稿版本。 - 版本状态流转为 `draft -> reviewing -> published -> offline`；管理员也可以从草稿直接发布。 - 执行过程保存事件记录，便于复盘和统计。 - 需要参与筛选和统计的字段不能只存 JSON，应在事件表或统计表中建立结构化字段。 ## 10. 后端接口规划 ### 场景接口 ```text POST /api/v1/scenarios GET /api/v1/scenarios GET /api/v1/scenarios/:id PUT /api/v1/scenarios/:id DELETE /api/v1/scenarios/:id ``` ### 自定义字段接口 ```text POST /api/v1/scenarios/:id/fields PUT /api/v1/scenario-fields/:id DELETE /api/v1/scenario-fields/:id ``` ### SOP 接口 ```text POST /api/v1/scenarios/:id/sops GET /api/v1/scenarios/:id/sops PUT /api/v1/sops/:id/draft POST /api/v1/sops/:id/validate POST /api/v1/sops/:id/submit-review POST /api/v1/sops/:id/publish POST /api/v1/sops/:id/offline ``` ### SOP 执行接口 ```text POST /api/v1/runs GET /api/v1/runs/:id POST /api/v1/runs/:id/answer POST /api/v1/runs/:id/finish POST /api/v1/runs/:id/feedback ``` ## 11. 流程执行引擎 执行流程如下： 1. 创建执行实例，绑定一个已发布的 SOP 版本。 2. 加载开始节点并返回给前端。 3. 前端展示话术、表单或选项。 4. 后端校验客户回答和字段类型。 5. 在事务中保存回答和节点事件。 6. 根据结构化条件计算下一节点。 7. 返回下一节点或结束动作。 流程引擎只处理通用节点和规则，不理解“宠物”“保险”等具体业务。行业知识放在场景字段、话术内容和知识卡中。 ## 12. Zap 日志规范 使用 Zap 输出结构化 JSON 日志到 stdout，由 Docker、Kubernetes 或云平台采集，不由应用自己维护日志文件。 日志至少包含： - `service` - `env` - `request_id` - `tenant_id` - `user_id` - `action` - `resource` - `resource_id` - `duration_ms` - `err` 日志等级约定： - `DEBUG`：本地开发细节 - `INFO`：正常请求、发布、执行等业务事件 - `WARN`：参数异常、权限拒绝、客户端错误 - `ERROR`：服务异常、数据库失败、流程执行失败 禁止记录密码、Token、完整客户聊天内容和未脱敏的个人信息。 Gin 请求日志中需要记录请求方法、路径、状态码、耗时和 Request ID。业务日志使用结构化字段，不使用字符串拼接。 ## 13. 前端页面规划 ### 管理端 - 场景列表 - 创建/编辑场景 - 自定义字段配置 - SOP 列表 - SOP 步骤编辑器 - 节点条件配置 - 知识卡管理 - 审核发布中心 - 执行数据看板 ### 执行端 - 场景选择 - SOP 当前节点 - 客户信息录入 - 标准话术展示 - 分支选择 - 转人工或转诊提醒 - 执行结果和反馈 Ant Design Vue 主要使用 `Form`、`Table`、`Drawer`、`Modal`、`Steps`、`Tree`、`Tabs` 和 `Descriptions`。动态字段表单由场景字段配置生成，字段校验规则也由配置生成。 ## 14. 安全与权限 - 用户登录后从 Token 中获取 `tenant_id`，不能信任前端传入的租户 ID。 - 所有查询必须自动附加租户条件。 - 场景、SOP、知识卡、执行记录都需要做资源级权限判断。 - 发布、下线、审核和修改权限分离。 - 已发布 SOP 版本只读，修改时复制为新的草稿版本。 - 记录关键操作到 `audit_logs`。 - 条件规则禁止执行任意代码。 ## 15. 第一阶段开发顺序 ### 第 1 阶段：基础服务 - Go 服务初始化 - Zap 日志 - 配置加载 - MySQL 连接 - 登录和租户权限 - 前端构建和 go:embed ### 第 2 阶段：场景配置 - 场景 CRUD - 自定义字段 CRUD - 场景权限 - 场景状态管理 ### 第 3 阶段：SOP 编排 - 节点管理 - 连线和条件配置 - 草稿保存 - 流程校验 - 版本复制 ### 第 4 阶段：SOP 执行 - 创建执行实例 - 节点展示 - 回答提交 - 条件跳转 - 执行事件记录 ### 第 5 阶段：审核和反馈 - 提交审核 - 审核发布 - 下线和回滚 - 执行反馈 - 基础数据统计 ## 16. 构建和部署约定 首次初始化本地 MySQL 数据库时执行： ```bash cd codes mysql -uroot -p < scripts/create-databases.sql ``` 服务启动时会自动执行 `migrations/` 中的迁移，创建业务表并记录 `schema_migrations` 版本。 本地开发时前后端可以分别启动： ```text 前端开发服务：codes/web Go API 服务：codes ``` 生产构建时先构建前端，再构建 Go 服务。最终产物只需要： - Go 二进制 - 配置文件 - MySQL 数据库 前端静态资源已经通过 `go:embed` 编译进入 Go 二进制，不需要单独部署前端静态目录。 ## 17. 暂不实现的内容 - 文件上传和对象存储 - AI 自动提炼话术 - AI 客户模拟陪练 - CRM、企业微信和客服系统集成 - 多服务拆分 - Redis 缓存 - 消息队列 - 复杂 BI 分析 这些内容等核心闭环验证成功后再加入，避免第一版架构过度复杂。