1. 为什么还要做一个 CRM：DeskcommCRM 的由来
1.1 从一张 Excel 表开始的真实需求
DeskcommCRM 这个名字，最初只是我随手起的内部代号，没想到最后真的长成了一套能用的客户管理系统。项目持续了大半年，起因不是老板拍板要数字化，而是我们团队自己先被一张《客户跟进总表》逼疯了。
当时的情况很典型：销售、交付、客服三个角色共用一张在线表格，谁都可以打开编辑，但没人知道上一版是谁改的、昨天那条跟进记录是不是最新。客户名在不同的同事嘴里有不同叫法，工商注册名、客户简称、备注里的英文名，经常是同一个人。更麻烦的是，不同人维护的列完全不一致，有的填了下次跟进时间，有的只写了"已联系"，数据根本没法统计。
我最初只是想找一个替代表格的工具，结果看了市面上一圈 CRM 之后发现，要么像销售易、Salesforce 那样功能重到需要专门配置顾问，要么像一些轻量工具一样只能管客户姓名和手机号，根本覆盖不了"一个客户从线索到交付，中间有几十次交互"这个场景。就是在这样一个"CRM 太重、Excel 太轻"的夹缝里，我决定自己动手，这成了 DeskcommCRM 立项的起点。
1.2 不是再造轮子，而是补上中间地带
有人问过我，为什么不咬牙买一套商业 CRM？说实话，预算倒不是最大问题，真正的问题是业务对象不够灵活。我们公司做的是跨境电商衍生服务，客户类型分平台卖家、独立站卖家和代运营需求方，每一类的资质字段都不一样。商业 CRM 的定制字段通常要升级到企业版才解锁，而且修改字段后，已有数据的清洗逻辑很别扭。再加上我们需要把客户跟进记录和内部项目进度打通，商业软件很难做到这种"半业务半协作"的深度定制。
所以 DeskcommCRM 的定位非常明确：面向 20 到 80 人的中小团队，以客户对象为底座，强调跟进留痕、权限划分和字段可配置。对比大型 CRM，它不追求销售自动化算法，不做复杂的工作流，只把"客户数据统一管理"这一件事做透。对比 Excel，它又保证了并发编辑的稳定性和权限的严谨性。项目启动前我花了两周画原型和梳理需求，最后只保留四张核心表，这个"减法"过程比开发本身还重要。
2. 需求收敛：第一版只做四件事
2.1 四个核心业务对象：客户、联系人、商机、订单
很多 CRM 项目死于"什么都要做"。我在需求阶段最常见的心理冲动就是：加上营销邮件功能、加上在线客服、加上销售预测报表。但冷静下来之后，我把第一版范围砍到了四个对象：
- 客户（Account）：企业级客户主体，是整个系统的根。
- 联系人（Contact）：客户公司里的具体沟通对象，一个客户下面挂多个联系人。
- 商机（Opportunity）：潜在的销售机会，关联客户和金额，带销售阶段。
- 订单（Order）：成交后的业务单据，关联商机和金额，有回款状态。
这四个对象形成了一个清晰的漏斗：客户 → 商机 → 订单。联系人则是客户下面的子资源，不单独进入漏斗。这个数据模型看起来简单，但保证了后面动态表单、看板、权限都能围绕同一个主键体系运转。第一版我甚至刻意没有做线索（Lead）表，因为线索本质上可以用"客户+状态=未成单"来表达，少一张表，查询和权限就少一层复杂度。
2.2 动态表单与字段自定义
需求阶段我访谈了销售和交付同事，大家提得最多的一个需求是："这个客户最好能记信用证条款、备案号、供应商等级。"这些字段，每个客户类型都不一样，预先写死在数据库表里显然不现实。
动态表单就成了第一版必须做的基础能力。思路是：字段定义不写死在代码里，而是存成元数据。每张业务表对应一个form_schema，它是一个 JSON 结构，描述了有哪些字段、字段类型、是否必填、下拉选项是什么。前端根据这个 schema 动态渲染表单，后端根据 schema 主动解析和校验数据。这样运营的同学在系统里新增一个字段，不需要改一行代码，后端也只需要读取配置再校验，不用为了新增字段出一次版本。
这个设计有一个隐含的好处：DeskcommCRM 的各个对象页面天然长得不一样，却共用同一套渲染引擎，后期的维护成本被压得很低。代价则是，查询和统计需要处理 JSON 字段的存储，这一点我在数据模型章节专门展开说。
2.3 时间线追踪：所有动作都留下痕迹
销售管理的核心不是数据本身，而是沟通的连续性。我见过很多同事跟客户聊了两个星期，然后因为换人交接，新接手的人完全不记得之前聊过什么，只能翻聊天记录和邮件。DeskcommCRM 里给每个客户和商机都设计了一个统一的时间线（Timeline），把电话沟通、微信记录摘要、邮件正文、线下拜访纪要和系统内的字段变更全部按时间顺序揉在一起。
实现上我采用了一张events事件表，event_type标记动作类型，payload用 JSONB 存具体内容。这样不管前端展示的是"张三更新了商机金额"还是"李四记录了一通电话"，都走同一条查询逻辑。第一版上线后，我发现使用率最高的功能就是时间线，因为省去了无数条"刚才那个客户聊到哪了"的群消息。
3. 技术选型背后的取舍
3.1 前后端技术栈：也踩过"全栈统一"的甜蜜陷阱
技术栈选择上，我给自己定的原则是：团队成员最熟什么用什么，不追新框架。当时我和另一个同事都是 TypeScript 的背景，所以前端干脆用 React + TypeScript + Antd，后端用 NestJS，数据库用 PostgreSQL + Prisma ORM。整套技术栈共享类型定义，从接口到实体都能生成类型，确实省了不少联调成本。
这里有一个想提醒大家的点：全栈 TypeScript 虽然统一，但容易在service 层和数据库类型复杂化时失控。刚开始我也天真地以为"前后端共用类型"能解决所有问题，实际上 Prisma 生成的类型和前端表单 schema 的灵活性天然冲突，动态字段在静态类型里根本没法表达。最后我采用了分层策略：基础领域对象用 Prisma 类型，动态字段对象全部走一个RecordValue接口，前端用 zod 做运行时校验，而不是依赖编译期类型。
3.2 为什么用 PostgreSQL 而不是 MySQL
如果只是存储常规的业务记录，MySQL 完全够用。但 DeskcommCRM 有动态表单和多租户两个硬需求，PostgreSQL 的JSONB 类型和行级安全（Row Level Security）就成了我们的最大底气。
动态字段数据可以存进一个record_values表，每行是一对record_id + field_key + value，也可以直接在业务表加几个 JSONB 列。我最终选了后者，理由是大部分客户的基本字段都是固定的，只有少部分扩展字段需要 JSONB，如果全部做 EAV，查询时要把几十行拼成一条记录，性能会很差。而 PostgreSQL 的 JSONB 可以直接建 GIN 索引，我做了一个"按客户名模糊搜索 + 按自定义字段匹配"的联合查询，线上百万级数据下依然能稳定在 50ms 以内。
3.3 多租户的实现：同一库，不做每个客户一套数据库
DeskcommCRM 一开始要服务多个团队，但我没有采用常见的"一租户一库"方案，而是在每个业务表上都加上tenant_id列，并且打开 PostgreSQL 的 RLS 约束。这样应用层查询时，只要保证SET app.current_tenant被正确设置，数据库层就会自动限制只能看到当前租户的数据，哪怕业务代码里漏写了where tenant_id = xxx，也不会造成被租户数据串读的事故。
RLS 的核心收益是权限下沉到数据库层，应用层代码因此非常干净。代价是连接池要小心处理会话级设置，每个请求都必须在一个事务里先set_config再执行业务查询。这个坑我们上线初期踩过，当时因为某条查询走了非事务连接，导致租户隔离失效，多亏压测时发现了。细节放在后面排查清单里讲。
4. 数据模型设计：两次重构踩过的坑
4.1 第一版：传统关联表设计的无力感
第一版我按照普通业务系统思维，设计了accounts、contacts、opportunities、orders四张独立的表，每张表都提前预留十几个字段：license_file、tax_id、industry_type、platform_type等等。当时想着"这个字段总会用上，先加上再说"。
结果不到两周就出问题了。销售组反馈需要记录"目标国家"，交付组需要记录"服务里程碑"，这些字段预告不到，我只能频繁改表。改一次表，Prisma 要生成一次 migration，上线还需要停服维护窗口。更麻烦的是，每个对象对应不同的自定义字段组合，传统关系型表的列越多，查询和展示的逻辑就越混乱。到第二次需求评审时，我已经意识到固定字段的 schema 完全走不通。
4.2 第二版：固定重要字段 + JSONB 扩展字段
第二次重构，我把表的模型改成了这样：
- 每个业务对象都保留全世界系统都需要的核心字段，例如名称、负责人、创建时间、更新时间、租户 ID；
- 其余业务扩展字段不再建列，而是全部放进一个
custom_fieldsJSONB 字段； - 字段的元数据描述，也就是字段名、显示名、类型、候选值，存到
form_schema对应的元数据表里。
这个方案的好处是，数据库的固定列可以保持很干净，而扩展字段的增删改查全部走同一套读取逻辑。举个例子，客户列表要显示"目标国家"这一列，前端从form_schema拿到这个字段的key是target_country，然后从每行记录的custom_fields.target_country取出值。新增一个字段，不需要改任何表结构，只需要往form_schema里插入一条记录，动态渲染就自动生效。
我们做查询的时候，还把最常用的几个自定义字段做了"冗余字段快照"：比如把platform_type单独抽成一个普通列，方便建索引。这样做属于工程妥协，用很小的一致性成本换取查询效率，我认为对于中小规模系统非常理智。
4.3 时间线的底层设计
事件表events是所有对象活动的"垃圾桶"。它包含actor_id（操作人）、tenant_id、resource_type（客户 / 联系人 / 商机 / 订单）、resource_id、event_type、payload、created_at。操作人更新商机金额，会记录一条opportunity.field_updated事件，payload 里存{field: "amount", from: "10000", to: "15000"}；记录一通电话，会记录一条activity.phone_call事件，payload 存通话摘要和时长。
这条表设计有一个很容易被忽略的细节：resource_type和resource_id必须建立联合索引，否则时间线的查询会在数据量变大后慢到不可接受。我们后来加了(tenant_id, resource_type, resource_id, created_at DESC)的复合索引，列表页才从十秒优化到几百毫秒。这个教训让我意识到，任何"看起来统一又多态"的表模型，都必须先想好索引策略。
5. 权限模型：角色、数据范围与字段级权限的简化方案
5.1 简单 RBAC 为什么不够用
一般的权限系统第一反应就是 RBAC，给用户分配角色，给角色分配权限。但落地到客户管理场景，光靠"菜单权限"远远不够。DeskcommCRM 必须回答三个问题：
- 张三能不能看到这个客户？
- 张三能不能编辑这个客户？
- 张三能不能看到这个客户的自定义字段"客户毛利"？
如果用 RBAC 硬做，只能做到菜单级别的"能进客户模块/不能进客户模块"，完全没有切到数据级。所以我的第一版权限模型直接跳过了传统 RBAC，选择"角色 + 数据范围规则 + 字段权限"三层。
5.2 数据范围规则：全员 / 部门 / 仅本人 / 参与人
数据范围我用了一个简单但务实的模型。每个用户有一个角色，每个角色带一组数据范围规则：
- 全部：可以看到所有租户内数据，通常给管理员和老板；
- 本部门：只能看自己所在部门的数据；
- 仅本人：只能看自己创建或负责人是自己的数据；
- 参与人：只要出现在一个商机的参与者列表里，就能看到该商机关联的客户。
这个规则的判定放在了 NestJS 的拦截器里，不散落在各个 controller 中。拦截器会解析当前用户的角色和数据范围，自动拼接到查询条件上。这样业务代码里写的都是"我要查所有商机"，实际执行时会被追加where条件，漏写法导致的越权基本被根治了。
5.3 字段级权限：不追求精细，但要能兜底
字段级权限我做了简化：只控制"可见性"和"可编辑性"。在form_schema里，每个字段除了类型和默认值，还会带一个permissions对象。比如{ "view": ["role_admin", "role_sales_manager"], "edit": ["role_admin"] }。前端拿到 schema 后会根据角色过滤可见字段，后端在解析 payload 时也会根据角色决定是否接受该字段的更新。
简化到这一步最大的价值是，它让"销售负责人能看到所有客户，但普通销售只能看自己的客户"这一类真实需求有了快捷配置入口。如果真要做到字段级动态脱敏、继承权限，复杂度会指数上升，对 40 人团队来说性价比太低。权限模型不是一个越精细越好的东西，够用且可逃离，才是关键。
6. 核心功能实现：动态表单、看板与自动化导入
6.1 动态表单渲染器的关键思路
动态表单的渲染器是 DeskcommCRM 使用体验的胜负手。我采用的方法是：将 JSON Schema 和 Antd Form 绑定。form_schema里描述了一个字段数组，每个字段包含name、label、component、props、options、rules。前端的动态表单组件遍历 schema，根据component字段动态渲染输入框、下拉选择、日期选择、自定义人员选择器等。
这个模式开发时比较顺利，真正坑人的是字段联动。比如选择了客户类型为"平台卖家"，需要联动展示"店铺链接"字段；选择了"独立站卖家"，要联动展示"域名"字段。我在form_schema里给字段加了一个visibleWhen声明式配置，前端渲染时统一解析，不把联动逻辑写死在各个业务组件里，也让运营同学可以通过配置引擎实现简单的"如果，那么"效果。
6.2 销售看板的拖拽更新
看板（Kanban）是销售最喜欢的视图，按商机阶段分列，卡片可以拖拽到下一个阶段。实现上，我用一列stage字段来保存商机的阶段，拖拽时前端将卡片从 A 列移到 B 列，同时乐观更新本地 UI，然后调用后端接口把stage改成 B。
这里的核心问题是并发冲突与权限校验。用户 A 看到商机在"谈判"阶段，拖到了"赢单"，同时用户 B 已经从"谈判"拖到了"丢失"，最后 A 的更新可能会覆盖 B 的数据。我的处理方案并不复杂：前端在拖拽请求里附带当前阶段的version字段，后端执行UPDATE ... SET stage = $new, version = version + 1 WHERE id = $id AND version = $old，影响行数为 0 就返回冲突错误，前端再提示用户刷新重试。这个乐观锁模式在多数管理后台里足够用，不必引入分布式锁。
6.3 Excel 导入的三个典型陷阱
客户管理系统的数据导入几乎避不开 Excel。我前后写了三版导入逻辑，才把各种编码问题、表头匹配问题和大批量性能问题收拾利落。
- 编码：很多用户上传的 Excel 是 GBK 或带 BOM 的 UTF-8，直接用
xlsx库解析偶尔会乱码。我统一在上传时读取Buffer并转换编码，再交给解析库。 - 表头匹配：不要假设 Excel 的列和系统字段一一对应，更不能假设用户的表头名称完全一致。我在导入向导里提供了字段映射页面，让用户手动把 Excel 列拖到系统字段上，并且记住历史映射。
- 大批量导入：一次性插入一万条数据会把事务拉长，还可能撑爆内存。我改成每 200 条一个批次，每个批次在事务里完成动态字段和关联关系的写入，失败写出错误日志，不阻塞后续批次。
这一模块上线后，我们销售团队从原来每周花一下午整理表格，变成了 5 分钟上传快速导入。工具类的价值就是如此，看起来不起眼，但能实打实解放人力。
7. 部署上线：Docker Compose、备份与线上问题清单
7.1 单机部署的核心配置
DeskcommCRM 的目标用户规模决定了我们不需要上 K8s，一台 4C8G 的小机器就能跑起来。部署形态我用 Docker Compose 编排了五个服务：postgres、api、web、nginx、redis。这里贴一段精简的 Compose 核心配置：
version: "3.9" services: postgres: image: postgres:15 restart: always environment: POSTGRES_DB: deskcomm POSTGRES_USER: deskcomm POSTGRES_PASSWORD: ${DB_PASSWORD} volumes: - pgdata:/var/lib/postgresql/data healthcheck: test: ["CMD-SHELL", "pg_isready -U deskcomm"] interval: 10s timeout: 5s retries: 5 api: build: ./server restart: always env_file: - .env.production depends_on: postgres: condition: service_healthy web: build: ./web restart: always nginx: image: nginx:1.25 restart: always volumes: - ./nginx.conf:/etc/nginx/conf.d/default.conf ports: - "${HTTP_PORT:-80}:80" depends_on: - api - web volumes: pgdata:启动命令没什么特别的，核心是数据卷pgdata必须持久化，否则容器一重启数据全丢。另外.env.production里的数据库密码和生产密钥，我用的是环境变量注入，而不是写死在代码里。很多自研系统最终倒在部署环节，往往不是功能问题，而是环境变量和密钥管理太随意。
7.2 备份恢复实操：只备份数据卷远远不够
很多人以为只要 Docker 挂了数据卷就万事大吉，真到恢复的时候会发现备份文件是坏的。DeskcommCRM 上线前我做了一次完整的恢复演练，之后把备份写成了每天凌晨 3 点执行的脚本，核心命令是这样的：
pg_dump -h postgres -U deskcomm deskcomm \ | gzip > /backups/deskcomm_$(date +%F).sql.gz恢复时只需要解压后执行psql -h postgres -U deskcomm deskcomm < backup.sql。但要注意的是，如果在事务里用了 RLS，恢复时不能直接切换搜索路径。我们的做法是先恢复到一个临时的普通表空间，确认数据完整后再通过一个迁移脚本把tenant_id和owner_id修正为当前租户状态。否则直接恢复后，应用层会因为 RLS 找不到租户而提示无权限。
备份这件事，我最大的心得只有一句：定期备份不如定期恢复演练。备份文件放在磁盘上没有任何价值，只有确认"能从零恢复到可运行状态"，才叫真正的备份。
7.3 上线初期的三个线上问题复盘
上线两周内，我们记录到了三个比较典型的问题，每一个都足够写一篇完整的排查报告。
第一个是列表页 N+1 查询。客户列表加载时需要展示最近一条跟进时间和负责人姓名，第一版代码里在循环里查联系人和事件表，一条列表请求发了上百条 SQL。用Prisma的日志插件看到慢查询后，我改用left join加子查询，把时间线的最新事件拉出来，列表接口从 8 秒降到 150 毫秒。
第二个是租户隔离失效的隐患。前文提到 RLS 需要每个事务设置app.current_tenant，某次压测发现，在错误处理分支里没有开启新事务，导致连接复用了之前请求的租户上下文，从而可能读到别的团队数据。修复很简单：在 NestJS 拦截器里强制在每个请求的开始就设置租户上下文，并且对没设置完成的事务直接抛异常而不是继续执行。
第三个是前端动态表单的缓存问题。后台修改了字段定义，前端因为本地缓存了旧的form_schema没有刷新，导致页面渲染时找不到字段配置直接白屏。后来我给 schema 查询加了一个updated_at版本号，前端在加载页面时每次比较版本，不一致就强制重新拉取，白屏问题才彻底消失。
这类线上问题通常不是单点逻辑错误，而是跨层、跨状态的拖泥带水。排查时最重要的是先看日志链路，而不是猜测和打补丁。
8. 现在怎么评价 DeskcommCRM：使用反馈与后续规划
8.1 团队从"抵制系统"到"离不开系统"
上线最初两周，团队里最大的声音是"又多了一个要填的表格"。当时我做了三件事改变了局面：把历史表格里的数据一次性导入，让销售不用重复录入；把看板做成默认首页，让每人打开系统第一眼就看到自己的待办商机；砍掉一切非必要的必填字段，能选填的绝不强制。
一个季度之后，系统里积累了接近四千条客户记录和一万两千条跟进事件，销售开始主动在晨会上打开 DeskcommCRM 的看板展示项目进展。那个阶段我意识到，客户管理系统能否落地，有时根本不取决于功能多少，而取决于与现有工作流之间的摩擦力有多大。每一次新增必填字段，都要扪心自问：这个字段带来的分析价值真的大于录入成本吗？
8.2 我学到的三句话
第一，不要为未来过度设计。最早规划的营销模块、报表模块、工单模块，一年过去了真正用得上的只有数据导出和基础漏斗统计。过度扩展第一版范围，只会让开发周期无限拉长，上线遥遥无期。
第二，权限要早做，但点到为止。租户隔离和数据显示范围一旦上线后再补，需要改动大量查询和接口；但字段级权限真的不需要一开始就做到复杂继承，否则光设计权限模型就要一个月。
第三，企业软件的关键是数据可迁移。我在每个对象都设计了"导出为 Excel"的能力，也会定期做完整数据库备份，因为这个世界上没有哪个软件能永远用下去，用户必须能够随时带着数据离开，这才是对用户最大的尊重。
8.3 后续准备做的三件事
DeskcommCRM 下一步，我会优先做三件事。一是把外部 API 完整开放出去，让客户方或者合作方可以按 token 读取订单状态，减少人工对接；二是做一个轻量级的自动化工作流，比如"商机进入赢单阶段后，自动创建订单提醒"，不用支持复杂的拖拽编排，只要能配置几个触发规则就好；三是离线版，让销售在高铁上没网的环境也能查看客户资料和跟进记录，有网络后再同步。
我一直觉得，一个内部工具最好的归宿，不是被关在公司的服务器里，而是能成为团队每天工作的自然延伸。DeskcommCRM 还有很长的路要走，但很庆幸当初没有在"要不要用商业软件"这个问题上纠结太久。如果你也在考虑给自己的团队做一个内部的客户管理工具，我的建议很简单：从最小闭环开始，先解决"客户资料不统一"和"跟进记录不可追溯"这两个痛点，其它的，等用完再迭代。
