21 KiB
OA Trip 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: 在审批「套件」Tab 增加出差套件:事由 + 可增删多行程(钉钉半日制算时长)+ 出差天数汇总 / 备注 / 同行人 / 外部人员;提交时后端权威重算与校验;不回写业务表。
Architecture: FormCreate tripKit 布局容器(input: false,默认 6 子字段)+ 自定义可填控件 tripItinerary(v-model 为行程对象数组)。半日时长纯函数前后端各一份;发起页 watch 行程/天数;start_instance 调用 apply_trip_kit_days。手改标记:行内 durationManual;出差天数用 formData['__manual_' + daysField] = true(对齐请假套件)。
Tech Stack: Vue 3 · @form-create/designer · Element Plus · FastAPI · pytest · Node node:test
Spec: docs/superpowers/specs/2026-07-30-oa-trip-kit-design.md
File map
| Path | Responsibility |
|---|---|
Create: web-admin/src/utils/oa-trip-days.ts |
半日制时长 / 汇总纯函数 |
Create: web-admin/src/utils/oa-trip-days.test.ts |
算法单测 |
Create: backend/app/services/oa_trip_days.py |
同算法 + apply/validate |
Create: backend/tests/test_oa_trip_days.py |
pytest |
Create: web-admin/src/components/oa-approval/OaTripItinerary.vue |
行程列表 UI(增删、半日联动) |
Create: web-admin/src/utils/oa-trip-itinerary-rule.ts |
tripItinerary DragRule(一般不单独出现在组件库;由套件内嵌) |
Create: web-admin/src/utils/oa-form-create-trip-itinerary.ts |
注册 tripItinerary 控件 |
Create: web-admin/src/components/oa-approval/OaTripKit.vue |
套件容器 |
Create: web-admin/src/utils/oa-trip-kit-rule.ts |
套件 DragRule + 默认子字段 |
Create: web-admin/src/utils/oa-form-create-trip-kit.ts |
setupOaTripKit |
Create: web-admin/src/utils/oa-trip-kit-runtime.ts |
解析 schema、apply 自动时长/天数 |
Modify: web-admin/src/main.ts |
注册 itinerary + tripKit |
Modify: web-admin/src/oa-fc-host/main.ts |
同上 |
Modify: web-admin/src/oa-fc-host/App.vue |
拖入 tripKit 画布 refresh 白名单 |
Modify: web-admin/src/views/oa-approval/start/index.vue |
发起页联动 |
Modify: web-admin/src/utils/oa-approval-print.ts |
unwrap tripKit;格式化行程数组 |
Modify: backend/app/services/oa_publish.py |
LAYOUT_TYPES + FILLABLE_TYPES |
Modify: backend/app/services/oa_engine.py |
start_instance 调用 apply/validate |
Modify: docs/superpowers/specs/2026-07-30-oa-trip-kit-design.md |
状态 → 已实现 |
Task 1: Half-day algorithm (TDD, frontend)
Files:
-
Create:
web-admin/src/utils/oa-trip-days.ts -
Create:
web-admin/src/utils/oa-trip-days.test.ts -
Step 1: Write failing tests
// web-admin/src/utils/oa-trip-days.test.ts
import { describe, it } from 'node:test'
import assert from 'node:assert/strict'
import {
calcTripLegDays,
sumTripLegDays,
isHalfDayMultiple
} from './oa-trip-days'
describe('calcTripLegDays', () => {
it('same day morning->morning => 0.5', () => {
assert.equal(calcTripLegDays('2026-08-01', '上午', '2026-08-01', '上午'), 0.5)
})
it('same day morning->afternoon => 1', () => {
assert.equal(calcTripLegDays('2026-08-01', '上午', '2026-08-01', '下午'), 1)
})
it('same day afternoon->afternoon => 0.5', () => {
assert.equal(calcTripLegDays('2026-08-01', '下午', '2026-08-01', '下午'), 0.5)
})
it('same day afternoon->morning => null', () => {
assert.equal(calcTripLegDays('2026-08-01', '下午', '2026-08-01', '上午'), null)
})
it('D1 morning -> D2 afternoon => 2', () => {
assert.equal(calcTripLegDays('2026-08-01', '上午', '2026-08-02', '下午'), 2)
})
it('D1 afternoon -> D2 morning => 1', () => {
assert.equal(calcTripLegDays('2026-08-01', '下午', '2026-08-02', '上午'), 1)
})
it('invalid date => null', () => {
assert.equal(calcTripLegDays('', '上午', '2026-08-01', '下午'), null)
})
})
describe('sumTripLegDays', () => {
it('sums durations', () => {
assert.equal(sumTripLegDays([{ duration: 0.5 }, { duration: 1 }, { duration: 2 }]), 3.5)
})
it('ignores non-number', () => {
assert.equal(sumTripLegDays([{ duration: 1 }, { duration: null }]), 1)
})
})
describe('isHalfDayMultiple', () => {
it('accepts 0.5 steps', () => {
assert.equal(isHalfDayMultiple(1.5), true)
assert.equal(isHalfDayMultiple(1.25), false)
})
})
- Step 2: Run — expect FAIL
cd web-admin && pnpm exec tsx --test src/utils/oa-trip-days.test.ts
Expected: FAIL(模块不存在)
- Step 3: Implement
oa-trip-days.ts
// web-admin/src/utils/oa-trip-days.ts
const DATE_RE = /^(\d{4})-(\d{2})-(\d{2})$/
export type TripHalf = '上午' | '下午'
function dayIndex(dateStr: string): number | null {
const m = DATE_RE.exec(String(dateStr || '').trim())
if (!m) return null
const y = Number(m[1]), mo = Number(m[2]), d = Number(m[3])
const t = Date.UTC(y, mo - 1, d)
if (Number.isNaN(t)) return null
return t / 86400000
}
function startOffset(half: string): number | null {
if (half === '上午') return 0
if (half === '下午') return 0.5
return null
}
function endOffset(half: string): number | null {
if (half === '上午') return 0.5
if (half === '下午') return 1
return null
}
/** 非法或 endPoint <= startPoint 返回 null */
export function calcTripLegDays(
startDate: string,
startHalf: string,
endDate: string,
endHalf: string
): number | null {
const ds = dayIndex(startDate)
const de = dayIndex(endDate)
const so = startOffset(String(startHalf || '').trim())
const eo = endOffset(String(endHalf || '').trim())
if (ds == null || de == null || so == null || eo == null) return null
const duration = de + eo - (ds + so)
if (!(duration > 0)) return null
return Math.round(duration * 2) / 2
}
export function sumTripLegDays(legs: Array<{ duration?: unknown }>): number {
let sum = 0
for (const leg of legs || []) {
const n = Number(leg?.duration)
if (Number.isFinite(n) && n >= 0) sum += n
}
return Math.round(sum * 2) / 2
}
export function isHalfDayMultiple(n: unknown): boolean {
const v = Number(n)
if (!Number.isFinite(v) || v < 0) return false
return Math.abs(v * 2 - Math.round(v * 2)) < 1e-9
}
export function emptyTripLeg(): Record<string, unknown> {
return {
transport: '',
tripType: '',
fromCity: '',
toCity: '',
startDate: '',
startHalf: '上午',
endDate: '',
endHalf: '下午',
duration: null,
durationManual: false
}
}
- Step 4: Run — expect PASS
cd web-admin && pnpm exec tsx --test src/utils/oa-trip-days.test.ts
- Step 5: Commit
git add web-admin/src/utils/oa-trip-days.ts web-admin/src/utils/oa-trip-days.test.ts
git commit -m "feat(oa): add trip kit half-day duration helpers"
Task 2: Backend algorithm + apply/validate (TDD)
Files:
-
Create:
backend/app/services/oa_trip_days.py -
Create:
backend/tests/test_oa_trip_days.py -
Modify:
backend/app/services/oa_publish.py -
Modify:
backend/app/services/oa_engine.py(在 leave apply 之后插入 trip apply) -
Step 1: Write failing pytest
# backend/tests/test_oa_trip_days.py
from app.services.oa_trip_days import calc_trip_leg_days, sum_trip_leg_days, apply_trip_kit_days, validate_trip_kit_form_values
def test_half_day_samples():
assert calc_trip_leg_days("2026-08-01", "上午", "2026-08-01", "上午") == 0.5
assert calc_trip_leg_days("2026-08-01", "上午", "2026-08-01", "下午") == 1.0
assert calc_trip_leg_days("2026-08-01", "下午", "2026-08-01", "上午") is None
assert calc_trip_leg_days("2026-08-01", "下午", "2026-08-02", "上午") == 1.0
def test_sum():
assert sum_trip_leg_days([{"duration": 0.5}, {"duration": 2}]) == 2.5
def test_apply_overwrites_when_not_manual():
schema = [{
"type": "tripKit",
"props": {"tripListField": "L1", "tripDaysField": "D1"},
"children": [
{"type": "tripItinerary", "field": "L1", "props": {"_fc_kit_field": "tripList"}},
{"type": "inputNumber", "field": "D1", "props": {"_fc_kit_field": "tripDays"}},
],
}]
data = {
"L1": [{
"transport": "飞机", "tripType": "单程",
"fromCity": "合肥", "toCity": "上海",
"startDate": "2026-08-01", "startHalf": "上午",
"endDate": "2026-08-01", "endHalf": "下午",
"duration": 9, "durationManual": False,
}],
"D1": 9,
}
out = apply_trip_kit_days(schema, data)
assert out["L1"][0]["duration"] == 1.0
assert out["D1"] == 1.0
def test_respect_manual_flags():
schema = [{
"type": "tripKit",
"props": {"tripListField": "L1", "tripDaysField": "D1"},
"children": [
{"type": "tripItinerary", "field": "L1", "props": {"_fc_kit_field": "tripList"}},
{"type": "inputNumber", "field": "D1", "props": {"_fc_kit_field": "tripDays"}},
],
}]
data = {
"L1": [{
"startDate": "2026-08-01", "startHalf": "上午",
"endDate": "2026-08-01", "endHalf": "下午",
"duration": 3, "durationManual": True,
"transport": "火车", "tripType": "往返",
"fromCity": "a", "toCity": "b",
}],
"D1": 7,
"__manual_D1": True,
}
out = apply_trip_kit_days(schema, data)
assert out["L1"][0]["duration"] == 3
assert out["D1"] == 7
def test_validate_end_before_start():
schema = [{
"type": "tripKit",
"props": {"tripListField": "L1", "tripDaysField": "D1"},
"children": [
{"type": "tripItinerary", "field": "L1", "props": {"_fc_kit_field": "tripList"}},
{"type": "inputNumber", "field": "D1", "props": {"_fc_kit_field": "tripDays"}},
],
}]
data = {
"L1": [{
"transport": "飞机", "tripType": "单程",
"fromCity": "a", "toCity": "b",
"startDate": "2026-08-01", "startHalf": "下午",
"endDate": "2026-08-01", "endHalf": "上午",
"duration": 0.5, "durationManual": True,
}],
"D1": 0.5,
}
errs = validate_trip_kit_form_values(schema, data)
assert errs
- Step 2: Run — expect FAIL
cd backend && PYTHONPATH=. python -m pytest tests/test_oa_trip_days.py -v
- Step 3: Implement
oa_trip_days.py
要点(与前端公式一致):
calc_trip_leg_days/sum_trip_leg_days/is_half_day_multiple_walk_trip_kits(schema):找type == tripKit,解析tripListField/tripDaysField(props 优先,否则_fc_kit_field)apply_trip_kit_days(schema, data):- 对每行:若非
durationManual,用算法覆盖duration;算不出则保持原值 - 若
data.get("__manual_" + daysField)非真,则data[daysField] = sum(leg durations)
- 对每行:若非
validate_trip_kit_form_values:- 列表为 list 且
len >= 1 - 每行必填:transport/tripType/fromCity/toCity/startDate/startHalf/endDate/endHalf
calc_trip_leg_days(...)必须非 null(即结束晚于开始)- duration / days:
>= 0且半日倍数
- 列表为 list 且
手改约定:
MANUAL_PREFIX = "__manual_" # 出差天数
# 行程行:leg["durationManual"] is True
- Step 4: Wire publish + engine
oa_publish.py:
# FILLABLE_TYPES 增加
"tripItinerary",
# LAYOUT_TYPES 增加
"tripKit",
oa_engine.py(紧接 leave 校验之后):
from app.services.oa_trip_days import apply_trip_kit_days, validate_trip_kit_form_values
data = apply_trip_kit_days(schema, data)
trip_errs = validate_trip_kit_form_values(schema, data)
if trip_errs:
raise OaEngineError(trip_errs[0])
- Step 5: pytest PASS + commit
cd backend && PYTHONPATH=. python -m pytest tests/test_oa_trip_days.py -v
git add backend/app/services/oa_trip_days.py backend/tests/test_oa_trip_days.py \
backend/app/services/oa_publish.py backend/app/services/oa_engine.py
git commit -m "feat(oa): add trip kit day calc and submit validation"
Task 3: tripItinerary FormCreate control
Files:
-
Create:
web-admin/src/components/oa-approval/OaTripItinerary.vue -
Create:
web-admin/src/utils/oa-trip-itinerary-rule.ts -
Create:
web-admin/src/utils/oa-form-create-trip-itinerary.ts -
Modify:
web-admin/src/main.ts(先注册 itinerary,再注册 kit) -
Modify:
web-admin/src/oa-fc-host/main.ts -
Step 1: DragRule(可不进组件菜单,仅登记 type;
menu可省略或menu: 'aide'不展示——推荐不addDragRule到可见菜单,仅component注册;套件 children 引用 type)
oa-form-create-trip-itinerary.ts:
import FcDesigner from '@form-create/designer'
import OaTripItinerary from '@/components/oa-approval/OaTripItinerary.vue'
const FLAG = '__oaTripItineraryConfigured'
export function setupOaTripItinerary(formCreate?: { component?: (name: string, c: unknown) => void }) {
if ((FcDesigner as any)[FLAG]) return
FcDesigner.component('tripItinerary', OaTripItinerary)
if (typeof formCreate?.component === 'function') {
formCreate.component('tripItinerary', OaTripItinerary)
}
;(FcDesigner as any)[FLAG] = true
}
- Step 2: Implement
OaTripItinerary.vue
行为:
modelValue: TripLeg[];空或非数组时初始化为[emptyTripLeg()]- 每条卡片字段:交通 select、单程往返 select、出发/目的 input、开始 date+half、结束 date+half、时长 inputNumber(step 0.5)
- options 来自
props.transportOptions/props.tripTypeOptions(缺省用设计默认四项/两项) - 上下午固定:
上午/下午 - 未
durationManual时,watch 起止变化 →calcTripLegDays写回duration - 用户改时长 →
durationManual = true;旁提供文字按钮「恢复自动计算」清标记并重算 - 「新增行程」push
emptyTripLeg();「删除」在length > 1时 splice - 设计器预览:同样可渲染(FormCreate 设计器内编辑 value 可不持久,有 slot/attrs 即可)
组件骨架:
<template>
<div class="oa-trip-itinerary">
<div v-for="(leg, idx) in inner" :key="idx" class="oa-trip-leg">
<div class="oa-trip-leg__head">
<span>行程 {{ idx + 1 }}</span>
<el-button link type="danger" :disabled="inner.length <= 1" @click="remove(idx)">删除</el-button>
</div>
<!-- el-select / el-input / el-date-picker / el-input-number 绑定 leg 字段 -->
<!-- 时长旁:恢复自动计算 -->
</div>
<el-button @click="add">新增行程</el-button>
</div>
</template>
样式:Fresh Mint;卡片圆角与间距对齐现有 OA 表单(参考 oa-fc-runtime.scss 间距,避免另起色板)。
- Step 3: Register in both mains
import { setupOaTripItinerary } from '@/utils/oa-form-create-trip-itinerary'
setupOaTripItinerary(FcDesigner.formCreate)
- Step 4: Commit
git add web-admin/src/components/oa-approval/OaTripItinerary.vue \
web-admin/src/utils/oa-form-create-trip-itinerary.ts \
web-admin/src/utils/oa-trip-itinerary-rule.ts \
web-admin/src/main.ts web-admin/src/oa-fc-host/main.ts
git commit -m "feat(oa): add tripItinerary FormCreate control"
(若无需单独 rule 文件,可省略 oa-trip-itinerary-rule.ts,本 Task 以 component 注册为准。)
Task 4: tripKit container + designer registration
Files:
-
Create:
web-admin/src/components/oa-approval/OaTripKit.vue -
Create:
web-admin/src/utils/oa-trip-kit-rule.ts -
Create:
web-admin/src/utils/oa-form-create-trip-kit.ts -
Create:
web-admin/src/utils/oa-trip-kit-runtime.ts -
Modify:
web-admin/src/main.ts/oa-fc-host/main.ts -
Modify:
web-admin/src/oa-fc-host/App.vue(refresh 排除名加tripKit) -
Modify:
web-admin/src/utils/oa-approval-print.ts -
Step 1:
OaTripKit.vue— 对齐OaOvertimeKit.vue(仅 slot 容器) -
Step 2:
oa-trip-kit-rule.ts
默认 options 常量:
export const DEFAULT_TRANSPORT_OPTIONS = [
{ label: '飞机', value: '飞机' },
{ label: '火车', value: '火车' },
{ label: '汽车', value: '汽车' },
{ label: '其他', value: '其他' }
]
export const DEFAULT_TRIP_TYPE_OPTIONS = [
{ label: '单程', value: '单程' },
{ label: '往返', value: '往返' }
]
buildTripKitChildren() 生成 field ids,children 顺序:
- textarea 事由(
type: 'input', props: { type: 'textarea', rows: 3, _fc_kit_field: 'tripReason' };若项目用textareatype 则改用现网等价) tripItinerary行程(props 带 transport/tripType options +_fc_kit_field: 'tripList')inputNumber出差天数(step 0.5, precision 1,_fc_kit_field: 'tripDays')- textarea 备注
personmultiple 同行人input外部人员
容器 props 挂 tripReasonField 等六个 id。
DragRule:
export const tripKitDragRule = {
menu: 'kit' as const,
icon: 'icon-date',
label: '出差',
name: 'tripKit',
input: false,
drag: true,
dragBtn: true,
mask: false,
inside: true,
rule() { /* return type tripKit + props + children */ },
props() { return [] }
}
-
Step 3:
setupOaTripKit— 同 overtime:addMenu('kit')+ component +addDragRule -
Step 4:
oa-trip-kit-runtime.ts
export type TripKitRef = {
listField: string
daysField: string
}
export function listTripKits(schema: unknown): TripKitRef[]
export function applyTripKitDaysToFormData(
schema: unknown,
formData: Record<string, unknown>
): { data: Record<string, unknown>; changed: boolean }
逻辑:对每个 kit,读 listField 数组;对非 manual 行重算 duration;若无 __manual_${daysField} 则写 sum。
-
Step 5: App.vue — 在 kit refresh 过滤条件中加入
name !== 'tripKit'(与 leave/overtime/resignation 并列) -
Step 6: Print —
LAYOUT_UNWRAP(或现有 kit 列表)加入'tripKit';行程数组打印时格式化为多行文本(交通/城市/日期时段/时长) -
Step 7: Commit
git commit -m "feat(oa): register tripKit in FormCreate designer"
Task 5: Start page runtime linkage
Files:
-
Modify:
web-admin/src/views/oa-approval/start/index.vue -
Step 1: Import
listTripKits/applyTripKitDaysToFormData -
Step 2: Watch formData(可与 leave 并列独立 syncing 标志)
伪逻辑:
let tripKitSyncing = false
let tripKitPrev: Record<string, unknown> = {}
function syncTripKitDurations() {
if (tripKitSyncing) return
const schema = /* current form rules */
const curr = { ...formData }
for (const kit of listTripKits(schema)) {
const prevDays = tripKitPrev[kit.daysField]
const daysChanged =
prevDays !== undefined && prevDays !== curr[kit.daysField]
if (daysChanged) {
curr['__manual_' + kit.daysField] = true
}
// 行程行内 durationManual 由 OaTripItinerary 维护
}
const { data, changed } = applyTripKitDaysToFormData(schema, curr)
tripKitPrev = { ...data }
if (!changed) return
tripKitSyncing = true
Object.assign(formData, data)
nextTick(() => { tripKitSyncing = false })
}
在 form-create onChange / 现有 leave sync 钩子旁调用 syncTripKitDurations。
- Step 3: 手工冒烟
- 设计器拖「出差」→ 发布
- 发起:填事由;改行程起止看时长与出差天数
- 手改天数后改行程天数不变;清
__manual_或提供恢复后汇总恢复 - 同日下午→上午提交应被后端拒绝
- Step 4: Commit
git commit -m "feat(oa): wire trip kit duration sync on approval start"
Task 6: Spec status + graphify
- 将设计文档状态改为 已实现
./scripts/update-graph.sh frontend与backend(或依赖 commit hook)- Commit docs
git commit -m "docs(oa): mark trip kit design as implemented"
Spec coverage
| Spec 项 | Task |
|---|---|
| tripKit 容器 + 三部分字段 | T4 |
| tripItinerary 多行程增删 ≥1 | T3 |
| 钉钉半日制 0.5 步进 | T1/T2 |
| 出差天数 Σ + 手改断开 | T1/T2/T5 |
| 交通工具含火车 | T4 defaults |
| 不回写业务表 | (无 sync 服务,默认满足) |
| 单行程 end>start 校验 | T2 validate |
| 不校验行程重叠 | (无代码,满足) |
| 发布白名单 | T2 |
| 打印 unwrap | T4 |
| 条件分支仅顶层 | T4(行程数组不注册条件) |
Placeholder / consistency self-check
- 手改:行
durationManual+ 天数__manual_<field>— 全任务统一。 - Type 名:
tripKit/tripItinerary— 与 publish / print / mains 一致。 - 算法:
endPoint > startPoint— 与 spec §4/§6 一致。 - 无 TBD/「类似 Task N」未展开项。
Execution handoff
Plan complete and saved to docs/superpowers/plans/2026-07-30-oa-trip-kit.md.
Two execution options:
- Subagent-Driven(推荐) — 每 Task 派生子代理,Task 间复审
- Inline Execution — 本会话按 executing-plans 连续执行并设检查点
Which approach?