6aspec 2.0.0-dev.9 → 3.0.0-dev.1

package/.6aspec/rules/biz/code.md

@@ -1,39 +1,133 @@
 ---
-description: 
-globs: 
-alwaysApply: false
+description: 代码编写规范与质量标准
+globs: "**/*.{java,js,ts,py,go,cpp,c,cs}"
+alwaysApply: true
 ---
 
-## 代码质量
-- **单一职责**：每个类和方法只负责一个功能
-- **开闭原则**：对扩展开放，对修改关闭
-- **依赖倒置**：依赖抽象而不是具体实现
-- **接口隔离**：使用小而专一的接口
-- **代码复用**：提取公共逻辑，避免重复代码
+# 代码编写规范
+
+## 🚨 红线规则（绝对禁止）
+
+### 性能红线
+- **禁止在循环中进行数据库查询**：避免N+1问题，使用批量查询或预加载
+- **禁止在循环中进行网络请求**：使用批量API或异步处理
+- **禁止在循环中进行文件I/O操作**：批量读写或使用缓存
+- **禁止在热点代码路径中使用反射**：影响性能，考虑编译时生成或缓存
+- **禁止在生产环境使用System.out.println调试**：使用日志框架
+
+### 安全红线
+- **禁止直接拼接SQL语句**：必须使用参数化查询防止SQL注入
+- **禁止在日志中输出敏感信息**：密码、token、身份证号等
+- **禁止硬编码密钥和敏感配置**：使用配置文件或环境变量
+- **禁止信任用户输入**：所有外部输入必须验证和过滤
+- **禁止使用弱加密算法**：MD5、SHA1等已不安全
+
+### 架构红线
+- **禁止循环依赖**：包、模块、类之间不能相互依赖
+- **禁止跨层直接调用**：Controller不能直接调用DAO
+- **禁止在实体类中包含业务逻辑**：保持实体类的纯净性
+- **禁止在静态代码块中进行复杂操作**：可能导致类加载问题
+- **禁止捕获异常后不处理**：空catch块是代码异味
+
+## 🔒 安全规范
+
+### 输入验证
+- **参数校验**：所有API入参必须校验
+- **数据过滤**：防止XSS、SQL注入等攻击
+- **权限检查**：每个操作都要验证用户权限
+- **敏感数据处理**：加密存储，脱敏展示
+
+### 日志安全
+- **敏感信息脱敏**：密码、token等不能明文记录
+- **操作审计**：关键操作必须记录审计日志
+- **错误信息**：不暴露系统内部信息给用户
+
+## ⚡ 性能优化
+
+### 数据库优化
+- **索引使用**：查询字段必须有合适的索引
+- **批量操作**：使用批量插入/更新减少数据库交互
+- **连接池管理**：合理配置数据库连接池
+- **查询优化**：避免全表扫描，使用分页查询
 
-## 性能优化
-- **算法复杂度**：选择合适的算法和数据结构
-- **缓存策略**：合理使用缓存减少重复计算
-- **懒加载**：对于昂贵的操作使用懒加载
-- **批量处理**：批量处理数据库操作和网络请求
+### 缓存策略
+- **多级缓存**：本地缓存 + 分布式缓存
+- **缓存更新**：及时更新或失效过期数据
+- **缓存穿透**：防止恶意查询不存在的数据
+- **缓存雪崩**：设置随机过期时间
 
+### 算法复杂度
+- **时间复杂度**：优先选择O(1)、O(log n)算法
+- **空间复杂度**：避免不必要的内存占用
+- **数据结构选择**：根据使用场景选择合适的数据结构
 
-## 编码规范
-- **命名规范**：类名、方法名、变量名清晰表达意图
-- **代码结构**：合理的包结构和类层次
-- **注释规范**：必要的类和方法注释
-- **代码复用**：避免重复代码，提取公共方法
+## 📝 编码规范
 
+### 命名规范
+- **类名**：大驼峰命名，名词，表达清晰意图
+- **方法名**：小驼峰命名，动词开头，表达具体行为
+- **变量名**：小驼峰命名，避免缩写，见名知意
+- **常量名**：全大写，下划线分隔
+- **包名**：全小写，层次清晰
 
