沿街商铺摸排管理技能 v3
任务目标
- 本技能用于：管理和查询沿街商铺摸排数据
- 能力包含：商铺查询、统计汇总、到期提醒、数据导出、网格员管理、授权码管理、业务类型配置
- 触发条件：用户说"查一下商铺数据"、"摸排进度"、"到期提醒"、"生成通报"、"添加网格员"、"授权码"、"业务类型"
🔑 授权码系统（v3新增）
为什么需要授权码？
系统从v3版本开始引入授权码机制，保护核心API服务。所有数据操作（读取、写入、导出等）均需要在云函数层面验证授权码，前端无法绕过。
套餐类型
| 套餐 | 最大记录数 | 有效期 | 价格 |
|---|---|---|---|
| 免费版 (free) | 100条 | 永久 | 免费 |
| 专业版 (pro) | 10000条 | 1年 | 付费 |
| 企业版 (enterprise) | 无限制 | 永久 | 付费 |
如何获取授权码
- 免费版：系统初始化管理员时自动生成一个免费授权码
- 专业版/企业版：联系开发者购买，管理员通过
generate-licenseAPI 生成 - 授权码格式：
SHOP-XXXX-XXXX-XXXX（大写字母和数字组合）
授权码管理API
| API | 说明 | 权限 |
|---|---|---|
| verify-license | 验证授权码 | 无需登录 |
| activate-license | 激活授权码 | 无需登录 |
| check-license | 检查授权状态和配额 | 无需登录 |
| generate-license | 生成新授权码 | 管理员 |
| list-licenses | 列出所有授权码 | 管理员 |
| disable-license | 禁用授权码 | 管理员 |
📋 业务类型配置（v3新增）
概述
业务类型（如"政企业务商机"、"本次办理业务"的选项）从硬编码改为可配置化，支持不同行业场景。
行业模板
| 行业标识 | 说明 | 包含的业务类型 |
|---|---|---|
| telecom | 通信行业 | 政企业务商机、本次办理业务 |
| retail | 零售行业 | 经营品类、业务需求 |
| food | 餐饮行业 | 餐饮类型、业务需求 |
| property | 物业行业 | 物业类型、业务需求 |
| education | 教育行业 | 教育类型、业务需求 |
业务类型管理API
| API | 说明 | 权限 |
|---|---|---|
| get-business-types | 获取业务类型配置 | 需授权码 |
| add-business-type | 添加业务类型 | 管理员 |
| delete-business-type | 删除业务类型 | 管理员 |
| init-business-types | 初始化行业模板 | 管理员 |
| list-industries | 获取可用行业列表 | 无需登录 |
前置准备
- 设置环境变量（必须）：
SHOP_COLLECT_ENV_ID- CloudBase环境IDSHOP_COLLECT_SECRET_ID- 腾讯云SecretIdSHOP_COLLECT_SECRET_KEY- 腾讯云SecretKeySHOP_COLLECT_PWD_SALT- 密码哈希盐值SHOP_COLLECT_LICENSE_KEY- 授权码（v3必需）
核心能力
1. 查询商铺数据
- 查询商铺数据（按网格、微网格、运营商、到期时间等条件）
- 支持模糊搜索和组合条件筛选
- v3注意：所有数据查询API需要授权码验证
2. 统计汇总
- 统计摸排进度（完成率、新增数、各网格对比）
- 按网格/微网格汇总数据
- 生成通报模板
- v3新增：显示当前记录数/套餐配额
3. 到期提醒
- 查询即将到期的商铺（7天/30天/自定义）
- 已过期商铺列表
- 自动提醒功能
4. 数据导出
- 导出CSV/JSON格式
- 支持按条件筛选导出
5. 网格员管理
- 管理网格员账号（添加、删除、查看）
- 密码使用SHA256+盐值哈希存储
6. 授权码管理（v3新增）
- 生成、激活、验证、禁用授权码
- 查看授权状态和配额
- 前端采集页面首次使用需输入授权码
- 汇总表页面可查看/更换授权码
7. 业务类型配置（v3新增）
- 动态加载业务类型选项（替代硬编码）
- 支持多行业模板一键初始化
- 管理员可自定义添加/删除业务类型
数据模型
核心字段
| 字段名 | 含义 | 示例值 |
|---|---|---|
| shopName | 商铺名称 | 张三便利店 |
| grid | 网格 | （用户自定义） |
| microGrid | 微网格 | （用户自定义） |
| address | 地址 | XX路XX号 |
| contactName | 联系人 | 张三 |
| phone | 电话 | 13800138000 |
| operator | 运营商 | 移动/电信/联通 |
| expireDate | 到期日期 | 2026-12-31 |
| bizStatus | 商机状态 | 跟进中/已成交 |
| createTime | 创建时间 | 2026-07-01 10:00:00 |
授权码表 (licenses)
| 字段 | 含义 |
|---|---|
| license_key | 授权码（唯一） |
| plan_type | 套餐类型（free/pro/enterprise） |
| max_records | 最大记录数 |
| expires_at | 过期时间 |
| activated_at | 激活时间 |
| device_id | 绑定设备标识 |
| status | 状态（active/expired/disabled） |
业务类型表 (business_types)
| 字段 | 含义 |
|---|---|
| typeName | 类型分类名 |
| items | JSON数组，选项列表 |
| industry | 行业标签 |
| created_by | 创建者标识 |
使用示例
- 示例1:
- 用户说："查一下即将到期的商铺"
- 执行：
python scripts/api_client.py expire --days 30 -
输出：30天内到期的商铺列表，按到期时间排序
-
示例2:
- 用户说："生成一个专业版授权码"
- 执行：
python scripts/api_client.py generate-license --plan pro -
输出：新生成的授权码 SHOP-XXXX-XXXX-XXXX
-
示例3:
- 用户说："初始化零售行业模板"
- 执行：
python scripts/api_client.py init-business-types --industry retail -
输出：零售行业业务类型配置已初始化
-
示例4:
- 用户说："统计一下各网格摸排进度"
- 执行：
python scripts/api_client.py grid-summary -
输出：各网格的总数、已过期、即将到期、完成率
-
示例5:
- 用户说："查看当前授权状态"
- 执行：
python scripts/api_client.py check-license - 输出：当前套餐、记录数/配额、到期时间
脚本命令速查
| 命令 | 说明 | 示例 |
|---|---|---|
| summary | 汇总统计 | api_client.py summary |
| expire | 到期提醒 | api_client.py expire --days 7 |
| export | 数据导出 | api_client.py export --output csv |
| grid-summary | 网格统计 | api_client.py grid-summary |
| add-user | 添加用户 | api_client.py add-user --phone 138xxx --password xxx |
| list-users | 查看用户 | api_client.py list-users |
| generate-license | 生成授权码 | api_client.py generate-license --plan pro |
| check-license | 查看授权状态 | api_client.py check-license |
| list-licenses | 列出授权码 | api_client.py list-licenses |
| init-business-types | 初始化行业模板 | api_client.py init-business-types --industry telecom |
注意事项
- 授权码必须：v3版本所有数据操作API需要授权码验证，在云函数层面强制执行，前端无法绕过
- 环境变量：所有敏感配置通过环境变量传入，不要硬编码
- 数据安全：密码使用SHA256+盐值哈希存储，不要明文存储
- 网格结构：网格和微网格名称从数据库动态读取，支持任意命名
- 数据权限：网格员只能看到自己网格的数据，管理员可看全部
- 业务类型：行业模板可通过API一键初始化，也可自定义添加
- 免费版限制：免费版最多100条记录，适合小规模试用
