diff --git a/.claude/agents/changeable-auto-doc.md b/.claude/agents/changeable-auto-doc.md new file mode 100644 index 0000000..67e2d40 --- /dev/null +++ b/.claude/agents/changeable-auto-doc.md @@ -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. **返回概要** → 提供更新概要 diff --git a/.claude/agents/changeable-code-analyst.md b/.claude/agents/changeable-code-analyst.md new file mode 100644 index 0000000..77f9f82 --- /dev/null +++ b/.claude/agents/changeable-code-analyst.md @@ -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)**: +(指定关注点,如"分析分布式锁"、"追踪排期加载链路"等) diff --git a/.claude/agents/changeable-java-dev.md b/.claude/agents/changeable-java-dev.md new file mode 100644 index 0000000..05c61b5 --- /dev/null +++ b/.claude/agents/changeable-java-dev.md @@ -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是否能解决,汇总返回用户 +--- +## 我已准备就绪!请开始描述你的代码库和业务场景。 +**专业术语(模糊匹配理解):** +**背景:** + +**要求:** diff --git a/.claude/agents/changeable-react-dev.md b/.claude/agents/changeable-react-dev.md new file mode 100644 index 0000000..ad11f54 --- /dev/null +++ b/.claude/agents/changeable-react-dev.md @@ -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是否能解决,汇总返回用户 +--- +## 我已准备就绪!请开始描述你的前端项目和业务场景。 +**专业术语(模糊匹配理解):** +**背景:** + +**要求:** diff --git a/.claude/agents/changeable-taro-nutui-dev.md b/.claude/agents/changeable-taro-nutui-dev.md new file mode 100644 index 0000000..88a6e6d --- /dev/null +++ b/.claude/agents/changeable-taro-nutui-dev.md @@ -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是否能解决,汇总返回用户 +--- +## 我已准备就绪!请开始描述你的前端项目和业务场景。 +**专业术语(模糊匹配理解):** +**背景:** + +**要求:** \ No newline at end of file diff --git a/.gitignore b/.gitignore index 70e0f85..36e7ee3 100644 --- a/.gitignore +++ b/.gitignore @@ -16,3 +16,8 @@ .dumi/tmp-test .dumi/tmp-production .DS_Store + +.bmad-core +/.claude/commands/BMad +/.claude/commands/openspec +/docs diff --git a/.nvmdrc b/.nvmdrc index c130222..fdb2eaa 100644 --- a/.nvmdrc +++ b/.nvmdrc @@ -1 +1 @@ -20.18.0 \ No newline at end of file +22.11.0 \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..0669699 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,18 @@ + +# 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. + + \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..0669699 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,18 @@ + +# 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. + + \ No newline at end of file diff --git a/openspec/AGENTS.md b/openspec/AGENTS.md new file mode 100644 index 0000000..96ab0bb --- /dev/null +++ b/openspec/AGENTS.md @@ -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//`. +3. Draft spec deltas using `## ADDED|MODIFIED|REMOVED Requirements` with at least one `#### Scenario:` per requirement. +4. Run `openspec validate --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 --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 --type spec` (use `--json` for filters) + - Change: `openspec show --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 [--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//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//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 [--yes|-y] # Mark complete (add --yes for automation) +``` + +Remember: Specs are truth. Changes are proposals. Keep them in sync. diff --git a/openspec/project.md b/openspec/project.md new file mode 100644 index 0000000..ffe4339 --- /dev/null +++ b/openspec/project.md @@ -0,0 +1,164 @@ +# Project Context + +## Purpose +瓜联丨西瓜产业一体化智能管理平台 - 基于微信小程序的多端ERP系统,专注于西瓜产业的采购管理、供应商管理、交付管理等核心业务流程数字化。项目旨在为西瓜产业链提供高效的数字化管理工具,提升供应链效率和透明度。 + +## Tech Stack + +### 前端核心 +- **React 18.0.0** + **TypeScript 5.1.6** - 现代化前端开发框架 +- **Taro 4.1.7** - 多端跨平台解决方案,支持微信小程序、H5、支付宝等平台 +- **Zustand 5.0.3** - 轻量级全局状态管理 +- **SWR 2.3.6** - 数据获取和缓存策略 + +### UI与样式 +- **NutUI 3.0.18** - 微信小程序专用React组件库 +- **TailwindCSS 4.1** + **PostCSS** - 原子化CSS框架 +- **Sass** - CSS预处理器 +- **CSS Variables** - 统一主题系统设计 + +### 开发工具链 +- **pnpm workspace** - 包管理和工作空间 +- **Webpack 5.94.0** - 构建工具 +- **Babel 7.x** + **SWC** - 代码编译 +- **ESLint** + **Prettier** + **Husky** - 代码质量和Git钩子 +- **Jest 29.3.1** - 单元测试框架 + +### 数据与网络 +- **Axios 1.7.4** - HTTP客户端 +- **OpenAPI** - API类型定义生成 +- **本地存储** - 数据持久化 + +## Project Conventions + +### Code Style + +#### 命名规范 +- **组件**: PascalCase (如: CustomTabBar, PurchaseSection) +- **文件**: kebab-case (如: purchase-order-list.tsx) +- **变量/函数**: camelCase (如: getUserInfo, handleSubmit) +- **常量**: SCREAMING_SNAKE_CASE (如: API_BASE_URL) +- **CSS类**: TailwindCSS原子类 + 自定义kebab-case类 + +#### 代码组织 +``` +src/ +├── pages/ # 页面组件,按业务模块分组 +├── components/ # 通用组件,按功能分组 +├── services/ # API服务层 +├── store/ # 状态管理 +├── utils/ # 工具函数 +└── types/ # TypeScript类型定义 +``` + +#### TypeScript规范 +- 启用严格类型检查 +- 优先使用interface定义对象结构 +- 使用联合类型和泛型提高类型复用性 +- 避免使用any类型,必要时使用unknown + +### Architecture Patterns + +#### 分层架构 +- **表现层**: React组件 + Taro页面 +- **业务层**: 业务逻辑组件 + HOC +- **服务层**: API调用 + 数据转换 +- **状态层**: Zustand全局状态 + SWR缓存 + +#### 设计模式 +- **HOC模式**: 基础HOC提供全局功能(认证、权限等) +- **组合模式**: 组件按功能分层组合 +- **策略模式**: 不同角色的业务逻辑策略 +- **观察者模式**: SWR数据订阅和更新 + +#### 模块化设计 +- 按业务功能垂直切分模块 +- 模块内部高内聚,模块间低耦合 +- 统一的导出和依赖管理 + +### Testing Strategy +- **单元测试**: Jest + React Testing Library,覆盖核心业务逻辑 +- **组件测试**: 关键组件的渲染和交互测试 +- **API测试**: 服务层接口调用测试 +- **端到端测试**: 关键业务流程的集成测试 +- **目标覆盖率**: 核心模块80%以上 + +### Git Workflow +- **主要分支**: master (生产), develop (开发) +- **功能分支**: feature/功能名,从develop创建 +- **修复分支**: hotfix/问题描述,从master创建 +- **提交规范**: Conventional Commits,使用中文提交信息 +- **代码审查**: 所有PR必须经过代码审查 + +## Domain Context + +### 核心业务模块 +1. **采购管理**: + - 采购单创建、编辑、提交 + - 多级审核流程(采购员→审核员→审批员) + - 采购历史记录和状态追踪 + - 费用计算和价格管理 + +2. **供应商管理**: + - 供应商信息维护 + - 供应商资质管理 + - 采购历史关联 + +3. **交付管理**: + - 交付单创建和管理 + - 配送状态跟踪 + - 交付确认和验收 + +4. **用户权限**: + - 基于角色的访问控制(RBAC) + - 功能权限动态分配 + - 多角色身份支持 + +### 业务流程 +- **采购流程**: 需求确认 → 供应商选择 → 采购单创建 → 多级审核 → 执行采购 +- **交付流程**: 采购完成 → 交付安排 → 物流跟踪 → 确认收货 + +### 数据模型关键概念 +- **采购单**: 采购业务的核心实体,包含商品、数量、价格、供应商等信息 +- **角色权限**: 采购员、审核员、审批员等不同角色的操作权限 +- **状态流转**: 采购单从创建到完成的完整生命周期管理 + +## Important Constraints + +### 技术约束 +- **微信小程序限制**: 包体积限制、API调用限制、UI组件限制 +- **多端兼容**: 必须同时支持微信小程序和H5平台 +- **性能要求**: 首屏加载时间 < 3秒,操作响应时间 < 1秒 +- **离线支持**: 关键数据本地缓存,支持弱网环境 + +### 业务约束 +- **数据一致性**: 采购状态、库存数据等关键信息的实时一致性 +- **权限控制**: 严格的基于角色的功能访问控制 +- **审计追踪**: 所有操作必须可追溯,支持审计需求 +- **数据安全**: 敏感业务数据加密存储和传输 + +### 合规约束 +- **隐私保护**: 遵循数据隐私保护相关法规 +- **微信生态**: 符合微信小程序开发规范和审核要求 + +## External Dependencies + +### 微信生态服务 +- **微信登录**: 用户身份认证 +- **微信支付**: 支付集成(如需要) +- **微信消息推送**: 业务消息通知 + +### 核心业务API +- **RESTful API**: 后端业务系统接口 +- **文件上传服务**: 附件、图片上传 +- **PDF生成服务**: 采购单、交付单等文档生成 + +### 第三方服务 +- **地图服务**: 位置相关功能(如需要) +- **统计分析**: 业务数据分析 +- **Lottie动画**: 动画效果支持 + +### 开发与部署 +- **CI/CD平台**: 持续集成和部署 +- **代码托管**: Git仓库管理 +- **包管理**: npm/pnpm私有仓库(如需要) diff --git a/packages/app-client/src/utils/format.ts b/packages/app-client/src/utils/format.ts index 15cde0b..d51c041 100644 --- a/packages/app-client/src/utils/format.ts +++ b/packages/app-client/src/utils/format.ts @@ -55,7 +55,9 @@ export function convertSeconds(seconds, outputUnit) { // 格式化金额显示 export const formatCurrency = (value: number) => { // 去掉 小数点后多余的0 - return Number(value || 0)?.toFixed(2).replace(/\.?0+$/, ""); + return Number(value || 0) + ?.toFixed(2) + .replace(/\.?0+$/, ""); }; // 格式化金额显示 @@ -65,7 +67,7 @@ export const formatUnitPrice = (value: number) => { export const validatePrice = (value: string) => { const regex = /^\d*\.?\d{0,2}$/; - console.log("validatePrice", value, regex.test(value)) + console.log("validatePrice", value, regex.test(value)); if (value === "" || regex.test(value)) { // 如果值以小数点结尾,则暂不转换为数字 if (value.endsWith(".") || value.endsWith(".0") || value.endsWith(".00")) {