客户项目管理器

一套完整的自由职业业务管理系统。通过单一技能统一跟踪客户、项目、截止日期、交付物、发票及沟通记录。

使用方法

/client-project-manager add client "Acme Corp" --contact "jane@acme.com" --rate "$100/hr"
/client-project-manager add project "Website Redesign" --client "Acme Corp" --deadline "2026-03-15" --budget "$5000"
/client-project-manager status
/client-project-manager update "Website Redesign" --progress 60 --note "Homepage mockup approved"
/client-project-manager invoice "Acme Corp" --project "Website Redesign"
/client-project-manager weekly-update "Acme Corp"
/client-project-manager dashboard

数据存储

所有数据均以 JSON 文件形式存储在 ./freelance-data/ 目录下：

freelance-data/
  clients.json        # 客户 CRM 数据
  projects.json       # 进行中与已完成的项目
  time-log.json       # 工时记录条目
  invoices/           # 生成的发票
  updates/            # 客户周报邮件

若该目录不存在，则首次使用时自动创建；若文件已存在，则优先读取并完整保留所有现有数据。

命令说明

add client

向客户关系管理系统（CRM）添加新客户。

/client-project-manager add client "[名称]" --contact "[邮箱]" --rate "[费率]" --notes "[备注]"

数据存入 clients.json：

{
  "id": "client-uuid",
  "name": "Acme Corp",
  "contact_email": "jane@acme.com",
  "default_rate": "$100/hr",
  "notes": "Prefers Slack for communication",
  "projects": [],
  "total_billed": 0,
  "total_paid": 0,
  "created": "2026-02-13",
  "status": "active"
}

add project

为客户新增一个项目。

/client-project-manager add project "[名称]" --client "[客户]" --deadline "[日期]" --budget "[金额]" --deliverables "[列表]"

数据存入 projects.json：

{
  "id": "project-uuid",
  "name": "Website Redesign",
  "client_id": "client-uuid",
  "client_name": "Acme Corp",
  "status": "active",
  "progress": 0,
  "budget": 5000,
  "billed": 0,
  "deadline": "2026-03-15",
  "created": "2026-02-13",
  "deliverables": [
    { "name": "Homepage mockup", "status": "pending", "due": "2026-02-20" },
    { "name": "Inner pages", "status": "pending", "due": "2026-03-01" },
    { "name": "Development", "status": "pending", "due": "2026-03-10" },
    { "name": "Launch", "status": "pending", "due": "2026-03-15" }
  ],
  "notes": [],
  "time_entries": []
}

log time

记录在某项目上投入的工作时间。

/client-project-manager log time "[项目]" --hours [X] --description "[所做工作]"

追加至 time-log.json：

{
  "id": "entry-uuid",
  "project_id": "project-uuid",
  "client_id": "client-uuid",
  "date": "2026-02-13",
  "hours": 3.5,
  "rate": 100,
  "amount": 350,
  "description": "Built responsive navigation and hero section"
}

update

更新项目进度并添加备注。

/client-project-manager update "[项目]" --progress [0-100] --note "[更新内容]" --deliverable "[交付物名称]" --status "[done|in-progress|pending]"

status

显示所有进行中项目的当前状态。

输出格式示例：

╔══════════════════════════════════════════════════════════════╗
║                    FREELANCE DASHBOARD                       ║
╠══════════════════════════════════════════════════════════════╣

📊 进行中项目：3  
💰 待收发票总额：$2,500  
⏰ 本周工时：22.5  
📅 下一个截止日期：Website Redesign（Acme Corp）— 3月15日  

──────────────────────────────────────────────────────────────
PROJECT: Website Redesign  
CLIENT: Acme Corp | DEADLINE: Mar 15, 2026  
PROGRESS: ████████████░░░░░░░░ 60%  
BUDGET: $3,000 / $5,000 billed  
DELIVERABLES:  
  ✅ Homepage mockup（Feb 20）— DONE  
  🔄 Inner pages（Mar 1）— IN PROGRESS  
  ⬜ Development（Mar 10）— PENDING  
  ⬜ Launch（Mar 15）— PENDING  
──────────────────────────────────────────────────────────────

invoice

