Skip to content

Commit 1225d4d

Browse files
loong10kloong10k
committed
docs: mark engines-webmvc, cleanup-sync and markdown plans complete
1 parent 1d63394 commit 1225d4d

3 files changed

Lines changed: 81 additions & 81 deletions

File tree

‎docs/superpowers/plans/2026-08-26-easypdf-cleanup-sync.md‎

Lines changed: 24 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# easypdf Word 侧清理与三分支终验计划（Phase 4）
22

3-
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
3+
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [x]`) syntax for tracking.
44
55
**Goal:** 完成 easypdf 的"纯 PDF"收敛：删除全部 docx4j Word 侧代码（core 的 Word 工具包、xhtml 的 HTML→docx 转换器、9 个旧 `WordprocessingML{Engine}Template`），xhtml 模块收敛为"HTML/Markdown → PDF"转换模块；三分支全量验证通过并做发布演练，确保三分支可正常发布。
66

@@ -30,12 +30,12 @@
3030
- Consumes: Phase 3（引擎已迁移，旧 Word 类无生产引用）
3131
- Produces: core 仅含 `PdfTemplate` + `core/convert` + `core/template`；依赖仅保留 iText html2pdf/kernel/layout/io 等
3232

33-
- [ ] **Step 1: 验证零引用**
33+
- [x] **Step 1: 验证零引用**
3434

3535
Run: `grep -rln "WordprocessingMLTemplate\|Docx4jConstants\|io.github.easy4j.pdf.io\|io.github.easy4j.pdf.wml\|io.github.easy4j.pdf.utils\|io.github.easy4j.pdf.fonts\|io.github.easy4j.pdf.handler\|io.github.easy4j.pdf.bus" --include="*.java" easypdf-*/src/main | grep -v "easypdf-core/src/main"`
3636
Expected: 空输出（跨模块零引用；easydoc 无关）
3737

38-
- [ ] **Step 2: 删除 core Word 侧**
38+
- [x] **Step 2: 删除 core Word 侧**
3939

4040
```bash
4141
git rm -r easypdf-core/src/main/java/io/github/easy4j/pdf/io \
@@ -49,7 +49,7 @@ git rm easypdf-core/src/main/java/io/github/easy4j/pdf/WordprocessingMLTemplate.
4949
easypdf-core/src/main/java/io/github/easy4j/pdf/Docx4jConstants.java
5050
```
5151

52-
- [ ] **Step 3: 删除对应测试（保留 convert/template 测试）**
52+
- [x] **Step 3: 删除对应测试（保留 convert/template 测试）**
5353

5454
```bash
5555
for f in $(find easypdf-core/src/test/java -name "*.java"); do
@@ -60,16 +60,16 @@ for f in $(find easypdf-core/src/test/java -name "*.java"); do
6060
done
6161
```
6262

63-
- [ ] **Step 4: 编辑 core pom**
63+
- [x] **Step 4: 编辑 core pom**
6464

6565
删除 docx4j 三个依赖、javax.servlet-api、commons-lang3/commons-io、testExcludes 配置块。
6666

67-
- [ ] **Step 5: 验证**
67+
- [x] **Step 5: 验证**
6868

6969
Run: `~/tools/apache-maven-4.0.0-rc-6/bin/mvn -B -ntp -pl easypdf-core -am clean verify`
7070
Expected: BUILD SUCCESS
7171

72-
- [ ] **Step 6: Commit**
72+
- [x] **Step 6: Commit**
7373

7474
```bash
7575
git add -A
@@ -91,12 +91,12 @@ git commit -m "refactor(core): remove docx4j Word-side code and dependencies, ke
9191
- Consumes: Phase 3（9 引擎已不依赖 easypdf-xhtml）
9292
- Produces: xhtml 仅含 `convert/**`（EasyPdf/MarkdownConverter）与 HTML→PDF 相关依赖
9393

94-
- [ ] **Step 1: 验证零引用**
94+
- [x] **Step 1: 验证零引用**
9595

