# 内力与应力叠加：可计算范围、假定和数据合同

这套展台将三维几何、解析结果和显示状态分开保存。材质渲染、构件分解及施工过程示意不参与内力计算。当前提供两条可核验的解析路径；其他异形桥和组合桥保留外部计算结果导入接口，不给未求解的桥型生成工程数值。

| 模型 | 本轮可计算量 | 结果的含义 |
|---|---|---|
| `girder_reference` 梁桥受弯基准 | `M`、`V`、`sigma` | 指定 24 m 全钢等截面简支箱梁的竖向弯矩、剪力、下缘纵向正应力 |
| `stayed_standard` 双塔双索面斜拉桥 | `N` | 给定每根索分担长度后，单根索竖向平衡所需的轴向拉力 |
| 其余 11 种教学变体 | 外部结果导入 | 需由提供者说明计算来源、模型版本、工况、轴向及结果适用范围 |

本轮没有建立整个空间桥梁的有限元模型，也没有做承载力、稳定、动力或施工状态验算。外部数据成功导入只表示格式与模型绑定通过，不表示其计算方法及结论经过独立复核。

## 1. 简支全钢箱梁解析算例

桥跨支承中心为 `x=-12 m` 与 `x=12 m`，跨度 `L=24 m`。专用分析主梁 ID 为 `equivalent-main-beam`。显示基线位于 `y=0、z=4.4 m`，它是构件示意轴；截面的实际形心高度另行精算，不能把显示基线误当形心。

顶面标高 `z=5.0 m`，箱梁总高 `1.2 m`。四块不重叠矩形板件均假定为同一钢材、同一弹性模量：

| 板件 | 宽或厚（m） | 高或厚（m） | 面积（m²） | 自箱梁底面起的形心 z（m） |
|---|---:|---:|---:|---:|
| 顶板 | 6.00 | 0.18 | 1.080 | 1.110 |
| 底板 | 5.20 | 0.12 | 0.624 | 0.060 |
| 左腹板 | 0.12 | 0.90 | 0.108 | 0.570 |
| 右腹板 | 0.12 | 0.90 | 0.108 | 0.570 |

由矩形面积加权及平行轴定理得到：

- 总面积 `A=1.92 m²`。
- 形心距底面 `c_lower=0.708 m`，实际形心标高 `z=4.508 m`。
- 形心距顶面 `c_upper=0.492 m`。
- 绕横桥向 y 轴的惯性矩 `I_y=0.45891072 m⁴`。
- 下缘抗弯截面模量 `W_lower=0.6481789831 m³`。

这里使用的是空心箱梁板件的组合截面，不能用 `6×1.2` 外包实体矩形的惯性矩替代。铺装、栏杆、行人等不计入截面刚度。

令 `x_local` 为从左支承起的距离，`q` 为整根梁上的向下均布线荷载，单位 kN/m：

```text
R_left = R_right = q L / 2
V(x_local) = q L / 2 − q x_local
M_y(x_local) = q x_local (L − x_local) / 2
sigma_lower [MPa] = M_y [kN·m] c_lower [m] / I_y [m⁴] / 1000
```

弯矩以下缘受拉的正弯矩为正。剪力采用左段截面内剪力向下为正的约定，因此左端内侧为正、右端内侧为负。下缘应力以拉为正。图线偏移只是标量大小的显示，不能当成变形曲线。

默认 `q=20 kN/m` 时，两端反力各为 `240 kN`；跨中最大弯矩 `1440 kN·m`；两端内侧剪力分别为 `+240` 和 `−240 kN`；下缘最大纵向拉应力为 `2.221608595 MPa`。

`sigma` 仅表示下缘纵向正应力，沿主梁基线显示。它不包含腹板剪应力、局部应力集中、扭转、剪力滞或局部屈曲，不是实体表面全场应力，也不是 von Mises 应力云图。采用小位移线弹性梁假定；程序不会自动添加自重或设计荷载组合。

