localCRM — 本地贷款CRM系统

纯本地运行的贷款客户管理系统，覆盖客户全生命周期：获客 → 画像构建 → 贷款申请 → 审批/放款/拒绝 → 贷后维护。兼具 Web 界面和 CLI 命令行操作。

技术栈

层级	技术
后端	Python 3 + Flask
数据库	SQLite（WAL 模式，16 张表）
前端	Tailwind CSS + Alpine.js + HTMX（CDN，无需构建）
CLI	Python Click
加密	pycryptodome（AES-256）
意向分析	由当前智能体（DS/Claude）完成，CLI 不接入内置大模型

快速开始

# 1. 进入项目目录
cd localCRM

# 2. 创建并激活虚拟环境
python3 -m venv venv
source venv/bin/activate

# 3. 安装 localCRM（自动安装全部依赖）
pip install -e .

# 4. 初始化数据库（首次运行自动执行，也可手动）
localcrm init-db

# 5. 启动 Web 服务（后台守护进程）
localcrm server start
# 前台调试用: localcrm server
# 访问 http://localhost:5000

# 6. CLI 命令
localcrm --help

可选依赖（按需安装）：

pip install -e ".[excel]"              # Excel 导入支持 (openpyxl)

项目结构

localCRM/                              # 项目根目录（代码，Git 管理）
├── web/                               # Flask Web 应用
│   ├── app.py                     # 入口，注册 13 个 Blueprint
│   ├── config.py                  # 配置管理（从 ~/.localcrm/.env 读取）
│   ├── database.py                # 数据库连接 + 建表 DDL + 种子数据
│   ├── models.py                  # 数据模型层（16 个 Model 类）
│   ├── auto_service.py            # 自动打标签/标记逾期服务
│   ├── routes/                    # 路由模块
│   │   ├── main.py                # 首页仪表盘
│   │   ├── customers.py           # 客户 CRUD + 标签 + 画像
│   │   ├── tags.py                # 标签管理
│   │   ├── communications.py      # 沟通记录
│   │   ├── applications.py        # 贷款申请 + 阶段流转
│   │   ├── followups.py           # 回访管理
│   │   ├── documents.py           # 文档上传 + 加密
│   │   ├── products.py            # 产品管理 + 客户匹配
│   │   ├── industries.py          # 行业知识库
│   │   ├── company_sync.py        # 公司系统对接
│   │   ├── stats.py               # 统计分析看板
│   │   └── settings.py            # 系统设置
│   └── templates/                 # 22 个 HTML 模板
├── cli/                           # CLI 命令行工具
│   ├── main.py                    # CLI 入口
│   ├── customer_commands.py       # 客户管理命令
│   ├── communication_commands.py  # 沟通记录 + 回访管理命令
│   ├── application_commands.py    # 贷款申请管理命令
│   ├── tag_commands.py            # 标签 CRUD 命令
│   ├── product_commands.py        # 产品管理 + 匹配命令
│   ├── stats_commands.py          # 统计分析 + 预判命令
│   ├── writeback_commands.py      # 外呼命令组（outbound）
│   └── utils.py                   # 格式化输出工具
├── actions/                       # 外呼动作层（名单为核心资产）
│   ├── prepare_list.py            # 名单筛选
│   ├── call.py / status.py / asr.py / record.py / daylimit.py
│   └── tel_cli.py                 # aicall CLI 统一调用
├── scripts/                       # 独立脚本
│   ├── init_db.py                 # 数据库初始化
│   ├── match_products.py          # 产品匹配引擎
│   ├── rejection_predict.py       # 拒绝预判引擎
│   ├── backup.py                  # 数据库备份/恢复
│   └── import_adapter.py          # 批量导入（Excel/CSV/JSON）
├── CLAUDE.md                       # AI 操作指南
├── REQUIREMENTS.md                 # 详细需求文档
└── README.md                       # 本文档

~/.localcrm/                       # 用户数据目录（运行时数据，不提交 Git）
├── .env                            # 环境变量（加密密钥等）
├── data/crm.db                     # SQLite 数据库
├── customers/                      # 客户文档目录
└── backups/                        # 数据库备份

---

CLI 命令详解

CLI 入口为 localcrm，共 12 个命令组，覆盖 Web 端全部功能。

客户管理 (customer)

列出客户

localcrm customer list [选项]

选项	说明	示例
--stage	按客户阶段筛选	--stage 有意向
--source	按来源渠道筛选	--source 陌拜
--search	搜索姓名/手机/公司	--search 张三
--tag	按标签名筛选（可多次指定）	--tag 可入公司
--industry-id	按行业ID筛选	--industry-id 1
--sort-by	排序字段：created_at/updated_at/name/avatar_stage	--sort-by updated_at
--sort-dir	排序方向：asc/desc（默认desc）	--sort-dir asc
--deleted	显示已删除客户（回收站）	--deleted
--page	页码（默认1）	--page 2
--per-page	每页数量（默认20）	--per-page 50

