@specpow/framework 0.6.0 → 0.6.1

package/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.1] - 2026-09-10
+
+### 🔧 mes-prd-to-code Schema 规则修正
+
+统一后端 Excel 导出/导入公共基类约定，修正包路径错误。
+
+#### 变更内容
+
+- **后端公共类引用规则**：导出统一使用 `BaseExcelExportTemplate`、导入统一使用 `BaseAnalysisEventListener`（均为 `com.twsz.mom.ds.util.excel`）
+- **后端 Controller 规范**：导出/导入逻辑封装在 ServiceImpl，Controller 只负责调用
+- **EasyExcel 白名单**：仅允许 `EasyExcel.read(...)`（作为 `BaseAnalysisEventListener` 的驱动入口）；禁止 `EasyExcel.write(...)`、`doReadSync()`
+- **ExcelUtil 废弃**：`com.twsz.mom.web.utils.ExcelUtil` 标注为已废弃，禁止使用
+- 修正 `BaseExcelExportTemplate` 包路径（`core.web.excel` → `ds.util.excel`）并补齐 API 说明（`getTotal()`、`getData(start, size)`，start 从 1 开始）
+- `templates/tech-design.md` 伪代码由 `uploadExcel(List<T>)` 改为 `export(...)` + `handle(List<T>)`
+
 ## [0.5.29] - 2026-08-31
 
 ### ✨ Memory Auto Adapter 系统

package/builtin/schemas/mes-prd-to-code/references.md

@@ -37,13 +37,14 @@
 - `new BaseException(String message)` → 从消息构造
 - `new BaseException(HttpStatus status, Object... args)` → 带参数格式化
 
-### ExcelUtil (com.twsz.mom.core.utils.ExcelUtil)
+### ExcelUtil (com.twsz.mom.web.utils.ExcelUtil) 【已废弃，禁止使用】
 - `importExcel(InputStream is)` → `List<Map<String, Object>>`（原始导入）
 - `importExcel(InputStream is, Class<T> clazz)` → `List<T>`（类型化导入）
 - `export(HttpServletResponse resp, Class<T> clazz, Boolean isCsv, Collection<?> data)` → 标准导出
 - `export(HttpServletResponse resp, Class<T> clazz, Boolean isCsv, Supplier<Collection<?>> supplier)` → 懒加载导出
 - `responseJson(HttpServletResponse resp, ResponseWrapper<T> wrapper)` → 写 JSON 错误响应
 - `exportException(HttpServletResponse resp, Throwable e)` → 写异常为 JSON
+- 废弃说明: 导出改用 BaseExcelExportTemplate，导入改用 BaseAnalysisEventListener；本节仅用于识别存量代码
 
 ### ApplicationContextUtil (com.twsz.mom.core.utils.ApplicationContextUtil)
 - `getUserActName()` → 获取当前登录用户名称（仅在业务逻辑中需要用户名时使用，如日志记录、业务校验）
@@ -53,12 +54,24 @@
 - `fastSimpleUUID()` → 生成无横线 UUID（用于导出文件名等）
 
 ### EasyExcel (com.alibaba.excel.EasyExcel)
-- `EasyExcel.write(OutputStream, Class<T>).sheet("sheet").doWrite(List)` → 简单导出
-- `EasyExcel.read(InputStream, Class<T>, ReadListener).sheet().doRead()` → 监听式导入
-
-### BaseExcelExportTemplate (com.twsz.mom.core.web.excel.BaseExcelExportTemplate)
-- 抽象类：`getTotal()` + `getData(Integer start, Integer size)` → 分批导出模板
-- 默认 batch size: 1000, sheet max: 1,048,576
+- `EasyExcel.read(InputStream, Class<T>, ReadListener).sheet().doRead()` → 监听式导入（唯一允许用法，必须配合 BaseAnalysisEventListener）
+- 禁止: EasyExcel.write(...)、EasyExcel.read(...).doReadSync()
+
+### BaseExcelExportTemplate (com.twsz.mom.ds.util.excel.BaseExcelExportTemplate)
+- 定义: public abstract class BaseExcelExportTemplate<T>
+- 抽象方法: int getTotal() 与 List<T> getData(Integer start, Integer size)
+- 重要: getData 的 start 参数从 1 开始（源码按 getData(i + 1, batchSize) 调用）
+- 构造器: (Class<T>) / (String fileName, String sheetName, Class<T>) / (..., Integer batchSize) / (..., Integer batchSize, Integer sheetNum)
+- 默认值: batchSize=1000, sheetNum=1048576；sheetNum < batchSize 抛 BaseException
+- exportBatch(HttpServletResponse, Converter<?>...) → 同步导出，内置 try-catch，失败回写 ResponseWrapper.ofFail("导出失败")
+- exportBatch(OutputStream, WriteHandler, Converter<?>...) → 异步落文件，抛异常
+
+### BaseAnalysisEventListener (com.twsz.mom.ds.util.excel.BaseAnalysisEventListener)
+- 定义: public abstract class BaseAnalysisEventListener<T> extends com.alibaba.excel.event.AnalysisEventListener<T>
+- 构造器: (int batchSize)
+- 抽象方法: void handle(List<T> dataList) — 唯一需要实现的方法
+- 分批机制: invoke() 累积满 batchSize 触发 handle() 并清空；doAfterAllAnalysed() 冲刷余量
+- 用法: EasyExcel.read(inputStream, Entity.class, new BaseAnalysisEventListener<Entity>(1000){ handle(list) }).sheet().doRead()
 
 ### ViewModel 常量 (com.twsz.mom.ds.model.ViewModel)
 - `ViewModel.OPT_ADD = "1"` — 新增标记

