🦊 玖朝雲启 CRM · 智能体交接文档

📖 目录

📌 项目概述

玖朝雲启是一家专注于企业服务的公司，核心业务包括腾讯电子签、腾讯云等SaaS产品的渠道销售与客户管理。

项目背景

• 原为腾讯电子签官网项目的一个子模块，后于 2026-05-28 独立拆分为 CRM 项目
• 设计为面向渠道销售团队的客户关系管理系统（非传统CRM，而是电子签业务定制）
• 管理销售 → 创建线索 → 跟进商机 → 转客户 → 下单发货 → 售后续费的全流程

当前状态

团队规模

⚙️ 技术架构

技术栈

系统架构

├── 官网 (tencentesign.com)
│   ├── Next.js + Prisma + SQLite
│   ├── 端口 3000, PM2: esign-website
│   └── 数据库: prisma/dev.db (独立)
│
├── CRM (jiuzhaoyunqi.com)
│   ├── Next.js + Prisma + SQLite  
│   ├── 端口 3001, PM2: crm-website
│   ├── 数据库: prisma/dev.db (主库) + prisma/ali.db (阿狸库)
│   └── AI助手: ali-server.mjs (端口 3002, PM2: ali)
│
├── Nginx 反向代理
│   ├── esign → 3000 (HTTPS)
│   └── jiuzhaoyunqi → 3001 (HTTP，SSL待申请)
│
└── Cron 定时任务
    ├── crm-cron (PM2进程)
    ├── 9:05 expiry-check (合同过期检查)
    ├── 9:00 renewal-remind (续费提醒)
    └── 9:10 opportunity-drop-check (商机掉落)

关键组件

📦 代码仓库

仓库结构

/Users/jiuchaoyunqi/WorkBuddy/研发/
├── crm-website/              ← CRM 项目（主项目）
│   ├── app/                   Next.js App Router
│   │   ├── api/               API 路由 (67个route.ts)
│   │   └── crm/               CRM 前端页面
│   ├── components/            共享组件
│   │   └── crm/               业务组件 (LeadCard, DetailPanel等)
│   ├── lib/                   工具库 (auth, permissions, notify, ali-core)
│   ├── prisma/                Schema + 数据库
│   ├── scripts/               初始化脚本
│   └── package.json
│
├── esign-website/             ← 官网项目（独立）
│   └── (同上结构，数据库独立)
│
└── .workbuddy/
    └── memory/                智能体记忆
        ├── MEMORY.md           长期记忆
        └── YYYY-MM-DD.md       每日工作日志

⚠️ CRM 项目无 git 仓库（2026-05-31 待初始化）

🛠️ 开发环境

前置要求

• Node.js 22.22.2 (本地开发) / Node.js 20.20.2 (服务器)
• npm 内置
• SSH Key: ~/.ssh/workbuddy.pem

本地运行

cd /Users/jiuchaoyunqi/WorkBuddy/研发/crm-website
# 安装依赖（如果 node_modules 不存在）
npm install

# 本地开发（使用本地 dev.db）
DATABASE_URL='file:./prisma/dev.db' npx prisma generate
DATABASE_URL='file:./prisma/dev.db' npm run dev

# 本地构建验证
cd / && rm -rf /path/.next  # 先切目录再删防锁定
cd /path && node node_modules/.bin/next build

当地 .env 要求

DATABASE_URL="file:./prisma/dev.db"    # ⚠️ 必须指向 prisma/ 下
NEXTAUTH_SECRET=...                     # session签名密钥
WECOM_CORP_ID=wwdb672a1af0855622        # 企业微信
WECOM_AGENT_ID=1000020                  # 企微应用ID
WECOM_SECRET=...                        # 企微应用Secret
CRON_SECRET=...                         # 定时任务Token
CRM_API_TOKEN=...                       # 外部导入API Token

🚀 部署信息

服务器信息

PM2 进程

🔴 部署铁律（必看！）

1. 最可靠部署方式：rsync 全量同步（禁止使用 deploy.sh，会漏文件）
2. PM2 重启：必须 pm2 delete + pm2 start，不能用 restart --update-env
3. PM2 命令格式：PORT=3001 pm2 start npm --name crm-website --cwd /path -- start（不要加 -p 3001）
4. 部署后修复 .env：sed 替换 DATABASE_URL 时要 确认 ALI_DATABASE_URL 没有被误改
5. 部署后重建 ali-client：npx prisma generate --config=prisma/ali.config.ts
6. 验证文件同步：rsync 成功后 ssh 到服务器 stat -c '%y' 文件 对比每个改动文件的时间戳
7. 验证构建产物：构建后 grep 确认新常量/函数名存在于 .next 中

