Files
CCLite/todo.md
T
2026-07-05 16:40:18 +08:00

343 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 最小可用层。
- [ ] T0121 定义 C IPC 薄层头文件。
完成判据:声明 shared memory、event、error 和 handle 基础接口。
- [ ] T0122 实现 shared memory create/open/map。
完成判据:可创建命名共享内存并取得 payload 指针。
- [ ] T0123 实现 shared memory unmap/close。
完成判据:资源释放后同名测试可重复运行。
- [ ] T0124 实现 named event create/open。
完成判据:可创建 Windows manual-reset named event。
- [ ] T0125 实现 named event wait/signal/reset/close。
完成判据:wait 支持 timeout,signal/reset 行为可测试。
- [ ] T0126 建立 Fortran2018 IPC wrapper。
完成判据:Fortran 侧可调用 C IPC 薄层并取得状态码。
- [ ] T0127 建立 IPC 资源命名规则。
完成判据:同一 case 的 command block、data block 和 event 名称可稳定生成。
- [ ] T0128 增加 IPC 错误映射。
完成判据:create/open/map/wait 失败能转换为 CCLite 错误码。
- [ ] 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 生产后端。