9696
Run: `grep -rln "WordprocessingMLHtmlTemplate\|XHTMLImporterUtils\|io.github.easy4j.pdf.xhtml" --include="*.java" easypdf-*/src/main | grep -v "easypdf-xhtml/src/main"`
9797
Expected: 空输出（引擎已迁移，无跨模块引用）
9898

99-
- [ ] **Step 2: 删除 xhtml Word 侧**
99+
- [x] **Step 2: 删除 xhtml Word 侧**
100100

101101
```bash
102102
git rm -r easypdf-xhtml/src/main/java/io/github/easy4j/pdf/xhtml/handler \
@@ -106,7 +106,7 @@ git rm easypdf-xhtml/src/main/java/io/github/easy4j/pdf/xhtml/WordprocessingMLHt
106106
easypdf-xhtml/src/main/java/io/github/easy4j/pdf/xhtml/DataMap.java
107107
```
108108

109-
- [ ] **Step 3: 删除对应测试与 demo**
109+
- [x] **Step 3: 删除对应测试与 demo**
110110

111111
```bash
112112
git rm easypdf-xhtml/src/test/java/io/github/easy4j/pdf/xhtml/WordprocessingMLHtmlTemplateTest.java \
@@ -123,14 +123,14 @@ git rm -r easypdf-xhtml/src/test/java/io/github/easy4j/pdf/xhtml/handler \
123123
easypdf-xhtml/src/test/java/io/github/easy4j/pdf/xhtml/utils
124124
```
125125

126-
- [ ] **Step 4: 编辑 xhtml pom**（移除 docx4j-ImportXHTML/xhtmlrenderer/cssparser/flying-saucer-pdf 依赖与 testExcludes）
126+
- [x] **Step 4: 编辑 xhtml pom**（移除 docx4j-ImportXHTML/xhtmlrenderer/cssparser/flying-saucer-pdf 依赖与 testExcludes）
127127

128-
- [ ] **Step 5: 验证**
128+
- [x] **Step 5: 验证**
129129

130130
Run: `~/tools/apache-maven-4.0.0-rc-6/bin/mvn -B -ntp -pl easypdf-xhtml -am clean verify`
131131
Expected: BUILD SUCCESS
132132

133-
- [ ] **Step 6: Commit**
133+
- [x] **Step 6: Commit**
134134

135135
```bash
136136
git add -A
@@ -150,7 +150,7 @@ git commit -m "refactor(xhtml): remove docx4j conversion classes, keep HTML/Mark
150150
- Consumes: Phase 3（新 `{Engine}PdfTemplate` 已就位且测试通过）
151151
- Produces: 每个引擎模块仅含 `{Engine}PdfTemplate` 与其测试
152152

153-
- [ ] **Step 1: 删除旧类与旧测试**
153+
- [x] **Step 1: 删除旧类与旧测试**
154154

155155
```bash
156156
for m in freemarker velocity thymeleaf beetl rythm jetbrick httl webit jsp; do
@@ -161,12 +161,12 @@ for m in freemarker velocity thymeleaf beetl rythm jetbrick httl webit jsp; do
161161
done
162162
```
163163

164-
- [ ] **Step 2: 全量验证**
164+
- [x] **Step 2: 全量验证**
165165

166166
Run: `~/tools/apache-maven-4.0.0-rc-6/bin/mvn -B -ntp clean verify`
167167
Expected: BUILD SUCCESS；记录测试基线（xhtml 的 19 个 docx4j 测试已删，engine 新测试 + core 测试为净增量）
168168

169-
- [ ] **Step 3: Commit**
169+
- [x] **Step 3: Commit**
170170

171171
```bash
172172
git add -A
@@ -184,40 +184,40 @@ git commit -m "refactor(engines): remove legacy WordprocessingML engine adapters
184184
- Consumes: Task 1-3 产物
185185
- Produces: 三分支纯 PDF 形态、全量 verify 通过、发布配置可执行
186186

