survey-workflow（调查工作流程）

survey-workflow Agent

概述

本 Agent 负责组织健康度与员工敬业度联合调研的全流程管理，从发送调研通知、追踪填答状态、自动催办，到数据分析与报告生成。

📋 问卷结构

麦肯锡组织健康度 (OHI) — 37题，10个维度

北森敬业度及满意度 — 29题

核心指标（敬业度8题）

关键驱动因素（满意度19题）

开放式问答（2题）

• Q_OPEN_001: 您认为公司在未来发展中，最需要保持或加强的一项能力是什么？
• Q_OPEN_002: 您对公司的组织氛围或管理方式，还有哪些具体的改进建议？

核心能力

1. 导入活动名单（前置动作）

通过 importSurveyTargets 接口将员工名单批量导入问卷系统。

API 信息：

• 路径：POST /questionnaire/admin/surveys/targets/import
• 生产环境：https://sg-al-cwork-web.mediportal.com.cn/open-api/questionnaire/admin/surveys/targets/import
• 测试环境：https://cwork-api-test.xgjktech.com.cn/open-api/questionnaire/admin/surveys/targets/import

请求参数：

{
  "surveyId": "问卷ID",
  "employeeIdList": ["员工ID列表"],
  "replace": false,
  "sourceType": "来源类型"
}

⚠️ 需要有效员工身份；导入完成后可衔接 sendNotify 发送通知。

1.1 追加人员流程（增量导入）

当发现调研名单有遗漏，需要追加人员时，按以下流程操作：

步骤1：导入追加人员

• 调用 importSurveyTargets 接口
• 设置 replace=false（关键参数，表示增量追加）
• 传入需要追加的员工ID列表

步骤2：向追加人员发送通知

• 调用 sendNotify 接口
• 传入新追加的员工ID列表
• 使用与初始通知相同或略作调整的通知文案

完整示例：

import requests

BASE_URL = "https://cwork-api-test.xgjktech.com.cn/open-api"
HEADERS = {"access-token": "your_token"}

survey_id = "200003"
new_employees = [1512393075401125890, 1512393196394213378]  # 新追加的员工

# Step 1：导入追加人员（增量）
import_url = f"{BASE_URL}/questionnaire/admin/surveys/targets/import"
import_resp = requests.post(import_url, json={
    "surveyId": survey_id,
    "employeeIdList": new_employees,
    "replace": False,  # ← 关键：设置为 False 表示追加
    "sourceType": "手动追加"
}, headers=HEADERS)

if import_resp.json()["resultCode"] == 1:
    print("✅ 追加人员导入成功")

    # Step 2：向追加人员发送通知
    notify_url = f"{BASE_URL}/questionnaire/notify/send"
    notify_resp = requests.post(notify_url, json={
        "surveyId": survey_id,
        "employeeIds": new_employees,
        "notifyTitle": "关于开展集团总部2026年度组织健康度与员工敬业度联合调研的通知",
        "notifyMarkdown": "【追加通知】\
\
您已加入本次调研名单，请点击以下链接完成填答：\
\
https://cwork-web-test.xgjktech.com.cn/questionnaire-web/web/dist/#/survey?surveyId=200003"
    }, headers=HEADERS)

    if notify_resp.json()["resultCode"] == 1:
        print("✅ 追加人员通知发送成功")
        print(f"批次号：{notify_resp.json()['data']['batchNo']}")
        print(f"成功：{notify_resp.json()['data']['successCount']} 人")

注意事项：

• ⚠️ replace=false 是追加人员的关键参数，不能遗漏
• ⚠️ 追加后建议单独发送通知，并在文案中标注"追加通知"或"补发"
• ⚠️ 追加人员的填答截止时间与初始调研保持一致
• 💡 建议将追加记录归档到对应批次的 input/notification_records.json 中

2. 发送调研通知（发汇报）

通过 sendNotify 接口发送调研通知，支持自定义 Markdown 通知文案。

API 信息：

• 路径：POST /questionnaire/notify/send
• 生产环境：https://sg-al-cwork-web.mediportal.com.cn/open-api/questionnaire/notify/send
• 测试环境：https://cwork-api-test.xgjktech.com.cn/open-api/questionnaire/notify/send

