本文档是 eWorkHelper 后续开发的先决条件。所有功能开发、修改、重构与修复均应遵守本约束。
以下能力已经人工验证通过，后续开发不得无故破坏：
- Visual Studio 使用 F5 可正常启动 Excel。
- eWorkHelper VSTO Add-in 可正常加载。
- 自定义 Ribbon 可正常显示。
- 正式 Ribbon 按钮事件链路可正常触发。
如后续修改影响上述任一能力，必须在交付前重新验证。
任何开发必须遵循：
- 先读取现有代码、项目结构和
/docs文档。 - 明确需求、影响范围、实现方案和风险。
- 必要时先补充开发/设计记录。
- 再修改代码。
- 完成后执行编译、调试或其他可行验证。
- 最后更新开发记录和遗留问题。
禁止未分析现状就直接进行大范围修改。
- 优先基于现有架构扩展，不无故重构。
- 只修改当前需求直接相关内容。
- 优先简单、明确、可维护的实现，禁止过度设计。
- 新增功能尽量独立，避免不必要的全局耦合。
- 优先使用现有 .NET Framework、VSTO、Excel Object Model 和已有依赖。
- 没有明确必要性时，不新增第三方依赖。
- 类、方法、变量必须使用有实际含义的命名。
- 一个方法只承担一个明确职责，避免超长方法。
- 公共逻辑合理复用，但禁止为了抽象而抽象。
- 禁止空
catch或吞掉异常。 - 禁止用大量
try-catch掩盖真实逻辑问题。 - 禁止保留废弃代码、大段注释代码、临时调试代码。
- 注释主要说明“为什么”，不要重复代码已经表达的内容。
- 优先遵循 VSTO 原生生命周期和 Excel Object Model。
- 不自行创建额外 Excel 进程代替 VSTO 宿主或调试机制。
- 避免无意义地长期持有 Excel COM 对象。
- 禁止在 UI 主线程执行明显耗时操作导致 Excel 长时间无响应。
- Ribbon、ThisAddIn、窗体与业务逻辑尽量职责分离。
- 不得无故破坏当前已经验证成功的 F5 调试链路。
- 修改工作簿、工作表或单元格时必须明确操作对象，禁止默认修改用户未指定的数据。
除非需求明确要求，否则禁止：
- 更换项目类型、目标框架或核心技术栈。
- 大规模重构项目结构。
- 修改与当前任务无关的代码。
- 引入新的 UI、DI、日志或配置框架。
- 使用硬编码用户名、机器名、本地路径等环境专属配置。
- 在代码中保存密码、密钥、Token 等敏感信息。
- 在文件内容、文件名、目录名、示例、日志或 Git 历史中保留个人、公司、客户或内部环境信息。
- 在 Git 初始化、Commit、Push、Merge、Tag 或 Release 前跳过敏感信息检查。
- 通过删除已有功能规避 Bug。
- 为了编译通过而屏蔽错误、吞异常或降低需求。
- 未完成验证就声明功能成功。
- 擅自修改已经确认的功能名称、交互方式或业务规则。
每次开发完成后至少记录：
- 本次需求。
- 修改文件。
- 关键实现方式。
- 编译/调试结果。
- 未验证项。
- 已知问题或后续事项。
代码行为发生变化时，相关文档必须同步更新。
任务只有同时满足以下条件才视为完成：
- 需求完整实现。
- 项目可以正常编译。
- 没有引入明显错误或无关改动。
- 可自动验证的内容已经验证。
- 无法自动验证的内容明确标记为“待人工验证”。
- 开发记录已经同步更新。
核心原则：先理解，后修改；只改必要内容；不隐藏问题；完成即验证；代码与文档保持一致。