0 Fork 0

Files

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

30 KiB

Raw Blame History

值班排班 · 字典类型 / 工作安排 / 时段 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

-- 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: 在本地库执行并确认

# 在已配置的 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

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）：

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 作为预置默认文案回退。

增加常量：

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

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

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 追加：

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: 跑测确认失败

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 顶部附近增加：

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 冲突加后缀）：

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: 跑测通过

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

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 放宽单测

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 失败

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：

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 循环内写入：

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：

@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: 跑相关单测

cd backend && source venv/bin/activate && pytest tests/test_duty_schedule.py -v

Expected: PASS

Step 6: Commit

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

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

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

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 结构改造

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「跨日」，当结束<开始时自动勾选
工作安排：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：

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

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: 班次卡片展示

在名额行下方：

<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

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: 后端全量值班测

cd backend && source venv/bin/activate && pytest tests/test_duty_schedule.py -v

Expected: PASS

Step 2: 前端类型检查（若耗时过长可仅 lint 改动文件）

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（若有遗漏文档）

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 按检查点推进。

30 KiB Raw Blame History Unescape Escape

值班排班 · 字典类型 / 工作安排 / 时段 Implementation Plan

文件结构

Task 1: SQL 迁移（字典 + ALTER + 回填）

Task 2: 模型与 Schema

Task 3: 字典 ensure、时段格式化与序列化（TDD）

Task 4: 序列化、save_day、grab 改造

Task 5: 前端 API 类型

Task 6: 管理端排班页

Task 7: 公开移动端 H5 同步

Task 8: 回归与收尾

Spec 覆盖自检

执行说明

30 KiB

Raw Blame History