Files
shanxia2.0/docs/superpowers/plans/2026-08-20-duty-shift-dict-time.md
T
zlwuandCursor 1850c7c3df docs: add duty shift dict and time implementation plan
Break the confirmed design into SQL, backend, admin UI, and public H5 tasks with TDD steps.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-20 20:44:39 +08:00

966 lines
30 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.
# 值班排班 · 字典类型 / 工作安排 / 时段 Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** 值班类型与工作安排改为 `sys_dict` 可扩展;`duty_slot` 增加时段与多选工作安排、独立备注;管理端与公开 H5 同步展示;存量数据可迁移。
**Architecture:** 种子字典 `duty_shift_type` / `duty_work_plan`;`duty_slot` 扩 `work_plans`、`start_time`、`end_time`、`cross_day`,原 `remark` 改为真正备注;保存日配置时 upsert 字典项;序列化返回 label / timeLabel;公开抢班校验改为「当日存在该 slot」。
**Tech Stack:** FastAPI + SQLAlchemy + Pydantic v2;Vue 3 + Element Plus;`pypinyin`(已有);pytest
**Spec:** `docs/superpowers/specs/2026-08-20-duty-shift-dict-time-design.md`
---
## 文件结构
| 操作 | 文件 | 职责 |
|------|------|------|
| Create | `backend/scripts/migrate_20260820_duty_shift_dict_time.sql` | 字典种子 + ALTER + 回填 |
| Modify | `backend/app/models/duty_models.py` | slot 新字段;保留 SHIFT_* 预置常量 |
| Modify | `backend/app/schemas/duty.py` | 放宽 shiftType;新增 workPlans / 时段字段 |
| Modify | `backend/app/services/duty_schedule.py` | 序列化、保存、grab、字典 ensure、timeLabel |
| Modify | `backend/app/api/duty.py` | 可选 `POST .../dict/ensure` |
| Modify | `backend/tests/test_duty_schedule.py` | 新行为单测 |
| Modify | `web-admin/src/api/duty.ts` | 类型与 save body |
| Modify | `web-admin/src/api/public-duty.ts` | 公开 slot 类型 |
| Modify | `web-admin/src/views/duty/schedule/index.vue` | 配置弹窗 + 月历统计 |
| Modify | `web-admin/src/views/public/duty/index.vue` | H5 展示时段/工作安排/备注 |
| Sync | `docs/sql/` | 迁移说明或片段备注(按仓库习惯追加脚本即可) |
---
### Task 1: SQL 迁移(字典 + ALTER + 回填)
**Files:**
- Create: `backend/scripts/migrate_20260820_duty_shift_dict_time.sql`
- [ ] **Step 1: 写迁移 SQL**
```sql
-- backend/scripts/migrate_20260820_duty_shift_dict_time.sql
-- 值班排班:字典类型/工作安排 + slot 时段与 work_plans
SET NAMES utf8mb4;
-- 1) 字典类型
INSERT INTO `sys_dict_type` (
`id`, `dict_name`, `dict_type`, `tenant_no`, `order_num`, `remark`,
`create_by`, `create_dept_id`, `create_time`, `update_by`, `update_time`, `del_flag`
) VALUES
(
'DUTYDICTTYPE00000000000000000001',
'值班类型',
'duty_shift_type',
'shanxia2.0',
90,
'值班排班班次类型',
'',
'',
NOW(),
'',
NOW(),
0
),
(
'DUTYDICTTYPE00000000000000000002',
'值班工作安排',
'duty_work_plan',
'shanxia2.0',
91,
'值班排班工作安排',
'',
'',
NOW(),
'',
NOW(),
0
)
ON DUPLICATE KEY UPDATE `dict_name` = VALUES(`dict_name`);
-- 若库无基于 id 的 upsert,改用 NOT EXISTS 插入(MySQL 5.7):
-- INSERT INTO ... SELECT ... FROM DUAL WHERE NOT EXISTS (SELECT 1 FROM sys_dict_type WHERE dict_type='duty_shift_type' AND tenant_no='shanxia2.0' AND del_flag=0);
INSERT INTO `sys_dict_data` (
`id`, `dict_label`, `dict_value`, `tag_type`, `dict_type`, `tenant_no`, `order_num`, `remark`,
`create_by`, `create_dept_id`, `create_time`, `update_by`, `update_time`, `del_flag`
)
SELECT * FROM (
SELECT 'DUTYDICTDATA0000000000000000001' AS id, '早班' AS dict_label, 'morning' AS dict_value, '' AS tag_type, 'duty_shift_type' AS dict_type, 'shanxia2.0' AS tenant_no, 1 AS order_num, NULL AS remark, '' AS create_by, '' AS create_dept_id, NOW() AS create_time, '' AS update_by, NOW() AS update_time, 0 AS del_flag
UNION ALL SELECT 'DUTYDICTDATA0000000000000000002', '晚班', 'evening', '', 'duty_shift_type', 'shanxia2.0', 2, NULL, '', '', NOW(), '', NOW(), 0
UNION ALL SELECT 'DUTYDICTDATA0000000000000000003', '值班', 'duty', '', 'duty_shift_type', 'shanxia2.0', 3, NULL, '', '', NOW(), '', NOW(), 0
UNION ALL SELECT 'DUTYDICTDATA0000000000000000004', '配酸', 'peisuan', '', 'duty_work_plan', 'shanxia2.0', 1, NULL, '', '', NOW(), '', NOW(), 0
UNION ALL SELECT 'DUTYDICTDATA0000000000000000005', '装卸', 'zhuangxie', '', 'duty_work_plan', 'shanxia2.0', 2, NULL, '', '', NOW(), '', NOW(), 0
) AS t
WHERE NOT EXISTS (
SELECT 1 FROM `sys_dict_data` d
WHERE d.tenant_no = t.tenant_no AND d.dict_type = t.dict_type AND d.dict_value = t.dict_value AND d.del_flag = 0
);
-- 2) duty_slot 扩字段
ALTER TABLE `duty_slot`
ADD COLUMN `work_plans` varchar(500) DEFAULT NULL COMMENT '工作安排dict_value逗号分隔' AFTER `capacity`,
ADD COLUMN `start_time` time DEFAULT NULL COMMENT '值班开始时间' AFTER `work_plans`,
ADD COLUMN `end_time` time DEFAULT NULL COMMENT '值班结束时间' AFTER `start_time`,
ADD COLUMN `cross_day` smallint(6) NOT NULL DEFAULT 0 COMMENT '结束是否次日0/1' AFTER `end_time`;
-- 若列已存在会失败:上线前按环境手工跳过或拆成可重复执行片段。
-- 3) 回填时段
UPDATE `duty_slot`
SET `start_time` = '08:00:00', `end_time` = '18:00:00', `cross_day` = 0
WHERE `del_flag` = 0 AND `shift_type` = 'morning' AND `start_time` IS NULL;
UPDATE `duty_slot`
SET `start_time` = '18:00:00', `end_time` = '07:00:00', `cross_day` = 1
WHERE `del_flag` = 0 AND `shift_type` = 'evening' AND `start_time` IS NULL;
-- 4) 回填工作安排(整段匹配);其它 remark 保留为备注
UPDATE `duty_slot`
SET `work_plans` = 'peisuan', `remark` = NULL
WHERE `del_flag` = 0 AND TRIM(`remark`) = '配酸' AND (`work_plans` IS NULL OR `work_plans` = '');
UPDATE `duty_slot`
SET `work_plans` = 'zhuangxie', `remark` = NULL
WHERE `del_flag` = 0 AND TRIM(`remark`) = '装卸' AND (`work_plans` IS NULL OR `work_plans` = '');
UPDATE `duty_slot`
SET `work_plans` = 'peisuan,zhuangxie', `remark` = NULL
WHERE `del_flag` = 0
AND (TRIM(`remark`) IN ('配酸,装卸', '配酸,装卸', '装卸,配酸', '装卸,配酸'))
AND (`work_plans` IS NULL OR `work_plans` = '');
```
- [ ] **Step 2: 在本地库执行并确认**
```bash
# 在已配置的 MySQL 上执行(按本地连接替换)
mysql -u... -p... your_db < backend/scripts/migrate_20260820_duty_shift_dict_time.sql
```
Expected: 无报错;`SHOW COLUMNS FROM duty_slot` 含新列;字典 options 可查到 5 条预置。
- [ ] **Step 3: Commit**
```bash
git add backend/scripts/migrate_20260820_duty_shift_dict_time.sql
git commit -m "chore(duty): add SQL migration for shift dict and slot time fields"
```
---
### Task 2: 模型与 Schema
**Files:**
- Modify: `backend/app/models/duty_models.py`
- Modify: `backend/app/schemas/duty.py`
- [ ] **Step 1: 扩展 DutySlot 模型**
在 `DutySlot` 中 `capacity` 之后增加(需 `from sqlalchemy import Time`):
```python
work_plans = Column(String(500), nullable=True, comment="工作安排dict_value逗号分隔")
start_time = Column(Time, nullable=True, comment="值班开始时间")
end_time = Column(Time, nullable=True, comment="值班结束时间")
cross_day = Column(SmallInteger, nullable=False, default=0, comment="结束是否次日")
```
保留 `SHIFT_MORNING` / `SHIFT_EVENING` / `SHIFT_DUTY` / `SHIFT_LABELS` 作为预置默认文案回退。
增加常量:
```python
DICT_SHIFT_TYPE = "duty_shift_type"
DICT_WORK_PLAN = "duty_work_plan"
DEFAULT_SHIFT_TIMES = {
SHIFT_MORNING: ("08:00", "18:00", 0),
SHIFT_EVENING: ("18:00", "07:00", 1),
}
```
- [ ] **Step 2: 放宽 Pydantic schema**
```python
from datetime import date, time
from typing import List, Literal, Optional, Union
from pydantic import BaseModel, Field, field_validator
LinkStatus = Literal["open", "closed"]
SourceType = Literal["assign", "grab"]
class DutyAssignmentIn(BaseModel):
source: SourceType = "assign"
userId: Optional[str] = None
personName: str = ""
class DutySlotSaveIn(BaseModel):
shiftType: str = Field(min_length=1, max_length=32)
capacity: int = Field(ge=1, le=99)
workPlans: List[str] = []
remark: Optional[str] = Field(default=None, max_length=500)
startTime: Optional[str] = Field(default=None, description="HH:mm")
endTime: Optional[str] = Field(default=None, description="HH:mm")
crossDay: bool = False
assignments: List[DutyAssignmentIn] = []
@field_validator("workPlans", mode="before")
@classmethod
def _split_work_plans(cls, v):
if v is None:
return []
if isinstance(v, str):
return [p.strip() for p in v.replace(",", ",").split(",") if p.strip()]
return v
class DutyDaySaveBody(BaseModel):
dutyDate: date
slots: List[DutySlotSaveIn]
linkStatus: Optional[LinkStatus] = None
class DutyLinkBody(BaseModel):
linkStatus: LinkStatus
class DutyGrabBody(BaseModel):
shiftType: str = Field(min_length=1, max_length=32)
userId: str = Field(min_length=1, max_length=64)
class DutyDictEnsureBody(BaseModel):
dictType: Literal["duty_shift_type", "duty_work_plan"]
label: str = Field(min_length=1, max_length=100)
```
- [ ] **Step 3: Commit**
```bash
git add backend/app/models/duty_models.py backend/app/schemas/duty.py
git commit -m "feat(duty): extend slot model and schemas for work plans and time"
```
---
### Task 3: 字典 ensure、时段格式化与序列化(TDD)
**Files:**
- Modify: `backend/app/services/duty_schedule.py`
- Modify: `backend/tests/test_duty_schedule.py`
- [ ] **Step 1: 写失败单测(纯函数优先)**
在 `backend/tests/test_duty_schedule.py` 追加:
```python
from app.services.duty_schedule import format_time_label, parse_hhmm, join_work_plans, split_work_plans
def test_parse_hhmm():
assert parse_hhmm("08:00").hour == 8
assert parse_hhmm("18:30").minute == 30
assert parse_hhmm(None) is None
assert parse_hhmm("") is None
def test_format_time_label_same_day():
assert format_time_label(parse_hhmm("08:00"), parse_hhmm("18:00"), False) == "08:00–18:00"
def test_format_time_label_cross_day():
assert format_time_label(parse_hhmm("18:00"), parse_hhmm("07:00"), True) == "18:00–次日07:00"
def test_format_time_label_empty():
assert format_time_label(None, None, False) is None
def test_work_plans_join_split():
assert join_work_plans(["peisuan", "zhuangxie"]) == "peisuan,zhuangxie"
assert split_work_plans("peisuan,zhuangxie") == ["peisuan", "zhuangxie"]
assert split_work_plans(None) == []
```
- [ ] **Step 2: 跑测确认失败**
```bash
cd backend && source venv/bin/activate && pytest tests/test_duty_schedule.py::test_parse_hhmm tests/test_duty_schedule.py::test_format_time_label_same_day tests/test_duty_schedule.py::test_format_time_label_cross_day tests/test_duty_schedule.py::test_format_time_label_empty tests/test_duty_schedule.py::test_work_plans_join_split -v
```
Expected: FAIL(import / 未定义)
- [ ] **Step 3: 实现辅助函数**
在 `duty_schedule.py` 顶部附近增加:
```python
from datetime import date, datetime, time
from typing import Any, Dict, List, Optional, Sequence, Tuple
from pypinyin import Style, lazy_pinyin
from app.models.duty_models import (
DEFAULT_SHIFT_TIMES, # 若放在 models
DICT_SHIFT_TYPE,
DICT_WORK_PLAN,
SHIFT_LABELS,
...
)
from app.models.models import SysDictData, SysRole, SysUser, SysUserRole
def parse_hhmm(value: Optional[str]) -> Optional[time]:
raw = (value or "").strip()
if not raw:
return None
parts = raw.split(":")
if len(parts) < 2:
raise DutyBizError("时间格式须为 HH:mm")
h, m = int(parts[0]), int(parts[1])
if not (0 <= h <= 23 and 0 <= m <= 59):
raise DutyBizError("时间格式须为 HH:mm")
return time(hour=h, minute=m)
def format_hhmm(t: Optional[time]) -> Optional[str]:
if t is None:
return None
return f"{t.hour:02d}:{t.minute:02d}"
def format_time_label(
start: Optional[time], end: Optional[time], cross_day: bool
) -> Optional[str]:
if start is None or end is None:
return None
s, e = format_hhmm(start), format_hhmm(end)
if cross_day:
return f"{s}–次日{e}"
return f"{s}–{e}"
def split_work_plans(raw: Optional[str]) -> List[str]:
if not raw:
return []
return [p.strip() for p in str(raw).replace(",", ",").split(",") if p.strip()]
def join_work_plans(values: Sequence[str]) -> Optional[str]:
parts = [v.strip() for v in values if (v or "").strip()]
return ",".join(parts) if parts else None
def build_dict_value_from_label(label: str) -> str:
text = (label or "").strip()
parts: List[str] = []
for ch in text:
if "\u4e00" <= ch <= "\u9fff":
pys = lazy_pinyin(ch, style=Style.NORMAL)
if pys and pys[0]:
parts.append(str(pys[0]).lower())
elif ch.isalnum():
parts.append(ch.lower())
base = "".join(parts)[:32] or "item"
return base
```
字典 ensure(同 label 复用;同 value 冲突加后缀):
```python
def ensure_dict_data(
db: Session,
*,
tenant_no: str,
dict_type: str,
label: str,
user_id: str = "",
preferred_value: Optional[str] = None,
) -> Dict[str, str]:
label = (label or "").strip()
if not label:
raise DutyBizError("字典标签不能为空")
if dict_type not in (DICT_SHIFT_TYPE, DICT_WORK_PLAN):
raise DutyBizError("不支持的字典类型")
existing_label = (
db.query(SysDictData)
.filter(
SysDictData.tenant_no == tenant_no,
SysDictData.dict_type == dict_type,
SysDictData.dict_label == label,
SysDictData.del_flag == 0,
)
.first()
)
if existing_label:
return {"label": existing_label.dict_label, "value": existing_label.dict_value}
value = (preferred_value or "").strip() or build_dict_value_from_label(label)
for _ in range(8):
clash = (
db.query(SysDictData)
.filter(
SysDictData.tenant_no == tenant_no,
SysDictData.dict_type == dict_type,
SysDictData.dict_value == value,
SysDictData.del_flag == 0,
)
.first()
)
if not clash:
break
value = f"{value[:27]}_{secrets.token_hex(2)}"
else:
raise DutyBizError("无法生成唯一字典值")
# 勿调用 dict_data_svc.create_dict_data(其内部会 commit,打断 save_day 事务)
from app.core.utils import generate_uuid
obj = SysDictData(
id=generate_uuid(),
dict_label=label,
dict_value=value,
dict_type=dict_type,
tag_type="",
tenant_no=tenant_no,
order_num=0,
remark=None,
create_by=user_id or None,
create_dept_id="",
create_time=datetime.now(),
update_by=user_id or None,
update_time=datetime.now(),
del_flag=0,
)
db.add(obj)
db.flush()
return {"label": obj.dict_label, "value": obj.dict_value}
def _load_dict_label_map(db: Session, tenant_no: str, dict_type: str) -> Dict[str, str]:
rows = (
db.query(SysDictData)
.filter(
SysDictData.tenant_no == tenant_no,
SysDictData.dict_type == dict_type,
SysDictData.del_flag == 0,
)
.all()
)
return {r.dict_value: r.dict_label for r in rows}
```
- [ ] **Step 4: 跑测通过**
```bash
cd backend && source venv/bin/activate && pytest tests/test_duty_schedule.py::test_parse_hhmm tests/test_duty_schedule.py::test_format_time_label_same_day tests/test_duty_schedule.py::test_format_time_label_cross_day tests/test_duty_schedule.py::test_format_time_label_empty tests/test_duty_schedule.py::test_work_plans_join_split -v
```
Expected: PASS
- [ ] **Step 5: Commit**
```bash
git add backend/app/services/duty_schedule.py backend/tests/test_duty_schedule.py backend/app/models/duty_models.py
git commit -m "feat(duty): add time/work-plan helpers and dict ensure"
```
---
### Task 4: 序列化、save_day、grab 改造
**Files:**
- Modify: `backend/app/services/duty_schedule.py`
- Modify: `backend/app/api/duty.py`
- Modify: `backend/tests/test_duty_schedule.py`
- [ ] **Step 1: 写 grab 放宽单测**
```python
def test_grab_allows_custom_shift_type_when_slot_exists():
"""自定义 shift_type 只要当日存在 slot 即可,不必在 SHIFT_LABELS。"""
db = MagicMock()
day = SimpleNamespace(
id="day1",
tenant_no="t1",
link_status=LINK_OPEN,
duty_date=date(2026, 8, 20),
access_token="tok",
del_flag=0,
)
slot = SimpleNamespace(
id="slot1",
duty_day_id="day1",
shift_type="zhongban",
capacity=2,
del_flag=0,
)
user = SimpleNamespace(
id="u1",
tenant_no="t1",
nick_name="王五",
user_no="wangwu",
status="1",
del_flag=0,
)
day_q = MagicMock()
day_q.filter.return_value.with_for_update.return_value.first.return_value = day
slot_q = MagicMock()
slot_q.filter.return_value.with_for_update.return_value.first.return_value = slot
user_q = MagicMock()
user_q.filter.return_value.first.return_value = user
role = SimpleNamespace(id=DUTY_STAFF_ROLE_ID)
role_q = MagicMock()
role_q.filter.return_value.first.return_value = role
ur_q = MagicMock()
ur_q.filter.return_value.first.return_value = SimpleNamespace(
user_id="u1", role_id=DUTY_STAFF_ROLE_ID
)
def query_side_effect(model):
name = getattr(model, "__name__", str(model))
if name == "DutyDay":
return day_q
if name == "DutySlot":
return slot_q
if name == "SysUser":
return user_q
if name == "SysRole":
return role_q
if name == "SysUserRole":
return ur_q
if name == "SysDictData":
dq = MagicMock()
dq.filter.return_value.all.return_value = []
dq.filter.return_value.first.return_value = None
return dq
aq = MagicMock()
aq.filter.return_value.count.return_value = 0
aq.filter.return_value.first.return_value = None
return aq
db.query.side_effect = query_side_effect
result = grab(db, "tok", "zhongban", "u1")
assert result["shiftType"] == "zhongban"
assert result["status"] == "ok"
```
- [ ] **Step 2: 跑测应因仍校验 SHIFT_LABELS 失败**
```bash
cd backend && source venv/bin/activate && pytest tests/test_duty_schedule.py::test_grab_allows_custom_shift_type_when_slot_exists -v
```
Expected: FAIL match `班次类型无效` 或未实现
- [ ] **Step 3: 改造 `_slot_dict` / `save_day` / `grab`**
`_slot_dict` 签名改为接收 label maps:
```python
def _slot_dict(
slot: DutySlot,
assignments: Sequence[DutyAssignment],
*,
shift_labels: Dict[str, str],
work_plan_labels: Dict[str, str],
) -> Dict[str, Any]:
active = [a for a in assignments if a.del_flag == 0]
plans = split_work_plans(getattr(slot, "work_plans", None))
cross = bool(getattr(slot, "cross_day", 0) or 0)
start = getattr(slot, "start_time", None)
end = getattr(slot, "end_time", None)
return {
"id": slot.id,
"shiftType": slot.shift_type,
"shiftLabel": shift_labels.get(slot.shift_type)
or SHIFT_LABELS.get(slot.shift_type, slot.shift_type),
"capacity": slot.capacity,
"taken": len(active),
"workPlans": plans,
"workPlanLabels": [work_plan_labels.get(v, v) for v in plans],
"remark": (slot.remark or "").strip() or None,
"startTime": format_hhmm(start),
"endTime": format_hhmm(end),
"crossDay": cross,
"timeLabel": format_time_label(start, end, cross),
"assignments": [_assignment_dict(a) for a in active],
}
```
`_serialize_day` / `_day_dict`:按 `day.tenant_no` 加载两份 label map 再序列化 slots。
`save_day` 循环内写入:
```python
plans = join_work_plans(slot_in.workPlans or [])
# 确保 work plan values 在字典中存在(按 value 查找;不存在则用 value 当 label ensure)
for v in (slot_in.workPlans or []):
row = (
db.query(SysDictData)
.filter(
SysDictData.tenant_no == tenant_no,
SysDictData.dict_type == DICT_WORK_PLAN,
SysDictData.dict_value == v,
SysDictData.del_flag == 0,
)
.first()
)
if not row:
ensure_dict_data(
db,
tenant_no=tenant_no,
dict_type=DICT_WORK_PLAN,
label=v,
preferred_value=v,
user_id=user_id,
)
# shift type:若非预置且字典无 value,则 ensure(label 回退 SHIFT_LABELS 或 value)
if slot_in.shiftType not in SHIFT_LABELS:
row = (
db.query(SysDictData)
.filter(
SysDictData.tenant_no == tenant_no,
SysDictData.dict_type == DICT_SHIFT_TYPE,
SysDictData.dict_value == slot_in.shiftType,
SysDictData.del_flag == 0,
)
.first()
)
if not row:
ensure_dict_data(
db,
tenant_no=tenant_no,
dict_type=DICT_SHIFT_TYPE,
label=slot_in.shiftType,
preferred_value=slot_in.shiftType,
user_id=user_id,
)
start_t = parse_hhmm(slot_in.startTime)
end_t = parse_hhmm(slot_in.endTime)
cross = 1 if slot_in.crossDay else 0
# 若只填了一端,拒绝
if (start_t is None) ^ (end_t is None):
raise DutyBizError("值班时间须同时填写开始与结束,或全部留空")
# create/update DutySlot 时设置 work_plans/start_time/end_time/cross_day/remark
```
`grab`:删除 `if shift_type not in SHIFT_LABELS`;slot 不存在仍报「该班次不存在」;`shiftLabel` 用字典 map + `SHIFT_LABELS` 回退。
- [ ] **Step 4: API ensure 端点**
在 `backend/app/api/duty.py`:
```python
@router.post("/dict/ensure")
def ensure_duty_dict(
body: DutyDictEnsureBody,
db: Session = Depends(get_db),
user=Depends(get_current_user),
):
tenant_no = ...
try:
data = duty_schedule.ensure_dict_data(
db,
tenant_no=tenant_no,
dict_type=body.dictType,
label=body.label,
user_id=user.get("user_id") or "",
)
db.commit()
return success_response(data)
except DutyBizError as e:
...
```
- [ ] **Step 5: 跑相关单测**
```bash
cd backend && source venv/bin/activate && pytest tests/test_duty_schedule.py -v
```
Expected: PASS
- [ ] **Step 6: Commit**
```bash
git add backend/app/services/duty_schedule.py backend/app/api/duty.py backend/tests/test_duty_schedule.py
git commit -m "feat(duty): persist work plans and times; relax grab shift types"
```
---
### Task 5: 前端 API 类型
**Files:**
- Modify: `web-admin/src/api/duty.ts`
- Modify: `web-admin/src/api/public-duty.ts`
- [ ] **Step 1: 更新 `duty.ts`**
```typescript
export type ShiftType = string // 预置 morning|evening|duty,亦可自定义 dict_value
export interface DutySlotItem {
id?: string
shiftType: ShiftType
shiftLabel?: string
capacity: number
taken?: number
workPlans?: string[]
workPlanLabels?: string[]
remark?: string | null
startTime?: string | null
endTime?: string | null
crossDay?: boolean
timeLabel?: string | null
assignments: DutyAssignmentItem[]
}
export function saveDutyDay(data: {
dutyDate: string
slots: Array<{
shiftType: ShiftType
capacity: number
workPlans?: string[]
remark?: string | null
startTime?: string | null
endTime?: string | null
crossDay?: boolean
assignments: DutyAssignmentItem[]
}>
linkStatus?: LinkStatus
}) { ... }
export function ensureDutyDict(data: {
dictType: 'duty_shift_type' | 'duty_work_plan'
label: string
}) {
return request.post<{ label: string; value: string }>({
url: '/web/admin/duty/dict/ensure',
data
})
}
```
- [ ] **Step 2: 更新 `public-duty.ts`**
`PublicDutySlot` / `PublicDutyGrabResult` 的 `shiftType` 改为 `string`;slot 增加 `workPlans`、`workPlanLabels`、`startTime`、`endTime`、`crossDay`、`timeLabel`;`remark` 语义为备注。
- [ ] **Step 3: Commit**
```bash
git add web-admin/src/api/duty.ts web-admin/src/api/public-duty.ts
git commit -m "feat(duty): update frontend API types for dict and time fields"
```
---
### Task 6: 管理端排班页
**Files:**
- Modify: `web-admin/src/views/duty/schedule/index.vue`
- [ ] **Step 1: 加载字典 options**
```typescript
import { fetchDictDataOptions } from '@/api/admin'
import { ensureDutyDict, ... } from '@/api/duty'
const shiftTypeOptions = ref<Array<{ label: string; value: string }>>([])
const workPlanOptions = ref<Array<{ label: string; value: string }>>([])
async function loadDictOptions() {
const [shifts, plans] = await Promise.all([
fetchDictDataOptions('duty_shift_type'),
fetchDictDataOptions('duty_work_plan')
])
// Api.Dict.DictDataOption: { label, value }
shiftTypeOptions.value = (shifts || []).map((x) => ({ label: x.label, value: x.value }))
workPlanOptions.value = (plans || []).map((x) => ({ label: x.label, value: x.value }))
}
```
在 `onMounted` 中调用。
- [ ] **Step 2: formSlots 结构改造**
```typescript
type FormSlot = {
shiftType: string
enabled: boolean
capacity: number
workPlans: string[]
remark: string
startTime: string
endTime: string
crossDay: boolean
pendingUserId: string
assignments: DutyAssignmentItem[]
}
const PRESET_TYPES = ['morning', 'evening', 'duty'] as const
function defaultTimesFor(shiftType: string) {
if (shiftType === 'morning') return { startTime: '08:00', endTime: '18:00', crossDay: false }
if (shiftType === 'evening') return { startTime: '18:00', endTime: '07:00', crossDay: true }
return { startTime: '', endTime: '', crossDay: false }
}
function blankFormSlots(): FormSlot[] {
return PRESET_TYPES.map((t) => ({
shiftType: t,
enabled: t === 'morning' || t === 'evening',
capacity: 1,
workPlans: [],
remark: '',
...defaultTimesFor(t),
pendingUserId: '',
assignments: []
}))
}
```
打开详情时:按返回 slots 回填;缺失的预置类型补空卡;额外自定义类型追加卡片。
- [ ] **Step 3: 弹窗模板字段**
每条 slot 卡片增加(Fresh Mint,`label-position="top"`):
- 时段:两个 `el-time-picker` `value-format="HH:mm"`;`crossDay` 可用 checkbox「跨日」,当结束&lt;开始时自动勾选
- 工作安排:`el-select` multiple filterable allow-create;`@create`/change 时对新建 label 调 `ensureDutyDict({ dictType: 'duty_work_plan', label })`,用返回 `value` 写入 `workPlans`
- 备注:`el-input` textarea(原工作安排输入位改为此)
- 「添加班次」:下拉选未占用的 `shiftTypeOptions`,allow-create → `ensureDutyDict({ dictType: 'duty_shift_type', label })` 后 push 新 FormSlot
保存 body:
```typescript
slots: formSlots.value
.filter((s) => s.enabled)
.map((s) => ({
shiftType: s.shiftType,
capacity: s.capacity,
workPlans: s.workPlans,
remark: s.remark || null,
startTime: s.startTime || null,
endTime: s.endTime || null,
crossDay: !!s.crossDay,
assignments: s.assignments
}))
```
- [ ] **Step 4: 月历图例 / 筛选 / 统计**
- `shiftLabel` 优先用接口或字典 map,回退旧 `SHIFT_LABELS`
- 筛选:预置三项 + 动态「其他」或按字典列出(至少预置三项可点)
- 统计列:morning/evening/duty + `other` 计数
CSS:未知类型用 `.dot.other` 中性色。
- [ ] **Step 5: 手动点检**
`pnpm dev` → `/#/duty/schedule`:新建日默认三类型;改时段;多选工作安排并新建;添加自定义类型;保存刷新后仍在。
- [ ] **Step 6: Commit**
```bash
git add web-admin/src/views/duty/schedule/index.vue
git commit -m "feat(duty): admin schedule UI for dict types, work plans, and time"
```
---
### Task 7: 公开移动端 H5 同步
**Files:**
- Modify: `web-admin/src/views/public/duty/index.vue`
- [ ] **Step 1: 班次卡片展示**
在名额行下方:
```vue
<p v-if="slot.timeLabel" class="slot-time">值班时间:<strong>{{ slot.timeLabel }}</strong></p>
<p v-if="slot.workPlanLabels?.length" class="slot-remark">
工作安排:<strong>{{ slot.workPlanLabels.join('、') }}</strong>
</p>
<p v-if="slot.remark" class="slot-note">备注:{{ slot.remark }}</p>
```
去掉把 `remark` 当工作安排的旧文案(若仍显示 `工作安排:{{ slot.remark }}` 则替换)。
点样式:`:class="dotClass(slot.shiftType)"`,仅 `morning|evening|duty` 用旧色,其它用 `other`。
- [ ] **Step 2: 成功页摘要**
成功态增加时段、工作安排(若接口返回;否则成功后回列表可见)。若 grab 响应暂无这些字段,至少 `shiftLabel` 正确;可选在 grab 响应中带回 `timeLabel` / `workPlanLabels`(与 Task 4 对齐时一并返回)。
- [ ] **Step 3: 点检公开页**
复制某日链接 → 手机宽度或 DevTools:可见时段与工作安排;抢班成功。
- [ ] **Step 4: Commit**
```bash
git add web-admin/src/views/public/duty/index.vue
git commit -m "feat(duty): sync public H5 with time, work plans, and remark"
```
---
### Task 8: 回归与收尾
**Files:**
- 视需要:在 `docs/sql/shanxia2.0.sql` 旁注或只保留 scripts 迁移(按仓库惯例,本计划以 `backend/scripts/` 为准)
- [ ] **Step 1: 后端全量值班测**
```bash
cd backend && source venv/bin/activate && pytest tests/test_duty_schedule.py -v
```
Expected: PASS
- [ ] **Step 2: 前端类型检查(若耗时过长可仅 lint 改动文件)**
```bash
cd web-admin && pnpm exec eslint "src/views/duty/schedule/index.vue" "src/views/public/duty/index.vue" "src/api/duty.ts" "src/api/public-duty.ts"
```
- [ ] **Step 3: 按 spec 验收清单手工过一遍**(见设计文档「测试要点」)
- [ ] **Step 4: 最终 commit(若有遗漏文档)**
```bash
git add docs/superpowers/plans/2026-08-20-duty-shift-dict-time.md
git commit -m "docs: add duty shift dict and time implementation plan"
```
(若本 plan 文件已在此前单独提交则跳过。)
---
## Spec 覆盖自检
| Spec 要求 | Task |
|-----------|------|
| 字典两类 + 预置 | Task 1 |
| slot 扩字段 + 迁移回填 | Task 1 |
| shiftType 存 dict_value / 不改历史编码 | Task 2–4 |
| workPlans 多选 + remark 备注分离 | Task 4、6、7 |
| 早/晚默认时段、值班空 | Task 1 回填 + Task 6 默认 |
| 同日同类型唯一 | 已有 save_day 校验,保持 |
| ensure 字典 / allow-create | Task 3–4、6 |
| 公开 H5 同步 | Task 7 |
| grab 放宽 | Task 4 |
| 月历统计「其他」 | Task 6 |
## 执行说明
实现时优先 **subagent-driven-development**(每 Task 新子代理 + 两段审查),或本会话 **executing-plans** 按检查点推进。