## 2. 标准斜拉桥的单索分担荷载算例

桥梁主跨 120 m、两侧边跨各 48 m，总长 216 m，两个索面。每根索由真实规范坐标中的梁端和塔端定义，顺序固定为 `[deckAnchor, towerAnchor]`。模型显式给出每根索的纵向分担长度 `s_i`；计算不从索的外观或网格密度猜测这个长度。

设全桥宽范围内的向下线荷载为 `q`，索面数为 `n=2`，索长为 `L_i`，梁端至塔端的竖向高差为 `Δz_i`：

```text
W_i = q s_i / n
sin(theta_i) = Δz_i / L_i
N_i = W_i / sin(theta_i)
F_on_deck = N_i (p_tower − p_deck) / L_i
F_on_tower = −F_on_deck
```

每索面覆盖的分担长度为 185 m；其余 31 m 对应塔旁、跨中和端部未纳入本算例的梁区。默认 `q=20 kN/m` 时，各索分担荷载之和为 `3700 kN`。这个数字仅是所指定局部区域的竖向荷载总和，不能称为全桥总荷载或支座反力。

计算返回每根索的拉力、坡角、水平分力和三维力向量。逐索核对 `N_i sin(theta_i)=W_i`，并核对梁端和塔端的作用反作用。只在各索内部绘制恒定轴力。

该算例没有求解主梁刚度、塔柱位移或各索之间的荷载重新分配。忽略索自重垂度、预张力、温度和几何非线性；索的水平分力需要由主梁、塔柱及锚固体系平衡，这些构件的内力没有由本算例求出。不能由这些索力反推斜拉桥的全桥弯矩图或应力场。

## 3. 图示与阶段的适用边界

- 内置基准简支梁的解析 `M/V` 可沿规范全局 z 方向画偏移图，并附原始量纲和正负号。偏移高度是显示比例，不是结构变形。
- 外部 `M/V` 沿构件未变形基线着色表达标量，不画空间偏移图；侧栏必须显示数据提供者的 `result_axis` 和 `sign_convention`。即使数据使用局部轴，也不擅自把它解释成全局方向。
- `N/sigma` 沿相关构件基线着色；单个样本可显示点值，不补造未提供的结果。它们都不自动变成实体表面全场云图。
- 切换桥型应清除旧桥结果。当前合同仅接受 `stage_id='complete'`；施工阶段或爆炸分解时暂时隐藏完整装配结果，恢复匹配状态再显示。
- 几何、荷载及原始结果仍保存在米制规范坐标内。相机、材质、构件分解位移、显示比例不能回写到结果值或分析坐标。

## 4. 程序接口

```js
availableQuantities(model) // ['M','V','sigma']、['N'] 或 []
computeTeachingResult(model, { q: 20, quantity: 'M' })
validateOverlay(data, model) // { ok: boolean, errors: string[] }
```

`computeTeachingResult` 默认工程量是 `M`；界面必须按 `availableQuantities()` 选择当前桥型的可用量。没有数值路径时函数抛出明确说明，不生成代用结果。`boxSectionProperties(section)` 额外导出截面核算函数，供复核使用。

计算结果的共同字段：

```json
{
  "schema": "bridge-force-overlay/1",
  "bridge_id": "girder_reference",
  "geometry_revision": "1",
  "source": {
    "kind": "analytical",
    "title": "等截面简支全钢箱梁 · 主梁弯矩解析算例",
    "file_or_url": "结果叠加说明.md",
    "equations": ["M_y(x) = q x (L-x) / 2"]
  },
  "quantity": "M",
  "unit": "kN·m",
  "load_case": "q=20 kN/m，整根梁均布荷载，自重未自动附加",
  "combination": null,
  "stage_id": "complete",
  "coordinate_system": "x-longitudinal,y-transverse,z-up",
  "length_unit": "m",
  "sign_convention": "下缘受拉的正弯矩为正",
  "result_axis": "global transverse y bending; sagging-positive convention",
  "samples": [
    { "component_id": "equivalent-main-beam", "position_m": [-12, 0, 4.4], "value": 0 },
    { "component_id": "equivalent-main-beam", "position_m": [0, 0, 4.4], "value": 1440 },
    { "component_id": "equivalent-main-beam", "position_m": [12, 0, 4.4], "value": 0 }
  ],
  "min": 0,
  "max": 1440,
  "legend": { "title": "主梁弯矩 M_y", "unit": "kN·m", "min": 0, "max": 1440 },
  "assumptions": ["24 m 等截面全钢简支箱梁，仅此基准算例适用"]
}
```

