Spec Kit 实战 04 · 个人博客增量需求实战：定时发布

1personal-blog/
2├── src/main/java/com/example/blog/
3│   ├── BlogStarter.java                # @SpringBootApplication 启动类
4│   ├── controller/PostController.java  # 含 publishNow 等接口
5│   ├── request/PostSaveRequest.java
6│   ├── vo/PostVO.java
7│   ├── service/PostService.java
8│   ├── service/impl/PostServiceImpl.java   # createDraft / publishNow / preview
9│   ├── mapper/PostMapper.java
10│   ├── entity/PostEntity.java
11│   └── job/                            # 已有 xxl-job 任务处理器
12├── src/main/resources/
13│   ├── application.yml + application-local.yml
14│   ├── mapper/PostMapper.xml
15│   └── db/ddl/                         # 现有表结构脚本
16├── src/test/java/com/example/blog/
17│   ├── PostServiceTest.java
18│   └── JobTest.java
19└── pom.xml

1现有状态：draft -> published（PostStatusEnum）
2现有入口：POST /api/post/publishNow
3现有公开详情：GET /api/post/queryBySlug（对外渲染为 /posts/{slug}）
4现有调度：xxl-job 控制台注册的每分钟任务
5现有时间存储：数据库 DATETIME，统一 UTC 口径
6必须回归：立即发布、草稿预览、公开 URL、作者权限

1给博客增加高级发布功能，顺便优化文章模块。

1/speckit.specify
2在现有个人博客服务中增加定时发布：作者可以为 draft 文章设置一个未来发布时间；
3到点后系统通过现有 xxl-job 任务自动公开文章。
4
5必须保持：现有立即发布接口、草稿预览、作者权限、文章 slug 和公开 URL 不变。
6定时发布后，文章内容和 URL 与立即发布结果一致。
7
8第一版不做周期发布、社交平台分发、发布失败通知、内容审批流、批量调度，
9也不允许用户选择展示时区。不要重构整个 posts 模块或引入新队列。

1### User Story 1 - Schedule a draft (P1)
21. Given 文章为 draft，When 作者设置未来时间，
3   Then 状态变为 scheduled，持久化 UTC 时间，到点前公开接口返回 404。
42. Given 时间等于或早于服务端当前时间，When 设置调度，
5   Then 返回 SCHEDULE_TIME_MUST_BE_FUTURE，文章保持 draft。
63. Given 文章已 published，When 设置调度，
7   Then 返回 POST_NOT_DRAFT，公开文章不变。
8
9### User Story 2 - Reschedule or cancel (P1)
101. Given 文章为 scheduled，When 改为另一个未来时间，Then 只有新时间生效。
112. Given 文章为 scheduled，When 取消，Then 回到 draft 且 scheduled_at 清空。
12
13### User Story 3 - Publish due posts (P1)
141. Given scheduled_at <= now，When 任务运行，Then 原子变为 published 且只执行一次。
152. Given 系统停机期间错过时间，When 恢复后任务首次运行，Then 文章被补发。
163. Given 两个 worker 同时扫描，When 都尝试发布，Then 只有一个状态更新成功。
17
18### Regression Acceptance
19- 立即发布仍使用原接口并保持响应契约。
20- draft/scheduled 的作者预览仍可用。
21- slug 和公开 URL 不改变。
22- 非作者仍不能修改调度。

1specs/002-scheduled-publishing/spec.md

1/speckit.clarify
2重点检查：过去时间、时区输入、改期/取消、文章编辑与调度的关系、
3停机补发、双 worker 幂等、立即发布与定时发布冲突。优先询问会改变
4现有状态机、数据迁移或外部 API 的问题。