部署前检查清单（13项）

1. 本地 clean build 通过
2. 关键文件行数验证（本地 vs 服务器）
3. 服务器 PM2 状态（4 个进程 online）
4. 端口占用（3000 + 3001 + 3002）
5. nginx 配置（sudo nginx -t）
6. 磁盘空间（df -h /，需 >10G）
7. 数据库备份（到 backups/）
8. 根目录无空 dev.db
9. Schema 模型完整（model Customer, Lead）
10. .env DATABASE_URL 正确
11. 服务器 Git 干净
12. JSON 默认值检查（Sqlite：空字符串 → 修复）
13. 自省复盘（记录新坑、优化点、老板反馈）

部署命令速查

# rsync 全量同步（CRM）
rsync -avz --delete --exclude='node_modules' --exclude='.next' \
  --exclude='prisma/dev.db*' --exclude='backups/' --exclude='.git' \
  --exclude='ali-skills' --exclude='.env' --exclude='public/uploads' \
  -e "ssh -i ~/.ssh/workbuddy.pem" \
  ./ ubuntu@150.158.137.193:/home/ubuntu/crm-website/

# 服务器构建
ssh -i ~/.ssh/workbuddy.pem ubuntu@150.158.137.193 \
  "cd /home/ubuntu/crm-website && cd / && rm -rf /home/ubuntu/crm-website/.next ..."
  "&& cd /home/ubuntu/crm-website && DATABASE_URL='file:./prisma/dev.db' npm run build"

# PM2 重启
PORT=3001 pm2 start npm --name crm-website --cwd /home/ubuntu/crm-website -- start

SSH 快捷登录

ssh -i ~/.ssh/workbuddy.pem ubuntu@150.158.137.193

🎯 关键功能

核心业务流程

线索公海 → 领取 → 我的商机 → 转客户 → 创建订单 → 提单发货 → 审批流 → 续费/流失
(leads_public) (claim) (my opps) (customer) (order) (deliver) (approve) (renew/lost)

1. 线索管理（4个池子）

2. 客户管理

• 状态流：pending(待审批) → approved(已审批) → finance_confirmed(财务确认) → shipped(已发货) → completed(已完成)
• 标签页：全部、本月、本周、已流失、已过期、即将到期、待审批、已驳回、已审批、财务确认、待提单、已发货、已完成
• 每个标签页右上角有计数角标（2026-06-15 最新改动）
• 归属：管理员看全部、主管看本部门、销售只看自己的

3. 订单与发货

• 提单 → 主管审批 → 财务审批 → 发货员确认
• 状态：pending → approved → finance_approved → completed
• 通知：提单后自动发站内信给主管，主管找不到→转给管理员兜底

4. 站内信系统

5. 续费与过期机制

• 合同到期当天 → 发站内信给销售（7天确认期）
• 7天内销售确认"续费" → 30天缓冲期
• 7天内销售确认"不续费" → 标记 lost
• 7天未操作 → 自动掉商机公海 + 标记 lost
• 30天缓冲期满无订单 → 掉商机公海

6. 商机3天/30天掉落

• 3天未跟进 → 第2天发提醒 → 第3天掉公海，原销售3天禁领
• 30天未成交 → 第27-29天发提醒 → 第30天掉公海

7. 阿狸 AI 助手

• 独立 PM2 进程（ali），端口 3002
• 9 个模块（config/db/session/middleware/web/tools/tool-engine/router/index）
• 38 个 Function Calling 工具，支持流式 SSE
• 前端：ali-chat.html 骨架 + ali-chat.css 样式 + ali-chat.js 逻辑
• 数据库：prisma/ali.db（独立 SQLite，Prisma 7 + LibSQL adapter）

8. 权限体系

⚠️ 2026-06-10 全面审计修复 修正了finance/shipper/channel_manager越权问题、ownerId参数越权漏洞、17个页面角色检查缺失

🗄️ 数据库设计

核心模型

关键设计决策

