人力服务 · 业务与证据

字段、计算与指标字典

现场只填事实，业务负责人配置规则，系统计算结果，审核人员作出决定。六类字段在这里明确区分。

事实

人或设备观察到的事件、数值、时间，不凭公式臆造。

引用

选择已存在的业务记录，保存编号。

规则

商业约定或班次标准，有来源和生效版本。

计算

由事实及规则计算，页面只读，服务端重算。

审批

授权人员作出的决定，保留人和时间。

系统

编号、版本、审计及保存状态，由服务端维护。

事实表、维度、计算列与度量

“事实表”是一种数据表，不等于某个输入框。出勤、绩效、验收是不同粒度的业务事实；人员、日期、岗位和班次可以作为分析维度。每条出勤的净分钟是计算列；某时期总工时、平均每单收入属于查询时计算的度量。聚合前必须明确粒度、筛选范围、单位和币种。

工时按人员的出勤记录求和；收入按订单的一份锁定结算求和。不能把订单与多条附件直接连接后再累计订单金额，否则会重复计算。

HR-F01 · 人员建档与核验

一名人员一条名册记录。返回表单说明

中文字段 / 接口键	来源	类型	必填、校验与口径	保存位置
人员编号 `personnelCode`	事实	文本	必填；公司内唯一，不用姓名代替关联编号。	`personnel_people.personnel_code`
法定姓名 `legalName`	事实	文本	必填；修改已核验姓名需要重新核验。	`personnel_people.legal_name`
显示姓名 `displayName`	事实	文本	必填；用于现场识别。	`personnel_people.display_name`
联系电话 `phone`	事实	电话	选填；只作联系信息。	`personnel_people.phone`
岗位 `roleName`	规则	文本	必填；派遣岗位必须与订单匹配。	`personnel_people.role_name`
技能 `skills`	事实	列表	选填；数组保存。	`personnel_people.skills_json`
身份核验结果 `identityStatus`	审批	枚举	待核验、已核验、未通过；审核人员操作。	`personnel_people.identity_status`
身份核验方式 `identityMethod`	事实	文本	核验时记录依据和方式。	`personnel_people.identity_method`
核验凭据参考 `identityReference`	事实	文本	仅保留脱敏末四位；不保存完整证件号。	`personnel_people.identity_reference_masked`
岗位资格核验 `qualificationStatus`	审批	枚举	派遣前须已核验。	`personnel_people.qualification_status`
可派遣情况 `availability`	规则	枚举	可派遣或不可派遣，另校验时间冲突。	`personnel_people.availability`
在册状态 `status`	规则	枚举	在册或归档；归档不抹去历史。	`personnel_people.status`
人员备注 `notes`	事实	长文本	选填，不放完整证件。	`personnel_people.notes`
人员记录编号 `id`	系统	编号	服务端生成，派遣引用此编号。	`personnel_people.id`
记录修订号 `version`	系统	整数	更新必须提交此前读取的版本。	`personnel_people.version`
核验人 `identityVerifiedBy`	系统	编号	服务端记录审核者。	`personnel_people.verified_by`
核验时间 `identityVerifiedAt`	系统	日期时间	服务端时间。	`personnel_people.verified_at`

HR-F02 · 班次标准

一种班次的一版标准。返回表单说明

中文字段 / 接口键	来源	类型	必填、校验与口径	保存位置
班次编号 `code`	规则	文本	必填；稳定且唯一。	`personnel_shifts.code`
班次名称 `name`	规则	文本	必填；例如三小时白班。	`personnel_shifts.name`
计划上工时间 `startTime`	规则	时间	必填；津巴布韦当地时间。	`personnel_shifts.start_time`
计划下工时间 `endTime`	规则	时间	必填；早于开始表示次日，相等无效。	`personnel_shifts.end_time`
计划休息区间 `breaks`	规则	区间列表	每项开始、结束；班次内且不重叠；不代表实际休息。	`personnel_shifts.breaks_json`
标准工作分钟 `standardMinutes`	计算	分钟	计划跨度减计划休息，由系统计算。	`personnel_shifts.standard_minutes`
班次说明 `notes`	规则	长文本	选填，记录约定。	`personnel_shifts.notes`
班次状态 `status`	规则	枚举	有效或归档；已引用记录保持快照。	`personnel_shifts.status`
班次记录编号 `id`	系统	编号	服务端生成。	`personnel_shifts.id`
班次修订号 `version`	系统	整数	版本化更新。	`personnel_shifts.version`

HR-F03 · 客户服务订单

一个客户、一天、一个班次及岗位的一项需求。返回表单说明

