wecom-user-manager

# 企业微信用户管理技能 > 完整的用户生命周期管理：添加用户 → 自动激活 → 权限管理 --- ## 🎯 功能概述 ### 管理员视角 - ✅ 添加用户权限（支持自然语言命令） - ✅ 发送确认卡片 - ✅ 处理回调创建用户 ### 用户视角 - ✅ 首次登录自动激活 - ✅ 自动获取真实姓名 - ✅ 欢迎消息和权限信息 --- ## 📱 使用流程 ### 流程 1：管理员添加用户 ``` 管理员：添加用户 zhangsan 店长 正义路 机器人： ┌────────────────────────────────┐ │ 请确认以下信息 │ │ UserID: zhangsan │ │ │ │ 角色：店长 │ │ 门店：昆明五华区正义路 60 号红谷 │ │ │ │ ℹ️ 姓名将在首次登录时自动获取 │ │ │ │ [✅ 确认添加] [🔄 重新选择] │ └────────────────────────────────┘ 管理员点击确认： ✅ 用户添加成功！ ℹ️ 姓名将在首次登录时自动获取 ``` ### 流程 2：用户首次登录 ``` 用户（首次）：你好 机器人： 👋 欢迎使用红谷门店经营助手！ 检测到您是首次使用，正在激活账户... ✅ 账户已激活 姓名：张三 企业微信 ID: zhangsan 角色：店长 门店：1 家 现在可以开始使用了！ ``` ### 流程 3：用户再次登录 ``` 用户：早上好 机器人： 早上好，张三！有什么可以帮您？ ``` --- ## 🔧 核心功能 ### 1. 添加用户 **命令格式**： ``` 添加用户 <UserID> <角色> <门店/地区> ``` **支持的角色**： - 总部管理员/总部/管理员 - 区域经理/区域/大区 - 省份经理/省份/省级 - 城市经理/城市 - 店长 - 店员/导购 **示例**： ``` 添加用户 zhangsan 店长 正义路 添加用户 liming 省份经理 云南 添加用户 wangwu 区域经理 西南区 ``` ### 2. 自动激活 **触发条件**： - 用户首次发送任意消息 - 用户状态为"待激活_xxx" **激活流程**： 1. 提取 UserID 和姓名 2. 检查用户状态 3. 更新用户名（从"待激活_" → 真实姓名） 4. 记录登录时间 5. 发送欢迎消息 ### 3. 权限检查 **可以添加用户的角色**： - ✅ 总部管理员 - ✅ 区域经理 - ✅ 省份经理 **不可以添加用户的角色**： - ❌ 城市经理 - ❌ 店长 - ❌ 店员 --- ## 📁 文件结构 ``` wecom-user-manager/ ├── SKILL.md # 技能文档（本文件） ├── handler.py # 消息处理器 ├── auto_activate.py # 自动激活脚本 ├── references/ │ └── api-user-manager.md # API 文档 └── tests/ └── test_user_manager.py # 测试脚本 ``` --- ## 🔗 API 接口 ### add_user — 添加用户 ``` wecom_mcp call user add_user '{"userid": "zhangsan", "role": "store_manager", "store_id": "xxx"}' ``` ### activate_user — 激活用户 ``` wecom_mcp call user activate_user '{"userid": "zhangsan", "name": "张三"}' ``` ### check_user — 检查用户状态 ``` 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" # 应返回：无权限 ``` --- ## 📊 用户状态流转 ``` 添加用户 → 待激活_xxx → (首次登录) → 真实姓名 → (后续登录) → 更新 last_login ``` | 状态 | username 前缀 | 操作 | |------|--------------|------| | 待激活 | `待激活_` | 激活并更新用户名 | | 已激活 | 其他 | 仅更新 last_login | --- ## 🎯 典型场景 ### 场景 1：新店开业添加店长 ``` 管理员：添加用户 zhangsan 店长 正义路 → 发送确认卡片 → 管理员确认 → 用户创建成功 zhangsan 首次登录： → 自动激活 → 发送欢迎消息 → 开始使用 ``` ### 场景 2：批量添加店员 ``` 管理员：添加用户 liming 店员 正义路 管理员：添加用户 wangwu 店员 正义路 管理员：添加用户 zhaoliu 店员 正义路 liming 首次登录： → 自动激活 → "欢迎使用，liming！" ``` ### 场景 3：添加省份经理 ``` 管理员：添加用户 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 (合并版) **状态**: ✅ 已部署