实际内置梁结果使用 49 个站点；上例只保留 3 个站点说明数据格式。内置索结果每索使用 9 个等分站点，其中值保持常数。返回的 `equilibrium` 为平衡复核数据；梁还返回 `section`，索还返回 `cable_checks`。这些字段用于解释与复核，不改变原始样本。

## 5. 外部结果导入

外部文件沿用以上合同，但 `source.kind` 必须为 `external`，并提供 `source.title`、`source.file_or_url`，以及可识别的 `source.solver`（包含版本）或 `source.report`。不能仅把文件名写成“计算结果”而省略计算来源、轴向及工况。实际报告及求解文件由提供者保管；展台不会根据字段文字去验证报告的真实性。

工程量和单位严格配对：`M → kN·m`，`N/V → kN`，`sigma → MPa`。位置必须用 m，三维坐标必须为 `x=纵桥向、y=横桥向、z=向上`。其他单位请在上游显式换算；展台不静默猜测换算比例。

`samples` 是唯一消费的样本数组，每项需给构件 ID、恰有三个有限坐标的位置、有限有符号数值。按工程报告提供局部轴信息；同一份标量数据只描述一种明确轴向或应力分量，不得混入多个物理分量。数据基线须位于对应构件的规范几何范围内；若该 ID 对应杆件中心线，位置还必须落在其未变形基线上，容差为 `0.0001 m`。

校验拒绝错误合同版本、桥型/几何版本不符、未知构件、非有限数、错误坐标维数、空结果、坐标越界、不兼容施工阶段、缺失来源和符号约定、单位不符、冗余数组长度不符、虚报极值或图例等。单份最多 100000 个样本。若声明 `display_scale`，必须为有限正数并附 `display_scale_unit`；若声明 `display_direction`，必须为规范坐标内的单位向量。这些显示字段不允许修改原始值。

## 6. 核验与重跑

在本目录运行：

```text
node analysis-verify.mjs
```

结果写入 `analysis-verification.json`。核验包含：箱梁独立手算截面；支承平衡和零端弯矩；跨中及四分点弯矩；剪力与弯矩导数一致；下缘应力单位换算；3-4-5 单索手算；带横向分力的三维索；零荷载；不适用桥型拒绝；导入错误拒绝；校验无副作用；实际 `model.js` 中全部可计算模型的绑定。

手算单索基准为：索水平投影 30 m、高差 40 m、长度 50 m，`q=20 kN/m`、`s=8 m`、两个索面，因此单索竖向分担荷载为 80 kN，拉力为 100 kN，水平分力为 60 kN。该独立基准用于检验算法，不代表标准斜拉桥每根索具有同一坡角。

核验文件记录程序执行时间、运行版本、通过/失败条目与实际模型极值。数值核验和导入合同核验不替代浏览器视觉核验，也不构成桥梁设计证明。


### 导入结果的本轮显示方式

无论导入文件声明为外部计算或解析算例，均只在原始规范坐标采样点上着色，不把稀疏点跨越曲线构件连成直线，也不推断样本之间的应力场。可见图例同时保留工况、工程量、单位、方向、正负号与极值。只有页面内即时计算的基准简支梁生成沿规范 z 方向偏移的弯矩、剪力图和给定荷载/支反力箭头。导入失败会清除旧结果，防止误把上一文件的图形当作新结果。