-## 设计原则
-- **SOLID 原则**：单一职责、开闭原则等
-- **DRY 原则**：不重复自己
-- **KISS 原则**：保持简单
-- **YAGNI 原则**：你不会需要它
+### 代码结构
+- **包结构**：按功能模块划分，层次清晰
+- **类大小**：单个类不超过500行
+- **方法长度**：单个方法不超过50行
+- **参数个数**：方法参数不超过5个
+- **嵌套层次**：代码嵌套不超过4层
 
+### 注释规范
+- **类注释**：说明类的职责和使用场景
+- **方法注释**：说明参数、返回值、异常
+- **复杂逻辑注释**：解释为什么这样做
+- **TODO注释**：标记待完成的工作
 
-## 重构策略
-- **持续重构**：小步快跑，持续改进
+## 🏗️ 设计原则
+
+### SOLID原则
+- **单一职责原则**：一个类只负责一个功能领域
+- **开闭原则**：对扩展开放，对修改关闭
+- **里氏替换原则**：子类可以替换父类
+- **接口隔离原则**：使用多个专门的接口
+- **依赖倒置原则**：依赖抽象而不是具体实现
+
+### 其他原则
+- **DRY原则**：不重复自己，提取公共代码
+- **KISS原则**：保持简单，避免过度设计
+- **YAGNI原则**：你不会需要它，不做过度设计
+- **最少知识原则**：对象应该对其他对象有最少的了解
+
+## 🔄 重构策略
+
+### 重构时机
+- **新功能开发时**：同步重构相关代码
+- **Bug修复时**：改善代码结构
+- **代码审查时**：发现问题及时重构
+- **性能优化时**：重构性能瓶颈代码
+
+### 重构原则
+- **小步快跑**：每次重构范围要小
 - **测试保护**：重构前确保测试覆盖
-- **重构时机**：新功能开发时同步重构
-- **技术债务**：定期评估和偿还技术债务
+- **持续集成**：频繁提交，及时发现问题
+- **技术债务管理**：定期评估和偿还
+
+## ✅ 检查清单
+
+### 代码提交前检查
+- [ ] 是否违反红线规则
+- [ ] 是否有安全漏洞
+- [ ] 是否有性能问题
+- [ ] 命名是否规范
+- [ ] 是否有充分的测试
+- [ ] 是否有必要的注释
+- [ ] 是否符合团队编码风格
+
+### 代码审查检查
+- [ ] 业务逻辑是否正确
+- [ ] 异常处理是否完善
+- [ ] 边界条件是否考虑
+- [ ] 是否有代码重复
+- [ ] 是否符合设计原则
+- [ ] 是否有技术债务
+- [ ] 文档是否需要更新

package/.6aspec/rules/biz/code_implementation_sop.md

