Skip to content

Project-Retrospective.md

Latest commit

 

History

History
89 lines (65 loc) · 3.7 KB

Project-Retrospective.md

File metadata and controls

89 lines (65 loc) · 3.7 KB
Raw

PowerUpSQLSharp 项目经验沉淀

供后续类似项目（PowerShell → C# 重写、安全工具 CLI、域/SQL 集成测试）参考。

1. 架构决策回顾

决策 效果 建议
领域服务 + 薄命令层 108 个 CLI 命令可共享连接/过滤/格式化逻辑 后续项目优先「服务接口 + Command 注册表」
PowerUpSQL 1:1 命令名 降低迁移成本，集成测试可直接对照 兼容层与内部命名分离（C# PascalCase 类名）
Batch 分阶段交付 降低单次 PR 风险，便于验收 保留 Mapping 文档并同步 Status
单文件 Costura 发布 适合 Sliver execute-assembly --in-process 发布脚本 + strip 验证缺一不可

2. 测试策略

层级 做法 经验
单元测试 Fake Service + Command 层断言 命令参数解析、ExitCode、Formatter 优先单测
集成测试 Run-IntegrationTests.ps1 + test-env.ps1 敏感配置 gitignore，example 文件入仓
对照验收 与 PowerUpSQL 并行跑同一目标 语义等价而非字节级一致

3. 安全与隐私

  • 发布前运行 verify-strip.ps1 检查 PDB 路径、用户名、机器名泄漏
  • test-env.ps1、credentials.json、.env 永不入仓
  • Commit/PR 描述中脱敏主机名、IP、真实路径（见 global-conventions）

4. 推荐沉淀为 Cursor Rules

以下规则建议放在本地 .cursor/rules/（不提交 Git），供 AI 助手持续遵循：

4.1 powerupsqlsharp-conventions.mdc

---
description: PowerUpSQLSharp 项目约定
globs: src/**/*.cs, scripts/**/*.ps1
---
- 新命令必须注册到 CommandBootstrap.ExportedFunctions 并保持 PowerUpSQL 原名
- 连接参数复用 ConnectionTestCommandHelper / ReconCommandHelper
- 输出经 CommandResultFormatter + OutputFormatter，支持 --format json
- 每个新命令至少 1 个单元测试；Batch 级别变更更新 Integration-TestPlan

4.2 git-commit-push.mdc（已有）

  • 有文件变更时自动 commit + push
  • 禁止提交 test-env.ps1、.cursor/、.reference/

4.3 global-conventions.mdc（已有）

  • 中文回答、提交前脱敏

5. 推荐创建 Agent Skills

Skill 名称 用途 触发场景
powerupsqlsharp-add-command 新增命令 checklist：Service → Command → Bootstrap → Test → Mapping 「添加 Get-SQLXxx 命令」
powerupsqlsharp-integration-test 指导编写 Run-IntegrationTests 用例与 test-env 变量 「加集成测试」
powerupsqlsharp-release release.ps1 → verify-strip → Normalize-ReleaseArtifact 流程 「发布版本」
powershell-to-csharp-port PS 函数 → C# 服务方法迁移模板 类似重写项目

Skill 模板可参考 Cursor 官方 create-skill 指引，存放于用户级 ~/.cursor/skills/ 或项目本地 .cursor/skills/（gitignore）。

6. 文档清单（本项目最终态）

文档 用途
README.md 入口：构建、用法、文档索引
docs/Usage-Examples.md 全命令操作示例
docs/PowerUpSQL-Mapping.md 108 函数映射与实现状态
docs/Integration-TestPlan.md 集成测试矩阵
docs/Acceptance-Tests.md 验收规范
docs/AutomatedLab-TestEnvironment.md 实验环境搭建
docs/Project-Retrospective.md 本文：经验沉淀

7. 收尾 Checklist（可复用）

  • 全命令 Usage 文档
  • Mapping Status 与代码一致
  • .cursor/ 加入 gitignore 并从索引移除
  • 本地参考目录（.reference/）不入仓
  • 集成测试 example 配置齐全
  • release + strip 验证通过
  • README 文档链接完整

最后更新：2026-07-04