查看客户详情

localcrm customer show <客户ID>

搜索客户

localcrm customer search <关键词>

新增客户（交互式）

localcrm customer add [选项]

选项	说明	默认值
--name	客户姓名	交互输入
--phone	手机号	交互输入
--wechat	微信号	空
--wechat-nickname	微信昵称	空
--company	公司名称	空
--position	职位	空
--industry-id	行业ID	空
--region	地区	空
--source	来源渠道	其他
--court-executor	法院被执行人 0=未知 1=否 2=是	0
--court-records	涉诉信息	空
--qichacha-data	企查查数据	空

快速新增客户

localcrm customer quickadd <姓名> <手机号>

编辑客户

localcrm customer edit <客户ID> [选项]

选项	说明
--name	姓名
--phone	手机号
--wechat	微信号
--wechat-nickname	微信昵称
--company	公司名称
--position	职位
--industry-id	行业ID
--region	地区
--source	来源渠道
--stage	客户阶段
--court-executor	法院被执行人
--court-records	涉诉信息
--qichacha-data	企查查数据

删除 / 恢复客户

localcrm customer delete <客户ID> [--yes]     # 软删除
localcrm customer restore <客户ID>             # 恢复已删除客户

客户画像管理

localcrm customer profile <客户ID>                          # 查看客户画像
localcrm customer profile-edit <客户ID> [选项]               # 编辑客户画像

画像字段选项：

选项	说明
--loan-willingness	贷款意愿
--expected-amount-min	期望金额下限(万)
--expected-amount-max	期望金额上限(万)
--expected-rate	期望利率
--rate-sensitivity	利率敏感度 高/中/低
--urgency	紧急程度 高/中/低
--loan-purpose	资金用途
--income-range	收入范围
--has-house	房产 0=未知 1=无 2=有
--has-car	车辆 0=未知 1=无 2=有
--asset-summary	资产摘要
--credit-score	征信等级
--credit-query-count	征信查询次数
--credit-overdue	逾期 0=未知 1=无 2=有
--credit-detail	征信详情
--communication-style	沟通风格
--is-decision-maker	是否决策人 0=未知 1=否 2=是

标签操作

localcrm customer tag <客户ID> <标签名>          # 给客户打标签
localcrm customer untag <客户ID> <标签名>        # 移除客户标签
localcrm customer set-tags <客户ID> <标签名...>  # 批量设置标签（覆盖已有）
localcrm customer list-tags                     # 列出所有标签（按分类分组）

沟通记录 (comm)

localcrm comm add <客户ID> [选项]          # 新增沟通记录
localcrm comm list [选项]                  # 列出沟通记录
localcrm comm show <记录ID>                # 查看沟通详情

选项 (add)	说明
--type	沟通方式：电话/微信/面谈/短信（默认电话）
--direction	沟通方向：主动联系/客户主动（默认主动联系）
--duration	通话时长(分钟)
--summary	沟通摘要
--mood	客户情绪：积极/中性/消极
--next-contact-at	下次联系时间 (YYYY-MM-DD HH:MM)

选项 (list)	说明
--customer-id	按客户ID筛选
--days	最近N天的记录
--limit	返回条数（默认20）

localcrm comm add 1 --type 电话 --direction 主动联系 --duration 5 --summary "客户有贷款意愿" --mood 积极
localcrm comm list --days 7
localcrm comm list --customer-id 1 --limit 10
localcrm comm show 3

回访管理 (followup)

localcrm followup add <客户ID> --planned-at <时间> [选项]   # 新增回访计划
localcrm followup list [选项]                               # 列出回访计划
localcrm followup show <回访ID>                             # 查看回访详情
localcrm followup complete <回访ID> [选项]                  # 完成回访
localcrm followup cancel <回访ID> [--yes]                   # 取消回访

选项 (list)	说明
--customer-id	按客户ID筛选
--overdue	只看逾期未回访
--today	只看今天待回访
--upcoming	未来N天待回访
--days	最近N天回访记录

选项 (complete)	说明
--result	回访结果摘要
--next-plan	后续计划内容
--next-planned-at	下次跟进时间 (YYYY-MM-DD HH:MM)
--next-purpose	下次跟进目的

localcrm followup add 1 --planned-at "2026-05-10 14:00" --method 电话 --purpose "跟进贷款意向"
localcrm followup list --today
localcrm followup list --overdue
localcrm followup list --upcoming 3
localcrm followup complete 2 --result "客户同意申请" --next-planned-at "2026-05-15 10:00" --next-purpose "收集资料"
localcrm followup cancel 3 --yes

贷款申请 (app)

