Instruction file imported from AntiAnimeGeneral/Ousia-OS (
.github/instructions/architecture-abstraction.instructions.md). Copyright stays with the author.
架构与抽象规范
这些规则用于实现者、架构师和 reviewer 判断模块边界、抽象层次和依赖方向是否成立。
架构边界
- 新模块、新类型和新接口应围绕“变化频率不同的东西”划边界：经常变化的部分和应保持稳定的部分要分开。
- 分层按职责和变化原因划分，不按文件大小、模板对齐或形式主义拆分。
- 高层策略不应反向依赖底层细节；跨模块协作必须经过清晰边界。
- 页面、handler、controller 应保持薄；业务编排、领域规则、数据访问和外部集成细节放到合适层承载。
- 当传输模型、领域模型、持久化模型和展示模型语义不一致时，不要强行复用同一个结构。
状态所有权
- 每个可变状态应有清晰 owner；编排者可以协调状态转移，但不应偷持有底层事实。
- 状态所有权、数据流和副作用边界应能用一句话说明。说不清时，优先修正边界而不是补注释。
- 跨模块协作时，读取、校验、转换和提交状态的职责应在边界处明确，避免多个模块各自维护同一事实。
抽象取舍
- 当抽象能澄清语义、稳定边界、隔离副作用、降低耦合、提升可测试性或减少重复决策时，应主动抽象。
- 避免空泛通用层、透传包装层、黑箱式私有框架，以及只增加名字但不保存语义的抽象。
- 增加扩展点前，先说明它允许哪类未来变化独立演进。说不出来就不要加。
- 不做为了“看起来更工程化”的轻薄包装、透传 helper 或提前抽象。只有语义确实相同、边界确实稳定、重复确实有维护成本时，才共享 helper 或增加抽象。
命名和职责
- 命名必须暴露职责和语义。
manager、handler、data、info这类模糊命名是警讯，除非它们在领域内确有精确定义。 - 公共能力按有意义的领域模块归档，不要把不相关逻辑堆进
util或helper。 - 模块职责应能用一句话说清；如果说不清，优先重构边界，不要靠注释补救。