187-
- [ ] **Step 1: 3.0.x 最终验证 + 发布演练**
187+
- [x] **Step 1: 3.0.x 最终验证 + 发布演练**
188188

189189
Run: `~/tools/apache-maven-4.0.0-rc-6/bin/mvn -B -ntp clean verify`
190190
Expected: BUILD SUCCESS
191191

192192
Run: `~/tools/apache-maven-4.0.0-rc-6/bin/mvn -B -ntp -DskipTests -P central install`（本地验证 central profile 装配，不触网发布）
193193
Expected: BUILD SUCCESS（校验 central-publishing-plugin 配置与 GPG/源码/javadoc 插件装配无误）
194194

195-
- [ ] **Step 2: 同步到 1.0.x**（对比整合：Word 侧删除 + 依赖清理 + testExcludes 移除）
195+
- [x] **Step 2: 同步到 1.0.x**（对比整合：Word 侧删除 + 依赖清理 + testExcludes 移除）
196196

197197
```bash
198198
git checkout feature/1.0.x
199199
# 移植 Task 1-3 变更
200200
```
201201

202-
- [ ] **Step 3: 验证 1.0.x**（含 `-P central` 本地装配，1.0.x 用 Maven 3.9.16）
202+
- [x] **Step 3: 验证 1.0.x**（含 `-P central` 本地装配，1.0.x 用 Maven 3.9.16）
203203

204204
Run: `/opt/homebrew/bin/mvn -B -ntp clean verify` + `/opt/homebrew/bin/mvn -B -ntp -DskipTests -P central install`
205205
Expected: BUILD SUCCESS
206206

207-
- [ ] **Step 4: Commit 1.0.x**
207+
- [x] **Step 4: Commit 1.0.x**
208208

209209
```bash
210210
git add -A
211211
git commit -m "refactor(cleanup): sync Word-side removal and final PDF-only state from 3.0.x"
212212
```
213213

214-
- [ ] **Step 5: 同步到 2.0.x**（同 Step 2）
214+
- [x] **Step 5: 同步到 2.0.x**（同 Step 2）
215215

216-
- [ ] **Step 6: 验证 2.0.x**（同 Step 3）
216+
- [x] **Step 6: 验证 2.0.x**（同 Step 3）
217217

218-
- [ ] **Step 7: Commit 2.0.x**（同 Step 4 信息）
218+
- [x] **Step 7: Commit 2.0.x**（同 Step 4 信息）
219219

220-
- [ ] **Step 8: 回 3.0.x 推送三分支 + 勾选本计划**
220+
- [x] **Step 8: 回 3.0.x 推送三分支 + 勾选本计划**
221221

222222
```bash
223223
git checkout feature/3.0.x

‎docs/superpowers/plans/2026-08-26-easypdf-engines-webmvc.md‎

Lines changed: 28 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# easypdf 引擎适配器与 webmvc 迁移计划（Phase 3）
22

3-
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
3+
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [x]`) syntax for tracking.
44
55
**Goal:** 把 9 个模板引擎适配器从 docx4j Word 输出（包装 `WordprocessingMLHtmlTemplate`）迁移到 PDF 输出（`PdfTemplate` + html2pdf 管线），并为 webmvc 提供 `PdfTemplateView`/`PdfViewResolver`，完成 easypdf "引擎渲染 HTML → PDF"的主链路。
66

@@ -31,7 +31,7 @@
3131
- `public abstract class AbstractStringTemplateWrappingPdfTemplate extends PdfTemplate` —— 构造器 `protected AbstractStringTemplateWrappingPdfTemplate()`；`process(String template, Map vars, OutputStream out)` 已实现（`render(template, vars)` → `HtmlPdfConverter.htmlToPdf(html, out)`）；`protected abstract String render(String template, Map<String, Object> variables) throws Exception;`（引擎特有渲染）
3232
- Task 2-3 的 9 个引擎适配器继承此基类
3333