中文字段 / 接口键	来源	类型	必填、校验与口径	保存位置
客户名称 `clientName`	事实	文本	必填；当前客户按文本记录，尚未独立客户主档。	`personnel_orders.client_name`
合同编号 `contractRef`	引用	文本	必填；关联商务约定。	`personnel_orders.contract_ref`
服务地点 `site`	事实	文本	必填。	`personnel_orders.site`
服务日期 `serviceDate`	事实	日期	必填；班次开始所在日期。	`personnel_orders.service_date`
班次标准 `shiftTemplateId`	引用	选择	必填；选择有效班次，不手输班次名称。	`personnel_orders.shift_template_id`
需求人数 `requestedPeople`	规则	整数	必填且大于零；派遣人数必须一致。	`personnel_orders.requested_people`
需求岗位 `roleName`	规则	文本	必填；与名册岗位匹配。	`personnel_orders.role_name`
结算币种 `currency`	规则	文本	必填；不同币种不得相加。	`personnel_orders.currency`
客户每小时费率 `clientHourRate`	规则	金额	必填非负；录入元，存储最小货币单位。	`personnel_orders.client_hour_rate_minor`
人工每小时成本 `labourHourCost`	规则	金额	必填非负；与客户费率分开。	`personnel_orders.labour_hour_cost_minor`
订单预算 `budgetAmount`	规则	金额	必填非负；不自动等于结算金额。	`personnel_orders.budget_amount_minor`
需求备注 `notes`	事实	长文本	选填。	`personnel_orders.notes`
计划开始 `plannedStartAt`	计算	日期时间	服务日期与班次落为具体带时区的时间。	`personnel_orders.planned_start_at`
计划结束 `plannedEndAt`	计算	日期时间	支持次日。	`personnel_orders.planned_end_at`
每人标准分钟 `standardMinutes`	计算	分钟	创建时的班次标准快照。	`personnel_orders.standard_minutes`
班次来源版本 `shiftTemplateVersion`	系统	整数	保留创建时版本。	`personnel_orders.shift_template_version`
班次快照 `shiftSnapshot`	系统	对象	规则和计划休息快照；不随模板修改。	`personnel_orders.shift_snapshot_json`
计算规范版本 `ruleVersion`	系统	文本	新记录 hr-0.3.0；历史记录明确标记。	`personnel_orders.rule_version`
订单状态 `status`	系统	枚举	由业务操作推进，不手工随意改值。	`personnel_orders.status`
订单编号 `id`	系统	编号	所有履约记录引用它。	`personnel_orders.id`
订单修订号 `version`	系统	整数	每次操作带原版本防止覆盖。	`personnel_orders.version`

HR-F04 · 人员派遣与排班

一个订单下的一人一次排班。返回表单说明

中文字段 / 接口键	来源	类型	必填、校验与口径	保存位置
所选人员 `personId`	引用	多选	从合格名册选择；每人产生一条派遣记录。	`personnel_assignments.person_id`
所选订单 `orderId`	引用	编号	上下文选择，不是新增表单。	`personnel_assignments.order_id`
排班开始 `plannedStartAt`	计算	日期时间	继承订单具体计划；禁止同一人员排班重叠。	`personnel_assignments.planned_start_at`
排班结束 `plannedEndAt`	计算	日期时间	保留跨日的完整日期。	`personnel_assignments.planned_end_at`
标准分钟 `standardMinutes`	计算	分钟	此人此派遣的标准额度。	`personnel_assignments.standard_minutes`
排班依据 `schedule`	系统	对象	保留班次与来源信息。	`personnel_assignments.schedule_json`
人员编号快照 `personnelCode`	系统	文本	派遣时保留。	`personnel_assignments.personnel_code`
姓名快照 `displayName`	系统	文本	人员改名不改历史派遣。	`personnel_assignments.display_name`
岗位快照 `roleName`	系统	文本	派遣时岗位。	`personnel_assignments.role_name`
派遣状态 `status`	系统	枚举	已派遣、已替换等。	`personnel_assignments.status`
派遣编号 `id`	系统	编号	出勤、绩效关联键。	`personnel_assignments.id`

HR-F05 · 出勤与实际休息

一名派遣人员的一段工作区间或一条缺勤说明。返回表单说明

