# 家校宿舍通知（dorm-notice）

武校家校信息发布模块 —— **宿舍通知** 子模块。用于德育处 / 生活管理科 / 宿管向住宿生家长发布宿舍类通知，
并回收家长的**已读**与**回执**（确认知悉 / 按单据填报）。

> 以 `D:\项目管理\FamilyActivity`（家校活动信息发布）为模板工程改造：保留其 Vue3 + Vite + view-ui-plus + alova +
> vite-plugin-mock 技术栈、布局壳层、权限菜单契约、表格/分页/选人/富文本/附件等基础设施，业务域整体替换为「宿舍通知」。
> 完整的功能与接口说明见 [`docs/宿舍通知模块-功能与接口说明-v1.md`](docs/宿舍通知模块-功能与接口说明-v1.md)。

## 快速开始

```bash
# 纯前端演示（内置 mock 数据，无需后端）
npm run dev:mock

# 联调本地后端
npm run dev

# 构建（产物直出 dist/）
npm run build
```

mock 模式默认访问 <http://localhost:8078/>（端口被占用时 Vite 会自动改用 8079，以控制台输出为准）。

> 环境要求：Node 20（`package.json` 里 `nodeversion: 20.19.4`）。

## 与「活动」模块的核心差异

| 维度 | 活动信息发布 | 宿舍通知 |
| --- | --- | --- |
| 收件人粒度 | 班级（`receiveType=class`） | **宿舍房间**（`receiveType=room`） |
| 应收人数口径 | 班级学生数 | 覆盖房间的**实际入住床位数** |
| 回执形态 | 报名（人数 + 随行 + 费用） | 仅通知 / 需确认（打开即确认） / 需填报（按单据字段） |
| 回执字段 | 固定 | **动态**，由发布方声明 |
| 紧急程度 | 无 | 普通 / 重要 / 紧急（家长端置顶标红） |
| 宿管协同 | 无 | `needSupervisor` 需宿管到场配合 |
| 覆盖统计 | 按班 | 按**楼栋**统计房间数 / 床位数 |

**为什么必须下沉到房间**：武校寄宿制下同班学生分住不同楼栋房间，按班级下发会让「1号楼 3 层明日停水」触达全校家长，
真正受影响的房间只占少数，回执率也失去管理意义。

## 功能范围

### 发布端（教师 / 宿管 / 德育处）

| 菜单 | 路由 | 说明 |
| --- | --- | --- |
| 我发布的 | `/list` | 自己发布的通知，按流程状态分标签（全部/已发布/已截止/已结束/草稿） |
| 全部通知 | `/noticelist` | 管理端全量列表（同一组件，去掉 `scope=user`） |
| 发布通知 | `/list/new` | 新建 / 编辑 / 复用再发；支持存草稿与定时发布 |
| 通知详情 | `/list/detail`、`/noticelist/detail` | `type=0` 管理视角（已读进度 + 回执进度 + 编辑/打印/复用）；`type=1` 查看视角 |
| 回执情况 | `/receipts` | 按「楼栋 · 房间」分组的回执/填报名单 + 汇总卡 + 代确认/取消/退回 + 催办 + 导出 CSV |
| 通知统计 | `/stats` | 总量卡、类型分布、月度趋势、楼栋覆盖、发布人分布、我发布通知的回执明细 |
| 宿舍设置 | `/setting` | 通知类型字典（拖拽排序/启停）+ 宿舍楼栋房间台账（含住宿生床位安排 / 宿舍长指定）+ 自定义组（宿管/生活老师） |

### 家长端（家长 / 学生，演示用）

| 菜单 | 路由 | 说明 |
| --- | --- | --- |
| 宿舍通知箱 | `/par/notices` | 左侧分桶列表（全部/待回执/已回执/已结束）+ 右侧详情与回执操作 |
| 我的回执 | `/par/mine` | 同一组件，默认落「已回执」 |

### 三档回执方式

- **仅通知**（`none`）：阅读即知悉，不产生回执记录，只统计已读。适合作息调整、停水停电、卫生检查、违规通报、假期安排。
- **需确认**（`confirm`）：家长**打开通知详情即自动确认**，无需点击；仅在自动确认失败时给手动兜底按钮。
- **需填报**（`fill`）：家长按发布方声明的字段提交单据（留宿申请 / 家长探视 / 宿舍调整），截止前可修改、可取消。

### 三套预设填报模板

留宿申请单、家长探视预约单、宿舍调整确认单 —— 字段口径与后端一致，可一键套用后按需增删。

## 目录结构（本模块相关）

```
src/
├── api/module/dorm.ts          # 接口封装：baseApi / noticeApi / dormApi / settingApi
├── types/dorm.ts               # 类型契约（枚举、VO/DTO、请求入参）
├── assets/mock/dormapi.ts      # 全量 mock（约 2200 行，确定性伪随机）
├── views/dorm/
│   ├── NoticeList.vue          # 我发布的 / 全部通知
│   ├── NewNotice.vue           # 发布通知（含宿舍选择器、填报字段编辑器）
│   ├── NoticeDetails.vue       # 通知详情
│   ├── Receipts.vue            # 回执情况
│   ├── NoticeStats.vue         # 通知统计
│   ├── DormSetting.vue         # 宿舍设置（通知类型 / 楼栋房间 / 自定义组）
│   └── ParentNotices.vue       # 家长端通知箱
├── router/routes.ts            # 路由 + modId 契约
├── assets/config/menu.ts       # 本地菜单兜底
└── utils/menuRoute.ts          # 平台模块配置 → 内部路由的统一解析器
docs/宿舍通知模块-功能与接口说明-v1.md
```

## mock 数据（演示要点）

- 4 栋宿舍楼：1/2 号男生（6+5 层 × 8 间 × 8 床）、3 号女生（4 层 × 6 间 × 6 床）、4 号武术特长班（3 层 × 6 间 × 4 床）
- `roomId = buildingId*10000 + floor*100 + index`，如 `10305` = 1 号楼 3 层 05 房（房间号 `305`）
- 1 床 1 生，含武校风格姓名、文化班 + 套路表演班/散打竞技班/拳击班混合编排、家长信息
- 14 条通知覆盖 13 种类型 × 4 种流程状态 × 3 档回执方式 × 3 种紧急程度，含草稿 / 已撤回 / 定时未到 / 已截止等边界
- 家长端演示身份固定为 **1 号楼 305 室** 的第一位学生，只看该房间命中的通知
- 写操作（发布、编辑、删除、处理回执、提交回执）都会改内存数据，刷新后行为一致；重启 dev server 复位

## 接入后端时需改的地方

1. `vite.config.ts` 中 `/api` 代理 target —— 现仍指向模板的 `familyactivity` 上下文，需换成本模块后端。
2. `src/assets/config/menu.ts` —— 本地菜单兜底，接入 `GetUserMod` 后以接口返回为准（`modId` 契约见路由注释）。
3. `src/assets/mock/index.ts` —— prod mock 入口，正式构建不启用（`localEnabled: mode === "mock"`）。