<!-- 同步影响报告 ================ 版本更改: 初始版本 → 1.0.0 修改的原则: N/A（首次创建） 添加的部分: - 核心原则（I-VI） - 技术约束 - 开发工作流程 - 治理 需要更新的模板: ✅ .specify/templates/plan-template.md - 已验证章程检查部分一致 ✅ .specify/templates/spec-template.md - 已验证功能需求与原则对齐 ✅ .specify/templates/tasks-template.md - 已验证任务分类反映原则 ✅ CODEBUDDY.md - 项目指导文档，版本号约定已同步 后续 TODO: 无 -->

深蓝词库转换项目章程

核心原则

I. 测试优先与质量保证

不可协商的测试要求：

• 每个功能必须有对应的集成测试，验证完整的用户场景
• 整体代码单元测试(Unit Test)覆盖度必须达到60%以上
• TDD工作流：编写测试 → 测试失败(红) → 实现功能 → 测试通过(绿) → 重构(重构)
• 测试文件命名规范：*Test.csproj，测试类命名：[TestedClass]Test
• 禁止合并未通过测试的代码

理由：输入法词库转换涉及多种格式和编码，错误转换会导致数据丢失或损坏。高覆盖率的测试是保证质量的基础。

II. 中文注释与文档化

文档要求：

• 所有公共类、方法、属性必须有中文XML文档注释
• 复杂算法和业务逻辑必须有中文行内注释说明
• 非显而易见的代码块需要注释解释"为什么"而不仅是"是什么"
• README文档必须包含：功能描述、使用方法、支持的输入法列表、编译指南
• 每个词库格式转换器需要在Wiki中有详细文档

理由：项目主要服务中文用户，中文注释降低理解门槛。词库格式复杂多样，详细文档对维护和扩展至关重要。

III. C#编码规范遵循

编码标准：

• 遵循Microsoft C# Coding Conventions
• 使用PascalCase命名类、方法、属性；camelCase命名私有字段和局部变量
• 私有字段使用下划线前缀（如_fieldName）
• 每个文件一个类（除内部类外）
• 方法长度不超过50行，复杂度不超过10
• 使用有意义的命名，避免缩写（除广泛认知的如IME、ID、URL）
• 优先使用LINQ和现代C#特性（如模式匹配、表达式体成员）

理由：统一的编码规范提高代码可读性和可维护性，降低团队协作成本。

IV. 跨平台兼容性

平台支持：

• 核心库(ImeWlConverterCore)必须支持：.NET 8.0、.NET Framework 4.6
• CLI工具(ImeWlConverterCmd)支持：Windows、Linux、macOS
• GUI工具：Windows(WinForms)、macOS(原生)
• 禁止使用平台特定API，除非有明确的平台抽象层
• 文件路径处理必须使用Path.Combine和Path.DirectorySeparatorChar
• 字符编码处理必须明确指定（UTF-8、GBK等）

理由：不同平台用户需求不同，跨平台支持扩大用户基础，是项目核心价值之一。

V. 版本控制与自动化发布

版本管理规则：

• 版本号由MinVer从Git tag自动生成，格式：vX.Y.Z
• 禁止手动修改：ConstantString.cs中的VERSION字段、.csproj中的<Version>标签
• 遵循语义化版本规范(Semantic Versioning)：
  • MAJOR：不兼容的API变更
  • MINOR：向后兼容的功能新增
  • PATCH：向后兼容的问题修正
• 发布新版本：创建并推送Git tag，GitHub Actions自动构建和发布
• 非Git环境构建：使用环境变量PACKAGE_VERSION指定版本号

理由：自动化版本管理消除人为错误，简化发布流程，确保版本号一致性。详见RELEASING.md。

VI. 模块化与可扩展性

架构原则：

• 核心转换逻辑独立于UI层
• 每种输入法格式一个独立的转换器类，实现统一接口
• 使用工厂模式或服务定位器管理转换器实例
• 新增输入法支持不应修改现有转换器代码（开闭原则）
• 避免静态类和全局状态，使用依赖注入

理由：输入法格式众多且持续新增，模块化设计降低变更风险，提高扩展效率。

技术约束

语言与框架

• 主语言：C#
• 核心框架：.NET 8.0（新代码）、.NET Framework 4.6（兼容性）
• 测试框架：xUnit或NUnit
• 代码覆盖率工具：Coverlet + ReportGenerator

性能要求

• 单个词库文件（<10MB）转换时间 <5秒
• 批量转换支持并行处理
• 内存占用：单文件转换 <100MB

安全与编码

• 所有外部输入必须验证（文件格式、编码、大小）
• 禁止执行任意代码或脚本
• 敏感错误信息不暴露给最终用户

开发工作流程

代码审查

• 所有PR必须经过至少一位核心维护者审查
• 审查检查点：
  • 测试覆盖率是否达标（60%+）
  • 是否有集成测试验证新功能
  • 中文注释是否完整
  • 是否遵循C#编码规范
  • 跨平台兼容性是否验证

测试门禁

• 所有单元测试必须通过
• 集成测试必须通过
• 代码覆盖率不得下降
• 静态代码分析无高危警告

提交规范

• 提交信息格式：<type>(<scope>): <subject>
  • type: feat, fix, docs, test, refactor, style, chore
  • scope: 影响的模块或输入法名称
  • subject: 简短描述（中文或英文）
• 示例：feat(sougou): 添加搜狗五笔词库支持

治理

章程优先级

本章程优先于所有其他开发实践和个人偏好。所有PR和代码审查必须验证是否符合章程要求。

修正程序

修改本章程需要：

1. 提出修正提案（Issue或PR）
2. 核心维护者讨论并投票（需2/3同意）
3. 更新章程文档并递增版本号
4. 更新相关模板和指导文档
5. 通知所有贡献者

复杂性豁免

如需违反"VI. 模块化与可扩展性"或其他原则，必须：

• 在设计文档中明确说明理由
• 证明更简单的方案为何不适用
• 获得至少一位核心维护者批准

合规审查

• 每月审查一次测试覆盖率报告
• 季度审查代码质量指标（圈复杂度、重复率）
• 重大功能发布前进行全面合规检查

运行时指导

日常开发请参考：

• CODEBUDDY.md - 项目级指导文档
• RELEASING.md - 版本发布流程
• .specify/templates/ - 规范和计划模板

版本: 1.0.0 | 批准日期: 2026-01-25 | 最后修正: 2026-01-25