为客户生成专业发票。

/client-project-manager invoice "[客户]" --project "[项目]" --period "[起始日期] to [结束日期]"

在 freelance-data/invoices/ 目录下同时生成 Markdown 和 HTML 格式发票：

发票内容：

INVOICE #[INV-YYYY-NNN]  
Date: [今日日期]  
Due: [今日日期 + 14 天]  

FROM:  
[您的姓名/公司名称 — 若存在则从 freelance-data/config.json 中读取]  

TO:  
[客户名称]  
[客户联系人]  

PROJECT: [项目名称]  
PERIOD: [日期范围]  

| Date | Description | Hours | Rate | Amount |  
|------|-------------|-------|------|--------|  
| ... 此期间内的工时记录 ... |  

                              Subtotal: $X,XXX.XX  
                              Tax (0%): $0.00  
                              TOTAL DUE: $X,XXX.XX  

Payment Terms: Net 14  
Payment Methods: [来自 config.json，或默认为 "Bank Transfer / PayPal"]  

Thank you for your business.  

保存为 freelance-data/invoices/INV-2026-001-acme-corp.md 和对应 .html 文件。

weekly-update

为客户生成专业的周度进展邮件。

/client-project-manager weekly-update "[客户]"

读取该客户的项目信息、近期工时记录及备注，自动生成如下内容：

Subject: Weekly Update — [项目名称] — Week of [日期]  

Hi [联系人名],  

Here's your weekly update on [项目名称]:  

**This Week:**  
- [已完成交付物及进度]  
- [关键决策事项]  
- [已投入工时：X.X]  

**Next Week:**  
- [计划交付物]  
- [需客户确认的阻塞项或决策点]  

**Project Status:**  
- Progress: XX%  
- Budget used: $X,XXX / $X,XXX  
- On track for [deadline]: ✅ Yes / ⚠️ At risk / ❌ Behind  

[Any questions or items needing client input]  

Best,  
[您的姓名]  

保存至 freelance-data/updates/ 目录，并在终端中显示供复制粘贴。

payment-reminder

为逾期未付发票生成礼貌的付款提醒。

/client-project-manager payment-reminder "[客户]"

检查是否存在已过期但尚未支付的发票，并按逾期天数生成相应级别的提醒：

• 逾期 1–7 天：温和提醒
• 逾期 8–14 天：坚定但保持专业性的跟进
• 逾期 15 天及以上：含滞纳金说明的最终通知

dashboard

展示全面的业务概览：

╔══════════════════════════════════════════════════════════════╗
║                  MONTHLY BUSINESS REPORT                     ║
╠══════════════════════════════════════════════════════════════╣

💰 本月收入：     $4,250  
💰 上月收入：     $3,800（↑ 12%）  
📊 进行中项目：   3  
✅ 本月完成项目： 1  
⏰ 已计费工时：   42.5  
💵 实际小时费率： $100/hr  
📋 待收发票：     $2,500（共 2 张）  
⚠️  逾期发票：    $0  

TOP CLIENTS（按收入排序）：  
  1. Acme Corp        $2,500（59%）  
  2. StartupXYZ       $1,250（29%）  
  3. LocalBiz         $500（12%）  

UPCOMING DEADLINES：  
  Feb 20 — Homepage mockup（Acme Corp）  
  Mar 01 — Content strategy（StartupXYZ）  
  Mar 15 — Website launch（Acme Corp）  

config

设置您的企业信息，用于发票和客户沟通。

/client-project-manager config --name "Your Name" --business "Your Business LLC" --email "you@email.com" --payment "PayPal: you@email.com / Bank: routing XXX"

保存至 freelance-data/config.json。

数据完整性规则

1. 禁止覆盖写入 — 每次操作前必须先读取现有数据，修改后再整体写回
2. 强制备份校验 — 所有写入操作前，须验证数据文件存在且为合法 JSON 格式
3. UUID 生成规范 — 使用基于时间戳的 ID：client-[timestamp]、project-[timestamp]
4. 日期格式统一 — 始终采用 ISO 8601 标准：YYYY-MM-DD
5. 货币数值处理 — 内部以纯数字存储，显示时添加 $ 符号并格式化