@@ -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. 历史周翻看时，请假数据对应当时的日期区间
|
||||
Reference in New Issue
Block a user