diff --git a/dev_scripts/check_harness.py b/dev_scripts/check_harness.py index bd2c588..6b237a7 100644 --- a/dev_scripts/check_harness.py +++ b/dev_scripts/check_harness.py @@ -91,6 +91,7 @@ CORE_DOCUMENT_REQUIREMENTS = { "docs/07-new-project-documentation-setup.md": ( "## 初始化顺序", "### 2. 选择建设基线", + "#### 判断案例", "### 3. 识别子项目与交付单元", "### 7. 确定交付对象和文档", "## 完成标准", diff --git a/docs/07-new-project-documentation-setup.md b/docs/07-new-project-documentation-setup.md index fe82bc5..e6d8c10 100644 --- a/docs/07-new-project-documentation-setup.md +++ b/docs/07-new-project-documentation-setup.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki,禁止直接编辑本文件) wiki_page: New-Project-Documentation-Setup wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/New-Project-Documentation-Setup.- -wiki_revision: 0d603f4d71a28c3de346b30dc3f450f7917c50e9 -synchronized_at: 2026-08-16T11:29:05Z +wiki_revision: 864d81b515b420d17fa4ff0fc7f528109b1a3d99 +synchronized_at: 2026-08-16T11:38:04Z # 新项目文档初始化 @@ -44,6 +44,44 @@ synchronized_at: 2026-08-16T11:29:05Z 采用开源基线时,在 Project-Profile 的“技术栈与运行环境”记录上游项目名称、仓库地址、基线版本或提交、许可证、保留能力、定制范围和上游升级策略。尚未确认的候选和取舍先写入首个技术方案工单,不得把假设写成项目事实。 +#### 判断案例 + +以下案例用于说明判断方式,不代表必须选择某种技术或具体开源项目。 + +##### 案例一:适合基于成熟项目二次开发 + +计划开发企业内部管理系统。候选项目已经具备用户、权限、审计日志、基础数据管理和自动化测试;功能与目标架构基本匹配,许可证允许预期使用,项目持续维护,发布与升级流程完整,预计只需修改业务模块和界面。 + +- 结论:优先基于该项目二次开发。 +- 原因:可以减少通用功能的开发和验证成本,定制范围可控。 +- 记录:上游仓库、基线版本、许可证、保留功能、定制模块和上游升级方式。 + +##### 案例二:项目成熟但许可证不兼容 + +候选项目功能完整、维护活跃、文档充分,但许可证与当前产品的闭源分发、商业模式或交付条件不兼容。 + +- 结论:不采用该项目作为建设基线。 +- 原因:技术成熟度不能消除许可证风险;不确定结论必须交由负责人或法律专业人员确认。 +- 记录:候选项目、许可证限制、确认人员和排除原因。 + +##### 案例三:功能相似但改造成本过高 + +候选项目表面上覆盖大部分功能,但数据模型、权限体系和部署结构与目标项目差异很大,需要大量删除模块、重写主要接口,并长期维护上游冲突。 + +- 结论:不直接基于完整项目二次开发,可以评估只复用合适的组件或设计思路。 +- 原因:二次开发的总成本、理解成本和长期维护风险已经高于自主实现核心业务。 +- 记录:主要结构差异、改造估算、长期维护风险和最终选择。 + +##### 案例四:只复用成熟框架或组件 + +没有功能高度匹配的完整开源产品,但存在成熟的应用框架、更新组件、日志组件或通信库。 + +- 结论:从零开发业务功能,同时复用经过评估的成熟框架或组件。 +- 原因:复用基础能力不等于必须采用完整产品,可以避免被不匹配的业务架构绑定。 +- 记录:每个依赖的用途、版本、许可证、安全边界、升级方式和可替换方案。 + +每个案例的实际评估都必须记录候选项目、判断依据、最终选择、未采用原因,以及升级或退出方式。 + ### 3. 识别子项目与交付单元 先判断仓库中有几个应用、服务、客户端、库或其他可独立交付的部分。对每个部分确认: diff --git a/tests/test_harness_docs.py b/tests/test_harness_docs.py index 272fb84..79c3864 100644 --- a/tests/test_harness_docs.py +++ b/tests/test_harness_docs.py @@ -63,6 +63,7 @@ class CoreDocumentTests(unittest.TestCase): "docs/07-new-project-documentation-setup.md" ] self.assertIn("### 2. 选择建设基线", required) + self.assertIn("#### 判断案例", required) self.assertIn("### 3. 识别子项目与交付单元", required) def test_missing_or_wrong_core_mapping_is_reported(self) -> None: