programming-design-style

# 编程设计风格 ## 适用方式 - **写逻辑前**：必须先读取本 Skill 及本次适用的细则，将规范作为后续设计、编码、修改和验证的约束，然后按照规范编写逻辑。规范贯穿实现过程，不是只在写前参考一下，也不是等写完才补检查。 - **针对已有逻辑做分析、检查或巡检**：使用 [编程设计巡检](../programming-design-review/SKILL.md)。它负责审查流程和证据，复用本 Skill 的工程规则；确定要修改后，在动手前按本 Skill 执行。 两者按工作阶段分工，不重复维护规则，也不强制每次实施都生成完整巡检报告。审查本身不授权修改。用户本次范围优先；项目格式化、命名、目录和已有公开接口约定优先于通用写法，但不能以历史旁路为理由复制业务事实。 ## 核心要求 - **数据驱动**：业务状态、内容集合、资源映射、可调参数和流程组合按可扩展数据设计。新增同类内容应通过数据完成；不能擅自断定业务状态永远只有代码中的几个值。 - **唯一数据源**：每项业务事实有唯一拥有者。修改经拥有者执行并确认；前端、引擎组件和其他入口不能各存一套正式数据或只改界面就报告成功。默认保存引用键，通过统一入口访问。 - **逻辑与表现分离**：稳定逻辑拥有规则、状态和持久化，表现负责生命周期、交互和可重建展示。复用现有模块、配置、事件、工具和 API；同进程直接调用合理，不强造远程分层或多余管理器。 - **身份与缓存明确**：按引用、存档和同步需要选择稳定身份，不给所有对象加 UID；需要的内部身份由受控入口生成。缓存明确命名、来源、重建和失效责任，不能充当正式状态。 - **旧逻辑必须收尾**：同一次改动决定兼容、删除或归档，检查待退役内容的实际可恢复性和关联入口；不遗留第二套业务实现。 - **操作可追踪**：关键操作和数据变动接入统一分组日志；诊断开启后能追踪真实数据源、调用链及关键调用堆栈。多来源锁定按组和拥有者管理，每次获取独立释放。 - **改动可验证**：遵循项目代码规范，验证真实行为和失败路径，不以搜索到关键词、界面变化或写了测试代替执行证据。 ## 按触及范围读取 以下规则可同时适用。只加载本次需要的资料；同一版本已读内容复用，实施中发现新范围再补读。资料缺失时说明缺口，继续可确定的工作，不宣称完成缺失部分的检查。 | 本次触及 | 必须读取 | 重点判断 | | --- | --- | --- | | 业务状态、内容扩展、配置、身份、缓存、存档或工具保存 | [数据驱动与数据归属](references/data-ownership-and-workflows.md) | 数据定义与执行能力如何分工；谁真正读写 | | UI、引擎组件、客户端或其他表现入口 | [逻辑与表现边界](references/logic-presentation-boundaries.md) | 既有拥有者、表现职责和真实写入链路 | | 编码、重构或代码规范审查 | [代码质量基线](references/code-quality-standards.md) | 项目规则、可读性、失败处理和验证 | | 替换旧逻辑、兼容、删除或归档 | [质量基线中的退役规则](references/code-quality-standards.md#新旧逻辑归档和兼容) | 当前内容可恢复性、局部与整文件退役 | | 关键操作、数据变动、日志、输入锁、黑屏或异步锁定 | [操作日志与协作锁](references/operation-logging-and-lock-coordination.md) | 数据源和堆栈追踪、开关分组、逐次释放 | 只有核对设计来源时才读 [来源摘录](references/source-notes.md)，不把来源举例当作当前项目的强制框架。 ## 最小工作顺序 1. **改前确认**：检查目标范围及已有 diff，保护无关和用户未提交改动；沿真实调用链找数据拥有者、现有实现、数据入口及同功能旧逻辑。不能只搜当前 UI 或组件附近的代码。 2. **实施目标**：在拥有者和既有数据/工具入口上扩展，完成主流程及相关失败处理；同步处理触及的旧入口。仅整理与本次目标直接相关的代码，不顺手改造全仓。 3. **改后验证**：运行项目已有的最小相关检查，并按已加载参考中的行为验证收尾。报告改了什么、检查结果和未覆盖部分；只报告实际获得的证据。 以上是工作顺序，不是每次都要输出的表格或审批流程。小改动简短说明后执行；纯分析保持只读。 ## 何时需要比较方案 只有存在会影响模块职责、数据归属、兼容性或明显成本的未决取舍时，才比较 1–3 个合理做法，说明分工、数据与表现流、复用方式、验证和推荐。先查代码与项目资料；只有缺失决定确实改变做法时才提问。方向已明确的小改动不因“长期维护”而强制多方案、画图或反复确认。 涉及新表现入口，至少确认业务拥有者、复用入口和表现新增内容；复杂关系按需用图。复用的稳定决定按项目约定记录，不为普通改动创建额外文档、Hook 或工作流平台。 写逻辑前读取 [团队约定](references/team-design-rules.md)；同版本已读取时复用。本页与专项参考共同约束当前任务。