34-
- [ ] **Step 1: 写失败测试**
34+
- [x] **Step 1: 写失败测试**
3535

3636
`AbstractStringTemplateWrappingPdfTemplateTest.java`：
3737
```java
@@ -81,12 +81,12 @@ class AbstractStringTemplateWrappingPdfTemplateTest {
8181
}
8282
```
8383

84-
- [ ] **Step 2: 运行测试确认失败**
84+
- [x] **Step 2: 运行测试确认失败**
8585

8686
Run: `~/tools/apache-maven-4.0.0-rc-6/bin/mvn -B -ntp -pl easypdf-core -am test -Dtest=AbstractStringTemplateWrappingPdfTemplateTest`
8787
Expected: FAIL（类不存在）
8888

89-
- [ ] **Step 3: 实现基类**
89+
- [x] **Step 3: 实现基类**
9090

9191
```java
9292
package io.github.easy4j.pdf.template;
@@ -121,12 +121,12 @@ public abstract class AbstractStringTemplateWrappingPdfTemplate extends PdfTempl
121121
}
122122
```
123123

124-
- [ ] **Step 4: 运行测试确认通过**
124+
- [x] **Step 4: 运行测试确认通过**
125125

126126
Run: `~/tools/apache-maven-4.0.0-rc-6/bin/mvn -B -ntp -pl easypdf-core -am test -Dtest=AbstractStringTemplateWrappingPdfTemplateTest`
127127
Expected: PASS（2 tests）
128128

129-
- [ ] **Step 5: Commit**
129+
- [x] **Step 5: Commit**
130130

131131
```bash
132132
git add easypdf-core/src/main/java/io/github/easy4j/pdf/template/AbstractStringTemplateWrappingPdfTemplate.java easypdf-core/src/test/java/io/github/easy4j/pdf/template/AbstractStringTemplateWrappingPdfTemplateTest.java
@@ -147,7 +147,7 @@ git commit -m "feat(engines): add AbstractStringTemplateWrappingPdfTemplate base
147147
- Produces: `FreemarkerPdfTemplate` —— 构造器（无参/`(boolean landscape, boolean altChunk)` 保留兼容签名但忽略布局参数）+ `getEngine()/setEngine()/setFreemarkerSettings/setPreTemplateLoaders/setPostTemplateLoaders/setDefaultEncoding/setFreemarkerVariables`（从旧类复制）+ `render(String, Map)` 用 `getEngine().getTemplate(template).process(variables, writer)` 产出 HTML
148148
- 其余 8 个引擎（Task 3）按同一模式
149149

150-
- [ ] **Step 1: 写失败测试**
150+
- [x] **Step 1: 写失败测试**
151151

152152
`FreemarkerPdfTemplateTest.java`：
153153
```java
@@ -188,12 +188,12 @@ class FreemarkerPdfTemplateTest {
188188
}
189189
```
190190

191-
- [ ] **Step 2: 运行测试确认失败**
191+
- [x] **Step 2: 运行测试确认失败**
192192

193193
Run: `~/tools/apache-maven-4.0.0-rc-6/bin/mvn -B -ntp -pl easypdf-freemarker -am test -Dtest=FreemarkerPdfTemplateTest`
194194
Expected: FAIL（类不存在）
195195

196-
- [ ] **Step 3: 实现 FreemarkerPdfTemplate**
196+
- [x] **Step 3: 实现 FreemarkerPdfTemplate**
197197

198198
从 `WordprocessingMLFreemarkerTemplate` 复制引擎配置代码（`engine`/`freemarkerSettings`/`freemarkerVariables`/`templateLoaders`/`preTemplateLoaders`/`postTemplateLoaders`/`getInternalEngine()`/`getAggregateTemplateLoader()`/`postProcessTemplateLoaders()` 及全部 setter），差异仅两处：继承 `AbstractStringTemplateWrappingPdfTemplate` 而非 `WordprocessingMLTemplate`；删除 `mlHtmlTemplate` 字段与构造器，`render` 实现为：
199199

@@ -337,16 +337,16 @@ public class FreemarkerPdfTemplate extends AbstractStringTemplateWrappingPdfTemp
337337
}
338338
```
339339

