# CCLite 0.2.x 开发计划 ## Coupling & Contact Lite for SPHLite and FEMLite **文件名**:`v2.x_development_plan.md` **适用版本**:CCLite 0.2.x **文档依据**:`01_requirements.md` 到 `06_test_and_verification_plan.md` **实现基线**:CCLite 0.1.10 主控、通信、mock worker、AoR v1 和真实 worker 能力审计 **核心目标**:基础 SPH 粒子-FEM facet penalty contact 首次实现 **第一阶段平台**:Windows / gfortran / 本机共享内存 **输入格式**:Abaqus 风格 `.inp` **编码要求**:中文,UTF-8 without BOM # 1. 文档目的 本文档定义 CCLite 0.2.x 的开发目标、版本节奏、工作包、测试算例、验收清单和风险控制。 0.2.x 的核心目标是从 0.1.x 的通信空耦合进入基础物理接触: 1. 解析 `*CCLITE SURFACE INTERACTION` 和 `*CCLITE CONTACT PAIR`; 2. 建立 SPH particle view 和 FEM facet view; 3. 实现基础几何 primitive、AABB、宽相搜索和窄相最近点; 4. 实现 SPH 粒子到 FEM 三角形 facet 的基础法向 penalty contact; 5. 支持法向阻尼的最小可用路径; 6. 将接触力写回 `CCL_TO_SPH_FORCE` 和 `CCL_TO_FEM_LOAD`; 7. 输出 contact report、force balance 和几何诊断; 8. 通过 `V020_GEOMETRY_PRIMITIVES`、`V020_SINGLE_PARTICLE_WALL` 和 `V020_MULTI_PARTICLE_PLANE`; 9. 至少完成一条单真实 worker 集成 gate,若协议 adapter 尚未完成,则必须形成明确的受控缺口报告。 0.2.x 的成功标准不是工程级接触库,而是让 CCLite 第一次具备可验证的 SPH-FEM 基础接触力闭环。 # 2. 当前基线 0.1.10 已完成: 1. CCLite 独立主控程序; 2. Windows shared memory 与 named event 薄封装; 3. command block、seq/ack、heartbeat 和 timeout; 4. data block header 与 AoR v1 record; 5. `SPH_TO_CCL_PARTICLE`、`FEM_TO_CCL_FACET`、`CCL_TO_SPH_FORCE`、`CCL_TO_FEM_LOAD` 的基础布局; 6. mock SPH/FEM worker service 模式; 7. 1 step 与 100 step 空耦合; 8. `run.log`、`ipc_report.csv`、`force_balance.csv`; 9. Python checker; 10. SPHLite/FEMLite 外部包能力审计。 当前真实 worker 状态: ```text EXTERNAL_WORKERS_READY_CCLITE_PROTOCOL_ADAPTER_REQUIRED ``` 含义是 SPHLite/FEMLite 已报告真实 IPC 能力,但 CCLite 仍需要完成协议/命名 adapter 或统一外部二进制契约,才能声明真实外部进程联调完成。 # 3. 版本边界 ## 3.1 0.2.x 必须完成 0.2.x 必须完成以下能力: 1. `*CCLITE SURFACE INTERACTION` 支持 `NORMAL=PENALTY`; 2. `*CCLITE CONTACT PAIR` 支持 `TYPE=SPH_PARTICLE_TO_FEM_FACE`; 3. CCLite case model 保存 interaction、contact pair 和接触输出配置; 4. SPH particle view 读取 `external_id`、`internal_index`、`status`、`contact_radius`、`x`、`v`; 5. FEM facet view 读取 `facet_id`、`node_count`、`node_ids`、`area`、`thickness`、`normal`、`x`、`v`; 6. 几何基础:Vec3、AABB、point-segment、point-triangle; 7. 四边形 facet 可采用拆三角形的最小实现,复杂四边形一致性补强进入 0.3.x; 8. uniform hash grid 宽相搜索; 9. SPH 粒子到 FEM facet 的候选对生成; 10. 法向间隙 `g`、穿透量 `d` 和局部法向 `n`; 11. 法向 penalty 力和基础法向阻尼; 12. FEM 节点力按 barycentric/shape weight 分配; 13. SPH force record 写回; 14. FEM nodal force load record 写回; 15. 接触数量、最大穿透、总力、总力矩和力平衡误差诊断; 16. Python checker 验证几何、接触方向和力平衡; 17. 0.2.x 验证算例进入回归集合。 ## 3.2 0.2.x 可做但不作为硬验收 以下能力可作为实现便利或实验性能力,但不得作为 0.2.x 完成定义的必要条件: 1. point-edge helper; 2. 平面四边形拆三角形接触; 3. 单真实 worker + 单 mock worker 的调试性联调; 4. 外部 worker 协议 adapter 原型; 5. 接触快照 CSV; 6. 简单性能计时。 ## 3.3 0.2.x 不完成 0.2.x 不完成以下能力: 1. Coulomb 摩擦; 2. 接触 persistence 和历史切向变量; 3. 完整 edge fallback 验收; 4. 复杂壳边缘、非平面四边形和壳厚度高级接触; 5. tied coupling 和 release; 6. pressure projection、boundary/ghost particle 和 FSI; 7. 异步子循环和强耦合迭代; 8. 自动 penalty 参数推荐; 9. SoA v2 性能布局; 10. Linux/MPI 生产后端; 11. 工程级水下爆炸或船体局部破坏算例。 # 4. 与 0.3.x 和 0.4.x 的分界 0.2.x 只做基础接触首次实现。 0.3.x 负责: 1. 壳厚度补强; 2. edge fallback 完整验收; 3. 四边形接触一致性; 4. contact persistence 初步; 5. 接触状态连续性诊断。 0.4.x 负责: 1. Coulomb 摩擦; 2. 接触历史; 3. penalty 参数估计; 4. 接触稳定时间步; 5. 接触能量耗散诊断。 0.2.x 可以保留字段和枚举,但不能把这些后续能力写成已完成。 # 5. 推荐 patch 版本节奏 0.2.x 内部 patch 版本建议如下。实际开发可合并相邻 patch,但不得跳过对应验收目标。 | 版本 | 主题 | 主要交付 | | --- | --- | --- | | 0.2.0 | 0.2.x 入口和协议前置 | 本计划、0.2 case skeleton、真实 worker protocol adapter 设计和审计 gate | | 0.2.1 | 接触输入与 case model | `SURFACE INTERACTION`、`CONTACT PAIR`、interaction/pair 校验 | | 0.2.2 | 接口 view 和 load buffer | SPH particle view、FEM facet view、非空 force/load block 写回 | | 0.2.3 | 几何 primitive | Vec3、AABB、point-segment、point-triangle、基础退化诊断 | | 0.2.4 | 宽相搜索 | uniform hash grid、candidate pair、去重和容量保护 | | 0.2.5 | 窄相接触 | gap、penetration、normal、shape weight、contact pair 输出 | | 0.2.6 | penalty force | 法向 penalty、基础阻尼、FEM 节点力分配、SPH/FEM 载荷写回 | | 0.2.7 | 诊断与 checker | contact_report.csv、force_balance.csv 增强、V020 checker | | 0.2.8 | 验证算例 | 单粒子撞面、多粒子压面、几何/搜索/力平衡回归 | | 0.2.9 | 单真实 worker gate | 至少完成一侧真实 worker 集成,或形成协议 adapter 受控缺口 | | 0.2.10 | 发布候选 | 全量 0.1.x/0.2.x 回归、文档一致性、UTF-8 without BOM 检查 | # 6. 交付物 ## 6.1 程序交付物 0.2.x 应交付: 1. `cclite.exe`,支持基础 contact run; 2. mock SPH/FEM worker,可生成可控粒子和 facet; 3. 接触算法模块; 4. 几何和搜索模块; 5. contact diagnostics; 6. Python checker; 7. 0.2.x 验证算例。 ## 6.2 源码交付物 建议新增或补强以下目录: ```text src/ geometry/ contact/ search/ transfer/ verification_support/ ``` 若不新增目录,也必须在现有模块边界中保持职责清晰: | 职责 | 建议模块 | | --- | --- | | Vec3/AABB/最近点 | `src/geometry/` | | hash grid/candidate | `src/search/` | | contact pair/penalty force | `src/contact/` | | SPH force/FEM load 写回 | `src/transfer/` | | contact report | `src/diagnostics/` | | checker | `Python/checkers/` | 0.2.x 不应把接触算法写入 SPHLite 或 FEMLite 内部。 ## 6.3 文档交付物 0.2.x 结束时应更新: 1. `README.md`; 2. `docs/03_detailed_design.md`,若模块结构或数据结构变化; 3. `docs/04_mathematical_model_and_algorithms.md`,若公式、伪代码或版本映射变化; 4. `docs/05_interface_control_document.md`,若 block 字段、record stride、命名规则或 adapter 变化; 5. `docs/06_test_and_verification_plan.md`,若新增验收算例或 checker; 6. `docs/07_real_worker_access_audit.md`,若真实 worker gate 状态变化; 7. 本开发计划; 8. `docs/0.2.x_release_notes.md`,在发布候选阶段新增。 ## 6.4 测试交付物 0.2.x 测试交付物包括: 1. 几何单元测试; 2. hash grid 单元测试; 3. contact pair 单元测试; 4. penalty force 单元测试; 5. load buffer 单元测试; 6. `V020_GEOMETRY_PRIMITIVES`; 7. `V020_SINGLE_PARTICLE_WALL`; 8. `V020_MULTI_PARTICLE_PLANE`; 9. `V020_FORCE_BALANCE`; 10. `V020_SINGLE_REAL_WORKER_SMOKE` 或受控缺口报告。 # 7. 工作包分解 ## 7.1 WP00:0.1.10 到 0.2.x 交接 目标: 确认 0.1.x 通信闭环可作为 0.2.x 开发地基,并处理真实 worker 协议前置风险。 任务: 1. 保留 `V010_EMPTY_COUPLING` 为 0.2.x 回归前置; 2. 保留 `real_worker_gap_report.json`; 3. 梳理 SPHLite/FEMLite 当前 IPC 结构、命名规则和能力查询; 4. 决定 0.2.x 是否先采用 mock worker 完成 A 层物理算法验收; 5. 若做真实 worker,先实现 CCLite 侧协议 adapter 或统一外部协议; 6. 记录 adapter 选择到 05 号文档。 完成标准: 1. 0.1.x 全量测试通过; 2. 真实 worker 状态不被误判为物理接触完成; 3. 0.2.x 的 A 层 mock 算例可独立于真实 worker 运行。 ## 7.2 WP01:接触输入与 case model 目标: 解析 0.2.x 接触输入关键词并建立内部 case model。 必须支持: ```text *CCLITE SURFACE INTERACTION, NAME=PENALTY_1 NORMAL=PENALTY, KN=..., CN=... *CCLITE CONTACT PAIR, NAME=PAIR_1 INTERFACE=... INTERACTION=... TYPE=SPH_PARTICLE_TO_FEM_FACE ``` 任务: 1. 扩展 parser 支持 interaction 和 contact pair; 2. 保存 `normal_model`、`kn`、`cn` 和 `friction` 字段; 3. 0.2.x 中若 `FRICTION` 非 0,应报错或 warning 并忽略; 4. 校验 `CONTACT PAIR` 引用的 interface 与 interaction; 5. 校验 `TYPE=SPH_PARTICLE_TO_FEM_FACE`; 6. 输出 check summary; 7. 添加非法输入测试。 完成标准: 1. 合法 contact `.inp` 可通过 `cclite check`; 2. 缺少 `KN`、非法 `NORMAL`、未知 pair 引用能给出行号和错误; 3. 0.2.x 不把摩擦写成已启用能力。 ## 7.3 WP02:SPH/FEM 接口 view 与 load buffer 目标: 把 AoR v1 payload 转成接触算法可用的只读 view,并把接触力写回 load block。 SPH particle view 至少包含: ```text external_id internal_index status contact_radius x[3] v[3] mass valid_flags ``` FEM facet view 至少包含: ```text facet_id node_count node_ids[8] area thickness normal[3] x[8,3] v[8,3] valid_flags ``` 任务: 1. 建立 SPH particle view; 2. 建立 FEM facet view; 3. 检查有效字段、非有限值、容量和 record stride; 4. 建立 SPH force accumulator; 5. 建立 FEM nodal load accumulator; 6. 写 `CCL_TO_SPH_FORCE`; 7. 写 `CCL_TO_FEM_LOAD`; 8. 对同一粒子或同一节点多条载荷做合并; 9. 输出导入/导出计数。 完成标准: 1. 空 block 仍可合法通过; 2. 固定粒子和固定 facet 可生成非空 view; 3. 非有限输入不进入接触力计算; 4. 写回 block 可由 mock worker 消费; 5. force/load record 的 step id 与 command step 匹配。 ## 7.4 WP03:几何 primitive 目标: 实现 04 号文档第 4 章要求的 0.2.x 几何基础。 任务: 1. Vec3 dot/cross/norm/normalize; 2. AABB 初始化、扩展、重叠测试; 3. SPH particle AABB; 4. FEM facet AABB; 5. point-segment closest point; 6. point-triangle closest point; 7. barycentric/shape weight; 8. point-quad split 为两个 triangle; 9. 退化边、退化三角形和非法 normal 诊断; 10. 单元测试覆盖内部、边、顶点和退化输入。 完成标准: 1. 点到三角形最近点误差在容差内; 2. barycentric 权重和为 1; 3. 退化几何不产生非有限结果; 4. `V020_GEOMETRY_PRIMITIVES` 通过。 ## 7.5 WP04:宽相搜索 目标: 实现 uniform hash grid,从 SPH particle view 和 FEM facet view 生成 candidate pair。 任务: 1. 定义 grid cell size; 2. facet AABB 插入 grid; 3. particle AABB 查询邻近 cell; 4. candidate pair 去重; 5. candidate 容量保护; 6. 输出 candidate 统计; 7. 添加小规模和边界单元测试。 完成标准: 1. 单 facet、单粒子可生成候选; 2. 不接触的远距离粒子不生成候选; 3. 跨 cell 边界的候选不漏检; 4. 重复 facet 不导致重复 candidate; 5. candidate overflow 有明确错误码。 ## 7.6 WP05:窄相 contact pair 目标: 从 candidate pair 生成真实 contact pair。 任务: 1. 对每个 candidate 计算最近点; 2. 计算局部法向; 3. 计算 gap; 4. 计算有效接触距离; 5. 计算 penetration; 6. 生成 contact pair; 7. 保存 shape weight 和 node_count; 8. 保存 contact state; 9. 记录退化和跳过原因; 10. 输出 `contact_report.csv`。 完成标准: 1. 粒子在面外无接触; 2. 粒子穿透面时生成接触; 3. 接触法向方向与设计一致; 4. `penetration = r_c - g`; 5. shape weight 可用于节点力分配; 6. 退化 facet 不产生接触力。 ## 7.7 WP06:Penalty force 与节点分配 目标: 实现基础法向 penalty damping 接触力,并写回 SPH/FEM 载荷。 0.2.x 力模型: ```text f_i = (k_n d + c_n max(0, -v_n)) n ``` FEM 节点力: ```text F_A = N_A (-f_i) ``` 任务: 1. 读取 `KN` 和 `CN`; 2. 计算 FEM 最近点速度; 3. 计算法向相对速度; 4. 计算 penalty 力; 5. 计算阻尼力; 6. 分配 FEM 节点力; 7. 合并 SPH 粒子力; 8. 合并 FEM 节点力; 9. 检查非有限力; 10. 输出力和力矩诊断。 完成标准: 1. 无穿透时接触力为 0; 2. 穿透时接触力方向正确; 3. 闭合速度时阻尼力非负; 4. 分配节点力合力等于 facet 反力; 5. SPH/FEM 总力平衡误差小于容差; 6. 非有限力被拒绝并终止当前 step。 ## 7.8 WP07:Controller 接触 run 流程 目标: 在 0.1.x step loop 中插入真实接触计算。 0.2.x run 流程: ```text for each step: send EXPORT_INTERFACE to SPH/FEM read SPH particle block read FEM facet block build interface views build broad-phase candidates run narrow-phase contact compute penalty loads write CCL_TO_SPH_FORCE write CCL_TO_FEM_LOAD send IMPORT_LOADS send ADVANCE write diagnostics ``` 任务: 1. 区分 dry-run 和 contact run; 2. contact run 要求 contact pair 已定义; 3. 每步清零 contact/force/load accumulator; 4. 读取 interface block 后执行接触; 5. 写非空 load block; 6. 调用 `IMPORT_LOADS`; 7. 记录 step 级诊断; 8. 异常时停止两个 worker 并释放资源。 完成标准: 1. 空接触 case 仍可运行; 2. 单粒子撞面 case 可产生载荷; 3. 接触算法错误不会造成 worker 残留; 4. `run.log` 可定位输入、接口、几何或力计算错误。 ## 7.9 WP08:诊断输出 目标: 形成可自动检查的接触诊断。 建议输出: ```text contact_report.csv candidate_report.csv force_balance.csv ipc_report.csv run.log verification_report.json ``` `contact_report.csv` 建议字段: ```text step_id,pair_id,sph_id,facet_id,contact_type,gap,penetration, normal_x,normal_y,normal_z,force_x,force_y,force_z,node_count ``` `force_balance.csv` 在 0.2.x 增加: ```text num_contacts,max_penetration,total_contact_force_norm, moment_balance_error,nonfinite_contact_count,skipped_degenerate_count ``` 完成标准: 1. 每个 contact step 有诊断; 2. 无接触时诊断仍写 0 值; 3. checker 可读取并判定方向、力平衡和最大穿透; 4. CSV 表头变化会触发回归失败。 ## 7.10 WP09:Python Checker 和算例生成 目标: 使用 `Python/` 支持 0.2.x 自动验收和可控算例生成。 任务: 1. 新增 `check_v020_geometry_primitives.py`; 2. 新增 `check_v020_contact.py`; 3. 新增公共 contact CSV 读取工具; 4. 可选新增 case generator; 5. 对单粒子撞面计算参考力; 6. 对多粒子压面检查总力方向和数量级; 7. 生成 `verification_report.json`; 8. 返回明确退出码。 完成标准: 1. checker 不依赖 CCLite 内部 Fortran 模块; 2. 失败报告包含 step、pair、字段和期望/实际值; 3. Python 只用于测试、算例和报告,不参与核心算法。 ## 7.11 WP10:真实 worker adapter gate 目标: 0.2.x 起逐步接入真实 SPHLite/FEMLite worker,不让 mock 算法验收掩盖真实接口问题。 任务: 1. 明确 CCLite 采用统一通用 block 还是求解器专用 adapter; 2. 为 SPHLite 建立命名/结构 adapter 或要求其支持 CCLite 通用 block; 3. 为 FEMLite 建立命名/结构 adapter 或要求其支持 CCLite 通用 block; 4. 建立单真实 worker 1 step 空耦合; 5. 建立单真实 worker 100 step 空耦合; 6. 建立真实 worker payload 读取 smoke; 7. 将 worker 能力查询写入验证报告; 8. 若无法完成,输出 `CONTROLLED_PROTOCOL_GAP`,不阻塞 A 层算法验证。 完成标准: 1. 至少一条单真实 worker 集成路径通过,或缺口清晰记录; 2. 真实 worker 数据经过与 mock 数据相同的 header 和 payload 校验; 3. 不把 `supports_real_ipc=yes` 写成真实接触物理验收完成。 # 8. 0.2.x 输入样例 ```text ** CCLite 0.2.x single particle wall contact case. *CCLITE CONTROL, NAME=V020_SINGLE_PARTICLE_WALL, MODE=RUN VERSION=0.2 *CCLITE SOLVER, ID=SPH, KIND=SPHLITE EXECUTABLE=mock_sph_worker.exe INPUT=mock_sph_contact.inp *CCLITE SOLVER, ID=FEM, KIND=FEMLITE EXECUTABLE=mock_fem_worker.exe INPUT=mock_fem_wall.inp *CCLITE IPC, TYPE=WINDOWS_SHMEM NAME_PREFIX=CCLITE_V020 BUFFER=DOUBLE TIMEOUT_MS=5000 *CCLITE TIME START=0.0 END=1.0e-6 DT=1.0e-6 *CCLITE INTERFACE, NAME=WALL_CONTACT SPH_REGION=SPH_CONTACT_REGION FEM_SURFACE=FEM_WALL *CCLITE SURFACE INTERACTION, NAME=PENALTY_1 NORMAL=PENALTY, KN=1.0e6, CN=0.0 FRICTION=0.0 *CCLITE CONTACT PAIR, NAME=PAIR_1 INTERFACE=WALL_CONTACT INTERACTION=PENALTY_1 TYPE=SPH_PARTICLE_TO_FEM_FACE *CCLITE OUTPUT DIRECTORY=output/v020_single_particle_wall CONTACT=YES IPC=YES FORCE_BALANCE=YES ``` # 9. 验证算例 ## 9.1 `V020_GEOMETRY_PRIMITIVES` 目标: 验证 Vec3、AABB、point-segment、point-triangle 和基础 point-quad split。 通过判据: 1. 最近点位置误差小于容差; 2. 权重和为 1; 3. 退化几何被拒绝; 4. 无非有限值输出。 ## 9.2 `V020_SINGLE_PARTICLE_WALL` 目标: 验证单 SPH 粒子撞 FEM 平面 facet 的接触方向和接触力。 通过判据: 1. 无穿透时接触数为 0; 2. 穿透时接触数为 1; 3. 法向方向正确; 4. 接触力大小等于 `KN * penetration`,若 `CN=0`; 5. FEM 节点力合力等于 SPH 反力; 6. force balance error 小于容差。 ## 9.3 `V020_MULTI_PARTICLE_PLANE` 目标: 验证多个 SPH 粒子同时接触同一 FEM 平面。 通过判据: 1. 接触数量等于预期; 2. 总 SPH 力与总 FEM 力平衡; 3. 最大穿透量与输入几何一致; 4. 无重复 contact pair; 5. candidate 数量可复核。 ## 9.4 `V020_FORCE_BALANCE` 目标: 专门验证力和力矩诊断。 通过判据: 1. `sum_force_sph + sum_force_fem` 小于容差; 2. 力矩误差有界且非有限计数为 0; 3. CSV 中每步都有 force balance 记录。 ## 9.5 `V020_SINGLE_REAL_WORKER_SMOKE` 目标: 验证 CCLite 与至少一个真实 worker 的 0.2.x 接口路径。 通过判据: 1. worker 能启动; 2. worker 能导出非空或可控空 interface block; 3. CCLite 能写回空或可控 load block; 4. worker 能响应 `IMPORT_LOADS`、`ADVANCE` 和 `STOP`; 5. 若协议 adapter 未完成,报告必须明确写出缺口和下一步。 # 10. 测试计划 ## 10.1 单元测试 0.2.x 单元测试至少覆盖: 1. contact keyword parser; 2. interaction/pair 引用校验; 3. Vec3; 4. AABB; 5. point-segment; 6. point-triangle; 7. barycentric weight; 8. hash grid; 9. candidate 去重; 10. contact pair; 11. penalty force; 12. FEM 节点分配; 13. force/load block 写回; 14. 非有限输入保护。 ## 10.2 接口测试 0.2.x 接口测试至少覆盖: 1. `SPH_TO_CCL_PARTICLE` 非空 payload; 2. `FEM_TO_CCL_FACET` 非空 payload; 3. `CCL_TO_SPH_FORCE` 非空 payload; 4. `CCL_TO_FEM_LOAD` 非空 payload; 5. payload record stride; 6. `valid_flags`; 7. step id 匹配; 8. capacity overflow; 9. block state 转换; 10. worker 消费非空载荷。 ## 10.3 集成测试 0.2.x 集成测试至少覆盖: 1. CCLite + 双 mock workers 单粒子撞面; 2. CCLite + 双 mock workers 多粒子压面; 3. CCLite + 单真实 SPHLite worker + mock FEM worker,若 adapter 可用; 4. CCLite + mock SPH worker + 单真实 FEMLite worker,若 adapter 可用; 5. 接触输入错误; 6. worker 超时; 7. 非有限粒子; 8. 退化 facet; 9. force balance 回归; 10. 0.1.x 空耦合回归。 # 11. 验收清单 0.2.x 发布候选必须满足: 1. 0.1.x 全量回归通过; 2. `cclite --version` 输出 0.2.x; 3. `cclite check` 支持 contact 输入; 4. 几何单元测试通过; 5. 搜索单元测试通过; 6. penalty force 单元测试通过; 7. 非空 force/load block 测试通过; 8. `V020_GEOMETRY_PRIMITIVES` 通过; 9. `V020_SINGLE_PARTICLE_WALL` 通过; 10. `V020_MULTI_PARTICLE_PLANE` 通过; 11. `V020_FORCE_BALANCE` 通过; 12. 至少一条单真实 worker gate 通过,或形成受控协议缺口报告; 13. 接触报告、力平衡报告和验证报告完整; 14. 文档与实现一致; 15. UTF-8 without BOM 检查通过; 16. 不声明摩擦、tied/release、FSI 或工程算例已完成。 # 12. 质量门禁 每个 0.2.x patch 合入前应满足: 1. 构建通过; 2. 新增算法有单元测试; 3. 0.1.x 回归不退化; 4. 新增 CSV 表头同步 checker; 5. 新增 `.inp` 样例可由 `cclite check` 解析; 6. 非有限输入有明确错误码; 7. 接触力方向有测试; 8. force balance 有测试; 9. 文档为 UTF-8 without BOM; 10. 不修改已冻结接口字段,除非同步更新 05 号文档。 # 13. 风险与对策 ## 13.1 真实 worker 协议未对齐 风险: SPHLite/FEMLite 已报告真实 IPC 能力,但二进制结构和命名规则与 CCLite 0.1.x 当前通用 block 不完全一致。 对策: 1. 0.2.x A 层算法验收继续使用 mock worker; 2. 单真实 worker gate 独立推进; 3. adapter 状态写入 `07_real_worker_access_audit.md`; 4. 不把真实 worker 缺口阻塞基础 contact 算法单元测试。 ## 13.2 接触力方向错误 风险: 法向方向、gap 符号或 SPH/FEM 反力符号错误,会导致单粒子算例看似有力但物理方向错误。 对策: 1. 单粒子撞面必须有手算参考; 2. force balance 必须检查作用-反作用; 3. contact report 输出 normal、gap、penetration 和 force; 4. 测试包含粒子在 facet 两侧的情况。 ## 13.3 退化几何导致非有限值 风险: 退化 facet、零长度边、非法 normal 会污染接触力。 对策: 1. 几何函数统一返回错误码; 2. 退化候选不产生接触力; 3. 诊断记录 skipped_degenerate_count; 4. checker 检查非有限计数为 0。 ## 13.4 penalty 参数过大导致数值不稳定 风险: 过大 `KN` 或 `CN` 可产生非有限力或过大速度增量。 对策: 1. 0.2.x 先使用手算小算例; 2. 检查力是否有限; 3. 输出最大接触力和最大穿透; 4. 自动 penalty 参数和稳定时间步放入 0.4.x。 ## 13.5 范围膨胀 风险: 过早加入摩擦、tie、FSI、工程算例会拖慢基础 contact 验收。 对策: 1. 0.2.x 只做基础法向 penalty contact; 2. 摩擦字段可解析但不启用; 3. tie 和 FSI 只保留接口字段; 4. 工程算例进入 0.9.x。 # 14. Backlog 以下事项不进入 0.2.x 硬验收: 1. 完整 edge fallback; 2. 四边形双线性投影; 3. 壳厚度高级几何; 4. contact persistence; 5. Coulomb 摩擦; 6. 自动 penalty 参数; 7. 接触稳定时间步; 8. 接触能量诊断; 9. tied/release; 10. pressure projection; 11. boundary/ghost particle; 12. Riemann FSI; 13. SoA v2; 14. Linux/MPI; 15. 工程简化算例。 # 15. 完成定义 CCLite 0.2.x 完成的定义: 1. CCLite 保持独立主控程序身份; 2. 0.1.x 通信和空耦合能力不退化; 3. CCLite `.inp` 可定义基础 penalty contact; 4. SPH particle view 和 FEM facet view 可参与接触计算; 5. 几何 primitive、宽相搜索和窄相检测通过单元测试; 6. 单粒子撞面能产生方向正确的接触力; 7. 多粒子压面能产生可复核的总力; 8. SPH/FEM 作用-反作用误差可控; 9. `CCL_TO_SPH_FORCE` 和 `CCL_TO_FEM_LOAD` 可写入非空载荷; 10. contact report 和 force balance 可由 checker 自动验收; 11. 至少一个真实 worker 集成路径完成或形成明确协议缺口; 12. 0.2.x 不宣称摩擦、tied/release、FSI 或工程级应用完成。 0.2.x 的成功标准是一条从界面数据、几何搜索、接触力计算、载荷写回到自动验收的最小物理闭环。该闭环稳定后,0.3.x 才适合继续处理壳、边缘、四边形和接触连续性。