localcrm app create <客户ID> [选项]                    # 创建贷款申请
localcrm app list [选项]                               # 列出贷款申请
localcrm app show <申请ID>                             # 查看申请详情（含阶段流转日志）
localcrm app edit <申请ID> [选项]                      # 编辑申请
localcrm app advance <申请ID> --to-stage <阶段> [--note 说明]  # 推进阶段
localcrm app reject <申请ID> --rejection-id <原因ID> [选项]    # 拒绝申请
localcrm app disburse <申请ID>                         # 标记放款
localcrm app rejection-reasons [--category 分类]       # 列出拒绝原因

贷款申请阶段：意向确认 → 资料收集 → 资料审核 → 提交审批 → 审批中 → 审批结果 → 签约 → 放款

localcrm app create 1 --amount 50 --rate 3.6 --term-months 12
localcrm app list --stage 资料收集
localcrm app list --result 进行中
localcrm app show 1
localcrm app advance 1 --to-stage 资料收集 --note "已收到征信报告和流水"
localcrm app reject 2 --rejection-id 1 --fail-stage 资料收集 --fail-detail "征信查询过多"
localcrm app disburse 3
localcrm app rejection-reasons
localcrm app rejection-reasons --category 征信

标签管理 (tag)

localcrm tag list                                            # 列出所有标签
localcrm tag create --name <名称> --category <分类> [选项]    # 创建标签
localcrm tag edit <标签ID> [选项]                             # 编辑标签
localcrm tag delete <标签ID> [--yes]                          # 删除标签

localcrm tag create --name "VIP客户" --category "行为" --color "#8B5CF6" --description "放款金额大于100万的客户"
localcrm tag edit 1 --color "#DC2626"
localcrm tag delete 1 --yes

产品管理 (product)

localcrm product list                                       # 列出所有产品
localcrm product show <产品ID>                              # 查看产品详情
localcrm product create --name <名称> [选项]                 # 新增产品
localcrm product edit <产品ID> [选项]                        # 编辑产品
localcrm product delete <产品ID> [--yes]                    # 停用产品
localcrm product match [选项]                                # 产品匹配

选项 (match)	说明
<客户ID>	为指定客户匹配产品
--all	为所有客户匹配产品
--stage	按客户阶段筛选（配合 --all）
--rate-sensitive	查找利率敏感客户
--threshold	利率敏感阈值（默认3.5%）

localcrm product create --name "经营贷" --rate-min 3.5 --rate-max 6.0 --amount-min 10 --amount-max 100
localcrm product match 1
localcrm product match --all
localcrm product match --all --stage 有意向
localcrm product match --rate-sensitive --threshold 4.0

统计分析 (stats)

localcrm stats dashboard                        # 数据仪表盘（客户/申请/沟通/回访/画像总览）
localcrm stats funnel                           # 客户转化漏斗 + 申请阶段漏斗
localcrm stats rejection                        # 拒绝原因分布分析
localcrm stats monthly [--months 6]             # 月度客户增长趋势
localcrm stats predict <客户ID>                 # 拒绝风险预判

localcrm stats dashboard
localcrm stats monthly --months 12
localcrm stats predict 1

外呼动作中枢 (outbound，名单为核心资产)

localcrm outbound prepare-list                  # 从 CRM 筛本次待呼名单（黑名单排除+额度截断）
localcrm outbound call 13800138001 13912345678   # 发起外呼
localcrm outbound status [task_id]               # 查询外呼状态
localcrm outbound asr <callId> -t <taskId>       # 查通话 ASR 文本（判意向）
localcrm outbound record <callId> -t <taskId>    # 下载录音
localcrm outbound daylimit                       # 今日外呼额度
localcrm outbound writeback results.json         # 回写外呼结果（标签/阶段/沟通/回访/黑名单）

外呼动作统一走 localcrm outbound *（实现在 actions/ 外呼动作层）。闭环： prepare-list 筛名单 → call 发起 → status 等结果 → 接通 asr 判意向 → writeback 回写。

数据库备份 (backup)

localcrm backup backup                          # 完整备份（数据库 + 客户文档）
localcrm backup list                            # 列出所有备份文件
localcrm backup restore <备份文件.gz>            # 从备份恢复
localcrm backup cleanup                         # 清理30天前的旧备份

批量导入 (import)

localcrm import <文件路径> [--dry-run] [--source 来源]

支持 Excel (.xlsx)、CSV (.csv)、JSON (.json) 格式，自动识别中文列名并去重（手机号相同跳过）。

自动列名映射：

文件中的列名	映射到
姓名/客户名/名字	name
手机/手机号/电话	phone
微信/微信号	wechat
公司/公司名/单位	company
职位/职务	position
地区/区域	region
来源/渠道	source
行业	industry
标签/备注	tags（逗号分隔）
收入/收入范围	income_range
贷款意愿/意愿	loan_willingness
金额/期望金额	expected_amount
利率敏感	rate_sensitivity