1/speckit.plan
2先读取 com/example/blog/service/impl/PostServiceImpl.java、
3controller/PostController.java、job/ 下现有任务处理器、PostMapper.xml、
4现有 DDL 脚本和测试。复用现有 xxl-job 调度和 ResultDTO/CodeEnum 响应约定，
5不引入 Redis、消息队列或第二套 PostService。
6
7为 t_post 增加 SCHEDULED 状态枚举值和 nullable 的 scheduled_at（DATETIME，
8UTC 口径）；提供向前与回滚 DDL。增加设置、改期、取消调度的接口，沿用现有
9request/vo 风格。发布任务每分钟查找到期记录，用条件 UPDATE 从 scheduled
10原子迁移到 published；失败记录保持 scheduled，下一轮重试。
11立即发布 scheduled 文章时清空 scheduled_at，并保持现有 URL 与权限。
12
13输出真实文件路径、状态机、接口契约、DDL、双 worker/停机补发测试，
14以及全部现有 posts 回归命令（注意父 POM 可能默认 skipTests=true）。
15任何新依赖都必须说明现有能力为何不足。

1stateDiagram-v2
2    [*] --> draft
3    draft --> published: 立即发布
4    draft --> scheduled: 设置未来时间
5    scheduled --> scheduled: 改期
6    scheduled --> draft: 取消调度
7    scheduled --> published: 到点任务或立即发布

1t_post.status: PostStatusEnum 增加 SCHEDULED（tinyint 新枚举值，不动旧值）
2t_post.scheduled_at: DATETIME, nullable, UTC 口径
3index: idx_status_scheduled_at(status, scheduled_at) 支持到期扫描

1ALTER TABLE `t_post`
2    ADD COLUMN `scheduled_at` DATETIME NULL COMMENT '定时发布时间（UTC 口径）',
3    MODIFY COLUMN `status` TINYINT NOT NULL
4        COMMENT '0=draft，1=scheduled，2=published';
5ALTER TABLE `t_post`
6    ADD INDEX `idx_status_scheduled_at` (`status`, `scheduled_at`);

1POST /api/post/schedule        PostScheduleRequest { postId, scheduledAt }
2POST /api/post/cancelSchedule  @RequestParam postId
3POST /api/post/publishNow      # 原接口，兼容 scheduled 文章

1rg -n "queue|redis|rocketmq|kafka|ScheduledPostService|第二个调度" specs/002-scheduled-publishing

1- [ ] 实现定时发布功能

1## Phase 1: Migration and state
2- [ ] BT001 添加 SCHEDULED 状态值与 scheduled_at 列的向前 DDL src/main/resources/db/ddl/V042__schedule_post.sql
3- [ ] BT002 添加回滚 DDL 并验证执行/回滚 src/main/resources/db/ddl/U042__schedule_post_rollback.sql
4- [ ] BT003 [P] 更新 PostEntity、PostStatusEnum 与索引映射 src/main/java/com/example/blog/entity/PostEntity.java
5
6## Phase 2: Schedule management (BFR-001..004)
7- [ ] BT004 [P] 编写未来时间、过去时间、非 draft、offset 校验测试 src/test/java/com/example/blog/PostSchedulingTest.java
8- [ ] BT005 实现设置/改期/取消调度 PostServiceImpl.schedule/cancelSchedule
9- [ ] BT006 实现 /api/post/schedule 与 /api/post/cancelSchedule controller/PostController.java
10- [ ] BT007 验证 scheduled 到点前公开 404、作者预览可用 src/test/java/com/example/blog/PostSchedulingTest.java
11
12## Phase 3: Due publishing (BFR-005..007)
13- [ ] BT008 [P] 编写停机补发与失败重试测试 src/test/java/com/example/blog/PublishDuePostsJobTest.java
14- [ ] BT009 编写双 worker 原子状态迁移测试 src/test/java/com/example/blog/PublishDuePostsJobTest.java
15- [ ] BT010 实现并注册 publishDuePosts 任务 job/PublishDuePostsJob.java + PostMapper.xml 条件 UPDATE
16
17## Phase 4: Compatibility (BFR-008)
18- [ ] BT011 更新立即发布以支持 scheduled 并清空 scheduled_at service/impl/PostServiceImpl.java
19- [ ] BT012 运行立即发布、预览、权限、slug、公开 URL 回归测试
20- [ ] BT013 执行 quickstart、DDL 回滚与完整测试（-DskipTests=false）