中文字段 / 接口键	来源	类型	必填、校验与口径	保存位置
派遣人员 `assignmentId`	引用	选择	必填；只能选当前订单有效派遣。	`personnel_timesheets.assignment_id`
出勤情况 `attendance`	事实	枚举	出勤或缺勤；缺勤不产生工时。	`personnel_timesheets.attendance`
实际上工 `startedAt`	事实	日期时间	出勤必填；津巴布韦时间输入，UTC 保存。	`personnel_timesheets.started_at`
实际下工 `endedAt`	事实	日期时间	出勤必填；完整日期，晚于上工。	`personnel_timesheets.ended_at`
实际休息区间 `breaks`	事实	区间列表	每项 startedAt、endedAt；工作区间内且不重叠。	`personnel_timesheets.breaks_json`
确认本段无休息 `noBreakConfirmed`	事实	确认	无休息区间时必须明确确认，缺失不能默认为零。	`personnel_timesheets.no_break_confirmed`
出勤说明 `replacementNote`	事实	长文本	异常、缺勤等说明。	`personnel_timesheets.replacement_note`
实际休息分钟 `breakMinutes`	计算	分钟	实际休息各区间时长之和；不可手填。	`personnel_timesheets.break_minutes`
实际净工作分钟 `effectiveMinutes`	计算	分钟	下工减上工减休息。	`personnel_timesheets.effective_minutes`
正常工作分钟 `regularMinutes`	计算	分钟	min(本段净工时,max(0,标准工时−此前净工时))。	`personnel_timesheets.regular_minutes`
超出标准分钟 `overtimeMinutes`	计算	分钟	本段净工时减本段正常工时；不是审核结果。	`personnel_timesheets.overtime_minutes`
加班审核状态 `overtimeStatus`	审批	枚举	有加班自动待审核；另由 HR-F07 决定。	`personnel_timesheets.overtime_status`
标准额度快照 `standardMinutes`	系统	分钟	引用排班标准，旧记录不补造。	`personnel_timesheets.standard_minutes`
计算规范 `ruleVersion`	系统	文本	记录使用的计算规则。	`personnel_timesheets.rule_version`
出勤记录编号 `id`	系统	编号	加班审核引用。	`personnel_timesheets.id`
出勤修订号 `version`	系统	整数	审核并发控制。	`personnel_timesheets.version`

HR-F06 · 绩效与服务结果

一名派遣人员的一次成果记录。返回表单说明

中文字段 / 接口键	来源	类型	必填、校验与口径	保存位置
派遣人员 `assignmentId`	引用	选择	当前订单有效派遣。	`personnel_performance.assignment_id`
完成数量 `quantity`	事实	数值	非负，必须连同单位解释。	`personnel_performance.quantity`
数量单位 `unit`	规则	文本	必填；不同单位不能直接相加。	`personnel_performance.unit`
质量评分 `qualityScore`	事实	数值	0–100；评价事实，不自动代表产量。	`personnel_performance.quality_score`
评价依据 `evidenceBasis`	事实	长文本	必填，可注明附件编号。	`personnel_performance.evidence_basis`
返工与异常 `reworkOrIncident`	事实	长文本	选填。	`personnel_performance.rework_or_incident`
绩效记录编号 `id`	系统	编号	服务端生成。	`personnel_performance.id`

HR-F07 · 加班审核

一条出勤中待审核加班的一次决定。返回表单说明

中文字段 / 接口键	来源	类型	必填、校验与口径	保存位置
出勤记录 `id`	引用	选择	所选出勤编号。	`personnel_timesheets.id`
加班决定 `status`	审批	枚举	批准或拒绝；本期整段审核，不提供部分批准。	`personnel_timesheets.overtime_status`
出勤版本 `timesheetVersion`	系统	整数	提交当前版本，冲突需重新读取。	`personnel_timesheets.version`
审核人 `overtimeDecidedBy`	系统	编号	从登录会话记录。	`personnel_timesheets.overtime_decided_by`
审核时间 `overtimeDecidedAt`	系统	日期时间	服务端时间。	`personnel_timesheets.overtime_decided_at`

HR-F08 · 客户验收

一份订单的一次客户验收意见。返回表单说明

中文字段 / 接口键	来源	类型	必填、校验与口径	保存位置
验收决定 `decision`	审批	枚举	接受、拒绝、争议、退回。	`personnel_acceptance.decision`
客户验收人 `reviewerName`	事实	文本	必填；系统另记录操作人。	`personnel_acceptance.reviewer_name`
验收说明 `reason`	事实	长文本	记录决定依据。	`personnel_acceptance.reason`
订单编号 `orderId`	引用	编号	与服务订单关联。	`personnel_acceptance.order_id`
验收记录编号 `id`	系统	编号	保留历次意见，不覆盖。	`personnel_acceptance.id`

HR-F09 · 结算核对与锁定

一份订单的一份锁定结算。返回表单说明

