v6ole/qiji
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 请假功能设计文档

Browse Source 
Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
v6ole
2026-07-12 12:48:19 +08:00
parent e8b92a6f99
commit 531df448c1
1 changed files with 349 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/superpowers/specs/2026-07-12-leave-management-design.md
+349
View File
@@ -0,0 +1,349 @@
# 客户经理请假功能 — 设计文档
> 日期：2026-07-12 | 状态：已确认
## 一、需求概述
为政企周报管理系统添加客户经理请假功能。请假可由客户经理自己提交或支局长代为提交，提交即生效（无需审批）。请假期间免填报考核、免催办提醒，AI 周报摘要标注请假信息。
## 二、核心决策
| 决策项 | 结论 |
|--------|------|
| 粒度 | 按天（start_date ~ end_date） |
| 审批 | 无需审批，提交即生效 |
| 类型 | 年假 / 事假 / 病假 / 调休 / 其他 |
| 权限 | 经理看自己，支局长/领导看全员 |
| 入口 | PC 端仪表盘卡片 + 独立页面 + 移动端首页 + 表单页 |
## 三、数据模型
### 新增表 `leaves`
```sql
CREATE TABLE leaves (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
manager_id UUID NOT NULL REFERENCES users(id),
leave_type VARCHAR(20) NOT NULL DEFAULT '事假', -- 年假/事假/病假/调休/其他
start_date DATE NOT NULL,
end_date DATE NOT NULL,
reason VARCHAR(500) DEFAULT '',
submitted_by UUID NOT NULL REFERENCES users(id), -- 提交人（本人或支局长）
created_at TIMESTAMPTZ DEFAULT now(),
updated_at TIMESTAMPTZ DEFAULT now()
);
CREATE INDEX idx_leaves_manager_id ON leaves(manager_id);
CREATE INDEX idx_leaves_dates ON leaves(start_date, end_date);
```
### 设计要点
- `start_date <= end_date`，应用层校验
- 判断"今天是否请假中"：`start_date <= today <= end_date`
- 判断"本周是否有请假"：`start_date <= sunday AND end_date >= monday`
- 无 edit_log 列（请假记录简单，不追变更历史）
### SQLAlchemy 模型
```python
class Leave(Base):
__tablename__ = "leaves"
id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
manager_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), ForeignKey("users.id"), index=True)
leave_type: Mapped[str] = mapped_column(String(20), default="事假")
start_date: Mapped[date] = mapped_column(Date)
end_date: Mapped[date] = mapped_column(Date)
reason: Mapped[str] = mapped_column(String(500), default="")
submitted_by: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), ForeignKey("users.id"))
created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now())
```
## 四、业务逻辑变更
### 4.1 填报进度判断 (`get_reporting_progress`)
**文件：** `backend/app/services/dashboard.py`
变更点：
1. 查询本周所有请假记录（`start_date <= sunday AND end_date >= monday`）
2. 对每个经理判断今日是否在请假区间内
3. 新增第四种状态 `on_leave`
```python
# 新增返回字段
{
"manager_id": "uuid",
"has_reported_today": bool,
"completed": bool,
"on_leave": bool, # ← 新增
"leave_info": { # ← 新增（仅 on_leave=True 时有值）
"leave_type": "事假",
"start_date": "...",
"end_date": "..."
} | null
}
```
前端三色状态扩展为四色：
| 状态 | 条件 | 颜色 | 印章 |
|------|------|------|------|
| `full` | 已填 + 完成 | 绿 (sage) | 满 |
| `catching` | 已填 + 追赶中 | 黄 (gold) | 追 |
| `missing` | 未填 | 红 (vermilion) | 未 |
| `on_leave` | 请假中 | 蓝灰 | 假 |
### 4.2 催办提醒 (`check_daily_reporting`)
**文件：** `backend/app/services/scheduler.py`
变更点：
1. 查询当天请假中的经理（`start_date <= today <= end_date`）
2. 从催办列表中排除这些经理
3. 汇总消息标注"X人请假，已豁免"
### 4.3 仪表盘统计卡
**文件：** `backend/app/services/dashboard.py` + 前端 `Dashboard.vue`
新增第五张统计卡「本周请假」：
- 数字：本周请假总人数
- 数据来源：统计 `start_date <= sunday AND end_date >= monday` 的去重 manager 数
- 点击跳转 `/leaves`
- 颜色：蓝灰调
### 4.4 AI 摘要提示词
**文件：** `backend/app/services/ai_summary.py` → `build_summary_prompt()`
新增一节注入请假数据：
```markdown
## 本周请假情况
- 张三 (事假): 2026-07-13 ~ 2026-07-15 (3天)
- 李四 (年假): 2026-07-14 ~ 2026-07-17 (4天)
```
效果：LLM 生成的摘要会自然提及"本周张三请事假3天未参与拜访"等信息。
## 五、API 设计
所有接口挂载在 `/api/leaves`，需登录认证。
### 5.1 列表
```
GET /api/leaves?manager_id=xxx&status=active&page=1&page_size=25
```
权限：`director`/`leader` 看全员，`manager` 只返回自己的记录。
`status` 筛选项：`active`（进行中）/ `upcoming`（未来）/ `past`（已结束）/ 不传全部。
默认按 `start_date DESC` 排序。
### 5.2 新建
```
POST /api/leaves
```
```json
{
"manager_id": "uuid",
"leave_type": "年假",
"start_date": "2026-07-13",
"end_date": "2026-07-15",
"reason": "回老家"
}
```
权限：`manager` 只能给自己建（manager_id 必须等于自己），`director` 可以给任何人建。
校验：`end_date >= start_date`。
### 5.3 编辑
```
PUT /api/leaves/{id}
```
请求体同新建。权限：`director` 可编辑任意记录，`manager` 仅可编辑自己提交且尚未开始的记录。
### 5.4 删除
```
DELETE /api/leaves/{id}
```
权限：同编辑。
### 5.5 概览（仪表盘用）
```
GET /api/leaves/overview?reference_date=2026-07-12
```
```json
{
"week_start": "2026-07-13",
"week_end": "2026-07-19",
"total_on_leave": 2,
"leave_list": [
{
"manager_id": "uuid",
"manager_name": "张三",
"leave_type": "事假",
"start_date": "2026-07-13",
"end_date": "2026-07-15",
"days": 3
}
]
}
```
权限：`director`/`leader` 返回全员请假数据，`manager` 只返回自己。
## 六、前端设计
### 6.1 PC 端 — 仪表盘卡片
**文件：** `frontend/src/views/desktop/Dashboard.vue`
- 新增第五张统计卡「本周请假」
- 样式与现有四卡一致（stat-card + stat-glyph + 数字 + 标签）
- 颜色：蓝灰色调（`--slate` 系列 CSS 变量）
- 点击跳转 `/leaves`
- 数据来源：`GET /api/leaves/overview`
### 6.2 PC 端 — 请假管理页
**文件：** 新增 `frontend/src/views/desktop/Leaves.vue`
**路由：** `/leaves`，DesktopLayout 侧边栏「工作」分组下新增「请假管理」
**页面结构：**
- 顶部汇总栏：按请假类型分组统计条数（年假X / 事假X / 病假X / 调休X / 其他X）
- 筛选栏：按经理筛选（支局长/领导可见）、按状态筛选（进行中 / 即将开始 / 已结束）
- 表格列：姓名 + 类型（彩色标签）+ 日期范围 + 天数 + 原因摘要 + 提交人 + 操作（编辑/删除）
- 进行中的行蓝色左边框高亮
- 新增/编辑弹窗（el-dialog）：选择经理（支局长代填时）、请假类型 chip 按钮组、日期范围选择器、原因 textarea
**参考文件：**
- 汇总栏样式：参考 `WorkPlans.vue` / `KeyVisits.vue` 的顶部汇总栏
- 表格模式：参考 `CustomerManage.vue` 的 el-table + 分页
- 表单弹窗：参考各独立工作页的 CRUD 弹窗
### 6.3 PC 端 — 填报进度卡片
**文件：** `frontend/src/views/desktop/Dashboard.vue`
- 请假中的经理卡片：蓝色「假」印章水印 + 灰色进度条 + "请假中"文案
- 不计入未填报人数统计
### 6.4 PC 端 — 侧边栏
**文件：** `frontend/src/components/DesktopLayout.vue`
侧边栏「工作」分组新增：
```
工作
├─ 工作计划
├─ 商机跟单
├─ 要客拜访
└─ 请假管理 ← 新增，📋 icon
```
### 6.5 移动端 — 首页入口
**文件：** `frontend/src/views/mobile/Home.vue`
- 在快捷按钮区域（现有「工作计划」「商机跟单」「要客拜访」旁）新增「请假」chip
- 如果当前有进行中的请假，chip 右上角显示蓝色小圆点
- 点击跳转 `/m/leaves`
### 6.6 移动端 — 请假列表页
**文件：** 新增 `frontend/src/views/mobile/LeavesList.vue`
**路由：** `/m/leaves`
- 卡片流式列表（参考 Home.vue 的记录卡片风格）
- 每条记录：类型彩色标签 + 日期范围 + 天数 + 原因
- 进行中的卡片蓝色左边框
- 顶部有「新建请假」按钮（ink 风格全宽按钮）
### 6.7 移动端 — 请假表单页
**文件：** 新增 `frontend/src/views/mobile/LeaveForm.vue`
**路由：** `/m/leave/new` + `/m/leave/:id/edit`（复用同一组件）
- 沿用现有移动端表单模式（editorial header + 返回按钮 + 中文标题 + 英文副标题 + 金色装饰线）
- 请假类型：chip 按钮组（年假/事假/病假/调休/其他），参考 VisitForm 的拜访方式 chip
- 日期范围：开始日期 → 结束日期
- 原因：textarea，选填
- 提交按钮：全宽暗色按钮「提交请假」
- 编辑模式下额外显示删除按钮（vermilion 描边）
### 6.8 移动端 — 路由配置
**文件：** `frontend/src/router/index.ts`
新增 3 条移动端路由：
```typescript
{ path: 'leaves', component: LeavesList }, // /m/leaves
{ path: 'leave/new', component: LeaveForm }, // /m/leave/new
{ path: 'leave/:id/edit', component: LeaveForm }, // /m/leave/:id/edit
```
## 七、文件变更清单
### 后端新增
| 文件 | 说明 |
|------|------|
| `backend/app/models/leave.py` | Leave SQLAlchemy 模型 |
| `backend/app/schemas/leave.py` | Pydantic 请求/响应 schema |
| `backend/app/api/leaves.py` | REST API 路由 |
| `backend/app/services/leaves.py` | 业务逻辑层 |
| `backend/alembic/versions/xxxx_add_leaves_table.py` | 数据库迁移 |
### 后端修改
| 文件 | 改动 |
|------|------|
| `backend/app/services/dashboard.py` | 填报进度 +`on_leave` 状态；统计卡 +请假数 |
| `backend/app/services/scheduler.py` | 催办过滤请假人员 |
| `backend/app/services/ai_summary.py` | `build_summary_prompt` 注入请假数据 |
| `backend/app/models/__init__.py` | 导入 Leave 模型 |
| `backend/app/main.py` | 注册 leaves 路由 + lifespan 自动建表 |
### 前端新增
| 文件 | 说明 |
|------|------|
| `frontend/src/views/desktop/Leaves.vue` | PC 端请假管理页 |
| `frontend/src/views/mobile/LeavesList.vue` | 移动端请假列表页 |
| `frontend/src/views/mobile/LeaveForm.vue` | 移动端请假表单页 |
| `frontend/src/api/leaves.ts` | Axios API 模块 |
### 前端修改
| 文件 | 改动 |
|------|------|
| `frontend/src/views/desktop/Dashboard.vue` | 新增请假统计卡 + 填报进度 on_leave 状态 |
| `frontend/src/components/DesktopLayout.vue` | 侧边栏新增请假管理入口 |
| `frontend/src/router/index.ts` | 新增 /leaves + /m/leaves 等路由 |
| `frontend/src/views/mobile/Home.vue` | 新增请假快捷入口 chip |
## 八、验证要点
1. 经理提交请假后，当天仪表盘填报进度显示蓝「假」状态
2. 请假中的经理不收到催办提醒
3. 支局长可代任意经理提交请假
4. AI 摘要中体现请假信息
5. 移动端可完成请假提交→列表查看→编辑→删除全流程
6. 历史周翻看时，请假数据对应当时的日期区间