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>
This commit is contained in:
zlwuandCursor committed
1 parent
361e923396
commit
1850c7c3df
1 file changed
+965
@@ -0,0 +1,965 @@
|
||||
# 值班排班 · 字典类型 / 工作安排 / 时段 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「跨日」，当结束<开始时自动勾选
|
||||
- 工作安排：`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** 按检查点推进。
|
||||
Reference in new issue
Block a user