外观
7. 成本与分析
7.0 快速上手：5 分钟从查看总成本到导出部门报表
作为运维主管，你想了解上个月各部门的维护成本分布，并导出报表用于月度会议。
Step 1：打开成本分析
点击左侧菜单「成本与分析」→「成本分析」，页面展示 6 张成本总览卡片 + 趋势图 + 类型分布图。 → 详见 §7.3.1
Step 2：设置时间范围
点击日期范围选择器，选择上月 1 日至月末。卡片数据自动刷新。 → 详见 §7.3.2
Step 3：切换到部门别视图
在明细表上方点击「部门别」单选按钮 → 表格切换为按部门汇总的成本数据。 → 详见 §7.3.5
Step 4：导出 Excel
点击右上角「导出」按钮 → 系统生成包含成本总览、明细列表、趋势数据的 Excel 文件并自动下载。 → 详见 §7.3.6
💡 完成以上步骤后，你已通过「成本分析 → 日期筛选 → 部门别视图 → 导出」的路径，从总览指标到明细报表完整走通。
7.1 功能概述
本章介绍「成本与分析」模块的四个核心功能：
| 模块 | 定位 | 核心功能 |
|---|---|---|
| 成本分析 | 维护成本全景看板 | 成本总览卡片、趋势图表、费用类型分布、设备别/部门别/费用类型明细表、Excel 导出 |
| 据点对比看板 | 跨租户 KPI 对比 | 多据点维护成本、工单完成率、MTTR 横向对比 |
| 设备保全费排名 | 设备维护成本排行 | 按总成本降序排列设备、成本占比可视化 |
| 工时费率档案 | 人工成本计价基础 | 工时费率 CRUD、默认费率、启用/停用 |
此外，工单详情弹窗中的「费用管理」入口允许在工单级录入和查看费用明细（详见本章 §7.6）。
7.2 页面入口
- PC端：左侧菜单「成本与分析」→「成本分析」「据点对比看板」「设备保全费排名」（需要对应权限）
- 工时费率档案：左侧菜单「档案管理」→「工时费率档案」（需要
cost:manage权限） - 工单费用：工单详情弹窗中点击「费用」按钮打开独立费用管理弹窗（查看需要
workorder:view权限；编辑需要cost:item_edit+workorder:update权限）
7.3 PC端 - 成本分析
7.3.1 页面布局
成本分析页面从上到下分为四个区域：
- 筛选工具栏 — 日期范围选择器 + 部门下拉 + 查询/刷新/导出按钮
- 成本总览卡片 — 6 张统计卡片
- 图表区域 — 成本趋势图（左宽）+ 费用类型分布饼图（右窄）
- 明细表 — 支持设备别/部门别/费用类型三种视图切换 + 分页
7.3.2 筛选工具栏
| 控件 | 说明 |
|---|---|
| 日期范围选择器 | 选择统计起止日期，支持快捷选择月份 |
| 部门下拉 | 按部门筛选（允许清空查看全部） |
| 查询按钮 | 应用筛选条件，重新加载所有数据（与「刷新」按钮行为相同） |
| 刷新按钮 | 使用当前条件重新加载数据（与「查询」按钮行为相同） |
| 导出按钮 | 导出当前视图的 Excel 报表（需要 cost:export 权限） |
💡 后台 API 还支持
location_id（位置）、equipment_type_id（设备类型）两个筛选项，当前前端页面仅开放部门筛选。成本趋势接口仅支持部门筛选，不支持位置和设备类型筛选。
7.3.3 成本总览卡片
页面顶部一行 6 张卡片，展示当前筛选条件下的成本汇总：
| 卡片 | 说明 | 格式 |
|---|---|---|
| 材料成本 | 所有工单消耗备件的总成本 | ¥ 精度两位 |
| 人工成本 | 所有工单人工费用的总成本 | ¥ 精度两位 |
| 外包成本 | 所有工单外包费用的总成本 | ¥ 精度两位 |
| 其他成本 | 交通、工具等杂项费用总和 | ¥ 精度两位 |
| 总成本 | 以上四项合计（紫色高亮） | ¥ 精度两位 |
| 外包工单占比 | 标记为外包的工单数 / 总工单数（基于工单 is_outsourced 字段判定，非费用明细中是否存在外包费用） | 百分比 + 分子/分母 |
💡 系统还返回「总工时（total_hours）」指标，用于 Excel 导出和月度快照。
7.3.4 图表区域
成本趋势图
左宽区域展示堆叠柱状图 + 折线图：
- 柱状图（堆叠）：材料（蓝）、人工（绿）、外包（橙）、其他（红）四类费用按月堆叠
- 折线图：总成本趋势线（紫色）
- 鼠标悬停显示当月各费用类型明细
费用类型分布饼图
右窄区域展示环形饼图：
- 按费用类型（材料/人工/外包/其他）汇总金额占比
- 扇区标签显示类型名称 + 金额
- 鼠标悬停显示金额和百分比
7.3.5 明细表
明细表上方有三个视图切换按钮：
| 视图 | 表格列 | 说明 |
|---|---|---|
| 设备别 | 设备编号、设备名称、材料、人工、外包、其他、总成本、工单数、外包工单数、外包工单占比、总工时 | 按设备汇总维护成本 |
| 部门别 | 部门编号、部门名称、材料、人工、外包、其他、总成本、工单数、外包工单数、外包工单占比、总工时 | 按部门汇总维护成本 |
| 费用类型 | 费用类型、金额、工单数 | 按费用类型汇总 |
表格支持分页，切换视图时自动重置到第 1 页。
7.3.6 Excel 导出
点击「导出」按钮后，系统生成包含两张工作表的 Excel 文件：
| 工作表 | 内容 |
|---|---|
| Sheet 1 — 成本总览 | 标题行、导出时间、筛选条件、汇总指标（材料/人工/外包/其他/总成本/工单数/外包工单数/外包工单占比/总工时，共 9 列）、成本趋势数据（按月 + 费用类型分解）+ 堆叠柱状图 + 折线图、费用类型分布数据 + 饼图 |
| Sheet 2 — 明细列表 | 当前视图的明细数据（设备别/部门别 11 列：ID+名称+4项成本+总成本+工单数+外包工单数+占比+总工时；费用类型 3 列）+ 汇总行 |
导出文件自动以 cost_analysis_YYYYMMDD_HHMMSS.xlsx 命名（日期无连字符，精确到秒）。下载时浏览器文件名优先使用服务端 Content-Disposition 头返回的 i18n 文件名。
7.4 PC端 - 据点对比看板
权限要求：
site_comparison:view
7.4.1 页面布局
据点对比看板页面用于跨租户（多据点）的 KPI 横向对比，从上到下分为：
- 筛选工具栏 — 日期范围选择器 + 刷新按钮
- 据点 KPI 汇总表 — 多维度数据对比表格
- 对比图表 — 成本对比 + 完成率对比（并排）
7.4.2 据点 KPI 汇总表
表格列按据点展示关键指标：
| 列 | 说明 | 排序 |
|---|---|---|
| 据点名称 | 各租户据点名称 | — |
| 设备数 | 据点设备总量 | ✓ |
| 工单总数 | 筛选期间工单数 | ✓ |
| 已完成 | 已完成工单数 | — |
| 完成率 | 已完成 / 总数（精度 1 位小数） | ✓ |
| 总维护成本 | 材料 + 人工 + 外包 + 其他四项合计（前端列标题显示为"总费用"） | ✓ |
| 材料费 | 材料成本 | — |
| 人工费 | 人工成本 | — |
| 外包费 | 外包成本 | — |
| MTTR(h) | 平均修复时间：已完成且工时 >0 工单的 actual_hours 平均值（精度 1 位小数） | ✓ |
⚠️ 前后端差异：后端 API 返回了
other_cost（其他成本）字段，但当前前端表格未定义该列，也未列入kpi_keys，因此"其他成本"数据不会在据点对比看板中展示。
💡 后端还计算
equipment_running（运行中设备数）和equipment_fault（故障设备数），当前前端表格未展示。
7.4.3 对比图表
| 图表 | 类型 | 说明 |
|---|---|---|
| 据点维护成本对比 | 堆叠柱状图 | 各据点材料/人工/外包成本堆叠对比 |
| 工单完成率对比 | 柱状图 | 各据点的工单完成率（≥80%绿色，≥50%黄色，<50%红色） |
7.5 PC端 - 设备保全费排名
权限要求：
equipment_cost_ranking:view
7.5.1 页面布局
设备保全费排名页面按维护成本降序展示设备排名，从上到下分为：
- 筛选工具栏 — 日期范围选择器 + 显示前 N 名 + 刷新按钮
- 汇总卡片 — 总维护成本 + 上榜设备数
- 排名图表 — 水平条形图（排名从上到下）
- 排名明细表 — 按总成本降序排列
7.5.2 汇总卡片
| 卡片 | 说明 |
|---|---|
| 总计 | 所有上榜设备的总维护成本 |
| 设备数 | 当前排名的设备数量 |
7.5.3 排名图表
水平条形图，设备名称在 Y 轴、金额在 X 轴：
- 排名从上到下（第一名在最上方）
- 每根柱子右侧显示金额标签
- 悬停提示展示设备名 + 总费用
7.5.4 排名明细表
| 列 | 说明 | 排序 |
|---|---|---|
| # | 排名序号 | — |
| 设备编号 | 设备唯一编码（equipment_id） | — |
| 设备名称 | 设备名称 | — |
| 设备类型 | 设备类型分类 | — |
| 状态 | 设备当前状态 | — |
| 工单数 | 维护工单数量 | ✓ |
| 总成本 | 材料 + 人工 + 外包 + 其他 | ✓（默认降序） |
| 材料 | 材料成本 | — |
| 人工 | 人工成本 | — |
| 外包 | 外包成本 | — |
| 其他 | 其他成本 | — |
| 平均工时 | 所有匹配工单的平均 actual_hours（精度 1 位小数）。注：SQL AVG 自动忽略 NULL 值，但不限于已完成状态的工单 | — |
| 占比 | 该设备占全部上榜设备总成本的百分比（精度 1 位小数，进度条展示） | ✓ |
7.6 PC端 - 工单费用管理
权限要求：查看费用需要
workorder:view；编辑费用需要cost:item_edit+workorder:update
7.6.1 入口
在工单详情弹窗中，点击「费用」按钮打开独立的费用管理弹窗。
7.6.2 费用录入表单
费用录入表单支持三种费用类型的录入：
| 字段 | 说明 |
|---|---|
| 类型 | 人工 / 外包 / 其他（下拉选择） |
| 说明 | 费用描述文本 |
| 费率 | 仅「人工」类型显示，下拉选择已配置的工时费率（自动带入单价） |
| 外包商 | 仅「外包」类型显示，下拉选择供应商档案 |
| 日期 | 费用发生日期（日期选择器） |
| 数量/工时 | 「人工」类型显示为「工时」，其他为「数量」 |
| 单价 | 单价（¥ 精度两位），选择费率后自动填充 |
| 金额 | 自动计算 = 数量 × 单价（只读，灰色背景） |
| 发票号 | 可选，录入发票或收据编号 |
7.6.3 费用列表
表单下方展示当前工单已录入的费用明细：
- 筛选：全部 / 人工 / 外包 / 其他 按钮切换
- 列：类型（彩色标签）、说明、数量/工时、单价、金额（加粗）、日期、操作（编辑/删除）
- 行操作：编辑（回填表单）、删除（二次确认后软删除，保留审计记录）
7.6.4 费用编辑约束
后端白名单允许以下 9 种工单状态下编辑费用：
| 工单状态 | 状态码 | 允许操作 |
|---|---|---|
| 待处理（PENDING） | pending | 新增、编辑、删除全部允许 |
| 待审批（PENDING_APPROVAL） | pending_approval | 新增、编辑、删除全部允许 |
| 已指派（ASSIGNED） | assigned | 新增、编辑、删除全部允许 |
| 进行中（IN_PROGRESS） | in_progress | 新增、编辑、删除全部允许 |
| 已挂起（ON_HOLD） | on_hold | 新增、编辑、删除全部允许 |
| 已派发（DISPATCHED） | dispatched | 新增、编辑、删除全部允许 |
| 已完成（COMPLETED） | completed | 新增、编辑、删除全部允许（典型场景：补录外包发票） |
| 已评价（RATED） | rated | 新增、编辑、删除全部允许 |
| 待复核（REVIEW） | review | 新增、编辑、删除全部允许 |
💡 后端对 9 种状态使用统一的
is_cost_editable()判断函数，不区分操作类型。所有白名单内的状态均可执行完整 CRUD 操作。
⚠️ 前后端差异：前端以
status !== 'cancelled'作为可编辑判断条件，比后端白名单更宽松。对于不在白名单内但非"已取消"的状态（如 REJECTED、ARCHIVED），前端可能显示编辑按钮，但后端会返回 400 错误拒绝操作。
7.6.5 成本口径
系统遵循「单一事实来源」原则：
| 成本类型 | 数据来源 |
|---|---|
| 材料成本 | WorkOrderMaterialUsage 表中备件消耗汇总 |
| 人工成本 | 费用明细中 cost_type='labor' 汇总 |
| 外包成本 | 费用明细中 cost_type='outsource' 汇总 |
| 其他成本 | 费用明细中 cost_type='other' 汇总 |
| 总成本 | 以上四类合计 |
⚠️ 人工成本不直接从工单的
actual_hours字段计算，而是通过费用明细统一管理。系统在工单完成时会自动检测：若工单actual_hours > 0且不存在人工费用明细，则自动生成一条人工费用明细（标记is_auto_generated=True）——有默认费率时按费率计价；未配置默认费率时也会生成（单价/金额计 0，说明标注「金额待补价」），可后续在费用明细中编辑单价补价（已完工工单的费用仍可编辑）。如需手动基于工时生成人工费用，请在费用明细中录入「人工」类型并选择工时费率。
💡 工单
actual_cost字段与total_cost保持同步更新，两者数值始终一致。
7.7 PC端 - 工时费率档案
权限要求：
cost:manage
7.7.1 页面入口
左侧菜单「档案管理」→「工时费率档案」。
7.7.2 费率列表
| 列 | 说明 |
|---|---|
| 费率名称 | 如「高级技师」「电气工程师」 |
| 小时单价 | ¥ 精度两位 |
| 生效日期 | 费率生效起始日期 |
| 失效日期 | 费率失效日期（为空表示持续有效） |
| 状态 | 启用 / 停用 |
| 默认 | 是否为默认费率（新建人工费用时自动选择） |
| 更新时间 | 记录最后一次修改时间 |
| 操作 | 编辑 / 设为默认 / 停用 |
支持「显示非活跃」开关切换是否展示已停用的费率。
7.7.3 新增/编辑费率
弹窗表单包含以下字段：
| 字段 | 说明 | 必填 |
|---|---|---|
| 名称 | 费率名称 | ✓ |
| 小时单价 | ¥ 精度两位 | ✓ |
| 生效日期 | 日期选择器 | ✓ |
| 失效日期 | 日期选择器（可选，留空表示持续有效） | — |
| 状态 | 开关，控制费率是否启用（启用/停用） | — |
| 默认费率 | 开关，设为默认后新建费用时自动选用，且工单完成时若无人费用则自动生成（全局仅一个可设为默认） | — |
7.7.4 月度快照
权限要求：
cost:manage
月度快照用于按期间固化成本数据，便于历史对比和审计追溯。
- 触发方式：需由管理员在后台调用
POST /api/v1/cost/snapshot接口，传入year_month（格式YYYY-MM）和维度类型（默认equipment+department） - 数据内容：按设备/部门/位置/设备类型等维度，汇总当月材料成本、人工成本、外包成本、其他成本、总成本、工单数、总工时
- 存储表：
monthly_cost_snapshots，支持按year_month+dimension_type查询历史快照 - 前端入口：当前版本无前端页面入口，需通过 API 工具或系统维护操作触发
7.8 相关权限
成本与分析模块涉及的权限列表：
| 权限 | 中文名称 | 说明 |
|---|---|---|
cost:view | 查看成本 | 左侧菜单「成本与分析」→「成本分析」可见性；仪表盘维护成本趋势图表 |
cost:manage | 管理成本 | 工时费率档案增改停用；月度快照生成 |
cost:export | 导出成本 | 成本分析页面「导出」按钮可见性 |
cost:item_edit | 编辑费用明细 | 工单费用明细的新增/编辑/删除按钮可见性 |
site_comparison:view | 据点对比看板 | 左侧菜单「成本与分析」→「据点对比看板」可见性 |
equipment_cost_ranking:view | 设备保全费排名 | 左侧菜单「成本与分析」→「设备保全费排名」可见性 |
角色默认权限分配（基于 permissions.py 静态角色定义）：
| 角色 | 成本与分析相关权限 |
|---|---|
| 超级管理员 | 全部权限 |
| 租户管理员 | 据点对比看板、设备保全费排名 |
| 设备主管 | 据点对比看板、设备保全费排名 |
| 技术员 | — |
| 操作员 | — |
| 仓库管理员 | 成本分析四项（查看/管理/导出/编辑费用明细），不含据点对比看板和设备保全费排名 |
| 只读用户 | 据点对比看板、设备保全费排名 |
⚠️ 租户管理员权限缺口：当前静态角色定义中
tenant_admin未包含cost:view、cost:manage、cost:export、cost:item_edit四项权限，导致新部署环境下租户管理员无法访问成本分析页面。已部署环境通过迁移脚本sync_cost_permissions_to_master.py动态补齐（该脚本为super_admin、tenant_admin、equipment_manager三个角色赋予全部成本权限）。建议在静态定义中补全。
⚠️ 仓库管理员编辑费用受限：仓库管理员拥有
cost:item_edit权限，但缺少workorder:update权限。由于费用编辑 API 同时要求这两项权限（require_all=True），仓库管理员在前端可以看到编辑按钮，但实际调用 API 时会收到 403 错误。如需仓库管理员可编辑费用，需额外为其分配workorder:update权限。
7.9 常见问题
Q: 为什么成本分析页面的材料成本是 0？ A: 材料成本来源于工单的备件消耗记录（WorkOrderMaterialUsage）。如果工单没有消耗备件，或者消耗备件没有录入出库，材料成本即为 0。
Q: 新增人工费用时为什么没有费率可选？ A: 需要先在「档案管理」→「工时费率档案」中创建至少一条启用状态的费率。创建后回到工单费用弹窗即可选择。
Q: 费用明细删除后能恢复吗？ A: 系统采用软删除，数据保留在数据库中但前端不再展示。如需恢复，请联系管理员在后台操作。
Q: 据点对比看板没有数据？ A: 据点对比看板依赖多租户架构。如果您使用的是单租户部署，则只有一条据点数据。确认已在「系统管理」→「租户管理」中配置了多个活跃租户。
Q: 导出的 Excel 打不开？ A: 导出为 .xlsx 格式，需要 Excel 2007 或以上版本，或使用 WPS、LibreOffice 等兼容软件打开。
Q: 工单状态为"已驳回"时点击费用编辑按钮报错？ A: 前端以"非已取消"作为可编辑条件，但后端仅允许 9 种指定状态下编辑费用（详见 §7.6.4）。对于"已驳回（REJECTED）"等不在白名单中的状态，后端会拒绝操作。