# CCLite 0.1.x 待办事项 ## Coupling & Contact Lite for SPHLite and FEMLite **依据**:`docs/v1.x_development_plan.md` **适用范围**:CCLite 0.1.x **目标**:完成主控、通信、worker、mock、空耦合、诊断和自动验收闭环。 **不包含**:真实 SPH-FEM 接触力、单粒子撞面物理验收、摩擦、FSI、Linux/MPI 生产实现、SoA v2。 # 1. 任务颗粒度约定 每个待办事项应满足: 1. 可以由一个小 patch 独立完成; 2. 有明确输入、输出或可观察行为; 3. 有最小测试或检查方式; 4. 不跨越多个架构层大改; 5. 完成后能让项目更接近 `V010_EMPTY_COUPLING`。 状态标记: ```text [ ] 未开始 [~] 进行中 [x] 已完成 [!] 阻塞 ``` # 2. 0.1.0 工程骨架 目标:建立可编译工程、程序入口和最小 smoke。 - [x] T0101 建立 `src/`、`include/`、`tests/`、`cases/`、`Python/` 基础目录。 完成判据:目录结构与开发计划一致,空目录有占位说明或后续构建可识别。 - [x] T0102 建立 Windows/gfortran 构建入口。 完成判据:可构建至少一个 `cclite` 空程序目标。 - [x] T0103 增加 CCLite 版本模块。 完成判据:程序能输出 `0.1.0` 版本号和构建平台信息。 - [x] T0104 增加主程序 CLI 骨架。 完成判据:支持 `--help`、`--version`、`check`、`dry-run`、`run` 命令入口。 - [x] T0105 增加基础错误码模块。 完成判据:输入错误、IPC 错误、worker 错误、系统错误有独立范围。 - [x] T0106 增加基础日志模块。 完成判据:能写 `run.log`,包含时间、级别、模块名和消息。 - [x] T0107 建立空 mock worker 构建目标。 完成判据:`mock_sph_worker` 和 `mock_fem_worker` 可启动并输出自身身份。 - [x] T0108 增加工程 smoke 测试。 完成判据:测试能检查 `cclite --version`、`cclite --help` 和两个 mock worker 启动。 # 3. 0.1.1 `.inp` 与 Case Model 目标:支持 CCLite 主控输入和 check 模式。 - [x] T0111 定义 `CCL_Case` 数据结构。 完成判据:可保存 control、solver、ipc、time、interface、output 配置。 - [x] T0112 实现关键词行解析。 完成判据:支持 `*CCLITE ...` 关键词、大小写兼容、注释和空行。 - [x] T0113 实现参数键值解析。 完成判据:支持 `KEY=VALUE`、字符串路径、数值和布尔值。 - [x] T0114 解析 `*CCLITE CONTROL` 和运行模式。 完成判据:能识别 `check`、`dry-run`、`run`,非法模式报错。 - [x] T0115 解析 `*CCLITE SOLVER`。 完成判据:能保存 SPH/FEM solver id、kind、executable 和 input 文件。 - [x] T0116 解析 `*CCLITE IPC`。 完成判据:0.1.x 只接受 `TYPE=WINDOWS_SHMEM`,其他类型给出预留或不支持错误。 - [x] T0117 解析 `*CCLITE TIME`、`*CCLITE INTERFACE` 和 `*CCLITE OUTPUT`。 完成判据:能保存时间范围、dt、region/surface 映射和输出目录。 - [x] T0118 实现 case 校验。 完成判据:缺失 solver、缺失 IPC、非法时间步、缺失输出目录均能定位到关键词。 - [x] T0119 实现 `cclite check`。 完成判据:合法输入输出检查摘要,非法输入返回非零错误码。 - [x] T0120 增加 `.inp` parser 单元测试。 完成判据:覆盖合法输入、未知关键词、缺失字段、非法 IPC 和大小写兼容。 # 4. 0.1.2 IPC 基础 目标:完成 Windows shared memory 和 named event 最小可用层。 - [x] T0121 定义 C IPC 薄层头文件。 完成判据:声明 shared memory、event、error 和 handle 基础接口。 - [x] T0122 实现 shared memory create/open/map。 完成判据:可创建命名共享内存并取得 payload 指针。 - [x] T0123 实现 shared memory unmap/close。 完成判据:资源释放后同名测试可重复运行。 - [x] T0124 实现 named event create/open。 完成判据:可创建 Windows manual-reset named event。 - [x] T0125 实现 named event wait/signal/reset/close。 完成判据:wait 支持 timeout,signal/reset 行为可测试。 - [x] T0126 建立 Fortran2018 IPC wrapper。 完成判据:Fortran 侧可调用 C IPC 薄层并取得状态码。 - [x] T0127 建立 IPC 资源命名规则。 完成判据:同一 case 的 command block、data block 和 event 名称可稳定生成。 - [x] T0128 增加 IPC 错误映射。 完成判据:create/open/map/wait 失败能转换为 CCLite 错误码。 - [x] T0129 增加 IPC 接口测试。 完成判据:覆盖 shared memory 生命周期、event wait/signal/reset、timeout 和重复释放。 # 5. 0.1.3 Command Block 与 Worker 协议 目标:实现命令共享块、seq/ack 和 worker 状态机基础。 - [ ] T0131 定义 command id 枚举。 完成判据:支持 `INIT`、`READ_INPUT`、`BUILD_MODEL`、`EXPORT_INTERFACE`、`ADVANCE`、`WRITE_OUTPUT`、`STOP`。 - [ ] T0132 定义 worker state 枚举。 完成判据:支持 `STARTING`、`READY`、`BUSY`、`DONE`、`ERROR`、`STOPPED`。 - [ ] T0133 定义 command block 逻辑类型。 完成判据:字段覆盖 05 号文档要求,`substep_id` 和 `iteration_id` 在 0.1.x 写 0。 - [ ] T0134 实现 command block pack/unpack。 完成判据:二进制布局可稳定写入共享内存并读回。 - [ ] T0135 实现 magic/version/layout 校验。 完成判据:非法 magic、ABI 或 layout id 能在初始化阶段拒绝。 - [ ] T0136 实现 command seq/ack 配对。 完成判据:每条命令都有递增 seq,worker 回写对应 ack。 - [ ] T0137 实现 heartbeat 更新。 完成判据:worker 空闲或执行命令时能更新 `heartbeat_seq`。 - [ ] T0138 实现 command timeout 检测。 完成判据:worker 不响应时 CCLite 返回超时错误,不永久等待。 - [ ] T0139 增加 command block 单元测试。 完成判据:覆盖字段读写、seq/ack、版本校验、非法状态和 timeout。 # 6. 0.1.4 Data Block 与 AoR v1 目标:实现 data block header、block role 和基础 AoR v1 payload。 - [ ] T0141 定义 data block header。 完成判据:包含 magic、version、role、layout、record size、count、capacity、state 和 step id。 - [ ] T0142 定义 block role 枚举。 完成判据:支持 `SPH_TO_CCL_PARTICLE`、`FEM_TO_CCL_FACET`、`CCL_DIAGNOSTIC`、`CCL_COMMAND_SPH`、`CCL_COMMAND_FEM`。 - [ ] T0143 定义 buffer state。 完成判据:支持 empty、writing、ready、reading、error 状态转换。 - [ ] T0144 实现 header pack/unpack。 完成判据:共享内存中 header 可由 CCLite 和 worker 双向读写。 - [ ] T0145 实现 header 校验。 完成判据:非法 role、record size、count 超限和 payload bytes 超限可被拒绝。 - [ ] T0146 定义 SPH particle AoR v1 record。 完成判据:字段覆盖 id、index、position、velocity、mass、density、h、radius、pressure、sound speed 和 flags。 - [ ] T0147 定义 FEM facet AoR v1 record。 完成判据:字段覆盖 facet id、surface id、node ids、coords、velocity、normal、area、thickness、mass per area 和 flags。 - [ ] T0148 定义空载荷 record 预留。 完成判据:0.1.x 可创建 `CCL_TO_SPH_FORCE` 和 `CCL_TO_FEM_LOAD` 空 block。 - [ ] T0149 增加 data block 单元测试。 完成判据:覆盖空 payload、固定 record、最大 capacity、bad header 和 bad count。 # 7. 0.1.5 Controller 空耦合 目标:跑通 CCLite + 双 mock worker 的三进程空耦合。 - [ ] T0151 实现 worker 进程描述结构。 完成判据:可保存 executable、input、solver id、ipc 名称、状态和进程句柄。 - [ ] T0152 实现 worker 启动器。 完成判据:CCLite 可启动 mock SPH/FEM worker,并记录启动命令。 - [ ] T0153 实现 worker 停止和退出监控。 完成判据:正常 STOP 和异常退出都能被 CCLite 识别。 - [ ] T0154 实现 mock worker IPC attach。 完成判据:mock worker 可打开 command block、data block 和 named event。 - [ ] T0155 实现 mock worker 命令循环。 完成判据:mock worker 可响应 0.1.x 必需命令并回写 ack。 - [ ] T0156 实现 mock SPH 固定粒子导出。 完成判据:可按配置导出 0 个或少量固定 SPH record。 - [ ] T0157 实现 mock FEM 固定 facet 导出。 完成判据:可按配置导出 0 个或少量固定 FEM facet record。 - [ ] T0158 实现 CCLite dry-run step loop。 完成判据:CCLite 可执行 export、读 header、写空载荷、advance、diagnostics。 - [ ] T0159 实现 1 step 空耦合集成测试。 完成判据:双 mock worker 完成 1 step 并正常退出。 - [ ] T0160 实现 100 step 空耦合集成测试。 完成判据:双 mock worker 完成 100 step,无 timeout,无残留进程。 # 8. 0.1.6 诊断与 Python Checker 目标:形成可自动判定的 `V010_EMPTY_COUPLING` 验证闭环。 - [ ] T0161 实现 `run.log` 标准输出。 完成判据:记录版本、输入、worker 命令、IPC 名称、错误码和资源释放。 - [ ] T0162 实现 `ipc_report.csv`。 完成判据:每步输出 solver id、command id、seq、ack、worker state、heartbeat、elapsed 和 error。 - [ ] T0163 实现 `force_balance.csv`。 完成判据:0.1.x 空耦合每步输出 SPH/FEM 总力为 0。 - [ ] T0164 建立 `Python/checkers/`。 完成判据:目录中有 checker 入口和公共 CSV 读取工具。 - [ ] T0165 定义 `verification_report.json` schema。 完成判据:包含 case id、status、metrics、failed checks、输入和输出文件。 - [ ] T0166 实现 `V010_EMPTY_COUPLING` checker。 完成判据:检查 seq/ack、step id、timeout、worker state、空载荷和退出状态。 - [ ] T0167 建立 `cases/v0_1_ipc_empty_coupling/`。 完成判据:包含 CCLite `.inp`、mock 输入说明和预期输出说明。 - [ ] T0168 集成 checker 到本地测试命令。 完成判据:运行测试后自动生成 `verification_report.json`。 - [ ] T0169 增加诊断回归测试。 完成判据:CSV 表头变化或关键字段缺失会导致测试失败。 # 9. 0.1.7 真实 Worker 最小接入 目标:在不破坏 SPHLite/FEMLite 独立运行的前提下,定义或实现最小 worker/service handshake。 - [ ] T0171 确认 SPHLite worker 接入方式。 完成判据:明确是修改 SPHLite 入口、增加包装程序,还是暂以接入缺口记录。 - [ ] T0172 确认 FEMLite worker 接入方式。 完成判据:明确是修改 FEMLite 入口、增加包装程序,还是暂以接入缺口记录。 - [ ] T0173 固化 worker 启动参数。 完成判据:SPHLite/FEMLite 采用一致的 `--cclite-worker` 参数约定。 - [ ] T0174 实现或记录 SPHLite handshake。 完成判据:SPHLite worker 能进入 `READY`,或形成明确缺口说明。 - [ ] T0175 实现或记录 FEMLite handshake。 完成判据:FEMLite worker 能进入 `READY`,或形成明确缺口说明。 - [ ] T0176 验证 SPHLite 空接口导出。 完成判据:真实或包装 worker 可导出空 particle block。 - [ ] T0177 验证 FEMLite 空接口导出。 完成判据:真实或包装 worker 可导出空 facet block。 - [ ] T0178 验证真实 worker 空载荷接收。 完成判据:worker 能接受空 force/load block,不报物理算法错误。 - [ ] T0179 执行单真实 worker 集成 smoke。 完成判据:CCLite + 一个真实 worker + 一个 mock worker 可完成最小 dry-run,或输出受控缺口报告。 # 10. 0.1.8 发布候选 目标:冻结 0.1.x 通信闭环,准备进入 0.2.x 接触算法开发。 - [ ] T0181 执行全量 0.1.x 单元测试。 完成判据:`.inp`、command block、data block、错误码和 CSV writer 测试通过。 - [ ] T0182 执行全量 0.1.x 接口测试。 完成判据:shared memory、named event、timeout、bad header 和 bad layout 测试通过。 - [ ] T0183 执行全量 0.1.x 集成测试。 完成判据:双 mock workers 1 step 和 100 step 空耦合通过。 - [ ] T0184 执行 `V010_EMPTY_COUPLING` 验证算例。 完成判据:Python checker 生成通过报告。 - [ ] T0185 执行干净环境重建。 完成判据:从干净目录构建、运行 smoke 和 V010 均通过。 - [ ] T0186 检查 UTF-8 without BOM。 完成判据:新增文档和 `.inp` 样例均无 BOM。 - [ ] T0187 检查文档一致性。 完成判据:README、03、05、06 和开发计划与实现字段、命令、输出一致。 - [ ] T0188 冻结 0.1.x 接口常量。 完成判据:command id、worker state、block role、layout id、CSV 表头有记录。 - [ ] T0189 整理 0.1.x release notes。 完成判据:列出已完成能力、未完成能力、真实 worker 接入状态和 0.2.x 入口条件。 # 11. 0.1.x 总体验收清单 - [ ] A001 `cclite.exe` 可作为独立主控程序启动。 - [ ] A002 `mock_sph_worker` 和 `mock_fem_worker` 可由 CCLite 启动。 - [ ] A003 CCLite 可创建和释放 Windows shared memory。 - [ ] A004 CCLite 可创建和释放 Windows manual-reset named event。 - [ ] A005 Command block seq/ack 在 100 step 中全部匹配。 - [ ] A006 Data block header 校验覆盖正常和异常路径。 - [ ] A007 AoR v1 空 payload 和固定 payload 均可处理。 - [ ] A008 `cclite check` 可检查合法和非法 `.inp`。 - [ ] A009 `cclite dry-run` 可完成双 mock 空耦合。 - [ ] A010 `run.log`、`ipc_report.csv`、`force_balance.csv` 均生成。 - [ ] A011 Python checker 可生成 `verification_report.json`。 - [ ] A012 `V010_EMPTY_COUPLING` 自动检查通过。 - [ ] A013 Linux/MPI 配置只给出预留或不支持提示。 - [ ] A014 0.1.x 不宣称真实 SPH-FEM 接触力已完成。 - [ ] A015 0.2.x 可在该基础上进入基础 penalty contact 开发。 # 12. 暂不进入 0.1.x 的事项 以下事项进入 backlog,不作为 0.1.x 待办: - [ ] B001 单粒子撞刚性面物理验收。 - [ ] B002 点到三角形和点到四边形几何验证。 - [ ] B003 基础 penalty contact 力计算。 - [ ] B004 壳厚度、边缘 fallback 和接触 persistence。 - [ ] B005 Coulomb 摩擦和接触能量耗散。 - [ ] B006 tied coupling 和 release。 - [ ] B007 pressure projection 和 boundary/ghost particle。 - [ ] B008 Riemann FSI。 - [ ] B009 SoA v2 性能优化。 - [ ] B010 Linux/MPI 生产后端。