API 参考已发布

RAILWISE-OS 报告模板开发指南

RAILWISE-OS 报告模板引擎的开发规范，包含模板语法、变量系统、图表配置与自定义扩展

复核 2026-07-09入门公开可引用RailWise 技术团队

API 参考

RAILWISE-OS 报告模板开发指南

AI语义标签: #报告模板 #模板引擎 #自动化报告 #Jinja2 #Python #开发者指南

1. 概述

RAILWISE-OS 报告引擎基于 Python + Jinja2 模板系统，支持动态数据绑定、自动图表生成、智能排版与多格式导出。开发者可通过自定义模板实现监测报告的自动化生成。

1.1 模板引擎架构

┌─────────────────────────────────────────────────────────────┐
│                    报告生成流程                               │
├─────────────────────────────────────────────────────────────┤
│  1. 模板加载 → 2. 数据获取 → 3. 渲染引擎 → 4. 格式输出       │
├─────────────────────────────────────────────────────────────┤
│  模板文件 (.j2)    数据库/API      Jinja2 +     Word/PDF/   │
│  + 样式配置 (.yaml)  + 缓存层      图表生成      HTML        │
└─────────────────────────────────────────────────────────────┘

1.2 模板类型

模板类型	扩展名	适用场景	复杂度
日报模板	`.j2`	每日监测快报	低
周报模板	`.j2`	周监测汇总	中
月报模板	`.j2`	月度监测分析	中
专项报告	`.j2`	特定事件/阶段报告	高
自定义模板	`.j2`	用户自定义格式	可变

2. 模板基础语法

2.1 文件结构

一个完整的报告模板包含：

template/
├── template.j2          # 主模板文件（Jinja2 语法）
├── config.yaml          # 模板配置（数据源、图表、样式）
├── styles/
│   ├── heading.yaml     # 标题样式
│   ├── table.yaml       # 表格样式
│   └── chart.yaml       # 图表默认配置
└── assets/
    ├── logo.png         # 机构 Logo
    └── watermark.png    # 水印图片

2.2 Jinja2 基础语法

RAILWISE-OS 模板引擎支持标准 Jinja2 语法：

