wecom-user-manager

企业微信用户管理技能。支持管理员添加用户权限，用户首次登录自动激活。包含完整的用户生命周期管理。

企业微信用户管理技能

完整的用户生命周期管理：添加用户 → 自动激活 → 权限管理

---

🎯 功能概述

管理员视角

• ✅ 添加用户权限（支持自然语言命令）
• ✅ 发送确认卡片
• ✅ 处理回调创建用户

用户视角

• ✅ 首次登录自动激活
• ✅ 自动获取真实姓名
• ✅ 欢迎消息和权限信息

---

📱 使用流程

流程 1：管理员添加用户

text

管理员：添加用户 zhangsan 店长 正义路

机器人：
┌────────────────────────────────┐
│ 请确认以下信息                  │
│ UserID: zhangsan               │
│                                │
│ 角色：店长                      │
│ 门店：昆明五华区正义路 60 号红谷  │
│                                │
│ ℹ️  姓名将在首次登录时自动获取  │
│                                │
│ [✅ 确认添加] [🔄 重新选择]    │
└────────────────────────────────┘

管理员点击确认：
✅ 用户添加成功！
ℹ️  姓名将在首次登录时自动获取

流程 2：用户首次登录

text

用户（首次）：你好

机器人：
👋 欢迎使用红谷门店经营助手！

检测到您是首次使用，正在激活账户...
✅ 账户已激活

姓名：张三
企业微信 ID: zhangsan
角色：店长
门店：1 家

现在可以开始使用了！

流程 3：用户再次登录

text

用户：早上好

机器人：
早上好，张三！有什么可以帮您？

---

🔧 核心功能

1. 添加用户

命令格式：

text

添加用户 <UserID> <角色> <门店/地区>

支持的角色：

• 总部管理员/总部/管理员
• 区域经理/区域/大区
• 省份经理/省份/省级
• 城市经理/城市
• 店长
• 店员/导购

示例：

text

添加用户 zhangsan 店长 正义路
添加用户 liming 省份经理 云南
添加用户 wangwu 区域经理 西南区

2. 自动激活

触发条件：

• 用户首次发送任意消息
• 用户状态为"待激活_xxx"

激活流程：

1. 提取 UserID 和姓名
2. 检查用户状态
3. 更新用户名（从"待激活_" → 真实姓名）
4. 记录登录时间
5. 发送欢迎消息

3. 权限检查

可以添加用户的角色：

• ✅ 总部管理员
• ✅ 区域经理
• ✅ 省份经理

不可以添加用户的角色：

• ❌ 城市经理
• ❌ 店长
• ❌ 店员

---

📁 文件结构

text

wecom-user-manager/
├── SKILL.md                    # 技能文档（本文件）
├── handler.py                  # 消息处理器
├── auto_activate.py            # 自动激活脚本
├── references/
│   └── api-user-manager.md     # API 文档
└── tests/
    └── test_user_manager.py    # 测试脚本

---

🔗 API 接口

add_user — 添加用户

text

wecom_mcp call user add_user '{"userid": "zhangsan", "role": "store_manager", "store_id": "xxx"}'

activate_user — 激活用户

text

wecom_mcp call user activate_user '{"userid": "zhangsan", "name": "张三"}'

check_user — 检查用户状态

text

wecom_mcp call user check_user '{"userid": "zhangsan"}'

---

⚠️ 注意事项

1. UserID 格式

• 必须是企业微信中的真实 UserID
• 可以在企业微信管理后台查看
• 格式如：zhangsan、liming001、10001

2. 姓名获取

• 添加时无需提供姓名
• 首次登录时自动从企业微信获取
• 确保 UserID 与企业微信一致

3. 门店搜索

• 支持模糊搜索
• 输入关键词即可（如"正义路"）
• 如有多个匹配，会提示选择

4. 配置文件同步

• 工作区和插件目录的 users.json 需要保持同步
• 激活后自动同步

---

🧪 测试用例

测试 1：添加用户

bash

python3 handler.py handle_message "添加用户 zhangsan 店长 正义路" "hq_admin_001"

测试 2：自动激活

bash

python3 auto_activate.py check_and_activate "zhangsan" "张三"

测试 3：权限检查

bash

python3 handler.py check_permission "store_clerk_001"
# 应返回：无权限

---

📊 用户状态流转

text

添加用户 → 待激活_xxx → (首次登录) → 真实姓名 → (后续登录) → 更新 last_login

状态	username 前缀	操作
待激活	待激活_	激活并更新用户名
已激活	其他	仅更新 last_login

---

🎯 典型场景

场景 1：新店开业添加店长

text

管理员：添加用户 zhangsan 店长 正义路
→ 发送确认卡片
→ 管理员确认
→ 用户创建成功

zhangsan 首次登录：
→ 自动激活
→ 发送欢迎消息
→ 开始使用

场景 2：批量添加店员

text

管理员：添加用户 liming 店员 正义路
管理员：添加用户 wangwu 店员 正义路
管理员：添加用户 zhaoliu 店员 正义路

liming 首次登录：
→ 自动激活
→ "欢迎使用，liming！"

场景 3：添加省份经理

text

管理员：添加用户 sunqi 省份经理 云南
→ 发送确认卡片（不需要门店）
→ 管理员确认
→ 用户创建成功（可访问云南省所有门店）

sunqi 首次登录：
→ 自动激活
→ "欢迎使用，sunqi！您管理云南省所有门店"

---

🔍 故障排查

问题 1：用户未自动激活

症状：用户发送消息后，username 仍然是"待激活_xxx"

解决：

bash

# 手动激活
python3 auto_activate.py check_and_activate "userid" "姓名"

# 检查配置文件
cat config/users.json | grep "userid"

问题 2：权限不足

症状：店长尝试添加用户时收到"权限不足"提示

解决：

• 只有总部/区域/省份经理可以添加用户
• 联系总部管理员添加

问题 3：配置文件不同步

症状：插件目录已激活，工作区仍是待激活

解决：

bash

# 同步配置文件
cp plugin/config/users.json workspace/config/users.json

---

📝 最佳实践

1. 自动激活流程

javascript

// 企业微信插件消息处理
async function onMessage(message) {
    const { from_userid, from_name } = message;
    
    // 1. 自动激活
    const result = await activateUser(from_userid, from_name);
    
    // 2. 如果是首次激活，发送欢迎消息
    if (result.activated) {
        await sendWelcomeMessage(from_userid, result.message);
    }
    
    // 3. 继续处理其他消息
    await handleMessage(message);
}

2. 配置文件管理

bash

# 启动时同步
cp workspace/config/users.json plugin/config/users.json

# 关闭时同步
cp plugin/config/users.json workspace/config/users.json

3. 日志记录

python

# 记录用户操作
logging.info(f"添加用户：{userid}, 角色：{role}")
logging.info(f"激活用户：{userid}, 姓名：{name}")

---

🎊 总结

wecom-user-manager 是一个完整的用户管理 Skill，包含：

1. ✅ 添加用户 - 支持自然语言命令
2. ✅ 自动激活 - 首次登录自动完成
3. ✅ 权限管理 - 严格的权限控制
4. ✅ 欢迎消息 - 个性化的用户体验

---

最后更新: 2026-03-28
版本: v1.0 (合并版)
状态: ✅ 已部署