spzwin

@clawhub-spzwin-1ae0f5894d
34prompts
0upvotes received
0contributions
Joined about 1 month ago
34 contributions in the last year
Jun
Jul
Aug
Sep
Oct
Nov
Dec
Jan
Feb
Mar
Apr
May
Less
survey-workflow
Skill
组织健康度与员工敬业度调研全流程管理 Agent。功能包括：①员工名单批量导入问卷系统；②追加人员（增量导入）；③发送调研通知（支持自定义通知模板）；④追踪填答状态；⑤截止前自动催办；⑥拉取答卷数据（API直连）；⑦计算本批次基准均值；⑧按模板生成部门/集团诊断报告。问卷包含麦肯锡组织健康度37题（10维度）+...
---
name: survey-workflow
description: 组织健康度与员工敬业度调研全流程管理 Agent。功能包括：①员工名单批量导入问卷系统；②追加人员（增量导入）；③发送调研通知（支持自定义通知模板）；④追踪填答状态；⑤截止前自动催办；⑥拉取答卷数据（API直连）；⑦计算本批次基准均值；⑧按模板生成部门/集团诊断报告。问卷包含麦肯锡组织健康度37题（10维度）+ 北森敬业度29题（核心敬业度+驱动满意度+开放问题）。
skillcode: survey-workflow
version: 1.2.0
---

# survey-workflow Agent

## 概述

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

---

## 📋 问卷结构

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

| 维度 | 题数 | 题目代码 |
|------|------|----------|
| 发展方向 | 3题 | Q_OHI_001~003 |
| 领导力 | 4题 | Q_OHI_004~007 |
| 工作氛围 | 4题 | Q_OHI_008~011 |
| 责任制度 | 3题 | Q_OHI_012~014 |
| 运营体系 | 5题 | Q_OHI_015~019 |
| 组织能力 | 4题 | Q_OHI_020~023 |
| 员工激励 | 4题 | Q_OHI_024~027 |
| 外部导向 | 4题 | Q_OHI_028~031 |
| 创新和学习 | 4题 | Q_OHI_032~035 |
| 赋能和心理安全 | 2题 | Q_OHI_036~037 |

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

**核心指标（敬业度8题）**
| 维度 | 题数 | 题目代码 |
|------|------|----------|
| 留任 | 2题 | Q_ENG_001~002 |
| 努力 | 2题 | Q_ENG_003~004 |
| 挑战 | 2题 | Q_ENG_005~006 |
| 组织赋能感 | 2题 | Q_ENG_007~008 |

**关键驱动因素（满意度19题）**
| 序号 | 维度 | 题目代码 | 题目内容 |
|------|------|----------|----------|
| 1 | 自主性 | Q_ENG_009 | 在工作中，我有充分的机会展现自己的能力所长 |
| 2 | 重视员工 | Q_ENG_010 | 公司在制定政策和制度的过程中，重视员工的意见和建议 |
| 3 | 职业发展 | Q_ENG_011 | 我相信我能在公司实现自己的职业目标 |
| 4 | 直接上级_沟通期望 | Q_ENG_012 | 我的直接上级能与我清晰沟通工作期望 |
| 5 | 直接上级_工作支持 | Q_ENG_013 | 我的直接上级能为我提供必要的工作支持 |
| 6 | 赞扬认可 | Q_ENG_014 | 当表现出色时，我能得到上级或同事们的肯定 |
| 7 | 薪酬福利 | Q_ENG_015 | 相对于我的付出，公司的薪酬福利水平是合理的 |
| 8 | 同事关系 | Q_ENG_016 | 同事间的沟通是坦诚的 |
| 9 | 挑战性 | Q_ENG_017 | 我的工作内容要求我不断提高自己的知识和技能 |
| 10 | 企业愿景 | Q_ENG_018 | 我清楚我的工作与公司发展目标间的关联 |
| 11 | 培训学习 | Q_ENG_019 | 公司鼓励员工进行持续性学习 |
| 12 | 绩效管理 | Q_ENG_020 | 我能定期收到清晰的工作反馈 |
| 13 | 沟通协作_团队合作 | Q_ENG_021 | 团队各成员能为了共同目标而紧密合作 |
| 14 | 工作资源 | Q_ENG_022 | 我能及时获取到工作所需的必要资源 |
| 15 | 工作生活平衡 | Q_ENG_023 | 在非工作时间也会积极参加各项工作，以保证工作的及时性 |
| 16 | 工作环境 | Q_ENG_024 | 公司提供了舒适的办公环境 |
| 17 | 创新 | Q_ENG_025 | 公司支持员工将新想法、新技能运用到工作中 |
| 18 | 推荐意愿 | Q_ENG_026 | 我愿意介绍正在求职的朋友加入公司 |
| 19 | 沟通协作_跨部门 | Q_ENG_027 | 公司鼓励跨部门间协作事务、共享信息与资源 |

