Spec Kit 实战 05 · 老项目接入 Spec Kit：先做一次低风险试点

1personal-blog/
2├── pom.xml                        # Spring Boot 父子结构、插件与 profile
3├── src/main/java/com/example/blog/
4│   ├── controller/                # PostController、TagController、CommentController
5│   ├── request/
6│   ├── vo/
7│   ├── service/ + service/impl/
8│   ├── mapper/
9│   ├── entity/                    # PostEntity、TagEntity、PostTagEntity
10│   ├── enums/
11│   └── advice/                    # GlobalExceptionAdvice、GlobalResultAdvice
12├── src/main/resources/
13│   ├── application.yml + application-local.yml
14│   ├── mapper/PostMapper.xml、TagMapper.xml
15│   └── db/ddl/                    # 现有表结构脚本
16├── src/test/java/com/example/blog/
17├── Dockerfile
18└── README.md

1请只读分析当前 personal-blog 仓库，不修改任何文件。
2
3输出一份 brownfield inventory，必须包含：
41. pom.xml 中的 Java 版本、Spring Boot/MyBatis-Plus 版本、构建插件、
5   profile 和测试开关（surefire 是否 skipTests）；
62. src/main/java 下的 controller、service、mapper、job 和核心模块；
73. entity 与 db/ddl 中与文章、标签、评论相关的表、字段、索引和关联关系；
84. 已有接口路径、请求/响应对象、ResultDTO 与 CodeEnum 错误处理方式；
95. application*.yml、Dockerfile 和外部服务依赖（数据库、xxl-job、Redis 等）；
106. 测试目录、测试框架、可运行命令和当前已知缺口；
117. README、CI、部署脚本中的约束；
128. 不能破坏的既有行为；
139. 需要开发者回答的不确定点。
14
15输出只写观察到的事实，未知内容标记 NEEDS CLARIFICATION，
16结尾列出本次试点预计修改的文件，仍不要编辑文件。

1## Runtime
2- Java 8，Maven 单模块 Spring Boot 2 工程，测试命令 `mvn test`。
3  注意：项目 pom 未显式关闭 skipTests，但公司父 POM 默认 true，
4  实际执行测试需 `mvn test -DskipTests=false`。
5- 生产由 Docker 部署，MySQL 单库；未发现独立搜索服务。
6
7## Existing behavior
8- `PostController` 提供 `POST /api/post/queryPage`，PageDTO 分页，
9  当前实现默认按 `create_time DESC` 返回 published 文章。
10- `TagMapper.selectUsedTags` 返回已使用标签。
11- 列表查询当前无 `tag` 过滤参数。
12- 未确认：无过滤时的默认页大小（代码里是 20，与 PageDTO 默认一致）、
13  不存在 tag 时的返回（推测是空列表，未见测试）。
14
15## Data model（来自 db/ddl 脚本与 entity 注解的交叉核对）
16- `t_post`：id、title、slug、status（0=draft、2=published）、
17  create_time、is_delete。
18- `t_tag`：id、name（列 collation 为 utf8mb4_general_ci，天然大小写不敏感）。
19- `t_post_tag`：post_id + tag_id 关联表，无额外字段。
20- 关联查询目前只用于详情页的标签回显。
21
22## Do-not-break
23- `GET /api/post/queryBySlug`（对外渲染为 /posts/{slug}）公开 URL 不变。
24- draft 不出现在公开列表。
25- 现有作者权限检查和评论审核流程不变。
26
27## Candidate files
28- `src/main/java/com/example/blog/request/PostQueryRequest.java`
29- `src/main/resources/mapper/PostMapper.xml`
30- `src/test/java/com/example/blog/PostListTest.java`
31- `README.md`

1docs/spec-kit/brownfield-inventory.md  # 人工修订后提交