• ownerId vs ownerName：Customer 表 ownerId 存储 User.id，ownerName 存中文名用于显示。⚠️ 历史数据 ownerId 误存为"system"，2026-06-10已批量修复
• followUpLogs：Prisma Json 字段，存储为 JSON 字符串数组。前端读取时必须 JSON.parse 或使用 parseFollowUpLogs() 安全解析。不能直接当数组访问
• Prisma 7 特殊处理：ali.db 使用 Prisma 7 + PrismaLibSql adapter，需要在 ali.config.ts 中独立配置。主 schema 的 prisma generate 不会生成 ali-client，需额外执行 --config=prisma/ali.config.ts
• SQLite NULL != value：Prisma where.field = { not: "approved" } 会翻译为 WHERE field != "approved"，SQLite 中 NULL != "approved" 为 NULL(非TRUE)。必须显式 OR [{ field: null }, { field: { not: value } }]
• _UserRoles 表：Prisma 隐式多对多表，A=UserId, B=RoleId。⚠️ 历史上A/B列曾反转，2026-06-09已修复，但仍残存反转行（不影响查询）

Json 字段注意事项

⚠️ 禁止手动 JSON.stringify() Prisma 7 的 Json? 字段在写入时自动 JSON.stringify，读取时自动 JSON.parse。手动 JSON.stringify 会导致双重编码，数据库存为 "[{"...}]" 而不是 [{"...}]，页面上 .filter() 会报错。

SQLite 中新增 Json 字段不会自动给默认值，必须事后手动 UPDATE：

UPDATE Customer SET editHistory = '[]' WHERE editHistory IS NULL OR editHistory = '';

🔌 API 文档

认证方式

• 用户登录：Cookie session（crm_session），HMAC 签名，httpOnly
• Cron 任务：x-cron-token 头（CRON_SECRET 环境变量）
• 外部导入：/api/leads/public-submit 使用 CRM_API_TOKEN（Bearer Token）
• 企微免登：/api/wecom/auth + /api/auth/auto-login

核心 API 列表

关键响应格式

// GET /api/customers
{
  "customers": [...],
  "total": 510,
  "totalOrders": 783,
  "totalAmount": 1966355,
  "counts": { "active": 499, "lost": 11, "total": 510 },
  "tabCounts": {
    "active": 499, "lost": 11, "total": 510,
    "pending": 0, "rejected": 0, "approved": 13,
    "this_week": 0, "this_month": 0
  }
}

// 错误响应格式
{ "error": "无权访问", "status": 403 }
{ "error": "权限不足", "status": 403 }

💰 财务核算与提成规则

毛利率计算

提成阶梯

净利润公式

净利润 = 毛利 - 工资成本(底薪+绩效+提成) - 发货成本 - 均摊成本
净利率 = 净利润 / 回款 × 100%（分母是回款，不是收入）

返佣规则

• 结算周期：次月底结算上月 → 算 N 月返佣用 N-1 月发货成本
• 估算公式：新开发货成本 × 40%，续费 × 35%
• 实际录入：RebateAdjustment 表（year + month @@unique）
• 当月显示：按日实时更新；历史月用实际数据

支付金额校准

电子签标准定价：1200 元/年起。订单系统的 paymentAmount 按实际合同金额存储。

🕳️ 完整踩坑清单（46条）

以下是从2025年项目启动至今的所有技术踩坑记录，按类别整理。新智能体接手项目时务必通读！

部署相关

Prisma / SQLite

前后端

业务逻辑

🔗 外部集成与配置

企业微信

POI 企业抓取

百度 oCPC 回传

Token 已配置在服务器 .env 中。用于广告转化数据回传。

微信支付

已开通 AI 对话中代扣能力（AI 专属卡），用于 WorkBuddy 内的小额采购等场景。

电子签

• 官网：tencentesign.com（端口 3000）
• 客服电话：15399567093 / 13129911553
• 定价：1200 元/年起
• 合规红线：公开场合严禁低价引流，只能提"一站式对接服务"

🐛 已知问题 & 技术债务

🔴 严重

🟡 中等

🟢 技术债务 & 改进建议

👤 联系方式与工作方式

联系人

🔴🔴🔴 与老板合作的绝对铁律 🔴🔴🔴

计划 → [等老板说"开干"] → 写代码 → [审查代码，等老板说"继续"] 
→ 部署前检查(13项) → [出检查报告，等老板亲口说"部署"] → 执行部署

其他重要信息

• 员工拒绝：说话小心，涉及员工评价、绩效等时，不直接下结论。说"观察到...，您觉得呢?"
• 易学顾问：老板的八字是 乙亥 丙戌 甲申 辛未（1995-10-20 13:17），用神水木。会用八字做决策参考。需要时提供"命理大师"技能。
• 微信支付：已开通AI对话中代扣微信支付能力（AI专属卡），用于小额采购等场景
• 公司配置：企微已对接（OAuth免登）、已接入企业微信MCP

📎 附录：近期关键事件时间线