**开放式问答（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`

**请求参数**：
```json
{
  "surveyId": "问卷ID",
  "employeeIdList": ["员工ID列表"],
  "replace": false,
  "sourceType": "来源类型"
}
```

| 参数 | 说明 |
|------|------|
| `replace=true` | 全量覆盖（替换已有名单） |
| `replace=false` | 增量导入（追加到已有名单）**← 追加人员时使用此参数** |
| `employeeIdList` | 不可为空 |

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

---

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

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

**步骤1：导入追加人员**
- 调用 `importSurveyTargets` 接口
- 设置 `replace=false`（关键参数，表示增量追加）
- 传入需要追加的员工ID列表

**步骤2：向追加人员发送通知**
- 调用 `sendNotify` 接口
- 传入新追加的员工ID列表
- 使用与初始通知相同或略作调整的通知文案

**完整示例**：
```python
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": "【追加通知】\n\n您已加入本次调研名单，请点击以下链接完成填答：\n\nhttps://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`

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

**典型调用流程**：
1. 调 `listUnsubmittedParticipants`（5.9）获取未通知人员
2. 调 `sendNotify`（5.5）发送通知
3. 记录发送结果

**响应结构**：
```json
{
  "resultCode": 1,
  "resultMsg": null,
  "data": {
    "batchNo": "批次号",
    "successCount": 3,
    "failCount": 0
  }
}
```

---

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

**相关 API**：
| 操作 | 路径 | 说明 |
|------|------|------|
| 查已提交名单 | `GET /questionnaire/surveys/participants/submitted/list?surveyId={id}` | 活动名单口径-已提交 |
| 查未提交名单 | `GET /questionnaire/surveys/participants/unsubmitted/list?surveyId={id}` | 活动名单口径-未提交 |
| 查单个提交状态 | `GET /questionnaire/submission/status?surveyId={id}&employeeId={empId}` | 查询某员工是否已提交 |
| 分页提交列表 | `POST /questionnaire/submission/list` | 按部门筛选分页查看 |

---

### 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章）— 必须完整包含：

| 章节 | 必须包含的内容 |
|------|--------------|
| 第1章 | 核心结论速览：含 OHI 总分/敬业度总分/满意度总分 + 与总部平均分对比表；Top3 优势维度 + Top3 改进维度；与总部差距最大的维度 |
| 第2章 | 10维度得分概览表（含本部门得分/总部平均/差距/评级）+ Mermaid 雷达图（用 `mermaid` 格式，dept vs 总部平均两条曲线） |
| 第3章 | 核心敬业度4子维度（含总部对比）+ 驱动满意度全部20项维度（含总部对比），缺一不可 |
| 第4章 | 优势保持（详细说明）+ 改进方向（根因 + 措施 + 时间三要素必须齐全） |
| 第5章 | 情感分析表（负面/中性/正面数量和占比）+ 高频主题与典型原话表 |
| 第6章 | 部门负责人行动清单（行动项/负责人/完成时间/成功标准，四列必须完整） |
| 第7章 | HRBP支持资源 + 人力资源中心资源 + 建议下一步动作 |

---

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

| 章节 | 必须包含的内容 |
|------|--------------|
| 第1章 | 核心结论速览：含 OHI 总分/敬业度总分；Top3 优势维度 + Top3 改进维度；员工最关注的3个问题；核心建议 |
| 第2章 | 调研概况与样本结构：填答概况表（发放数/回收数/填答率/平均时长）+ 样本分布（按部门/司龄/职级） |
| 第3章 | OHI分析：Mermaid雷达图（集团 vs 行业基准）+ 10维度得分详表（排名 + 评价）+ 题目级详细分析 |
| 第4章 | 敬业度分析：核心敬业度4子维度得分 + 驱动满意度全部维度 + 与敬业度相关性标注 + 结论 |
| 第5章 | 交叉分析：各部门得分对比表 + 管理者vs员工对比（如有数据）+ 不同司龄群体对比（如数据支持） |
| 第6章 | 开放式反馈分析：情感分析（正面/中性/负面占比）+ 高频主题词Top10 + 各主题提及频次与情感倾向表 |
| 第7章 | 核心发现与改进建议：优势领域 + 主要短板 + 根因 + 改进优先级排序表（P0/P1/P2，含责任主体/措施/预期效果/建议时间） |
| 第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       ← 集团报告生成
```

**运行命令**：
```bash
# 部门报告（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`，确认关键词均为有效搭配。

