Spec Kit 实战 03 · 图书管理系统实战：从需求到实现

1library-system/
2├── .specify/
3│   └── memory/constitution.md
4└── .agents/skills/

1library-system/
2└── docs/requirements/
3    ├── library-mvp-brief.md    # 需求简报：一页纸的产品判断
4    └── backlog.md              # Backlog：暂不做的事项登记

1# 图书管理 MVP 需求简报
2
3## 背景
4内部图书角目前靠一张共享表格登记借还：谁借了哪本、是否逾期，
5全靠人翻表格核对。本期做一个最小的管理系统替代它。
6
7## 本期目标
81. 管理员能录入和编辑图书（书名、作者、ISBN、库存）。
92. 管理员能按书名、作者或 ISBN 查书，看到库存。
103. 管理员能办理借书和还书，借期 14 天。
114. 会员能查看自己的借阅和逾期状态。
12
13## 角色
14- LIBRARIAN（图书管理员）：维护书目、办理借还、查逾期。
15- MEMBER（普通会员）：查书、看本人借阅。
16- 身份由应用上下文提供；登录、注册本期不做。
17
18## 明确不做
19细粒度权限、预约、罚款、采购、多分馆、通知。
20
21## 未知项（先记下，留给 Clarify 回答）
22- 库存按书目聚合还是按实体副本管理？
23- ISBN 采用什么校验规则？
24- 编辑总库存时，当前借出数怎么约束？
25- 逾期边界：到期当天算不算逾期？

1# Backlog
2
3| 想法 | 来源 | 状态 |
4|---|---|---|
5| 预约已借出的图书 | 产品提议 | 未排期 |
6| 逾期罚款 | 产品提议 | 未排期 |
7| 实体副本条码管理 | 工程提议 | 未排期 |
8| 到期提醒通知 | 产品提议 | 未排期 |
9| 登录与角色配置 | 架构决定 | 另立 feature |
10
11以上均未进入 001-library-circulation。将来启动时每项单独立项，
12不回头扩本期范围。

1/speckit.constitution
2为图书管理系统制定项目原则：
31. 借书、还书和库存更新必须在单个数据库事务中完成；任何路径都不得让
4   available_copies 小于 0 或大于 total_copies。
52. 业务规则必须有自动化测试，至少覆盖正常借还、无库存、重复借阅、
6   重复归还和最后一本的并发竞争。
73. API 错误必须返回稳定、机器可读的错误码，不暴露内部堆栈和 SQL。
84. 优先使用 JDK、Spring Boot 与父 POM 已管理的依赖；新增依赖必须在
9   plan.md 记录理由与替代方案。
105. 每个 feature 必须提供可重复执行的 quickstart、DDL 脚本与回滚说明。
116. 规格、计划、任务和实现必须一起评审；AI 生成内容不得自行批准。

1# Library System Constitution
2
3## I. Transactional Circulation
4借书、还书与库存更新 MUST 在一个事务中完成（rollbackFor = Exception.class）。
5数据库与条件更新 MUST 共同保证：0 <= available_copies <= total_copies。
6
7## II. Testable Business Rules
8每条借还规则 MUST 有可执行测试；并发测试不得用两个顺序请求冒充。
9
10## III. Stable External Errors
11冲突 MUST 映射为 CodeEnum 稳定错误码；内部异常、SQL 和堆栈不得进入响应。
12
13## IV. Minimal Dependencies
14新增依赖 MUST 在 plan.md 记录 Decision、Rationale、Alternatives。
15
16## Governance
17Constitution 高于 feature plan。修改需人工评审、版本说明和迁移影响。

1docs/requirements/library-mvp-brief.md   # 团队起草，已提交
2docs/requirements/backlog.md             # 已提交，含五项未排期想法
3.specify/memory/constitution.md          # 已由团队审查

1.specify/memory/constitution.md  # 已批准
2specs/                           # 尚无本 feature

