Files
shanxia2.0/docs/superpowers/specs/2026-08-14-duty-schedule-design.md
T

206 lines
8.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 值班排班(日历 + 公开链接抢班)— 设计文档
> **日期**: 2026-08-14
> **状态**: 待实现
> **仓库**: shanxia2.0(`backend/` + `web-admin/`)
> **方案**: 方案 1 —「日排班 + 班次名额 + 公开 Token 链接」
> **UI 原型**: `docs/demos/duty-schedule-v1-demo.html`(管理端)、`docs/demos/duty-h5-grab-demo.html`(公开 H5)
> **权威对照**: Fresh Mint(`docs/web-admin-ui-spec-fresh-mint.md`)、公开页可参考运输计划司机免登录(`/#/public/pl/transport/{token}`)
## 背景
总经理需要按日历安排值班(早班 / 晚班 / 值班等),可设定各班次人数,并可直接指定系统用户;同时生成**按日**的公开链接,员工免登录填写姓名抢班,满员不可再抢。总经理在日历中可查看历史排班。
参考截图(仅视觉参考):`值班系统截图/`。第一版**不做**统计页。
## 已确认决策
| # | 决策 |
|---|------|
| D1 | 管理端在 **web-admin** 排班;员工通过 **公开 H5 链接**抢班 |
| D2 | **一天一个链接**(如「8 月 20 日值班」),每次配置某日即对应一条 token 链接 |
| D3 | H5 上将当日多个班次**独立罗列**,不做筛选,方便直接抢 |
| D4 | 抢班只填**姓名**;同名不拦截,靠总经理事后核对 |
| D5 | 总经理「直接安排」从**系统用户**选择 |
| D6 | 员工不能自己取消;总经理可删人、改名额/班次、关链接 |
| D7 | 有人报名后总经理仍可改(不整日锁定) |
| D8 | V1 只要**日历 + 历史排班**;统计页以后再说 |
| D9 | 班次类型**系统预置**(早班 / 晚班 / 值班),暂不可自定义 |
| D10 | 只能**按天**建:点日历某日 → 配置 → 生成该日链接(不做批量日期范围) |
| D11 | 同一天同一人**可以**占多个班次(早班 + 晚班互不影响) |
| D12 | 关链后重开仍用**原 token**(V1 不做「重置链接」) |
| D13 | 将 `capacity` 调到小于当前报名人数时**禁止保存**,须先删人 |
| D14 | 过往日期仍允许总经理修改(不做历史冻结) |
| D15 | 权限按**菜单权限**控制,不单独硬编码「总经理」角色名 |
## 方案选择
**采用方案 1(已确认)**:`duty_day` + `duty_slot` + `duty_assignment`,公开 token 对齐现有免登录链接模式。
未采用:扁平日历事件(名额与关链难控);纯列表无月历(不符合「按日历排班/看历史」)。
## 架构与边界
| 端 | 职责 |
|----|------|
| **web-admin** | 月历、按日配置、指定用户、复制/关闭链接、删人改班、历史翻月 |
| **公开页(web-admin `#/public/...`)** | token 打开当日抢班页;免登录;只填姓名提交 |
| **backend** | 租户隔离管理 API + 公开抢班 API;名额并发控制;路径加入加密排除列表 |
公开页落地建议:与司机免登录一致,挂在 web-admin hash 路由,例如 `/#/public/duty/{token}`;链接 Origin 使用现有 `PUBLIC_WEB_ORIGIN`(或等价配置)拼接。
```
duty_day (一天 = 一个 access_token)
└── duty_slot × N(morning / evening / duty,各有 capacity)
└── duty_assignment × M(source = assign | grab)
```
## 数据模型
表名前缀建议 `duty_`;均含门户公共字段(`id`, `tenant_no`, `order_num`, `remark`, `create_by`, `create_dept_id`, `create_time`, `update_by`, `update_time`, `del_flag`)。字段顺序:`id` → 业务字段 → 公共字段。软删。
### `duty_day`(值班日)
| 字段 | 说明 |
|------|------|
| `duty_date` | 值班日期;**同一 `tenant_no` 下唯一**(未删除) |
| `access_token` | 公开访问令牌;足够长、不可猜;租户内唯一 |
| `link_status` | `open` / `closed` |
### `duty_slot`(班次名额)
| 字段 | 说明 |
|------|------|
| `duty_day_id` | 所属值班日 |
| `shift_type` | 预置:`morning`(早班)/ `evening`(晚班)/ `duty`(值班) |
| `capacity` | 名额,≥ 1 |
约束:同一 `duty_day_id` + `shift_type` 唯一(未删除)。
### `duty_assignment`(占位)
| 字段 | 说明 |
|------|------|
| `duty_slot_id` | 所属班次 |
| `source` | `assign`(管理端指定)/ `grab`(H5 抢班) |
| `user_id` | 指定时必填;抢班为空 |
| `person_name` | 展示名(用户姓名或手填姓名) |
满员规则:该 slot 下未删除 assignment 数 `< capacity` 才可新增。
SQL 变更须同步维护 `docs/sql/`(与 `database-conventions` 一致)。
## Web 管理端
### 入口与权限
- 新菜单「值班排班」(具体挂载位置实现时定),按钮级权限可拆:查看 / 编辑 / 关链(最小也可合并为菜单权限,能进即可改)。
- UI:Fresh Mint;主色 `#10b981`;`label-position="top"`;弹窗无背景模糊。
- 模式:月历主视图;**不做统计页**(D8)。
### 月历
- 月切换 +「今天」。
- 日格摘要:班次 chip(类型 + 人名或 `已占/名额`);未配置显示未排班。
- 点击日期 → 配置弹窗(与 Demo 一致)。
### 配置某日
- 配置预置班次及 `capacity`(可只启用部分班次)。
- 从系统用户选择直接安排 → `source=assign`,写入 `user_id` + `person_name`;指定人数不得超过该班次剩余名额。
- 列表展示已报名,区分指定 / 抢班;支持删除 assignment。
- **复制链接**:`{PUBLIC_WEB_ORIGIN}/#/public/duty/{access_token}`。
- **关闭 / 打开链接**:改 `link_status`;关链后 H5 展示关闭态;日历仍可见数据。
- 缩容校验(D13):`capacity` 不得小于当前有效报名数。
- 去掉某班次(不再启用):若该 slot 仍有有效报名,**禁止删除/停用**,须先清空报名。
- 首次保存某日:创建 `duty_day` + slots,生成 `access_token`;再次保存更新 slots/安排,token 不变(D12)。
### 历史
- 翻月查看过往排班;过往日仍可编辑(D14)。
## 公开 H5
对齐原型 `docs/demos/duty-h5-grab-demo.html`;视觉用三墙 Token(`#0a9f6d`),与管理端色值不混用。
### 状态
| 状态 | 表现 |
|------|------|
| 可抢 | 班次卡片独立罗列;可填姓名提交;满员卡片禁用 |
| 提交成功 | 展示日期 / 班次 / 姓名摘要 |
| 链接关闭 | 「报名已关闭」 |
| token 无效 | 「链接无效或已失效」 |
### 规则
- 免登录;只填姓名(D4)。
- 不可自助取消(D6)。
- 同天可抢多个班次(D11)。
- 展示已报名姓名列表(便于员工感知剩余名额;同名风险已知晓)。
## API
### 管理端(登录 + 租户 + 数据权限按现有约定)
| 能力 | 说明 |
|------|------|
| 月历查询 | 按年月返回每日摘要(slots + assignments 精简) |
| 日详情 | 含链接状态、token/完整 URL、slots、assignments |
| 保存日配置 | 创建或更新 day/slots;校验缩容;可选写入 assign |
| 删除 assignment | 释放名额 |
| 开关链接 | `open` / `closed` |
用户选择器复用现有系统用户列表接口。
### 公开(免登录)
| 接口 | 说明 |
|------|------|
| `GET /api/public/duty/{token}` | 当日只读:日期、状态、各 slot 与已报名姓名 |
| `POST /api/public/duty/{token}/grab` | body: `{ shiftType, personName }`;`personName` 去首尾空格后非空且长度受限(建议 ≤20);校验开链与名额 |
须:
- 注册路由于 `app/api/__init__.py` 与 `app/main.py`。
- 公开路径加入 `API_ENCRYPT_EXCLUDE_PATHS`(及前端等价排除,若有)。
- 抢班在事务内检查人数后再插入,防止超卖。
- 错误:满员 / 已关闭 / token 无效 — 明确文案。
- V1:按 IP 或 token 做基础限流(实现时可用现有中间件或轻量计数)。
公开响应**不**返回其他日期或其他租户数据。
## 错误处理
| 场景 | 行为 |
|------|------|
| 抢班时刚好满员 | 返回失败,H5 提示名额已满并刷新人数 |
| 关链后提交 | 拒绝,展示关闭态 |
| 管理端缩容过大 | 保存失败,提示先删除多余人员 |
| 删除不存在的 assignment | 幂等或明确 404 |
## 测试要点(验收)
1. 按日配置早/晚/值班名额并复制链接,H5 可打开且班次独立展示。
2. 指定系统用户占名额;H5 抢班占名额;满员后不可再抢。
3. 关链后 H5 不可抢;打开后可继续抢(同 token)。
4. 管理端删人后名额释放;缩容小于当前人数被拒。
5. 同姓名可重复报名;同人同日可抢多个班次。
6. 翻月可看历史排班。
7. 租户隔离:A 租户链接不可看到 B 租户数据。
## 明确不做(V1)
- 统计页 / 按人汇总卡片
- 批量按日期范围建排班
- 自定义班次类型
- H5 登录、手机号、验证码
- 员工自助取消
- 重置 token
- 历史日期自动冻结
## 原型索引
- 管理端月历 + 配置:`docs/demos/duty-schedule-v1-demo.html`
- 公开 H5 多状态:`docs/demos/duty-h5-grab-demo.html`