340-
- [ ] **Step 4: 修改 freemarker pom 依赖**
340+
- [x] **Step 4: 修改 freemarker pom 依赖**
341341

342342
`easypdf-freemarker/pom.xml`：`<artifactId>easypdf-xhtml</artifactId>` 改为 `<artifactId>easypdf-core</artifactId>`。
343343

344-
- [ ] **Step 5: 运行测试确认通过**
344+
- [x] **Step 5: 运行测试确认通过**
345345

346346
Run: `~/tools/apache-maven-4.0.0-rc-6/bin/mvn -B -ntp -pl easypdf-freemarker -am test -Dtest=FreemarkerPdfTemplateTest`
347347
Expected: PASS（1 test）
348348

349-
- [ ] **Step 6: Commit**
349+
- [x] **Step 6: Commit**
350350

351351
```bash
352352
git add easypdf-freemarker
@@ -382,16 +382,16 @@ git commit -m "feat(engines): add FreemarkerPdfTemplate rendering HTML templates
382382
- Webit：`WebitEngine` + `WebitTemplate.merge(Map, Writer)`
383383
- JSP：`JspTemplateImpl`（复用 easypdf-jsp/engine 包内现有 JspEngine 抽象，render 走 `JspEngine.render(template, vars)`）
384384

385-
- [ ] **Step 1: 逐个迁移（每个引擎：复制旧类引擎代码 → 改继承 → render 实现 → pom 依赖 → 测试）**
385+
- [x] **Step 1: 逐个迁移（每个引擎：复制旧类引擎代码 → 改继承 → render 实现 → pom 依赖 → 测试）**
386386

387387
对每个引擎重复 Task 2 的 Step 1-5 模式，测试断言统一为：渲染该引擎的简单模板（如 `<html><body><h1>${var}</h1></body></html>` 的引擎语法版本）→ 输出以 `%PDF-` 开头。模板资源放各模块 `src/test/resources/tpl/`。
388388

389-
- [ ] **Step 2: 每引擎验证**
389+
- [x] **Step 2: 每引擎验证**
390390

391391
Run: `~/tools/apache-maven-4.0.0-rc-6/bin/mvn -B -ntp -pl easypdf-{engine} -am test -Dtest={Engine}PdfTemplateTest`
392392
Expected: PASS
393393

394-
- [ ] **Step 3: 汇总提交**
394+
- [x] **Step 3: 汇总提交**
395395

396396
```bash
397397
git add easypdf-velocity easypdf-thymeleaf easypdf-beetl easypdf-rythm easypdf-jetbrick easypdf-httl easypdf-webit easypdf-jsp
@@ -414,7 +414,7 @@ git commit -m "feat(engines): migrate remaining 8 template engines to PDF output
414414
- `public class PdfTemplateView extends AbstractView` —— `setTemplate(PdfTemplate)`/`setTemplateName(String)`；`renderMergedOutputModel` 用 `createTemporaryOutputStream()` → `template.process(templateName, model, baos)` → `writeToResponse(response, baos)`
415415
- `public class PdfViewResolver implements ViewResolver` —— `resolveViewName` 返回 `PdfTemplateView`（PdfTemplate 通过 setter 注入）
416416

417-
- [ ] **Step 1: 写失败测试**
417+
- [x] **Step 1: 写失败测试**
418418

419419
`PdfTemplateViewTest.java`（用 `MockHttpServletResponse`，验证 `application/pdf` 内容类型与 PDF 魔数）：
420420
```java
@@ -457,12 +457,12 @@ class PdfTemplateViewTest {
457457
}
458458
```
459459