package/builtin/schemas/mes-prd-to-code/rules.md

@@ -58,8 +58,10 @@
 - Controller 只做参数校验和结果封装，禁止写业务逻辑
 - 禁止在 Controller 中 try-catch（全局异常处理器 @ControllerAdvice 统一处理）
 - delete 接口: @DeleteMapping，接收 `Long[] ids`
-- export 接口: 使用 ExcelUtil.export() 或 EasyExcel 直接写入 HttpServletResponse
-- import 接口: 接收 MultipartFile，使用 ExcelUtil.importExcel() 或 EasyExcel.read()
+- export 接口: 必须用 BaseExcelExportTemplate 匿名子类（实现 getTotal()、getData(start, size)，start 从 1 开始），调用 exportBatch(HttpServletResponse, Converter...) 写入响应；禁止 ExcelUtil.export()、禁止 EasyExcel.write()
+- export 位置: 匿名子类封装在 ServiceImpl 导出方法中（如 entityService.export(entity, response)），Controller 只注入调用，禁止在 Controller 内写导出逻辑
+- import 接口: 接收 MultipartFile，必须用 EasyExcel.read(inputStream, Entity.class, new BaseAnalysisEventListener<Entity>(batchSize) { handle(List<Entity>) }).sheet().doRead() 驱动；禁止 ExcelUtil.importExcel()、禁止 doReadSync() 裸读
+- import 位置: 校验与入库逻辑写在 BaseAnalysisEventListener.handle(List<Entity>) 内，由 batchSize 控制分批；禁止在 handle() 内单条循环查询
 
 ## 后端 Service 规范
 
@@ -107,8 +109,10 @@
 - BaseException: `new BaseException(AIHttpStatus.XXX.getCode(), AIHttpStatus.XXX.getMessage())` — com.twsz.mom.core.exception.BaseException
 - PageForm<T>: size(页大小), current(页码,1-based), condition(查询条件对象) — com.twsz.mom.core.common.PageForm
 - ApplicationContextUtil: 获取当前用户名称（getUserActName） — com.twsz.mom.core.utils.ApplicationContextUtil
-- ExcelUtil: importExcel/export — com.twsz.mom.core.utils.ExcelUtil
-- EasyExcel: com.alibaba.excel.EasyExcel
+- BaseExcelExportTemplate: 导出统一基类，匿名子类实现 getTotal() 与 getData(start, size)（start 从 1 开始），调用 exportBatch(response, converters...) — com.twsz.mom.ds.util.excel.BaseExcelExportTemplate
+- BaseAnalysisEventListener: 导入统一监听器，new BaseAnalysisEventListener<T>(batchSize){ handle(list) }，配合 EasyExcel.read(...) 驱动 — com.twsz.mom.ds.util.excel.BaseAnalysisEventListener
+- EasyExcel: 仅允许 EasyExcel.read(...) 驱动 BaseAnalysisEventListener，禁止 EasyExcel.write() — com.alibaba.excel.EasyExcel
+- ExcelUtil: 【已废弃，禁止使用】 — com.twsz.mom.web.utils.ExcelUtil
 - ViewModel.OPT_ADD = "1", OPT_MODIFY = "2", OPT_DELETE = "3", OPT_NOT_MODIFY_DATE = "0"
 - IdUtil: cn.hutool.core.util.IdUtil（fastSimpleUUID 等）
 

package/builtin/schemas/mes-prd-to-code/schema.yaml

@@ -230,7 +230,7 @@ artifacts:
         - PUT /{entity}/update — 修改
         - DELETE /{entity}/delete — 批量删除
         - POST /{entity}/export — 导出
-        - POST /{entity}/uploadExcel — 导入（如有）
+        - POST /{entity}/uploadExcel — 导入（如有），由 BaseAnalysisEventListener 承载批量校验与入库
       - 外部接口（如功能文档有定义）：
         - 按功能文档定义的路径和方法
         - 请求/响应格式按功能文档
@@ -409,7 +409,7 @@ artifacts:
       - deleteByIds: 批量删除+级联
       - search: 分页查询
       - list: 列表查询
-      - importExcel/uploadExcel: 逐行校验、跳过统计（如有）
+      - uploadExcel: BaseAnalysisEventListener.handle() 内批量校验、跳过统计（如有）
 
       ## 文件路径
       测试文件放在: src/test/java/{与ServiceImpl相同的包路径}/

package/builtin/schemas/mes-prd-to-code/templates/tech-design.md

@@ -236,10 +236,17 @@ insert({Entity} entity):
     1. <校验规则描述>
     2. <校验通过> → baseMapper.insert(entity)
 
-uploadExcel(List<{Entity}> list):
+export({Entity} entity, HttpServletResponse response):
+    new BaseExcelExportTemplate<{Entity}>({Entity}.class) {
+        getTotal() → <总数查询描述>
+        getData(start, size) → <分页查询描述，start 从 1 开始>
+    }.exportBatch(response)
+
+handle(List<{Entity}> list):
+    // BaseAnalysisEventListener 回调，由 EasyExcel.read(...).doRead() 驱动
     @Transactional(rollbackFor = Exception.class)
-    1. <导入校验描述>
-    2. 逐行 insert
+    1. <批量导入校验描述>
+    2. 批量 insert（按 batchSize 分批）
 ```
 
 ### 3.4 Controller

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specpow/framework",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Spec-Powered AI Development Framework - 融合 OpenSpec 规范驱动 + Superpowers 执行引擎的企业级 AI 辅助编程框架",
   "type": "module",
   "main": "dist/index.js",