Aethera/Project_detail_specification.md

项目细节规范

代码组织

• .hpp 只放业务契约和必要前置声明，不允许出现函数体；构造函数、薄壳函数及模板函数也只能声明。模板定义统一放对应 .ipp，非模板定义放 .cpp 或仅供头文件实例化的 .ipp。
• 嵌套 Private 在 .hpp 只写 struct Private;，完整定义、内部字段和 CRTP 定制点放在对应 .ipp。
• 派生 Private 必须继承 Prev_Private。可覆盖或必需的 CRTP 能力必须在 Private 定义处写清用途、参数、返回值、默认行为、调用时机和编译期选择优先级。
• 状态处理、算法和内部协作都实现在 Private；只有外部消费者需要的业务能力才在原始类声明薄壳，并通过 d 调用最终 Private。
• 替换实现时删除旧实现，不保留重复定义、兼容别名或转发层。

状态与接口

• 每个状态只能有一个权威来源。双缓冲交换后的当前结构就是稳定读面，跨对象直接读取该结构；禁止为无锁访问再复制一份快照、View、镜像字段或同步缓存。
• Prop 保存外部可读写的业务属性，State 保存实现向外发布的运行结果，Private 保存实现细节；三者不得互相复制并手工同步。
• 每个 Def 定义层自动以自身类型生成 Base_Tag；Prop、State、Private 分别在隔离的标签空间中复用该标签，禁止再声明 XXX_Prop_Tag、XXX_State_Tag 或 XXX_Private_Tag。
• 依赖可以选择 Prop/State 的单字段或整个 Base_Tag 层；字段写入必须同时发出字段级和所属层级变更，使用方按实际重建粒度选择一种依赖。
• 整体对象依赖只表达依赖图中的拓扑顺序，不传播 dirty；准备顺序、绘图顺序等业务含义由各自 Tag 解释。具体字段依赖才用于对应 Tag 的 dirty 传播，例如绘图缓存失效。
• Kernel Scene 只负责 2D/3D 共有的 Prepare 数据阶段；Paint、缓存失效、像素合成和异步后端提交由对应渲染模块自己的 Scene、Tag 与 Taskflow 负责。
• Root 只保存一个最终 Private 指针；Builder::build() 校验成功后创建并挂接完整 Private，Root 通过公共 Private 基类的虚析构统一释放。禁止直接公开该指针。
• 能从权威结构查询或计算的数据即时获取，不保存为成员。类只保存自身职责需要且无法推导的状态，并检查每个新增成员的读写者和生命周期。
• 公共接口只表达业务语义，不暴露 Private、内部指针、线程状态或缓冲区角色；接口保持正交，不增加空配置、未完成接口、无消费者统计或只做转发的 getter/setter。

注释与修改

• 普通字段使用对齐的同行 /* ... */ 注释，写清含义、单位、有效条件和生命周期；函数、类型及 CRTP 契约使用声明前注释。
• 审计和重命名应一次完成结构、引用、测试及文档闭环。任何 fallback 必须先写明触发条件、影响范围和验证方式，再实施。
• 修改后完整编译相关目标；需要运行程序时按 AGENTS.md 通过 CDB 执行。