label_backend/specs/001-label-backend-spec/plan.md

实施计划：label_backend 知识图谱智能标注平台

分支: 001-label-backend-spec | 日期: 2026-04-09 | 规格说明: spec.md
输入: 功能规格说明 /specs/001-label-backend-spec/spec.md

---

摘要

构建面向多租户的知识图谱智能标注平台后端服务，驱动文本线（三元组提取 → 问答对生成 → 训练样本）和图片线（四元组提取 → 问答对生成 → 训练样本）两条流水线。视频作为预处理入口异步汇入两条流水线。系统基于 Spring Boot 3 + Apache Shiro + MyBatis Plus + PostgreSQL + Redis + RustFS 构建，通过 HTTP 调用 Python FastAPI AI 服务完成 AI 辅助标注和问答生成能力。

---

技术上下文

语言/版本: Java 17（LTS）
主要依赖: Spring Boot ≥ 3.0.x、Apache Shiro ≥ 1.13.x、MyBatis Plus ≥ 3.5.x、Spring Data Redis
存储: PostgreSQL ≥ 14（主库）、Redis ≥ 6.x（会话/权限缓存/分布式锁）、RustFS（S3 兼容对象存储）
测试: JUnit 5 + Testcontainers（真实 PostgreSQL + Redis 实例）、Spring Boot Test
目标平台: Linux 服务器，Docker Compose 容器化部署
项目类型: Web Service（REST API）
性能目标: 任务领取并发下有且仅有一人成功；权限变更延迟 < 1 秒生效
约束: 禁止 JWT；禁止 Spring Security；禁止文件字节流存入数据库；AI HTTP 调用禁止在 @Transactional 内同步执行；所有列表接口强制分页
规模: 多租户（多公司），每公司独立数据空间；11 张核心业务表

---

宪章合规检查

门控：Phase 0 研究前必须通过。Phase 1 设计后重检。

#	宪章原则	状态	说明
1	环境约束（JDK 17、SB 3、Shiro、MyBatis Plus）	✅ 通过	pom.xml 中版本约束与宪章完全对齐；无 Spring Security 引入
2	多租户数据隔离（company_id + ThreadLocal）	✅ 通过	TenantLineInnerInterceptor 自动注入；CompanyContext 在 finally 块清理
3	BCrypt 密码 + UUID Token + 禁 JWT	✅ 通过	AuthService 使用 BCrypt ≥ 10；UUID v4 Token 存 Redis；无 JWT 库
4	分级 RBAC + 权限注解 + 角色变更驱逐缓存	✅ 通过	@RequiresRoles 声明权限；updateRole() 立即删 user:perm:{userId}
5	双流水线 + 级联触发 + parent_source_id 溯源	✅ 通过	仅文本线/图片线；审批通过用 @TransactionalEventListener 触发 QA
6	状态机完整性（StateValidator）	✅ 通过	所有状态变更经 StateValidator.assertTransition()；禁止绕过 Mapper 直写
7	任务争抢双重保障（Redis SET NX + DB 乐观锁）	✅ 通过	task:claim:{taskId} TTL 30s + WHERE status='UNCLAIMED'
8	异步视频处理幂等 + 重试上限 + FAILED 手动重置	✅ 通过	SUCCESS 回调静默忽略；retry_count ≥ max_retries → FAILED
9	只追加审计日志 + AOP 切面 + 审计失败不回滚业务	✅ 通过	@OperationLog AOP；sys_operation_log 无 UPDATE/DELETE；异常仅 error 日志
10	RESTful URL + 统一响应格式 + 强制分页	✅ 通过	Result 包装；无动词路径；PageResult 分页
11	YAGNI：业务在 Service，Controller 只处理 HTTP	✅ 通过	分层明确；无预测性抽象层

门控结果：全部通过，可进入 Phase 0。

---

项目结构

规格说明文档（本功能）

specs/001-label-backend-spec/
├── plan.md              # 本文件（/speckit.plan 输出）
├── research.md          # Phase 0 输出
├── data-model.md        # Phase 1 输出
├── quickstart.md        # Phase 1 输出
├── contracts/           # Phase 1 输出（REST API 契约）
│   ├── auth.md
│   ├── source.md
│   ├── tasks.md
│   ├── extraction.md
│   ├── qa.md
│   ├── export.md
│   ├── config.md
│   └── video.md
└── tasks.md             # Phase 2 输出（/speckit.tasks 命令创建，非本命令）

源代码（仓库根目录）

src/
└── main/
    └── java/com/label/
        ├── LabelBackendApplication.java
        ├── common/
        │   ├── result/           # Result<T>、ResultCode、PageResult<T>
        │   ├── exception/        # BusinessException、GlobalExceptionHandler
        │   ├── context/          # CompanyContext（ThreadLocal）
        │   ├── shiro/            # TokenFilter、UserRealm、ShiroConfig
        │   ├── redis/            # RedisKeyManager、RedisService
        │   ├── aop/              # AuditAspect、@OperationLog 注解
        │   ├── storage/          # RustFsClient（S3 兼容封装）
        │   ├── ai/               # AiServiceClient（RestClient 封装 8 个端点）
        │   └── statemachine/     # StateValidator、各状态枚举
        └── module/
            ├── user/             # AuthController、UserController、AuthService、UserService
            ├── source/           # SourceController、SourceService
            ├── task/             # TaskController、TaskService、TaskClaimService
            ├── annotation/       # ExtractionController、QaController、ExtractionService、QaService
            ├── export/           # ExportController、ExportService、FinetuneService
            ├── config/           # SysConfigController、SysConfigService
            └── video/            # VideoController、VideoProcessService

src/
└── test/
    └── java/com/label/
        ├── integration/          # Testcontainers（真实 PG + Redis）集成测试
        │   ├── AuthIntegrationTest.java
        │   ├── TaskClaimConcurrencyTest.java
        │   ├── VideoCallbackIdempotencyTest.java
        │   ├── MultiTenantIsolationTest.java
        │   └── ShiroFilterIntegrationTest.java
        └── unit/                 # 纯单元测试（状态机、业务逻辑）
            └── StateMachineTest.java

sql/
└── init.sql                      # 全部 DDL（11 张表，按依赖顺序执行）

docker-compose.yml                # postgres、redis、rustfs、backend、ai-service、frontend
Dockerfile                        # eclipse-temurin:17-jre-alpine
pom.xml

结构决策：单一后端服务（Web Service），无前端代码。标准 Maven 项目布局，源代码在 src/main/java/com/label/，测试在 src/test/java/com/label/，按 common/ + module/ 两层分包。

---

复杂度追踪

宪章检查无违规，本节留空。

---

GSTACK REVIEW REPORT

Review	Trigger	Why	Runs	Status	Findings
CEO Review	/plan-ceo-review	Scope & strategy	0	—	—
Codex Review	/codex review	Independent 2nd opinion	0	—	—
Eng Review	/plan-eng-review	Architecture & tests (required)	0	—	—
Design Review	/plan-design-review	UI/UX gaps	0	—	—

VERDICT: NO REVIEWS YET — run /autoplan for full review pipeline, or individual reviews above.