---
name: huanxi-admin-module
description: "寰汐管理端模块与任务：全量查模块任务、建模块、改模块状态、整组配置成员、跨模块任务管理。当用户说「建个模块」「把某人加进模块」「全公司任务情况」「关掉这个模块」时使用。"
---

# 寰汐管理端 · 模块与任务

**前置：先读 `huanxi-admin-shared`。**

全量视角，不受「我参不参与」过滤。

---

## 查

```
module_query(status_category?, q?)        全量模块，带负责人与成员数
module_get(module_ids=[...])              详情含成员名单与各自角色
task_query(module_ids?, assignee_ids?, status_category?, priority?, q?)
task_get(task_ids=[...])
```

过滤维度都收列表，一次查多个比循环调用好。

---

## 建模块

```
module_create(name, type_id, leader_user_id, description?)
```

`type_id` 先 `dict_get(kinds=["module_types"])` 取，`leader_user_id` 用 `user_query` 取。
创建后会自动生成该模块的「杂记」任务，承载不值得单独建任务的零散工作。

---

## 改模块

```
module_update(module_id, name?, description?, status_option_id?)
```

⏸ **切到「已取消」有副作用**：级联取消该模块下全部未完成任务，并给成员发飞书通知。
这不是可撤销的操作，确认清楚再调。

模块**删除**不在本端点——那是纠错场景（建错了），需要在后台确认。

---

## 成员整组配置

```
module_set_members(module_id, members=[{user_id, role}, ...])
```

⏸ **替换语义**：不在名单里的现有成员**会被移除**。正确做法：

```
1. module_get 拿现有名单
2. 在现有名单基础上做改动（加人/改角色/去人）
3. 把完整的最终名单整组传回
4. 先把「改完会变成谁、谁会被移除」说给用户听，确认后再调
```

返回的 `added` / `role_changed` / `removed` 三组是本次实际发生的变更，
用它向用户复述结果。

一人一模块只能有一个角色（`leader` / `reviewer` / `member`）。新加入的成员会收到飞书通知。

---

## 任务

```
task_create(module_id, tasks=[{title, ...}])
task_update(updates=[{id, status_option_id?, progress?, priority?, ...}])
task_set_assignees(task_id, user_ids=[...])
```

- 改状态先 `dict_get` 取 task 类型的 `status_option_id`
- 状态与进度**有联动，只传一个就够**（进度 100 自动完成；已完成的调低进度自动回落）
- 非叶子任务（`progress_readonly` 为 true）不能直接设进度，要改它的子任务
- `task_set_assignees` 是**替换**不是追加，同 `module_set_members` 的注意事项

任务删除与跨模块转移不在本端点。