final version

docs/参数注册表_中文.md

@@ -0,0 +1,352 @@
+# 参数注册表（中文）
+
+本注册表用于将当前代码中硬编码的参数，映射到统一的 `config` 结构中。
+它采用“字段导向”的组织方式，目的是让后续 GUI 能围绕稳定的数据 schema 来构建。
+
+## 约定说明
+
+- `Config Path`：统一 `config` 中的目标字段路径
+- `Source Variable`：当前代码中的变量名
+- `Source File`：当前 MATLAB 中定义该参数的文件
+- `Cases`：当前哪些算例目录使用了该字段
+- `Editable`：GUI 是否应向用户暴露该字段
+- `Notes`：行为说明、枚举含义或数据形状说明
+
+## Meta
+
+| Config Path | Source Variable | Source File | Cases | Editable | Notes |
+| --- | --- | --- | --- | --- | --- |
+| `meta.case_name` | 无 | 模板层 | 全部 | 是 | 显示名称 |
+| `meta.case_id` | 无 | 模板层 | 全部 | 是 | 稳定的预设 ID |
+| `meta.description` | 无 | 模板层 | 全部 | 是 | 自由文本描述 |
+| `meta.source_case_folder` | 文件夹名 | 模板层 | 全部 | 否 | 用于追踪来源 |
+| `meta.created_from_template` | 无 | 模板层 | 全部 | 否 | 预设来源 |
+| `meta.version` | 无 | 配置系统 | 全部 | 否 | Schema 版本 |
+
+## Model
+
+| Config Path | Source Variable | Source File | Cases | Editable | Notes |
+| --- | --- | --- | --- | --- | --- |
+| `model.modelflag` | `modelflag` | `main1.m` | 1-7 | 是 | 当前算例均使用 `1` |
+| `model.grid_model` | `grid_model` | `main1.m` | 1-7 | 是 | `1` 为 SP，`2` 为 DP |
+| `model.flow_model` | `flow_model` | `main1.m` | 1-7 | 是 | `1` 气水，`2` 油水，`3` 组分流 |
+
+## Grid Geometry
+
+| Config Path | Source Variable | Source File | Cases | Editable | Notes |
+| --- | --- | --- | --- | --- | --- |
+| `grid.dx` | `dx` | `main1.m` | 1-7 | 是 | 向量 |
+| `grid.dy` | `dy` | `main1.m` | 1-7 | 是 | 向量 |
+| `grid.dz` | `dz` | `main1.m` | 1-7 | 是 | 向量 |
+| `grid.nx` | `nx` | `main1.m` | 1-7 | 否 | 由 `dx` 推导 |
+| `grid.ny` | `ny` | `main1.m` | 1-7 | 否 | 由 `dy` 推导 |
+| `grid.nz` | `nz` | `main1.m` | 1-7 | 否 | 由 `dz` 推导 |
+| `grid.NTG` | `NTG` | `main1.m` | 1-7 | 否 | 大小为 `nx*ny*nz` 的数组 |
+
+由 `GridProp_pre.m` 生成的派生字段：
+
+- `grid.coordinates`
+- `grid.nodes`
+- `grid.nP`
+- `grid.nmc`
+- `grid.dxv`
+- `grid.dyv`
+- `grid.dzv`
+- `grid.zm`
+- `grid.vm`
+- `grid.xrao`
+- `grid.yrao`
+- `grid.zrao`
+- `grid.cell_mid_coords`
+
+## Fracture Input
+
+| Config Path | Source Variable | Source File | Cases | Editable | Notes |
+| --- | --- | --- | --- | --- | --- |
+| `fracture.input_style` | `input_style` | `main1.m` | 1-7 | 是 | 1 工程输入，2 向量输入，3 二维线段输入，4 fab 预留 |
+| `fracture.input_content` | `input_content` | `main1.m` | 1-7 | 是 | 工程裂缝表 |
+| `fracture.f` | `f` | `main1.m` / helper 输出 | 1-7 | 高级 | 裂缝向量表示 |
+| `fracture.fellip` | `fellip` | `main1.m` / helper 输出 | 1-7 | 高级 | 椭圆裂缝 |
+| `fracture.fractureLines` | `fractureLines` | `main1.m` | 1-7 | 是 | 在模式 3 下使用 |
+| `fracture.fractureHeights` | `fractureHeights` | `main1.m` | 1-7 | 是 | 在模式 3 下使用 |
+| `fracture.flowBarrierFlags` | `flowBarrierFlags` | `main1.m` | 1-7 | 是 | 可选 |
+| `fracture.frac_information` | `frac_information` | helper 输出 | 1-7 | 否 | 由辅助函数生成 |
+| `fracture.nf` | `nf` | `main1.m` | 1-7 | 否 | 裂缝数量派生值 |
+
+## Discretization Selection
+
+| Config Path | Source Variable | Source File | Cases | Editable | Notes |
+| --- | --- | --- | --- | --- | --- |
+| `discretization.mode` | `grid_model` | `main1.m` | 1-7 | 是 | 与 `model.grid_model` 对应 |
+| `discretization.use_operator` | 隐式 | `main1.m` | 1-7 | 否 | 当前始终调用 `OperatorRS` |
+
+## SP Rock And Boundary Parameters
+
+这些字段是关键的可编辑参数，之前统计时偏少。
+
+| Config Path | Source Variable | Source File | Cases | Editable | Notes |
+| --- | --- | --- | --- | --- | --- |
+| `discretization.sp.boundary_polygon` | `boundary` | `grid_discretization_SP_model.m` | 1 | 是 | 不规则计算域边界多边形 |
+| `discretization.sp.invalid_layer` | `invalid_layer` | `grid_discretization_SP_model.m` | 1,2,4,5,6,7 | 是 | 在模拟中禁用的层号 |
+| `discretization.sp.valid_grids` | `valid_grids` | `grid_discretization_SP_model.m` | 1,2,4,5,6,7 | 否 | 由边界和层信息推导 |
+| `discretization.sp.matrix.kx` | `kx` | `grid_discretization_SP_model.m` | 1,2,4,5,6,7 | 是 | 数组或生成场 |
+| `discretization.sp.matrix.ky` | `ky` | `grid_discretization_SP_model.m` | 1,2,4,5,6,7 | 是 | 数组或生成场 |
+| `discretization.sp.matrix.kz` | `kz` | `grid_discretization_SP_model.m` | 1,2,4,5,6,7 | 是 | 数组或生成场 |
+| `discretization.sp.matrix.pori` | `pori` | `grid_discretization_SP_model.m` | 1,2,4,5,6,7 | 是 | 数组或生成场 |
+| `discretization.sp.matrix.prpor` | `prpor` | `grid_discretization_SP_model.m` | 1,2,4,5,6,7 | 是 | 基质参考压力 |
+| `discretization.sp.matrix.cpor` | `cpor` | `grid_discretization_SP_model.m` | 1,2,4,5,6,7 | 是 | 基质压缩系数 |
+| `discretization.sp.matrix.rock_density` | `rock_density` / `density_rock` | `grid_discretization_SP_model.m` | 1,2,4,5,6,7 | 是 | 各算例命名不一致 |
+| `discretization.sp.fracture.Kf` | `Kf` | `grid_discretization_SP_model.m` | 1,2,4,5,6,7 | 是 | 裂缝渗透率 |
+| `discretization.sp.fracture.Wf` | `Wf` | `grid_discretization_SP_model.m` | 1,2,4,5,6,7 | 是 | 裂缝缝宽 |
+| `discretization.sp.fracture.Porf` | `Porf` | `grid_discretization_SP_model.m` | 1,2,4,5,6,7 | 是 | 裂缝孔隙度 |
+| `discretization.sp.fracture.prporf` | `prporf` | `grid_discretization_SP_model.m` | 1,2,4,5,6,7 | 是 | 裂缝参考压力 |
+| `discretization.sp.fracture.cporf` | `cporf` | `grid_discretization_SP_model.m` | 1,2,4,5,6,7 | 是 | 裂缝压缩系数 |
+| `discretization.sp.stress.fracture_factor` | `stress_factor_fracture` | `grid_discretization_SP_model.m` | 1,2,4,5,6,7 | 是 | 应力敏感系数 |
+| `discretization.sp.stress.matrix_factor` | `stress_factor_matrix` | `grid_discretization_SP_model.m` | 1,2,4,5,6,7 | 是 | 应力敏感系数 |
+| `discretization.sp.stress.ref_pressure` | `stress_factor_ref_pressure` | `grid_discretization_SP_model.m` | 1,2,4,5,6,7 | 是 | 参考压力 |
+| `discretization.sp.stress.Rpt` | `Rpt` | `grid_discretization_SP_model.m` | 1,2,4,5,6,7 | 是 | 含义待进一步确认 |
+| `discretization.sp.stress.cf` | `cf` | `grid_discretization_SP_model.m` | 1,2,4,5,6,7 | 是 | 含义待进一步确认 |
+| `discretization.sp.stress.ca` | `ca` | `grid_discretization_SP_model.m` | 1,2,4,5,6,7 | 是 | 含义待进一步确认 |
+
+各算例补充说明：
+
+- 算例 1 使用空间函数和不规则多边形边界。
+- 算例 2 和 4 在适用时使用 `invalid_layer` 关闭第二层。
+- 算例 5 和 7 的常数基质参数与算例 2、4、6 不同。
+
+## DP Rock Parameters
+
+| Config Path | Source Variable | Source File | Cases | Editable | Notes |
+| --- | --- | --- | --- | --- | --- |
+| `discretization.dp.fracture_layer.kx` | `kx` | `grid_discretization_DP_model.m` | 3 | 是 | 双重介质中的裂缝层 |
+| `discretization.dp.fracture_layer.ky` | `ky` | `grid_discretization_DP_model.m` | 3 | 是 | 双重介质中的裂缝层 |
+| `discretization.dp.fracture_layer.kz` | `kz` | `grid_discretization_DP_model.m` | 3 | 是 | 双重介质中的裂缝层 |
+| `discretization.dp.fracture_layer.pori` | `pori` | `grid_discretization_DP_model.m` | 3 | 否 | 裂缝层孔隙度 |
+| `discretization.dp.matrix_layer.kx` | `kx_matrixLayer` | `grid_discretization_DP_model.m` | 3 | 是 | 基质层渗透率 |
+| `discretization.dp.matrix_layer.ky` | `ky_matrixLayer` | `grid_discretization_DP_model.m` | 3 | 是 | 基质层渗透率 |
+| `discretization.dp.matrix_layer.kz` | `kz_matrixLayer` | `grid_discretization_DP_model.m` | 3 | 是 | 基质层渗透率 |
+| `discretization.dp.matrix_layer.pori` | `pori_matrixLayer` | `grid_discretization_DP_model.m` | 3 | 是 | 基质层孔隙度 |
+| `discretization.dp.shape_factor` | `sigma` | `grid_discretization_DP_model.m` | 3 | 是 | 孔隙间形状因子 |
+| `discretization.dp.valid_grids` | `valid_grids` | `grid_discretization_DP_model.m` | 3 | 否 | 当前算例中全为 1 |
+| `discretization.dp.NTG` | `NTG` | `grid_discretization_DP_model.m` | 3 | 是 | 在文件中被重新赋值 |
+| `discretization.dp.prpor` | `prpor` | `grid_discretization_DP_model.m` | 3 | 是 | 参考压力 |
+| `discretization.dp.cpor` | `cpor` | `grid_discretization_DP_model.m` | 3 | 是 | 压缩系数 |
+| `discretization.dp.fracture.Kf` | `Kf` | `grid_discretization_DP_model.m` | 3 | 是 | 裂缝渗透率 |
+| `discretization.dp.fracture.Wf` | `Wf` | `grid_discretization_DP_model.m` | 3 | 是 | 裂缝缝宽 |
+| `discretization.dp.fracture.Porf` | `Porf` | `grid_discretization_DP_model.m` | 3 | 是 | 裂缝孔隙度 |
+| `discretization.dp.fracture.prporf` | `prporf` | `grid_discretization_DP_model.m` | 3 | 是 | 裂缝参考压力 |
+| `discretization.dp.fracture.cporf` | `cporf` | `grid_discretization_DP_model.m` | 3 | 是 | 裂缝压缩系数 |
+| `discretization.dp.stress.fracture_factor` | `stress_factor_fracture` | `grid_discretization_DP_model.m` | 3 | 是 | 应力敏感 |
+| `discretization.dp.stress.matrix_factor` | `stress_factor_matrix` | `grid_discretization_DP_model.m` | 3 | 是 | 应力敏感 |
+| `discretization.dp.stress.ref_pressure` | `stress_factor_ref_pressure` | `grid_discretization_DP_model.m` | 3 | 是 | 参考压力 |
+| `discretization.dp.rock_density` | `rock_density` | `grid_discretization_DP_model.m` | 3 | 是 | 岩石密度 |
+| `discretization.dp.Rpt` | `Rpt` | `grid_discretization_DP_model.m` | 3 | 是 | 含义待进一步确认 |
+| `discretization.dp.cf` | `cf` | `grid_discretization_DP_model.m` | 3 | 是 | 含义待进一步确认 |
+| `discretization.dp.ca` | `ca` | `grid_discretization_DP_model.m` | 3 | 是 | 含义待进一步确认 |
+
+## Flow: Gas-Water
+
+| Config Path | Source Variable | Source File | Cases | Editable | Notes |
+| --- | --- | --- | --- | --- | --- |
+| `flow.gas_water.gas_prop.VL` | `gas_prop.VL` | `gas_water_flow.m` | 4 | 是 | Langmuir 体积 |
+| `flow.gas_water.gas_prop.PL` | `gas_prop.PL` | `gas_water_flow.m` | 4 | 是 | Langmuir 压力 |
+| `flow.gas_water.gas_prop.Kn` | `gas_prop.Kn` | `gas_water_flow.m` | 4 | 是 | Knudsen 数 |
+| `flow.gas_water.gas_prop.Kn_modified_factor` | `gas_prop.Kn_modified_factor` | `gas_water_flow.m` | 4 | 否 | 派生值 |
+| `flow.gas_water.gas_prop.beta_non_darcy_flow` | `gas_prop.beta_non_Darcy_flow` | `gas_water_flow.m` | 4 | 是 | 高速流修正项 |
+| `flow.gas_water.p_grad_threshold` | `p_grad_threshold` | `gas_water_flow.m` | 4 | 是 | 启动压力梯度 |
+| `flow.gas_water.density_g_sc` | `density_g_sc` | `gas_water_flow.m` | 4 | 是 | 标况气体密度 |
+| `flow.gas_water.density_w_sc` | `density_w_sc` | `gas_water_flow.m` | 4 | 是 | 标况水密度 |
+| `flow.gas_water.gas_model` | `gas_model` | `gas_water_flow.m` | 4 | 是 | 1 生成型 PVT，2 表格型 PVT |
+| `flow.gas_water.prg` | `prg` | `gas_water_flow.m` | 4 | 是 | 仅在模型 1 中使用 |
+| `flow.gas_water.Bgi` | `Bgi` | `gas_water_flow.m` | 4 | 是 | 仅在模型 1 中使用 |
+| `flow.gas_water.cg` | `cg` | `gas_water_flow.m` | 4 | 是 | 仅在模型 1 中使用 |
+| `flow.gas_water.vgi` | `vgi` | `gas_water_flow.m` | 4 | 是 | 仅在模型 1 中使用 |
+| `flow.gas_water.cvg` | `cvg` | `gas_water_flow.m` | 4 | 是 | 仅在模型 1 中使用 |
+| `flow.gas_water.Ppr` | `Ppr` | `gas_water_flow.m` | 4 | 是 | 表格或生成值 |
+| `flow.gas_water.BG` | `BG` | `gas_water_flow.m` | 4 | 是 | 表格或生成值 |
+| `flow.gas_water.MUG` | `MUG` | `gas_water_flow.m` | 4 | 是 | 表格或生成值 |
+| `flow.gas_water.prw` | `prw` | `gas_water_flow.m` | 4 | 是 | 水参考压力 |
+| `flow.gas_water.Bwi` | `Bwi` | `gas_water_flow.m` | 4 | 是 | 水体积系数 |
+| `flow.gas_water.cw` | `cw` | `gas_water_flow.m` | 4 | 是 | 水压缩系数 |
+| `flow.gas_water.vwi` | `vwi` | `gas_water_flow.m` | 4 | 是 | 水黏度 |
+| `flow.gas_water.cvw` | `cvw` | `gas_water_flow.m` | 4 | 是 | 水黏压系数 |
+| `flow.gas_water.ifpcgl` | `ifpcgl` | `gas_water_flow.m` | 4 | 是 | 毛管压开关 |
+| `flow.gas_water.matrix_relperm_table` | `RPGW` | `gas_water_flow.m` | 4 | 是 | 基质相对渗透率表 |
+| `flow.gas_water.fracture_relperm_table` | `PRF` | `gas_water_flow.m` | 4 | 是 | 裂缝相对渗透率表 |
+
+## Flow: Oil-Water
+
+| Config Path | Source Variable | Source File | Cases | Editable | Notes |
+| --- | --- | --- | --- | --- | --- |
+| `flow.oil_water.density_o_sc` | `density_o_sc` | `oil_water_flow.m` | 5,6,7 | 是 | 原油密度 |
+| `flow.oil_water.density_w_sc` | `density_w_sc` | `oil_water_flow.m` | 5,6,7 | 是 | 水密度 |
+| `flow.oil_water.oil_model` | `oil_model` | `oil_water_flow.m` | 5,6,7 | 是 | 1 生成型 PVT，2 表格型 |
+| `flow.oil_water.pro` | `pro` | `oil_water_flow.m` | 5,6,7 | 是 | 原油参考压力 |
+| `flow.oil_water.Boi` | `Boi` | `oil_water_flow.m` | 5,6,7 | 是 | 原油体积系数 |
+| `flow.oil_water.co` | `co` | `oil_water_flow.m` | 5,6,7 | 是 | 原油压缩系数 |
+| `flow.oil_water.voi` | `voi` | `oil_water_flow.m` | 5,6,7 | 是 | 原油黏度 |
+| `flow.oil_water.cvo` | `cvo` | `oil_water_flow.m` | 5,6,7 | 是 | 原油黏压系数 |
+| `flow.oil_water.Ppr` | `Ppr` | `oil_water_flow.m` | 5,6,7 | 是 | 表格或生成值 |
+| `flow.oil_water.BO` | `BO` | `oil_water_flow.m` | 5,6,7 | 是 | 表格或生成值 |
+| `flow.oil_water.MUO` | `MUO` | `oil_water_flow.m` | 5,6,7 | 是 | 表格或生成值 |
+| `flow.oil_water.prw` | `prw` | `oil_water_flow.m` | 5,6,7 | 是 | 水参考压力 |
+| `flow.oil_water.Bwi` | `Bwi` | `oil_water_flow.m` | 5,6,7 | 是 | 水体积系数 |
+| `flow.oil_water.cw` | `cw` | `oil_water_flow.m` | 5,6,7 | 是 | 水压缩系数 |
+| `flow.oil_water.vwi` | `vwi` | `oil_water_flow.m` | 5,6,7 | 是 | 水黏度 |
+| `flow.oil_water.cvw` | `cvw` | `oil_water_flow.m` | 5,6,7 | 是 | 水黏压系数 |
+| `flow.oil_water.ifpcow` | `ifpcow` | `oil_water_flow.m` | 5,6,7 | 是 | 毛管压开关 |
+| `flow.oil_water.matrix_relperm_table` | `PRM` | `oil_water_flow.m` | 5,6,7 | 是 | 基质表 |
+| `flow.oil_water.fracture_relperm_table` | `PRF` | `oil_water_flow.m` | 5,6,7 | 是 | 裂缝表 |
+| `flow.oil_water.beta_non_darcy_flow` | `beta_non_Darcy_flow` | `oil_water_flow.m` | 5,6,7 | 是 | 非达西系数 |
+| `flow.oil_water.p_grad_threshold` | `p_grad_threshold` | `oil_water_flow.m` | 5,6,7 | 是 | 启动梯度 |
+
+## Flow: Multi-Component
+
+| Config Path | Source Variable | Source File | Cases | Editable | Notes |
+| --- | --- | --- | --- | --- | --- |
+| `flow.multi_component.Ds` | `Ds` | `multi_component_flow.m` | 1,2,3 | 是 | 表活扩散系数 |
+| `flow.multi_component.Db` | `Db` | `multi_component_flow.m` | 1,2,3 | 是 | 盐扩散系数 |
+| `flow.multi_component.c_ca_table` | `c_ca_table` | `multi_component_flow.m` | 1,2,3 | 是 | 吸附表 |
+| `flow.multi_component.cs_data` | `cs_data` | `multi_component_flow.m` | 1,2,3 | 否 | 由表派生 |
+| `flow.multi_component.cb_data` | `cb_data` | `multi_component_flow.m` | 1,2,3 | 否 | 由表派生 |
+| `flow.multi_component.csa_data` | `csa_data` | `multi_component_flow.m` | 1,2,3 | 否 | 由表派生 |
+| `flow.multi_component.cba_data` | `cba_data` | `multi_component_flow.m` | 1,2,3 | 否 | 由表派生 |
+| `flow.multi_component.R` | `R` | `multi_component_flow.m` | 1,2,3 | 是 | 化学常数 |
+| `flow.multi_component.Vm` | `Vm` | `multi_component_flow.m` | 1,2,3 | 是 | 摩尔体积 |
+| `flow.multi_component.Temperature` | `Temperature` | `multi_component_flow.m` | 1,2,3 | 是 | 温度 |
+| `flow.multi_component.chemistry_cof` | `chemistry_cof` | `multi_component_flow.m` | 1,2,3 | 否 | 派生值 |
+| `flow.multi_component.x_matrix!!!!` | `xm` | `multi_component_flow.m` | 1,2,3 | 是 | 基质单元化学活度因子 |
+| `flow.multi_component.x_fracture!!!` | `xf` | `multi_component_flow.m` | 1,2,3 | 是 | 裂缝单元化学活度因子 |
+| `flow.multi_component.cs_Nc` | `cs_Nc` | `multi_component_flow.m` | 1,2,3 | 是 | 动态相对渗透率映射 |
+| `flow.multi_component.Nc_nosurf` | `Nc_nosurf` | `multi_component_flow.m` | 1,2,3 | 否 | 派生值 |
+| `flow.multi_component.Nc_surf` | `Nc_surf` | `multi_component_flow.m` | 1,2,3 | 否 | 派生值 |
+| `flow.multi_component.kr_nosurf` | `kr_nosurf` | `multi_component_flow.m` | 1,2,3 | 是 | 相对渗透率表 |
+| `flow.multi_component.kr_surf` | `kr_surf` | `multi_component_flow.m` | 1,2,3 | 是 | 相对渗透率表 |
+| `flow.multi_component.PC` | `PC` | `multi_component_flow.m` | 1,2,3 | 是 | 毛管压表 |
+| `flow.multi_component.cs_Nc_fracture` | `cs_Nc_fracture` | `multi_component_flow.m` | 1,2,3 | 是 | 裂缝表 |
+| `flow.multi_component.kr_nosurf_fracture` | `kr_nosurf_fracture` | `multi_component_flow.m` | 1,2,3 | 是 | 裂缝表 |
+| `flow.multi_component.kr_surf_fracture` | `kr_surf_fracture` | `multi_component_flow.m` | 1,2,3 | 是 | 裂缝表 |
+| `flow.multi_component.PC_fracture` | `PC_fracture` | `multi_component_flow.m` | 1,2,3 | 是 | 裂缝毛管压表 |
+| `flow.multi_component.ifpcgl` | `ifpcgl` | `multi_component_flow.m` | 1,2,3 | 是 | 毛管压开关 |
+| `flow.multi_component.p_grad_threshold` | `p_grad_threshold` | `multi_component_flow.m` | 1,2,3 | 是 | 启动梯度 |
+| `flow.multi_component.gas_prop.VL` | `gas_prop.VL` | `multi_component_flow.m` | 1,2,3 | 是 | 类油场景中通常为 0 |
+| `flow.multi_component.gas_prop.PL` | `gas_prop.PL` | `multi_component_flow.m` | 1,2,3 | 是 | Langmuir 压力 |
+| `flow.multi_component.gas_prop.Kn` | `gas_prop.Kn` | `multi_component_flow.m` | 1,2,3 | 是 | Knudsen 数 |
+| `flow.multi_component.gas_prop.Kn_modified_factor` | `gas_prop.Kn_modified_factor` | `multi_component_flow.m` | 1,2,3 | 否 | 派生值 |
+| `flow.multi_component.gas_prop.stress_factor_fracture` | `gas_prop.stress_factor_fracture` | `multi_component_flow.m` | 1,2,3 | 是 | 在算例流体文件中出现 |
+| `flow.multi_component.gas_prop.stress_factor_matrix` | `gas_prop.stress_factor_matrix` | `multi_component_flow.m` | 1,2,3 | 是 | 在算例流体文件中出现 |
+| `flow.multi_component.gas_prop.stress_factor_ref_pressure` | `gas_prop.stress_factor_ref_pressure` | `multi_component_flow.m` | 1,2,3 | 是 | 在算例流体文件中出现 |
+| `flow.multi_component.gas_prop.beta_non_darcy_flow` | `gas_prop.beta_non_Darcy_flow` | `multi_component_flow.m` | 1,2,3 | 是 | 非达西系数 |
+| `flow.multi_component.density_g_sc` | `density_g_sc` | `multi_component_flow.m` | 1,2,3 | 是 | 标况密度 |
+| `flow.multi_component.gas_model` | `gas_model` | `multi_component_flow.m` | 1,2,3 | 是 | 1 生成型，2 表格型 |
+| `flow.multi_component.prg` | `prg` | `multi_component_flow.m` | 1,2,3 | 是 | 参考压力 |
+| `flow.multi_component.Bgi` | `Bgi` | `multi_component_flow.m` | 1,2,3 | 是 | 体积系数 |
+| `flow.multi_component.cg` | `cg` | `multi_component_flow.m` | 1,2,3 | 是 | 压缩系数 |
+| `flow.multi_component.vgi` | `vgi` | `multi_component_flow.m` | 1,2,3 | 是 | 黏度 |
+| `flow.multi_component.cvg` | `cvg` | `multi_component_flow.m` | 1,2,3 | 是 | 黏压系数 |
+| `flow.multi_component.Ppr` | `Ppr` | `multi_component_flow.m` | 1,2,3 | 是 | 表格或生成值 |
+| `flow.multi_component.BG` | `BG` | `multi_component_flow.m` | 1,2,3 | 是 | 表格或生成值 |
+| `flow.multi_component.MUG` | `MUG` | `multi_component_flow.m` | 1,2,3 | 是 | 表格或生成值 |
+| `flow.multi_component.density_w_sc` | `density_w_sc` | `multi_component_flow.m` | 1,2,3 | 是 | 水密度 |
+| `flow.multi_component.prw` | `prw` | `multi_component_flow.m` | 1,2,3 | 是 | 水参考压力 |
+| `flow.multi_component.Bwi` | `Bwi` | `multi_component_flow.m` | 1,2,3 | 是 | 水体积系数 |
+| `flow.multi_component.cw` | `cw` | `multi_component_flow.m` | 1,2,3 | 是 | 水压缩系数 |
+| `flow.multi_component.vwi` | `vwi` | `multi_component_flow.m` | 1,2,3 | 是 | 水黏度 |
+| `flow.multi_component.cvw` | `cvw` | `multi_component_flow.m` | 1,2,3 | 是 | 水黏压系数 |
+| `flow.multi_component.number_state_variables` | `number_state_variables` | `multi_component_flow.m` | 1,2,3 | 否 | 当前代码固定为 4 |
+
+## Initial Conditions
+
+| Config Path | Source Variable | Source File | Cases | Editable | Notes |
+| --- | --- | --- | --- | --- | --- |
+| `initial.pressure` | `P` | flow files | 1-7 | 是 | 初始压力数组 |
+| `initial.sw` | `Sw` | flow files | 1-7 | 是 | 初始含水饱和度数组 |
+| `initial.cs` | `Cs` | `multi_component_flow.m` | 1,2,3 | 是 | 初始表活浓度 |
+| `initial.cb` | `Cb` | `multi_component_flow.m` | 1,2,3 | 是 | 初始盐浓度 |
+
+## Wells
+
+| Config Path | Source Variable | Source File | Cases | Editable | Notes |
+| --- | --- | --- | --- | --- | --- |
+| `wells.well1` | `well1` | `main1.m` | 1-7 | 是 | 常规井表 |
+| `wells.num_fracture_wells` | `num_fracture_wells` | `main1.m` | 1-7 | 是 | 数量 |
+| `wells.welloc` | `welloc` | `main1.m` | 1-7 | 是 | 压裂井坐标 |
+| `wells.perfnum` | `perfnum` | helper 输出 | 1-7 | 否 | 由 `findWelloc` 推导 |
+| `wells.well2` | `well2` | `main1.m` | 1-7 | 是 | 压裂井表 |
+| `wells.Wellc` | `Wellc` | helper 输出 | 1-7 | 否 | 运行期组合结构 |
+
+常规井单行结构：
+
+- 井名
+- 射孔数
+- 射孔网格索引矩阵
+- 井筒半径
+- skin
+- 井类型
+
+压裂井单行结构：
+
+- 井名
+- 射孔数
+- 射孔索引
+- 井筒半径
+- skin
+- 井类型
+
+## Schedule
+
+| Config Path | Source Variable | Source File | Cases | Editable | Notes |
+| --- | --- | --- | --- | --- | --- |
+| `schedule.number_phases` | `number_phases` | `main1.m` | 1-7 | 是 | 阶段数 |
+| `schedule.well_schedules` | `well_schedules` | `main1.m` | 1-7 | 是 | 每个阶段的控制行 |
+| `schedule.time` | `time` | `main1.m` | 1-7 | 是 | 阶段时长向量 |
+| `schedule.dtmax` | `dtmax` | `main1.m` | 1-7 | 是 | 各阶段最大时间步 |
+| `schedule.dtmin` | `dtmin` | `main1.m` | 1-7 | 是 | 各阶段最小时间步 |
+
+观察到的 schedule 单行字段：
+
+- 井名
+- 井状态
+- 井角色
+- 控制模式
+- 目标值 1
+- 目标值 2
+- 可选的 `Cs_inj`
+- 可选的 `Cb_inj`
+
+## Solver
+
+| Config Path | Source Variable | Source File | Cases | Editable | Notes |
+| --- | --- | --- | --- | --- | --- |
+| `solver.yitap` | `yitap` | `main1.m` | 1-7 | 是 | 自适应时间步控制 |
+| `solver.yitas` | `yitas` | `main1.m` | 1-7 | 是 | 自适应时间步控制 |
+| `solver.omega` | `omega` | `main1.m` | 1-7 | 是 | 自适应时间步控制 |
+| `solver.Nmax` | `Nmax` | `main1.m` | 1-7 | 是 | 牛顿最大迭代次数 |
+| `solver.epsave` | `epsave` | `main1.m` | 1-7 | 是 | 平均残差容限 |
+| `solver.epsmax` | `epsmax` | `main1.m` | 1-7 | 是 | 最大残差容限 |
+
+## Runtime / Output
+
+| Config Path | Source Variable | Source File | Cases | Editable | Notes |
+| --- | --- | --- | --- | --- | --- |
+| `output.result_name` | 无 | 未来 GUI | 全部 | 是 | 结果标签 |
+| `output.save_input_path` | 无 | 未来 GUI | 全部 | 是 | 输入保存位置 |
+| `output.save_result_path` | 无 | 未来 GUI | 全部 | 是 | 结果保存位置 |
+| `output.plot_requests` | 无 | 未来 GUI | 全部 | 是 | 用户请求的绘图动作 |
+
+仅运行期输出：
+
+- `Times`
+- `OutputRs`
+- `Wellpara`
+- `trun`
+
+## 已知需要统一的地方
+
+- `rock_density` 和 `density_rock` 在 SP 离散化文件中都出现过。
+- 有些字段在某个算例里是可编辑表达式，在另一个算例里是常量数组，尤其是 `kx`、`ky`、`kz`、`pori`。
+- `boundary` 只出现在算例 1，其他 SP 算例没有。
+- DP 模式引入了 SP 模式中不存在的一组额外字段。
+
+这些不一致，正是为什么 GUI 必须建立在规范化 `config` 上，而不能直接建立在原始脚本变量之上。
+