1/speckit.specify
2根据 docs/requirements/library-mvp-brief.md 创建图书管理 MVP 的规格。
3
4角色：LIBRARIAN 和 MEMBER。身份由应用上下文提供，本期不实现登录、注册和角色配置。
5
6P1：LIBRARIAN 可以录入和编辑图书。ISBN、书名、作者必填；ISBN 唯一；
7库存为非负整数；总库存不能改到小于当前借出数。
8P1：LIBRARIAN 和 MEMBER 都可以按书名、作者或完整/部分 ISBN 查询图书，
9并看到总库存与可借数量。
10P1：LIBRARIAN 为有效会员办理借书和归还。借期是 borrowed_at 后 14 天；
11最后一本的并发借阅只允许一个成功；同一会员不能同时借同一书目两次；
12重复归还不能再次增加库存。
13P1：MEMBER 可以查看自己的借阅及 ACTIVE、OVERDUE、RETURNED 状态，不能查看他人记录。
14P2：LIBRARIAN 可以查看指定时刻所有逾期且未归还的借阅。
15
16成功标准：P1 的图书维护、查询、角色边界和借还场景有自动化测试；
17两个请求竞争最后一本时只允许一个成功；新开发者能按 quickstart
18在 10 分钟内完成录书、查询、借书、查看状态和归还。
19
20不做细粒度权限配置、实体副本条码、预约、罚款、采购、多分馆和通知。
21请只描述用户目标、业务规则、边界和可测结果，不选择技术栈。

1specs/001-library-circulation/
2├── spec.md
3└── checklists/requirements.md

1# Feature Specification: Library Circulation MVP
2
3## User Story 1 - Maintain catalog (Priority: P1)
4LIBRARIAN 录入和编辑图书。
5
6**Acceptance Scenarios**:
71. Given 合法 ISBN、非空书名/作者、total_copies=3，When 录入，Then 返回新图书且 available_copies=3。
82. Given ISBN 已存在，When 再次录入，Then 返回 ISBN_ALREADY_EXISTS。
93. Given 当前借出 2 本，When 把 total_copies 改为 1，Then 返回 TOTAL_BELOW_BORROWED，库存不变。
104. Given MEMBER 身份，When 录入或编辑图书，Then 返回 FORBIDDEN。
11
12## User Story 2 - Search books (Priority: P1)
13LIBRARIAN 和 MEMBER 按书名、作者或 ISBN 查询，并看到总库存和可借数。
14
15**Independent Test**: 录入三本图书，按部分书名和部分 ISBN 查询；无匹配时返回空列表。
16
17## User Story 3 - Borrow and return (Priority: P1)
181. Given 有库存且会员无相同 active loan，When LIBRARIAN 办理借书，
19   Then due_at=borrowed_at+14 days、available_copies 减 1。
202. Given available_copies=0，When 借书，Then 返回 BOOK_UNAVAILABLE。
213. Given 相同 active loan，When 再借，Then 返回 ACTIVE_LOAN_EXISTS。
224. Given 借阅未归还，When 归还，Then returned_at 被记录且库存加 1。
235. Given 借阅已归还，When 再次归还，Then 返回 LOAN_ALREADY_RETURNED 且库存不变。
24
25## User Story 4 - View loan status (Priority: P1)
26MEMBER 只能查看自己的借阅。as_of 时刻下：returned_at 非空为 RETURNED；
27未归还且 due_at < as_of 为 OVERDUE；其余为 ACTIVE。
28
29## User Story 5 - View all overdue loans (Priority: P2)
30LIBRARIAN 查看指定时刻全部 OVERDUE 借阅；MEMBER 请求该列表返回 FORBIDDEN。
31
32## Functional Requirements
33- FR-001: LIBRARIAN 可录入合法图书，ISBN、书名、作者必填，ISBN 唯一。
34- FR-002: LIBRARIAN 可编辑书名、作者和库存，总库存不得小于当前借出数。
35- FR-003: LIBRARIAN 和 MEMBER 可按书名、作者或 ISBN 搜索并看到库存。
36- FR-004: LIBRARIAN 可为有效会员创建借期 14 天的借阅。
37- FR-005: 借书与库存扣减原子完成，最后一本并发竞争恰好一个成功。
38- FR-006: 同一会员、同一书目最多一条 active loan。
39- FR-007: 归还只成功一次并原子增加库存。
40- FR-008: 系统按 as_of 派生 ACTIVE、OVERDUE、RETURNED 状态。
41- FR-009: MEMBER 只能查看本人借阅，LIBRARIAN 可查看全部逾期。
42- FR-010: 只有 LIBRARIAN 可维护图书和办理借还。
43- FR-011: 校验失败和冲突返回稳定错误码，不暴露内部异常。
44- FR-012: 身份由受信任应用上下文提供，本期不实现登录、注册和角色配置。
45
46## Success Criteria
47- SC-001: P1 的图书维护、查询、角色边界、借书和还书场景都有自动化测试。
48- SC-002: 两个请求竞争最后一本时恰好一个成功，库存不为负。
49- SC-003: 新开发者按 quickstart 可在 10 分钟内完成录书、查询、借书、查看状态和归还。
50
51## Out of Scope
52登录、注册、细粒度权限配置、实体副本条码、预约、罚款、采购、多分馆、通知。