---

## 使用方式

### 方式一：脚本式（本地数据）
```bash
# 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 数据。

**推荐流程（通知 → 催办 → 复盘）**：
```python
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 索引速查**：
| 功能 | 方法 | 路径 | 小节 |
|------|------|------|------|
| 查询提交状态 | GET | `/questionnaire/submission/status` | 5.1 |
| 查询提交详情 | GET | `/questionnaire/submission/detail` | 5.2 |
| 提交列表分页 | POST | `/questionnaire/submission/list` | 5.3 |
| 评分统计 | GET | `/questionnaire/statistics` | 5.4 |
| **发送通知（发汇报）** | POST | `/questionnaire/notify/send` | **5.5** |
| **催办** | GET | `/questionnaire/notify/pressure` | **5.6** |
| 条件已提交名单 | POST | `/questionnaire/surveys/submitted` | 5.7 |
| **已提交人员列表** | GET | `/questionnaire/surveys/participants/submitted/list` | **5.8** |
| **未提交人员列表** | GET | `/questionnaire/surveys/participants/unsubmitted/list` | **5.9** |
| 导入活动名单 | POST | `/questionnaire/admin/surveys/targets/import` | 5.10 |

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

---

## 配置文件 (config/config.json)

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

---

## 数据文件格式

### 员工名单 Excel
| 工号 | 姓名 | 部门 | 中心 |
|------|------|------|------|
| 001 | 张三 | 人力资源部 | 专业责任中心 |

### 问卷数据 Excel
| 工号 | 姓名 | 部门 | 中心 | Q_OHI_001 | Q_OHI_002 | ... | Q_ENG_001 | ... | 提交时间 |
|------|------|------|------|-----------|-----------|-----|-----------|-----|----------|

---

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

每次调研视为一个独立批次，**所有操作必须归档到对应批次目录**，不得散落在 `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 必须字段

```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 请求头
```

### 认证命令

```bash
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

```python
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="...", ...)
```

### 常见错误

| 错误 | 原因 | 解决方法 |
|------|------|----------|
| `401: 缺少访问凭证` | 直接用 app_key 当 token | 用 login.py 换成 access-token |
| `401: Token校验失败` | token 已过期或用错了 | 重新用 login.py 换取新 token |
| `活动名单为空` | 未导入名单 | 先调 `import_targets` 再发通知 |

## 依赖

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

---

## 维护说明

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

FILE:open API 文件/问卷系统API调用说明.md
# 问卷系统 Open API 调用说明

**配套文档**：
- [《问卷开放接口API说明》](./问卷开放接口API说明.md)（questionnaire 下游原始接口与数据结构定义）
- [《BP系统API调用说明》](./BP系统API调用说明.md)（调用说明体例参考）
- [《OPS系统API调用说明》](./OPS系统API调用说明.md)（本仓新增文档体例参考）

本文承担：**修订记录、能力概述、通用约定、接口索引、编排场景、注意事项**；字段级结构以《问卷开放接口API说明》为准。

---

## 修订记录

| 版本 | 日期 | 变更摘要 | 变更人 |
|------|------|----------|--------|
| 1.0 | 2026-04-21 | 基于本次新增 `QuestionnaireController` + `QuestionnaireFeign` 生成调用说明 | OpenAPI-Agent |
| 1.1 | 2026-04-21 | 新增管理端导入接口（`/questionnaire/admin/surveys/targets/import`）调用说明 | OpenAPI-Agent |
| 1.2 | 2026-04-21 | `sendNotify` 请求体新增通知文案字段 `notifyMarkdown` | OpenAPI-Agent |
| 1.3 | 2026-04-21 | `sendNotify` 请求体新增通知标题字段 `notifyTitle`（sendV2 场景必传） | OpenAPI-Agent |

---

## 一、概述

本服务在 `open-api` 网关层新增了问卷聚合控制器：`QuestionnaireController`，对外统一暴露 `/questionnaire/**` 路径，并透传到下游 `questionnaire` 服务的 `/open/**` 接口。