docs/开发者快速入门.md

@@ -0,0 +1,503 @@
+# EDFM Simulator 开发者快速入门
+
+## 1. 先明确当前主线
+
+这个项目当前的正式 GUI 路线是：
+
+- 界面文件：`gui_support/app/EDFM_Simulator_App.mlapp`
+- 控制器：`gui_support/app/EDFMAppController.m`
+- 统一运行入口：`gui_support/runtime/run_case.m`
+
+早期 `.m` 版界面：
+
+- `gui_support/app/EDFMSimulatorApp.m`
+
+现在只应视为历史过渡版本，不应再作为主要开发方向。
+
+如果后续要继续开发，请默认以：
+
+- `.mlapp + controller`
+
+为主线。
+
+## 2. 当前架构怎么理解
+
+建议把项目拆成三层理解。
+
+### 第一层：界面层
+
+正式界面在：
+
+- `EDFM_Simulator_App.mlapp`
+
+你导出的可读版本在：
+
+- `gui_support/app/edfm_simulator_app.txt`
+
+这一层主要负责：
+
+- 组件摆放
+- 组件命名
+- 回调入口
+
+### 第二层：控制器层
+
+控制器文件：
+
+- `gui_support/app/EDFMAppController.m`
+
+这一层主要负责：
+
+- startup 初始化
+- 模板加载
+- 导入/导出配置
+- 导入/导出结果
+- UI 到 `config` 的写回
+- `config` 到 UI 的回填
+- 调用 `run_case(config)`
+- 更新结果页
+- 处理 wells 页表格逻辑
+
+### 第三层：后端运行层
+
+统一运行入口：
+
+- `gui_support/runtime/run_case.m`
+
+这一层负责：
+
+- 根据 `config` 构造运行所需参数
+- 调用网格、裂缝、流体、井、schedule 相关逻辑
+- 最终调用原始求解器
+
+## 3. 开发时应遵循的原则
+
+以后开发尽量遵循下面的分工。
+
+### `.mlapp` 负责什么
+
+- 负责界面布局
+- 负责组件名称
+- 负责简单回调入口
+
+### `EDFMAppController.m` 负责什么
+
+- 负责业务逻辑
+- 负责数据同步
+- 负责调用后端
+
+### `run_case.m` 负责什么
+
+- 负责统一组织求解流程
+- 负责把 `config` 真正转换成后端求解器输入
+
+简化理解就是：
+
+- `.mlapp` 负责“长什么样”
+- `controller` 负责“点了之后做什么”
+- `run_case` 负责“真正怎么算”
+
+## 4. 当前 `.mlapp` 已经具备什么
+
+根据你导出的 `edfm_simulator_app.txt`，当前 `.mlapp` 已经不是空壳，而是已经完成了较完整的绑定：
+
+- 已有 `Controller EDFMAppController`
+- 已有 `startupFcn`
+- startup 时会执行：
+
+```matlab
+app.Controller = EDFMAppController(app);
+app.Controller.startup();
+```
+
+- 顶部按钮已绑定到 controller
+- results 页按钮已绑定到 controller
+- wells 页表格增删与选中已绑定到 controller
+- 各类绘图参数变化已绑定到 controller
+
+这意味着当前开发重点不应再是“重新解释 `.m` 版怎么跑”，而应是：
+
+- 继续完善 `.mlapp` 布局
+- 保持组件名稳定
+- 在 `EDFMAppController.m` 中补逻辑
+
+## 5. App Designer 中最常见的组件
+
+下面只讲和当前 `.mlapp` 直接相关的组件。
+
+### `uidropdown`
+
+下拉框，用于：
+
+- 模板选择
+- 模型选择
+- 绘图选项选择
+
+常见属性：
+
+- `Items`
+- `Value`
+- `ValueChangedFcn`
+
+### `uibutton`
+
+按钮，用于：
+
+- 加载模板
+- 导入导出
+- 运行
+- 绘图
+- 表格行增删
+
+常见属性：
+
+- `Text`
+- `ButtonPushedFcn`
+
+### `uitable`
+
+表格控件，当前项目非常关键，尤其在 `Wells` 页。
+
+当前主要有：
+
+- `Well1Table`
+- `Well2Table`
+- `ScheduleTable`
+- `FractureWellLocationTable`
+
+常见属性：
+
+- `Data`
+- `ColumnName`
+- `RowName`
+- `ColumnEditable`
+- `CellSelectionCallback`
+
+### `uitextarea`
+
+多行文本框，当前仍大量用于输入 MATLAB 表达式，如：
+
+- 数组
+- 矩阵
+- cell
+- 边界与裂缝文本数据
+
+### `uieditfield`
+
+数值编辑框，用于：
+
+- 求解器参数
+- 初始条件
+- 部分单值参数
+
+### `uiaxes`
+
+绘图区，用于展示：
+
+- 时间步图
+- Newtons vs Time
+- 部分结果图
+
+## 6. 回调函数怎么理解
+
+回调函数就是用户操作组件时触发的函数。
+
+在当前 `.mlapp` 主线下，推荐让回调函数保持很薄，只做“转发”。
+
+例如按钮回调：
+
+```matlab
+function onRun(app, event)
+    app.Controller.runCurrentConfig();
+end
+```
+
+这种写法的好处是：
+
+- `.mlapp` 内代码简单
+- 业务逻辑集中在 controller
+- 后续换布局时不容易把逻辑打散
+
+## 7. startup 机制
+
+当前 `.mlapp` 的关键启动逻辑是：
+
+```matlab
+function startupFcn(app)
+    app.Controller = EDFMAppController(app);
+    app.Controller.startup();
+end
+```
+
+App 创建完成后，`runStartupFcn(app, @startupFcn)` 会触发这段逻辑。
+
+它的作用是：
+
+1. 给 app 挂上 controller
+2. 初始化下拉框
+3. 设置表格
+4. 加载默认模板
+5. 刷新界面
+
+如果启动后界面不正常，先查这条链路，而不是先去看求解器。
+
+## 8. 组件名为什么这么重要
+
+`EDFMAppController.m` 大量依赖组件名访问控件，例如：
+
+```matlab
+obj.App.(propName)
+```
+
+这意味着：
+
+- 组件名一旦变了
+- controller 里对应逻辑就可能失效
+
+所以在 App Designer 里改界面时，第一原则是：
+
+- 不要随意修改已有组件名
+
+如果确实要改名，必须同步修改 controller 中所有相关引用。
+
+## 9. 修改界面的正确方式
+
+## 9.1 纯布局修改
+
+如果只是改：
+
+- 位置
+- 大小
+- 标签文字
+- 页签布局
+
+那么直接在 App Designer 中改 `.mlapp` 即可。
+
+这种修改通常不需要动 controller。
+
+## 9.2 新增一个控件
+
+如果新增了一个输入控件，通常要做四件事。
+
+### 第一步：在 `.mlapp` 中添加控件
+
+例如增加：
+
+- 一个下拉框
+- 一个按钮
+- 一个数值框
+
+### 第二步：给它起稳定名字
+
+命名风格建议沿用现有项目，例如：
+
+- `MyNewDropDown`
+- `MyNewButton`
+- `MyNewEditField`
+
+### 第三步：添加回调
+
+例如按钮：
+
+```matlab
+function MyNewButtonPushed(app, event)
+    app.Controller.doSomething();
+end
+```
+
+### 第四步：在 controller 中补逻辑
+
+这是关键步骤，不要把逻辑只写在 `.mlapp` 里。
+
+## 10. 新增一个参数字段时怎么改
+
+假设新增一个参数，推荐按下面顺序。
+
+### 1. 先决定它在 `config` 中的位置
+
+例如：
+
+- `config.solver.xxx`
+- `config.wells.xxx`
+- `config.flow.multi_component.xxx`
+
+### 2. 修改默认配置
+
+编辑：
+
+- `gui_support/config/create_empty_config.m`
+
+### 3. 修改模板
+
+编辑：
+
+- `gui_support/templates/load_case_template_case01.m`
+- 其他需要的 `caseXX`
+
+### 4. 在 `.mlapp` 中增加控件
+
+并给出稳定组件名。
+
+### 5. 在 controller 中补两处
+
+必须同时补：
+
+- `refreshUIFromConfig()`
+- `pushUIToConfig()`
+
+这两个函数分别负责：
+
+- `config -> UI`
+- `UI -> config`
+
+如果只改一边，参数就会出现“显示了但不会保存”或者“保存了但不会显示”的问题。
+
+### 6. 如果运行要用到，再改 `run_case.m`
+
+只有到这一步，才去改后端运行逻辑。
+
+## 11. 如何实现一个完整功能
+
+这里给一个适用于本项目的通用开发流程。
+
+### 第一步：先明确功能边界
+
+先回答这几个问题：
+
+- 用户从哪个页面进入
+- 输入是什么
+- 点击哪个按钮
+- 结果显示在哪里
+
+### 第二步：落到统一 `config`
+
+不要直接从控件把值硬塞到求解器里，优先让它进入统一 `config`。
+
+### 第三步：补齐 UI 和 config 的双向同步
+
+需要改：
+
+- `.mlapp`
+- `refreshUIFromConfig()`
+- `pushUIToConfig()`
+
+### 第四步：补齐运行逻辑
+
+需要改：
+
+- `run_case.m`
+- 以及必要的后端函数
+
+### 第五步：补齐结果显示
+
+如果功能有结果输出，还需要改：
+
+- `refreshResults()`
+- 结果页控件
+- 可能的绘图逻辑
+
+## 12. Wells 页是当前最需要小心的地方
+
+当前 `Wells` 页已经从原来“纯文本输入”往 `uitable` 方向演进，这是比较正确的方向。
+
+开发时重点注意三件事。
+
+### 1. 表头要明确
+
+当前 controller 已统一设置这些表的 `ColumnName`。
+
+如果你在 `.mlapp` 中重建表格或改字段，记得同步更新 controller 中的表头配置。
+
+### 2. 默认行也要同步
+
+新增表格字段后，还要同步修改：
+
+- `getDefaultRowForTable()`
+
+否则新增行时默认数据长度会不匹配。
+
+### 3. 注意字符串和数值混合解析
+
+例如 `ScheduleTable` 既有：
+
+- 井名
+- `open/close`
+- `inj/pro`
+- 数值
+- 可能为空的项
+
+所以改表结构时，需要同步考虑：
+
+- `setTableValue`
+- `getTableValue`
+- `parseUITableData`
+- `parseTableCell`
+
+## 13. 开发者在 App Designer 中最常见的修改场景
+
+### 场景一：改一个按钮文字
+
+直接在 App Designer 中改 `Text` 即可。
+
+### 场景二：改布局
+
+直接在 App Designer 中调整控件位置、网格和页签。
+
+### 场景三：加一个按钮
+
+推荐做法：
+
+1. 在 `.mlapp` 里加按钮
+2. 生成回调函数
+3. 回调函数里调用 controller
+4. 在 controller 实现业务逻辑
+
+### 场景四：加一个新表字段
+
+推荐做法：
+
+1. 先改 `.mlapp` 里的表展示
+2. 再改 controller 表头
+3. 再改默认行
+4. 再改 config 和模板
+5. 最后确认后端是否需要这个字段
+
+## 14. 现在不推荐的做法
+
+以下做法不推荐继续扩大。
+
+### 1. 继续把主逻辑写回 `.m` 版老界面
+
+因为项目主线已经切到 `.mlapp`。
+
+### 2. 在 `.mlapp` 回调里直接堆业务逻辑
+
+因为这样会让界面代码越来越难维护。
+
+### 3. 改了组件名但不改 controller
+
+这会直接导致绑定失效。
+
+## 15. 当前最值得先看的文件
+
+如果你是新接手开发者，建议按下面顺序看代码。
+
+1. `gui_support/app/edfm_simulator_app.txt`
+2. `gui_support/app/EDFMAppController.m`
+3. `gui_support/config/create_empty_config.m`
+4. `gui_support/templates/load_case_template_case01.m`
+5. `gui_support/runtime/run_case.m`
+6. 对应算例目录下的 `main1.m`
+
+这个顺序能最快建立“界面字段 -> config -> 后端”的对应关系。
+
+## 16. 一句最实用的开发建议
+
+以后每次开发，都先问自己三件事：
+
+1. 这个改动在 `.mlapp` 里对应哪个组件
+2. 这个组件在 `config` 里对应哪个字段
+3. 这个字段在 `run_case` 或后端里最终去哪儿
+
+只要这三层关系始终清楚，项目就不会乱。
+