{# 变量输出 #}
{{ project.name }}
{{ project.contract_amount | format_currency }}

{# 条件判断 #}
{% if project.status == 'active' %}
  项目进行中
{% elif project.status == 'completed' %}
  项目已完成
{% else %}
  项目状态：{{ project.status }}
{% endif %}

{# 循环遍历 #}
{% for point in monitoring_points %}
  {{ loop.index }}. {{ point.name }}: {{ point.current_value }} mm
{% endfor %}

{# 宏定义（可复用代码块） #}
{% macro status_badge(status) %}
  {% if status == 'normal' %}<span class="badge-green">正常</span>
  {% elif status == 'warning' %}<span class="badge-yellow">预警</span>
  {% elif status == 'alarm' %}<span class="badge-red">报警</span>
  {% endif %}
{% endmacro %}

{# 使用宏 #}
{{ status_badge(point.status) }}

2.3 内置过滤器

过滤器	用法	说明
`format_date`	`{{ date \| format_date('%Y年%m月%d日') }}`	日期格式化
`format_number`	`{{ value \| format_number(2) }}`	数字格式化（保留小数位）
`format_currency`	`{{ amount \| format_currency }}`	货币格式化（¥）
`round`	`{{ value \| round(2) }}`	四舍五入
`abs`	`{{ value \| abs }}`	绝对值
`sum`	`{{ values \| sum }}`	求和
`avg`	`{{ values \| avg }}`	平均值
`max`	`{{ values \| max }}`	最大值
`min`	`{{ values \| min }}`	最小值
`markdown`	`{{ text \| markdown }}`	Markdown 转 HTML
`html_escape`	`{{ text \| html_escape }}`	HTML 转义

3. 数据变量系统

3.1 全局变量

所有模板均可访问以下全局变量：

变量名	类型	说明
`report`	Object	报告元信息（ID、名称、生成时间）
`project`	Object	项目信息
`organization`	Object	当前组织信息
`user`	Object	当前用户（生成者）
`generated_at`	string	报告生成时间（ISO 8601）

3.2 项目数据结构

interface ProjectData {
  id: string;
  code: string;
  name: string;
  type: string;
  status: string;
  contract_amount: number;
  start_date: string;
  end_date: string;
  manager: {
    name: string;
    phone: string;
    title: string;
  };
  client: {
    name: string;
    contact: string;
  };
  location: {
    province: string;
    city: string;
    address: string;
  };
  description: string;
}

3.3 监测数据变量

interface MonitoringData {
  points: MonitoringPoint[];      // 监测点列表
  data: DataRecord[];             // 数据记录
  statistics: {                   // 统计信息
    total_points: number;
    total_records: number;
    abnormal_count: number;
    warning_count: number;
    max_settlement: number;
    max_displacement: number;
  };
  trends: {                       // 趋势数据
    daily: TrendRecord[];
    weekly: TrendRecord[];
  };
}

interface MonitoringPoint {
  id: string;
  name: string;
  type: string;
  coordinates: [number, number];
  initial_values: Record<string, number>;
  current_values: Record<string, number>;
  cumulative_values: Record<string, number>;
  status: 'normal' | 'warning' | 'alarm';
  threshold: {
    warning: number;
    alarm: number;
  };
}

interface DataRecord {
  point_id: string;
  point_name: string;
  measured_at: string;
  values: Record<string, number>;
  status: string;
}

interface TrendRecord {
  date: string;
  point_id: string;
  value: number;
  status: string;
}

4. 图表配置

4.1 图表声明

在 config.yaml 中声明图表：

charts:
  - id: settlement_trend
    title: "沉降时程曲线"
    type: line
    data_source: trends.daily
    x_axis: date
    y_axis: value
    series:
      - field: value
        label: "累计沉降(mm)"
        color: "#2563eb"
    options:
      width: 600
      height: 400
      show_grid: true
      show_legend: true

  - id: displacement_distribution
    title: "位移分布图"
    type: bar
    data_source: points
    x_axis: name
    y_axis: cumulative_values.dx
    options:
      width: 600
      height: 400
      horizontal: false

4.2 图表类型

类型	说明	适用场景
`line`	折线图	时程曲线、趋势分析
`bar`	柱状图	数值对比、分布统计
`scatter`	散点图	相关性分析
`area`	面积图	累积量展示
`heatmap`	热力图	空间分布
`gauge`	仪表盘	单点状态
`table`	表格图	数据明细展示

4.3 在模板中引用图表

{# 方式1：自动插入（根据 config.yaml 配置） #}
{{ chart('settlement_trend') }}

{# 方式2：内联定义 #}
{{ chart({
  'type': 'line',
  'title': '水平位移时程曲线',
  'data': trends.daily,
  'x': 'date',
  'y': 'value',
  'series': [
    {'field': 'dx', 'label': 'X方向', 'color': '#2563eb'},
    {'field': 'dy', 'label': 'Y方向', 'color': '#dc2626'}
  ]
}) }}

5. 完整模板示例

5.1 监测日报模板

{# ========================================== #}
{# 监测日报模板 - template.j2                 #}
{# ========================================== #}

{% set report_date = report.period.end_date | format_date('%Y年%m月%d日') %}

<h1 style="text-align: center; font-size: 22pt;">
  {{ project.name }}监测日报
</h1>
<p style="text-align: center; color: #666;">
  第 {{ report.period.day_number }} 期 | {{ report_date }}
</p>

<h2>一、项目概况</h2>
<table class="info-table">
  <tr><td>项目名称</td><td>{{ project.name }}</td></tr>
  <tr><td>项目编号</td><td>{{ project.code }}</td></tr>
  <tr><td>监测单位</td><td>{{ organization.name }}</td></tr>
  <tr><td>建设单位</td><td>{{ project.client.name }}</td></tr>
  <tr><td>报告日期</td><td>{{ report_date }}</td></tr>
  <tr><td>天气情况</td><td>{{ report.weather | default('晴') }}</td></tr>
</table>

<h2>二、监测数据汇总</h2>
<p>本次监测共 {{ monitoring.statistics.total_points }} 个监测点，
   采集数据 {{ monitoring.statistics.total_records }} 条。</p>

<table class="data-table">
  <thead>
    <tr>
      <th>序号</th>
      <th>监测点</th>
      <th>类型</th>
      <th>累计沉降(mm)</th>
      <th>累计位移(mm)</th>
      <th>状态</th>
    </tr>
  </thead>
  <tbody>
    {% for point in monitoring.points %}
    <tr>
      <td>{{ loop.index }}</td>
      <td>{{ point.name }}</td>
      <td>{{ point.type }}</td>
      <td>{{ point.cumulative_values.settlement | round(2) }}</td>
      <td>{{ point.cumulative_values.displacement | round(2) }}</td>
      <td>{{ status_badge(point.status) }}</td>
    </tr>
    {% endfor %}
  </tbody>
</table>

<h2>三、时程曲线</h2>
{{ chart('settlement_trend') }}

<h2>四、异常点说明</h2>
{% if monitoring.statistics.abnormal_count > 0 %}
  <p class="warning">本次监测发现 {{ monitoring.statistics.abnormal_count }} 个异常点，详情如下：</p>
  <ul>
    {% for point in monitoring.points if point.status != 'normal' %}
    <li>
      <strong>{{ point.name }}</strong>：
      当前值 {{ point.current_values.settlement | round(2) }} mm，
      已超过 {{ point.threshold.warning }} mm 预警值
    </li>
    {% endfor %}
  </ul>
{% else %}
  <p class="normal">本次监测所有点位数据正常，无异常。</p>
{% endif %}

<h2>五、结论与建议</h2>
<p>根据本次监测数据分析：</p>
<ol>
  <li>各监测点数据变化趋势平稳，未发现明显异常；</li>
  <li>建议继续按现有频率进行监测；</li>
  <li>如遇特殊情况，应及时加密监测并上报。</li>
</ol>

<p style="text-align: right; margin-top: 40px;">
  报告编制：{{ user.name }}<br>
  审核：________________<br>
  日期：{{ generated_at | format_date('%Y年%m月%d日') }}
</p>

5.2 配套配置 (config.yaml)

# 模板配置
template:
  name: "监测日报"
  version: "1.0.0"
  description: "标准监测日报模板"

# 数据源配置
data_source:
  project:
    type: "api"
    endpoint: "/projects/{project_id}"

  monitoring:
    type: "api"
    endpoint: "/data/monitoring"
    params:
      start_time: "{{ report.period.start_date }}"
      end_time: "{{ report.period.end_date }}"

  trends:
    type: "api"
    endpoint: "/data/trends"
    params:
      interval: "day"

# 图表配置
charts:
  - id: settlement_trend
    title: "沉降时程曲线"
    type: line
    data_source: trends.daily
    x_axis: date
    y_axis: value
    series:
      - field: value
        label: "累计沉降(mm)"
        color: "#2563eb"
    options:
      width: 600
      height: 400
      show_grid: true
      y_axis_label: "累计沉降(mm)"

# 样式配置
styles:
  page:
    margin: "2.54cm"
    font_family: "SimSun, serif"
    font_size: "12pt"

  heading:
    h1: { font_size: "22pt", bold: true, align: "center" }
    h2: { font_size: "16pt", bold: true, color: "#1a1a1a" }
    h3: { font_size: "14pt", bold: true, color: "#333333" }

  table:
    border: true
    border_color: "#cccccc"
    header_background: "#f5f5f5"
    header_bold: true
    cell_padding: "6pt"

  badge:
    normal: { background: "#dcfce7", color: "#166534" }
    warning: { background: "#fef3c7", color: "#92400e" }
    alarm: { background: "#fee2e2", color: "#991b1b" }

6. 模板上传与管理

6.1 上传模板

curl -X POST "https://api.os.railwise.cn/v3/reports/templates" \
  -H "X-API-Key: rwsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: multipart/form-data" \
  -F "name=监测日报" \
  -F "description=标准监测日报模板" \
  -F "file=@template.zip"

6.2 模板管理 API

端点	方法	说明
`/reports/templates`	GET	获取模板列表
`/reports/templates`	POST	上传模板
`/reports/templates/{id}`	GET	获取模板详情
`/reports/templates/{id}`	PUT	更新模板
`/reports/templates/{id}`	DELETE	删除模板
`/reports/templates/{id}/preview`	POST	预览模板

7. 高级功能

7.1 自定义过滤器

开发者可在模板中注册自定义过滤器：

# Python 自定义过滤器示例
def format_settlement(value):
    """格式化沉降值，自动添加方向符号"""
    if value > 0:
        return f"抬升 {abs(value):.2f} mm"
    else:
        return f"沉降 {abs(value):.2f} mm"

# 在模板中使用
# {{ point.cumulative_values.settlement | format_settlement }}
# 输出: "沉降 2.50 mm" 或 "抬升 1.20 mm"

7.2 条件渲染

{# 根据项目类型显示不同内容 #}
{% if project.type == 'foundation' %}
  {% include 'sections/foundation_analysis.j2' %}
{% elif project.type == 'tunnel' %}
  {% include 'sections/tunnel_analysis.j2' %}
{% elif project.type == 'bridge' %}
  {% include 'sections/bridge_analysis.j2' %}
{% endif %}

7.3 分页控制

{# 强制分页 #}
<div style="page-break-after: always;"></div>

{# 避免分页断开表格 #}
<table style="page-break-inside: avoid;">
  ...
</table>

8. 调试与测试

8.1 模板预览

# 预览模板（不生成最终文件）
curl -X POST "https://api.os.railwise.cn/v3/reports/templates/tpl_001/preview" \
  -H "X-API-Key: rwsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "proj_abc123",
    "period": {
      "start_date": "2026-07-01",
      "end_date": "2026-07-08"
    }
  }'

8.2 调试模式

在 config.yaml 中启用调试模式：

development:
  debug: true
  show_variables: true  # 在报告中显示所有可用变量
  show_data_preview: true  # 显示数据预览

9. 相关文档

文档版本: v3.2.0 | 最后更新: 2026-07-08 | API版本: v3