feat(duty): add web-admin calendar page and public H5 grab UI

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
zlwuandCursor committed 2026-08-14 17:14:05 +08:00
1 parent 36fc7f286c
commit 35e09fa09b
9 files changed
+3152

No files matched your search

@@ -0,0 +1,644 @@
# 值班排班(日历 + 公开链接抢班)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:** 在 web-admin 提供按日月历排班(预置早/晚/值班、名额、指定系统用户、复制/关闭按日公开链接);员工打开 `/#/public/duty/{token}` 免登录填姓名抢班,满员拒绝;支持历史翻月查看。
**Architecture:** 三表 `duty_day` / `duty_slot` / `duty_assignment`;管理 API 挂 `/api/web/admin/duty`;公开 API 挂 `/api/public/duty`(加密排除);公开页复用 `publicPlGet`/`publicPlPost` 与 `isPublicMobile` 静态路由。业务规则集中在 `app/services/duty_schedule.py`。
**Tech Stack:** FastAPI + SQLAlchemy + Pydantic v2;Vue 3 + Element Plus + SCSS(Fresh Mint 管理端 / 三墙 Token 公开 H5);pytest
**Spec:** `docs/superpowers/specs/2026-08-14-duty-schedule-design.md`
**UI 原型:** `docs/demos/duty-schedule-v1-demo.html`、`docs/demos/duty-h5-grab-demo.html`
---
## 文件结构
| 操作 | 文件 | 职责 |
|------|------|------|
| Create | `backend/scripts/migrate_20260814_duty_schedule.sql` | 建表 + 菜单 |
| Create | `backend/app/models/duty_models.py` | ORM |
| Create | `backend/app/schemas/duty.py` | 请求/响应 schema |
| Create | `backend/app/services/duty_schedule.py` | 保存日配置、抢班、关链、序列化 |
| Create | `backend/app/api/duty.py` | 管理端路由 |
| Create | `backend/app/api/public_duty.py` | 公开路由 |
| Create | `backend/tests/test_duty_schedule.py` | 名额/关链/缩容单测 |
| Modify | `backend/app/main.py` | `include_router` |
| Modify | `backend/app/core/config.py` | `API_ENCRYPT_EXCLUDE_PATHS` |
| Create | `web-admin/src/api/duty.ts` | 管理端 API |
| Create | `web-admin/src/api/public-duty.ts` | 公开 API |
| Create | `web-admin/src/views/duty/schedule/index.vue` | 月历 + 日配置弹窗 |
| Create | `web-admin/src/views/public/duty/index.vue` | 公开 H5 |
| Modify | `web-admin/src/router/routes/staticRoutes.ts` | 公开路由 |
| Modify | `web-admin/.env.development` / `.env.production`(若有独立排除列表) | 排除公开 path |
| Sync | `docs/sql/` | 将 migrate 表结构并入基线说明或追加脚本备注 |
**Shift 常量(全栈统一):** `morning` / `evening` / `duty` → 文案 早班 / 晚班 / 值班。
---
### Task 1: SQL 迁移(三表 + 菜单)
**Files:**
- Create: `backend/scripts/migrate_20260814_duty_schedule.sql`
- [ ] **Step 1: 写迁移 SQL**
```sql
-- backend/scripts/migrate_20260814_duty_schedule.sql
-- 值班排班 V1:按日链接 + 班次名额 + 报名
CREATE TABLE IF NOT EXISTS `duty_day` (
`id` varchar(64) NOT NULL COMMENT '主键ID(UUID)',
`duty_date` date NOT NULL COMMENT '值班日期',
`access_token` varchar(64) NOT NULL COMMENT '公开访问令牌',
`link_status` varchar(16) NOT NULL DEFAULT 'open' COMMENT 'open/closed',
`tenant_no` varchar(64) NOT NULL DEFAULT 'shanxia2.0' COMMENT '租户编号',
`order_num` int(11) DEFAULT NULL COMMENT '排序号',
`remark` varchar(500) DEFAULT NULL COMMENT '备注',
`create_by` varchar(64) DEFAULT NULL COMMENT '创建者',
`create_dept_id` varchar(64) NOT NULL DEFAULT '' COMMENT '创建部门',
`create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
`update_by` varchar(64) DEFAULT NULL COMMENT '更新者',
`update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
`del_flag` smallint(6) NOT NULL DEFAULT '0' COMMENT '删除标志',
PRIMARY KEY (`id`),
UNIQUE KEY `uk_token` (`access_token`),
KEY `idx_tenant_date` (`tenant_no`, `duty_date`, `del_flag`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='值班日(一天一条公开链接)';
CREATE TABLE IF NOT EXISTS `duty_slot` (
`id` varchar(64) NOT NULL COMMENT '主键ID(UUID)',
`duty_day_id` varchar(64) NOT NULL COMMENT '值班日ID',
`shift_type` varchar(32) NOT NULL COMMENT 'morning/evening/duty',
`capacity` int(11) NOT NULL DEFAULT 1 COMMENT '名额',
`tenant_no` varchar(64) NOT NULL DEFAULT 'shanxia2.0' COMMENT '租户编号',
`order_num` int(11) DEFAULT NULL COMMENT '排序号',
`remark` varchar(500) DEFAULT NULL COMMENT '备注',
`create_by` varchar(64) DEFAULT NULL COMMENT '创建者',
`create_dept_id` varchar(64) NOT NULL DEFAULT '' COMMENT '创建部门',
`create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
`update_by` varchar(64) DEFAULT NULL COMMENT '更新者',
`update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
`del_flag` smallint(6) NOT NULL DEFAULT '0' COMMENT '删除标志',
PRIMARY KEY (`id`),
KEY `idx_day` (`duty_day_id`, `del_flag`),
KEY `idx_tenant` (`tenant_no`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='值班班次名额';
CREATE TABLE IF NOT EXISTS `duty_assignment` (
`id` varchar(64) NOT NULL COMMENT '主键ID(UUID)',
`duty_slot_id` varchar(64) NOT NULL COMMENT '班次名额ID',
`source` varchar(16) NOT NULL COMMENT 'assign/grab',
`user_id` varchar(64) DEFAULT NULL COMMENT '系统用户ID(指定时)',
`person_name` varchar(64) NOT NULL COMMENT '展示姓名',
`tenant_no` varchar(64) NOT NULL DEFAULT 'shanxia2.0' COMMENT '租户编号',
`order_num` int(11) DEFAULT NULL COMMENT '排序号',
`remark` varchar(500) DEFAULT NULL COMMENT '备注',
`create_by` varchar(64) DEFAULT NULL COMMENT '创建者',
`create_dept_id` varchar(64) NOT NULL DEFAULT '' COMMENT '创建部门',
`create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
`update_by` varchar(64) DEFAULT NULL COMMENT '更新者',
`update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
`del_flag` smallint(6) NOT NULL DEFAULT '0' COMMENT '删除标志',
PRIMARY KEY (`id`),
KEY `idx_slot` (`duty_slot_id`, `del_flag`),
KEY `idx_tenant` (`tenant_no`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='值班占位(指定或抢班)';
-- 菜单:挂在系统管理或独立一级均可;此处挂 Web 虚拟根下「值班排班」
-- parent_id 请按环境库 Web 根菜单 id 调整(查询 parent_id=0 且面向 Web 的根)
INSERT INTO `sys_menu` (
`id`, `menu_name`, `parent_id`, `menu_type`, `path`, `component`, `perms`,
`is_frame`, `visible`, `status`, `tenant_no`, `order_num`, `remark`,
`create_by`, `create_dept_id`, `create_time`, `update_by`, `update_time`, `del_flag`
) VALUES (
'DUTY000000000000000000000000001',
'值班排班',
'0',
'C',
'duty-schedule',
'/duty/schedule/index',
'duty:schedule:list',
1, '1', '1', 'shanxia2.0', 90,
'日历排班与公开抢班链接',
'system', '', NOW(), NULL, NOW(), 0
)
ON DUPLICATE KEY UPDATE
`menu_name`=VALUES(`menu_name`),
`component`=VALUES(`component`),
`perms`=VALUES(`perms`),
`path`=VALUES(`path`);
```
执行前:查出现网 Web 菜单父级,将 `parent_id='0'` 改为正确父菜单 id(勿做成孤儿叶子;若 `0` 为虚拟根且项目允许顶栏入口,按门户习惯调整)。
- [ ] **Step 2: 在本地库执行迁移**
```bash
cd backend && source venv/bin/activate
# 用项目惯用方式执行 SQL,例如 mysql client 指向 .env.local
mysql ... < scripts/migrate_20260814_duty_schedule.sql
```
Expected: 三表创建成功;菜单可见(刷新权限后)。
- [ ] **Step 3: Commit**
```bash
git add backend/scripts/migrate_20260814_duty_schedule.sql
git commit -m "$(cat <<'EOF'
chore(duty): add duty_day/slot/assignment tables and menu SQL
EOF
)"
```
---
### Task 2: ORM 模型
**Files:**
- Create: `backend/app/models/duty_models.py`
- Modify: 若项目有 `models/__init__.py` 导出习惯则一并导出
- [ ] **Step 1: 创建模型(对齐 bx 公共字段风格)**
```python
"""值班排班模型 — docs/superpowers/specs/2026-08-14-duty-schedule-design.md"""
from datetime import datetime
from sqlalchemy import Column, Date, DateTime, Integer, SmallInteger, String
from app.core.database import Base
SHIFT_MORNING = "morning"
SHIFT_EVENING = "evening"
SHIFT_DUTY = "duty"
SHIFT_LABELS = {
SHIFT_MORNING: "早班",
SHIFT_EVENING: "晚班",
SHIFT_DUTY: "值班",
}
LINK_OPEN = "open"
LINK_CLOSED = "closed"
SOURCE_ASSIGN = "assign"
SOURCE_GRAB = "grab"
class DutyDay(Base):
__tablename__ = "duty_day"
id = Column(String(64), primary_key=True)
duty_date = Column(Date, nullable=False)
access_token = Column(String(64), nullable=False)
link_status = Column(String(16), nullable=False, default=LINK_OPEN)
tenant_no = Column(String(64), nullable=False, default="shanxia2.0")
order_num = Column(Integer, nullable=True)
remark = Column(String(500), nullable=True)
create_by = Column(String(64), nullable=True)
create_dept_id = Column(String(64), nullable=False, default="")
create_time = Column(DateTime, nullable=False, default=datetime.now)
update_by = Column(String(64), nullable=True)
update_time = Column(DateTime, nullable=False, default=datetime.now, onupdate=datetime.now)
del_flag = Column(SmallInteger, nullable=False, default=0)
class DutySlot(Base):
__tablename__ = "duty_slot"
id = Column(String(64), primary_key=True)
duty_day_id = Column(String(64), nullable=False)
shift_type = Column(String(32), nullable=False)
capacity = Column(Integer, nullable=False, default=1)
tenant_no = Column(String(64), nullable=False, default="shanxia2.0")
order_num = Column(Integer, nullable=True)
remark = Column(String(500), nullable=True)
create_by = Column(String(64), nullable=True)
create_dept_id = Column(String(64), nullable=False, default="")
create_time = Column(DateTime, nullable=False, default=datetime.now)
update_by = Column(String(64), nullable=True)
update_time = Column(DateTime, nullable=False, default=datetime.now, onupdate=datetime.now)
del_flag = Column(SmallInteger, nullable=False, default=0)
class DutyAssignment(Base):
__tablename__ = "duty_assignment"
id = Column(String(64), primary_key=True)
duty_slot_id = Column(String(64), nullable=False)
source = Column(String(16), nullable=False)
user_id = Column(String(64), nullable=True)
person_name = Column(String(64), nullable=False)
tenant_no = Column(String(64), nullable=False, default="shanxia2.0")
order_num = Column(Integer, nullable=True)
remark = Column(String(500), nullable=True)
create_by = Column(String(64), nullable=True)
create_dept_id = Column(String(64), nullable=False, default="")
create_time = Column(DateTime, nullable=False, default=datetime.now)
update_by = Column(String(64), nullable=True)
update_time = Column(DateTime, nullable=False, default=datetime.now, onupdate=datetime.now)
del_flag = Column(SmallInteger, nullable=False, default=0)
```
- [ ] **Step 2: Commit**
```bash
git add backend/app/models/duty_models.py
git commit -m "$(cat <<'EOF'
feat(duty): add SQLAlchemy models for duty schedule
EOF
)"
```
---
### Task 3: Schemas + 领域服务(含 TDD)
**Files:**
- Create: `backend/app/schemas/duty.py`
- Create: `backend/app/services/duty_schedule.py`
- Create: `backend/tests/test_duty_schedule.py`
- [ ] **Step 1: 写失败单测(纯函数/可测逻辑优先)**
在 `test_duty_schedule.py` 先测容量校验与姓名规范化(不依赖 DB 的部分),以及用 SQLite/fixture 测 `grab` 满员(若项目测试多用 mock Session,则测 service 内 `_assert_capacity` / `normalize_person_name`)。
最小必测:
```python
import pytest
from app.services.duty_schedule import normalize_person_name, SHIFT_LABELS
from app.models.duty_models import SHIFT_MORNING
def test_normalize_person_name_ok():
assert normalize_person_name(" 张三 ") == "张三"
def test_normalize_person_name_empty():
with pytest.raises(ValueError, match="姓名"):
normalize_person_name(" ")
def test_normalize_person_name_too_long():
with pytest.raises(ValueError, match="姓名"):
normalize_person_name("啊" * 21)
def test_shift_labels():
assert SHIFT_LABELS[SHIFT_MORNING] == "早班"
```
- [ ] **Step 2: 跑测确认失败(函数尚未存在)**
```bash
cd backend && source venv/bin/activate && pytest tests/test_duty_schedule.py -v
```
Expected: FAIL import / not defined
- [ ] **Step 3: 实现 schemas**
```python
# backend/app/schemas/duty.py
from __future__ import annotations
from datetime import date
from typing import List, Literal, Optional
from pydantic import BaseModel, Field
ShiftType = Literal["morning", "evening", "duty"]
LinkStatus = Literal["open", "closed"]
SourceType = Literal["assign", "grab"]
class DutyAssignmentIn(BaseModel):
source: SourceType = "assign"
userId: Optional[str] = None
personName: str = ""
class DutySlotSaveIn(BaseModel):
shiftType: ShiftType
capacity: int = Field(ge=1, le=99)
assignments: List[DutyAssignmentIn] = []
class DutyDaySaveBody(BaseModel):
dutyDate: date
slots: List[DutySlotSaveIn]
linkStatus: Optional[LinkStatus] = None
class DutyGrabBody(BaseModel):
shiftType: ShiftType
personName: str
```
- [ ] **Step 4: 实现 service 核心**
`duty_schedule.py` 必须提供:
- `normalize_person_name(name: str) -> str`
- `new_access_token() -> str`(`secrets.token_urlsafe(24)`,截断到 ≤64)
- `build_public_url(token: str) -> str` → `f"{settings.PUBLIC_WEB_ORIGIN.rstrip('/')}/#/public/duty/{token}"`
- `get_month_summary(db, tenant_no, year, month) -> list`
- `get_day_detail(db, tenant_no, duty_date|day_id) -> dict`
- `save_day(db, tenant_no, user, body: DutyDaySaveBody) -> dict`
- 校验:每个 slot `len(assignments) <= capacity`;停用已有报名的 shift 须先清空
- upsert day(按 tenant+date);token 仅首次生成
- soft-delete 去掉的 slots(无报名时)与多余 assignments
- `set_link_status(db, tenant_no, day_id, status)`
- `soft_delete_assignment(db, tenant_no, assignment_id)`
- `get_public_page(db, token) -> dict`(无效 404 语义)
- `grab(db, token, shift_type, person_name) -> dict`
- 关链拒绝;姓名规范化;`with_for_update` 锁 slot 行或 day 行;`count < capacity` 再 insert `source=grab`
序列化字段用 camelCase,与前端一致:`dutyDate`, `linkStatus`, `accessToken`, `publicUrl`, `shiftType`, `shiftLabel`, `capacity`, `taken`, `assignments: [{ id, source, userId, personName }]`。
- [ ] **Step 5: 补充 DB 级单测(可用现有测试 DB fixture;若无 fixture,则 mock Session 测分支)**
至少覆盖:
1. `grab` 在 capacity=1 时第二次失败
2. `link_status=closed` 时 grab 失败
3. `save_day` 缩容小于已报名人数抛错
- [ ] **Step 6: 跑通测试**
```bash
cd backend && source venv/bin/activate && pytest tests/test_duty_schedule.py -v
```
Expected: PASS
- [ ] **Step 7: Commit**
```bash
git add backend/app/schemas/duty.py backend/app/services/duty_schedule.py backend/tests/test_duty_schedule.py
git commit -m "$(cat <<'EOF'
feat(duty): add schemas and duty_schedule service with capacity tests
EOF
)"
```
---
### Task 4: 管理端 + 公开 API 路由注册
**Files:**
- Create: `backend/app/api/duty.py`
- Create: `backend/app/api/public_duty.py`
- Modify: `backend/app/main.py`
- Modify: `backend/app/core/config.py`
- [ ] **Step 1: 管理路由** `prefix="/web/admin/duty"`
```python
# 关键端点(均 Depends 现有 admin 鉴权,如 require_admin_or_super_admin / 菜单守卫)
GET ""?year=&month= -> month summary
GET "/day?dutyDate=YYYY-MM-DD" -> day detail(无则返回空骨架 slots=[])
POST "/day" -> save_day body
POST "/day/{dayId}/link" -> { linkStatus }
DELETE "/assignments/{id}" -> soft delete
```
鉴权用户取 `tenant_no`、`user_id`、`create_dept_id`(与 leave 一致)。指定用户时用现有用户查询解析姓名写入 `person_name`。
- [ ] **Step 2: 公开路由** `prefix="/public/duty"`
```python
GET "/{token}" -> get_public_page;404 文案「链接无效或已失效」
POST "/{token}/grab" -> DutyGrabBody;业务错误用 error_response / HTTP 400
```
- [ ] **Step 3: `main.py` 注册**
```python
from app.api.duty import router as duty_router
from app.api.public_duty import router as public_duty_router
# ...
app.include_router(duty_router, prefix=settings.API_V1_PREFIX)
app.include_router(public_duty_router, prefix=settings.API_V1_PREFIX)
```
- [ ] **Step 4: 加密排除**
在 `API_ENCRYPT_EXCLUDE_PATHS` 追加:
```
"/api/public/duty,"
```
检查 `web-admin/.env.development` 与 `.env.production` 的 `VITE_API_ENCRYPT_EXCLUDE_PATHS`,若存在则同样追加 `/api/public/duty`。
- [ ] **Step 5: 手工用 curl/Swagger 冒烟**
```bash
# 登录后 POST /api/web/admin/duty/day 创建某日
# GET /api/public/duty/{token}
# POST /api/public/duty/{token}/grab {"shiftType":"evening","personName":"测试"}
```
- [ ] **Step 6: Commit**
```bash
git add backend/app/api/duty.py backend/app/api/public_duty.py backend/app/main.py backend/app/core/config.py web-admin/.env.development web-admin/.env.production
git commit -m "$(cat <<'EOF'
feat(duty): register admin and public duty APIs with encrypt exclude
EOF
)"
```
---
### Task 5: web-admin 管理端月历页
**Files:**
- Create: `web-admin/src/api/duty.ts`
- Create: `web-admin/src/views/duty/schedule/index.vue`
- 菜单 component 已指向 `/duty/schedule/index`(动态路由按现有菜单加载)
- [ ] **Step 1: API 模块**
```typescript
// web-admin/src/api/duty.ts
import request from '@/utils/http'
export type ShiftType = 'morning' | 'evening' | 'duty'
export const fetchDutyMonth = (year: number, month: number) =>
request.get({ url: '/web/admin/duty', params: { year, month } })
export const fetchDutyDay = (dutyDate: string) =>
request.get({ url: '/web/admin/duty/day', params: { dutyDate } })
export const saveDutyDay = (data: unknown) =>
request.post({ url: '/web/admin/duty/day', data })
export const setDutyLinkStatus = (dayId: string, linkStatus: 'open' | 'closed') =>
request.post({ url: `/web/admin/duty/day/${dayId}/link`, data: { linkStatus } })
export const deleteDutyAssignment = (id: string) =>
request.del({ url: `/web/admin/duty/assignments/${id}` })
```
(若项目 `request` 方法名是 `delete` 而非 `del`,与邻近 API 文件保持一致。)
- [ ] **Step 2: 月历页**
实现要求(对齐 `docs/demos/duty-schedule-v1-demo.html` + Fresh Mint):
- `panel-top` + `h2.title-bar-heading`「值班排班」
- 月切换、今天
- 7 列日历网格(可用纯 CSS/table,不必上 FullCalendar)
- 日格展示 chip:早班/晚班/值班颜色区分(管理端可用琥珀/蓝/红浅底,勿用小程序主色当 primary 按钮)
- 点击日期打开 `el-dialog`:`label-position="top"`,`modal-class` 无 blur,`dialog-form-layout`
- 弹窗内三个可启用班次:`capacity` + 系统用户选择(复用现有用户远程搜索/选择组件,参考 `system/user` 或其它选人控件)+ 已安排 tags(指定/抢班)可删
- 复制 `publicUrl`;开关链接按钮
- 保存调用 `saveDutyDay`;缩容错误展示后端 message
按钮均带 `<el-icon>`。
- [ ] **Step 3: 本地 `pnpm dev` 打开菜单验证月历加载与保存**
- [ ] **Step 4: Commit**
```bash
git add web-admin/src/api/duty.ts web-admin/src/views/duty/schedule/index.vue
git commit -m "$(cat <<'EOF'
feat(duty): add web-admin calendar schedule page
EOF
)"
```
---
### Task 6: 公开 H5 页
**Files:**
- Create: `web-admin/src/api/public-duty.ts`
- Create: `web-admin/src/views/public/duty/index.vue`
- Modify: `web-admin/src/router/routes/staticRoutes.ts`
- [ ] **Step 1: 静态路由**(插在其它 public 路由旁)
```typescript
{
path: '/public/duty/:token',
name: 'PublicDutyGrab',
component: () => import('@views/public/duty/index.vue'),
meta: { title: '值班抢班', isHideTab: true, isPublicMobile: true }
},
```
- [ ] **Step 2: 公开 API**
```typescript
import { publicPlGet, publicPlPost } from '@/utils/http/public-pl'
export const publicDutyApi = {
getPage: (token: string) => publicPlGet<any>(`/public/duty/${token}`),
grab: (token: string, data: { shiftType: string; personName: string }) =>
publicPlPost<any>(`/public/duty/${token}/grab`, data)
}
```
- [ ] **Step 3: H5 页面**
对齐 `docs/demos/duty-h5-grab-demo.html`:
- 三墙色:`#0a9f6d` / `#087f57` / `#e9f9f2` / `#f5f8f7`
- 状态:加载中 / 无效 / 已关闭 / 可抢列表 / 成功摘要
- 班次独立卡片;满员禁用;可抢输入姓名(max 20)提交
- `onMounted` 读 `route.params.token`
参考 `web-admin/src/views/public/pl/transport/index.vue` 的公开页壳与错误处理。
- [ ] **Step 4: 端到端手测**
1. 管理端建日 → 复制链接 → 无痕打开 H5
2. 抢晚班成功 → 再抢同班次满员失败
3. 关链 → H5 显示关闭
4. 管理端删人 → 名额释放可再抢
- [ ] **Step 5: Commit**
```bash
git add web-admin/src/api/public-duty.ts web-admin/src/views/public/duty/index.vue web-admin/src/router/routes/staticRoutes.ts
git commit -m "$(cat <<'EOF'
feat(duty): add public H5 grab page for daily duty links
EOF
)"
```
---
### Task 7: 收尾与图谱
**Files:**
- 按需更新 `docs/sql/` 备注或拷贝 migrate 说明
- 跑 `./scripts/update-graph.sh backend` 与 `frontend`(或 `graphify update .`)
- [ ] **Step 1: 对照 spec 验收清单勾选**(设计文档「测试要点」7 条)
- [ ] **Step 2: 更新知识图谱**
```bash
./scripts/update-graph.sh all
# 或
graphify update .
```
- [ ] **Step 3: 最终 commit(若有 docs/sql 或 graph 变更)**
```bash
git add docs/sql backend/graphify-out web-admin/graphify-out graphify-out
git commit -m "$(cat <<'EOF'
chore(duty): sync sql notes and knowledge graph after duty schedule
EOF
)"
```
---
## Spec 覆盖自检
| Spec 项 | Task |
|---------|------|
| D1 web + 公开 H5 | 5, 6 |
| D2 一天一链接 | 1–4 save_day token |
| D3 班次独立罗列 | 6 |
| D4 只填姓名 | 3 grab / 6 |
| D5 系统用户指定 | 4–5 |
| D6/D7 员工不可取消、经理可改 | 4 delete/save/link |
| D8 无统计页 | 5 仅日历 |
| D9 预置班次 | models 常量 |
| D10 按天建 | 5 点日配置 |
| D11 同日多班次 | grab 不按人跨 slot 限制 |
| D12 token 不重置 | save_day |
| D13 缩容校验 | service + test |
| D14 历史可改 | 无冻结逻辑 |
| D15 菜单权限 | migrate menu |
| 加密排除 | Task 4 |
| 并发满员 | grab + test |
**V1 限流:** 若无现成中间件,可在 `grab` 内不做强限流,验收文档注明「后续可加」;不阻塞主路径(YAGNI)。若已有简易 IP 限流工具则挂上。
---
## 执行方式
Plan 已保存。可选:
1. **Subagent-Driven(推荐)** — 每任务新开子代理,任务间审查
2. **Inline Execution** — 本会话按 executing-plans 连续推进并设检查点
请选择一种,或指出计划中要先改的部分。
@@ -0,0 +1,205 @@
# 值班排班(日历 + 公开链接抢班)— 设计文档
> **日期**: 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`