@@ -0,0 +1,77 @@
+---
+description: 代码实现标准操作流程 (Code Implementation SOP)
+alwaysApply: false
+---
+
+# code: 代码实现标准操作流程
+
+你现在是 **Senior Developer**，负责根据用户描述的需求编写高质量、可运行的业务代码。
+
+## 0. 需求类型智能判断
+
+分析用户描述中的关键词和场景，判断需求类型：
+
+**判断规则**：
+- **API接口**：接口、API、Controller、HTTP、REST、查询、新增、修改、删除、DataApi
+- **后台任务**：BackgroundJob、异步任务、批量操作、批量绑定、批量解绑、批量更新
+- **定时任务**：定时任务、Job、定时执行、Cron、每天、每小时、凌晨、定时清理
+- **事件订阅**：EventSubscriber、监听事件、订阅、事件处理、事件触发
+- **其他类型**：不属于以上四种类型（工具类、辅助方法、配置类、实体类等）
+
+**判断输出**：
+```
+📋 需求类型：<类型名称>
+📚 加载规范：<规范文件列表>
+```
+
+## 1. 上下文加载
+
+### 1.1 必须加载（所有类型）
+1. `.6aspec/rules/biz/code.md` - 代码编写规范
+2. `.6aspec/rules/biz/project-structure.md` - 项目结构规范
+
+### 1.2 根据类型加载
+- **API接口** → `.6aspec/rules/biz/api_rule.md`
+- **后台任务** → `.6aspec/rules/biz/background_job_rule.md`
+- **定时任务** → `.6aspec/rules/biz/scheduled_job_rule.md`
+- **事件订阅** → `.6aspec/rules/biz/event_subscriber_rule.md`
+- **其他类型** → 只加载基础规范
+
+## 2. 代码实现
+
+严格按照加载的规范文件进行实现，遵循规范中定义的：
+- 包结构和命名规范
+- 类结构和注解使用
+- 实现顺序和关键要点
+- 异常处理和日志记录
+
+## 3. 质量检查
+
+### 3.1 代码规范检查
+使用 `.6aspec/rules/biz/code.md` 中的"检查清单"进行自我验证。
+
+**红线规则（零容忍）**：
+- [ ] 循环中的数据库查询、网络请求、文件I/O操作
+- [ ] SQL字符串拼接、敏感信息硬编码、弱加密算法使用
+- [ ] 循环依赖、跨层直接调用、空catch块
+
+### 3.2 类型特定检查
+使用对应规范文件中的"检查清单"章节进行验证。
+
+## 4. 完成输出
+
+```
+✅ 代码实现完成
+
+**需求类型**：<类型名称>
+**实现文件**：<文件列表>
+**关键点**：<关键实现点>
+```
+
+## 5. 异常处理
+
+遇到以下情况时停止并报告：
+- 需求不清晰，无法判断类型或实现方式
+- 缺少必要信息（参数定义、消息类型等）
+- 技术方案冲突，与现有架构或规范冲突
+- 依赖缺失，需要的 Service、Repository 等不存在

package/.6aspec/rules/brown/brown_analyze_sop.md