中文字段 / 接口键	来源	类型	必填、校验与口径	保存位置
服务订单 `orderId`	引用	选择	读取订单及其履约记录。	`personnel_settlements.order_id`
正常分钟合计 `regularMinutes`	计算	分钟	同一订单正常工时求和。	`personnel_settlements.regular_minutes`
批准加班分钟 `approvedOvertimeMinutes`	计算	分钟	只计已批准加班。	`personnel_settlements.approved_overtime_minutes`
本期结算分钟 `billableMinutes`	计算	分钟	正常分钟＋已批准加班。	`personnel_settlements.billable_minutes`
结算币种 `currency`	系统	文本	订单币种快照。	`personnel_settlements.currency`
客户服务收入 `revenueMinor`	计算	最小货币单位	结算分钟×客户时费率÷60，按货币最小单位四舍五入。	`personnel_settlements.revenue_minor`
直接人工成本 `directLabourCostMinor`	计算	最小货币单位	本期采用相同结算分钟×人工时费率÷60。	`personnel_settlements.direct_labour_cost_minor`
收入减直接人工 `grossDifferenceMinor`	计算	最小货币单位	不含其他费用，不称净利润。	`personnel_settlements.gross_difference_minor`
结算依据快照 `snapshot`	系统	对象	保存来源与结果，锁定后不随上游变动。	`personnel_settlements.snapshot_json`
锁定结果 `locked`	系统	确认	通过服务端验收条件后置为锁定。	`personnel_settlements.locked`
结算编号 `id`	系统	编号	唯一关联订单。	`personnel_settlements.id`
结算版本 `version`	系统	整数	保留锁定版本。	`personnel_settlements.version`

HR-F10 · 照片、视频与证据

一个订单阶段的一份附件。返回表单说明

中文字段 / 接口键	来源	类型	必填、校验与口径	保存位置
关联订单 `orderId`	引用	编号	当前订单。	`personnel_media.order_id`
采集环节 `stage`	事实	选择	派遣、到场、出勤、绩效、验收。	`personnel_media.stage`
附件用途 `purpose`	事实	文本	必填，例如到场确认。	`personnel_media.purpose`
现场说明 `description`	事实	长文本	必填；模拟材料必须标明模拟。	`personnel_media.description`
拍摄时间 `capturedAt`	事实	日期时间	可选；不能拿上传时间冒充拍摄时间。	`personnel_media.captured_at`
文件名 `originalName`	事实	文件	浏览器读取文件名称。	`personnel_media.original_name`
文件类型 `contentType`	系统	文本	图像或视频白名单；服务端校验。	`personnel_media.content_type`
申报文件大小 `sizeBytes`	系统	字节	浏览器读取；当前每份不超过 25 MiB。	`personnel_media.size_bytes`
视频时长 `durationSeconds`	系统	秒	浏览器读取视频元数据；服务端验证数值，不宣称已做云端转码校验。	`personnel_media.duration_seconds`
实收字节 `byteCount`	系统	字节	服务端从真实文件计算。	`personnel_media.byte_count`
内容校验值 `contentHash`	系统	文本	服务端计算，用于一致性。	`personnel_media.content_hash`
上传状态 `status`	系统	枚举	待上传、已上传、失败、已删除。	`personnel_media.status`
失败原因 `failureReason`	系统	文本	运营排障用。	`personnel_media.failure_reason`
对象存储位置 `objectKey`	系统	私有文本	服务端私有，不向页面暴露；按附件编号授权访问。	`personnel_media.object_key`
附件编号 `id`	系统	编号	业务关联标识。	`personnel_media.id`
附件修订号 `version`	系统	整数	删除或变更使用版本校验。	`personnel_media.version`

HR-F11 · 派遣替换

一名原派遣与一名替代人员的关系。返回表单说明

中文字段 / 接口键	来源	类型	必填、校验与口径	保存位置
原派遣人员 `originalAssignmentId`	引用	选择	选当前有效派遣；有出勤时禁止直接替换。	`personnel_assignments.replaced_assignment_id`
替代人员 `personId`	引用	选择	需合格、可用且无排班冲突。	`personnel_assignments.person_id`
替换原因 `reason`	事实	长文本	必填；原记录保留。	`personnel_assignments.replacement_reason`
新派遣编号 `id`	系统	编号	服务端生成。	`personnel_assignments.id`

所有变更共有的控制字段

expectedVersion：变更已有记录必须附带此前读取的记录版本；冲突后重新读取，不覆盖。

Idempotency-Key：每次新提交使用独立请求编号；网络重试沿用原编号，防止重复建单。

created_at / updated_at / created_by：服务端审计事实；不是现场自行输入。

下载完整表单登记册 JSON · 服务接口契约