服务管理 (server)

localcrm server                        # 前台运行（调试用，Ctrl+C 停止）
localcrm server start [--port 5000]    # 后台启动（守护进程，退出终端后继续运行）
localcrm server stop                   # 停止后台服务
localcrm server status                 # 查看服务状态
localcrm server restart [--port 5000]  # 重启服务

后台启动后服务脱离终端运行，日志输出到 ~/.localcrm/data/server.log。

数据库初始化

localcrm init-db                       # 初始化数据库

Web 界面

启动后访问 http://localhost:5000。

页面导航

页面	URL	说明
首页仪表盘	/	待回访提醒、近期沟通、关键统计
客户列表	/customers	搜索、筛选、标签过滤
客户详情	/customers/<id>	5 个 Tab：概览/画像/沟通记录/贷款申请/文档
新增客户	/customers/new	表单录入
沟通记录	/communications	列表查看和录入
回访管理	/followups	回访计划和完成记录
贷款申请	/applications	申请列表、阶段流转（8 阶段进度条）
标签管理	/tags	新增/编辑/删除标签
产品管理	/products	产品维护、批量匹配、利率敏感客户
产品匹配	/products/match	客户与产品匹配结果
行业知识	/industries	行业信息库，含用款周期/淡旺季/风险因素
统计分析	/stats	8 个可视化模块（漏斗/分布/趋势/排行）
公司对接	/sync	同步管理、字段配置、同步日志
设置	/settings	系统配置

手机端适配

• 手机端底部固定 Tab 导航（首页/客户/新增/回访/更多）
• PC 端左侧侧边栏导航
• 触控友好：按钮最小 44x44px
• 适配 iPhone 安全区域（刘海屏/底部横条）

---

Web 登录认证

当 CRM_WEB_PASSWORD 设置后，所有 Web 页面都需要登录后才能访问。未登录用户自动跳转到 /login 登录页。

• 本地使用：不设置密码，认证关闭，所有页面可直接访问
• 对外开放：设置密码，所有页面需要登录
• 修改密码：修改 .env 中 CRM_WEB_PASSWORD 的值，重启服务生效
• CLI 命令：不受影响，无需认证

环境变量（.env）

环境变量文件位于 ~/.localcrm/.env（首次启动时自动创建）：

# 数据库和客户文档路径默认在 ~/.localcrm/ 下，无需设置
# CRM_DATABASE_PATH=/absolute/path/to/crm.db  （自定义数据库路径用）
# CRM_CUSTOMERS_DIR=/absolute/path/to/customers  （自定义文档目录用）

# 数据库加密密钥（用于敏感文档 AES-256 加密）
CRM_ENCRYPTION_KEY=

# Web 登录认证（留空不启用认证，对外开放时务必设置密码）
CRM_WEB_USERNAME=admin
CRM_WEB_PASSWORD=

# Flask 密钥（生产环境请改为随机字符串）
CRM_SECRET_KEY=change-me-to-a-random-string

# 公司系统 API（可选）
CRM_COMPANY_API_BASE_URL=
CRM_COMPANY_API_KEY=

# 服务配置
CRM_DEBUG=true
CRM_HOST=0.0.0.0
CRM_PORT=5000

---

数据库表

表名	说明
customer	客户基本信息
customer_profile	客户画像（收入/征信/贷款偏好/性格）
tag	标签定义（预置 34 个）
customer_tag	客户-标签关联
communication	沟通记录
document	文档/资料索引
loan_application	贷款申请
stage_log	阶段流转记录
rejection_reason	拒绝原因（预置 17 条）
follow_up	回访计划
industry	行业知识
product	产品信息
company_customer_mapping	本地↔公司客户 ID 映射
sync_field_config	同步字段配置
sync_log	同步日志
tag_change_log	标签变更日志

---

自动服务

由 CLI 操作触发（cli/main.py 入口调用 maybe_run_daily_auto_services()），每日最多执行一次，运行日期记录在 app_setting 表。不依赖首页访问或 web 定时器。

检测条件	自动操作
无意向 阶段客户距上次外呼 ≥90 天	阶段翻转为 待外呼（重新进入可拨池，历史跟进记录保留）
回访计划超过计划时间未完成	自动标记为 overdue
每日推荐客户（生日/下次联系）	生成至 recommended_customer

---

数据安全

• 敏感文档（征信报告、身份证、流水）自动 AES-256 加密存储
• 加密密钥存储在 .env，不进入代码或数据库
• 公司同步前硬编码过滤敏感文件（不可配置绕过），敏感字段额外加密传输
• 仅手动触发同步，无自动后台同步
• 同步日志完整记录每次数据流向