@@ -0,0 +1,289 @@
+# 棕地需求 - Analyze SOP
+
+需求澄清与影响面分析（合并原 Understand + Impact 两个阶段）
+
+**适用流程**：标准级、完整级
+
+**流程定位**：标准级/完整级的第一阶段，通过对话式澄清理解需求，确认后分析影响面，产出单一 analysis.md 文档
+
+**输入**：`/6aspec:brown:analyze` 后可选需求名称。如果省略，从上下文推断或提示选择。
+
+---
+
+## 步骤
+
+### 1. 选择需求并检查状态
+
+如果提供了名称，使用它。否则：
+- 从对话上下文推断
+- 如果模糊，读取 `6aspecdoc/brown/` 目录，让用户选择
+
+读取 `6aspecdoc/brown/<name>/status.json`：
+- 确认流程深度为 "standard" 或 "complete"
+- 如果是 "lightweight"，提示轻量级流程不需要 analyze 阶段，应直接运行 `/6aspec:brown:proposal`
+- 确认 `phases.analyze` 为 "pending"
+- 如果 analyze 已完成，提示使用 `/6aspec:brown:continue` 进入下一阶段
+
+### 2. 读取需求描述
+
+读取 `6aspecdoc/brown/<name>/artifacts/original-requirement.md` 获取原始需求内容。
+
+### 3. 探索代码，分析现有系统
+
+根据需求关键词搜索相关代码，自主判断需要分析哪些维度。重点是找到与需求直接相关的代码结构，不需要对整个系统做全面文档化。
+
+```bash
+rg "<关键词>" --type java -g "*Entity.java"
+rg "<关键词>" --type java -g "*Service.java"
+rg "<关键词>" --type java -C 3
+```
+
+**可选分析维度**（根据需求涉及范围自主选取，不强制每项都有）：
+- 相关实体类与数据库表关系（ERD）
+- 相关服务类与核心业务流程（flowchart）
+- 相关 API 接口 / 定时任务 / 消息队列
+- 隐性假设、状态机约束、权限控制逻辑
+- 其他与需求直接相关的系统结构
+
+如果找不到相关代码，询问用户提供更多关键词。
+
+### 4. 创建 analysis.md（含现有系统分析内容）
+
+分析完成后，立即创建文档并填充第1节"现有系统分析"。第2-5节保留占位符，后续边澄清边填充。
+
+创建 `6aspecdoc/brown/<name>/artifacts/analysis.md`：
+
+```markdown
+# 需求澄清与影响面分析
+
+> **需求**: <name>
+> **流程**: <flowDepth>
+> **阶段**: Analyze
+> **状态**: 🔄 澄清中
+> **创建时间**: <timestamp>
+
+## 1. 现有系统分析
+
+> 根据需求涉及范围，聚焦与需求直接相关的部分，自由组织内容。
+
+<AI 根据实际情况自主选择分析维度并组织内容，不强制固定结构。
+可包含：实体类与表关系（ERD）、服务类与业务流程（flowchart）、
+API/定时任务/消息队列、隐性假设与约束等，按需取舍。>
+
+## 2. 需求澄清
+
+### 待澄清问题
+
+<按维度分组的问题清单，初始为空，逐步填入>
+
+### 澄清结果
+
+<用户回答后逐步填入>
+
+## 3. 影响面分析
+
+> 待需求澄清完成后填写
+
+**模块范围**：<单模块 / 跨模块，列出涉及的模块/服务>
+
+**数据层变更**：
+- schema 变更：<是/否，说明>
+- 数据迁移：<是/否，说明>
+- 索引：<是/否，说明>
+
+**间接影响范围**：
+- 缓存：<有影响 / 无影响>
+- 权限：<有影响 / 无影响>
+- 事件订阅：<有影响 / 无影响>
+- 数据同步：<有影响 / 无影响>
+- Excel 导入导出：<有影响 / 无影响>
+- 前端页面：<有影响 / 无影响>
+
+## 4. 非功能需求评估
+
+> 待需求澄清完成后填写
+
+- 性能：<是否影响核心查询路径>
+- 安全：<是否涉及敏感数据或权限变更>
+- 可用性：<是否需要灰度发布或特殊回滚方案>
+
+## 5. 风险清单
+
+> 待需求澄清完成后填写
+
+1. <风险描述（聚焦业务和数据风险）>
+2. <风险描述>
+3. <风险描述（可选）>
+```
+
+### 5. 生成待澄清问题清单
+
+基于需求描述和已找到的代码，识别所有需要明确的问题，**按维度分组**展示：
+
+**展示格式**：
+
+```
+## 待澄清问题（共 N 个维度，M 个问题）
+
+### 维度一：[维度名称]（X 个问题）
+1. [问题]
+2. [问题]
+
+### 维度二：[维度名称]（X 个问题）
+3. [问题]
+4. [问题]
+
+---
+你可以一次性回答所有问题，也可以逐个回答。对于暂时不确定的问题可以先跳过，我会在需要时追问。
+```
+
+**同时将问题清单写入 analysis.md 的"待澄清问题"章节**。
+
+**问题维度参考**（根据需求实际情况选取）：
+- 字段设计（名称、类型、必填、默认值、值域）
+- 业务规则（状态流转、修改限制、删除规则）
+- 数据关系（关联表、历史数据处理）
+- 集成影响（事件、缓存、权限、第三方）
+- UI/UX（展示字段、交互逻辑）
+
+### 6. 对话式澄清循环
+
+**用户回答后的处理规则**：
+
+a. **立即将答案写入 analysis.md** 的"澄清结果"章节（按维度整理，不是原文堆砌）
+
+b. **判断是否需要追问或指出风险**：
+   - 答案有歧义或不完整 → 追问
+   - 答案暗示存在未覆盖的**业务边界场景** → 用反问引导用户思考（例："你说只有待执行状态可以删除，那执行中途系统重启，状态会是什么？"）
+   - 多个答案之间存在**业务规则矛盾** → 直接指出矛盾，请用户确认（例："你说入账失败会回滚，但又说状态只有待执行和执行成功两种——回滚后状态回到待执行吗？"）
+   - 答案清晰完整且无风险 → 继续
+   - **不涉及技术实现层面的问题**（事务、通知机制、回滚策略等），那是 design 阶段的职责
+
+c. **追问格式**（简洁，不重复已知信息）：
+   > "关于[具体问题]，你提到了[用户答案]，我想进一步确认：[追问内容]"
+
+d. **禁止**：不得在用户未回答完所有问题时自动进入影响面分析
+
+e. **持续更新文档**：每次用户回复后，更新 analysis.md，确保文档与对话同步
+
+### 7. 判断澄清完成
+
+当以下条件满足时，AI 主动询问用户是否完成澄清：
+- 所有维度的问题均已有答案
+- 没有新的追问需要提出
+
+询问方式：
+> "所有问题已经澄清完毕，我没有需要继续追问的了。需求澄清是否已经完成？确认后我将进行影响面分析。"
+
+**如果用户说还有补充**：继续记录，回到步骤 6。
+
+**如果用户确认完成**：进入步骤 8。
+
+### 8. 粗粒度影响面评估
+
+基于澄清结果，评估需求的"重量"，为需求范围决策提供依据。**不做函数级映射**，那是 design 阶段的职责。
+
+填充到 analysis.md 第3节：
+
+**模块范围**：涉及哪些模块/服务，是单模块改动还是跨模块？
+
+**数据层变更**（这是最关键的判断）：
+- schema 变更：是否需要加字段/加表/改类型？
+- 数据迁移：是否涉及存量数据处理？
+- 索引：是否需要新增索引？
+
+**间接影响范围**（只判断有/无，不展开细节）：
+- 缓存、权限、事件订阅、数据同步、Excel 导入导出、前端页面
+
+**非功能需求**（粗粒度评估）：
+- 性能：是否影响核心查询路径？
+- 安全：是否涉及敏感数据或权限变更？
+- 可用性：是否需要灰度发布或特殊回滚方案？
+
+**关键风险**（2-3 条，聚焦业务和数据风险，不涉及技术实现细节）
+
+### 9. 完成文档并更新状态
+
+更新 analysis.md 头部状态为 `✅ 已完成`，补充完成时间。
+
+更新 `6aspecdoc/brown/<name>/status.json`：
+
+**标准级流程**：
+```json
+{
+  "status": "proposal_pending",
+  "flowDepth": "standard",
+  "phases": {
+    "analyze": "done",
+    "proposal": "pending",
+    "specs": "blocked",
+    "design": "blocked",
+    "tasks": "blocked",
+    "implement": "blocked"
+  },
+  "artifacts": ["analysis.md"]
+}
+```
+
+同时更新 `6aspecdoc/brown/<name>/requirement.md`：
+- 更新"状态"字段为 `📋 Proposal 待开始`
+- 更新"最后修改"时间戳
+- 更新"当前阶段"为 `Analyze - 需求澄清与影响面分析（已完成）`
+- 更新"下一步操作"为 `运行 /6aspec:brown:proposal 继续下一阶段`
+- 在"进度概览"中标记 Analyze 阶段为已完成 `[x]`
+
+### 10. 停止并等待用户指令
+
+---
+
+## 输出
+
+```
+## Analyze 完成：<name>
+
+**流程**: 标准级/完整级
+**进度**: 1/N 阶段完成
+
+### 澄清结果摘要
+- 澄清维度：<数量>
+- 澄清问题：<数量>
+
+### 影响范围
+- 模块范围：<单模块 / 跨模块>
+- schema 变更：<是/否>
+- 数据迁移：<是/否>
+- 间接影响：<列出有影响的项>
+
+### 关键风险
+<列出 2-3 个关键风险>
+
+### 文档位置
+6aspecdoc/brown/<name>/artifacts/analysis.md
+
+### 下一步
+- 运行 `/6aspec:brown:proposal` → 进入需求提案阶段
+- 运行 `/6aspec:brown:continue` → 自动进入下一阶段
+```
+
+---
+
+## 用户补充信息时的处理
+
+当用户在 analyze 完成后补充遗漏的影响点或修正分析（未使用阶段命令）：
+1. 将补充内容整合到 analysis.md 对应章节
+2. 展示变更摘要
+3. 再次提示可继续补充或用命令推进
+4. **禁止**：不得自动进入下一阶段
+
+---
+
+## 防护措施
+
+- 只适用于标准级和完整级流程
+- 代码范围确认前不得生成问题清单
+- 问题必须按维度分组，不得使用扁平编号列表
+- 每次用户回复后必须更新 analysis.md，保持文档与对话同步
+- 追问时一次最多提出 1-2 个问题，不得连续追问超过 3 轮同一问题
+- 必须用户明确确认澄清完成后才能进入影响面分析
+- 影响面分析只做粗粒度评估（模块范围、schema变更、间接影响有/无），不做函数级映射
+- 间接影响的每一项必须明确写出结论（有影响/无影响），不得留空