1specs/001-library-circulation/spec.md
2specs/001-library-circulation/checklists/requirements.md
3.specify/feature.json              # 指向当前 feature，通常机器本地状态

1/speckit.clarify
2重点检查库存模型、ISBN 与字段校验、LIBRARIAN/MEMBER 的身份来源和权限、
3总库存编辑、14 天的时间语义、同书重复借阅、最后一本并发竞争、
4重复归还和借阅状态边界。只问会改变需求、接口或数据模型的问题。

1### Clarifications
2- 2026-09-09: MVP 按书目聚合库存，不跟踪实体副本。
3- 2026-09-09: ISBN 去连字符后校验 ISBN-10/13；书名和作者长度为 1..200。
4- 2026-09-09: 身份由受信任应用上下文提供；本期不实现认证。
5- 2026-09-09: total_copies 不得小于 total_copies - available_copies。
6- 2026-09-09: 同一会员和书目最多一条 active loan。
7- 2026-09-09: 时间存库统一 UTC 口径，due_at = borrowed_at + 14 days。
8- 2026-09-09: returned_at 非空为 RETURNED；否则 due_at < as_of 为 OVERDUE，其余 ACTIVE。
9
10### Assumptions
11- 在线账号由应用上下文提供；角色只有 LIBRARIAN 和 MEMBER。
12- 借书只验证目标会员存在，不检查欠费或逾期资格。

1spec.md            # what/why 已澄清
2constitution.md    # 项目 gate 已批准

1## 已确定
2- Java 8、Spring Boot 2、MyBatis-Plus 3.4、MySQL；沿用公司父 POM 管理依赖。
3- Maven 多模块：library-api（对外契约）、library-service（业务核心）、library-web（HTTP 入口）。
4- 身份由应用上下文提供在线账号，不实现认证。
5- 接口沿用本章固定契约（api/book、api/loan 动词式端点）。
6- 不引入缓存、消息队列、微服务拆分或额外的 repository 包装层（Mapper 已承担该职责）。
7
8## 待调研
9- MySQL 5.x 不执行列级 CHECK 约束，库存不变量由条件 UPDATE 与服务层校验共同保证。
10- MySQL 没有 partial unique index，"同一会员同一书目仅一条 active loan"需要等价实现。
11- ISBN-10/13 校验没有现成注解，决定自写最小校验还是引入工具库。
12
13## 交付和验证
14- 接口、DDL 脚本（向前/回滚）、自动化测试、quickstart、需求追溯表。
15- 当前开发完成不等于已部署。

1/speckit.plan
2使用 Java 8、Spring Boot 2、MyBatis-Plus 3.4、MySQL，Maven 多模块
3（library-api / library-service / library-web），统一工程风格：
4ResultDTO 统一响应、CodeEnum 七位错误码、Request/DTO/VO/Entity 四层模型、
5校验分组、knife4j 接口文档。research.md 必须记录 MySQL 5.x 的约束差异
6与并发条件更新的验证边界。
7
8接口契约（POST + 请求体，分页用 PageDTO，页码从 0 开始）：
9- POST /api/book/create
10- POST /api/book/updateById
11- POST /api/book/queryPage
12- POST /api/loan/create
13- POST /api/loan/returnById
14- POST /api/loan/queryMemberPage
15- POST /api/loan/queryOverduePage
16
17身份由应用上下文提供在线账号（id、角色）；LIBRARIAN 才能维护图书和办理借还，
18MEMBER 只能查询图书和本人借阅。ISBN、文本长度、库存和角色错误都要有稳定错误码
19（CodeEnum，业务错误 HTTP 状态码统一 200，靠 code 区分）。
20借书使用带 available_copies > 0 条件的原子 UPDATE，并在同一事务插入 Loan；
21"同一 member_id/book_id 仅一条 active loan"用冗余 active_flag 列 + 唯一索引
22（MySQL 无 partial unique index 的等价方案，归还时置 NULL）兜底并发。
23归还只允许从 active 状态原子迁移一次。所有时间按 UTC 口径，状态按 as_of 派生。
24
25测试使用 JUnit + spring-boot-starter-test（MockMvc）；父 POM 默认 skipTests=true，
26测试命令必须显式 -DskipTests=false；并发测试必须真实并发，不能用顺序请求代替。
27输出 research.md、data-model.md、contracts/openapi.yaml、quickstart.md、
28向前/回滚 DDL 方案、真实项目目录与 Constitution Check。

1specs/001-library-circulation/
2├── spec.md
3├── plan.md
4├── research.md
5├── data-model.md
6├── contracts/openapi.yaml
7├── quickstart.md
8└── checklists/requirements.md

