# 活动信息发布模块 · 功能与接口说明 v1

> 武校家校信息发布 —— 活动信息发布子模块。本文档面向后端联调与前端维护，与代码同步维护。
> 前端契约：`src/types/activity.ts`、`src/api/module/activity.ts`；本地 mock：`src/assets/mock/activityapi.ts`。

## 一、页面与路由

| 页面 | 路由 | 组件 | 关键交互 |
| --- | --- | --- | --- |
| 我发布的 | `/list` | `ActivityList.vue` | 状态标签（全部/报名中/已截止/已结束/草稿）、时间范围 + 分类 + 关键字筛选、发布活动入口 |
| 全部活动 | `/activitylist` | `ActivityList.vue` | 同组件；不传 `scope=user`，展示全量 |
| 发布活动 | `/list/new` | `NewActivity.vue` | `?serid=` 编辑、`?fid=` 复用；立即发布 / 存草稿 / 定时发布 |
| 活动详情 | `/list/detail`、`/activitylist/detail` | `ActivityDetails.vue` | `type=0` 管理视角（阅读 + 回执进度、报名情况、编辑、复用、打印）；`type=1` 查看视角（标读） |
| 报名情况 | `/signups` | `Signups.vue` | 活动下拉切换、回执状态筛选、汇总卡、按班级分组名单、回执详情、代为确认/取消、催报名、导出 CSV |
| 活动统计 | `/stats` | `ActivityStats.vue` | 总量卡、分类分布、月度趋势、发布人分布、我发布活动的回执表 |
| 应用设置 | `/setting` | `ActivitySetting.vue` | 主办部门（拖拽排序 / 启停 / 内联改名）+ 自定义组（组成员设置） |
| 活动广场 | `/par/activities` | `ParentActivities.vue` | 家长端；标签（全部/待回执/已报名/已结束）+ 关键字；右侧详情 + 报名回执弹窗 |
| 我的报名 | `/par/mine` | `ParentActivities.vue` | 同组件，`meta.initTab=signed` |

菜单 ↔ 路由通过 `meta.modId` 契约绑定（`src/router/routes.ts` 头部注释为唯一口径来源）：

```
2  我发布的      /list
3  全部活动      /activitylist
4  活动统计      /stats
21 应用设置      /setting
25 报名情况      /signups
31 活动广场      /par/activities
32 我的报名      /par/mine
22 发布活动      /list/new            （深层子页，parentId=2，不在菜单）
23 活动详情      /list/detail         （parentId=2）
24 活动详情      /activitylist/detail （parentId=3）
```

## 二、枚举口径

| 字段 | 取值 | 含义 |
| --- | --- | --- |
| `actStatus` | `draft` / `signup` / `closed` / `finished` | 草稿 / 报名中 / 已截止 / 已结束 |
| `receiptMode` | `none` / `signup` / `confirm` | 仅通知 / 需报名 / 需确认（打开即自动确认） |
| `status`（回执记录） | `none` / `signed` / `confirmed` / `canceled` | 未回执 / 已报名 / 已确认 / 已取消（请假） |

派生量（`ActivityProgress`）：`should` 应收、`signed` 已报名、`confirmed` 已确认、`canceled` 已取消、
`unsigned` 未回执、`signupRate` 回执率(%)、`quota` 名额上限、`usedQuota` 已占名额、`full` 是否满额。

`receiptMode = none` 或 `actStatus = draft` 时 `progress` 为 `null`（不产生回执记录，只统计已读）。

## 三、接口清单

统一响应 `{ code, msg, data }`，`code` 为 0 表示成功，由 `utils/alova/alova-core.ts` 解包为 `data`。

