dev-task

# 开发任务管理 Skill 本 Skill 用于规范化的项目版本管理和开发任务流程。 --- ## ⚠️ 版本管理纪律（强制执行） ### 铁律 > **每个版本封版后必须立即归档完整代码和文档！** > **严禁在没有存档的情况下开始新版本号的开发！** ### 违规后果 - **v1.X 代码永久丢失** — 未归档即开始 v1.X+1 开发 - 无法回滚到中间版本 - 版本历史断档 ### 必须归档的内容 | 类别 | 必须文件 | 说明 | |------|---------|------| | **代码** | `src/` 目录 | 封版时的完整代码快照 | | **变更** | `docs/CHANGELOG.md` | 功能列表、Bug修复、已知问题 | | **需求** | `docs/REQUIREMENTS.md` | 需求规格、功能清单 | | **运维** | `docs/DEPLOY.md` | 部署步骤、回滚方案、监控方法 | --- ## 项目版本结构规范 ``` project-name/ ├── [当前开发文件] # 正在开发的代码 └── versions/ # ★版本归档目录（不可跳过） ├── README.md # 版本管理说明、当前版本 ├── v1.0/ # v1.0 版本（完整归档） │ ├── docs/ │ │ ├── CHANGELOG.md # 变更日志 │ │ ├── REQUIREMENTS.md # 需求文档 │ │ └── DEPLOY.md # 部署文档 │ ├── src/ # ★完整代码备份 │ └── release/ # 发布包（可选） ├── v1.1/ # v1.1 版本（完整归档） └── v1.2/ # v1.2 版本（完整归档） ``` --- ## 开发任务启动流程 ### Step 1: 确认版本编号（必须） **必须**向用户确认版本号，格式为 `v主版本.次版本.修订号`： > "请确认本次开发任务的版本编号（例如：v1.1.0）：" **版本号规则：** - **主版本号 (X.0.0)**: 重大功能变更、架构调整 - **次版本号 (0.X.0)**: 新增功能、向下兼容 - **修订号 (0.0.X)**: Bug 修复、小优化 **检查规则：** - 如果 versions/vX.Y.Z 已存在 → 询问继续开发还是换新版本 - 如果当前开发目录有未归档代码 → **必须先封版上一个版本！** ### Step 2: 检查上一个版本是否已归档 ```bash # 检查最新版本 ls -la versions/ | tail -5 # 如果上一个版本未完成归档，必须提醒用户： # "⚠️ 警告：上一个版本 vX.Y.Z 尚未封版归档！" # "必须先完成 vX.Y.Z 的归档，才能开始新版本开发。" ``` ### Step 3: 创建新版本目录结构 ```bash # 创建目录 mkdir -p versions/vX.Y.Z/{docs,src,release} # 初始化文档 cp references/CHANGELOG.template.md versions/vX.Y.Z/docs/CHANGELOG.md cp references/REQUIREMENTS.template.md versions/vX.Y.Z/docs/REQUIREMENTS.md cp references/DEPLOY.template.md versions/vX.Y.Z/docs/DEPLOY.md # 替换版本号占位符 sed -i 's/vX.Y.Z/vX.Y.Z/g' versions/vX.Y.Z/docs/*.md ``` ### Step 4: 更新 REQUIREMENTS.md 根据用户描述，填写本次开发的需求： - 功能需求清单 - 技术规格 - 约束条件 ### Step 5: 开始开发 在当前目录进行开发工作。 --- ## 版本封版流程（★关键步骤） ### 何时封版 - 功能开发完成 - 测试通过 - 准备部署或发布 ### 封版检查清单 **必须完成以下所有项，缺一不可：** - [ ] **CHANGELOG.md** 已更新 - [ ] 新增功能列表 - [ ] Bug 修复记录 - [ ] 已知问题说明 - [ ] 部署日期 - [ ] **REQUIREMENTS.md** 已更新 - [ ] 需求完成情况 - [ ] 功能清单核对 - [ ] **DEPLOY.md** 已更新 - [ ] 部署步骤 - [ ] 环境要求 - [ ] 回滚方案 - [ ] **代码已归档** ```bash cp -r client versions/vX.Y.Z/src/ cp -r server versions/vX.Y.Z/src/ cp package.json versions/vX.Y.Z/src/ cp [其他必要文件] versions/vX.Y.Z/src/ ``` - [ ] **versions/README.md** 已更新 - 当前版本信息 - 版本历史记录 ### 封版命令 ```bash #!/bin/bash VERSION=$1 # 传入版本号，如 v1.1.0 echo "=== 版本封版: $VERSION ===" # 1. 验证文档存在 for doc in CHANGELOG REQUIREMENTS DEPLOY; do if [ ! -f "versions/$VERSION/docs/${doc}.md" ]; then echo "❌ 错误: ${doc}.md 不存在！" exit 1 fi done # 2. 归档代码 echo "归档代码..." cp -r client versions/$VERSION/src/ cp -r server versions/$VERSION/src/ cp package.json versions/$VERSION/src/ 2>/dev/null || true # 3. 验证归档 if [ -d "versions/$VERSION/src/client" ] && [ -d "versions/$VERSION/src/server" ]; then echo "✅ 版本 $VERSION 封版完成！" else echo "❌ 归档失败！" exit 1 fi ``` --- ## 版本回滚 ```bash VERSION=$1 # 目标版本 echo "回滚到 $VERSION..." # 1. 停止服务 pm2 stop [服务名] # 2. 验证版本存在 if [ ! -d "versions/$VERSION/src" ]; then echo "❌ 版本 $VERSION 代码不存在！" exit 1 fi # 3. 恢复代码 cp -r versions/$VERSION/src/* ./ # 4. 重新安装依赖 npm install # 5. 启动服务 pm2 start [服务名] echo "✅ 已回滚到 $VERSION" ``` --- ## 参考模板 文档模板位于 `references/doc-templates/`： | 模板文件 | 用途 | 输出位置 | |---------|------|---------| | `CHANGELOG.template.md` | 变更日志 | `docs/CHANGELOG.md` | | `REQUIREMENTS.template.md` | 需求文档 | `docs/REQUIREMENTS.md` | | `DEPLOY.template.md` | 部署说明 | `docs/DEPLOY.md` | --- ## 违规处理 如果发现以下情况，必须立即纠正： | 违规情况 | 处理方式 | |---------|---------| | 未归档即开始新版本 | **立即停止**，先完成上一个版本归档 | | 缺少 CHANGELOG.md | 补充编写，记录变更 | | 缺少 REQUIREMENTS.md | 补充编写，明确需求 | | 缺少 DEPLOY.md | 补充编写，确保可部署 | | src/ 目录为空或不完整 | 重新归档完整代码 | --- ## CSS/样式调试检查清单 **遇到样式不生效时，按此顺序排查：** ### Step 1: 确认选择器匹配（最常见错误！） ``` ✅ 检查 HTML 中元素的 id/class 是否与 CSS 选择器一致 - id: chatInput vs #chat-input （命名不匹配！） - class: my-class vs .myClass （大小写敏感！） ✅ 用 DevTools Elements 面板确认元素的实际属性 ``` ### Step 2: 确认文件加载 ``` ✅ Network 面板 → CSS 文件状态 200 ✅ 文件名和路径是否正确（大小写敏感！） ``` ### Step 3: 确认样式应用 ``` ✅ DevTools Computed 面板 → 查看实际生效的样式 ✅ Styles 面板 → 查看哪些规则被划掉（特异性问题） ✅ 检查是否有更高优先级的规则覆盖 ``` ### Step 4: 复杂问题排查 ``` ✅ 浏览器默认样式 → 用 !important 或 appearance: none ✅ JS 动态修改 → 检查脚本是否修改了样式 ✅ CSS 变量未定义 → 检查 var(--xxx) 是否有值 ``` ### 黄金法则 > **90% 的 CSS 问题是基础错误（选择器不匹配、文件未加载），只有 10% 是复杂的优先级/兼容性问题。先查基础，再查复杂。** ### 经验教训归档 - 参考 `workspace/lessons/CSS_DEBUG_LESSON.md` - 每次遇到典型问题，更新此文档 --- ## 一句话总结 > **封版必归档，文档不能少，跳过是违规！** > **CSS 调试先查选择器，90% 问题都是命名不匹配！**