Metadata-Version: 2.4
Name: localcrm-x
Version: 0.0.1
Summary: 个人贷款客户经理 CRM 系统 — 含 agent-skills 命令组，可将技能导出供大模型学习
Author: localCRM
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: flask>=3.0
Requires-Dist: click>=8.0
Requires-Dist: pycryptodome>=3.20
Requires-Dist: python-dotenv>=1.0
Provides-Extra: excel
Requires-Dist: openpyxl>=3.0; extra == "excel"

# localCRM — 本地贷款CRM系统

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

## 技术栈

| 层级 | 技术 |
|------|------|
| 后端 | Python 3 + Flask |
| 数据库 | SQLite（WAL 模式，16 张表） |
| 前端 | Tailwind CSS + Alpine.js + HTMX（CDN，无需构建） |
| CLI | Python Click |
| 加密 | pycryptodome（AES-256） |
| AI分析 | LLM API（可配置，Claude/GPT 等） |

## 快速开始

```bash
# 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
```

可选依赖（按需安装）：

```bash
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 入口（注册 12 个命令组）
│   ├── customer_commands.py       # 客户管理命令
│   ├── communication_commands.py  # 沟通记录 + 回访管理命令
│   ├── application_commands.py    # 贷款申请管理命令
│   ├── tag_commands.py            # 标签 CRUD 命令
│   ├── product_commands.py        # 产品管理 + 匹配命令
│   ├── industry_commands.py       # 行业知识库命令
│   ├── document_commands.py       # 客户文档管理命令
│   ├── stats_commands.py          # 统计分析 + 预判命令
│   ├── sync_commands.py           # 公司同步命令
│   └── utils.py                   # 格式化输出工具
├── scripts/                       # 独立脚本
│   ├── init_db.py                 # 数据库初始化
│   ├── analyze_communication.py   # LLM 沟通内容分析
│   ├── match_products.py          # 产品匹配引擎
│   ├── rejection_predict.py       # 拒绝预判引擎
│   ├── company_sync.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`)

#### 列出客户

```bash
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` |

#### 查看客户详情

```bash
localcrm customer show <客户ID>
```

#### 搜索客户

```bash
localcrm customer search <关键词>
```

#### 新增客户（交互式）

```bash
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` | 企查查数据 | 空 |

#### 快速新增客户

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

#### 编辑客户

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

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

#### 删除 / 恢复客户

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

#### 客户画像管理

```bash
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=是 |

#### 标签操作

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

### 沟通记录 (`comm`)

```bash
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） |

```bash
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`)

```bash
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` | 下次跟进目的 |

```bash
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`)

```bash
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 分类]       # 列出拒绝原因
```

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

```bash
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`)

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

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

### 产品管理 (`product`)

```bash
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%） |

```bash
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
```

### 行业知识库 (`industry`)

```bash
localcrm industry list                                                  # 列出所有行业
localcrm industry show <行业ID>                                         # 查看行业详情
localcrm industry create --name <名称> [选项]                            # 创建行业
localcrm industry edit <行业ID> [选项]                                   # 编辑行业
```

```bash
localcrm industry create --name "餐饮业" --capital-cycle "6个月" --peak-season "春节前后" --avg-loan-amount 20
localcrm industry edit 1 --risk-factors "现金流波动大" --pain-points "无抵押物"
```

### 客户文档 (`doc`)

```bash
localcrm doc list <客户ID>          # 列出客户全部文档
localcrm doc show <文档ID>          # 查看文档详情
localcrm doc delete <文档ID> [--yes] # 删除文档（软删除）
```

### 统计分析 (`stats`)

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

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

### AI 分析

LLM API 配置（`~/.localcrm/.env`）：

```bash
CRM_LLM_API_URL=https://api.anthropic.com/v1/messages
CRM_LLM_API_KEY=sk-ant-...
CRM_LLM_MODEL=claude-sonnet-4-6
```

分析提示词模板文件：`~/.localcrm/analyze_prompt_template.txt`（首次运行自动创建，可直接编辑自定义）

#### 分析沟通内容

```bash
# 直接传入文本（支持多客户内容，LLM 自动识别人物）
localcrm comm analyze <客户ID> --content "客户：我想贷50万做生意，利率3厘左右..." --comm-type 微信

# 从文件读取（微信聊天导出、通话转写文本等）
localcrm comm analyze <客户ID> --file chat.txt --comm-type 电话

# 不指定客户ID（LLM 自动匹配已有客户）
localcrm comm analyze --file multi_person.txt --comm-type 微信
```

### 公司同步 (`sync`)

```bash
localcrm sync push <客户ID>     # 推送客户到公司系统
localcrm sync pull <客户ID>     # 从公司系统拉取数据
localcrm sync status <客户ID>   # 查看同步状态
```

### 数据库备份 (`backup`)

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

### 批量导入 (`import`)

```bash
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`)

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

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

### 数据库初始化

```bash
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`（首次启动时自动创建）：

```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 | 标签变更日志 |

---

## 自动服务

每次访问首页时自动运行：

| 检测条件 | 自动操作 |
|---------|---------|
| 活跃客户超过 30 天未联系 | 自动打标 `沉睡` |
| 意向客户 7 天无新沟通 | 自动打标 `待回访` |
| 回访计划超过计划时间未完成 | 自动标记为 `overdue` |

---

## 数据安全

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