当前开放能力共 10 个（与当前代码一致）：

1. `getSubmissionStatus` — 查询提交状态
2. `getSubmissionDetail` — 查询提交详情
3. `listSubmissions` — 查询提交列表（分页）
4. `getStatistics` — 查询统计数据
5. `sendNotify` — 发送问卷活动通知
6. `pressureNotify` — 问卷活动催办
7. `listSubmittedByCondition` — 查询已提交人员（按条件，不分页）
8. `listSubmittedParticipants` — 活动名单维度-已提交人员列表
9. `listUnsubmittedParticipants` — 活动名单维度-未提交人员列表
10. `importSurveyTargets` — 导入问卷活动名单（管理端补充）

---

## 二、给 AI / Agent 的阅读顺序

1. 先看本文 **四、通用说明**（鉴权头、统一响应结构、路径规则）。
2. 再看本文 **五、接口清单（索引）**（本服务路径与下游路径映射）。
3. 需要字段细节时，再看 [《问卷开放接口API说明》](./问卷开放接口API说明.md) 的“六、公共数据结构”。
4. 需要调用链路编排时，看本文 **七、关键业务流程说明**。

---

## 三、关键词与别名

| 用语 | 英文路径片段 | 说明 |
|------|--------------|------|
| 问卷 | `survey` | 问卷主标识为 `surveyId` |
| 提交记录 | `submission` | 提交主键为 `submissionId` |
| 已提交名单 | `submitted` | 可按条件或按活动名单口径查询 |
| 未提交名单 | `unsubmitted` | 活动名单口径下的差集人员 |
| 通知/催办 | `notify` / `pressure` | 问卷活动触达能力 |
| 名单导入 | `targets/import` | 活动名单导入，支持增量与全量覆盖 |

---

## 四、通用说明

### 4.1 访问地址

```text
https://{域名}/open-api/{接口地址}
```

### 4.2 环境信息

| 环境 | 域名                                          |
|------|---------------------------------------------|
| 生产环境 | `https://sg-al-cwork-web.mediportal.com.cn` |
| 测试环境 | `https://cwork-api-test.xgjktech.com.cn` |

### 4.3 公共请求头

| Header | 说明 | 是否必填 |
|--------|------|----------|
| `appKey` | 应用访问凭证（网关统一校验） | 是（兼容性见下） |

**兼容性**：部分场景下若传入合法 `access-token`，即使不带 `appKey` 也可兼容通过（由网关鉴权链路处理）。

### 4.4 通用响应结构

所有接口统一返回 `Result<T>`：

