nacadmin
/
NAC_Blockchain
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

feat: 创建Issue #025 预留导入管理机制工单 

背景：
- Issue #024开发中遇到大量未使用导入警告
- 需要统一的预留导入管理机制
- 避免使用#[allow(unused)]掩盖问题

方案：
- 统一的@reserved属性语法（Rust/Charter/CNNL）
- 预留编号规范和生命周期管理
- cargo-constitution工具链支持
- IDE插件和CI/CD集成

价值：
- 将未使用导入从代码异味转变为活文档
- 提升技术债可见性
- 支持团队协作和知识传承
This commit is contained in:
NAC Development Team 2026-02-19 01:11:27 -05:00
parent 3cbf8b376f
commit d13a4757e9
1 changed files with 542 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

542
ISSUE_025_RESERVED_IMPORTS_MANAGEMENT.md Normal file
View File

@ -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