数据与媒体架构
私有 D1/R2 资源已开通，包含 preview 与 pilot 环境。当前资料描述已部署的目标架构；真实网页上传、读取、删除和正式云端闭环仍待验收。
公开字段契约：personnel-service-contract.json。时间以 UTC ISO 8601 保存；业务页面应按 Africa/Harare 展示完整日期，跨日不可截断。金额由 API 转为最小货币单位存储，服务端统一按两位小数输出。
订单、派遣与工时字段
| 网页/API 字段 | SQL 列 | 用途与约束 |
|---|---|---|
| clientName、contractRef、site、serviceDate、shiftName、requestedPeople、roleName、currency、notes | personnel_orders.client_name、contract_ref、site、service_date、shift_name、requested_people、role_name、currency、notes | 客户服务订单；status/version/created_by/时间戳由服务端维护。 |
| clientHourRate、labourHourCost、budgetAmount | personnel_orders.client_hour_rate_minor、labour_hour_cost_minor、budget_amount_minor | 网页输入金额，服务端换算最小货币单位；不能把毛利差额称作净利润。 |
| personnelCode、displayName、roleName、qualificationStatus | personnel_assignments.personnel_code、display_name、role_name、qualification_status | 派遣只需代号和必要资格；不收集政府身份证件。替换关系由 replaced_assignment_id、replacement_reason、status 记录。 |
| assignmentId、startedAt、endedAt、breakMinutes、attendance、overtimeMinutes、overtimeStatus、replacementNote | personnel_timesheets.assignment_id、started_at、ended_at、break_minutes、attendance、overtime_minutes、overtime_status、replacement_note | actual effective/regular minutes 与提交/审批人由服务端计算和审计；一线只能申请加班，审核人才能决定 pending。 |
绩效、验收、结算与审计
| 网页/API 字段 | SQL 列 | 说明 |
|---|---|---|
| assignmentId、quantity、unit、qualityScore、reworkOrIncident、evidenceBasis | personnel_performance.assignment_id、quantity、unit、quality_score、rework_or_incident、evidence_basis | 质量分数为 0–100；事件要有依据。 |
| decision、reason、reviewerName | personnel_acceptance.decision、reason、reviewer_name | 验收由 reviewer/admin 角色提交，决定会推进订单状态。 |
| 收入、直接人工成本、毛利差额（服务端输出） | personnel_settlements.revenue_minor、direct_labour_cost_minor、gross_difference_minor | 快照还保存 currency、regular_minutes、approved_overtime_minutes、billable_minutes、snapshot_json。仅已批准加班进入结算。 |
| 操作者、动作、前后 JSON、时间 | personnel_audit.actor_id、action、before_json、after_json、created_at | 浏览器只显示 API 返回的审计项，不能改写。 |
私有 R2 媒体流程与元数据
浏览器先 POST /personnel/media/init 建立 metadata，再 PUT 原始二进制到同一媒体 ID；失败重试复用该 ID，读取和删除只经授权 API。R2 object_key 永不返回网页。当前试用单件上限为 25 MiB（PERSONNEL_MEDIA_MAX_BYTES），可由部署环境调整；服务端核验文件的字节、类型和大小；视频时长由浏览器读取并记录。当前没有云转码或内容审核。
| 网页/API 字段 | SQL 列 | 状态 |
|---|---|---|
| orderId、stage、purpose、originalName、contentType、sizeBytes、durationSeconds | personnel_media.order_id、stage、purpose、original_name、content_type、size_bytes、duration_seconds | 阶段可以为派遣、到场、工时、绩效或验收；同一阶段可有任意数量的图片和视频。 |
| description、capturedAt、上传结果 | personnel_media.description、captured_at、status、failure_reason、byte_count、content_hash | pending → uploaded/linked；失败带原因且可重试；deleted 由授权删除操作产生。 |