整体架构
企智通采用经典的前后端分离 + 单体模块化架构。后端 qzt-go-server 是整个系统的唯一数据源与业务规则持有者；admin、cms、mobile 三套前端都是后端 RESTful API 的消费方，前端本身不直接持有任何业务状态。
架构总览图
┌─────────────────────────────┐
│ 终端用户访问 │
└──────────────┬──────────────┘
│
┌────────────────────────────┼────────────────────────────┐
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│ admin (SPA) │ │ cms (Next.js) │ │ mobile (SPA) │
│ React + antd │ │ SSR / ISR │ │ antd-mobile │
│ 后台管理 / 运营 │ │ 官网 / 博客 / SEO│ │ 外勤 / 移动办公 │
└────────┬────────┘ └────────┬─────────┘ └────────┬─────────┘
│ │ │
│ HTTPS / RESTful API │ │
└───────────────────────────┼────────────────────────────┘
│
▼
┌───────────────────────────────────────────┐
│ qzt-go-server (Go 单体后端) │
│ │
│ ┌─────────────────────────────────────┐ │
│ │ 中间件链 │ │
│ │ Recovery → Trace → CORS → Logger │ │
│ │ → Auth → OperationLog → Casbin │ │
│ └─────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────┐ │
│ │ 业务模块 (每个实现 Module 接口) │ │
│ │ CRM · HRM · PSI · Finance · CMS │ │
│ │ Approval · System · OA · KB ... │ │
│ │ (另挂 /mcp: 全功能 MCP 开放) │ │
│ └─────────────────────────────────────┘ │
│ │
│ 分层: handler → service → repository │
└─────┬───────────────┬───────────────┬─────┘
│ │ │
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────────┐
│ MySQL │ │ Redis │ │ OSS / 本地存储│
│ 业务数据 │ │ 缓存/会话 │ │ 文件资源 │
└──────────┘ └──────────┘ └──────────────┘
设计原则
1. 后端为唯一数据源
所有业务规则、数据校验、权限判断、数据一致性都由后端负责。前端只负责展示与交互，不做任何关键业务决策。这意味着：
- 任何前端都可以替换（admin / cms / mobile / 第三方），不影响业务正确性
- 所有写操作必须经过后端 API，避免绕过权限
- 数据计算（统计、聚合）统一在后端完成，前端不重复实现
2. 单体模块化
后端是单进程单体，但内部按业务领域严格模块化。每个模块（CRM、HRM、Approval 等）：
- 实现统一的
Module接口（注册路由、注册菜单、注册权限、数据迁移等） - 拥有独立的 handler / service / repository / model 分层
- 模块之间通过显式依赖注入协作，而非直接 import 对方内部实现
这种设计兼顾了单体的部署简单与微服务的代码清晰，适合中小企业体量。
3. 统一 API 信封
所有 API 响应遵循统一的信封格式，前端可写一次拦截器处理所有响应：
{
"code": 0,
"msg": "success",
"data": { },
"timestamp": 1722816000
}
| 字段 | 含义 |
|---|---|
code | 业务码，0 表示成功，非 0 为业务错误码（与 HTTP 状态码解耦） |
msg | 人类可读的提示信息，可直接展示给用户 |
data | 业务数据载荷，失败时为 null |
timestamp | 服务器时间戳，用于排查时序问题 |
分页响应在 data 中统一为：
{
"list": [],
"total": 0,
"page": 1,
"page_size": 20
}
数据流向
以「销售员创建客户」为例，展示典型请求链路：
销售员在 admin 填表
│
▼
admin 调用 POST /api/v1/crm/customers
│ (axios 自动携带 JWT)
▼
qzt-go-server 中间件链:
Recovery → Trace(生成 traceId)
→ CORS → Logger → Auth(解析 JWT, 注入用户上下文)
→ OperationLog(记录请求体) → Casbin(校验 crm:customer:create)
│
▼
crm 模块 handler: 参数绑定与校验
│
▼
service 层: 业务规则（重名校验、公海规则、数据权限过滤）
│
▼
repository 层: GORM 写入 MySQL (crm_customers 表)
│
▼
统一信封封装 → JSON 响应
│
▼
admin axios 拦截器自动解包 → UI 刷新
横切关注点
| 关注点 | 实现方式 |
|---|---|
| 链路追踪 | 每个请求分配 traceId，贯穿日志与响应头 |
| 操作审计 | 写操作自动记录操作人、IP、UA、请求体、响应体 |
| 限流 | 基于 Redis 的令牌桶，按 IP / 用户限流 |
| 缓存 | Redis 缓存字典、菜单、权限策略，减少 DB 压力 |
| 国际化 | 后端错误码对应多语言文案，前端按 locale 展示 |