---
name: zhouyilab-modules
description: 在 ZhouYiLab 新增或重构 C++23 模块、分析入口与公共契约时规范分层、依赖和 cppm/cpp 组织。
---

## 模块组织与依赖

- 普通功能模块采用同目录、同名的 `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。