zhouyilab-modules

模块组织与依赖

• 普通功能模块采用同目录、同名的 xxx.cppm 接口和 xxx.cpp 实现。接口写 export module、必要的 import、导出类型及函数声明；实现写同名 module、实现依赖和函数定义。禁止把算法、报告拼装、大型规则表全部堆进接口。
• 纯枚举/结构契约、纯重导出入口不强造空 .cpp。模板及确实需要导入者在编译期求值的 constexpr 定义可保留在接口，并说明原因；其他普通函数不要习惯性添加 constexpr。禁止接口声明 constexpr、实现单元才定义的跨模块接口。
• 公开签名直接导入其类型所属模块，必要时使用完整类型限定；不能依赖别的控制器的 using 或偶然的传递可见性。export namespace 内声明已导出，不机械重复添加 export。
• export import 只用于有意重导出的公共契约/门面；内部依赖普通 import。头文件如必须引入，应放在合法的全局模块片段，避免将标准库或第三方声明意外附着到命名模块。
• .cppm 只进入目标的一个 CXX_MODULES file set；对应 .cpp 作为普通源参与构建。拆分后核对声明、定义、调用方 import、CMake 收录和链接，避免漏编译实现或重复定义。

各层职责

层	职责	不得承担
src/common/	干支、五行、藏干、历法、时间、卦序等共用基础	流派判断、控制器依赖、报告拼装
src/<术数>/ 排盘模块	依据输入生成该术数盘局	面向某流派的取用、输出文件
analysis/*contract.cppm	请求、结果、规则依据等领域契约	运行分析、终端输出、大型实现
analysis/ 规则模块	根据排盘推演，产出结构化结论及依据	重写共用干支表、文件 I/O
*controller	校验与用例编排，选择排盘/分析入口	中文表格、JSON 字段拼装、打印
*presenter / *report	从排盘与分析结果渲染中文/结构化报告	再算一遍规则、修改原局结论
examples/、应用入口	调用控制器与展示模块、选择输出路径	定义另一套排盘/分析算法

依赖由应用和展示指向契约、分析、排盘及基础层，基础层不得反向导入高层。共享契约不得反向依赖分析器或展示实现。

拆分与设计模式

• 按稳定职责拆分原局、关系、取用/做功、岁运、应期、展示；先查找现有模块再决定新增，不能仅因文件长便切成无语义的 part1/part2。
• 流派选择采用统一门面入口加策略分派；子平与盲派各自保持契约和实现。规则执行可采用明确的分阶段流水线；静态规则适合枚举键和定义表。没有扩展需求时不要为展示设计模式堆叠虚基类、工厂和单例。
• 大契约按消费者及语义内聚性拆为子契约，再由小入口重导出；共用类型只有一个定义来源，避免循环导入和为方便复制 enum/struct。