# solveplan-peanut-center **Repository Path**: slsplatform/solveplan-peanut-center ## Basic Information - **Project Name**: solveplan-peanut-center - **Description**: springboot4+jdk25+动态数据源 - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-08-22 - **Last Updated**: 2026-09-10 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Peanut Center - 企业智能助理平台 > AI Agent 技术百科主入口:[`SPEC-KIT.md`](SPEC-KIT.md) Peanut Center 是一个 AI 驱动的智能调度/工厂管理平台,集成 Spring AI 2.0.0 提供 AI MCP Server(SSE 协议),支持多租户 SaaS 架构、钉钉 Stream 机器人交互、Google OR-Tools 车辆路径优化。 **核心能力**: - 🤖 **多 AI 模型接入**(腾讯混元、深度思考)+ **MCP 工具调用协议** - 💬 **SSE 流式对话** + 多轮上下文记忆 - 📊 **动态 SQL 引擎**(portal-query 的 BaseQuerySqlApi,用于 AI Tool 底层数据查询) - 🏢 **钉钉 Stream 机器人**消息监听 + 启动/异常通知推送 - 🔐 **多租户 SaaS**(MyBatis-Plus 自动填充 tenant_id) - 🧵 **JDK 25 ScopedValue** 请求上下文传播(替代 ThreadLocal,虚拟线程安全) --- ## 快速开始 ```bash # 1. 设置 JDK 25 export JAVA_HOME=/Users/wangbao/Library/Java/openjdk-25.0.1/Contents/Home export PATH="$JAVA_HOME/bin:$PATH" # 2. 启动(需要本地 MySQL + Redis) mvn spring-boot:run -pl portal-gateway -Dspring-boot.run.profiles=local # 访问: http://localhost:80 | MCP SSE: http://localhost:80/mcp ``` 详细构建、打包、Docker 部署见 [`spec-kit/08-testing-build.md`](spec-kit/08-testing-build.md)。 --- ## 使用 Spec-Kit 开发 > 这是本项目的 **AI 辅助开发工作流**。简单说就是:把所有技术规范、代码模板、架构决策写成文档喂给 AI,让 AI 按规范生成代码、规划任务、审查变更。 > 类比:Spec-Kit 就像一个**永不离职的高级技术导师**,你只要说「我要做 XXX」,它就会按项目规范帮你写代码。 ### 一、目录结构(你需要知道的) ``` solveplan-peanut-center/ ├── SPEC-KIT.md ← 【主入口】AI 首先读这个文件 │ 含:项目概述 + 15 个子文件索引 + Cheat Sheet + 架构决策 │ ├── spec-kit/ ← 【规范文档库】15 个专题文件 │ ├── 01-tech-stack-config.md # 技术栈版本号 + application.yml 全配置 │ ├── 02-module-structure.md # 7 个模块职责 + 依赖关系 + 包结构 │ ├── 03-database.md # 数据库规范(双数据源、BaseEntity 10 字段、SQL 规则、表结构) │ ├── 04-coding-standards.md # 代码风格、Lombok、日志、异常、MapStruct 规范 │ ├── 05-ai-tool-development.md # 🎯 AI Tool 开发完整模板 + 命名规范 + 6 条红线 │ ├── 06-multi-tenant.md # 多租户隔离、ScopedValue、LoginUser 上下文 │ ├── 07-annotations.md # 自定义注解 + Spring AI + MyBatis-Plus 注解速查 │ ├── 08-testing-build.md # 测试规范 + 所有 Maven 命令 + 覆盖率 │ ├── 09-key-base-classes.md # 30+ 工具类、8 个 AOP、关键基类 API │ ├── 10-controller-conventions.md # Controller 约定(POST-only、@MethodExt 等) │ ├── 11-sdd-backlog-workflow.md # 🎯 任务规划 → 执行 → 归档完整工作流 │ ├── 12-peanut-properties.md # PeanutProperties 22 个配置项说明 │ ├── 13-frontend-architecture.md # Vue 3 前端架构(目录、路由、状态管理) │ ├── 14-api-endpoints.md # 所有 API 端点 + SSE + 过滤器链 │ └── 15-agent-execution.md # Agent 执行阶段指南(代码位置索引 + 退出条件) │ └── backlog/ ← 【任务看板】所有待做/已做任务 ├── specs/ # 需求规格(active 状态) ├── tasks/ # 任务文件(YAML frontmatter + Acceptance Criteria) ├── milestones/ # 里程碑 └── docs/ # 项目状态文档 ``` ### 二、Spec-Kit 开发迭代(四阶段) > Spec-Kit 核心理念:**先写规格,再写代码**。每次迭代按四阶段推进: ``` Brainstorm ──▶ Spec ──▶ Tasks ──▶ Implement (发散) (收敛) (拆解) (执行) ``` | 阶段 | 你做什么 | AI 做什么 | 产出物 | |------|---------|----------|--------| | **Brainstorm** | 说「我要做 XXX」,描述需求和约束 | 帮你梳理问题、方案、边界(Non-Goals) | `backlog/drafts/` 讨论稿 | | **Spec** | 确认规格方向 | 写 `backlog/specs/{模块}/` 下的 schema.sql、api-endpoints.md 等 | 规格契约 | | **Tasks** | 确认任务拆分 | 写 `backlog/tasks/task-NNN-*.md`(YAML frontmatter + Acceptance Criteria) | 可验收任务清单 | | **Implement** | 审查 AI 生成的代码 | 读 SPEC-KIT.md + 专题规范 → 生成代码 → 编译验证 → 归档联动 | 代码 + 测试 + 归档 | **Implement 阶段的 5 个实操步骤**: ``` ┌─────────────┐ │ ① 读取规范 │ AI 自动加载 SPEC-KIT.md + 相关专题文件 │ │ (新建 AI Tool → 读 05 + 03) │ │ (新建 CRUD → 读 04 + 03 + 10) └──────┬──────┘ ▼ ┌─────────────┐ │ ② 生成代码 │ AI 按规范生成:Entity → Mapper → Service → Controller │ │ 自动处理:BaseEntity 继承、MapStruct 转换、? 占位符 SQL └──────┬──────┘ ▼ ┌─────────────┐ │ ③ 验证检查 │ mvn spotless:apply ← 格式化 │ │ mvn compile -q ← 编译 │ │ 单测覆盖率 ≥ 70% ← 质量门禁 └──────┬──────┘ ▼ ┌─────────────┐ │ ④ 对照 Spec │ 逐条核对 Acceptance Criteria,确保规格已满足 └──────┬──────┘ ▼ ┌─────────────┐ │ ⑤ 归档收尾 │ 任务状态 → Done → 移入 archived/ │ │ 按 §11.5 联动矩阵同步 spec-kit/ 和 backlog/docs/ └─────────────┘ ``` ### 三、上手教程:两个最常见场景 #### 场景 A:新建一个 AI Tool(让大模型能查询新数据表) **你只需要说**: > 我需要一个 AI Tool,让大模型能查询「设备信息」表,返回设备名称、型号、位置、状态。 AI 会按 [`05-ai-tool-development.md`](spec-kit/05-ai-tool-development.md) 自动: ``` Step 1: 生成 Entity(portal-mcp/.../entity/DeviceInfo.java) → extends BaseEntity ✅ 自动带 10 个公共字段 → @TableName("base_device_info") ✅ 表名 base_ 前缀 Step 2: 生成 Tool 类(portal-mcp/.../tools/DeviceInfoToolImpl.java) → extends DbToolAbstractImpl ✅ 只读数据源基类 → @Component + @Slf4j → @Tool(name="device_info_query", description="中文描述") → SQL 用 ? 占位符,自动加 AND is_delete = 0 Step 3: 返回结构固定 → Map.of("data", list, "字段解释:", fieldNames(DeviceInfo.class)) ``` **你需要关注**:检查 SQL 逻辑对不对、`@Tool name` 命名是否符合 snake_case 规范。 #### 场景 B:新建一个业务 CRUD(前端页面 + 后端接口) **你只需要说**: > 我要做一个「合作伙伴管理」模块,包括合作伙伴名称、联系方式、合作类型、合作开始日期。 AI 会按规范 03 + 04 + 10 自动: ``` Step 1: 生成 DDL(DROP + CREATE 完整语句) → 10 个公共字段 + 业务字段 + 索引 → 必须提供 DROP TABLE IF EXISTS ✅ Step 2: 生成 Entity → Mapper → Service → ServiceImpl → Converter → Entity extends BaseEntity → Mapper extends BaseMapper → Converter 用 MapStruct Spring 模式(禁止 INSTANCE 静态模式) Step 3: 生成 Controller → 全部 POST(禁止 GET) → @PostMapping("/{domain}/{action}") → @MethodExt 控制返回值格式 Step 4: 生成前端页面(Vue 3 + Element Plus) → 列表页 + 新增/编辑弹窗 → 使用已封装的 IconPicker(图标选择器) → API 调用方式:post('/api/base/partner/list', params) ``` ### 四、给 AI 提问的正确姿势 | ❌ 反例 | ✅ 正例 | |---------|---------| | 帮我写个工具类 | 我需要一个 AI Tool 查询设备表,字段有 name、model、location、status | | 加个接口 | 在 partner 模块新增 deleteById 接口,软删除(is_delete = UNIX_TIMESTAMP()) | | 这个报错了 | 这是报错堆栈 [粘贴],帮我定位根因,不要改业务逻辑代码 | | 重构一下 | 把 XxxService 中重复的 3 个方法提取到 portal-sdk 的 CommonService,保持向后兼容 | **好的提示词三要素**: 1. **说清楚做什么**:模块 + 目标 + 输入输出 2. **给出约束条件**:软删除、? 占位符、MapStruct、禁止拼接 SQL 等 3. **说明边界**:改哪个文件、不要改哪个、保持向后兼容 ### 五、开发红线(绝对禁止) | # | 红线 | 正确做法 | 查阅 | |---|------|---------|------| | 1 | ❌ SQL 字符串拼接 | ✅ `?` 占位符 + 参数数组 | `03-database.md` §4.6 | | 2 | ❌ 手写 SQL 忘加 `AND is_delete = 0` | ✅ 所有手写 SQL 必须显式加 | `03-database.md` §4.6 | | 3 | ❌ 对象拷贝用 BeanUtil / $.copy | ✅ MapStruct Spring 模式 | `04-coding-standards.md` §5.8 | | 4 | ❌ AI Tool 直接抛出异常 | ✅ catch 返回 `Map.of("error", "中文")` | `05-ai-tool-development.md` §6.8 | | 5 | ❌ Controller 用 GET | ✅ 全部 POST | `10-controller-conventions.md` | | 6 | ❌ 关联表省略 BaseEntity 公共字段 | ✅ 即使 package_resource 也必须 10 字段 | `03-database.md` §4.7 | | 7 | ❌ is_delete 用 TINYINT | ✅ 必须 BIGINT(存 UNIX_TIMESTAMP()) | `03-database.md` §4.7 | | 8 | ❌ 用 ThreadLocal | ✅ 用 JDK 25 ScopedValue | `06-multi-tenant.md` | ### 六、快速查询:遇到问题去哪里看 | 你想做什么 | 看哪个文件 | |-----------|-----------| | 新建/修改 AI Tool | [`spec-kit/05-ai-tool-development.md`](spec-kit/05-ai-tool-development.md) | | 写 SQL、查表结构、改表 | [`spec-kit/03-database.md`](spec-kit/03-database.md) | | 新建业务 CRUD(Entity/Service/Controller) | [`spec-kit/04-coding-standards.md`](spec-kit/04-coding-standards.md) + [`10-controller-conventions.md`](spec-kit/10-controller-conventions.md) | | 对象转换用 MapStruct | [`spec-kit/04-coding-standards.md`](spec-kit/04-coding-standards.md) §5.8 | | 多租户隔离、获取当前用户 | [`spec-kit/06-multi-tenant.md`](spec-kit/06-multi-tenant.md) | | 跑测试、格式化、打包 | [`spec-kit/08-testing-build.md`](spec-kit/08-testing-build.md) | | 规划任务、写 spec、归档 | [`spec-kit/11-sdd-backlog-workflow.md`](spec-kit/11-sdd-backlog-workflow.md) | | 前端开发 | [`spec-kit/13-frontend-architecture.md`](spec-kit/13-frontend-architecture.md) | | 不确定哪个文件 | 先读 [`SPEC-KIT.md`](SPEC-KIT.md) 的 Cheat Sheet 表 | --- ### 七、Trae IDE 实操指南(Spec-Kit 完整生命周期) > Spec-Kit 不是一个 npm 包也不是一个 VS Code 插件——它就是**写在仓库里的 Markdown 规范文件**。Trae IDE 的 AI Agent 会自动把这些文件当作项目知识库来读取、遵守、执行。 > 换句话说:**你不需要安装任何东西,只要在 Trae 里打开这个仓库,SPEC-KIT.md 和 spec-kit/ 下的规范就自动生效了。** #### 7.1 前提条件 - ✅ 安装 [Trae IDE](https://www.trae.ai)(字节跳动出品的 AI 原生 IDE,基于 VS Code) - ✅ 打开项目根目录 `solveplan-peanut-center/` - ✅ Trae 左侧 AI 面板能正常对话(需要登录/配置 API Key) #### 7.2 规范文件是怎么来的(以及你怎么维护它) **第一次初始化 Spec-Kit(本项目已完成,新模块可参考)**: 在 Trae 的 AI 对话框里输入: ``` 你好,这是一个 Spring Boot 4 + Spring AI 2 + MyBatis-Plus 3.5 + Vue 3 + JDK 25 的多租户 SaaS 项目。请帮我: 1. 在项目根目录生成 SPEC-KIT.md(AI 主入口文件) 2. 在 spec-kit/ 目录下按专题拆分 15 个规范文件 3. 每个文件用中文,包含:规则 + 代码模板 + 反例说明 + 红线 4. 所有规范遵守 SSOT 原则——规则只在一处定义,其他文件用链接引用 ``` AI 会自动扫描项目的 pom.xml、application.yml、现有代码结构,然后生成完整的规范体系。 **后续更新规范(比如加了新技术栈)**: ``` 我们刚升级到 Spring Boot 4.1.0,请帮我更新 spec-kit/01-tech-stack-config.md 和 SPEC-KIT.md 里的版本号。 ``` ``` 新增了 portal-sdk 的 XxxUtil 工具类,请补充到 spec-kit/09-key-base-classes.md 的工具类清单里。 ``` #### 7.3 日常开发:在 Trae 里完成一个完整任务 下面是一段**真实的 Trae 对话**,展示从「我要做 XX」到「代码写完归档」的全过程。 --- ##### Step 1️⃣ 规划任务(告诉 Trae 你要做什么) > **你(在 Trae AI 对话框里输入)**: > > 我要做一个「合作伙伴管理」模块。需求: > - 合作伙伴名称、联系人、联系电话、合作类型(战略/普通/试用)、开始日期、备注 > - 需要前端管理页面(列表 + 新增/编辑弹窗)+ 后端 CRUD 接口 > - 需要 AI Tool 让大模型能查询合作伙伴列表 > > 请先帮我规划任务,写一份 backlog/tasks/task-001-partner-management.md > **Trae 自动做的事**: > > 1. 读取 `SPEC-KIT.md` + `spec-kit/11-sdd-backlog-workflow.md`(任务文件格式) > 2. 生成任务文件,包含 YAML frontmatter + Acceptance Criteria: > > ``` > --- > id: TASK-001 > title: 合作伙伴管理模块 > status: Todo > priority: High > domain: partner > acceptance_criteria: > - [ ] DDL 包含 10 个 BaseEntity 公共字段 > - [ ] Entity extends BaseEntity > - [ ] Controller 全部 POST > - [ ] AI Tool 返回 Map.of("data", list, "字段解释:", ...) > - [ ] 前端页面使用 Element Plus + IconPicker > --- > ``` > > 3. 创建 `backlog/tasks/task-001-partner-management.md` --- ##### Step 2️⃣ 生成代码(让 Trae 开始执行) > **你**: > > 开始执行 task-001,按 Acceptance Criteria 逐条完成。 > **Trae 自动做的事**: > > ``` > ✅ 读取 task-001 的 6 条 Acceptance Criteria > ✅ 读取 spec-kit/03-database.md(DDL + BaseEntity 规范) > ✅ 读取 spec-kit/04-coding-standards.md(Entity/Service/MapStruct 规范) > ✅ 读取 spec-kit/05-ai-tool-development.md(AI Tool 模板) > ✅ 读取 spec-kit/10-controller-conventions.md(Controller 约定) > ✅ 读取 spec-kit/13-frontend-architecture.md(前端架构) > > Step 1: 生成 DDL → backlog/specs/partner/schema.sql > DROP TABLE IF EXISTS `base_partner`; > CREATE TABLE `base_partner` ( > `id` BIGINT NOT NULL, > `is_delete` BIGINT NOT NULL DEFAULT 0, > `tenant_id` BIGINT, > ... 10 个公共字段 ... > `partner_name` VARCHAR(128) NOT NULL, > `contact_name` VARCHAR(64), > ... 业务字段 ... > ); > > Step 2: 生成 Entity → portal-base/.../partner/entity/Partner.java > extends BaseEntity > @TableName("base_partner") > > Step 3: 生成 Mapper + Service + ServiceImpl + Converter (MapStruct) > > Step 4: 生成 Controller → POST /api/base/partner/page, /list, /create, /update, /delete > @MethodExt 控制返回值 > > Step 5: 生成 AI Tool → portal-mcp/.../tools/PartnerToolImpl.java > extends DbToolAbstractImpl > @Tool(name="partner_query", description="查询合作伙伴") > SQL 用 ? 占位符 + AND is_delete = 0 > 返回 Map.of("data", list, "字段解释:", fieldNames(Partner.class)) > > Step 6: 生成前端页面 → portal-web/admin-web/src/views/partner/PartnerManage.vue > Element Plus el-table + el-dialog + IconPicker > ``` --- ##### Step 3️⃣ 验证检查 > **Trae 自动做的事**(你也可以手动触发): > > ```bash > # 格式化 > mvn spotless:apply > > # 编译(portal-base + portal-mcp 联动编译) > mvn compile -pl portal-base,portal-mcp -am -q > > # 运行单元测试 > mvn test -pl portal-base -q > ``` > > 如果编译报错,Trae 会自动读取错误信息,定位到具体代码行,按规范修复后重新编译。 --- ##### Step 4️⃣ 归档收尾 > **你**: > > 全部完成了,帮我归档。 > **Trae 自动做的事**(按 `spec-kit/11-sdd-backlog-workflow.md` §11.5): > > ``` > 1. 把 backlog/tasks/task-001-partner-management.md 中的 status: Todo → Done > 2. 移动文件 → backlog/tasks/archived/task-001-partner-management.md > 3. 同步更新 backlog/docs/project-status.md > 从「活跃任务」表移除 task-001,在「已完成」表追加一行 > 4. DDL 移入 backlog/specs/archived/partner/schema.sql > ``` --- #### 7.4 常用 Trae 指令速查 | 你想做什么 | 直接在 Trae AI 对话框里说 | |-----------|--------------------------| | **新建规范文件** | `按 spec-kit/ 的风格,新增一个 16-xxx-topic.md 规范文件,内容是 XXX` | | **规划任务** | `帮我规划 XXX 模块的任务,写入 backlog/tasks/task-NNN-xxx.md` | | **开始执行** | `开始执行 task-NNN,按 Acceptance Criteria 逐条完成` | | **编译检查** | `编译 portal-base + portal-mcp,帮我修复报错` | | **格式化** | `对整个项目执行 spotless:apply` | | **代码审查** | `审查刚才生成的 PartnerToolImpl,按 spec-kit/05 的红线检查` | | **归档任务** | `task-NNN 已完成,帮我归档并更新 project-status.md` | | **查某个规范** | `AI Tool 的返回格式规范是什么?`(Trae 会自动读 05-ai-tool-development.md) | | **查某个工具类** | `BaseQuerySqlApi 有哪些方法?`(Trae 会读 portal-sdk 源码 + 09-key-base-classes.md) | #### 7.5 注意事项 | # | 注意 | 说明 | |---|------|------| | 1 | **Trae 不会自动替你做决策** | 生成代码前会给你方案选项,需要你确认后才写文件 | | 2 | **规范文件本身也需要维护** | 新模块/新技术栈进来后,记得让 Trae 同步更新 `spec-kit/` 下对应的规范文件 | | 3 | **不要绕过归档流程** | 即使是小改动,也让 Trae 更新 backlog——这样 `project-status.md` 永远是最新的 | | 4 | **Trae 读不到的文件要手动放到它能读到的位置** | 规范文件必须在项目根目录或子目录里,不能在 Trae 工作区之外 | | 5 | **一次只做一件事** | 不要说「帮我把所有模块都重构一遍」,拆成小任务逐个执行更稳 | --- ## 模块概览 ``` portal-gateway(启动入口,端口 80) ├── portal-sdk # 核心 SDK:工具类、配置、过滤器、AOP、BaseEntity ├── portal-base # 动态 SQL 引擎 + 业务 CRUD(Tenant、AdminUser 等) ├── portal-query # 查询模块 ├── portal-ai # AI 服务层(多模型路由 + 流式对话) ├── portal-mcp # AI MCP Tool 基类层(DbToolAbstractImpl) └── portal-dingtalk # 钉钉 Stream 机器人 + ServerNotice ``` 每个模块的完整包结构、类职责、依赖关系见 [`spec-kit/02-module-structure.md`](spec-kit/02-module-structure.md) 和 [`spec-kit/09-key-base-classes.md`](spec-kit/09-key-base-classes.md)。 --- ## 技术栈(节选) | 分类 | 技术 | |------|------| | 语言 | Java 25(OpenJDK) | | 框架 | Spring Boot 4.1.0 + Spring AI 2.0.0 | | ORM | MyBatis-Plus 3.5.17 | | AI 协议 | MCP(SSE 协议) | | 对象转换 | MapStruct 1.6.3(唯一协议,禁止 BeanUtil/手工 setter) | | 多租户 | ScopedValue(JDK 25)+ MyMetaObjectHandler 自动填充 | | 数据库 | MySQL 9.x + dynamic-datasource 双数据源 | | 前端 | Vue 3 + Vite + TypeScript + Element Plus + Pinia | 完整版本号 + Maven 依赖表见 [`spec-kit/01-tech-stack-config.md`](spec-kit/01-tech-stack-config.md)。 数据库表清单(8 张)见 [`backlog/docs/tech-stack-overview.md`](backlog/docs/tech-stack-overview.md)。 --- ## 前端管理后台 Vue 3 + TypeScript + Vite + Element Plus + Pinia。路由由后端菜单动态驱动,API 统一 POST `/api/{domain}/{action}`。 完整前端架构(目录、路由、权限、状态、环境变量、类型层拆分)见 [`spec-kit/13-frontend-architecture.md`](spec-kit/13-frontend-architecture.md)。 --- ## AI Tool 开发速查 ```java @Component @Slf4j public class XxxTool extends DbToolAbstractImpl { @Tool(name = "snake_case_name", description = "中文描述") public Map queryXxx(@ToolParam String param) { String sql = "SELECT ... WHERE col = ?"; List list = queryListAndFieldAnn(sql, XxxEntity.class, param); return Map.of("data", list, "字段解释:", fieldNames(XxxEntity.class)); } } ``` 完整 AI Tool 模板、命名规范、6 条红线见 [`spec-kit/05-ai-tool-development.md`](spec-kit/05-ai-tool-development.md)。 --- ## 文档索引 所有详细技术规范拆分在 `spec-kit/` 目录,AI Agent 主入口为 [`SPEC-KIT.md`](SPEC-KIT.md),含 15 个子文件索引 + Cheat Sheet + 架构决策回顾。 backlog 工作流(specs / tasks / milestones / 归档 / docs 同步)见 [`spec-kit/11-sdd-backlog-workflow.md`](spec-kit/11-sdd-backlog-workflow.md)。 --- ## License 本项目仅供内部使用。