1## Technical Context
2- Runtime: Java 8（maven.compiler.source/target 1.8）
3- Framework: Spring Boot 2（继承公司父 POM）
4- Persistence: MyBatis-Plus 3.4 + MySQL（Druid 连接池）
5- Test: JUnit + spring-boot-starter-test（MockMvc；父 POM 默认 skipTests，命令需 -DskipTests=false）
6- Docs: knife4j（Swagger 2 注解）
7
8## Constitution Check
9- Transactional Circulation: PASS，借还各使用单事务和条件更新。
10- Testable Business Rules: PASS，FR-001..FR-012 映射到 integration tests。
11- Stable External Errors: PASS，业务错误统一 ResultDTO + CodeEnum，HTTP 200。
12- Minimal Dependencies: PASS，未引入队列、缓存或额外 repository 抽象。
13
14## Project Structure
15library-system/                          # Maven 父工程（packaging=pom）
16├── library-api/                         # 对外契约：ResultDTO/PageDTO/CodeEnum
17├── library-service/
18│   └── src/main/java/com/example/library/
19│       ├── entity/                      # BookEntity、LoanEntity（继承 BaseEntity）
20│       ├── mapper/                      # BookMapper、LoanMapper（含 XML）
21│       ├── dto/                         # BookDTO、LoanDTO、LoanCreateDTO 等
22│       ├── enums/                       # RoleEnum、LoanStatusEnum（派生状态）
23│       └── service/                     # BookService、LoanService + impl/
24├── library-web/
25│   └── src/main/java/com/example/library/
26│       ├── controller/                  # BookController、LoanController
27│       ├── request/                     # BookSaveRequest（校验分组）、LoanCreateRequest 等
28│       ├── request/validator/group/     # BookCreateValidationGroup 等
29│       ├── vo/                          # BookVO、LoanVO
30│       └── advice/                      # GlobalExceptionAdvice、GlobalResultAdvice
31├── library-web/src/main/resources/
32│   ├── application.yml + application-local.yml
33│   └── mapper/book/BookMapper.xml、mapper/loan/LoanMapper.xml
34├── docs/ddl/V001__library_schema.sql    # 向前 DDL
35├── docs/ddl/U001__library_schema_rollback.sql
36└── library-web/src/test/java/com/example/library/
37    ├── BookCatalogTest.java
38    ├── BookSearchTest.java
39    ├── RoleBoundaryTest.java
40    ├── CirculationTest.java
41    └── OverdueTest.java

1在线账号（User）
2- 不落库。由应用上下文提供 id（Long）与角色（RoleEnum: LIBRARIAN | MEMBER），
3  controller 层取值后显式传给 service。
4
5book
6- id: BIGINT, PK, AUTO_INCREMENT
7- isbn: VARCHAR(20), required, unique（uk_isbn）
8- title: VARCHAR(200), required
9- author: VARCHAR(200), required
10- total_copies: INT UNSIGNED, required
11- available_copies: INT UNSIGNED, required
12- create_time / update_time / is_delete（逻辑删除，沿用 BaseEntity）
13
14loan
15- id: BIGINT, PK, AUTO_INCREMENT
16- book_id: BIGINT, required
17- member_id: BIGINT, required（在线账号 ID）
18- member_name: VARCHAR(64)（回显用）
19- borrowed_at: DATETIME, required（UTC 口径）
20- due_at: DATETIME, required
21- returned_at: DATETIME, nullable
22- active_flag: TINYINT, nullable——在借时为 1，归还后置 NULL
23- create_time / update_time / is_delete
24
25Invariant: 同一 member_id + book_id 最多一条 active 记录。
26MySQL 无 partial unique index，等价实现为唯一索引
27uk_member_book_active(member_id, book_id, active_flag)——NULL 在唯一索引中可重复。
28Derived status(as_of): returned_at != NULL -> RETURNED; due_at < as_of -> OVERDUE; otherwise ACTIVE。

1CREATE TABLE `book` (
2    `id`               BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
3    `isbn`             VARCHAR(20)     NOT NULL,
4    `title`            VARCHAR(200)    NOT NULL,
5    `author`           VARCHAR(200)    NOT NULL,
6    `total_copies`     INT UNSIGNED    NOT NULL,
7    `available_copies` INT UNSIGNED    NOT NULL,
8    `create_time`      DATETIME        NOT NULL DEFAULT CURRENT_TIMESTAMP,
9    `update_time`      DATETIME        NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
10    `is_delete`        TINYINT         NOT NULL DEFAULT 0,
11    PRIMARY KEY (`id`),
12    UNIQUE KEY `uk_isbn` (`isbn`)
13) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4;
14
15CREATE TABLE `loan` (
16    `id`          BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
17    `book_id`     BIGINT UNSIGNED NOT NULL,
18    `member_id`   BIGINT UNSIGNED NOT NULL,
19    `member_name` VARCHAR(64)     DEFAULT NULL,
20    `borrowed_at` DATETIME        NOT NULL,
21    `due_at`      DATETIME        NOT NULL,
22    `returned_at` DATETIME        DEFAULT NULL,
23    `active_flag` TINYINT         DEFAULT NULL COMMENT '在借=1，归还后置 NULL',
24    -- create_time / update_time / is_delete 同 book 表
25    PRIMARY KEY (`id`),
26    UNIQUE KEY `uk_member_book_active` (`member_id`, `book_id`, `active_flag`),
27    KEY `idx_member_borrowed` (`member_id`, `borrowed_at`)
28) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4;

1paths:
2  /api/book/create:
3    post:
4      responses:
5        "200":
6          description: 录入成功或返回参数/权限/重复错误码
7  /api/book/updateById:
8    post:
9      responses:
10        "200":
11          description: 编辑成功或 TOTAL_BELOW_BORROWED 等错误码
12  /api/book/queryPage:
13    post:
14      description: 关键词匹配书名/作者/ISBN，PageDTO 分页（页码从 0 开始）
15  /api/loan/create:
16    post:
17      responses:
18        "200":
19          description: 借阅成功或 BOOK_UNAVAILABLE / ACTIVE_LOAN_EXISTS
20  /api/loan/returnById:
21    post:
22      responses:
23        "200":
24          description: 归还成功或 LOAN_ALREADY_RETURNED
25  /api/loan/queryMemberPage:
26    post:
27      description: 会员本人借阅列表（含按 as_of 派生状态）
28  /api/loan/queryOverduePage:
29    post:
30      description: 指定时刻全部逾期借阅（仅 LIBRARIAN）

1{
2  "code": 3010400,
3  "message": "图书无可借库存",
4  "success": false,
5  "model": null
6}

1## Decision: 条件 UPDATE 扣减库存
2Rationale: 单条 SQL（UPDATE book SET available_copies = available_copies - 1
3WHERE id = ? AND available_copies > 0）将可借条件与扣减绑定，行锁天然串行化
4最后一本竞争；返回影响行数 0 即视为 BOOK_UNAVAILABLE。
5Alternatives: 悲观锁 SELECT ... FOR UPDATE；应用层全局锁。
6MySQL 行为需在目标版本实测（本地与生产隔离级别差异写入测试边界）。
7
8## Decision: active_flag 冗余列 + 唯一索引阻止重复在借
9Rationale: MySQL 无 partial unique index；active_flag 在借为 1、归还置 NULL，
10uk_member_book_active 利用唯一索引忽略 NULL 的语义实现"仅一条 active"，
11并发下靠 DuplicateKeyException 兜底并翻译为业务错误码。
12Alternatives: 归还后删除记录（丢失历史）；应用层串行检查（无法兜住并发）。
13
14## Decision: 不引入任务队列和缓存
15Rationale: 当前需求是同步借还和查询；新增基础设施没有明确收益。
16Alternatives: Redis 队列；事件驱动库存。达到跨服务吞吐需求时再评估。

1mvn clean install -DskipTests=false          # 父 POM 默认 skipTests=true，必须显式打开
2mysql -u root -e "CREATE DATABASE IF NOT EXISTS library DEFAULT CHARACTER SET utf8mb4;"
3mysql -u root library < docs/ddl/V001__library_schema.sql
4mysql -u root library < docs/ddl/seed_demo.sql
5mvn --projects library-web spring-boot:run -Dspring-boot.run.profiles=local
6mvn --projects library-web test -DskipTests=false

1/speckit.checklist
2重点检查 FR-001..FR-012 的字段校验、角色边界、事务、库存不变量、重复操作、并发竞争、
3UTC 时间语义、稳定错误码，以及 SC-001..SC-003 是否可验证。

1- [ ] 是否定义了同一会员重复 active loan 的结果？
2- [ ] 是否定义了最后一本并发竞争的唯一结果？
3- [ ] 是否明确 due_at == as_of 不算逾期？
4- [ ] 是否说明重复归还不得增加库存？
5- [ ] 是否为每种冲突定义稳定错误码？
6- [ ] 是否说明 SC-003 的计时起点和环境？

1/speckit.tasks

1## Phase 1: Setup
2- [ ] T001 创建父 pom 与 library-api/library-service/library-web 模块骨架，继承公司父 POM，锁定 Spring Boot 2、MyBatis-Plus 3.4
3- [ ] T002 [P] 建立 service 模块包结构（entity/mapper/dto/enums/service）与 web 模块包结构（controller/request/vo/advice）及测试目录
4
5## Phase 2: Foundational
6- [ ] T003 定义 BookEntity/LoanEntity（继承 BaseEntity，含 active_flag）、RoleEnum/LoanStatusEnum 及全部字段约束 library-service/src/main/java/com/example/library/entity
7- [ ] T004 创建向前 DDL docs/ddl/V001__library_schema.sql 与回滚 docs/ddl/U001__library_schema_rollback.sql（含 uk_member_book_active）
8- [ ] T005 [P] 新增 CodeEnum 图书模块错误码（七位编码）与 GlobalExceptionAdvice/GlobalResultAdvice library-api、library-web/.../advice
9
10## Phase 3: US1 Maintain catalog (P1)
11- [ ] T006 [P] [US1] 编写 FR-001/FR-002/FR-010/FR-011 录入、编辑、非法 ISBN、库存下限和越权测试 library-web/src/test/java/com/example/library/BookCatalogTest.java
12- [ ] T007 [US1] 实现 BookSaveRequest（校验分组）、BookController 的 /api/book/create 与 /api/book/updateById 及 BookService 实现 library-web/.../controller、library-service/.../service/impl
13
14## Phase 4: US2 Search books (P1)
15- [ ] T008 [P] [US2] 编写 FR-003 搜索、空结果、角色可见性测试 library-web/src/test/java/com/example/library/BookSearchTest.java
16- [ ] T009 [US2] 实现 BookQueryRequest 与 /api/book/queryPage（PageDTO 分页，页码从 0 开始） library-web/.../request、library-web/.../controller
17
18## Phase 5: US3 Borrow and return (P1)
19- [ ] T010 [P] [US3] 编写 FR-004/FR-005/FR-006 借书测试 library-web/src/test/java/com/example/library/CirculationTest.java
20- [ ] T011 [US3] 编写 SC-002 真实并发测试（两个线程经 CountDownLatch 同时调用借书） library-web/src/test/java/com/example/library/CirculationTest.java
21- [ ] T012 [US3] 实现条件库存扣减 UPDATE 与借阅事务 BookMapper.xml、library-service/.../service/impl/LoanServiceImpl.java
22- [ ] T013 [US3] 实现 LoanCreateRequest 与 /api/loan/create library-web/.../controller
23- [ ] T014 [US3] 编写 FR-007 重复归还测试 library-web/src/test/java/com/example/library/CirculationTest.java
24- [ ] T015 [US3] 实现归还服务（条件迁移 returned_at/active_flag）与 /api/loan/returnById，修改 library-service/.../service/impl/LoanServiceImpl.java 和 library-web/.../controller/LoanController.java
25
26## Phase 6: US4 View loan status (P1)
27- [ ] T016 [P] [US4] 编写 FR-008/FR-009 状态边界和 MEMBER 隔离测试 library-web/src/test/java/com/example/library/RoleBoundaryTest.java
28- [ ] T017 [US4] 实现 /api/loan/queryMemberPage（as_of 派生状态） library-web/.../controller、library-service/.../service/impl
29
30## Phase 7: US5 Overdue loans (P2)
31- [ ] T018 [P] [US5] 编写 FR-008/FR-009 due_at < as_of 和角色测试 library-web/src/test/java/com/example/library/OverdueTest.java
32- [ ] T019 [US5] 实现 /api/loan/queryOverduePage library-web/.../controller、LoanMapper.xml
33
34## Final Phase: Polish
35- [ ] T020 运行完整测试（-DskipTests=false）、DDL 升级/回滚及契约检查（knife4j 导出与 contracts/openapi.yaml 比对）
36- [ ] T021 在干净环境执行 quickstart，记录 SC-003 结果

1/speckit.analyze

1HIGH: FR-006 要求数据库层阻止重复 active loan，T004 只写"唯一索引"，
2      未说明 active_flag 置 NULL 的归还路径与该索引的配合方式。
3MEDIUM: T010 与 T011 都修改 CirculationTest.java，不能同时并行。
4MEDIUM: SC-003 要求 10 分钟内完成，但 quickstart 未定义计时起点。

1/speckit.implement
2只执行 Phase 1 和 Phase 2（T001-T005）。运行 DDL 脚本、实体/错误码相关测试；
3报告修改文件、命令、退出码和未完成项。遇到未决业务规则时停止，
4不要实现接口或加入 out-of-scope 功能。

1/speckit.implement
2执行 Phase 3 至 Phase 5（T006-T015）。先运行对应测试观察失败，再实现；
3每完成 US1、US2 或 US3 就运行该故事的测试（记得 -DskipTests=false）。
4T011 必须使用两个真实并发线程（ExecutorService + CountDownLatch 同时进入
5service 事务），不能用两个顺序请求冒充。不要实现 US4/US5。

1@Service
2@Slf4j
3public class LoanServiceImpl implements LoanService {
4
5    @Resource
6    private BookMapper bookMapper;
7
8    @Resource
9    private LoanMapper loanMapper;
10
11    @Override
12    @Transactional(rollbackFor = Exception.class)
13    public Long createLoan(LoanCreateDTO createDTO) {
14        // 应用层先挡一道明显的重复在借；并发漏网的交给唯一索引兜底
15        Long activeCount = loanMapper.selectCount(
16                new LambdaQueryWrapper<LoanEntity>()
17                        .eq(LoanEntity::getMemberId, createDTO.getMemberId())
18                        .eq(LoanEntity::getBookId, createDTO.getBookId())
19                        .isNull(LoanEntity::getReturnedAt));
20        if (activeCount > 0) {
21            throw new FailedException(CodeEnum.LIBRARY_USER_ERROR_0401.getCode());
22        }
23
24        // 条件更新把“可借”与“扣减”绑在同一条 SQL 上，最后一本竞争由行锁串行化
25        int deducted = bookMapper.deductAvailableCopy(createDTO.getBookId());
26        if (deducted != 1) {
27            throw new FailedException(CodeEnum.LIBRARY_USER_ERROR_0400.getCode());
28        }
29
30        Date borrowedAt = new Date();
31        LoanEntity loan = LoanEntity.builder()
32                .bookId(createDTO.getBookId())
33                .memberId(createDTO.getMemberId())
34                .memberName(createDTO.getMemberName())
35                .borrowedAt(borrowedAt)
36                .dueAt(DateUtil.offsetDay(borrowedAt, LoanConstants.LOAN_PERIOD_DAYS))
37                .activeFlag(LoanConstants.ACTIVE_FLAG_ON)
38                .build();
39        try {
40            loanMapper.insert(loan);
41        } catch (DuplicateKeyException ex) {
42            // uk_member_book_active 冲突说明并发下已产生在借记录，翻译为业务错误码
43            log.warn("[LoanServiceImpl.createLoan] 并发重复借阅冲突（uk_member_book_active），"
44                            + "会员ID: [{}]，图书ID: [{}]",
45                    createDTO.getMemberId(), createDTO.getBookId());
46            throw new FailedException(CodeEnum.LIBRARY_USER_ERROR_0401.getCode());
47        }
48        return loan.getId();
49    }
50}

1<update id="deductAvailableCopy">
2    UPDATE `library`.`book`
3    SET `available_copies` = `available_copies` - 1
4    WHERE `id` = #{bookId}
5      AND `available_copies` &gt; 0
6      AND `is_delete` = 0
7</update>

1@Data
2@Builder
3@NoArgsConstructor
4@AllArgsConstructor
5@ApiModel(value = "图书新增/编辑请求", description = "图书新增/编辑请求")
6public class BookSaveRequest implements Serializable {
7
8    private static final long serialVersionUID = 1L;
9
10    @Null(message = "新增时不能传图书 ID", groups = BookCreateValidationGroup.class)
11    @NotNull(message = "图书 ID 不能为空", groups = BookUpdateValidationGroup.class)
12    @Positive(message = "图书 ID 必须为正数", groups = BookUpdateValidationGroup.class)
13    @ApiModelProperty(value = "图书 ID（编辑时必传，新增禁止传）")
14    private Long id;
15
16    @NotBlank(message = "ISBN 不能为空")
17    @ApiModelProperty(value = "ISBN（ISBN-10 或 ISBN-13，允许连字符）", required = true)
18    private String isbn;
19
20    @NotBlank(message = "书名不能为空")
21    @Size(max = 200, message = "书名长度不能超过 200")
22    @ApiModelProperty(value = "书名", required = true)
23    private String title;
24
25    @NotNull(message = "总库存不能为空")
26    @PositiveOrZero(message = "总库存必须为非负整数")
27    @ApiModelProperty(value = "总库存（非负整数）", required = true)
28    private Integer totalCopies;
29
30    public BookSaveDTO toSaveDTO() {
31        return BookSaveDTO.builder()
32                .id(this.id)
33                .isbn(this.isbn)
34                .title(this.title)
35                .totalCopies(this.totalCopies)
36                .build();
37    }
38}

1private void validateIsbnOrThrow(String isbn) {
2    String normalized = StringUtils.deleteWhitespace(isbn.replace("-", ""));
3    if (!IsbnValidator.isIsbn10Or13(normalized)) {
4        throw new FailedException(CodeEnum.LIBRARY_USER_ERROR_0101.getCode());
5    }
6}

1/speckit.implement
2执行 Phase 6、Phase 7 和 Final Phase（T016-T021）。实现借阅状态与逾期查询；
3运行完整测试（-DskipTests=false）、DDL 升级/回滚、契约检查（knife4j 导出比对
4contracts/openapi.yaml）；在干净环境按 quickstart 计时。不要把测试通过描述为已部署。

1specs/001-library-circulation/implementation-report.md

1## Scope
2实现 T001-T021，未实现 Out of Scope。
3
4## Traceability
5| Requirement | Implementation | Test / evidence | Result |
6| FR-001 | library-web/.../controller/BookController.java | BookCatalogTest.java | passed |
7| FR-005 | LoanServiceImpl + LoanMapper.xml + V001 DDL | CirculationTest.java | passed |
8
9## Commands
10- `mvn --projects library-web test -DskipTests=false`: [真实结果]
11- `mysql -u root library < docs/ddl/V001__library_schema.sql`: [真实结果]
12- `mysql -u root library < docs/ddl/U001__library_schema_rollback.sql`: [真实结果]
13
14## Deviations and open items
15[没有运行、失败、阻塞、人工验收和 Plan 偏离必须逐项写明]

1library-system/
2├── .specify/
3├── specs/001-library-circulation/
4│   ├── spec.md
5│   ├── plan.md
6│   ├── research.md
7│   ├── data-model.md
8│   ├── contracts/openapi.yaml
9│   ├── quickstart.md
10│   ├── checklists/requirements.md
11│   └── tasks.md                    # T001..T021 已更新状态
12├── docs/ddl/V001__library_schema.sql
13├── library-api/
14├── library-service/
15└── library-web/                    # 含 src/test/java/com/example/library/

1mvn --projects library-web test -DskipTests=false
2Tests run: 28, Failures: 0, Errors: 0, Skipped: 0
3exit 0
4
5mysql -u root library < docs/ddl/V001__library_schema.sql
6exit 0
7
8mysql -u root library < docs/ddl/U001__library_schema_rollback.sql
9exit 0
10
11mysql -u root library < docs/ddl/V001__library_schema.sql
12exit 0

1spec.md + plan.md + tasks.md
2        ↓
3代码 + 测试
4        ↓
5implementation-report.md
6        ↓
7V1 candidate

1/speckit.converge

1Tasks appended:
2- T022 [US3] 验证重复归还后 available_copies 未变化
3- T023 补 quickstart 中错误码响应示例

1/speckit.implement
2只执行 Convergence 新增的 T022-T023，运行相关测试并报告结果。
3
4/speckit.converge

1Converged — implementation satisfies the spec, plan, and tasks.

1Artifact review: spec/plan/tasks approved
2Automated tests: Tests run: 28, Failures: 0, Errors: 0
3DDL upgrade/rollback: passed
4Quickstart: passed in 7m42s from clean checkout
5Product acceptance: US1/US2/US3/US4 accepted; US5 accepted separately if included
6Spec Kit converge: Converged
7Deployment: not performed

1# Circulation Specification
2
3## Purpose
4图书目录维护与借还流转能力：LIBRARIAN 维护书目并办理借还，
5MEMBER 查询书目与本人借阅。
6
7## Requirements
8
9### Requirement: Catalog maintenance
10系统 SHALL 允许 LIBRARIAN 录入与编辑图书（ISBN 唯一、库存非负整数）；
11MEMBER 不得执行维护操作。
12
13#### Scenario: 重复 ISBN 被拒绝
14- **GIVEN** 某 ISBN 已存在
15- **WHEN** 再次录入同一 ISBN
16- **THEN** 返回 ISBN_ALREADY_EXISTS 错误码，库存不变
17
18### Requirement: Atomic borrow and return
19借书与库存扣减 SHALL 在同一事务内完成；并发竞争最后一本时恰好一个
20请求成功；归还 SHALL 只成功一次并原子恢复库存。
21
22### Requirement: Derived loan status
23借阅状态 SHALL 按查询时刻派生：已归还为 RETURNED，未归还且逾期为
24OVERDUE，其余为 ACTIVE。

1openspec validate --specs
2git add openspec && git commit -m "20260910_library-system_seedCirculationSpec"