### 基础 / 布局（`/api/base`）

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/api/base/GetUserInfo` | 当前登录用户 |
| GET | `/api/base/GetUserMod` | 已授权模块（左侧菜单） |
| POST | `/api/base/SetRole` | 切换视角 `{ as: "teacher" \| "parent" }`，需在拉取用户信息前调用 |
| GET | `/api/base/GetSchoolAll` | 教师组织树（选择用户） |
| GET | `/api/base/GetClassTree` | 年级 → 班级树（发布对象到班级一级，叶子带 `studentCount`） |
| POST | `/api/base/FileUpload` | 附件上传 |

### 活动域（`/api/activity`）

| 方法 | 路径 | 入参 | 说明 |
| --- | --- | --- | --- |
| GET | `/List` | `ActivityQuery` | 家长端收件箱（已发布 + 面向本班） |
| GET | `/SendList` | `ActivityQuery`（`scope=user` 只看自己） | 我发布的 / 全部活动 |
| GET | `/Detail` | `serid, type` | `type=1` 标读；`type=0` 不标读（管理视角） |
| GET | `/GetDetail` | `serid` | 编辑/复用回显，不标读 |
| GET | `/GetNextPrev` | `serid, type` | 上一篇/下一篇 id |
| GET | `/ReadDetail` | `serid` | 阅读情况：按年级分组的班级读/未读 |
| POST | `/Create` | `ActivityRequest` | 新建，返回活动 id |
| POST | `/Edit` | `ActivityRequest`（含 `sourceId`） | 编辑 |
| POST | `/Delete` | `number[]` | 批量删除（级联清回执记录） |
| POST | `/InitializeRed` | —— | 一键全部已读 |
| POST | `/UserPull` | `serid` | 撤回（家长端不可见） |
| POST | `/SetTopmost` | `serid, topmost` | 置顶 / 取消置顶 |
| POST | `/Expedite` | `serid` | 催办未读，返回 `{ reminded }` |
| POST | `/ReceiveClasses` | `serid, classes` | 追加接收班级（补发，自动补回执记录） |
| GET | `/Statis` | `startTime?, endTime?` | 活动统计 |
| GET | `/Signups` | `serid, signupStatus` | 报名回执名单（按班级分组 + 汇总） |
| GET | `/SignupDetail` | `signupId` | 单条回执详情 |
| POST | `/Review` | `{ signupId, action: "confirm"\|"cancel"\|"waitlist", remark? }` | 处理回执 |
| POST | `/Remind` | `serid` | 催报名，返回 `{ reminded }` |
| GET | `/ExportSignups` | `serid` | 导出回执名单（JSON 包装 `{ csv }`，csv 为带 BOM 的 CSV 文本，前端取 csv 字段生成文件下载） |
| GET | `/MyActivities` | `ActivityQuery` | 家长端活动广场（含分桶计数 `buckets`） |
| GET | `/MySignup` | `serid` | 家长端活动详情 + 我的回执（同时标读） |
| POST | `/Signup` | `{ serid, joinCount, guardianName, guardianPhone, remark }` | 家长报名 / 修改回执 |
| POST | `/CancelSignup` | `serid` | 取消报名 |

### 字典 / 联系组

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/api/dict/List?type=1` | 主办部门下拉（仅启用） |
| GET | `/api/dict/ManageList?type=dept` | 主办部门管理列表 |
| POST | `/api/dict/Add` / `Update` / `Delete` / `Sort` | 主办部门增删改与排序 |
| GET | `/api/contacts/GetGroup` | 自定义组分页 |
| POST | `/api/contacts/AddGroup` / `EditGroup` / `DelGroup` | 自定义组增删改 |
| GET | `/api/contacts/GetContactsTea` | 组内成员（`page=0&count=0` 取全部） |
| POST | `/api/contacts/SetContactsTea` | 设置组内成员 |
| GET | `/api/contacts/GetGroupTree` | 组 → 成员树（选人弹窗 tab） |

### 文件

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| POST | `/api/file/UploadImage` | 富文本内嵌图片上传 |
| GET | `/api/file/Preview` | 文件预览 |
| GET | `/api/file/Down` | 附件下载 |
| GET | `/api/activity/AllFileDown` | 全部附件打包下载 |

## 四、关键实现约定

1. **表单参数传递**：`postForm` 会把参数同时拼进 URL query。后端 `@RequestParam` 都能接收；本地 `vite-plugin-mock`
   不解析 `application/x-www-form-urlencoded` body，靠 query 才能取到参数（不影响线上）。
2. **`@RequestBody` 接口**（`Create` / `Edit` / `Delete` / `Signup` / `Review`）走 `postJSON`，mock 侧用 `bodyOf(body, query)` 合并取参。
3. **接收班级**：`receiveList = "ALL"` 或班级 id 逗号串；`targetClassIds()` 统一解析。
4. **已读判定**：以班级为粒度（`classRead: string[]`）；应收 / 已读人数按班级 `studentCount` 累加。
5. **端分离**：`App.vue` 依据路由前缀（`/par` → 家长端）调用 `SetRole` 切换视角并重新拉取 `GetUserMod`，
   菜单与用户信息随视角变化；家长端菜单提供「发布端（教师）」入口便于返回。
6. **表格高度**：`Utils.useTableHeight({ isSearch, isTabs, isPage, isOperat })`，头部 112（自身 header 56 + 面包屑 56）。
7. **操作列图标**：`Utils.operatingHandle(h, 提示, iconClass, cb)`，图标取自 `src/assets/styles/icons.css` 的 bsch-icons 字体。