1/speckit.constitution
2根据 docs/spec-kit/brownfield-inventory.md、README.md、CI 配置和现有测试，
3为 personal-blog 建立项目原则。只纳入有仓库证据或已获团队批准的规则：
4
5- 沿用现有 Java 8 / Spring Boot 2 / MyBatis-Plus / Maven 技术栈，不因单个 feature 换框架；
6- 公开文章接口和 slug URL 保持向后兼容，ResultDTO/CodeEnum 响应约定不变；
7- 数据库变更必须有向前 DDL、回滚脚本和备份/恢复步骤；
8- 新增行为先补自动化测试，保留现有测试命令（含 skipTests 开关约定）；
9- 认证、作者权限、评论审核规则不能被筛选功能绕过；
10- 日志不得包含 token、密码或文章私密内容；错误响应沿用现有 CodeEnum；
11- 每个 PR 说明影响文件、兼容性、测试结果和未完成项。
12
13输出 constitution 草案并列出需要人工确认的条款，不要修改业务代码。

1## Existing-Architecture First
2新功能 MUST 复用已存在的 controller/service/mapper 和测试模式；偏离必须记录理由。
3
4## API Compatibility
5现有公开字段、CodeEnum 错误码、slug URL 和权限行为 MUST 保持兼容，
6除非 feature spec 明确批准破坏性变化。
7
8## Migration Safety
9数据库变更 MUST 有向前/回滚脚本；生产操作 MUST 先备份并验证恢复路径。
10
11## Test and Observability
12新行为 MUST 有自动化测试；日志 MUST 不含凭据和私密正文。
13
14## Review Governance
15Planning artifacts 与实现 diff 一起评审；测试通过不等于产品验收或部署完成。

1.specify/memory/constitution.md
2docs/spec-kit/brownfield-inventory.md

1/speckit.specify
2在已有 personal-blog 中为公开文章列表增加标签筛选，先用它做文章搜索的低风险试点。
3
4用户目标：读者在文章列表页选择一个标签，只看到包含该标签且已 published 的文章。
5
6必须保留：
7- 对外公开 URL /posts/{slug} 与 GET /api/post/queryBySlug 行为；
8- draft 不可出现在公开列表；
9- 无 tag 参数时的排序和响应字段；
10- 作者权限和评论审核流程。
11
12范围：POST /api/post/queryPage 的请求体增加可选 tag 与分页参数（沿用现有
13PageDTO 约定：page 从 0 开始，count 默认 20、允许 1..50）；
14按 tag 精确匹配（大小写不敏感、去除首尾空格）；结果按现有 create_time DESC；
15响应沿用 PageDTO<PostVO> 结构。
16
17边界：tag 为空白等同于未传；不存在的 tag 返回 200 空列表；
18page 为负或 count 超出范围返回现有参数错误码（ResultDTO code，非 HTTP 4xx）；
19草稿和未公开文章必须过滤掉。
20
21性能：在本地样例数据 10,000 篇文章上，带 tag 的列表查询 P95 目标不超过 200ms；
22若现有数据库没有合适索引，记录为 Plan 风险，不在本 feature 引入搜索引擎。
23
24不做：全文搜索、模糊 tag、标签管理 UI、搜索建议、相关性排序、缓存和新数据库。
25请生成用户故事、SFR 编号、验收场景、成功标准、假设与 Out of Scope，
26不要决定实现代码结构。

1### User Story 1 - Filter published posts by tag (Priority: P1)
2**Independent Test**: 准备 3 篇 published、1 篇 draft 和 2 个 tag，
3请求体携带 tag=java、page=0、count=20，只返回匹配的 published 文章。
4
5**Acceptance Scenarios**:
61. Given tag=java 存在 2 篇 published，When 查询，Then 返回 success、total=2、按 create_time DESC。
72. Given tag 不存在，When 查询，Then 返回 success 和空 items，不创建新 tag。
83. Given tag="  Java  "，When 查询，Then 与 `java` 结果相同。
94. Given page=-1 或 count=51，When 查询，Then 返回现有参数错误码。
105. Given 某文章是 draft，即使拥有目标 tag，When 查询，Then 不返回该文章。
11
12### Requirements
13- SFR-001: `tag` 可选，空白 tag 按未传处理。
14- SFR-002: tag 精确匹配且大小写不敏感（依赖列 collation，Plan 中确认）。
15- SFR-003: 只返回 published 文章，保留默认排序与响应字段。
16- SFR-004: page 从 0 开始（PageDTO 约定），count 默认 20，范围 1..50。
17- SFR-005: 无效分页返回现有参数错误码（HTTP 200 + ResultDTO.code）。
18- SFR-006: 不存在 tag 返回空列表。
19- SFR-007: 在 10,000 篇本地样例上 P95 <= 200ms，测量方法写入 quickstart。
20- SFR-008: 不引入全文搜索、缓存或新数据库。

1/speckit.plan
2先阅读并引用以下文件的真实内容：
3docs/spec-kit/brownfield-inventory.md
4.specify/memory/constitution.md
5src/main/java/com/example/blog/controller/PostController.java
6src/main/java/com/example/blog/request/PostQueryRequest.java
7src/main/resources/mapper/PostMapper.xml
8src/main/resources/db/ddl/（文章与标签相关脚本）
9src/test/java/com/example/blog/PostListTest.java
10pom.xml
11
12在写 Plan 前先输出：现状、影响范围、不确定点、预计修改文件和不改文件。
13不要凭空假设项目使用的 ORM、分页约定、错误格式或缓存。
14
15方案必须：
161. 复用现有 PostMapper 查询与 t_post_tag 关联，不新建标签服务；
172. 保持无 tag 请求的 SQL、排序和响应兼容；
183. 说明分页换算（PageDTO 从 0 起，MyBatis-Plus 分页从 1 起）、
19   大小写（列 collation）、空结果、草稿过滤和参数错误码；
204. 说明是否需要索引（EXPLAIN 验证）及如何测量 P95；
215. 给出回滚方式和测试分层；
226. 不修改无关模块，不引入全文搜索、缓存或新数据库。
23
24在得到我对技术选择、影响文件和风险的确认前，不生成代码、不执行 DDL。

1## Current behavior
2- 无 tag 时复用 `PostMapper.selectPublishedPage`，排序 `create_time DESC`，
3  MyBatis-Plus 分页（入参 PageDTO 页码 +1 换算）。
4- t_post_tag 关联查询当前只用于详情页标签回显，列表查询未用到。
5
6## Proposed changes
7- `PostQueryRequest` 增加可选 tag 字段（@Size 上限 + 空白语义在 service 处理）。
8- `PostMapper.xml` 的列表查询增加 tag 关联与过滤（tag 非空时 join t_post_tag/t_tag）。
9- `PostServiceImpl` 做空白归一化与 collation 说明，分页沿用 PageDTO。
10- `PostListTest` 增加 SFR-001..007 场景。
11- `README.md` 补充接口查询示例。
12
13## Not changed
14- 评论模块、发布任务、queryBySlug 详情接口。
15
16## Risks
17- 列 collation 若为 _bin，大小写不敏感假设失效，需在目标库确认。
18- P95 目标需要基准数据，不用单元测试结果冒充。

1src/main/java/com/example/blog/request/PostQueryRequest.java
2src/main/java/com/example/blog/service/impl/PostServiceImpl.java
3src/main/resources/mapper/PostMapper.xml
4src/test/java/com/example/blog/PostListTest.java
5src/test/java/com/example/blog/TagFilterBench.java          # 基准与 P95 测量
6README.md

1- [ ] ST001 运行现有文章列表、权限和详情测试（-DskipTests=false），记录基线命令与结果
2- [ ] ST002 [P] 编写 SFR-001..006 的 tag、分页、空结果和 draft 过滤测试 src/test/java/com/example/blog/PostListTest.java
3- [ ] ST003 编写 SFR-007 的 10,000 篇基准数据 SQL 与 P95 测量脚本（EXPLAIN + 计时采样）
4- [ ] ST004 实现可选 tag 过滤查询 src/main/resources/mapper/PostMapper.xml
5- [ ] ST005 实现参数解析、空白归一化与分页换算 src/main/java/com/example/blog/service/impl/PostServiceImpl.java
6- [ ] ST006 运行 ST001 回归、P95 测量、完整测试
7- [ ] ST007 更新 specs/003-post-tag-filter/、brownfield inventory 与 README.md

1<select id="selectPublishedPageWithTag" resultType="com.example.blog.entity.PostEntity">
2    SELECT p.*
3    FROM `personal-blog`.`t_post` p
4    <if test="tag != null and tag != ''">
5        INNER JOIN `personal-blog`.`t_post_tag` pt ON pt.`post_id` = p.`id`
6        INNER JOIN `personal-blog`.`t_tag` t ON t.`id` = pt.`tag_id`
7        WHERE t.`name` = #{tag}
8    </if>
9    <if test="tag == null or tag == ''">
10        WHERE 1 = 1
11    </if>
12      AND p.`status` = 2
13      AND p.`is_delete` = 0
14    ORDER BY p.`create_time` DESC
15</select>

1Page<PostEntity> pageParam = new Page<>(pageDTO.getPage() + 1, pageDTO.getCount());
2String normalizedTag = StringUtils.trimToNull(request.getTag());

1/speckit.implement
2只执行标签筛选试点 ST001-ST007：先更新/创建 SFR-001..007 对应测试，确认失败，
3再修改 PostQueryRequest、PostServiceImpl 和 PostMapper.xml。保持无 tag 的现有
4响应和排序。不要改评论、发布任务、详情接口、数据库 schema 或引入依赖。
5每个阶段报告修改文件、测试命令、退出码和未完成项。

1mvn test -DskipTests=false -Dtest=PostListTest
2mvn test -DskipTests=false

1specs/003-post-tag-filter/spec.md
2specs/003-post-tag-filter/plan.md
3specs/003-post-tag-filter/tasks.md
4docs/spec-kit/brownfield-inventory.md       # 补充新入口和行为
5README.md                                   # 补充接口示例

1cd personal-blog
2openspec init --tools codex
3git status --short        # 只应新增 openspec/ 与工具命令目录

1personal-blog/
2├── .specify/                     # Spec Kit 基础设施
3├── specs/                        # Spec Kit feature 目录（002、003），保留为历史
4├── openspec/
5│   ├── specs/                    # 现行能力规格（当前为空）
6│   ├── changes/                  # 变更提案（当前为空）
7│   └── config.yaml
8└── ...                           # 工具命令目录（/opsx:* 说明文件）

1# Post Query Specification
2
3## Purpose
4公开文章列表查询能力：读者按标签过滤已发布文章，作者预览草稿。
5本规格描述系统当前行为，是后续变更提案的对照基准。
6
7## Requirements
8
9### Requirement: Published post list
10系统 SHALL 返回已发布（published）文章的分页列表，默认按创建时间倒序，
11未传过滤条件时行为与历史版本保持一致。
12
13#### Scenario: 默认列表
14- **GIVEN** 存在 published 与 draft 文章
15- **WHEN** 请求列表且不带过滤条件
16- **THEN** 仅返回 published 文章，按 create_time DESC 排列
17
18### Requirement: Filter by tag
19系统 SHALL 支持按单个标签精确过滤（大小写不敏感、忽略首尾空白），
20分页沿用统一 PageDTO 约定（页码从 0 起，count 默认 20、范围 1..50）。
21
22#### Scenario: 命中标签
23- **GIVEN** 标签 java 关联 2 篇 published 文章
24- **WHEN** 请求 tag=java
25- **THEN** 返回 total=2 的该标签文章
26
27#### Scenario: 标签不存在
28- **WHEN** 请求不存在的 tag
29- **THEN** 返回空列表，不创建新标签
30
31### Requirement: Pagination validation
32非法分页参数 SHALL 返回统一参数错误码（HTTP 200 + ResultDTO.code），
33不使用独立的状态码语义。

1openspec validate --specs
2git add openspec && git commit -m "20260911_personal-blog_seedPostQuerySpec"

1/opsx:propose add-multi-tag-filter
2在现有公开文章列表查询上增加多标签组合筛选（AND 语义）：
3读者可同时选最多 5 个标签，只返回同时具备全部所选标签的 published 文章。
4单标签请求行为必须与现状完全一致。分页与错误响应沿用现有 PageDTO、
5ResultDTO 约定。不引入搜索引擎、缓存或新表；不改变标签管理功能。

1openspec/changes/add-multi-tag-filter/
2├── proposal.md                    # 为什么改、改什么
3├── specs/post-query/spec.md       # 需求差异（delta）
4├── design.md                      # 技术方案（可选）
5└── tasks.md                       # 实施清单

1# Proposal: Add Multi-Tag Filter
2
3## Intent
4读者当前只能按单一标签过滤，技术类文章常需要"java + spring"这类交集
5视角；运营侧已多次收到同类反馈。
6
7## Scope
8### In scope
9- 查询请求的标签参数从单个扩展为最多 5 个的列表（AND 语义）
10- 单标签行为保持现状
11### Out of scope
12- OR 语义组合、标签管理、搜索建议、缓存
13
14## Approach
15沿用现有列表查询链路，在 mapper 层按标签集合做交集过滤；
16不引入新表与新依赖，索引影响在 design.md 评估。

1# Delta for Post Query
2
3## ADDED Requirements
4
5### Requirement: Filter by multiple tags
6系统 SHALL 支持按 2..5 个标签的组合过滤（AND 语义）：仅返回同时具备
7全部所选标签的 published 文章；标签项忽略首尾空白，空白项视为未传。
8
9#### Scenario: 组合过滤命中
10- **GIVEN** 文章 A 含标签 java、spring，文章 B 仅含 java
11- **WHEN** 请求 tags=[java, spring]
12- **THEN** 仅返回文章 A
13
14#### Scenario: 超过上限
15- **WHEN** 请求 tags 含 6 个有效标签
16- **THEN** 返回现有参数错误码，列表不变
17
18## MODIFIED Requirements
19
20### Requirement: Filter by tag
21系统 SHALL 支持按标签过滤：请求携带 1 个标签时行为与现有单标签过滤
22完全一致（精确匹配、大小写不敏感、忽略首尾空白）；请求未携带标签时
23不过滤。分页沿用统一 PageDTO 约定（页码从 0 起，count 默认 20、范围
241..50）。
25(Previously: 仅描述单个标签的精确过滤。)
26
27#### Scenario: 命中标签
28- **GIVEN** 标签 java 关联 2 篇 published 文章
29- **WHEN** 请求 tags=[java]
30- **THEN** 返回 total=2 的该标签文章

1# Tasks
2
3## 1. 测试先行
4- [ ] 1.1 编写 MFR-001 组合命中/未命中场景测试 PostListTest.java
5- [ ] 1.2 编写 MFR-002 单标签回归与 MFR-003 上限/空白测试 PostListTest.java
6
7## 2. 查询实现
8- [ ] 2.1 PostQueryRequest 增加 tags 字段与校验，service 归一化
9- [ ] 2.2 PostMapper.xml 增加交集子查询，保持无标签路径 SQL 不变
10
11## 3. 验证与收尾
12- [ ] 3.1 运行 PostListTest 与全量回归（-DskipTests=false）
13- [ ] 3.2 基准数据上测量 3 标签组合 P95（MFR-004）

1openspec validate add-multi-tag-filter --strict
2openspec status
3openspec show add-multi-tag-filter --deltas-only

1/opsx:apply
2执行 add-multi-tag-filter 的 tasks。先跑 1.x 测试确认失败，再实现 2.x；
3无标签与单标签请求的 SQL 路径必须保持不变；完成一项勾选一项。
43.1 之前报告测试命令与退出码，3.2 的 P95 用基准数据实测，不拿单测耗时冒充。

1<if test="tags != null and tags.size() > 0">
2    INNER JOIN (
3        SELECT pt.`post_id`
4        FROM `personal-blog`.`t_post_tag` pt
5        INNER JOIN `personal-blog`.`t_tag` t ON t.`id` = pt.`tag_id`
6        WHERE t.`name` IN
7        <foreach collection="tags" item="tag" open="(" separator="," close=")">#{tag}</foreach>
8        GROUP BY pt.`post_id`
9        HAVING COUNT(DISTINCT t.`id`) = #{tags.size()}
10    ) matched ON matched.`post_id` = p.`id`
11</if>

1openspec archive add-multi-tag-filter --yes

1openspec/
2├── specs/post-query/spec.md          # Filter by tag 已被替换为新正文；
3│                                     # Filter by multiple tags 已追加
4└── changes/archive/
5    └── 2026-09-12-add-multi-tag-filter/   # proposal/design/tasks/delta 完整保留

1openspec list --specs                 # 现行能力列表
2openspec validate --archived          # 校验归档项 tasks 全部勾选，适合放进 CI
3git add openspec && git commit -m "20260912_personal-blog_multiTagFilter"