460-
- [ ] **Step 2: 运行测试确认失败**
460+
- [x] **Step 2: 运行测试确认失败**
461461

462462
Run: `~/tools/apache-maven-4.0.0-rc-6/bin/mvn -B -ntp -pl easypdf-webmvc -am test -Dtest=PdfTemplateViewTest`
463463
Expected: FAIL（类不存在）
464464

465-
- [ ] **Step 3: 实现 PdfTemplateView 与 PdfViewResolver**
465+
- [x] **Step 3: 实现 PdfTemplateView 与 PdfViewResolver**
466466

467467
```java
468468
package io.github.easy4j.pdf.webmvc;
@@ -544,12 +544,12 @@ public class PdfViewResolver implements ViewResolver {
544544
}
545545
```
546546

547-
- [ ] **Step 4: 运行测试确认通过**
547+
- [x] **Step 4: 运行测试确认通过**
548548

549549
Run: `~/tools/apache-maven-4.0.0-rc-6/bin/mvn -B -ntp -pl easypdf-webmvc -am test -Dtest=PdfTemplateViewTest`
550550
Expected: PASS（1 test）
551551

552-
- [ ] **Step 5: Commit**
552+
- [x] **Step 5: Commit**
553553

554554
```bash
555555
git add easypdf-webmvc
@@ -567,40 +567,40 @@ git commit -m "feat(webmvc): add PdfTemplateView and PdfViewResolver for PDF res
567567
- Consumes: Task 1-4 产物
568568
- Produces: 三分支均具备 9 个 `{Engine}PdfTemplate` + webmvc 视图 + 基类，全量 verify 通过
569569

570-
- [ ] **Step 1: 3.0.x 全量验证**
570+
- [x] **Step 1: 3.0.x 全量验证**
571571

572572
Run: `~/tools/apache-maven-4.0.0-rc-6/bin/mvn -B -ntp clean verify`
573573
Expected: BUILD SUCCESS；记录测试基线（≥ 246 + 新引擎测试）
574574

575-
- [ ] **Step 2: 同步到 1.0.x**（对比整合：引擎旧类保留、新类与 pom 变更移植）
575+
- [x] **Step 2: 同步到 1.0.x**（对比整合：引擎旧类保留、新类与 pom 变更移植）
576576

577577
```bash
578578
git checkout feature/1.0.x
579579
# 移植：core 基类 + 测试；9 个 {Engine}PdfTemplate + 测试；9 个引擎 pom 依赖变更；webmvc 新增文件（1.0.x 无 webmvc 模块则跳过）
580580
```
581581

582-
- [ ] **Step 3: 验证 1.0.x**
582+
- [x] **Step 3: 验证 1.0.x**
583583

584584
Run: `/opt/homebrew/bin/mvn -B -ntp clean verify`
585585
Expected: BUILD SUCCESS
586586

587-
- [ ] **Step 4: Commit 1.0.x**
587+
- [x] **Step 4: Commit 1.0.x**
588588

589589
```bash
590590
git add -A
591591
git commit -m "feat(engines): sync engine PDF migration from 3.0.x"
592592
```
593593

594-
- [ ] **Step 5: 同步到 2.0.x**（同 Step 2）
594+
- [x] **Step 5: 同步到 2.0.x**（同 Step 2）
595595

596-
- [ ] **Step 6: 验证 2.0.x**
596+
- [x] **Step 6: 验证 2.0.x**
597597

598598
Run: `/opt/homebrew/bin/mvn -B -ntp clean verify`
599599
Expected: BUILD SUCCESS
600600

601-
- [ ] **Step 7: Commit 2.0.x**（同 Step 4 信息）
601+
- [x] **Step 7: Commit 2.0.x**（同 Step 4 信息）
602602

603-
- [ ] **Step 8: 回 3.0.x 推送三分支**
603+
- [x] **Step 8: 回 3.0.x 推送三分支**
604604

605605
```bash
606606
git checkout feature/3.0.x

0 commit comments

Comments
 (0)