1“发布审批”改变了角色、权限和状态机，不属于已批准的 BFR-001..008。
2当前 feature 继续交付定时发布；另建下一 feature 描述审批用户故事、状态迁移、
3权限和验收。两者通过现有 published 状态衔接，不在本 PR 顺手实现。

1/speckit.implement
2只执行 BT001-BT003。运行 DDL 执行/回滚和实体相关测试，不修改发布逻辑。

1/speckit.implement
2执行 BT004-BT007。沿用现有 controller/request/vo 和 ResultDTO 错误响应模式；
3运行 PostSchedulingTest 和原有 preview 测试。不要实现后台发布任务。

1/speckit.implement
2执行 BT008-BT013。双 worker 测试必须验证只有一次状态迁移；运行完整
3posts/job 测试、现有立即发布/预览/权限/URL 回归和 DDL 回滚。报告未执行项。

1@Lazy
2@Component
3@JobHander("publishDuePostsJob")
4public class PublishDuePostsJob extends IJobHandler {
5
6    @Resource
7    private PostMapper postMapper;
8
9    @Override
10    public ReturnT<String> execute(String... strings) throws Exception {
11        // 条件 UPDATE 把“到期”与“迁移”绑在同一条 SQL 上：
12        // status 仍是 SCHEDULED 才会被更新，天然幂等，双 worker 并发时后者影响 0 行
13        int published = postMapper.publishDuePosts(new Date());
14        XxlJobLogger.log("[publishDuePostsJob] --- 本轮定时发布文章数: [{0}]", published);
15        return ReturnT.SUCCESS;
16    }
17}

1<update id="publishDuePosts">
2    UPDATE `personal-blog`.`t_post`
3    SET `status` = 2,
4        `scheduled_at` = NULL,
5        `update_time` = now()
6    WHERE `status` = 1
7      AND `scheduled_at` &lt;= #{now}
8      AND `is_delete` = 0
9</update>

1private void validateScheduleTimeOrThrow(PostEntity post, Date scheduledAt) {
2    if (PostStatusEnum.PUBLISHED.equals(post.getStatus())) {
3        throw new FailedException(CodeEnum.POST_NOT_DRAFT.getCode());
4    }
5    if (!scheduledAt.after(new Date())) {
6        throw new FailedException(CodeEnum.SCHEDULE_TIME_MUST_BE_FUTURE.getCode());
7    }
8}

1personal-blog/
2├── specs/002-scheduled-publishing/
3├── src/main/resources/db/ddl/V042__schedule_post.sql
4├── src/main/java/com/example/blog/
5│   ├── controller/PostController.java            # 新增 schedule/cancelSchedule
6│   ├── request/PostScheduleRequest.java
7│   ├── service/impl/PostServiceImpl.java         # schedule/cancelSchedule/publishNow 调整
8│   ├── job/PublishDuePostsJob.java
9│   └── enums/PostStatusEnum.java                 # 增加 SCHEDULED
10├── src/main/resources/mapper/PostMapper.xml      # publishDuePosts 条件 UPDATE
11└── src/test/java/com/example/blog/
12    ├── PostSchedulingTest.java
13    └── PublishDuePostsJobTest.java

1openspec/changes/add-scheduled-publishing/
2├── proposal.md        # Intent：作者希望设定未来时间自动公开；
3│                      # Scope：不含周期发布/通知/审批/时区选择
4├── specs/post-publishing/spec.md
5│                      # delta：## Purpose + ## ADDED Requirements
6│                      # （BFR-001..008 的行为版，Scenario 用 GIVEN/WHEN/THEN）
7├── design.md          # 复用 xxl-job、条件 UPDATE 状态迁移（本章 Plan 的关键决策）
8└── tasks.md           # BT001..BT013 的分组编号复选清单