docs/软件使用手册.md

@@ -0,0 +1,459 @@
+# EDFM Simulator 软件使用手册
+
+## 1. 软件定位
+
+本软件是一个基于 MATLAB App Designer 的 EDFM 图形化模拟工具，正式界面文件为：
+
+- `gui_support/app/EDFM_Simulator_App.mlapp`
+
+当前项目已经不再以早期 `.m` 代码版界面为主线，后续使用与维护都应以 `.mlapp` 版本为准。
+
+软件的核心用途是：
+
+- 通过图形界面编辑 EDFM 模拟参数
+- 加载模板算例
+- 导入/导出配置
+- 运行模拟
+- 导入/导出结果
+- 查看基础结果和部分后处理图
+
+## 2. 运行前准备
+
+请确保：
+
+- 已安装 MATLAB
+- 工程目录完整
+- MATLAB 当前工作路径切换到工程根目录
+
+示例：
+
+```matlab
+cd('C:\Users\Administrator\Videos\3D_EDFM_simulator_20260305')
+```
+
+## 3. 推荐启动方式
+
+由于正式界面是 `.mlapp`，推荐两种启动方式。
+
+### 方式一：在 App Designer 中直接打开并运行
+
+直接打开：
+
+- `gui_support/app/EDFM_Simulator_App.mlapp`
+
+然后点击 Run。
+
+这是当前最推荐的方式。
+
+### 方式二：在 MATLAB 中直接实例化 App
+
+如果 `.mlapp` 已经在 MATLAB 路径下可见，可以在命令行中运行：
+
+```matlab
+app = EDFM_Simulator_App;
+```
+
+说明：
+
+- 根目录中的 `launch_edfm_simulator_app.m` 目前仍指向早期 `.m` 版 `EDFMSimulatorApp()`，不应再作为正式 GUI 的主入口理解。
+
+## 4. 软件整体结构
+
+界面按原始 `main1.m` 中的逻辑拆分为多个部分，并带有顶部工具栏。
+
+### 顶部工具栏
+
+主要包括：
+
+- `New Config`
+- `Template`
+- `Load Template`
+- `Import Config`
+- `Export Config`
+- `Run`
+- `Import Result`
+- `Export Result`
+- `Status`
+
+### 主页面签
+
+- `Model`
+- `Grid`
+- `Fracture`
+- `Discretization`
+- `Flow`
+- `Wells`
+- `Solover` 或 `Solver`
+- `Run`
+- `Results`
+
+不同版本导出的文字可能略有差异，但功能分组是一致的。
+
+## 5. 推荐使用流程
+
+建议按下面顺序使用。
+
+### 5.1 新建或加载配置
+
+你可以选择以下两种起点：
+
+- 点击 `New Config` 创建空配置
+- 在模板下拉框中选择 `case01` 到 `case07`，然后点击 `Load Template`
+
+如果是第一次使用，建议先加载已有模板，不建议直接从空配置开始。
+
+### 5.2 按页面修改参数
+
+#### Model 页
+
+这里主要设置：
+
+- `ModelFlag`
+- `GridModel`
+- `FlowModel`
+
+其中：
+
+- `FlowModel=1`：气水两相流
+- `FlowModel=2`：油水两相流
+- `FlowModel=3`：组分流
+
+运行时只使用当前选中的流动模型分支。
+
+#### Grid 页
+
+这里填写网格参数：
+
+- `dx`
+- `dy`
+- `dz`
+- `NTG`
+
+这类参数通常使用 MATLAB 表达式录入，例如：
+
+```matlab
+[10 10 10 10]
+```
+
+```matlab
+[5; 5; 5]
+```
+
+#### Fracture 页
+
+这里用于设置裂缝输入方式及裂缝相关参数，例如：
+
+- 输入类型
+- 裂缝工程输入
+- 裂缝线
+- 裂缝高度
+- 是否流动阻隔
+
+#### Discretization 页
+
+这里用于设置离散化参数，例如：
+
+- 边界
+- 无效层
+- 基质参数
+- 裂缝参数
+- 应力敏感参数
+
+#### Flow 页
+
+这里设置：
+
+- 初始压力
+- 初始含水饱和度
+- 初始 `Cs`
+- 初始 `Cb`
+- 与当前流动模型对应的流体参数
+
+注意：
+
+- 三种流动模型互斥
+- GUI 中虽然可能展示多个区块，但运行时只会使用当前 `FlowModel` 对应的数据
+
+#### Wells 页
+
+这是井和排产制度设置页面，当前包含四个关键表格：
+
+- `Well1Table`
+- `Well2Table`
+- `ScheduleTable`
+- `FractureWellLocationTable`
+
+同时还包括：
+
+- `time`
+- `dtmin`
+- `dtmax`
+
+### 5.3 Wells 页四个表如何填写
+
+#### 1. `Well1Table`
+
+通常用于定义常规井。
+
+当前表头含义：
+
+- `well_name`
+- `nperf`
+- `index_xyz`
+- `rw`
+- `skin`
+- `well_type`
+
+其中：
+
+- `index_xyz` 通常是网格索引，如 `[20 10 1; 20 10 2]`
+- `well_type` 对应原始代码中的井类型编号
+
+#### 2. `FractureWellLocationTable`
+
+用于定义压裂井轨迹点或井位坐标。
+
+当前表头含义：
+
+- `x`
+- `y`
+- `z`
+
+#### 3. `Well2Table`
+
+通常用于定义压裂水平井或与裂缝单元相关的井。
+
+当前表头含义：
+
+- `well_name`
+- `nperf`
+- `perfnum`
+- `rw`
+- `skin`
+- `well_type`
+
+#### 4. `ScheduleTable`
+
+用于定义井制度和阶段排产。
+
+当前表头含义：
+
+- `well_name`
+- `state(open/close)`
+- `role(inj/pro)`
+- `control(const_q/const_pwf)`
+- `target_1`
+- `target_2`
+- `Cs_key`
+- `Cs_inj`
+- `Cb_key`
+- `inj_salinity`
+
+结合原始 `main1.m` 注释，可按下面理解填写：
+
+- `state`
+  - `open`
+  - `close`
+- `role`
+  - `inj`
+  - `pro`
+- `control`
+  - `const_q`
+  - `const_pwf`
+- `target_1`
+  - 常用于输入目标流量或目标井底流压
+- `target_2`
+  - 一般与 `target_1` 成对使用
+- `Cs_inj`
+  - 注入表活剂浓度
+- `inj_salinity`
+  - 注入水或压裂液盐浓度，即矿化度
+
+### 5.4 时间步参数
+
+`Wells` 页还需要填写：
+
+- `time`
+- `dtmin`
+- `dtmax`
+
+这三个量通常按阶段一一对应。
+
+建议保证：
+
+- `time` 的阶段数
+- `dtmin` 的阶段数
+- `dtmax` 的阶段数
+- `well_schedules` 的阶段数
+
+四者保持一致。
+
+## 6. 配置导入与导出
+
+### 导出配置
+
+点击 `Export Config` 后，软件会把当前 GUI 数据整理成统一 `config` 结构，并保存为 `.mat` 文件。
+
+该 MAT 文件中应包含变量：
+
+```matlab
+config
+```
+
+### 导入配置
+
+点击 `Import Config`，选择包含 `config` 变量的 `.mat` 文件即可。
+
+## 7. 运行模拟
+
+参数设置完成后：
+
+1. 点击顶部 `Run`
+2. 或在 `Run` 页点击运行按钮
+
+运行时软件会：
+
+1. 从 `.mlapp` 控件读取参数
+2. 通过 `EDFMAppController.m` 写入统一 `config`
+3. 调用 `gui_support/runtime/run_case.m`
+4. 由 `run_case(config)` 组织网格、裂缝、流体、井和 schedule
+5. 最终调用底层求解器
+
+运行日志会显示在 `Run` 页文本框中。
+
+## 8. 查看结果
+
+运行成功后，可在 `Results` 页查看：
+
+- 结果摘要
+- 时间步信息
+- 牛顿迭代信息
+- 基础结果曲线
+
+并可调用部分旧版后处理功能，例如：
+
+- `PlotWellResponse`
+- `Plot2DLayer`
+- `Plot3DDistribution`
+- `PlotPerm`
+- `PlotSPDP`
+
+## 9. 结果导入与导出
+
+### 导出结果
+
+点击 `Export Result`，导出当前结果为 `.mat` 文件。
+
+MAT 文件中应包含变量：
+
+```matlab
+results
+```
+
+### 导入结果
+
+点击 `Import Result`，选择包含 `results` 变量的 `.mat` 文件即可。
+
+## 10. 输入格式说明
+
+当前软件中，很多复杂参数仍然采用 MATLAB 表达式方式输入。
+
+常见格式如下。
+
+### 数值
+
+```matlab
+10
+```
+
+### 向量
+
+```matlab
+[1 2 3]
+```
+
+### 列向量
+
+```matlab
+[1; 2; 3]
+```
+
+### 矩阵
+
+```matlab
+[1 2; 3 4]
+```
+
+### 单元数组
+
+```matlab
+{'w1', 1, [20 10 1], 0.089, 0, 1}
+```
+
+### 多行排产表
+
+```matlab
+{
+    'w1','open','inj','const_pwf',40,40,'Cs_inj',0.5,'Cb_inj',1;
+    'w1','open','pro','const_q',0,0,'',[],'',[]
+}
+```
+
+## 11. 使用建议
+
+建议遵循以下原则：
+
+- 优先从模板开始，而不是手工全新录入
+- 大改参数前先导出一份配置备份
+- 保证 `ScheduleTable` 井名与井定义一致
+- 保证 `time`、`dtmin`、`dtmax` 与阶段 schedule 数一致
+- 修改流体参数时，确认当前 `FlowModel` 是否正确
+
+## 12. 常见问题
+
+### 1. 为什么不建议再用 `.m` 版界面
+
+因为项目已经明确转向 App Designer 的 `.mlapp` 维护方式，`.m` 版只应视为早期过渡实现。
+
+### 2. 导入配置失败怎么办
+
+检查 `.mat` 文件中是否存在变量：
+
+```matlab
+config
+```
+
+### 3. 导入结果失败怎么办
+
+检查 `.mat` 文件中是否存在变量：
+
+```matlab
+results
+```
+
+### 4. 表格里不知道填什么
+
+建议按以下顺序判断：
+
+1. 先看表头
+2. 再看模板默认值
+3. 再看对应算例目录的 `main1.m` 注释
+
+### 5. 改了别的流动模型参数为什么不生效
+
+因为三种流动模型是互斥的，运行时只读取当前选中的 `FlowModel` 分支。
+
+## 13. 当前版本特点
+
+当前版本的重点是：
+
+- 正式界面已经放到 `.mlapp`
+- 业务逻辑主要通过 `EDFMAppController.m` 绑定
+- 运行入口已经统一为 `run_case(config)`
+
+也就是说，使用者可以把它理解为：
+
+- `.mlapp` 负责界面
+- `controller` 负责连接界面与后端
+- `run_case` 负责统一调度求解流程
+