```json
{
  "resultCode": 1,
  "resultMsg": null,
  "data": null
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `resultCode` | Integer | `1` 表示成功，其他值表示失败 |
| `resultMsg` | String | 失败时返回可读错误信息 |
| `data` | T | 业务数据 |

### 4.5 时间字段口径

- 与下游文档一致：问卷域时间字段使用**毫秒时间戳**（例如 `submitTimeMillis`）。

---

## 五、接口清单（索引）

> 下表左侧“本服务路径”为 `open-api` 暴露路径（`QuestionnaireController`），右侧“下游路径”为 `questionnaire` 服务路径（`QuestionnaireFeign`）。

| 小节 | 规范命名 | 方法 | 本服务路径 | 下游路径 | 读写 | 摘要 |
|------|----------|------|------------|----------|------|------|
| 5.1 | getSubmissionStatus | GET | `/questionnaire/submission/status` | `/open/submission/status` | 读 | 查询提交状态 |
| 5.2 | getSubmissionDetail | GET | `/questionnaire/submission/detail` | `/open/submission/detail` | 读 | 查询提交详情 |
| 5.3 | listSubmissions | POST | `/questionnaire/submission/list` | `/open/submission/list` | 读 | 提交列表分页 |
| 5.4 | getStatistics | GET | `/questionnaire/statistics` | `/open/statistics` | 读 | 评分统计 |
| 5.5 | sendNotify | POST | `/questionnaire/notify/send` | `/open/notify/send` | 写 | 发送活动通知 |
| 5.6 | pressureNotify | GET | `/questionnaire/notify/pressure` | `/open/notify/pressure` | 写 | 问卷催办 |
| 5.7 | listSubmittedByCondition | POST | `/questionnaire/surveys/submitted` | `/open/surveys/submitted` | 读 | 条件已提交名单 |
| 5.8 | listSubmittedParticipants | GET | `/questionnaire/surveys/participants/submitted/list` | `/open/surveys/participants/submitted/list` | 读 | 活动名单口径已提交 |
| 5.9 | listUnsubmittedParticipants | GET | `/questionnaire/surveys/participants/unsubmitted/list` | `/open/surveys/participants/unsubmitted/list` | 读 | 活动名单口径未提交 |
| 5.10 | importSurveyTargets | POST | `/questionnaire/admin/surveys/targets/import` | `/admin/surveys/targets/import` | 写 | 导入活动名单（管理端） |

---

## 六、推荐拉取路径（Agent）

**路径 A（状态先行）**：`5.1 -> 5.2`  
适合已知员工/提交记录，先判定是否提交，再拉详情。

**路径 B（统计看板）**：`5.4`  
直接获取整卷或维度统计，用于看板与 AI 摘要。

**路径 C（名单运营）**：`5.5 -> 5.6 -> 5.8/5.9`  
先通知，再催办，最后复盘已提交与未提交名单。

**路径 D（明细导出）**：`5.3` 或 `5.7`  
- 需要分页：走 `5.3`  
- 需要按条件全量已提交：走 `5.7`

**路径 E（名单初始化）**：`5.10 -> 5.5 -> 5.6`  
先导入活动名单，再发送通知，最后对未提交对象催办。

---

## 七、关键业务流程说明

### 场景一：查询某员工是否已完成问卷

1. 调 `5.1`：`GET /questionnaire/submission/status?surveyId={id}&employeeId={empId}`
2. 若 `submitted=true` 且返回 `submissionId`，继续调 `5.2` 拉取答卷详情

### 场景二：按部门筛选提交明细并分页查看

1. 调 `5.3`：`POST /questionnaire/submission/list`
2. 请求体带 `surveyId + department/departmentId + pageNum/pageSize`
3. 基于响应中的 `records` 渲染列表

### 场景三：问卷活动通知与催办闭环

1. 调 `5.5` 发送通知（可按员工或部门筛选触达范围；可通过 `notifyTitle`/`notifyMarkdown` 自定义标题与文案）
2. 调 `5.6` 对未提交且已通知人员发起催办
3. 调 `5.8` / `5.9` 分别获取活动名单口径下的已提交/未提交名单做复盘

### 场景四：统计分析（整卷/维度）

1. 调 `5.4`，传 `groupBy=survey` 获取整卷分值分布
2. 调 `5.4`，传 `groupBy=dimension` 获取分维度分值分布

### 场景五：管理端导入活动名单

1. 调 `5.10`：`POST /questionnaire/admin/surveys/targets/import`
2. 请求体包含：`surveyId`、`employeeIdList`、`replace`、`sourceType`
3. 当 `replace=true` 时按“全量覆盖”导入；`replace=false` 时按增量导入
4. 导入完成后可衔接 `5.5` 发送通知

---

## 八、注意事项

1. **路径不要混淆**：外部调用本服务必须用 `/questionnaire/**`，`/open/**` 是下游 `questionnaire` 内部路径。
2. **ID 精度**：`surveyId/submissionId/employeeId` 等 Long 字段在 JS 端建议按字符串处理。
3. **筛选条件优先级**：提交状态查询中 `employeeId` 与 `employeeName` 同时传入时，按下游约定优先工号。
4. **名单口径**：活动名单维度接口（`5.8/5.9`）与条件筛选接口（`5.7`）口径不同，报表侧不要混用。
5. **催办属于副作用接口**：`5.6` 虽为 GET，但业务语义为“触发催办”，请按写操作治理调用频率与审计。
6. **导入接口需要有效员工身份**：`5.10` 若缺少登录员工上下文，可能返回“未登录或缺少员工身份”。
7. **导入列表不能为空**：`employeeIdList` 为空会触发业务错误“员工ID列表不能为空”。
8. **通知文案字段**：`5.5` 新增 `notifyMarkdown`，建议控制文本长度并使用简洁 Markdown（纯文本同样可用）。
9. **通知标题字段**：`5.5` 新增 `notifyTitle`，控制工作汇报 `main`；在 sendV2 场景应作为必填参数处理。

---

## 九、附录：与下游接口编号对照

本服务 10 个接口与 [《问卷开放接口API说明》](./问卷开放接口API说明.md) 第四章编号一一对应：

- 本文 `5.1~5.10` 对应下游文档 `4.1~4.10`。