From d13a4757e95d3eeafdb859776ff7e42f4ec26b77 Mon Sep 17 00:00:00 2001 From: NAC Development Team Date: Thu, 19 Feb 2026 01:11:27 -0500 Subject: [PATCH] =?UTF-8?q?feat:=20=E5=88=9B=E5=BB=BAIssue=20#025=20?= =?UTF-8?q?=E9=A2=84=E7=95=99=E5=AF=BC=E5=85=A5=E7=AE=A1=E7=90=86=E6=9C=BA?= =?UTF-8?q?=E5=88=B6=E5=B7=A5=E5=8D=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 背景： - Issue #024开发中遇到大量未使用导入警告 - 需要统一的预留导入管理机制 - 避免使用#[allow(unused)]掩盖问题 方案： - 统一的@reserved属性语法（Rust/Charter/CNNL） - 预留编号规范和生命周期管理 - cargo-constitution工具链支持 - IDE插件和CI/CD集成 价值： - 将未使用导入从代码异味转变为活文档 - 提升技术债可见性 - 支持团队协作和知识传承 --- ISSUE_025_RESERVED_IMPORTS_MANAGEMENT.md | 542 +++++++++++++++++++++++ 1 file changed, 542 insertions(+) create mode 100644 ISSUE_025_RESERVED_IMPORTS_MANAGEMENT.md diff --git a/ISSUE_025_RESERVED_IMPORTS_MANAGEMENT.md b/ISSUE_025_RESERVED_IMPORTS_MANAGEMENT.md new file mode 100644 index 0000000..3af52ea --- /dev/null +++ b/ISSUE_025_RESERVED_IMPORTS_MANAGEMENT.md @@ -0,0 +1,542 @@ +# Issue #025: 预留导入管理机制 + +**工单编号**: #025 +**工单标题**: 实现统一的预留导入管理机制 +**优先级**: 中 +**类型**: 技术基础设施 +**创建日期**: 2026-02-19 +**预计工期**: 2-3周 +**状态**: 待处理 + +--- + +## 📋 问题背景 + +### 当前痛点 + +在NAC项目开发过程中，经常遇到以下问题： + +1. **未使用导入警告泛滥** + - 开发者为未来功能预留导入，但编译器报告`unused import`警告 + - 为了消除警告，开发者可能： + - 使用`#[allow(unused_imports)]`掩盖问题（危险！） + - 删除导入，导致未来开发者不知道原计划（埋雷！） + - 保留警告，干扰正常开发（烦人！） + +2. **技术债缺乏可见性** + - 预留的功能和依赖没有统一记录 + - 后续开发者不知道为什么某些代码被注释掉 + - 无法追踪预留项的生命周期 + +3. **多编译器不一致** + - Rust、Charter、CNNL三套编译器处理方式不同 + - 缺乏统一的预留导入规范 + - 团队协作困难 + +### 触发事件 + +在Issue #024 (nac-ai-valuation)开发过程中，遇到了大量未使用导入警告。经过讨论，确定了以下原则： +- ❌ 不使用`#[allow(unused)]`掩盖问题 +- ❌ 不随意删除可能需要的导入 +- ✅ 需要一个正式的预留导入管理机制 + +--- + +## 🎯 解决方案 + +### 核心理念 + +**将"未使用的导入"从"代码异味"转变为"未来路线图的活文档"** + +通过统一的预留属性语法，让预留导入成为： +- 📝 **可文档化** - 每个预留都有编号和说明 +- 🔍 **可追踪** - 可以生成预留清单，纳入技术债管理 +- 🔄 **可审计** - 可以检查预留是否过期，是否应该清理 +- 🤝 **可协作** - 团队成员清楚知道预留的目的和计划 + +### 设计原则 + +1. **统一性** - Rust、Charter、CNNL使用相同的语法和语义 +2. **明确性** - 每个预留都有唯一编号和清晰说明 +3. **可进化** - 支持预留的启用、延期、废弃 +4. **可审计** - 可以生成报告，追踪预留生命周期 +5. **零成本** - 不影响编译性能和运行时性能 + +--- + +## 📐 技术方案 + +### 1. 统一预留属性语法 + +#### 1.1 Rust（通过自定义属性） +```rust +#[reserved( + id = "XIC-001", + description = "跨链桥升级所需，预计2026Q3启用", + owner = "bridge-team", + deadline = "2026-09-30" +)] +use some_crate::FutureModule; +``` + +#### 1.2 Charter（语言原生支持） +```charter +@reserved( + id="XIC-002", + description="XTZH v2 预言机接口", + owner="oracle-team", + deadline="2027-03-31" +) +import future::oracle_v2; +``` + +#### 1.3 CNNL（宪法层预留条款） +```cnnl +// 宪法条款也可有预留导入 +@reserved( + id="CON-001", + description="国际商事法律规则库", + owner="legal-team", + deadline="2027-12-31" +) +import law::cisg; +``` + +### 2. 预留编号规范 + +#### 2.1 编号格式 +``` +<项目代号>-<序号> +``` + +#### 2.2 项目代号 +- `CORE` - 核心模块 +- `XIC` - 跨链互操作 +- `BRIDGE` - 跨链桥 +- `ORACLE` - 预言机 +- `AIVAL` - AI估值 +- `CON` - 宪法层 +- `RPC` - RPC接口 +- `TOOL` - 工具链 + +#### 2.3 序号规则 +- 从001开始连续编号 +- 同一项目代号下序号唯一 +- 废弃的编号不重用 + +### 3. 预留属性字段 + +#### 3.1 必填字段 +- `id` - 预留编号（全局唯一） +- `description` - 预留说明（简短描述用途） + +#### 3.2 可选字段 +- `owner` - 负责团队或负责人 +- `deadline` - 预计启用时间（YYYY-MM-DD） +- `issue` - 关联的Issue编号 +- `status` - 状态（planned/in-progress/blocked/cancelled） +- `priority` - 优先级（high/medium/low） + +### 4. 编译器行为 + +#### 4.1 Rust编译器扩展 +- 通过`cargo-constitution` Lint实现 +- 识别`#[reserved]`属性 +- 不报告`unused import`警告 +- 生成预留清单文件`reserved_deps.json` + +#### 4.2 Charter编译器 +- 原生支持`@reserved`属性 +- 编译时验证预留编号唯一性 +- 支持`--list-reserved`选项输出清单 + +#### 4.3 CNNL编译器 +- 原生支持`@reserved`属性 +- 与宪法治理流程集成 +- 预留的启用可能需要治理投票 + +### 5. 工具链支持 + +#### 5.1 cargo-constitution +```bash +# 查看所有预留 +cargo reserved list + +# 查看特定项目的预留 +cargo reserved list --project XIC + +# 检查过期预留 +cargo reserved check-expired + +# 生成预留报告 +cargo reserved report --format markdown + +# 启用预留（移除@reserved属性） +cargo reserved activate XIC-001 + +# 废弃预留（添加cancelled状态） +cargo reserved cancel XIC-002 --reason "需求变更" +``` + +#### 5.2 IDE插件 +- 高亮显示预留导入 +- 鼠标悬停显示预留信息 +- 快速跳转到相关Issue +- 提示即将过期的预留 + +#### 5.3 CI集成 +```yaml +# .github/workflows/check-reserved.yml +name: Check Reserved Imports + +on: [push, pull_request] + +jobs: + check: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - name: Check expired reserved imports + run: cargo reserved check-expired --fail-if-expired + - name: Generate reserved report + run: cargo reserved report --format markdown > reserved_report.md + - name: Upload report + uses: actions/upload-artifact@v2 + with: + name: reserved-report + path: reserved_report.md +``` + +### 6. 预留生命周期管理 + +#### 6.1 预留状态 +- `planned` - 已规划，等待实现 +- `in-progress` - 正在实现中 +- `blocked` - 被阻塞，无法继续 +- `cancelled` - 已取消，不再需要 +- `activated` - 已启用，移除预留标记 + +#### 6.2 生命周期流程 +``` +planned → in-progress → activated + ↓ ↓ +cancelled blocked → in-progress +``` + +#### 6.3 过期检查 +- 如果预留超过deadline未启用，CI发出警告 +- 如果预留超过1年未启用，建议评估是否取消 +- 定期（每季度）审查所有预留项 + +--- + +## 📦 交付物 + +### 1. 技术规范文档 +- [x] 预留导入管理机制规范（本文档） +- [ ] 附件G：多编译器协同使用细则（更新版） +- [ ] 预留编号分配指南 +- [ ] 预留生命周期管理流程 + +### 2. Rust工具链 +- [ ] cargo-constitution Lint扩展 +- [ ] 预留属性宏实现 +- [ ] cargo reserved子命令 +- [ ] 预留清单生成器 + +### 3. Charter编译器 +- [ ] @reserved属性解析 +- [ ] 预留编号唯一性检查 +- [ ] --list-reserved选项 +- [ ] 预留清单输出 + +### 4. CNNL编译器 +- [ ] @reserved属性解析 +- [ ] 与治理流程集成 +- [ ] 预留条款管理 + +### 5. IDE插件 +- [ ] VSCode插件（Rust） +- [ ] Charter语言服务器扩展 +- [ ] CNNL语言服务器扩展 + +### 6. CI/CD集成 +- [ ] GitHub Actions工作流 +- [ ] GitLab CI配置 +- [ ] 预留报告生成脚本 + +### 7. 文档和示例 +- [ ] 使用指南 +- [ ] 最佳实践 +- [ ] 示例项目 +- [ ] FAQ + +--- + +## 🎯 验收标准 + +### 1. 功能完整性 +- [ ] 三种语言（Rust/Charter/CNNL）都支持预留属性 +- [ ] 编译器能正确识别和处理预留导入 +- [ ] 不报告预留导入的unused警告 +- [ ] 能生成预留清单 + +### 2. 工具链完整性 +- [ ] cargo reserved命令可用 +- [ ] IDE插件正常工作 +- [ ] CI集成正常运行 +- [ ] 预留报告格式正确 + +### 3. 文档完整性 +- [ ] 技术规范文档完整 +- [ ] 使用指南清晰 +- [ ] 示例代码可运行 +- [ ] FAQ覆盖常见问题 + +### 4. 质量标准 +- [ ] 零编译警告 +- [ ] 所有测试通过 +- [ ] 代码覆盖率>80% +- [ ] 性能无明显下降 + +--- + +## 📅 实施计划 + +### Phase 1: 规范制定（3天） +- [ ] 完善技术规范文档 +- [ ] 制定预留编号分配规则 +- [ ] 设计预留清单格式 +- [ ] 评审和确认 + +### Phase 2: Rust工具链（1周） +- [ ] 实现cargo-constitution Lint扩展 +- [ ] 实现预留属性宏 +- [ ] 实现cargo reserved子命令 +- [ ] 编写测试 + +### Phase 3: Charter编译器（3天） +- [ ] 实现@reserved属性解析 +- [ ] 实现预留编号检查 +- [ ] 实现--list-reserved选项 +- [ ] 编写测试 + +### Phase 4: CNNL编译器（3天） +- [ ] 实现@reserved属性解析 +- [ ] 集成治理流程 +- [ ] 编写测试 + +### Phase 5: IDE插件（3天） +- [ ] 实现VSCode插件 +- [ ] 实现语言服务器扩展 +- [ ] 测试和优化 + +### Phase 6: CI/CD集成（2天） +- [ ] 编写GitHub Actions工作流 +- [ ] 编写预留报告生成脚本 +- [ ] 测试CI集成 + +### Phase 7: 文档和示例（2天） +- [ ] 编写使用指南 +- [ ] 编写最佳实践 +- [ ] 创建示例项目 +- [ ] 编写FAQ + +### Phase 8: 测试和优化（2天） +- [ ] 集成测试 +- [ ] 性能测试 +- [ ] 用户测试 +- [ ] 优化和修复 + +--- + +## 🔗 依赖关系 + +### 上游依赖 +- NAC编译器工具链（Charter/CNNL） +- cargo-constitution基础框架 +- NAC治理流程 + +### 下游影响 +- 所有NAC模块开发 +- 代码审查流程 +- 技术债管理 +- 项目规划 + +--- + +## 📊 成功指标 + +### 量化指标 +- 预留导入使用率 > 80%（团队采纳度） +- unused import警告减少 > 90% +- 技术债可见性提升 100%（所有预留都有记录） +- 预留启用率 > 60%（预留最终被使用的比例） + +### 质量指标 +- 团队满意度 > 4/5 +- 文档完整性 100% +- 工具稳定性 > 99% +- 性能影响 < 1% + +--- + +## ⚠️ 风险和挑战 + +### 技术风险 +1. **编译器集成复杂度** + - 风险：三套编译器集成工作量大 + - 缓解：分阶段实施，先Rust后Charter/CNNL + +2. **性能影响** + - 风险：预留检查可能影响编译速度 + - 缓解：优化算法，使用缓存 + +3. **向后兼容性** + - 风险：现有代码需要迁移 + - 缓解：提供迁移工具，保持兼容期 + +### 流程风险 +1. **团队采纳度** + - 风险：团队可能不愿意使用新机制 + - 缓解：提供培训，展示价值，强制在新代码中使用 + +2. **维护成本** + - 风险：预留项过多导致维护困难 + - 缓解：定期审查，自动化过期检查 + +--- + +## 💡 最佳实践 + +### 1. 何时使用预留导入 +✅ **应该使用**： +- 已确定的未来功能，但当前不实现 +- 跨模块依赖，等待上游模块完成 +- 实验性功能，需要feature flag控制 +- 技术债，计划未来重构 + +❌ **不应该使用**： +- 不确定是否需要的功能 +- 可以立即实现的功能 +- 已废弃的功能 +- 临时测试代码 + +### 2. 预留说明编写规范 +```rust +// ✅ 好的预留说明 +#[reserved( + id = "XIC-001", + description = "跨链桥升级到IBC协议，等待ibc-rs v2.0稳定版发布", + owner = "bridge-team", + deadline = "2026-09-30", + issue = "#123" +)] +use ibc_rs::v2::Context; + +// ❌ 不好的预留说明 +#[reserved(id = "XIC-002", description = "可能需要")] +use some_crate::Something; +``` + +### 3. 预留生命周期管理 +- 每月检查即将过期的预留 +- 每季度审查所有预留项 +- 及时更新预留状态 +- 启用后立即移除预留标记 + +--- + +## 📚 参考资料 + +### 相关Issue +- Issue #024: nac-ai-valuation AI估值系统完善（触发本工单） + +### 相关文档 +- NAC技术宪法 +- 附件G：多编译器协同使用细则 +- cargo-constitution设计文档 +- Charter语言规范 +- CNNL语言规范 + +### 外部参考 +- Rust RFC: Custom attributes +- Cargo book: Custom commands +- Language Server Protocol + +--- + +## 🎓 经验教训（来自Issue #024） + +### 1. 不要使用`#[allow(unused)]`掩盖问题 +未使用的代码可能是逻辑错误或安全隐患，不应该用属性掩盖。 + +### 2. 不要随意删除导入 +测试代码可能需要，应该在测试模块中导入，不要给未来开发者埋雷。 + +### 3. 所有字段都应该有用途 +如果不用就删除，如果用就实际使用，不要保留无用字段。 + +### 4. 需要正式的预留机制 +临时的注释和TODO不够，需要正式的、可追踪的预留机制。 + +--- + +## ✅ 验收清单 + +### 技术实现 +- [ ] Rust工具链完成 +- [ ] Charter编译器完成 +- [ ] CNNL编译器完成 +- [ ] IDE插件完成 +- [ ] CI/CD集成完成 + +### 文档完善 +- [ ] 技术规范完成 +- [ ] 使用指南完成 +- [ ] 最佳实践完成 +- [ ] FAQ完成 + +### 测试验证 +- [ ] 单元测试通过 +- [ ] 集成测试通过 +- [ ] 性能测试通过 +- [ ] 用户测试通过 + +### 部署上线 +- [ ] 代码提交Git +- [ ] 文档发布 +- [ ] 团队培训 +- [ ] 正式启用 + +--- + +## 📝 备注 + +### 临时方案（在正式实现前） +在正式实现预留导入管理机制之前，可以使用以下临时方案： + +```rust +// 临时方案：使用注释标记预留导入 +// @reserved(id="AIVAL-001", description="未来可能需要的XXX功能") +// use future_module::Something; +``` + +这种方式虽然不够优雅，但至少： +- 保留了预留意图 +- 不会产生编译警告 +- 可以通过grep搜索所有预留项 + +### 后续优化方向 +1. 与项目管理工具集成（Jira/GitHub Projects） +2. 自动生成预留路线图 +3. 预留依赖关系可视化 +4. AI辅助预留管理 + +--- + +**工单创建时间**: 2026-02-19 01:00:00 GMT+4 +**工单创建者**: NAC开发团队 +**工单状态**: 待处理 +**优先级**: 中 +**预计完成时间**: 2026-03-10