请求参数：

{
  "surveyId": "问卷ID",
  "employeeIds": ["员工ID列表"],
  "notifyMarkdown": "通知文案（支持 Markdown，不传则用系统默认文案）"
}

典型调用流程：

1. 调 listUnsubmittedParticipants（5.9）获取未通知人员
2. 调 sendNotify（5.5）发送通知
3. 记录发送结果

响应结构：

{
  "resultCode": 1,
  "resultMsg": null,
  "data": {
    "batchNo": "批次号",
    "successCount": 3,
    "failCount": 0
  }
}

3. 追踪填答状态

通过 API 实时查询员工的提交状态，支持按部门/名单维度查看填答率。

相关 API：

4. 自动催办提醒

截止前定时检查未提交人员，向未提交对象发送催办通知。

API 信息：

• 路径：GET /questionnaire/notify/pressure
• 生产环境：https://sg-al-cwork-web.mediportal.com.cn/open-api/questionnaire/notify/pressure
• 测试环境：https://cwork-api-test.xgjktech.com.cn/open-api/questionnaire/notify/pressure

请求参数：

GET /questionnaire/notify/pressure?surveyId={surveyId}&employeeIds={id1,id2,...}

典型催办闭环流程：

1. 调 listUnsubmittedParticipants（5.9）→ 获取未提交人员名单
2. 调 pressureNotify（5.6）→ 对未提交人员发起催办
3. 调 listSubmittedParticipants（5.8）/ listUnsubmittedParticipants（5.9）→ 复盘本次催办效果

⚠️ 催办接口虽为 GET，业务语义为写操作，请控制调用频率。

5. 拉取答卷数据

通过 getSubmissionDetail 接口拉取每位提交者的完整答卷数据。

API 信息：

• 路径：GET /questionnaire/submission/detail
• 生产环境：https://sg-al-cwork-web.mediportal.com.cn/open-api/questionnaire/submission/detail
• 测试环境：https://cwork-api-test.xgjktech.com.cn/open-api/questionnaire/submission/detail

请求参数：

GET /questionnaire/submission/detail?surveyId={surveyId}&submissionId={submissionId}

返回字段：

• answers[]：每题答题记录，含 questionId、dimension、scoreValue、textAnswer、supplementaryText
• durationSec：填答时长
• submitTimeMillis：提交时间

6. 统计分析

通过 getStatistics 接口获取整卷或分维度的评分统计。

API 信息：

• 路径：GET /questionnaire/statistics
• 生产环境：https://sg-al-cwork-web.mediportal.com.cn/open-api/questionnaire/statistics
• 测试环境：https://cwork-api-test.xgjktech.com.cn/open-api/questionnaire/statistics

请求参数：

GET /questionnaire/statistics?surveyId={surveyId}&groupBy={survey|dimension}

groupBy 取值：

• survey：获取整卷分值分布
• dimension：获取分维度分值分布

7. 生成分析报告

• 按模板输出结构化分析报告
• 包含数据概览、维度得分、问题诊断、改进建议

⚠️ 报告模板强制要求（必须严格遵守）

报告分两类：部门报告（7章） 和 集团报告（8章），两者章节结构不同，生成前必须确认报告类型并严格按对应模板输出。

部门报告（7章）— 必须完整包含：

集团报告（8章）— 必须完整包含：

常见错误（禁止再犯）：

• ❌ 部门报告不写总部平均分对比 → 每表必须有"总部平均"列
• ❌ 部门报告缺 Mermaid 雷达图 → 第2章必须包含
• ❌ 部门报告满意度只写部分维度 → 20项全部列出
• ❌ 部门报告改进建议缺时间/根因 → 根因+措施+时间三要素必须齐全
• ❌ 部门报告缺行动清单第6章 → 行动项/负责人/时间/成功标准四列必须完整
• ❌ 集团报告第5章缺各部门对比表 → 至少包含各部门 OHI + 敬业度得分对比
• ❌ 集团报告第7章缺优先级排序 → P0/P1/P2 + 责任主体/措施/效果/时间缺一不可
• ❌ 生成前不确认报告类型 → 先确认是"部门报告"还是"集团报告"再开始写

报告生成脚本（使用 Jinja2 模板）

报告生成采用「模板 + 数据分离」架构，确保报告结构不会在代码修改中丢失。

workspace-survey/
├── templates/
│   ├── dept_report.md.j2     ← 部门报告模板（Jinja2）
│   └── group_report.md.j2    ← 集团报告模板（Jinja2）
└── scripts/
    ├── generate_dept_reports_v4.py  ← 部门报告生成
    └── generate_group_report.py       ← 集团报告生成

运行命令：

# 部门报告（3份，每个部门一份）
python3 scripts/generate_dept_reports_v4.py --analysis-file data/分析结果.json

# 集团报告（1份）
python3 scripts/generate_group_report.py --analysis-file data/分析结果.json

⚠️ 关键词提取规则（必须遵守）：

开放式反馈的高频关键词必须是「动词+名词」的完整搭配，拒绝单独的形容词/动词。

✅ 合格关键词示例：提高薪酬、减少加班、加强团队建设、改善工作环境、明确职业发展

❌ 不合格关键词（会被过滤）：改善、加强、提高、减少（必须搭配名词才有意义）

实现逻辑见 generate_group_report.py 中 _extract_keywords 函数，核心约束：

1. 动作词列表 + 名词列表，通过子串匹配提取完整搭配
2. 按频次排序，长词覆盖短词
3. 单独的语气词/形容词不进入结果

复验方法：生成报告后执行 grep -A15 "高频主题词" output/集团报告_*.md，确认关键词均为有效搭配。

使用方式

方式一：脚本式（本地数据）

# 1. 员工匹配校验
python3 scripts/match_employees.py --excel-path data/员工名单.xlsx

# 2. 发送调研通知
python3 scripts/send_notification.py --employees data/匹配结果.json \
  --survey-url "https://xxx.com/survey" --deadline 2026-04-30

# 3. 追踪填答状态
python3 scripts/track_submissions.py --employees data/匹配结果.json \
  --data-file data/问卷数据.xlsx

# 4. 发送催办提醒
python3 scripts/send_reminder.py --employees data/匹配结果.json \
  --data-file data/问卷数据.xlsx --days-before 3

# 5. 加载问卷数据
python3 scripts/load_survey_data.py --data-file data/问卷数据.xlsx

# 6. 三层分析
python3 scripts/analyze_data.py --data-file data/问卷数据.xlsx --level all

# 7. 生成报告
python3 scripts/generate_report.py --data-file data/问卷数据.xlsx --level all

方式二：API 直连（实时数据）

直接调用问卷系统 Open API，无需本地 Excel 数据。

推荐流程（通知 → 催办 → 复盘）：

import requests

BASE_URL = "https://sg-al-cwork-web.mediportal.com.cn/open-api"
HEADERS = {"appKey": "你的appKey"}

survey_id = "问卷ID"

# Step 1：获取未提交人员名单
unsubmitted_url = f"{BASE_URL}/questionnaire/surveys/participants/unsubmitted/list"
resp = requests.get(unsubmitted_url, params={"surveyId": survey_id}, headers=HEADERS)
unsubmitted_list = resp.json()["data"]  # 人员列表

# Step 2：发送通知（发汇报）
notify_url = f"{BASE_URL}/questionnaire/notify/send"
requests.post(notify_url, json={
    "surveyId": survey_id,
    "employeeIds": [p["employeeId"] for p in unsubmitted_list]
}, headers=HEADERS)

# Step 3：催办未提交人员
pressure_url = f"{BASE_URL}/questionnaire/notify/pressure"
requests.get(pressure_url, params={
    "surveyId": survey_id,
    "employeeIds": ",".join([p["employeeId"] for p in unsubmitted_list])
}, headers=HEADERS)

# Step 4：复盘提交情况
submitted_url = f"{BASE_URL}/questionnaire/surveys/participants/submitted/list"
resp_sub = requests.get(submitted_url, params={"surveyId": survey_id}, headers=HEADERS)
submitted_list = resp_sub.json()["data"]
print(f"已提交: {len(submitted_list)} 人，未提交: {len(unsubmitted_list)} 人")

API 索引速查：

详细字段结构见 docs/问卷系统API调用说明.md

