做了这么多年业务系统，我有个越来越强的感受：一个产品只要出现"第二套入口"，就一定会出现"第二套逻辑"。这次的项目是 CRM，业务方一开始只要求做好 Web 端。等 Web 端跑顺了，又要加一个 AI 销售助手——也就是时下流行的 Agent。需求听起来很温和：帮销售查线索、建客户、推进商机、写跟进记录。但真动手之后我发现，如果照着"给 Agent 单独开接口"的思路做，大概率会做出一套和 Web 行为不一致的"伪 CRM"。这套逻辑不共用，Agent 就是颗定时炸弹——它今天帮你把商机阶段改错了，你还以为是业务规则变了。
这篇文章记录我用 Lume 重写一整套 CRM 的过程，核心就一句话：Web 和 Agent 必须共用同一套业务逻辑。我会把从领域模型、用例设计，到扫码采集、PDF 打印、Agent 工具接入、最终部署的完整链路都过一遍，适合正在做企业级 Web 开发、又准备给系统加 Agent 能力的朋友参考。
1. 为什么"共用业务逻辑"不是洁癖，而是成本问题
1.1 两套逻辑的教训：商机阶段是怎么被打乱的
先讲个反例。我们最初的 CRM 只有 Web 端，商机阶段流转规则写在页面按钮和接口里：从"初步沟通"到"需求确认"要有金额预估，从"方案报价"到"商务谈判"要先有报价单。后来加 Agent 的时候，为了图快，我让 Agent 直接调用一个"更新商机字段"的通用接口。结果就是：Agent 可以把一个商机从"初步沟通"直接改成"成交"，原因是通用接口只做 UPDATE，不校验状态流转。
这种问题不是偶发，而是必然。Web 端是给人用的，人的操作习惯会"天然"遵守流程；Agent 是按指令执行的，你让它"把这条商机标为成交"，它真的会直接改字段，才不会管你前面还有几步。等发现问题的时候，数据已经脏了，销售开始质疑系统。后来我把所有状态流转收敛到一个 moveOpportunityStage 函数里，Web 和 Agent 都只能走这个函数，问题才算根治。这件事让我彻底明白：凡是"规则"——状态流转、权限、必填字段、重复客户判断——必须只有一份实现，Web 和 Agent 只是两种"出入口"，不是两套"大脑"。
1.2 业务逻辑层应该长什么样：领域、用例、接口各管一摊
先说清楚，市面上叫 Lume 的不止一个，有做静态站点的，也有做数据工作台的；我这里用的是那个把领域逻辑和接口形态解耦的全栈框架。它最大的特点，是让我可以只写一遍业务逻辑，然后把它暴露成 HTTP 路由给 Web，暴露成工具调用给 Agent。
具体拆成三层：
- 领域层（domain）：实体定义、状态机、业务规则，零外部依赖，谁都不能绕过；
- 用例层（use-cases）：每一个业务动作对应一个纯函数，比如"创建线索""推进商机""记录跟进"，输入输出都是普通数据；
- 接口层（web / agent）：只负责把请求翻译成用例调用，不写任何业务规则。
这套结构的收益，最直观的体现是：Web 端加一个表单字段，Agent 端的工具参数描述自动跟着变；Agent 端加强一个校验，Web 端提交时也会被同一道闸门拦住。你不需要维护两份文档，更不需要担心两边的规则慢慢走样。
1.3 目录结构和关键技术决策
目录我这样组织：
crm/ domain/ # 实体、状态机、规则，零依赖 use-cases/ # 业务用例函数 storage/ # 数据访问实现（PostgreSQL、Redis） shared/ # 输入输出 schema、错误码、审计接口 web/ # HTTP 路由与页面渲染 agent/ # Agent 工具注册与对话流程技术决策也列成一张表，方便你对照：
| 横切面 | Web 形态 | Agent 形态 | 共用部分 |
|---|---|---|---|
| 参数校验 | 表单提交时调用 | 工具参数解析时调用 | 用例层的 zod schema |
| 权限判断 | 会话拦截器 | 工具执行前上下文检查 | 用例内的 assertCan |
| 状态流转 | 页面按钮按规则禁用 | 工具描述只展示合法流转 | domain 里的状态表 |
| 操作审计 | 写入操作日志 | 写入带 bot 标识的日志 | 同一个 audit 接口 |
数据库我用的 PostgreSQL，缓存用 Redis，部署用 Docker Compose。这个组合不算新潮，但在"小团队 + 要存客户数据 + 要跑 Agent"的场景下是最不容易翻车的。
2. 先把地基打好：实体、用例、存储三件套
2.1 五个核心实体：从线索到合同一条链
CRM 的领域模型不需要一开始就追求大而全。我总结下来，小团队真正跑得转的，五个实体就够：客户、线索、商机、跟进记录、合同。
| 实体 | 关键字段 | 作用 |
|---|---|---|
| Customer 客户 | 名称、行业、规模、联系人、地址、来源渠道、归属销售 | 一切业务的主体 |
| Lead 线索 | 来源、联系方式、原始备注、跟进状态 | 销售漏斗的入口 |
| Opportunity 商机 | 关联客户、金额、预计成交日期、阶段、赢单率、丢单原因 | 漏斗的中段 |
| Activity 跟进记录 | 类型、内容、下次跟进时间 | 复盘的原始材料 |
| Contract 合同 | 关联商机、金额、签署日期、状态 | 成交的终点 |
线索和客户分开，很多人不理解。实际业务里，一条线索可能还没验证过，直接建客户会把数据搞脏。所以我的规则是：线索经确认后可以"转化"为客户，转化动作本身也是一个用例，要校验必填字段和重复性。
domain 的实体定义长这样（简化版）：
// domain/entities.ts export type LeadSource = 'scan_qr' | 'website' | 'referral' | 'manual'; export interface Lead { id: string; companyName: string; contactName?: string; contactPhone?: string; source: LeadSource; rawNote?: string; status: 'new' | 'following' | 'converted' | 'invalid'; ownerId?: string; createdAt: Date; }2.2 用例函数：Web 和 Agent 共同调用的"那一个函数"
用例层是整篇文章的主角。拿"创建线索"举例，这个函数既被 Web 的 H5 表单调用，也被 Agent 的 create_lead 工具调用：
// use-cases/create-lead.ts import { z } from 'zod'; export const CreateLeadInput = z.object({ companyName: z.string().min(2), contactName: z.string().optional(), contactPhone: z.string().regex(/^1\d{10}$/).optional(), source: z.enum(['scan_qr', 'website', 'referral', 'manual']), rawNote: z.string().optional(), }); export async function createLead( ctx: CrmContext, input: z.infer<typeof CreateLeadInput>, ): Promise<Lead> { // 重复客户检查：同一公司名 + 同一电话视为重复 const dup = await ctx.repos.lead.findDuplicate(input.companyName, input.contactPhone); if (dup) throw new CrmError('DUPLICATE_LEAD', '已存在相同客户线索'); const lead = await ctx.repos.lead.insert({ ...input, status: 'new', createdAt: new Date(), }); await ctx.audit.log(ctx.actor, 'create_lead', lead.id); return lead; }这个函数有四个特点，缺一不可：
- 输入用 zod schema 声明，Web 表单和 Agent 工具参数共用这同一个 schema；
- 业务校验（重复客户）放在函数内部，不依赖调用方自觉；
- 审计在用例里做，不管谁调用都会留痕；
- 返回值是纯数据，Web 拿去做页面渲染，Agent 拿去做对话回复。
这样设计之后，新增业务规则时我只需要改一个函数，Web 和 Agent 的行为同时更新，测试也只需要写一份。
2.3 存储层：事务和并发是最容易被 Agent 引爆的雷
存储层我用仓库模式（Repository）把 SQL 隔离起来。注意，事务不能只包在 Web 接口里，Agent 调用同样要包。我踩过的坑是：Agent 连续快速触发多个动作，比如"先创建商机再关联合同"，如果两个动作不在一个事务里，中间崩溃就会出现孤儿数据。
另一个必须处理的是并发。Agent 和 Web 可能同时对同一个商机做操作，我用乐观锁解决：商机上有一个 version 字段，更新时校验 version，不匹配就抛 CONFLICT 错误。别小看这件事，Agent 并发的概率比人多得多，它跑多个任务时是真正的并行。
仓库层示例：
// storage/opportunity-repo.ts export async function updateOpportunity( db: Db, id: string, expectedVersion: number, patch: Partial<Opportunity>, ): Promise<Opportunity> { const rows = await db.query( `UPDATE opportunities SET ..., version = version + 1 WHERE id = $1 AND version = $2 RETURNING *`, [id, expectedVersion], ); if (!rows.length) throw new CrmError('CONFLICT', '数据已被其他操作修改，请刷新后重试'); return rows[0]; }3. 状态机和权限：最容易出现"两套逻辑"的战场
3.1 商机状态流转，定义成一张表而不是一堆 if
商机的阶段流转是 CRM 的灵魂。我是这么定义流转表的：
// domain/opportunity-flow.ts export const OPPORTUNITY_FLOW = { new: { to: ['qualifying'], require: ['expectedAmount'] }, qualifying: { to: ['proposal', 'lost'], require: ['solutionBrief'] }, proposal: { to: ['negotiation', 'lost'], require: ['quoteAmount'] }, negotiation: { to: ['won', 'lost'], require: [] }, won: { to: [] }, lost: { to: ['qualifying'], require: ['lostReason'] }, } as const;规则解释一下：
- 从 new 到 qualifying 必须填预计金额；
- 从 qualifying 到 proposal 必须补方案简述；
- 进入 negotiation 必须有报价金额；
- 转 lost 必须填丢单原因；转 won 必须有关联合同。
这个表的价值，在于它同时驱动了 Web 端和 Agent 端。Web 端页面上的"推进商机"按钮，向后端要的可选目标阶段列表，就是这张表算出来的；Agent 端的 move_opportunity_stage 工具描述里写的合法流转，也是从这张表生成的。你改一处规则，两端同时生效，不存在"Web 允许但 Agent 不允许"的割裂。
3.2 权限模型必须下沉到用例，而不是页面按钮
CRM 的权限如果不做对，销售会觉得系统在跟他作对。我的权限模型分两层：角色层是管理员、销售主管、销售、只读；数据层默认只看自己名下的数据，销售主管可看本组，管理员看全部。
重点是，权限判断必须写在用例层，不是写在页面路由或按钮上。原因有两个：一是页面可能漏写判断，二是 Agent 可能绕过页面。Agent 调用工具之前会注入"用户身份 + 角色"，然后用例层统一做检查：
// use-cases/permissions.ts function assertCan(ctx: CrmContext, action: string, record?: { ownerId?: string }) { if (ctx.actor.role === 'admin') return; if (ctx.actor.role === 'viewer') { throw new CrmError('FORBIDDEN', '只读账号不能执行此操作'); } if (record?.ownerId && record.ownerId !== ctx.actor.id && ctx.actor.role !== 'sales_manager') { throw new CrmError('FORBIDDEN', '只能操作自己名下的数据'); } }我把这个函数放在所有写操作的用例开头。页面按钮可能因为 bug 漏了判断，但用例层是最后一道闸门。Agent 比人更危险的地方在于，它会尝试各种越权路径，所以这层防护必须在业务逻辑里，而不是在某个中间件里。
3.3 审计日志：Agent 做的每一件事都要能翻旧账
说完权限说审计。审计日志在纯 Web 系统里是锦上添花，但有 Agent 之后就是必需品。因为 Agent 的操作是自动化的，出问题时销售一定会问"谁改的、什么时候改的、为什么改"。
我的审计记录里除了常规字段，还带了 actor_type（user/bot）、conversation_id（哪次对话触发的）、tool_call_id（工具调用的唯一 ID）。这样排查的时候，能把一次 Agent 误操作精确定位到某一轮对话。
实现上，审计不放在 controller 里，全部在用例函数里调用 ctx.audit.log。这样无论请求来自哪个入口，都会留痕。实测下来，这条对团队信任度帮助很大，销售看到 AI 操作也有记录，才敢放手用。
4. Web 端实战：扫码采集、PDF 打印、一键取号这些细节
4.1 Web 层只做翻译，不写规则
Web 端的路由处理函数我是这么写的：
// web/routes/leads.ts router.post('/leads', async (req) => { const input = CreateLeadInput.parse(await req.json()); const lead = await createLead(buildContext(req), input); return json({ ok: true, data: lead }, 201); });这段代码没有任何业务规则：参数解析交给 zod，业务逻辑交给 createLead，身份解析交给 buildContext。Web 端因此变得特别"薄"，改规则时基本不会动到路由层。这也让前端同学可以放心折腾 UI 而不用担心弄坏业务逻辑。
4.2 扫码采集：把展会获客变成"扫一下"的事
"CRM 管理系统结合扫码采集"是我这次做的重点功能。场景是展会现场：客户走到展位，扫一个二维码，打开 H5 页面，手机号自动带出（见 4.4），填个公司名提交，一条来源为 scan_qr 的线索就进了销售漏斗。这里的核心不是 H5 页面本身，而是它最终调用的同样是 createLead 这个用例函数，所以来源字段、重复检查、权限、审计一条龙都是现成的。
如果是老客户来访，扫码后可以直接关联到已有客户，快速创建一条"现场拜访"跟进记录。这里我加了一个识别逻辑：扫的是人还是物料。展位二维码对应"新增线索"，产品包装上的二维码对应"商品资料 + 添加到商机"。开发成本不高，但对销售体验提升非常大，客户不用手填一堆资料，销售也不用手动录单。
4.3 报价单 PDF 打印：浏览器打印和批量生成两条腿走
"web 页面 pdf 打印"这个需求，我一开始走了弯路——想用服务端生成 PDF，结果光调模板就折腾了两天。后来改成双轨方案：
- 单张报价：打开一个专用的打印视图，用专门的 print 样式，用户直接打印或另存为 PDF。优点是零依赖、改模板快；
- 批量报价/合同归档：走服务端渲染，把 HTML 转成 PDF 再存对象存储。
两条路拿到的数据都来自同一个 getQuoteData 用例，保证页面看到的金额和 PDF 里的金额永远是同一份数据。这个一致性，比"用哪个库生成 PDF"重要得多。销售最怕的就是页面上报 30 万，打印出来是 28 万。
4.4 一键获取手机号：正确姿势是"先用例后回填"
一键获取手机号是移动端 CRM 的刚需，尤其在扫码采集场景里。流程是这样的：前端调用运营商一键登录 SDK 拿到一次性 token，后端拿 token 去换真实手机号，然后把它传给用例层去更新联系人。
这里有个细节：换到的手机号属于敏感信息，协议上要求不能直接写进日志，也不能默认塞进 Agent 上下文。我做的处理是：手机号只存数据库加密字段，用例层返回给 Agent 的是脱敏版本（比如 138****1234）。Agent 如果需要完整号码，必须走单独的授权动作。一键取号和扫码采集经常组合使用：扫码后第一次进入的小型展会场景，如果能拿到手机号，直接预填表单，转化率提升非常明显。
4.5 列表和看板：Web 和 Agent 看到同一批数字
CRM 总得有统计看板。我没有单独给 Agent 做一套统计接口，而是把常用的查询都做成了用例，比如"本月新增线索数""我的商机总额""本周待跟进"。Web 看板展示这些用例的返回，Agent 也通过同名工具查同样的数据。
这保证了一个效果：销售问 Agent"我这个月开了多少商机"，和他在 Web 上看板看到的数字完全一致。数字不一致是团队信任最快的杀手，这一点必须从架构上杜绝。哪怕多花一点时间把查询逻辑抽象成用例，也是值得的。
5. Agent 接入：把用例变成工具的完整链路
5.1 一个用例自动变成一个 Agent 工具
Agent 端最爽的一刻，是把 createLead 变成 create_lead 工具。因为输入输出 schema 已经在用例层定义好了，工具注册只需要一层薄薄的声明：
// agent/tools.ts export const createLeadTool = { name: 'create_lead', description: '创建一条新的销售线索。来源包括 scan_qr（扫码）、website（官网）、referral（转介绍）、manual（手动录入）。', inputSchema: CreateLeadInput, async run(ctx, args) { return createLead(buildBotContext(ctx), args); }, };Agent 运行时从 inputSchema 拿到字段和类型，自然就知道该让大模型填哪些参数。校验错误也是统一的：大模型收到 DUPLICATE_LEAD 错误后，会自动向用户转述"已经有相同线索了"。你不需要为 Agent 单独写任何业务校验。
Agent 运行时本身用什么语言无所谓——社区里有人用 Rust 写 agent 运行时也没问题，这一层只要遵循 schema，和语言无关。重要的是，工具的参数描述里我会额外写一句"何时不该调用"，比如 listOpportunities 的描述里会注明"仅在用户询问商机列表或汇总时调用，不要主动批量调用"，这能明显减少大模型的无效工具调用。
5.2 Agent 记忆：会话记忆和业务记忆必须分开
"agent 记忆"这块，我把记忆分成两层：
- 会话记忆：存最近几轮对话，放 Redis，设置过期时间。它解决的是"刚才说到哪了"；
- 业务记忆：跟进记录、客户偏好、下次跟进时间，这些来自 Activity 仓库，是 CRM 的持久化数据。
之前有个教训：Agent 回答"上周跟 A 客户约了什么时间"时，居然从聊天缓存里翻。缓存一过期就答不上来。后来我把所有需要持久的事实都做成工具查询，Agent 不能再直接读聊天记忆来回答业务问题。会话记忆只负责对话连贯，业务记忆只认用例层的数据。这样即使 Agent 重启、Redis 清空，客户信息也不会丢。
5.3 Agent 安全边界：工具权限不能超过 Web
Agent 的权限必须满足一个铁律：Agent 能做的，不能超过当前用户能做的。落实到实现上：
- Agent 对话创建时绑定用户身份，后续所有工具调用都是"以该用户身份执行"；
- 危险操作（删除、标记流失、改大金额）必须二次确认：工具先返回 confirm_request，Agent 转问用户，用户确认后 Agent 再调用实际用例；
- 对 Agent 的接口增加频控，防止它在多轮循环里反复调用同一个工具造成浪费或破坏。
这点不做好，Agent 就是一个"没有准星的自动攻击器"。我在测试阶段遇到过 Agent 把一批商机全部标成 lost 的操作，幸好用例层的权限和确认机制拦住了。所以"agent 安全"不是上线前才考虑的选项，而是架构的一部分。
5.4 一个实测对话例子
放一段实测对话，你感受一下共用逻辑的效果：
用户：帮我把 A 公司推进到方案报价阶段。
Agent（调用 moveOpportunityStage）：抱歉，A 公司的商机还缺"方案简述"，无法从需求确认阶段推进到方案报价。麻烦先补充方案简述。
用户：补好了，再试一次。
Agent（再次调用 moveOpportunityStage）：已推进到方案报价阶段，当前报价金额 30 万，逾期提醒已设置。
用户：我名下现在有多少个有效商机？
Agent（调用 listOpportunities）：您名下有 12 个有效商机，合计金额约 360 万，其中 3 个处于商务谈判阶段。
注意第二轮的报错：这不是聊天话术，是用例层真实抛出的 REQUIRED_FIELD 错误被 Agent 转述。Web 端提交同样会得到这个错误。这就是"一套逻辑"最直观的体验。
6. 部署与运维：让 CRM 真正"永久在线"
6.1 部署方式：免费托管我劝你慎重
很多人搜"永久在线的 crm 网站"和"免费 web 服务器网站"，我的观点很直接：免费托管适合 Demo，不适合承载一个团队的真实客户数据。原因很简单，免费方案通常不承诺数据持久性和可用性，哪天服务关了，你的客户数据跟着没。
我的选择是一台低配云主机，1 核 2G 就够小团队跑了，用 Docker Compose 一键起四个服务：Lume 应用、PostgreSQL、Redis、Nginx。再加上每天凌晨自动备份数据库到对象存储，保留 30 天。要做到"永久在线"，本质是四件事：进程守护（崩溃自动重启）、外网可达、数据备份、监控告警。四件事缺一件，"永久"都是空话。
6.2 Linux 缓存与性能：Nginx 层能挡掉的别让应用扛
性能优化的优先级我是这样排的：先静态资源，再热点查询，最后才考虑加机器。Nginx 配 proxy_cache 缓存静态资源；Redis 缓存两类热点数据：看板统计（分钟级失效）和客户搜索联想（模糊搜索词条）。商机明细这类频繁更新的数据不缓存，避免销售看到旧数据。
数据库层面，重点关注几个大表的慢查询，记得给 opportunities(owner_id, status)、activities(opportunity_id) 建组合索引。别一上来就上读写分离，小团队没那么大压力，复杂度才是主要敌人。这套组合跑下来，日常请求的 P99 基本都在 200ms 以内，销售体感是"快"。
6.3 Web 服务器安全：Agent 接口也要当正式接口保护
安全这一节，我给一个可以直接照抄的清单：
- HTTPS 全站开启，HTTP 自动跳转；
- 防火墙只放行 80/443，SSH 仅允许密钥登录；
- 安装 fail2ban 拦截爆破；
- 应用层做登录限流和验证码；
- 定期做备份恢复演练，别等数据丢了才发现备份是坏的；
- Agent 的对话接口同样必须走鉴权，不能因为是"内部工具"就裸奔。
最后一条特别提醒：很多人觉得 Agent 接口不是公开页面，随便加个 token 就行。实际上 Agent 接口能操作 CRM 数据，等于半个管理员入口，防护级别必须和 Web 接口一致，甚至更高。我在项目里给 Agent 接口单独做了 IP 白名单 + 短时 token 双保险，宁可麻烦一点，也不能留裸奔的洞。
7. 复盘：这次重写我学到的东西
7.1 三个让我少走弯路的决定
最值的投资，是把所有业务规则收敛到用例层。做完之后，新增一个"线索转客户"的功能，Web 和 Agent 都不需要分别开发，只要新增一个用例函数，再各加一层薄薄的接入即可。如果重来一次，我会把错误码体系设计得更早。现在 CrmError 的错误码是业务推进过程中陆续加的，有些提示语不够友好，Agent 转述时差点意思。建议一开始就规定：错误码即业务语义，提示语可以面向最终用户。
另一个经验是：给用例层写测试的性价比极高。因为 Web 和 Agent 都依赖它，一个用例的测试等于同时守护了两条链路。我后来把核心用例（状态机流转、权限、重复检查）的测试覆盖率补到了 90% 以上，明显感觉无论是改规则还是加新入口，底气都足了很多。
第三个决定是坚持用"一张流转表"管理商机状态，而不是散落的 if。后来销售提出要加一个"暂停跟进"阶段，我只改了 domain 里的一张表，Web 按钮和 Agent 工具描述当天就同步生效，这放在以前是想都不敢想的。
7.2 如果只留一条经验
如果只让我留一条经验给别人，那就是这句话：Web 是脸，Agent 是嘴，业务逻辑才是那个大脑。凡是发现两处行为不一致，先怀疑业务逻辑是不是真的只有一份。架构上偷的懒，最后都会变成数据修复会上流的汗。希望这篇记录能帮你少走一点弯路。
