feat(plan): 生成 label_backend 完整实施规划文档
Phase 0：research.md（10项技术决策，无需澄清项） Phase 1：data-model.md（11张表+Redis结构），contracts/（8个模块API契约），quickstart.md（Docker Compose启动+流水线验证） plan.md：宪章11条全部通过，项目结构确认
This commit is contained in:
wh
137
specs/001-label-backend-spec/plan.md
Normal file
137
specs/001-label-backend-spec/plan.md
Normal file
@@ -0,0 +1,137 @@
|
||||
# 实施计划：label_backend 知识图谱智能标注平台
|
||||
|
||||
**分支**: `001-label-backend-spec` | **日期**: 2026-04-09 | **规格说明**: [spec.md](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<T> 包装；无动词路径；PageResult<T> 分页 |
|
||||
| 11 | YAGNI：业务在 Service，Controller 只处理 HTTP | ✅ 通过 | 分层明确；无预测性抽象层 |
|
||||
|
||||
**门控结果：全部通过，可进入 Phase 0。**
|
||||
|
||||
---
|
||||
|
||||
## 项目结构
|
||||
|
||||
### 规格说明文档（本功能）
|
||||
|
||||
```text
|
||||
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 命令创建，非本命令）
|
||||
```
|
||||
|
||||
### 源代码（仓库根目录）
|
||||
|
||||
```text
|
||||
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.
|
||||
Reference in New Issue
Block a user