feat(oa): add leave kit with auto duration calculation

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
zlwuandCursor committed 2026-07-30 17:54:48 +08:00
1 parent b3d267e9ca
commit 3b46b10604
10 files changed
+1337

No files matched your search

@@ -0,0 +1,202 @@
# OA Leave Kit(请假套件)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:** 在审批「2 表单设计」增加「套件」菜单与请假套件:拖入后得到套件容器(工时属性)+ 四个基础子字段;发起时按双段工时自动算时长(可手改);提交时后端权威重算/校验。
**Architecture:** FormCreate 扩展 `leaveKit` 布局容器(`input: false`,可拖入子组件,默认带 4 子字段)+ `menu: 'kit'`。工时在容器 `props`。纯函数 `calcLeaveHours` 前后端各一份。发起页对 schema 中 leaveKit 绑定 watch;`start_instance` 调用 `apply_leave_kit_hours`。
**Tech Stack:** Vue 3 · `@form-create/designer` · Element Plus · FastAPI · pytest · Node `node:test`(前端算法单测)
**Spec:** `docs/superpowers/specs/2026-07-30-oa-leave-kit-design.md`
**Demo:** `docs/mockups/oa-form-kit-tab-demo.html`
---
## File map
| Path | Responsibility |
|------|----------------|
| Create: `web-admin/src/utils/oa-leave-hours.ts` | 重叠工时计算纯函数 |
| Create: `web-admin/src/utils/oa-leave-hours.test.ts` | 算法单测 |
| Create: `web-admin/src/components/oa-approval/OaLeaveKit.vue` | 套件容器 UI(设计器/运行时) |
| Create: `web-admin/src/utils/oa-leave-kit-rule.ts` | DragRule:menu=kit,默认 4 子字段 + 工时 props |
| Create: `web-admin/src/utils/oa-form-create-leave-kit.ts` | `addMenu('kit')` + `setupOaLeaveKit` |
| Create: `web-admin/src/utils/oa-leave-kit-runtime.ts` | 从 schema 解析 leaveKit、应用自动时长、手改标记 |
| Modify: `web-admin/src/main.ts` | 注册 leaveKit |
| Modify: `web-admin/src/oa-fc-host/main.ts` | 同上 |
| Modify: `web-admin/src/views/oa-approval/start/index.vue` | 发起页联动时长 |
| Create: `backend/app/services/oa_leave_hours.py` | 同算法 + `apply_leave_kit_hours` |
| Create: `backend/tests/test_oa_leave_hours.py` | pytest |
| Modify: `backend/app/services/oa_publish.py` | `LAYOUT_TYPES` 加 `leaveKit` |
| Modify: `backend/app/services/oa_engine.py` | `start_instance` 调用 apply |
| Modify: `docs/superpowers/specs/2026-07-30-oa-leave-kit-design.md` | 状态 → 实现中/已实现 |
---
### Task 1: Leave hours algorithm (TDD, frontend)
**Files:**
- Create: `web-admin/src/utils/oa-leave-hours.ts`
- Create: `web-admin/src/utils/oa-leave-hours.test.ts`
- [ ] **Step 1: Write failing tests**
```ts
// web-admin/src/utils/oa-leave-hours.test.ts
import { describe, it } from 'node:test'
import assert from 'node:assert/strict'
import { calcLeaveHours, DEFAULT_LEAVE_WORK_HOURS } from './oa-leave-hours'
describe('calcLeaveHours', () => {
const wh = DEFAULT_LEAVE_WORK_HOURS // 08:30-12:00, 13:00-17:30
it('same day morning+afternoon sample 09:00-15:00 => 5.0', () => {
assert.equal(calcLeaveHours('2026-07-30 09:00', '2026-07-30 15:00', wh), 5.0)
})
it('only morning', () => {
assert.equal(calcLeaveHours('2026-07-30 08:30', '2026-07-30 12:00', wh), 3.5)
})
it('gap across lunch not counted', () => {
assert.equal(calcLeaveHours('2026-07-30 11:00', '2026-07-30 14:00', wh), 2.0)
})
it('end before start => null', () => {
assert.equal(calcLeaveHours('2026-07-30 15:00', '2026-07-30 09:00', wh), null)
})
it('invalid => null', () => {
assert.equal(calcLeaveHours('', '2026-07-30 09:00', wh), null)
})
})
```
- [ ] **Step 2: Run tests — expect FAIL**
```bash
cd web-admin && pnpm exec tsx --test src/utils/oa-leave-hours.test.ts
```
- [ ] **Step 3: Implement `oa-leave-hours.ts`**
Export:
- `DEFAULT_LEAVE_WORK_HOURS = { morningStart, morningEnd, afternoonStart, afternoonEnd }`
- `calcLeaveHours(start, end, workHours): number | null` — 1 decimal, null if invalid/end≤start
- Overlap minutes with morning+afternoon segments per calendar day
- [ ] **Step 4: Run tests — expect PASS**
- [ ] **Step 5: Commit**(仅当用户要求 commit 时执行;本会话默认可暂缓)
---
### Task 2: Backend leave hours + publish whitelist
**Files:**
- Create: `backend/app/services/oa_leave_hours.py`
- Create: `backend/tests/test_oa_leave_hours.py`
- Modify: `backend/app/services/oa_publish.py` — add `leaveKit` to `LAYOUT_TYPES`
- Modify: `backend/app/services/oa_engine.py` — after formulas, call `apply_leave_kit_hours`
- [ ] **Step 1: pytest failing** for `calc_leave_hours` 09:00–15:00 → 5.0
- [ ] **Step 2: Implement** `calc_leave_hours` + `apply_leave_kit_hours(schema, data)`:
- Walk rules for `type == leaveKit`
- Find children fields: prefer props `startField`/`endField`/`durationField` if set, else by title/order (select, datePicker, datePicker, inputNumber)
- If duration props `durationManual` truthy: validate ≥0 one decimal only
- Else overwrite duration with calc result
- [ ] **Step 3: Wire `start_instance`**
- [ ] **Step 4: pytest PASS**
---
### Task 3: FormCreate leaveKit container + kit menu
**Files:**
- Create: `OaLeaveKit.vue` — 虚线框 + 标题「请假套件」+ `<slot />`
- Create: `oa-leave-kit-rule.ts` — DragRule
- Create: `oa-form-create-leave-kit.ts` — addMenu + component + addDragRule
- Modify: `main.ts`, `oa-fc-host/main.ts`
DragRule essentials:
```ts
{
menu: 'kit',
icon: 'icon-date',
label: '请假',
name: 'leaveKit',
input: false,
drag: true,
mask: false,
inside: true,
rule() {
return {
type: 'leaveKit',
props: { ...DEFAULT_LEAVE_WORK_HOURS },
children: [ /* select, 2x datePicker datetime, inputNumber duration */ ]
}
},
props() {
return [ /* 4x time inputs for morning/afternoon */ ]
}
}
```
`setupOaLeaveKit`:
```ts
FcDesigner.addMenu({ name: 'kit', title: '套件', list: [] })
FcDesigner.component('leaveKit', OaLeaveKit)
formCreate.component('leaveKit', OaLeaveKit)
FcDesigner.addDragRule(leaveKitDragRule)
```
子字段 field 用 uniqueId;时长 `props.precision=1`, `props.durationManual=false`;日期 `props.type='datetime'`, format/valueFormat=`YYYY-MM-DD HH:mm`。
---
### Task 4: Start form runtime linkage
**Files:**
- Create: `oa-leave-kit-runtime.ts` — `listLeaveKits(schema)`, `applyLeaveKitDurations(schema, formData, { respectManual })`
- Modify: `start/index.vue` — on form-create change / watch formData,未手改时写回时长;用户改时长字段时设 `durationManual`(若无法写回 schema,用并行隐藏字段或 formData 旁路 `__leaveDurationManual_<field>`;优先改 rule props 若 api 允许)
手改标记落地(择一,实现时选可工作的):
1. 时长字段 `props.durationManual`(设计器可读)+ 提交时由前端把 manual 状态塞进 formData 特殊 key,后端读取;或
2. formData 增加 `__manual_<durationField>: true`,后端识别后不覆盖。
**采用 2(更简单跑通)**:发起人手改时长 → 设 `formData['__manual_' + durationField] = true`;后端 `apply_leave_kit_hours` 检查该 key。
「恢复自动计算」:首期发起页可不做按钮,手改后仅断开;设计器 Demo 已有示意。Spec 中的恢复按钮可作为二期(或 start 页时长旁小链,有则加)。
---
### Task 5: Spec status + graphify + smoke checklist
- Update design doc status
- `./scripts/update-graph.sh frontend`(若改了 web-admin)
- Manual: designer 套件 Tab → 拖请假 → 配工时 → 发起算时长
---
## Spec coverage
| Spec 项 | Task |
|---------|------|
| 套件 Tab 双列卡片 | T3 |
| 4 基础字段 + 套件工时 | T3 |
| 双段重叠算法 1 位小数 | T1/T2 |
| 手改后不联动 | T4 + T2 |
| 发布白名单 leaveKit | T2 |
| 提交权威 | T2 |
| 多套 field 唯一 | T3 uniqueId |
| 恢复自动计算 | T4 可选/二期 |
---
## Execution
用户已要求继续开发:本会话采用 **Inline Execution**(executing-plans)。
@@ -0,0 +1,268 @@
# OA 表单设计 · 请假套件(Leave Kit)设计文档
**日期**: 2026-07-30
**状态**: 已实现(计划见 `docs/superpowers/plans/2026-07-30-oa-leave-kit.md`)
**范围**: `web-admin` 审批设计器「2 表单设计」套件 Tab + 发起/详情运行时;`backend` 时长重算与发布/提交校验
**界面模式**: 对齐 FormCreate 左侧控件库;视觉 Fresh Mint
**Demo**: `docs/mockups/oa-form-kit-tab-demo.html`
**前置**: `docs/superpowers/specs/2026-07-14-oa-approval-dingtalk-design.md` §4.5 / §4.6 / §5.4
---
## 1. 背景与目标
客户希望在「2 表单设计」左侧「组件」旁增加 **套件** Tab:将常用业务字段组合为一键插入的预制包。首个套件为 **请假套件**。
### 1.1 目标
- 左侧增加 **套件** Tab(位于「组件」之后),展示模式与「组件」一致(双列小卡片)。
- **请假套件** = 4 个基础组件拼装 + 套件级属性(上午/下午上班时段)。
- 时长按工时时段重叠自动计算(小时,1 位小数);支持手改后断开联动。
- Schema / form_data 仍符合双端契约;子字段可参与条件分支。
### 1.2 非目标(首期)
- 午休单独配置、节假日/工作日历、按工作日扣减。
- 租户全局考勤设置(工时挂在**套件实例**属性)。
- 出差 / 加班 / 报销等其它套件(可灰显占位)。
- 一体复合控件(单 type 包四字段对象值)——已否决,采用方案 1。
---
## 2. 产品决策(已确认)
| 项 | 决策 |
|----|------|
| 左侧 UI | Tab:`组件` → `套件` → `大纲`;套件独立 Tab(不出现在「组件」里);双列小卡片 |
| 组成 | 4 个**基础组件**拼装;套件容器上配置工时属性 |
| 字段 | 请假类型、开始时间、结束时间、时长(h) |
| 类型选项 | 内置:事假、调休、病假、年假、产假、陪产假、婚假、例假、丧假、哺乳假;设计器可维护 |
| 计量单位 | 全部按**小时** |
| 时间精度 | 开始/结束:年月日时分(`YYYY-MM-DD HH:mm`) |
| 工时模型 | 上午时段 + 下午时段;间隙(午休)自然不计 |
| 默认时段 | 上午 `08:30–12:00`,下午 `13:00–17:30` |
| 配置位置 | **套件实例属性**(每个审批应用各自配置) |
| 时长手改 | 默认可改;手改后不再随起止/工时自动重算;提供「恢复自动计算」 |
| 小数 | 保留 **1** 位小数 |
| 实现方案 | 方案 1:套件容器 + 展开/内嵌基础子字段(非一体 `leaveKit` 值对象) |
---
## 3. 信息模型
### 3.1 心智模型
```
┌─ 请假套件(组装体 / 容器)─────────────────────┐
│ 套件属性:上午时段、下午时段 │
│ │
│ · 基础·下拉 → 请假类型 │
│ · 基础·日期时间 → 开始时间 │
│ · 基础·日期时间 → 结束时间 │
│ · 基础·数字 → 时长(h) │
└─────────────────────────────────────────────────┘
```
- 选中**套件容器**:配置工时时段等套件属性(设计器右侧);运行时/发起页**不**额外渲染套件边框或标题,子字段与单独拖入的标准组件样式一致。
- 选中**子字段**:配置标题、必填、选项等(与普通组件相同)。
### 3.2 Schema 结构(示意)
容器类型建议登记为 `leaveKit`(布局类,不计可填字段数),或复用 `group` 并带 `_fc_kit: 'leave'` 标记。推荐独立 `leaveKit` 便于发布校验与选中态属性面板。
```json
{
"type": "leaveKit",
"props": {
"morningStart": "08:30",
"morningEnd": "12:00",
"afternoonStart": "13:00",
"afternoonEnd": "17:30"
},
"children": [
{
"type": "select",
"field": "leaveType",
"title": "请假类型",
"options": [
{ "label": "事假", "value": "事假" },
{ "label": "调休", "value": "调休" },
{ "label": "病假", "value": "病假" },
{ "label": "年假", "value": "年假" },
{ "label": "产假", "value": "产假" },
{ "label": "陪产假", "value": "陪产假" },
{ "label": "婚假", "value": "婚假" },
{ "label": "例假", "value": "例假" },
{ "label": "丧假", "value": "丧假" },
{ "label": "哺乳假", "value": "哺乳假" }
],
"$required": true
},
{
"type": "datePicker",
"field": "leaveStart",
"title": "开始时间",
"props": { "type": "datetime", "format": "YYYY-MM-DD HH:mm", "valueFormat": "YYYY-MM-DD HH:mm" },
"$required": true
},
{
"type": "datePicker",
"field": "leaveEnd",
"title": "结束时间",
"props": { "type": "datetime", "format": "YYYY-MM-DD HH:mm", "valueFormat": "YYYY-MM-DD HH:mm" },
"$required": true
},
{
"type": "inputNumber",
"field": "leaveDuration",
"title": "时长(h)",
"props": {
"precision": 1,
"min": 0,
"durationManual": false
},
"$required": true
}
]
}
```
说明:
- 子字段 `field` 插入时生成唯一 ID(同表单可插入多套请假套件,自动去重后缀)。
- 子字段通过 `props.kitRef` 或父 `leaveKit` 关联,用于运行时读取工时配置。
- `durationManual` 存在时长字段 props;发起人手改后置 `true`。
### 3.3 form_data
```json
{
"leaveType": "事假",
"leaveStart": "2026-07-30 09:00",
"leaveEnd": "2026-07-30 15:00",
"leaveDuration": 5.5
}
```
| 字段 | JSON 值形态 |
|------|-------------|
| 请假类型 | `string`(选项 value) |
| 开始/结束 | `string`,`YYYY-MM-DD HH:mm` |
| 时长 | `number`,一位小数 |
工时时段与 `durationManual` **不**作为业务展示主字段写入 form_data 的独立 key(配置在 schema);若运行时需回传手改状态,可在时长字段旁用约定 props 或并行隐藏字段,实现计划中二选一并保持双端一致。
---
## 4. 时长算法
### 4.1 规则
对闭开或闭闭区间,实现统一为:将 `[start, end]` 与每一天的上午段、下午段求交集,累加分钟数,再 `/ 60`,**四舍五入到 1 位小数**。
- 若 `end <= start`:时长视为无效(前端提示;后端拒绝或置 0 并报错)。
- 与任一时段无重叠:结果为 `0.0`。
- 跨天:按自然日切分后分别与两段求交再求和。
示例(默认工时):
- 开始 `09:00`,结束 `15:00`(同日)
→ 上午 `09:00–12:00`(3h)+ 下午 `13:00–15:00`(2h)= **5.0h**
(`12:00–13:00` 不计)
### 4.2 手改
| 状态 | 行为 |
|------|------|
| `durationManual = false` | 起止或套件工时变化时自动重算并写回时长 |
| `durationManual = true` | 不再自动重算;保留用户输入 |
| 「恢复自动计算」 | 清 `durationManual`,按当前起止与工时重算 |
### 4.3 前后端一致性
- 前端发起页:即时预览(未手改时)。
- 后端提交:
- **未手改**:按同一算法重算并**覆盖**提交时长后落库。
- **已手改**:信任提交时长,校验 `number ≥ 0` 且一位小数。
- 禁止任意 `eval`;算法放在独立纯函数模块(可与 `oa_formula` 并列,如 `oa_leave_hours.py` + 前端 `oa-leave-hours.ts`)。
---
## 5. 设计器与运行时交互
### 5.1 套件 Tab
- `FcDesigner.addMenu({ name: 'kit', title: '套件' })`(或等价配置),保证顺序在「组件」相关菜单之后。
- `addDragRule` 注册请假套件;视觉与基础组件卡片一致。
- 其它套件可 `coming` 占位,不注册拖拽或禁用。
### 5.2 拖入与编辑
| 操作 | 行为 |
|------|------|
| 拖入/点击请假 | 插入 `leaveKit` + 4 子字段 |
| 选中容器 | 右侧:上午/下午四个时间;校验段内 start &lt; end |
| 选中子字段 | 常规属性;类型字段可维护 options |
| 删除子字段 | 允许;套件不完整时发布 **警告可发**(不强制阻断) |
| 再拖一套 | **允许**;field 自动唯一 |
### 5.3 发起 / 详情 / 打印
- 四个子字段按基础组件渲染与打印。
- 套件容器不输出独立 form 值。
- 详情只读展示已保存时长;不再因工时变更重算历史单。
### 5.4 条件分支
子字段与普通字段相同:勾选「参与流程条件分支」后可在流程设计中引用(类型、时长等)。
---
## 6. 校验清单
### 6.1 设计器 / 发布
- `leaveKit`(或约定 group 标记)加入布局类白名单。
- 子 type 须为已允许的 `select` / `datePicker` / `inputNumber`(或项目现用等价 type)。
- 工时四段格式 `HH:mm`;上午/下午各自 start &lt; end;下午起点 &lt; 上午终点时仅 **提示**(不强制)。
### 6.2 提交
- 结束 ≥ 开始。
- 类型 ∈ 当前 options。
- 时长规则见 §4.3。
- 必填子字段非空。
---
## 7. 实现落点(指引,非任务拆解)
| 层 | 落点 |
|----|------|
| 设计器宿主 | `web-admin/src/oa-fc-host/`:菜单「套件」、拖拽规则、容器组件与属性 |
| 主应用注册 | 与金额/人员同类:`setupOaLeaveKit` + `main.ts` / `oa-fc-host/main.ts` |
| 算法前端 | `web-admin/src/utils/oa-leave-hours.ts` |
| 算法后端 | `backend/app/services/oa_leave_hours.py`;发起提交路径调用 |
| 发布白名单 | `backend/app/services/oa_publish.py` → `LAYOUT_TYPES` 增加 `leaveKit` |
| Demo | `docs/mockups/oa-form-kit-tab-demo.html` |
---
## 8. 验收标准
1. 「2 表单设计」左侧出现 **套件** Tab,样式与组件双列卡片一致;可插入请假套件。
2. 画布出现类型 / 开始 / 结束 / 时长四个基础字段;选中套件可配默认双段工时。
3. 类型含约定 10 项且可在设计器维护选项。
4. 未手改时,改起止后时长按重叠工时更新为 1 位小数;示例 09:00–15:00 → 5.0。
5. 手改时长后改起止不再变;「恢复自动计算」后恢复联动。
6. 提交后后端对未手改单据重算覆盖;已手改保留用户值(合法前提下)。
7. 手机预览可用;打印/详情展示四个字段值。
8. 子字段可勾选参与条件分支。
---
## 9. 开放问题(实现时可定)
- 手改状态是仅存 schema props,还是提交时附带隐藏字段:实现计划择一并写测试。
- Element Plus `datePicker` datetime 的 `valueFormat` 与后端解析严格对齐。
- 同一套件内删除「开始」后,时长字段是否自动禁用编辑提示:建议弱提示即可。