配置文件 (config/config.json)

关键配置项：

• survey.deadline: 调研截止日期
• survey.min_response_rate: 最低填答率要求 (85%)
• survey.survey_url: 调研H5页面链接
• reminder.schedule: 催办提醒规则

数据文件格式

员工名单 Excel

问卷数据 Excel

批次归档规范（强制执行）

每次调研视为一个独立批次，所有操作必须归档到对应批次目录，不得散落在 latest/ 或其他位置。

目录结构规范

output/archive/{surveyId}/{日期}/
├── input/
│   ├── employee_list.json       # 本批次导入的员工名单
│   └── notification_records.json # 发通知/催办记录（按时间顺序）
├── data/
│   ├── submissions/             # 每位提交者的原始答卷（一人一个文件）
│   │   └── {employeeId}_{姓名}.json
│   └── benchmark.json           # 本批次全体均值（生成报告前必须先有）
└── reports/
    ├── 集团报告_{日期}.md
    └── {部门名}_诊断报告_{日期}.md

关键规则

1. 先建档，再操作：每个新批次开始时，先创建目录结构
2. 发名单导入 → 写入 input/employee_list.json
3. 发通知/催办 → 追加到 input/notification_records.json
4. 拉取答卷数据 → 存入 data/submissions/{employeeId}_{姓名}.json
5. 计算均值 → 生成 data/benchmark.json（所有报告对比基准的唯一来源）
6. 生成报告 → 存入 reports/，同时同步到 output/latest/
7. 报告中的对比值：统一使用"本批次全体均值"，不得写"总部平均"（因为只有一批数据时这就是本批均值）

benchmark.json 必须字段

{
  "surveyId": "问卷ID",
  "surveyDate": "YYYY-MM-DD",
  "totalEmployees": 3,
  "totalSubmissions": 1,
  "responseRate": 0.333,
  "ohi_avg": 3.45,
  "engagement_avg": 3.62,
  "satisfaction_avg": 3.07,
  "ohi_dimensions": { "发展方向": 3.00, ... },
  "engagement_core": { "留任": 3.00, ... },
  "satisfaction": { "薪酬福利": 3.00, ... }
}

常见错误（禁止再犯）

• ❌ 报告对比值写"总部平均" → 统一写"本批次全体均值"
• ❌ 数据散落在 latest/ 不归档 → 操作后立即写入对应批次目录
• ❌ 不生成 benchmark.json 就出报告 → benchmark 是所有报告的对比基准
• ❌ 多人数据混在一个文件 → 一人一个 JSON 文件，方便独立引用

认证说明（重要，必须阅读）

🏭 默认使用生产环境，除非明确指定测试环境。

生产环境调用问卷系统 API 时，必须使用 APP Key 换取 access-token，不能直接用 token。

认证流程

XG_BIZ_API_KEY (APP Key)
        ↓  cms-auth-skills/login.py
  access-token
        ↓
  问卷系统 API 请求头

认证命令

python3 skills/cms-auth-skills/scripts/auth/login.py \
  --ensure \
  --app-key "$XG_BIZ_API_KEY"

QuestionnaireClient 自动鉴权

scripts/utils/questionnaire_client.py 已内置自动换 token 逻辑：

• 初始化时若有 XG_BIZ_API_KEY 但无 access_token，自动调用 login.py 换取 token
• 脚本调用时只需指定 base_url 为生产地址即可，无需手动传 token

from questionnaire_client import QuestionnaireClient

# 生产环境（自动用 XG_BIZ_API_KEY 换 token）
client = QuestionnaireClient(
    base_url="https://sg-al-cwork-web.mediportal.com.cn"
)

# 发送通知
client.send_notify(survey_id=200003, notify_title="...", ...)

常见错误

依赖

• Python 3.9+ (标准库)
• CWork API (通过 cms-auth-skills 鉴权)
• 问卷系统 Open API（路径 /questionnaire/**，见 docs/问卷系统API调用说明.md）

维护说明

• 配置文件：workspace-survey/config/config.json（权威版本，含题目原文、催办模板、数据质量规则、AI分析规则）
• 问卷维度配置已内置到 config.json 中
• 截止日期等参数可随时修改配置文件调整