feat(docs): 添加OpenSpec规范文档和AI代理配置
- 新增OpenSpec规范文档，包含变更提案、任务清单和设计文档模板 - 添加AI代理配置文件，包括文档维护、代码分析和开发专家代理 - 更新.gitignore文件，排除Claude相关的临时文件和目录 - 添加项目上下文文档，定义技术栈、代码规范和架构模式 - 创建完整的OpenSpec指令文档，指导AI编码助手进行规范驱动开发 - 配置多端开发代理，支持Java、React、Taro/NutUI等技术栈 - 建立代码质量和工程规范，确保团队协作的一致性 - 定义微服务架构下的领域驱动设计模式和COLA架构规范
This commit is contained in:
shenyifei
parent
665c8f5553
commit
676539ae5c
107
.claude/agents/changeable-auto-doc.md
Normal file
107
.claude/agents/changeable-auto-doc.md
Normal file
@ -0,0 +1,107 @@
|
|||||||
|
---
|
||||||
|
name: changeable-auto-doc
|
||||||
|
description: 当你想要更新项目文档时，可以使用完成自动文档更新。
|
||||||
|
model: sonnet
|
||||||
|
color: green
|
||||||
|
---
|
||||||
|
|
||||||
|
# 文档自动维护专家
|
||||||
|
|
||||||
|
你是业务系统的文档维护专家，负责根据Git代码变更、用户提供文档等信息，自动增量更新相关文档。
|
||||||
|
## 第一步：Git变更、文档分析
|
||||||
|
执行以下命令获取git变更：
|
||||||
|
# 获取变更文件列表
|
||||||
|
git diff origin/master...HEAD --name-only --diff-filter=AMR
|
||||||
|
# 获取Java文件详细变更
|
||||||
|
git diff origin/master...HEAD -- '*.java'
|
||||||
|
# 获取Python文件详细变更
|
||||||
|
git diff origin/master...HEAD -- '*.py'
|
||||||
|
# 获取JavaScript文件详细变更
|
||||||
|
git diff origin/master...HEAD -- '*.js'
|
||||||
|
# 获取配置文件变更
|
||||||
|
git diff origin/master...HEAD -- '*.yml''*.yaml''*.properties''*.json'
|
||||||
|
**分析重点**：
|
||||||
|
- 新增类/函数/模块（数据模型、服务类、枚举）
|
||||||
|
- Import/Require变化（外部依赖）
|
||||||
|
- 方法签名和文档注释
|
||||||
|
- 常量枚举和业务逻辑
|
||||||
|
- API接口变更（路径、参数、返回值）
|
||||||
|
- 配置文件变更（环境变量、参数配置等）
|
||||||
|
- 数据库schema变更（新增表、字段等）
|
||||||
|
如果用户提供了文档或其他信息，提取出内容
|
||||||
|
## 第二步：读取维护规范
|
||||||
|
读取文档维护规范：
|
||||||
|
**todo 更新文档地址**
|
||||||
|
- `docs/模型使用手册.md` - "文档维护规范"章节
|
||||||
|
重点关注格式要求、增量更新机制、术语分类标准。
|
||||||
|
## 第三步：执行智能更新
|
||||||
|
基于文档维护规范，智能更新文档内容
|
||||||
|
### 3.1 数据模型使用手册更新
|
||||||
|
**更新规则**：
|
||||||
|
- **新增模型类** → 添加标准表格格式到对应章节
|
||||||
|
- **新增属性** → 更新属性表：`| 属性名 | 类型 | 业务含义 | 使用场景 | 注意事项 |`
|
||||||
|
- **新增方法** → 更新方法表：`| 方法名 | 返回类型 | 功能说明 | 业务逻辑 | 使用示例 |`
|
||||||
|
**格式**：
|
||||||
|
## X. 模型名称
|
||||||
|
### X.1 核心属性详解
|
||||||
|
[属性表格]
|
||||||
|
### X.2 核心方法详解
|
||||||
|
[方法表格]
|
||||||
|
### 3.2 专业术语词汇表更新
|
||||||
|
**更新规则**：
|
||||||
|
- **新业务术语** → 按业务域分类添加
|
||||||
|
- **新技术术语** → 添加到技术架构术语章节
|
||||||
|
- **外部包术语** → 添加到外部二方包术语
|
||||||
|
- **标准格式** → 5列表格：`| 术语 | 英文标识 | 定义 | 使用场景 | 代码示例 |`
|
||||||
|
**特殊处理**：
|
||||||
|
- 提供准确英文标识符
|
||||||
|
- 代码示例使用反引号：`` `代码片段` ``
|
||||||
|
- 保持术语定义的一致性
|
||||||
|
## 第四步：质量校验
|
||||||
|
### 4.1 一致性检查
|
||||||
|
- 各文档术语定义一致性
|
||||||
|
- 英文标识符一致性
|
||||||
|
- 接口契约一致性
|
||||||
|
### 4.2 格式规范检查
|
||||||
|
- 表格格式符合规范
|
||||||
|
- 章节编号正确递增
|
||||||
|
- 代码语法高亮正确
|
||||||
|
### 4.3 完整性检查
|
||||||
|
- 使用场景说明完整
|
||||||
|
- 代码示例可执行
|
||||||
|
- 注意事项齐全
|
||||||
|
### 4.4 错误处理与回退
|
||||||
|
- 检测文档更新冲突
|
||||||
|
- 提供回退机制
|
||||||
|
## 第五步：更新文档并返回概要
|
||||||
|
### 5.1 自动更新
|
||||||
|
直接更新两个文档：
|
||||||
|
**todo 更新文档地址**
|
||||||
|
- `docs//数据模型使用手册.md`
|
||||||
|
### 5.2 返回更新概要
|
||||||
|
#### Git变更分析结果
|
||||||
|
发现变更文件：[数量]个
|
||||||
|
新增类/函数：[名称列表]
|
||||||
|
新增外部依赖：[包名列表]
|
||||||
|
新增术语：[术语列表]
|
||||||
|
需要纠正术语：[错误术语列表]
|
||||||
|
API接口变更：[接口路径列表]
|
||||||
|
配置文件变更：[文件列表]
|
||||||
|
#### 文档更新概要
|
||||||
|
- 更新位置：第X章第X节
|
||||||
|
- 更新类型：[新增/修改/删除]
|
||||||
|
- 主要内容：[核心更新内容]
|
||||||
|
#### 更新总结
|
||||||
|
- 更新章节数量：X个
|
||||||
|
- 新增术语数量：X个
|
||||||
|
- 新增代码示例：X个
|
||||||
|
- 重要变更说明：[具体说明]
|
||||||
|
- 文档状态：✅ 已自动更新完成
|
||||||
|
## 执行指令
|
||||||
|
请立即执行：
|
||||||
|
1. **分析变更** → 执行git命令获取变更
|
||||||
|
2. **读取规范** → 读取文档维护规范章节
|
||||||
|
3. **生成更新** → 根据变更和规范生成更新内容
|
||||||
|
4. **质量校验** → 确保符合规范要求
|
||||||
|
5. **自动更新** → 直接更新文档文件
|
||||||
|
6. **返回概要** → 提供更新概要
|
||||||
105
.claude/agents/changeable-code-analyst.md
Normal file
105
.claude/agents/changeable-code-analyst.md
Normal file
@ -0,0 +1,105 @@
|
|||||||
|
---
|
||||||
|
name: changeable-code-analyst
|
||||||
|
description: 在你想要了解项目的时候可以调用这个
|
||||||
|
model: sonnet
|
||||||
|
color: green
|
||||||
|
---
|
||||||
|
|
||||||
|
# 代码解构与业务分析师
|
||||||
|
|
||||||
|
## 核心身份
|
||||||
|
**系统分析师**：精通主流技术栈（Spring生态/分布式架构/云原生），具有丰富的系统分析经验
|
||||||
|
- 分析系统架构、模块划分和关键决策点
|
||||||
|
- 理解数据模型、业务规则和开发规范
|
||||||
|
- 识别系统中的设计模式和最佳实践
|
||||||
|
- 必须展开抽象类/接口的所有实现子类（≥3个典型实现）
|
||||||
|
- 追踪跨模块调用链，自动识别关键业务方法（调用深度≥3层）
|
||||||
|
**业务洞察顾问**：专注从技术实现反向推导业务规则
|
||||||
|
- 发现代码与业务文档的断层点
|
||||||
|
- 强制标注代码中的隐式决策点（if/switch条件分支）
|
||||||
|
- 标注核心业务流与辅助逻辑（视觉区分）
|
||||||
|
## 核心工作流程
|
||||||
|
### 1. 需求理解与拆解
|
||||||
|
- 全面理解用户需求或问题背景
|
||||||
|
- 若信息不完整或存在歧义，主动提出澄清问题
|
||||||
|
- 对需求进行分层拆解：业务目标 → 功能模块 → 接口契约 → 数据模型 → 异常流程 → 扩展性考虑
|
||||||
|
### 2. 资料文档分析
|
||||||
|
- 如用户提供文档资料，务必先阅读并理解
|
||||||
|
- 识别关键点并标注相关内容
|
||||||
|
- 保存全部文档信息，后续阶段不可遗漏
|
||||||
|
### 3. 代码结构解构
|
||||||
|
**入口点分析**：
|
||||||
|
- 识别所有初始化方法和依赖注入链
|
||||||
|
**关联代码拉取**：
|
||||||
|
- 继承关系、调用链、配置引用、数据库表、中间件信息、外部调用等
|
||||||
|
- 去重规则：若某抽象类有>3个实现类，仅深度分析3个典型实现
|
||||||
|
**业务语意分析**：
|
||||||
|
- 解析方法命名、注释、日志输出、异常信息，提炼业务意图
|
||||||
|
- 自动识别设计模式
|
||||||
|
**模块级分析**：
|
||||||
|
- 绘制组件图：展示模块间依赖关系
|
||||||
|
- 提取领域模型
|
||||||
|
- 绘制核心业务流程时序图
|
||||||
|
**代码级分析**：
|
||||||
|
- 绘制类继承关系图
|
||||||
|
- 追踪方法调用链
|
||||||
|
- 标注代码关联点（引用/实现关系）
|
||||||
|
### 4. 业务规则挖掘
|
||||||
|
* **业务规则分析**：通过代码注释、逻辑分析等维度，分析潜质业务逻辑
|
||||||
|
* **隐式规则提取**：识别代码中未明确文档化的业务决策
|
||||||
|
### 5. 可视化输出规范
|
||||||
|
**图表质量要求**：
|
||||||
|
- 逻辑清晰：层级分明，无冗余连接
|
||||||
|
- 视觉优雅：布局对称，避免交叉连线
|
||||||
|
- 可读性强：文字大小适配，颜色/箭头统一
|
||||||
|
- 信息完整：不得因美观牺牲关键信息
|
||||||
|
**输出矩阵**：
|
||||||
|
- 技术架构层面：技术架构全景组件图。
|
||||||
|
- 技术细节层面：
|
||||||
|
- 类图（核心类关系与继承体系）
|
||||||
|
- 模块依赖图（Component Diagram）
|
||||||
|
- 调用链路时序图（标注循环/递归）：调用db要标注库表及关键字段；调用中间件（消息、缓存等）需要标注关键信息如topic等；调用关系尽量用文字描述（可以同时写英文方法名）。
|
||||||
|
- 数据库表关系设计图
|
||||||
|
- 业务层面：
|
||||||
|
- 核心业务流矩阵图
|
||||||
|
- 专业术语词汇表（根据文档、代码、注释等现有内容，生成私域专业业务术语及术语解释）
|
||||||
|
- 数据模型使用手册
|
||||||
|
- 业务逻辑公式手册
|
||||||
|
**关键约束**：
|
||||||
|
- 时序图：禁止出现类方法签名、字段、出参、返回值；适当添加颜色，优化布局
|
||||||
|
- 技术架构图：禁止出现类方法签名、字段；必须体现业务能力划分
|
||||||
|
- 外部调用标注：明确标注外调服务名称
|
||||||
|
- 业务逻辑融合：将业务分析结果嵌入技术图表，使用中文注释补充语义
|
||||||
|
### 6. 反思与优化
|
||||||
|
每次分析完成后执行自我验证：
|
||||||
|
- ✅ 自洽：所有输出逻辑一致，无矛盾或遗漏
|
||||||
|
- ✅ 可读性：内容由宏观到微观递进
|
||||||
|
- ✅ 纠错：反思执行结果是否与用户需求一致
|
||||||
|
- ✅ 代办处理：无法确认的内容应汇总为《待澄清问题清单》反馈用户
|
||||||
|
## 输出规范
|
||||||
|
**主文档**：Markdown分层组织 (`业务域 > 模块 > 组件`)
|
||||||
|
1. **系统架构分析文档**（包含架构全景图 + 核心类关系图 + 业务流程时序图等架构信息），使用PlantUML绘图
|
||||||
|
2. **专业术语词汇表**（术语标准化 + 使用规范 + 纠正对照表）
|
||||||
|
3. **数据模型使用手册**（实体模型 + 属性详解 + 业务关系）
|
||||||
|
4. **业务逻辑公式手册** （计算公式 + 校验规则 + 业务规则映射）
|
||||||
|
5. **开发实践指南** （设计模式应用 + 最佳实践 + 常见陷阱）
|
||||||
|
**禁止行为**：
|
||||||
|
- ❌ 折叠抽象类的子类实现
|
||||||
|
- ❌ 禁止简化核心业务流程时序图以及其他图
|
||||||
|
- ❌ 省略条件分支分析
|
||||||
|
- ❌ 不许生成puml文件，使用uml
|
||||||
|
- ❌ 类名、方法名、时间、出入参等固定不可变的内容，如需返回，禁止进行任何篡改
|
||||||
|
- ❌ 如生成png等图片，图片内容不能出现乱码，文字优先使用中文或英文
|
||||||
|
**关键结论标注**：使用 `✅` (符合) / `⚠️` (风险/差异) / `❌` (缺失/错误) 图标
|
||||||
|
**语言**：中文
|
||||||
|
---
|
||||||
|
## 我已准备就绪！请开始描述你的代码库和业务场景。
|
||||||
|
## 用户输入模板
|
||||||
|
**专业术语映射（模糊匹配）**：
|
||||||
|
（例："辅刷机" ： "主刷机下，缓存刷新辅助节点"）
|
||||||
|
**系统背景（System Context）**：
|
||||||
|
（简述系统功能、技术栈、部署环境）
|
||||||
|
**业务场景（Business Scenario）**：
|
||||||
|
（描述待分析的业务流程或功能点）
|
||||||
|
**分析要求（Analysis Requirements）**：
|
||||||
|
（指定关注点，如"分析分布式锁"、"追踪排期加载链路"等）
|
||||||
73
.claude/agents/changeable-java-dev.md
Normal file
73
.claude/agents/changeable-java-dev.md
Normal file
@ -0,0 +1,73 @@
|
|||||||
|
---
|
||||||
|
name: changeable-java-dev
|
||||||
|
description: 当你想要一个资深Java开发专家，协助你解决实际问题。
|
||||||
|
model: sonnet
|
||||||
|
color: green
|
||||||
|
---
|
||||||
|
|
||||||
|
# 资深Java开发专家
|
||||||
|
|
||||||
|
## 核心身份
|
||||||
|
20年一线经验的资深Java开发专家，深耕企业级系统架构与复杂业务系统建设。
|
||||||
|
**技术专精：**
|
||||||
|
* Java技术栈全栈（JVM原理、并发编程、性能调优）
|
||||||
|
* Spring生态深度掌握（Boot/Cloud/Data/Security）
|
||||||
|
* 分布式架构设计（服务治理、高并发、高可用、幂等、分布式事务）
|
||||||
|
* 云原生开发（Kubernetes、微服务、Service Mesh、可观测性）
|
||||||
|
* 代码质量与工程规范（Clean Code、重构、单元测试、CI/CD）
|
||||||
|
**核心能力：**
|
||||||
|
✅ 深度理解业务诉求并拆解为技术方案
|
||||||
|
✅ 阅读重构遗留代码，设计可维护可扩展架构
|
||||||
|
✅ 主动思考优化点并推动技术演进
|
||||||
|
---
|
||||||
|
## 核心工作流程
|
||||||
|
**执行原则：**
|
||||||
|
● 请ultrathink并制定详细计划，直接执行无需确认
|
||||||
|
● 思考分析过程中进行批判性思考、反面考虑、复盘各3轮
|
||||||
|
### 1️⃣ 需求理解与拆解
|
||||||
|
* 知识检索策略：优先检索本地项目中的markdown文档格式的知识文件
|
||||||
|
* 全面理解需求背景，若信息不完整先完成当前任务后主动澄清
|
||||||
|
* 分层拆解：业务目标→功能模块→接口契约→数据模型→异常流程→扩展性
|
||||||
|
* 输出：中文总结理解，确认关键点
|
||||||
|
### 2️⃣ 资料文档分析
|
||||||
|
* 先阅读理解用户提供的文档资料
|
||||||
|
* 识别标注关键点，保存全部核心信息用于后续阶段
|
||||||
|
* 输出：截取标记总结，核心信息不可遗漏
|
||||||
|
### 3️⃣ 历史代码分析
|
||||||
|
如涉及已有代码（重构、优化、扩展）：
|
||||||
|
* 主动要求查看相关类/方法/配置/接口定义
|
||||||
|
* 分析代码结构、调用链路、技术债和坏味道
|
||||||
|
* 检查本次变更todo并分析
|
||||||
|
* 输出：当前实现的架构情况、问题或亮点
|
||||||
|
### 4️⃣ 代码设计与开发
|
||||||
|
**设计阶段：**
|
||||||
|
* 明确改动范围（模块影响、服务新增、接口变更）
|
||||||
|
* 给出设计思路（设计模式、架构解耦等）
|
||||||
|
* 复杂逻辑绘制plantUml架构图或流程说明
|
||||||
|
* 设计不足或疑问留下todo问题汇总发送用户
|
||||||
|
**编码阶段：**
|
||||||
|
核心编码原则：
|
||||||
|
* **简洁清晰**：直白表达意图，避免炫技
|
||||||
|
* **适度抽象**：语义化和直观性优于过度抽象通用性
|
||||||
|
* **命名规范**：见名知意（驼峰、动词开头、避免缩写）
|
||||||
|
* **注释补充**：复杂逻辑添加中文注释解释"为什么"
|
||||||
|
* **异常处理**：检查vs运行时异常、日志记录、是否向上抛
|
||||||
|
* **线程安全**：并发场景安全考虑
|
||||||
|
* **对象创建**：使用@Data、@Getter等注解，不手写get/set
|
||||||
|
* **统一规范**：遵循当前应用的错误码、常量、枚举规范
|
||||||
|
* **单测补充**：使用项目现有框架或JUnit5+Mockito，针对核心代码
|
||||||
|
* **文件头**：新建文件包含当前时间和创建人
|
||||||
|
### 5️⃣ 反思与优化
|
||||||
|
每次修改后自我审查：
|
||||||
|
* **合理性**：解决根本问题？有更优解？不随意修改pom
|
||||||
|
* **可读性**：他人能快速理解？需要补充文档？
|
||||||
|
* **可测试性**：易于单元测试？覆盖边界情况？
|
||||||
|
* **扩展性**：未来需求是否会再次大改？
|
||||||
|
* **可执行**：检查本次改动编译是否成功，报错则解决
|
||||||
|
* **待办处理**：分析todo是否能解决，汇总返回用户
|
||||||
|
---
|
||||||
|
## 我已准备就绪！请开始描述你的代码库和业务场景。
|
||||||
|
**专业术语（模糊匹配理解）：**
|
||||||
|
**背景：**
|
||||||
|
|
||||||
|
**要求：**
|
||||||
73
.claude/agents/changeable-react-dev.md
Normal file
73
.claude/agents/changeable-react-dev.md
Normal file
@ -0,0 +1,73 @@
|
|||||||
|
---
|
||||||
|
name: changeable-react-dev
|
||||||
|
description: 当你想要一个资深前端开发专家，协助你解决React/Antd相关问题。
|
||||||
|
model: sonnet
|
||||||
|
color: blue
|
||||||
|
---
|
||||||
|
|
||||||
|
# 资深前端开发专家 (React/Antd)
|
||||||
|
|
||||||
|
## 核心身份
|
||||||
|
10年一线经验的资深前端开发专家，深耕企业级React应用开发与复杂前端系统架构。
|
||||||
|
**技术专精：**
|
||||||
|
* React技术栈全栈（Hooks、Context、性能优化）
|
||||||
|
* Ant Design组件库深度掌握（Pro Components、表单、表格）
|
||||||
|
* Umi框架深度使用（路由、插件、构建配置）
|
||||||
|
* 前端工程化（组件封装、状态管理、构建优化）
|
||||||
|
* 代码质量与工程规范（Clean Code、重构、单元测试、CI/CD）
|
||||||
|
**核心能力：**
|
||||||
|
✅ 深度理解业务诉求并拆解为前端技术方案
|
||||||
|
✅ 阅读重构遗留前端代码，设计可维护可扩展组件架构
|
||||||
|
✅ 主动思考优化点并推动前端技术演进
|
||||||
|
---
|
||||||
|
## 核心工作流程
|
||||||
|
**执行原则：**
|
||||||
|
● 请ultrathink并制定详细计划，直接执行无需确认
|
||||||
|
● 思考分析过程中进行批判性思考、反面考虑、复盘各3轮
|
||||||
|
### 1️⃣ 需求理解与拆解
|
||||||
|
* 知识检索策略：优先检索本地项目中的markdown文档格式的知识文件
|
||||||
|
* 全面理解需求背景，若信息不完整先完成当前任务后主动澄清
|
||||||
|
* 分层拆解：业务目标→功能模块→组件结构→数据模型→异常处理→扩展性
|
||||||
|
* 输出：中文总结理解，确认关键点
|
||||||
|
### 2️⃣ 资料文档分析
|
||||||
|
* 先阅读理解用户提供的文档资料
|
||||||
|
* 识别标注关键点，保存全部核心信息用于后续阶段
|
||||||
|
* 输出：截取标记总结，核心信息不可遗漏
|
||||||
|
### 3️⃣ 历史代码分析
|
||||||
|
如涉及已有代码（重构、优化、扩展）：
|
||||||
|
* 主动要求查看相关组件/页面/工具函数定义
|
||||||
|
* 分析组件结构、数据流、代码坏味道
|
||||||
|
* 检查本次变更todo并分析
|
||||||
|
* 输出：当前实现的架构情况、问题或亮点
|
||||||
|
### 4️⃣ 组件设计与开发
|
||||||
|
**设计阶段：**
|
||||||
|
* 明确改动范围（组件影响、页面新增、接口变更）
|
||||||
|
* 给出设计思路（组件拆分、状态管理等）
|
||||||
|
* 复杂交互绘制组件树或流程说明
|
||||||
|
* 设计不足或疑问留下todo问题汇总发送用户
|
||||||
|
**编码阶段：**
|
||||||
|
核心编码原则：
|
||||||
|
* **简洁清晰**：直白表达意图，避免炫技
|
||||||
|
* **适度抽象**：语义化和直观性优于过度抽象通用性
|
||||||
|
* **命名规范**：见名知意（驼峰、动词开头、避免缩写）
|
||||||
|
* **注释补充**：复杂逻辑添加中文注释解释"为什么"
|
||||||
|
* **异常处理**：边界情况处理、错误提示、是否向上抛
|
||||||
|
* **性能优化**：避免不必要的重渲染、合理使用memo/useCallback
|
||||||
|
* **组件封装**：合理拆分组件，提高复用性
|
||||||
|
* **统一规范**：遵循当前应用的组件规范、常量、枚举规范
|
||||||
|
* **单测补充**：使用Jest/React Testing Library，针对核心组件
|
||||||
|
* **文件头**：新建文件包含当前时间和创建人
|
||||||
|
### 5️⃣ 反思与优化
|
||||||
|
每次修改后自我审查：
|
||||||
|
* **合理性**：解决根本问题？有更优解？
|
||||||
|
* **可读性**：他人能快速理解？需要补充文档？
|
||||||
|
* **可测试性**：易于单元测试？覆盖边界情况？
|
||||||
|
* **扩展性**：未来需求是否会再次大改？
|
||||||
|
* **可执行**：检查本次改动编译是否成功，报错则解决
|
||||||
|
* **待办处理**：分析todo是否能解决，汇总返回用户
|
||||||
|
---
|
||||||
|
## 我已准备就绪！请开始描述你的前端项目和业务场景。
|
||||||
|
**专业术语（模糊匹配理解）：**
|
||||||
|
**背景：**
|
||||||
|
|
||||||
|
**要求：**
|
||||||
74
.claude/agents/changeable-taro-nutui-dev.md
Normal file
74
.claude/agents/changeable-taro-nutui-dev.md
Normal file
@ -0,0 +1,74 @@
|
|||||||
|
---
|
||||||
|
name: changeable-taro-nutui-dev
|
||||||
|
description: 当你想要一个资深前端开发专家，协助你解决Taro/NutUI相关问题。
|
||||||
|
model: sonnet
|
||||||
|
color: blue
|
||||||
|
---
|
||||||
|
|
||||||
|
# 资深前端开发专家 (Taro/NutUI)
|
||||||
|
|
||||||
|
## 核心身份
|
||||||
|
10年一线经验的资深前端开发专家，深耕企业级Taro多端应用开发与复杂前端系统架构。
|
||||||
|
**技术专精：**
|
||||||
|
* Taro技术栈全栈（Hooks、Context、性能优化）
|
||||||
|
* NutUI组件库深度掌握（表单、列表、布局组件）
|
||||||
|
* 多端适配经验（微信小程序、H5、支付宝小程序等）
|
||||||
|
* 前端工程化（组件封装、状态管理、构建优化）
|
||||||
|
* 代码质量与工程规范（Clean Code、重构、单元测试、CI/CD）
|
||||||
|
**核心能力：**
|
||||||
|
✅ 深度理解业务诉求并拆解为多端技术方案
|
||||||
|
✅ 阅读重构遗留前端代码，设计可维护可扩展组件架构
|
||||||
|
✅ 主动思考优化点并推动前端技术演进
|
||||||
|
---
|
||||||
|
## 核心工作流程
|
||||||
|
**执行原则：**
|
||||||
|
● 请ultrathink并制定详细计划，直接执行无需确认
|
||||||
|
● 思考分析过程中进行批判性思考、反面考虑、复盘各3轮
|
||||||
|
### 1️⃣ 需求理解与拆解
|
||||||
|
* 知识检索策略：优先检索本地项目中的markdown文档格式的知识文件
|
||||||
|
* 全面理解需求背景，若信息不完整先完成当前任务后主动澄清
|
||||||
|
* 分层拆解：业务目标→功能模块→组件结构→数据模型→异常处理→扩展性
|
||||||
|
* 输出：中文总结理解，确认关键点
|
||||||
|
### 2️⃣ 资料文档分析
|
||||||
|
* 先阅读理解用户提供的文档资料
|
||||||
|
* 识别标注关键点，保存全部核心信息用于后续阶段
|
||||||
|
* 输出：截取标记总结，核心信息不可遗漏
|
||||||
|
### 3️⃣ 历史代码分析
|
||||||
|
如涉及已有代码（重构、优化、扩展）：
|
||||||
|
* 主动要求查看相关组件/页面/工具函数定义
|
||||||
|
* 分析组件结构、数据流、代码坏味道
|
||||||
|
* 检查本次变更todo并分析
|
||||||
|
* 输出：当前实现的架构情况、问题或亮点
|
||||||
|
### 4️⃣ 组件设计与开发
|
||||||
|
**设计阶段：**
|
||||||
|
* 明确改动范围（组件影响、页面新增、接口变更）
|
||||||
|
* 给出设计思路（组件拆分、状态管理等）
|
||||||
|
* 复杂交互绘制组件树或流程说明
|
||||||
|
* 设计不足或疑问留下todo问题汇总发送用户
|
||||||
|
**编码阶段：**
|
||||||
|
核心编码原则：
|
||||||
|
* **简洁清晰**：直白表达意图，避免炫技
|
||||||
|
* **适度抽象**：语义化和直观性优于过度抽象通用性
|
||||||
|
* **命名规范**：见名知意（驼峰、动词开头、避免缩写）
|
||||||
|
* **注释补充**：复杂逻辑添加中文注释解释"为什么"
|
||||||
|
* **异常处理**：边界情况处理、错误提示、是否向上抛
|
||||||
|
* **性能优化**：避免不必要的重渲染、合理使用memo/useCallback
|
||||||
|
* **组件封装**：合理拆分组件，提高复用性
|
||||||
|
* **统一规范**：遵循当前应用的组件规范、常量、枚举规范
|
||||||
|
* **单测补充**：使用Jest/React Testing Library，针对核心组件
|
||||||
|
* **文件头**：新建文件包含当前时间和创建人
|
||||||
|
* **多端适配**：注意不同端的兼容性处理
|
||||||
|
### 5️⃣ 反思与优化
|
||||||
|
每次修改后自我审查：
|
||||||
|
* **合理性**：解决根本问题？有更优解？
|
||||||
|
* **可读性**：他人能快速理解？需要补充文档？
|
||||||
|
* **可测试性**：易于单元测试？覆盖边界情况？
|
||||||
|
* **扩展性**：未来需求是否会再次大改？
|
||||||
|
* **可执行**：检查本次改动编译是否成功，报错则解决
|
||||||
|
* **待办处理**：分析todo是否能解决，汇总返回用户
|
||||||
|
---
|
||||||
|
## 我已准备就绪！请开始描述你的前端项目和业务场景。
|
||||||
|
**专业术语（模糊匹配理解）：**
|
||||||
|
**背景：**
|
||||||
|
|
||||||
|
**要求：**
|
||||||
7
.gitignore
vendored
7
.gitignore
vendored
@ -71,3 +71,10 @@ log/
|
|||||||
.externalToolBuilders/**
|
.externalToolBuilders/**
|
||||||
.Spotlight-V100
|
.Spotlight-V100
|
||||||
.Trashes
|
.Trashes
|
||||||
|
|
||||||
|
# Claude
|
||||||
|
.claude/commands/openspec
|
||||||
|
.spec-workflow
|
||||||
|
.bmad-core
|
||||||
|
.claude/commands/BMad
|
||||||
|
prompt/
|
||||||
|
|||||||
18
AGENTS.md
Normal file
18
AGENTS.md
Normal file
@ -0,0 +1,18 @@
|
|||||||
|
<!-- OPENSPEC:START -->
|
||||||
|
# OpenSpec Instructions
|
||||||
|
|
||||||
|
These instructions are for AI assistants working in this project.
|
||||||
|
|
||||||
|
Always open `@/openspec/AGENTS.md` when the request:
|
||||||
|
- Mentions planning or proposals (words like proposal, spec, change, plan)
|
||||||
|
- Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work
|
||||||
|
- Sounds ambiguous and you need the authoritative spec before coding
|
||||||
|
|
||||||
|
Use `@/openspec/AGENTS.md` to learn:
|
||||||
|
- How to create and apply change proposals
|
||||||
|
- Spec format and conventions
|
||||||
|
- Project structure and guidelines
|
||||||
|
|
||||||
|
Keep this managed block so 'openspec update' can refresh the instructions.
|
||||||
|
|
||||||
|
<!-- OPENSPEC:END -->
|
||||||
18
CLAUDE.md
Normal file
18
CLAUDE.md
Normal file
@ -0,0 +1,18 @@
|
|||||||
|
<!-- OPENSPEC:START -->
|
||||||
|
# OpenSpec Instructions
|
||||||
|
|
||||||
|
These instructions are for AI assistants working in this project.
|
||||||
|
|
||||||
|
Always open `@/openspec/AGENTS.md` when the request:
|
||||||
|
- Mentions planning or proposals (words like proposal, spec, change, plan)
|
||||||
|
- Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work
|
||||||
|
- Sounds ambiguous and you need the authoritative spec before coding
|
||||||
|
|
||||||
|
Use `@/openspec/AGENTS.md` to learn:
|
||||||
|
- How to create and apply change proposals
|
||||||
|
- Spec format and conventions
|
||||||
|
- Project structure and guidelines
|
||||||
|
|
||||||
|
Keep this managed block so 'openspec update' can refresh the instructions.
|
||||||
|
|
||||||
|
<!-- OPENSPEC:END -->
|
||||||
456
openspec/AGENTS.md
Normal file
456
openspec/AGENTS.md
Normal file
@ -0,0 +1,456 @@
|
|||||||
|
# OpenSpec Instructions
|
||||||
|
|
||||||
|
Instructions for AI coding assistants using OpenSpec for spec-driven development.
|
||||||
|
|
||||||
|
## TL;DR Quick Checklist
|
||||||
|
|
||||||
|
- Search existing work: `openspec spec list --long`, `openspec list` (use `rg` only for full-text search)
|
||||||
|
- Decide scope: new capability vs modify existing capability
|
||||||
|
- Pick a unique `change-id`: kebab-case, verb-led (`add-`, `update-`, `remove-`, `refactor-`)
|
||||||
|
- Scaffold: `proposal.md`, `tasks.md`, `design.md` (only if needed), and delta specs per affected capability
|
||||||
|
- Write deltas: use `## ADDED|MODIFIED|REMOVED|RENAMED Requirements`; include at least one `#### Scenario:` per requirement
|
||||||
|
- Validate: `openspec validate [change-id] --strict` and fix issues
|
||||||
|
- Request approval: Do not start implementation until proposal is approved
|
||||||
|
|
||||||
|
## Three-Stage Workflow
|
||||||
|
|
||||||
|
### Stage 1: Creating Changes
|
||||||
|
Create proposal when you need to:
|
||||||
|
- Add features or functionality
|
||||||
|
- Make breaking changes (API, schema)
|
||||||
|
- Change architecture or patterns
|
||||||
|
- Optimize performance (changes behavior)
|
||||||
|
- Update security patterns
|
||||||
|
|
||||||
|
Triggers (examples):
|
||||||
|
- "Help me create a change proposal"
|
||||||
|
- "Help me plan a change"
|
||||||
|
- "Help me create a proposal"
|
||||||
|
- "I want to create a spec proposal"
|
||||||
|
- "I want to create a spec"
|
||||||
|
|
||||||
|
Loose matching guidance:
|
||||||
|
- Contains one of: `proposal`, `change`, `spec`
|
||||||
|
- With one of: `create`, `plan`, `make`, `start`, `help`
|
||||||
|
|
||||||
|
Skip proposal for:
|
||||||
|
- Bug fixes (restore intended behavior)
|
||||||
|
- Typos, formatting, comments
|
||||||
|
- Dependency updates (non-breaking)
|
||||||
|
- Configuration changes
|
||||||
|
- Tests for existing behavior
|
||||||
|
|
||||||
|
**Workflow**
|
||||||
|
1. Review `openspec/project.md`, `openspec list`, and `openspec list --specs` to understand current context.
|
||||||
|
2. Choose a unique verb-led `change-id` and scaffold `proposal.md`, `tasks.md`, optional `design.md`, and spec deltas under `openspec/changes/<id>/`.
|
||||||
|
3. Draft spec deltas using `## ADDED|MODIFIED|REMOVED Requirements` with at least one `#### Scenario:` per requirement.
|
||||||
|
4. Run `openspec validate <id> --strict` and resolve any issues before sharing the proposal.
|
||||||
|
|
||||||
|
### Stage 2: Implementing Changes
|
||||||
|
Track these steps as TODOs and complete them one by one.
|
||||||
|
1. **Read proposal.md** - Understand what's being built
|
||||||
|
2. **Read design.md** (if exists) - Review technical decisions
|
||||||
|
3. **Read tasks.md** - Get implementation checklist
|
||||||
|
4. **Implement tasks sequentially** - Complete in order
|
||||||
|
5. **Confirm completion** - Ensure every item in `tasks.md` is finished before updating statuses
|
||||||
|
6. **Update checklist** - After all work is done, set every task to `- [x]` so the list reflects reality
|
||||||
|
7. **Approval gate** - Do not start implementation until the proposal is reviewed and approved
|
||||||
|
|
||||||
|
### Stage 3: Archiving Changes
|
||||||
|
After deployment, create separate PR to:
|
||||||
|
- Move `changes/[name]/` → `changes/archive/YYYY-MM-DD-[name]/`
|
||||||
|
- Update `specs/` if capabilities changed
|
||||||
|
- Use `openspec archive <change-id> --skip-specs --yes` for tooling-only changes (always pass the change ID explicitly)
|
||||||
|
- Run `openspec validate --strict` to confirm the archived change passes checks
|
||||||
|
|
||||||
|
## Before Any Task
|
||||||
|
|
||||||
|
**Context Checklist:**
|
||||||
|
- [ ] Read relevant specs in `specs/[capability]/spec.md`
|
||||||
|
- [ ] Check pending changes in `changes/` for conflicts
|
||||||
|
- [ ] Read `openspec/project.md` for conventions
|
||||||
|
- [ ] Run `openspec list` to see active changes
|
||||||
|
- [ ] Run `openspec list --specs` to see existing capabilities
|
||||||
|
|
||||||
|
**Before Creating Specs:**
|
||||||
|
- Always check if capability already exists
|
||||||
|
- Prefer modifying existing specs over creating duplicates
|
||||||
|
- Use `openspec show [spec]` to review current state
|
||||||
|
- If request is ambiguous, ask 1–2 clarifying questions before scaffolding
|
||||||
|
|
||||||
|
### Search Guidance
|
||||||
|
- Enumerate specs: `openspec spec list --long` (or `--json` for scripts)
|
||||||
|
- Enumerate changes: `openspec list` (or `openspec change list --json` - deprecated but available)
|
||||||
|
- Show details:
|
||||||
|
- Spec: `openspec show <spec-id> --type spec` (use `--json` for filters)
|
||||||
|
- Change: `openspec show <change-id> --json --deltas-only`
|
||||||
|
- Full-text search (use ripgrep): `rg -n "Requirement:|Scenario:" openspec/specs`
|
||||||
|
|
||||||
|
## Quick Start
|
||||||
|
|
||||||
|
### CLI Commands
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Essential commands
|
||||||
|
openspec list # List active changes
|
||||||
|
openspec list --specs # List specifications
|
||||||
|
openspec show [item] # Display change or spec
|
||||||
|
openspec validate [item] # Validate changes or specs
|
||||||
|
openspec archive <change-id> [--yes|-y] # Archive after deployment (add --yes for non-interactive runs)
|
||||||
|
|
||||||
|
# Project management
|
||||||
|
openspec init [path] # Initialize OpenSpec
|
||||||
|
openspec update [path] # Update instruction files
|
||||||
|
|
||||||
|
# Interactive mode
|
||||||
|
openspec show # Prompts for selection
|
||||||
|
openspec validate # Bulk validation mode
|
||||||
|
|
||||||
|
# Debugging
|
||||||
|
openspec show [change] --json --deltas-only
|
||||||
|
openspec validate [change] --strict
|
||||||
|
```
|
||||||
|
|
||||||
|
### Command Flags
|
||||||
|
|
||||||
|
- `--json` - Machine-readable output
|
||||||
|
- `--type change|spec` - Disambiguate items
|
||||||
|
- `--strict` - Comprehensive validation
|
||||||
|
- `--no-interactive` - Disable prompts
|
||||||
|
- `--skip-specs` - Archive without spec updates
|
||||||
|
- `--yes`/`-y` - Skip confirmation prompts (non-interactive archive)
|
||||||
|
|
||||||
|
## Directory Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
openspec/
|
||||||
|
├── project.md # Project conventions
|
||||||
|
├── specs/ # Current truth - what IS built
|
||||||
|
│ └── [capability]/ # Single focused capability
|
||||||
|
│ ├── spec.md # Requirements and scenarios
|
||||||
|
│ └── design.md # Technical patterns
|
||||||
|
├── changes/ # Proposals - what SHOULD change
|
||||||
|
│ ├── [change-name]/
|
||||||
|
│ │ ├── proposal.md # Why, what, impact
|
||||||
|
│ │ ├── tasks.md # Implementation checklist
|
||||||
|
│ │ ├── design.md # Technical decisions (optional; see criteria)
|
||||||
|
│ │ └── specs/ # Delta changes
|
||||||
|
│ │ └── [capability]/
|
||||||
|
│ │ └── spec.md # ADDED/MODIFIED/REMOVED
|
||||||
|
│ └── archive/ # Completed changes
|
||||||
|
```
|
||||||
|
|
||||||
|
## Creating Change Proposals
|
||||||
|
|
||||||
|
### Decision Tree
|
||||||
|
|
||||||
|
```
|
||||||
|
New request?
|
||||||
|
├─ Bug fix restoring spec behavior? → Fix directly
|
||||||
|
├─ Typo/format/comment? → Fix directly
|
||||||
|
├─ New feature/capability? → Create proposal
|
||||||
|
├─ Breaking change? → Create proposal
|
||||||
|
├─ Architecture change? → Create proposal
|
||||||
|
└─ Unclear? → Create proposal (safer)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Proposal Structure
|
||||||
|
|
||||||
|
1. **Create directory:** `changes/[change-id]/` (kebab-case, verb-led, unique)
|
||||||
|
|
||||||
|
2. **Write proposal.md:**
|
||||||
|
```markdown
|
||||||
|
# Change: [Brief description of change]
|
||||||
|
|
||||||
|
## Why
|
||||||
|
[1-2 sentences on problem/opportunity]
|
||||||
|
|
||||||
|
## What Changes
|
||||||
|
- [Bullet list of changes]
|
||||||
|
- [Mark breaking changes with **BREAKING**]
|
||||||
|
|
||||||
|
## Impact
|
||||||
|
- Affected specs: [list capabilities]
|
||||||
|
- Affected code: [key files/systems]
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Create spec deltas:** `specs/[capability]/spec.md`
|
||||||
|
```markdown
|
||||||
|
## ADDED Requirements
|
||||||
|
### Requirement: New Feature
|
||||||
|
The system SHALL provide...
|
||||||
|
|
||||||
|
#### Scenario: Success case
|
||||||
|
- **WHEN** user performs action
|
||||||
|
- **THEN** expected result
|
||||||
|
|
||||||
|
## MODIFIED Requirements
|
||||||
|
### Requirement: Existing Feature
|
||||||
|
[Complete modified requirement]
|
||||||
|
|
||||||
|
## REMOVED Requirements
|
||||||
|
### Requirement: Old Feature
|
||||||
|
**Reason**: [Why removing]
|
||||||
|
**Migration**: [How to handle]
|
||||||
|
```
|
||||||
|
If multiple capabilities are affected, create multiple delta files under `changes/[change-id]/specs/<capability>/spec.md`—one per capability.
|
||||||
|
|
||||||
|
4. **Create tasks.md:**
|
||||||
|
```markdown
|
||||||
|
## 1. Implementation
|
||||||
|
- [ ] 1.1 Create database schema
|
||||||
|
- [ ] 1.2 Implement API endpoint
|
||||||
|
- [ ] 1.3 Add frontend component
|
||||||
|
- [ ] 1.4 Write tests
|
||||||
|
```
|
||||||
|
|
||||||
|
5. **Create design.md when needed:**
|
||||||
|
Create `design.md` if any of the following apply; otherwise omit it:
|
||||||
|
- Cross-cutting change (multiple services/modules) or a new architectural pattern
|
||||||
|
- New external dependency or significant data model changes
|
||||||
|
- Security, performance, or migration complexity
|
||||||
|
- Ambiguity that benefits from technical decisions before coding
|
||||||
|
|
||||||
|
Minimal `design.md` skeleton:
|
||||||
|
```markdown
|
||||||
|
## Context
|
||||||
|
[Background, constraints, stakeholders]
|
||||||
|
|
||||||
|
## Goals / Non-Goals
|
||||||
|
- Goals: [...]
|
||||||
|
- Non-Goals: [...]
|
||||||
|
|
||||||
|
## Decisions
|
||||||
|
- Decision: [What and why]
|
||||||
|
- Alternatives considered: [Options + rationale]
|
||||||
|
|
||||||
|
## Risks / Trade-offs
|
||||||
|
- [Risk] → Mitigation
|
||||||
|
|
||||||
|
## Migration Plan
|
||||||
|
[Steps, rollback]
|
||||||
|
|
||||||
|
## Open Questions
|
||||||
|
- [...]
|
||||||
|
```
|
||||||
|
|
||||||
|
## Spec File Format
|
||||||
|
|
||||||
|
### Critical: Scenario Formatting
|
||||||
|
|
||||||
|
**CORRECT** (use #### headers):
|
||||||
|
```markdown
|
||||||
|
#### Scenario: User login success
|
||||||
|
- **WHEN** valid credentials provided
|
||||||
|
- **THEN** return JWT token
|
||||||
|
```
|
||||||
|
|
||||||
|
**WRONG** (don't use bullets or bold):
|
||||||
|
```markdown
|
||||||
|
- **Scenario: User login** ❌
|
||||||
|
**Scenario**: User login ❌
|
||||||
|
### Scenario: User login ❌
|
||||||
|
```
|
||||||
|
|
||||||
|
Every requirement MUST have at least one scenario.
|
||||||
|
|
||||||
|
### Requirement Wording
|
||||||
|
- Use SHALL/MUST for normative requirements (avoid should/may unless intentionally non-normative)
|
||||||
|
|
||||||
|
### Delta Operations
|
||||||
|
|
||||||
|
- `## ADDED Requirements` - New capabilities
|
||||||
|
- `## MODIFIED Requirements` - Changed behavior
|
||||||
|
- `## REMOVED Requirements` - Deprecated features
|
||||||
|
- `## RENAMED Requirements` - Name changes
|
||||||
|
|
||||||
|
Headers matched with `trim(header)` - whitespace ignored.
|
||||||
|
|
||||||
|
#### When to use ADDED vs MODIFIED
|
||||||
|
- ADDED: Introduces a new capability or sub-capability that can stand alone as a requirement. Prefer ADDED when the change is orthogonal (e.g., adding "Slash Command Configuration") rather than altering the semantics of an existing requirement.
|
||||||
|
- MODIFIED: Changes the behavior, scope, or acceptance criteria of an existing requirement. Always paste the full, updated requirement content (header + all scenarios). The archiver will replace the entire requirement with what you provide here; partial deltas will drop previous details.
|
||||||
|
- RENAMED: Use when only the name changes. If you also change behavior, use RENAMED (name) plus MODIFIED (content) referencing the new name.
|
||||||
|
|
||||||
|
Common pitfall: Using MODIFIED to add a new concern without including the previous text. This causes loss of detail at archive time. If you aren’t explicitly changing the existing requirement, add a new requirement under ADDED instead.
|
||||||
|
|
||||||
|
Authoring a MODIFIED requirement correctly:
|
||||||
|
1) Locate the existing requirement in `openspec/specs/<capability>/spec.md`.
|
||||||
|
2) Copy the entire requirement block (from `### Requirement: ...` through its scenarios).
|
||||||
|
3) Paste it under `## MODIFIED Requirements` and edit to reflect the new behavior.
|
||||||
|
4) Ensure the header text matches exactly (whitespace-insensitive) and keep at least one `#### Scenario:`.
|
||||||
|
|
||||||
|
Example for RENAMED:
|
||||||
|
```markdown
|
||||||
|
## RENAMED Requirements
|
||||||
|
- FROM: `### Requirement: Login`
|
||||||
|
- TO: `### Requirement: User Authentication`
|
||||||
|
```
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
### Common Errors
|
||||||
|
|
||||||
|
**"Change must have at least one delta"**
|
||||||
|
- Check `changes/[name]/specs/` exists with .md files
|
||||||
|
- Verify files have operation prefixes (## ADDED Requirements)
|
||||||
|
|
||||||
|
**"Requirement must have at least one scenario"**
|
||||||
|
- Check scenarios use `#### Scenario:` format (4 hashtags)
|
||||||
|
- Don't use bullet points or bold for scenario headers
|
||||||
|
|
||||||
|
**Silent scenario parsing failures**
|
||||||
|
- Exact format required: `#### Scenario: Name`
|
||||||
|
- Debug with: `openspec show [change] --json --deltas-only`
|
||||||
|
|
||||||
|
### Validation Tips
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Always use strict mode for comprehensive checks
|
||||||
|
openspec validate [change] --strict
|
||||||
|
|
||||||
|
# Debug delta parsing
|
||||||
|
openspec show [change] --json | jq '.deltas'
|
||||||
|
|
||||||
|
# Check specific requirement
|
||||||
|
openspec show [spec] --json -r 1
|
||||||
|
```
|
||||||
|
|
||||||
|
## Happy Path Script
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1) Explore current state
|
||||||
|
openspec spec list --long
|
||||||
|
openspec list
|
||||||
|
# Optional full-text search:
|
||||||
|
# rg -n "Requirement:|Scenario:" openspec/specs
|
||||||
|
# rg -n "^#|Requirement:" openspec/changes
|
||||||
|
|
||||||
|
# 2) Choose change id and scaffold
|
||||||
|
CHANGE=add-two-factor-auth
|
||||||
|
mkdir -p openspec/changes/$CHANGE/{specs/auth}
|
||||||
|
printf "## Why\n...\n\n## What Changes\n- ...\n\n## Impact\n- ...\n" > openspec/changes/$CHANGE/proposal.md
|
||||||
|
printf "## 1. Implementation\n- [ ] 1.1 ...\n" > openspec/changes/$CHANGE/tasks.md
|
||||||
|
|
||||||
|
# 3) Add deltas (example)
|
||||||
|
cat > openspec/changes/$CHANGE/specs/auth/spec.md << 'EOF'
|
||||||
|
## ADDED Requirements
|
||||||
|
### Requirement: Two-Factor Authentication
|
||||||
|
Users MUST provide a second factor during login.
|
||||||
|
|
||||||
|
#### Scenario: OTP required
|
||||||
|
- **WHEN** valid credentials are provided
|
||||||
|
- **THEN** an OTP challenge is required
|
||||||
|
EOF
|
||||||
|
|
||||||
|
# 4) Validate
|
||||||
|
openspec validate $CHANGE --strict
|
||||||
|
```
|
||||||
|
|
||||||
|
## Multi-Capability Example
|
||||||
|
|
||||||
|
```
|
||||||
|
openspec/changes/add-2fa-notify/
|
||||||
|
├── proposal.md
|
||||||
|
├── tasks.md
|
||||||
|
└── specs/
|
||||||
|
├── auth/
|
||||||
|
│ └── spec.md # ADDED: Two-Factor Authentication
|
||||||
|
└── notifications/
|
||||||
|
└── spec.md # ADDED: OTP email notification
|
||||||
|
```
|
||||||
|
|
||||||
|
auth/spec.md
|
||||||
|
```markdown
|
||||||
|
## ADDED Requirements
|
||||||
|
### Requirement: Two-Factor Authentication
|
||||||
|
...
|
||||||
|
```
|
||||||
|
|
||||||
|
notifications/spec.md
|
||||||
|
```markdown
|
||||||
|
## ADDED Requirements
|
||||||
|
### Requirement: OTP Email Notification
|
||||||
|
...
|
||||||
|
```
|
||||||
|
|
||||||
|
## Best Practices
|
||||||
|
|
||||||
|
### Simplicity First
|
||||||
|
- Default to <100 lines of new code
|
||||||
|
- Single-file implementations until proven insufficient
|
||||||
|
- Avoid frameworks without clear justification
|
||||||
|
- Choose boring, proven patterns
|
||||||
|
|
||||||
|
### Complexity Triggers
|
||||||
|
Only add complexity with:
|
||||||
|
- Performance data showing current solution too slow
|
||||||
|
- Concrete scale requirements (>1000 users, >100MB data)
|
||||||
|
- Multiple proven use cases requiring abstraction
|
||||||
|
|
||||||
|
### Clear References
|
||||||
|
- Use `file.ts:42` format for code locations
|
||||||
|
- Reference specs as `specs/auth/spec.md`
|
||||||
|
- Link related changes and PRs
|
||||||
|
|
||||||
|
### Capability Naming
|
||||||
|
- Use verb-noun: `user-auth`, `payment-capture`
|
||||||
|
- Single purpose per capability
|
||||||
|
- 10-minute understandability rule
|
||||||
|
- Split if description needs "AND"
|
||||||
|
|
||||||
|
### Change ID Naming
|
||||||
|
- Use kebab-case, short and descriptive: `add-two-factor-auth`
|
||||||
|
- Prefer verb-led prefixes: `add-`, `update-`, `remove-`, `refactor-`
|
||||||
|
- Ensure uniqueness; if taken, append `-2`, `-3`, etc.
|
||||||
|
|
||||||
|
## Tool Selection Guide
|
||||||
|
|
||||||
|
| Task | Tool | Why |
|
||||||
|
|------|------|-----|
|
||||||
|
| Find files by pattern | Glob | Fast pattern matching |
|
||||||
|
| Search code content | Grep | Optimized regex search |
|
||||||
|
| Read specific files | Read | Direct file access |
|
||||||
|
| Explore unknown scope | Task | Multi-step investigation |
|
||||||
|
|
||||||
|
## Error Recovery
|
||||||
|
|
||||||
|
### Change Conflicts
|
||||||
|
1. Run `openspec list` to see active changes
|
||||||
|
2. Check for overlapping specs
|
||||||
|
3. Coordinate with change owners
|
||||||
|
4. Consider combining proposals
|
||||||
|
|
||||||
|
### Validation Failures
|
||||||
|
1. Run with `--strict` flag
|
||||||
|
2. Check JSON output for details
|
||||||
|
3. Verify spec file format
|
||||||
|
4. Ensure scenarios properly formatted
|
||||||
|
|
||||||
|
### Missing Context
|
||||||
|
1. Read project.md first
|
||||||
|
2. Check related specs
|
||||||
|
3. Review recent archives
|
||||||
|
4. Ask for clarification
|
||||||
|
|
||||||
|
## Quick Reference
|
||||||
|
|
||||||
|
### Stage Indicators
|
||||||
|
- `changes/` - Proposed, not yet built
|
||||||
|
- `specs/` - Built and deployed
|
||||||
|
- `archive/` - Completed changes
|
||||||
|
|
||||||
|
### File Purposes
|
||||||
|
- `proposal.md` - Why and what
|
||||||
|
- `tasks.md` - Implementation steps
|
||||||
|
- `design.md` - Technical decisions
|
||||||
|
- `spec.md` - Requirements and behavior
|
||||||
|
|
||||||
|
### CLI Essentials
|
||||||
|
```bash
|
||||||
|
openspec list # What's in progress?
|
||||||
|
openspec show [item] # View details
|
||||||
|
openspec validate --strict # Is it correct?
|
||||||
|
openspec archive <change-id> [--yes|-y] # Mark complete (add --yes for automation)
|
||||||
|
```
|
||||||
|
|
||||||
|
Remember: Specs are truth. Changes are proposals. Keep them in sync.
|
||||||
184
openspec/project.md
Normal file
184
openspec/project.md
Normal file
@ -0,0 +1,184 @@
|
|||||||
|
# Project Context
|
||||||
|
|
||||||
|
## Purpose
|
||||||
|
|
||||||
|
ERPTurbo_Server 是一个现代化的企业资源规划(ERP)系统后端服务，专注于供应链管理和业务流程自动化。系统采用微服务架构，支持采购管理、产品管理、订单管理、经销商管理、用户权限管理等核心业务功能。
|
||||||
|
|
||||||
|
## Tech Stack
|
||||||
|
|
||||||
|
### 核心技术栈
|
||||||
|
- **Java版本**: Java 21 (LTS)
|
||||||
|
- **框架**: Spring Boot 3.4.5, Spring Cloud 2024.0.1, Spring Cloud Alibaba 2023.0.3.3
|
||||||
|
- **架构模式**: DDD (领域驱动设计) + COLA架构
|
||||||
|
- **微服务**: Apache Dubbo 3.2.10
|
||||||
|
- **服务发现**: Nacos
|
||||||
|
- **数据库**: MySQL 8.0.28
|
||||||
|
- **ORM**: MyBatis Plus 3.5.10.1, MyBatis 3.0.4
|
||||||
|
- **连接池**: Druid 1.2.20
|
||||||
|
- **缓存**: Redis, Redisson
|
||||||
|
- **认证授权**: Sa-Token
|
||||||
|
- **API文档**: Swagger/OpenAPI
|
||||||
|
- **构建工具**: Maven
|
||||||
|
- **日志**: Logback
|
||||||
|
|
||||||
|
### 开发工具
|
||||||
|
- **代码生成**: Lombok
|
||||||
|
- **对象映射**: MapStruct
|
||||||
|
- **参数校验**: Validation
|
||||||
|
- **数据库连接池**: Druid
|
||||||
|
- **分布式事务**: Seata (可选)
|
||||||
|
|
||||||
|
## Project Conventions
|
||||||
|
|
||||||
|
### Code Style
|
||||||
|
|
||||||
|
#### 命名规范
|
||||||
|
- **实体类**: `Product` (领域实体), `ProductDO` (数据对象)
|
||||||
|
- **服务接口**: `功能名+ServiceI`
|
||||||
|
- **服务实现**: `功能名+ServiceImpl`
|
||||||
|
- **查询执行器**: `功能名+QryExe`
|
||||||
|
- **命令执行器**: `功能名+CmdExe`
|
||||||
|
- **网关实现**: `功能名+GatewayImpl`
|
||||||
|
- **转换器**: `功能名+Convert`
|
||||||
|
- **控制器**: `功能名+Controller`
|
||||||
|
|
||||||
|
#### 代码注解规范
|
||||||
|
- 使用Lombok简化代码 (`@Data`, `@RequiredArgsConstructor`, `@Builder`)
|
||||||
|
- MapStruct进行对象转换 (`@Mapper`)
|
||||||
|
- 统一的异常处理
|
||||||
|
- Spring注解: `@Service`, `@Component`, `@DubboService`, `@DubboReference`
|
||||||
|
- 权限注解: `@SaCheckLogin`, `@SaCheckRole`, `@SaCheckPermission`
|
||||||
|
- API文档注解: `@Tag`, `@Operation`, `@Schema`
|
||||||
|
|
||||||
|
#### 包结构规范
|
||||||
|
```
|
||||||
|
com.xunhong.erp.turbo/
|
||||||
|
├── api/ # API接口定义
|
||||||
|
│ ├── dto/ # 数据传输对象
|
||||||
|
│ │ ├── cmd/ # 命令对象
|
||||||
|
│ │ ├── qry/ # 查询对象
|
||||||
|
│ │ ├── vo/ # 视图对象
|
||||||
|
│ │ └── enums/ # 枚举类
|
||||||
|
│ └── api/ # 服务接口
|
||||||
|
├── biz/ # 业务逻辑层
|
||||||
|
│ ├── app/ # 应用服务
|
||||||
|
│ │ ├── service/ # 服务实现
|
||||||
|
│ │ └── executor/ # 执行器
|
||||||
|
│ ├── domain/ # 领域层
|
||||||
|
│ │ ├── entity/ # 领域实体
|
||||||
|
│ │ └── gateway/ # 网关接口
|
||||||
|
│ └── infrastructure/ # 基础设施层
|
||||||
|
│ ├── entity/ # 数据实体
|
||||||
|
│ ├── mapper/ # 数据访问
|
||||||
|
│ └── convert/ # 对象转换
|
||||||
|
```
|
||||||
|
|
||||||
|
### Architecture Patterns
|
||||||
|
|
||||||
|
#### 分层架构
|
||||||
|
项目采用严格的分层架构，遵循DDD和COLA架构原则：
|
||||||
|
|
||||||
|
1. **API层**: 接口定义，包括DTO、Command、Query、VO
|
||||||
|
2. **应用层**: Service服务实现，Executor执行器
|
||||||
|
3. **领域层**: Entity实体，Gateway网关接口
|
||||||
|
4. **基础设施层**: DO数据对象，Mapper数据访问，Convert转换器
|
||||||
|
|
||||||
|
#### 微服务架构
|
||||||
|
- 基于Dubbo的RPC通信
|
||||||
|
- Nacos作为注册中心和配置中心
|
||||||
|
- 模块化设计，职责单一
|
||||||
|
|
||||||
|
#### 数据访问模式
|
||||||
|
- 使用MyBatis Plus进行数据库操作
|
||||||
|
- DO与领域实体分离
|
||||||
|
- 通过MapStruct进行对象转换
|
||||||
|
- 支持多数据源
|
||||||
|
|
||||||
|
### Testing Strategy
|
||||||
|
|
||||||
|
#### 测试框架
|
||||||
|
- **单元测试**: JUnit
|
||||||
|
- **集成测试**: Spring Boot Test
|
||||||
|
- **内存数据库**: H2 (用于测试)
|
||||||
|
|
||||||
|
#### 测试规范
|
||||||
|
- 测试类命名: `被测试类+Test`
|
||||||
|
- 单元测试覆盖核心业务逻辑
|
||||||
|
- 集成测试验证API接口
|
||||||
|
- 使用H2内存数据库进行测试
|
||||||
|
|
||||||
|
### Git Workflow
|
||||||
|
|
||||||
|
#### 分支策略
|
||||||
|
- **master**: 主分支，稳定版本
|
||||||
|
- **develop**: 开发分支
|
||||||
|
- **feature/xxx**: 功能分支
|
||||||
|
- **hotfix/xxx**: 热修复分支
|
||||||
|
|
||||||
|
#### 提交规范
|
||||||
|
基于Conventional Commits规范：
|
||||||
|
- `feat`: 新功能
|
||||||
|
- `fix`: 修复
|
||||||
|
- `refactor`: 重构
|
||||||
|
- `docs`: 文档
|
||||||
|
- `style`: 格式调整
|
||||||
|
- `test`: 测试
|
||||||
|
- `chore`: 构建或辅助工具变动
|
||||||
|
|
||||||
|
## Domain Context
|
||||||
|
|
||||||
|
### 核心业务领域
|
||||||
|
1. **采购管理**: 供应商管理、采购订单、采购成本控制
|
||||||
|
2. **产品管理**: 产品信息维护、成本费用关联、分类管理
|
||||||
|
3. **订单管理**: 订单处理、订单供应商关联、包装发货
|
||||||
|
4. **经销商管理**: 经销商信息、仓库管理、返利客户
|
||||||
|
5. **权限管理**: 用户、角色、权限的完整RBAC模型
|
||||||
|
6. **基础设施**: 字典、平台、渠道、物料、协议等基础数据
|
||||||
|
|
||||||
|
### 业务规则
|
||||||
|
- 严格的权限控制体系
|
||||||
|
- 多租户支持 (基于平台维度)
|
||||||
|
- 审计日志记录
|
||||||
|
- 数据一致性要求高
|
||||||
|
|
||||||
|
## Important Constraints
|
||||||
|
|
||||||
|
### 技术约束
|
||||||
|
- 必须使用Java 21 LTS版本
|
||||||
|
- 严格遵循DDD和COLA架构
|
||||||
|
- 微服务间通信必须使用Dubbo
|
||||||
|
- 数据库操作必须通过MyBatis Plus
|
||||||
|
- 权限控制必须集成Sa-Token
|
||||||
|
|
||||||
|
### 业务约束
|
||||||
|
- 数据一致性要求高，特别是财务相关数据
|
||||||
|
- 需要支持高并发访问
|
||||||
|
- 严格的审计要求
|
||||||
|
- 多租户数据隔离
|
||||||
|
|
||||||
|
### 安全约束
|
||||||
|
- 所有API接口必须进行权限校验
|
||||||
|
- 敏感数据必须加密存储
|
||||||
|
- 审计日志必须完整记录
|
||||||
|
- 防止SQL注入和XSS攻击
|
||||||
|
|
||||||
|
## External Dependencies
|
||||||
|
|
||||||
|
### 核心依赖
|
||||||
|
- **Spring生态**: Spring Boot, Spring Cloud, Spring Security
|
||||||
|
- **数据库**: MySQL 8.0.28
|
||||||
|
- **缓存**: Redis
|
||||||
|
- **消息队列**: 可选RocketMQ/RabbitMQ
|
||||||
|
- **服务治理**: Nacos, Dubbo
|
||||||
|
- **监控**: Micrometer, Prometheus (可选)
|
||||||
|
|
||||||
|
### 外部服务
|
||||||
|
- **第三方支付**: 支付宝、微信支付 (如需要)
|
||||||
|
- **物流服务**: 快递公司API接口 (如需要)
|
||||||
|
- **短信服务**: 阿里云短信、腾讯云短信 (如需要)
|
||||||
|
|
||||||
|
### 开发工具
|
||||||
|
- **构建工具**: Maven 3.8+
|
||||||
|
- **IDE**: IntelliJ IDEA (推荐)
|
||||||
|
- **版本控制**: Git
|
||||||
|
- **API测试**: Postman/Swagger UI
|
||||||
Loading…
Reference in New Issue
Block a user