From e23d249bd037d7a91c4190f8c7d62549ecd766a5 Mon Sep 17 00:00:00 2001 From: lxp <2770281812@qq.com> Date: Wed, 14 Oct 2026 10:26:20 +0800 Subject: [PATCH] =?UTF-8?q?=E7=A4=BE=E5=8C=BA=E5=88=9D=E5=A7=8B=E5=8C=96?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .env.example | 12 + .gitignore | 5 + README.md | 78 +- community-api/pom.xml | 39 + .../community/api/AuthController.java | 62 ++ .../community/api/CommunityApplication.java | 16 + .../community/api/CommunityController.java | 131 +++ .../community/api/OpenApiConfiguration.java | 30 + .../api/ProductionConfiguration.java | 32 + .../community/api/WorkspaceController.java | 158 +++ .../src/main/resources/application-prod.yml | 23 + .../src/main/resources/application-test.yml | 23 + .../src/main/resources/application.yml | 45 + .../community/api/FakeGiteaClient.java | 149 +++ .../community/api/GiteaLiveTest.java | 261 +++++ .../community/api/SchemaSupport.java | 28 + .../linkerbot/community/api/WorkflowTest.java | 601 +++++++++++ community-bean/pom.xml | 21 + .../linkerbot/community/bean/Contracts.java | 91 ++ .../community/bean/entity/BaseEntity.java | 19 + .../community/bean/entity/Project.java | 29 + .../community/bean/entity/ProjectComment.java | 17 + .../community/bean/entity/ProjectLike.java | 22 + .../linkerbot/community/bean/entity/User.java | 16 + community-common/pom.xml | 20 + .../community/common/ApiResponse.java | 14 + .../community/common/BusinessException.java | 42 + .../com/linkerbot/community/common/Codes.java | 11 + .../linkerbot/community/common/FilePaths.java | 38 + .../common/GlobalExceptionHandler.java | 68 ++ .../community/common/PageResponse.java | 5 + .../community/common/RequestIdFilter.java | 32 + .../src/main/resources/logback-spring.xml | 52 + community-security/pom.xml | 25 + .../community/security/BearerTokenFilter.java | 54 + .../community/security/CaptchaService.java | 95 ++ .../community/security/CurrentUser.java | 25 + .../security/SecurityConfiguration.java | 84 ++ .../community/security/TokenService.java | 40 + .../community/security/SessionTest.java | 45 + community-service/pom.xml | 30 + .../community/service/FileService.java | 264 +++++ .../community/service/InteractionService.java | 106 ++ .../community/service/ProjectLocks.java | 45 + .../community/service/ProjectService.java | 389 +++++++ .../community/service/UserService.java | 70 ++ .../service/config/CommunityProperties.java | 44 + .../service/config/MybatisConfiguration.java | 18 + .../community/service/gitea/GiteaClient.java | 31 + .../community/service/gitea/GiteaFailure.java | 16 + .../service/gitea/RestGiteaClient.java | 249 +++++ .../service/mapper/CommentMapper.java | 9 + .../community/service/mapper/LikeMapper.java | 9 + .../service/mapper/ProjectMapper.java | 9 + .../community/service/mapper/UserMapper.java | 9 + docs/api.md | 965 ++++++++++++++++++ docs/database.md | 80 ++ pom.xml | 58 ++ scripts/run-local.sh | 12 + scripts/test-gitea.py | 24 + 60 files changed, 4994 insertions(+), 1 deletion(-) create mode 100644 .env.example create mode 100644 .gitignore create mode 100644 community-api/pom.xml create mode 100644 community-api/src/main/java/com/linkerbot/community/api/AuthController.java create mode 100644 community-api/src/main/java/com/linkerbot/community/api/CommunityApplication.java create mode 100644 community-api/src/main/java/com/linkerbot/community/api/CommunityController.java create mode 100644 community-api/src/main/java/com/linkerbot/community/api/OpenApiConfiguration.java create mode 100644 community-api/src/main/java/com/linkerbot/community/api/ProductionConfiguration.java create mode 100644 community-api/src/main/java/com/linkerbot/community/api/WorkspaceController.java create mode 100644 community-api/src/main/resources/application-prod.yml create mode 100644 community-api/src/main/resources/application-test.yml create mode 100644 community-api/src/main/resources/application.yml create mode 100644 community-api/src/test/java/com/linkerbot/community/api/FakeGiteaClient.java create mode 100644 community-api/src/test/java/com/linkerbot/community/api/GiteaLiveTest.java create mode 100644 community-api/src/test/java/com/linkerbot/community/api/SchemaSupport.java create mode 100644 community-api/src/test/java/com/linkerbot/community/api/WorkflowTest.java create mode 100644 community-bean/pom.xml create mode 100644 community-bean/src/main/java/com/linkerbot/community/bean/Contracts.java create mode 100644 community-bean/src/main/java/com/linkerbot/community/bean/entity/BaseEntity.java create mode 100644 community-bean/src/main/java/com/linkerbot/community/bean/entity/Project.java create mode 100644 community-bean/src/main/java/com/linkerbot/community/bean/entity/ProjectComment.java create mode 100644 community-bean/src/main/java/com/linkerbot/community/bean/entity/ProjectLike.java create mode 100644 community-bean/src/main/java/com/linkerbot/community/bean/entity/User.java create mode 100644 community-common/pom.xml create mode 100644 community-common/src/main/java/com/linkerbot/community/common/ApiResponse.java create mode 100644 community-common/src/main/java/com/linkerbot/community/common/BusinessException.java create mode 100644 community-common/src/main/java/com/linkerbot/community/common/Codes.java create mode 100644 community-common/src/main/java/com/linkerbot/community/common/FilePaths.java create mode 100644 community-common/src/main/java/com/linkerbot/community/common/GlobalExceptionHandler.java create mode 100644 community-common/src/main/java/com/linkerbot/community/common/PageResponse.java create mode 100644 community-common/src/main/java/com/linkerbot/community/common/RequestIdFilter.java create mode 100644 community-common/src/main/resources/logback-spring.xml create mode 100644 community-security/pom.xml create mode 100644 community-security/src/main/java/com/linkerbot/community/security/BearerTokenFilter.java create mode 100644 community-security/src/main/java/com/linkerbot/community/security/CaptchaService.java create mode 100644 community-security/src/main/java/com/linkerbot/community/security/CurrentUser.java create mode 100644 community-security/src/main/java/com/linkerbot/community/security/SecurityConfiguration.java create mode 100644 community-security/src/main/java/com/linkerbot/community/security/TokenService.java create mode 100644 community-security/src/test/java/com/linkerbot/community/security/SessionTest.java create mode 100644 community-service/pom.xml create mode 100644 community-service/src/main/java/com/linkerbot/community/service/FileService.java create mode 100644 community-service/src/main/java/com/linkerbot/community/service/InteractionService.java create mode 100644 community-service/src/main/java/com/linkerbot/community/service/ProjectLocks.java create mode 100644 community-service/src/main/java/com/linkerbot/community/service/ProjectService.java create mode 100644 community-service/src/main/java/com/linkerbot/community/service/UserService.java create mode 100644 community-service/src/main/java/com/linkerbot/community/service/config/CommunityProperties.java create mode 100644 community-service/src/main/java/com/linkerbot/community/service/config/MybatisConfiguration.java create mode 100644 community-service/src/main/java/com/linkerbot/community/service/gitea/GiteaClient.java create mode 100644 community-service/src/main/java/com/linkerbot/community/service/gitea/GiteaFailure.java create mode 100644 community-service/src/main/java/com/linkerbot/community/service/gitea/RestGiteaClient.java create mode 100644 community-service/src/main/java/com/linkerbot/community/service/mapper/CommentMapper.java create mode 100644 community-service/src/main/java/com/linkerbot/community/service/mapper/LikeMapper.java create mode 100644 community-service/src/main/java/com/linkerbot/community/service/mapper/ProjectMapper.java create mode 100644 community-service/src/main/java/com/linkerbot/community/service/mapper/UserMapper.java create mode 100644 docs/api.md create mode 100644 docs/database.md create mode 100644 pom.xml create mode 100644 scripts/run-local.sh create mode 100644 scripts/test-gitea.py diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..fa6123e --- /dev/null +++ b/.env.example @@ -0,0 +1,12 @@ +# 复制为 .env;此文件不能填写真实凭据后提交。 +DB_URL='jdbc:mysql://localhost:3306/community?useUnicode=true&characterEncoding=utf8&connectionTimeZone=UTC' +DB_USERNAME=community_app +DB_PASSWORD='replace-with-your-database-password' +GITEA_BASE_URL=http://localhost:3000 +GITEA_ORGANIZATION=community +GITEA_TOKEN='replace-with-your-gitea-token' +# 默认 test,部署生产环境时改为 prod;连接信息也应对应生产环境。 +SPRING_PROFILES_ACTIVE=test +# 不设置 LOG_PATH 时,日志按环境写入 logs/test 或 logs/prod。 +# LOG_PATH=/data/community/logs +PORT=8993 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..9fa77e2 --- /dev/null +++ b/.gitignore @@ -0,0 +1,5 @@ +.idea/ +**/target/ +.env +.DS_Store +logs/ diff --git a/README.md b/README.md index ec9e76b..fafb39f 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,78 @@ -# community +# Community + +Spring Boot 社区后端,工程分层参考 cadworld。使用 Java 21、Spring Boot 3.5.7、MyBatis-Plus 3.5.11、MySQL 和 Gitea API v1。业务库名为 community,只有 sys_user、project、project_comment、project_like 四张表。 + +平台管理用户、项目归属、类型、发布、评论、点赞和 Fork 来源;Gitea 管理文件、目录、Commit 与历史。仓库统一存放在配置的 Gitea 组织下,为私有仓库。 + +内置项目类型为 GENERAL(通用)、HUMANOID(人形)、QUADRUPED(四足)、WHEELED(轮式)。前端通过 `/api/project-types` 获取类型列表,用于项目创建、修改和列表筛选。 + +## 功能与边界 + +支持邮箱加图片验证码登录、我的项目列表、在线文本编辑、新建文件和目录、上传及多文件提交、手动发布和撤回、已发布版本浏览、快照 Fork、平铺评论和点赞。工作区是用户项目列表,没有 workspace 表。没有 repository_operation 表、草稿保存、AI、类型表、标签、收藏、成员协作或管理后台。 + +**当前登录不验证邮箱归属,知道别人的邮箱也可能登录其账号。** 验证码和登录会话使用本机缓存,单实例部署,重启后重新登录。所有仓库写入统一经过平台后端。 + +## 启动 + +1. 安装 Java 21、Maven 3.9+,准备 MySQL 8 和现有 Gitea。 +2. 手动执行 [四表建表 SQL](docs/database.md),应用不会自动建表或修改数据库。 +3. 在 Gitea 创建私有组织,将技术账号设为组织所有者,生成具有 write:repository、write:organization、read:user 权限的 Token。 +4. 将 .env.example 复制为 .env,填写数据库连接与 Gitea 地址、组织、Token;默认使用 test 环境,.env 被 Git 忽略,不提交真实凭据。 +5. 执行: + +```bash +bash scripts/run-local.sh +``` + +当前机器已配置 Gitea 26.4.0,并建立私有组织 community。本机 .env 已保存 Gitea Token,权限为 0600;没有保存管理员密码。保留这些 Gitea 配置,再补充 DB_URL、DB_USERNAME、DB_PASSWORD 即可,不要用示例覆盖已有 Token。 + +直接部署时通过环境变量配置,运行打包后的 community-api/target/community-api-0.0.1-SNAPSHOT.jar。默认端口 8993,SERVER_PORT 或 PORT 可覆盖(SERVER_PORT 优先)。本机脚本会加载 .env,直接运行 jar 不会自动加载该文件。 + +接口文档:[前端接口对接文档](docs/api.md),包含全部接口、字段结构、请求响应示例、页面调用顺序和错误处理。启动后访问 /swagger-ui.html;机器可读 OpenAPI 为 /v3/api-docs。 + +## 环境与日志 + +配置与日志方式参考 cadworld:application.yml 保存公共配置,application-test.yml 和 application-prod.yml 分别保存环境相关的数据库、Gitea 和日志配置。不指定环境时默认 test,通过 SPRING_PROFILES_ACTIVE 或启动参数切换。 + +prod 启动时检查数据库连接、用户名、密码、Gitea 地址和 Token 是否已配置且非空;缺失时停止启动,错误信息只包含配置项名称。 + +| 配置 | test | prod | +| --- | --- | --- | +| 数据库 | 默认本机 community,可用 DB_* 覆盖 | 必须配置 DB_URL、DB_USERNAME、DB_PASSWORD | +| Gitea | 默认本机地址,使用 GITEA_* 覆盖 | 必须配置 GITEA_BASE_URL、GITEA_TOKEN;组织默认 community | +| 连接池 | 最少 1、最多 10 个连接 | 最少 1、最多 20 个连接 | +| 项目日志级别 | DEBUG | INFO | +| 日志目录 | logs/test | logs/prod | + +生产部署示例(先在部署环境配置以上连接变量): + +```bash +SPRING_PROFILES_ACTIVE=prod java -Djava.awt.headless=true -jar community-api/target/community-api-0.0.1-SNAPSHOT.jar +``` + +本机脚本支持传递启动参数,例如 `bash scripts/run-local.sh --spring.profiles.active=prod`,此时加载 .env 中的连接信息并使用 prod 配置。测试和生产数据库、Gitea 组织需要各自隔离时,分别设置对应的 DB_*、GITEA_* 变量。 + +公共模块的 logback-spring.xml 同时输出控制台、community.log 和 community-error.log,日志时间使用 Asia/Shanghai,包含线程、requestId 和业务编码。应用日志按天或每 100MB 归档,保留 30 天、总归档上限 10GB;错误日志按天或每 50MB 归档,保留 60 天、总归档上限 5GB。可用 LOG_PATH 覆盖日志目录。SQL Mapper 和 Spring Web 保持 INFO,不记录凭据、邮箱或代码内容。 + +## 验证 + +```bash +mvn clean verify +``` + +普通测试固定使用 test 配置,覆盖连接为临时 H2 MySQL 模式及模拟 Gitea,验证登录、权限、提交冲突、发布快照、Fork、评论、点赞和超时处理,不访问真实数据库或仓库。 + +真实 Gitea 联调: + +```bash +python3 scripts/test-gitea.py +``` + +该测试使用临时 H2 数据库,在配置的组织创建临时项目仓库,验证私有仓库、多文件提交、中文路径、二进制上传、固定发布版本及快照 Fork,结束后仅删除本次测试创建的仓库。Gitea 26.4.0 内置的 1.26.4 支持批量文件变更;以服务器 /swagger.v1.json 为对接依据。 + +## 运行约定 + +项目名称、描述、类型修改直接更新展示;工作区代码提交后,社区仍读取已发布 SHA,需要手动更新。Fork 复制已发布文件快照,不继承上游提交历史,也不自动同步。项目删除采用逻辑删除,保留仓库和已有 Fork。 + +创建或 Fork 前先写入 CREATING 项目,成功后标记 READY。结果不明或数据库回写失败需要人工核对;不提供后台自动恢复、无条件自动重试或跨重启完整幂等。具体恢复方式见接口文档。 diff --git a/community-api/pom.xml b/community-api/pom.xml new file mode 100644 index 0000000..6f96f6f --- /dev/null +++ b/community-api/pom.xml @@ -0,0 +1,39 @@ + + + 4.0.0 + + com.linkerbot + community + 0.0.1-SNAPSHOT + + community-api + + + com.linkerbot + community-security + ${project.version} + + + org.springdoc + springdoc-openapi-starter-webmvc-ui + + + com.mysql + mysql-connector-j + runtime + + + com.h2database + h2 + test + + + + + + org.springframework.boot + spring-boot-maven-plugin + + + + diff --git a/community-api/src/main/java/com/linkerbot/community/api/AuthController.java b/community-api/src/main/java/com/linkerbot/community/api/AuthController.java new file mode 100644 index 0000000..4dcb960 --- /dev/null +++ b/community-api/src/main/java/com/linkerbot/community/api/AuthController.java @@ -0,0 +1,62 @@ +package com.linkerbot.community.api; + +import com.linkerbot.community.bean.Contracts.*; +import com.linkerbot.community.bean.entity.User; +import com.linkerbot.community.common.ApiResponse; +import com.linkerbot.community.security.*; +import com.linkerbot.community.service.UserService; +import com.linkerbot.community.service.config.CommunityProperties; + +import io.swagger.v3.oas.annotations.Operation; +import io.swagger.v3.oas.annotations.security.SecurityRequirements; +import io.swagger.v3.oas.annotations.tags.Tag; + +import jakarta.validation.Valid; + +import lombok.RequiredArgsConstructor; + +import org.springframework.web.bind.annotation.*; + +@RestController +@RequiredArgsConstructor +@Tag(name = "登录与用户") +public class AuthController { + private final CaptchaService captcha; + private final TokenService tokens; + private final UserService users; + private final CommunityProperties config; + + @GetMapping("/api/auth/captcha") + @Operation(summary = "获取一次性图片验证码") + @SecurityRequirements + public ApiResponse captcha() { + return ApiResponse.success(captcha.issue()); + } + + @PostMapping("/api/auth/login") + @Operation(summary = "邮箱和图片验证码登录,首次自动创建用户") + @SecurityRequirements + public ApiResponse login(@Valid @RequestBody LoginRequest input) { + captcha.verify(input.captchaCode(), input.captchaAnswer()); + User user = users.login(input.email()); + return ApiResponse.success( + new LoginView( + tokens.issue(user.getId()), + "Bearer", + config.getTokenTtl().toSeconds(), + users.view(user))); + } + + @PostMapping("/api/auth/logout") + @Operation(summary = "退出登录") + public ApiResponse logout(@RequestHeader("Authorization") String authorization) { + tokens.revoke(authorization.startsWith("Bearer ") ? authorization.substring(7) : null); + return ApiResponse.success(null); + } + + @GetMapping("/api/users/me") + @Operation(summary = "当前用户") + public ApiResponse me() { + return ApiResponse.success(users.view(users.require(CurrentUser.required()))); + } +} diff --git a/community-api/src/main/java/com/linkerbot/community/api/CommunityApplication.java b/community-api/src/main/java/com/linkerbot/community/api/CommunityApplication.java new file mode 100644 index 0000000..afb37ca --- /dev/null +++ b/community-api/src/main/java/com/linkerbot/community/api/CommunityApplication.java @@ -0,0 +1,16 @@ +package com.linkerbot.community.api; + +import org.mybatis.spring.annotation.MapperScan; +import org.springframework.boot.SpringApplication; +import org.springframework.boot.autoconfigure.SpringBootApplication; +import org.springframework.boot.autoconfigure.security.servlet.UserDetailsServiceAutoConfiguration; + +@MapperScan("com.linkerbot.community.service.mapper") +@SpringBootApplication( + scanBasePackages = "com.linkerbot.community", + exclude = UserDetailsServiceAutoConfiguration.class) +public class CommunityApplication { + public static void main(String[] args) { + SpringApplication.run(CommunityApplication.class, args); + } +} diff --git a/community-api/src/main/java/com/linkerbot/community/api/CommunityController.java b/community-api/src/main/java/com/linkerbot/community/api/CommunityController.java new file mode 100644 index 0000000..e54f027 --- /dev/null +++ b/community-api/src/main/java/com/linkerbot/community/api/CommunityController.java @@ -0,0 +1,131 @@ +package com.linkerbot.community.api; + +import com.linkerbot.community.bean.Contracts.*; +import com.linkerbot.community.common.*; +import com.linkerbot.community.security.CurrentUser; +import com.linkerbot.community.service.*; + +import io.swagger.v3.oas.annotations.Operation; +import io.swagger.v3.oas.annotations.security.SecurityRequirements; +import io.swagger.v3.oas.annotations.tags.Tag; + +import jakarta.validation.Valid; + +import lombok.RequiredArgsConstructor; + +import org.springframework.http.ResponseEntity; +import org.springframework.web.bind.annotation.*; + +import java.util.List; + +@RestController +@RequiredArgsConstructor +@Tag(name = "社区") +public class CommunityController { + private final ProjectService projects; + private final FileService files; + private final InteractionService interactions; + + @GetMapping("/api/project-types") + @Operation(summary = "配置中的项目类型") + @SecurityRequirements + public ApiResponse> types() { + return ApiResponse.success(projects.types()); + } + + @GetMapping("/api/community/projects") + @Operation(summary = "已发布项目列表,支持类型和关键词筛选") + @SecurityRequirements + public ApiResponse> list( + @RequestParam(defaultValue = "1") long page, + @RequestParam(defaultValue = "20") long size, + @RequestParam(required = false) String type, + @RequestParam(required = false) String keyword) { + return ApiResponse.success( + projects.list(null, type, keyword, page, size, CurrentUser.optional())); + } + + @GetMapping("/api/community/projects/{projectCode}") + @Operation(summary = "社区项目详情") + @SecurityRequirements + public ApiResponse detail(@PathVariable String projectCode) { + return ApiResponse.success( + projects.view(projects.published(projectCode), CurrentUser.optional())); + } + + @GetMapping("/api/community/projects/{projectCode}/tree") + @Operation(summary = "已发布版本的目录") + @SecurityRequirements + public ApiResponse tree( + @PathVariable String projectCode, + @RequestParam(defaultValue = "") String path, + @RequestParam(required = false) String commitSha) { + rejectRef(commitSha); + return ApiResponse.success(files.communityTree(projectCode, path)); + } + + @GetMapping("/api/community/projects/{projectCode}/files") + @Operation(summary = "已发布版本文件,download=true 时下载") + @SecurityRequirements + public ResponseEntity file( + @PathVariable String projectCode, + @RequestParam String path, + @RequestParam(defaultValue = "false") boolean download, + @RequestParam(required = false) String commitSha) { + rejectRef(commitSha); + return download + ? WorkspaceController.download(files.communityFile(projectCode, path)) + : ResponseEntity.ok( + ApiResponse.success(files.communityFileView(projectCode, path))); + } + + private void rejectRef(String sha) { + if (sha != null) throw BusinessException.badRequest("社区文件仅允许读取当前已发布版本"); + } + + @PostMapping("/api/community/projects/{projectCode}/forks") + @Operation(summary = "复制已发布文件到我的工作区") + public ApiResponse fork( + @PathVariable String projectCode, @Valid @RequestBody ForkInput input) { + return ApiResponse.success(projects.fork(CurrentUser.required(), projectCode, input)); + } + + @GetMapping("/api/community/projects/{projectCode}/comments") + @Operation(summary = "评论列表") + @SecurityRequirements + public ApiResponse> comments( + @PathVariable String projectCode, + @RequestParam(defaultValue = "1") long page, + @RequestParam(defaultValue = "20") long size) { + return ApiResponse.success(interactions.list(projectCode, page, size)); + } + + @PostMapping("/api/community/projects/{projectCode}/comments") + @Operation(summary = "新增纯文本评论") + public ApiResponse comment( + @PathVariable String projectCode, @Valid @RequestBody CommentInput input) { + return ApiResponse.success( + interactions.comment(CurrentUser.required(), projectCode, input)); + } + + @DeleteMapping("/api/comments/{commentCode}") + @Operation(summary = "删除自己的评论") + public ApiResponse deleteComment(@PathVariable String commentCode) { + interactions.deleteComment(CurrentUser.required(), commentCode); + return ApiResponse.success(null); + } + + @PutMapping("/api/community/projects/{projectCode}/like") + @Operation(summary = "幂等点赞") + public ApiResponse like(@PathVariable String projectCode) { + interactions.like(CurrentUser.required(), projectCode); + return ApiResponse.success(null); + } + + @DeleteMapping("/api/community/projects/{projectCode}/like") + @Operation(summary = "幂等取消点赞") + public ApiResponse unlike(@PathVariable String projectCode) { + interactions.unlike(CurrentUser.required(), projectCode); + return ApiResponse.success(null); + } +} diff --git a/community-api/src/main/java/com/linkerbot/community/api/OpenApiConfiguration.java b/community-api/src/main/java/com/linkerbot/community/api/OpenApiConfiguration.java new file mode 100644 index 0000000..283f962 --- /dev/null +++ b/community-api/src/main/java/com/linkerbot/community/api/OpenApiConfiguration.java @@ -0,0 +1,30 @@ +package com.linkerbot.community.api; + +import io.swagger.v3.oas.models.*; +import io.swagger.v3.oas.models.info.Info; +import io.swagger.v3.oas.models.security.*; + +import org.springframework.context.annotation.*; + +@Configuration +public class OpenApiConfiguration { + @Bean + public OpenAPI openAPI() { + return new OpenAPI() + .info( + new Info() + .title("Community 首期接口") + .version("v1") + .description( + "四表社区后端。登录仅邮箱和图片验证码,无法验证邮箱归属。Gitea" + + " 仓库统一存放在组织下。文件下载返回二进制,其余响应使用统一包装。")) + .components( + new Components() + .addSecuritySchemes( + "bearer", + new SecurityScheme() + .type(SecurityScheme.Type.HTTP) + .scheme("bearer"))) + .addSecurityItem(new SecurityRequirement().addList("bearer")); + } +} diff --git a/community-api/src/main/java/com/linkerbot/community/api/ProductionConfiguration.java b/community-api/src/main/java/com/linkerbot/community/api/ProductionConfiguration.java new file mode 100644 index 0000000..ea3d5e9 --- /dev/null +++ b/community-api/src/main/java/com/linkerbot/community/api/ProductionConfiguration.java @@ -0,0 +1,32 @@ +package com.linkerbot.community.api; + +import org.springframework.context.annotation.Configuration; +import org.springframework.context.annotation.Profile; +import org.springframework.core.env.Environment; + +import java.util.List; + +@Configuration(proxyBeanMethods = false) +@Profile("prod") +public class ProductionConfiguration { + public ProductionConfiguration(Environment environment) { + for (String property : + List.of( + "spring.datasource.url", + "spring.datasource.username", + "spring.datasource.password", + "community.gitea.base-url", + "community.gitea.token")) { + String value; + try { + value = environment.getRequiredProperty(property); + } catch (IllegalArgumentException | IllegalStateException error) { + // 仅提示配置项名称,避免异常链携带配置值。 + throw new IllegalStateException("生产环境必须配置 " + property); + } + if (value.isBlank()) { + throw new IllegalStateException("生产环境必须配置 " + property); + } + } + } +} diff --git a/community-api/src/main/java/com/linkerbot/community/api/WorkspaceController.java b/community-api/src/main/java/com/linkerbot/community/api/WorkspaceController.java new file mode 100644 index 0000000..132fa5e --- /dev/null +++ b/community-api/src/main/java/com/linkerbot/community/api/WorkspaceController.java @@ -0,0 +1,158 @@ +package com.linkerbot.community.api; + +import com.linkerbot.community.bean.Contracts.*; +import com.linkerbot.community.common.*; +import com.linkerbot.community.security.CurrentUser; +import com.linkerbot.community.service.*; +import com.linkerbot.community.service.gitea.GiteaClient; + +import io.swagger.v3.oas.annotations.Operation; +import io.swagger.v3.oas.annotations.tags.Tag; + +import jakarta.validation.Valid; + +import lombok.RequiredArgsConstructor; + +import org.springframework.http.*; +import org.springframework.web.bind.annotation.*; +import org.springframework.web.multipart.MultipartFile; + +import java.nio.charset.StandardCharsets; +import java.util.List; + +@RestController +@RequiredArgsConstructor +@RequestMapping("/api/workspace/projects") +@Tag(name = "我的工作区") +public class WorkspaceController { + private final ProjectService projects; + private final FileService files; + + @GetMapping + @Operation(summary = "我的项目列表") + public ApiResponse> list( + @RequestParam(defaultValue = "1") long page, + @RequestParam(defaultValue = "20") long size, + @RequestParam(required = false) String type, + @RequestParam(required = false) String keyword) { + long user = CurrentUser.required(); + return ApiResponse.success(projects.list(user, type, keyword, page, size, user)); + } + + @PostMapping + @Operation(summary = "创建项目和组织中的私有仓库") + public ApiResponse create(@Valid @RequestBody ProjectInput input) { + return ApiResponse.success(projects.create(CurrentUser.required(), input)); + } + + @GetMapping("/{projectCode}") + @Operation(summary = "我的项目详情") + public ApiResponse detail(@PathVariable String projectCode) { + long user = CurrentUser.required(); + return ApiResponse.success(projects.view(projects.owner(user, projectCode), user)); + } + + @PatchMapping("/{projectCode}") + @Operation(summary = "修改名称、描述和类型") + public ApiResponse update( + @PathVariable String projectCode, @Valid @RequestBody ProjectInput input) { + return ApiResponse.success(projects.update(CurrentUser.required(), projectCode, input)); + } + + @DeleteMapping("/{projectCode}") + @Operation(summary = "逻辑删除项目并撤回社区") + public ApiResponse delete(@PathVariable String projectCode) { + projects.delete(CurrentUser.required(), projectCode); + return ApiResponse.success(null); + } + + @GetMapping("/{projectCode}/tree") + @Operation(summary = "读取目录,可指定本项目 Commit") + public ApiResponse tree( + @PathVariable String projectCode, + @RequestParam(defaultValue = "") String path, + @RequestParam(required = false) String commitSha) { + return ApiResponse.success( + files.ownerTree(CurrentUser.required(), projectCode, path, commitSha)); + } + + @GetMapping("/{projectCode}/files") + @Operation(summary = "读取文件,download=true 时下载") + public ResponseEntity file( + @PathVariable String projectCode, + @RequestParam String path, + @RequestParam(required = false) String commitSha, + @RequestParam(defaultValue = "false") boolean download) { + long user = CurrentUser.required(); + if (!download) + return ResponseEntity.ok( + ApiResponse.success(files.ownerFileView(user, projectCode, path, commitSha))); + return download(files.ownerFile(user, projectCode, path, commitSha)); + } + + public static ResponseEntity download(GiteaClient.StoredFile file) { + String name = file.path().substring(file.path().lastIndexOf('/') + 1); + return ResponseEntity.ok() + .contentType(MediaType.APPLICATION_OCTET_STREAM) + .header( + HttpHeaders.CONTENT_DISPOSITION, + ContentDisposition.attachment() + .filename(name, StandardCharsets.UTF_8) + .build() + .toString()) + .body(file.bytes()); + } + + @PostMapping("/{projectCode}/commits") + @Operation(summary = "多文件变更提交为一个 Commit") + public ApiResponse commit( + @PathVariable String projectCode, @Valid @RequestBody CommitInput input) { + return ApiResponse.success(files.commit(CurrentUser.required(), projectCode, input)); + } + + @GetMapping("/{projectCode}/commits") + @Operation(summary = "main 提交历史") + public ApiResponse> history( + @PathVariable String projectCode, + @RequestParam(defaultValue = "1") long page, + @RequestParam(defaultValue = "20") long size) { + return ApiResponse.success(files.history(CurrentUser.required(), projectCode, page, size)); + } + + @PostMapping( + value = "/{projectCode}/uploads/commit", + consumes = MediaType.MULTIPART_FORM_DATA_VALUE) + @Operation(summary = "上传或替换文件并一次提交") + public ApiResponse upload( + @PathVariable String projectCode, + @RequestParam String expectedCommitSha, + @RequestParam String message, + @RequestParam(defaultValue = "") String directory, + @RequestParam("files") List uploaded, + @RequestParam(required = false) List paths) { + return ApiResponse.success( + files.upload( + CurrentUser.required(), + projectCode, + expectedCommitSha, + message, + directory, + uploaded, + paths)); + } + + @PutMapping("/{projectCode}/publication") + @Operation(summary = "发布或手动更新社区文件版本") + public ApiResponse publish( + @PathVariable String projectCode, @Valid @RequestBody PublicationInput input) { + return ApiResponse.success( + projects.publish(CurrentUser.required(), projectCode, input.commitSha())); + } + + @DeleteMapping("/{projectCode}/publication") + @Operation(summary = "撤回社区") + public ApiResponse withdraw(@PathVariable String projectCode) { + projects.withdraw(CurrentUser.required(), projectCode); + return ApiResponse.success(null); + } +} diff --git a/community-api/src/main/resources/application-prod.yml b/community-api/src/main/resources/application-prod.yml new file mode 100644 index 0000000..e75b243 --- /dev/null +++ b/community-api/src/main/resources/application-prod.yml @@ -0,0 +1,23 @@ +spring: + datasource: + url: ${DB_URL} + username: ${DB_USERNAME} + password: ${DB_PASSWORD} + driver-class-name: com.mysql.cj.jdbc.Driver + hikari: + pool-name: CommunityHikariCP + minimum-idle: 1 + maximum-pool-size: 20 + connection-timeout: 5000 + +community: + gitea: + base-url: ${GITEA_BASE_URL} + owner: ${GITEA_ORGANIZATION:community} + token: ${GITEA_TOKEN} + +logging: + file: + path: ${LOG_PATH:logs/prod} + level: + com.linkerbot.community: INFO diff --git a/community-api/src/main/resources/application-test.yml b/community-api/src/main/resources/application-test.yml new file mode 100644 index 0000000..d5d27a9 --- /dev/null +++ b/community-api/src/main/resources/application-test.yml @@ -0,0 +1,23 @@ +spring: + datasource: + url: ${DB_URL:jdbc:mysql://localhost:3306/community?useUnicode=true&characterEncoding=utf8&connectionTimeZone=UTC} + username: ${DB_USERNAME:root} + password: ${DB_PASSWORD:} + driver-class-name: com.mysql.cj.jdbc.Driver + hikari: + pool-name: CommunityHikariCP + minimum-idle: 1 + maximum-pool-size: 10 + connection-timeout: 5000 + +community: + gitea: + base-url: ${GITEA_BASE_URL:http://localhost:3000} + owner: ${GITEA_ORGANIZATION:community} + token: ${GITEA_TOKEN:} + +logging: + file: + path: ${LOG_PATH:logs/test} + level: + com.linkerbot.community: DEBUG diff --git a/community-api/src/main/resources/application.yml b/community-api/src/main/resources/application.yml new file mode 100644 index 0000000..7433b1b --- /dev/null +++ b/community-api/src/main/resources/application.yml @@ -0,0 +1,45 @@ +server: + port: ${SERVER_PORT:${PORT:8993}} +spring: + application: + name: community + profiles: + default: test + sql: + init: + mode: never + servlet: + multipart: + max-file-size: 10MB + max-request-size: 52MB + jackson: + time-zone: UTC + main: + banner-mode: off +mybatis-plus: + configuration: + map-underscore-to-camel-case: true +community: + types: + GENERAL: 通用 + HUMANOID: 人形 + QUADRUPED: 四足 + WHEELED: 轮式 + captcha-ttl: 2m + token-ttl: 24h + max-text-bytes: 1048576 + max-file-bytes: 10485760 + max-request-bytes: 52428800 + gitea: + connect-timeout: 5s + request-timeout: 30s +springdoc: + swagger-ui: + path: /swagger-ui.html +logging: + level: + root: INFO + org.springframework: INFO + # 测试环境开启项目 DEBUG 时,不输出 SQL 参数或完整请求内容。 + com.linkerbot.community.service.mapper: INFO + org.springframework.web: INFO diff --git a/community-api/src/test/java/com/linkerbot/community/api/FakeGiteaClient.java b/community-api/src/test/java/com/linkerbot/community/api/FakeGiteaClient.java new file mode 100644 index 0000000..acb4dd0 --- /dev/null +++ b/community-api/src/test/java/com/linkerbot/community/api/FakeGiteaClient.java @@ -0,0 +1,149 @@ +package com.linkerbot.community.api; + +import com.linkerbot.community.bean.Contracts.*; +import com.linkerbot.community.common.PageResponse; +import com.linkerbot.community.service.gitea.*; + +import java.security.MessageDigest; +import java.util.*; +import java.util.concurrent.atomic.AtomicLong; + +final class FakeGiteaClient implements GiteaClient { + private static final class RepoData { + Repository repository; + String head; + Map> snapshots = new HashMap<>(); + List history = new ArrayList<>(); + } + + private final Map repositories = new HashMap<>(); + private final AtomicLong sequence = new AtomicLong(); + boolean timeoutNextCommit; + boolean timeoutNextCreate; + boolean failNextCreate; + + void reset() { + repositories.clear(); + timeoutNextCommit = false; + timeoutNextCreate = false; + failNextCreate = false; + } + + private String sha() { + return String.format("%040x", sequence.incrementAndGet()); + } + + private String blob(byte[] data) { + try { + return HexFormat.of().formatHex(MessageDigest.getInstance("SHA-1").digest(data)); + } catch (Exception error) { + throw new IllegalStateException(error); + } + } + + private RepoData repo(Repository repository) { + return repositories.get(repository.id()); + } + + @Override + public synchronized Repository createRepository(String name, boolean initialize) { + if (failNextCreate) { + failNextCreate = false; + throw new GiteaFailure(502, "GITEA_ERROR", "服务拒绝请求", false); + } + RepoData data = new RepoData(); + data.repository = new Repository(sequence.incrementAndGet(), "community", name); + repositories.put(data.repository.id(), data); + if (initialize) + commit( + data.repository, + List.of(new Change("create", "README.md", null, "initial".getBytes())), + "Initial commit", + "system", + "system"); + if (timeoutNextCreate) { + timeoutNextCreate = false; + throw new GiteaFailure(504, "REMOTE_RESULT_UNKNOWN", "创建结果未知", true); + } + return data.repository; + } + + @Override + public synchronized String head(Repository repository) { + return repo(repository).head; + } + + @Override + public synchronized List tree(Repository repository, String sha, String path) { + Map snapshot = repo(repository).snapshots.get(sha); + if (snapshot == null) throw new GiteaFailure(404, "NOT_FOUND", "版本不存在", false); + String prefix = path.isEmpty() ? "" : path + "/"; + Map entries = new TreeMap<>(); + for (Map.Entry file : snapshot.entrySet()) { + if (!file.getKey().startsWith(prefix)) continue; + String remainder = file.getKey().substring(prefix.length()); + int separator = remainder.indexOf('/'); + String name = separator < 0 ? remainder : remainder.substring(0, separator); + String entryPath = prefix + name; + entries.put( + entryPath, + separator < 0 + ? new TreeEntry( + entryPath, + name, + "file", + file.getValue().length, + blob(file.getValue())) + : new TreeEntry(entryPath, name, "dir", 0, "")); + } + return new ArrayList<>(entries.values()); + } + + @Override + public synchronized StoredFile file(Repository repository, String sha, String path) { + Map snapshot = repo(repository).snapshots.get(sha); + byte[] bytes = snapshot == null ? null : snapshot.get(path); + if (bytes == null) throw new GiteaFailure(404, "NOT_FOUND", "文件不存在", false); + return new StoredFile(path, blob(bytes), bytes.clone()); + } + + @Override + public synchronized CommitView commit( + Repository repository, + List changes, + String message, + String authorName, + String authorCode) { + RepoData repo = repo(repository); + Map snapshot = + repo.head == null ? new TreeMap<>() : new TreeMap<>(repo.snapshots.get(repo.head)); + for (Change change : changes) { + byte[] old = snapshot.get(change.path()); + if (change.operation().equals("create") && old != null) + throw new GiteaFailure(409, "GITEA_CONFLICT", "文件已存在", false); + if (!change.operation().equals("create") + && (old == null || !blob(old).equals(change.blobSha()))) + throw new GiteaFailure(409, "GITEA_CONFLICT", "文件版本冲突", false); + if (change.operation().equals("delete")) snapshot.remove(change.path()); + else snapshot.put(change.path(), change.bytes().clone()); + } + repo.head = sha(); + repo.snapshots.put(repo.head, snapshot); + repo.history.addFirst( + new HistoryEntry(repo.head, message, authorName, "2026-10-13T00:00:00Z")); + if (timeoutNextCommit) { + timeoutNextCommit = false; + throw new GiteaFailure(504, "REMOTE_RESULT_UNKNOWN", "提交结果未知", true); + } + return new CommitView(repo.head, message); + } + + @Override + public synchronized PageResponse history( + Repository repository, long page, long size) { + List history = repo(repository).history; + int from = (int) Math.min(history.size(), (page - 1) * size); + int to = (int) Math.min(history.size(), from + size); + return new PageResponse<>(history.subList(from, to), page, size, history.size()); + } +} diff --git a/community-api/src/test/java/com/linkerbot/community/api/GiteaLiveTest.java b/community-api/src/test/java/com/linkerbot/community/api/GiteaLiveTest.java new file mode 100644 index 0000000..bfb7dbf --- /dev/null +++ b/community-api/src/test/java/com/linkerbot/community/api/GiteaLiveTest.java @@ -0,0 +1,261 @@ +package com.linkerbot.community.api; + +import static org.assertj.core.api.Assertions.*; +import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*; +import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*; + +import com.fasterxml.jackson.databind.JsonNode; +import com.fasterxml.jackson.databind.ObjectMapper; +import com.linkerbot.community.security.CaptchaService; +import com.linkerbot.community.service.config.CommunityProperties; + +import org.junit.jupiter.api.*; +import org.junit.jupiter.api.condition.EnabledIfEnvironmentVariable; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc; +import org.springframework.boot.test.autoconfigure.web.servlet.MockMvcPrint; +import org.springframework.boot.test.context.*; +import org.springframework.context.annotation.*; +import org.springframework.http.MediaType; +import org.springframework.jdbc.core.JdbcTemplate; +import org.springframework.mock.web.MockMultipartFile; +import org.springframework.test.context.ActiveProfiles; +import org.springframework.test.web.servlet.*; +import org.springframework.test.web.servlet.request.MockHttpServletRequestBuilder; + +import java.net.URI; +import java.net.http.*; +import java.time.Duration; +import java.util.*; + +@SpringBootTest( + properties = { + "spring.datasource.url=jdbc:h2:mem:live;MODE=MySQL;DB_CLOSE_DELAY=-1", + "spring.datasource.username=sa", + "spring.datasource.password=", + "spring.datasource.driver-class-name=org.h2.Driver", + "logging.level.root=INFO", + "logging.level.org.springframework=WARN" + }) +@ActiveProfiles("test") +@AutoConfigureMockMvc(print = MockMvcPrint.NONE) +@Import(GiteaLiveTest.Config.class) +@EnabledIfEnvironmentVariable(named = "COMMUNITY_LIVE_GITEA", matches = "true") +class GiteaLiveTest { + @TestConfiguration + static class Config { + @Bean + @Primary + CaptchaService liveCaptcha(CommunityProperties properties) { + return new CaptchaService(properties) { + @Override + protected String generateAnswer() { + return "ABCDE"; + } + }; + } + } + + @Autowired MockMvc mvc; + @Autowired ObjectMapper json; + @Autowired JdbcTemplate jdbc; + @Autowired CommunityProperties config; + + @BeforeEach + void schema() throws Exception { + SchemaSupport.reset(jdbc); + } + + @AfterEach + void removeOnlyRepositoriesCreatedByThisTest() throws Exception { + HttpClient http = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(5)).build(); + for (String repo : jdbc.queryForList("SELECT gitea_repo_name FROM project", String.class)) { + if (!repo.matches("p_[0-9a-f]{32}")) throw new IllegalStateException("拒绝清理非测试仓库"); + HttpRequest request = + HttpRequest.newBuilder( + URI.create( + config.getGitea().getBaseUrl() + + "/api/v1/repos/" + + config.getGitea().getOwner() + + "/" + + repo)) + .timeout(Duration.ofSeconds(30)) + .header("Authorization", "token " + config.getGitea().getToken()) + .DELETE() + .build(); + assertThat(http.send(request, HttpResponse.BodyHandlers.discarding()).statusCode()) + .isIn(204, 404); + } + } + + private MockHttpServletRequestBuilder body(MockHttpServletRequestBuilder request, Object body) + throws Exception { + return request.contentType(MediaType.APPLICATION_JSON) + .content(json.writeValueAsBytes(body)); + } + + private MockHttpServletRequestBuilder auth( + MockHttpServletRequestBuilder request, String token) { + return request.header("Authorization", "Bearer " + token); + } + + private JsonNode perform(MockHttpServletRequestBuilder request, int expected) throws Exception { + MvcResult result = mvc.perform(request).andReturn(); + JsonNode response = json.readTree(result.getResponse().getContentAsByteArray()); + assertThat(result.getResponse().getStatus()) + .withFailMessage( + "请求失败 code=%s requestId=%s", + response.path("code").asText(), response.path("requestId").asText()) + .isEqualTo(expected); + return response.path("data"); + } + + private String login(String email) throws Exception { + String captcha = perform(get("/api/auth/captcha"), 200).path("captchaCode").asText(); + return perform( + body( + post("/api/auth/login"), + Map.of( + "email", + email, + "captchaCode", + captcha, + "captchaAnswer", + "ABCDE")), + 200) + .path("token") + .asText(); + } + + @Test + void realOrganizationRepositoryCommitPublishUploadAndSnapshotFork() throws Exception { + String owner = login("live-owner@example.invalid"), + other = login("live-fork@example.invalid"); + String code = + perform( + body( + auth(post("/api/workspace/projects"), owner), + Map.of("name", "集成测试临时项目", "projectType", "GENERAL")), + 200) + .path("projectCode") + .asText(); + String a = + perform(auth(get("/api/workspace/projects/" + code + "/tree"), owner), 200) + .path("commitSha") + .asText(); + JsonNode before = + perform( + auth( + get("/api/workspace/projects/" + code + "/files") + .param("path", "README.md"), + owner), + 200); + perform( + body( + auth(put("/api/workspace/projects/" + code + "/publication"), owner), + Map.of("commitSha", a)), + 200); + JsonNode b = + perform( + body( + auth(post("/api/workspace/projects/" + code + "/commits"), owner), + Map.of( + "expectedCommitSha", + a, + "message", + "集成验证多文件提交", + "changes", + List.of( + Map.of( + "action", + "UPDATE_FILE", + "path", + "README.md", + "content", + "unpublished"), + Map.of("action", "CREATE_DIRECTORY", "path", "空目录"), + Map.of( + "action", + "CREATE_FILE", + "path", + "源码/hello world.txt", + "content", + "你好")))), + 200); + assertThat( + perform( + get("/api/community/projects/" + code + "/files") + .param("path", "README.md"), + 200) + .path("content") + .asText()) + .isEqualTo(before.path("content").asText()); + byte[] binary = {0, 1, 2, 3, 4}; + MockMultipartFile upload = + new MockMultipartFile("files", "part.bin", "application/octet-stream", binary); + JsonNode c = + perform( + auth( + multipart("/api/workspace/projects/" + code + "/uploads/commit") + .file(upload) + .param("message", "验证二进制") + .param("expectedCommitSha", b.path("commitSha").asText()) + .param("directory", "模型"), + owner), + 200); + mvc.perform( + auth( + get("/api/workspace/projects/" + code + "/files") + .param("path", "模型/part.bin") + .param("download", "true"), + owner)) + .andExpect(status().isOk()) + .andExpect(content().bytes(binary)); + perform( + body( + auth(put("/api/workspace/projects/" + code + "/publication"), owner), + Map.of("commitSha", c.path("commitSha").asText())), + 200); + JsonNode fork = + perform( + body( + auth(post("/api/community/projects/" + code + "/forks"), other), + Map.of( + "name", + "集成测试临时副本", + "publishedCommitSha", + c.path("commitSha").asText())), + 200); + String copy = fork.path("projectCode").asText(); + assertThat( + perform( + auth( + get("/api/workspace/projects/" + copy + "/files") + .param("path", "源码/hello world.txt"), + other), + 200) + .path("content") + .asText()) + .isEqualTo("你好"); + mvc.perform( + auth( + get("/api/workspace/projects/" + copy + "/files") + .param("path", "模型/part.bin") + .param("download", "true"), + other)) + .andExpect(status().isOk()) + .andExpect(content().bytes(binary)); + assertThat( + perform( + auth( + get("/api/workspace/projects/" + code + "/commits"), + owner), + 200) + .path("total") + .asLong()) + .isGreaterThanOrEqualTo(3); + perform(auth(delete("/api/workspace/projects/" + code + "/publication"), owner), 200); + perform(get("/api/community/projects/" + code), 404); + perform(auth(get("/api/workspace/projects/" + copy + "/tree"), other), 200); + } +} diff --git a/community-api/src/test/java/com/linkerbot/community/api/SchemaSupport.java b/community-api/src/test/java/com/linkerbot/community/api/SchemaSupport.java new file mode 100644 index 0000000..d123b50 --- /dev/null +++ b/community-api/src/test/java/com/linkerbot/community/api/SchemaSupport.java @@ -0,0 +1,28 @@ +package com.linkerbot.community.api; + +import org.springframework.jdbc.core.JdbcTemplate; + +import java.io.IOException; +import java.nio.file.Files; +import java.nio.file.Path; +import java.util.regex.*; + +final class SchemaSupport { + static void reset(JdbcTemplate jdbc) throws IOException { + Path path = Path.of("../docs/database.md"); + if (!Files.exists(path)) path = Path.of("docs/database.md"); + String content = Files.readString(path); + Matcher matcher = Pattern.compile("CREATE TABLE [\\s\\S]*?;").matcher(content); + jdbc.execute("DROP ALL OBJECTS"); + int tables = 0; + while (matcher.find()) { + String ddl = + matcher.group() + .replaceAll(" COMMENT '[^']*'", "") + .replaceAll("\\) ENGINE=InnoDB[^;]*;", ");"); + jdbc.execute(ddl); + tables++; + } + if (tables != 4) throw new IllegalStateException("必须只有四张业务表"); + } +} diff --git a/community-api/src/test/java/com/linkerbot/community/api/WorkflowTest.java b/community-api/src/test/java/com/linkerbot/community/api/WorkflowTest.java new file mode 100644 index 0000000..f4d7367 --- /dev/null +++ b/community-api/src/test/java/com/linkerbot/community/api/WorkflowTest.java @@ -0,0 +1,601 @@ +package com.linkerbot.community.api; + +import static org.assertj.core.api.Assertions.*; +import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*; +import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*; + +import com.fasterxml.jackson.databind.JsonNode; +import com.fasterxml.jackson.databind.ObjectMapper; +import com.linkerbot.community.security.CaptchaService; +import com.linkerbot.community.service.config.CommunityProperties; + +import org.junit.jupiter.api.*; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc; +import org.springframework.boot.test.autoconfigure.web.servlet.MockMvcPrint; +import org.springframework.boot.test.context.*; +import org.springframework.context.annotation.*; +import org.springframework.http.MediaType; +import org.springframework.jdbc.core.JdbcTemplate; +import org.springframework.mock.web.MockMultipartFile; +import org.springframework.test.context.ActiveProfiles; +import org.springframework.test.web.servlet.*; +import org.springframework.test.web.servlet.request.MockHttpServletRequestBuilder; + +import java.util.*; +import java.util.concurrent.*; + +@SpringBootTest( + properties = { + "spring.datasource.url=jdbc:h2:mem:workflow;MODE=MySQL;DB_CLOSE_DELAY=-1", + "spring.datasource.username=sa", + "spring.datasource.password=", + "spring.datasource.driver-class-name=org.h2.Driver", + "logging.level.root=INFO", + "logging.level.org.springframework=WARN" + }) +@ActiveProfiles("test") +@AutoConfigureMockMvc(print = MockMvcPrint.NONE) +@Import(WorkflowTest.Config.class) +class WorkflowTest { + @TestConfiguration + static class Config { + @Bean + @Primary + FakeGiteaClient fakeGitea() { + return new FakeGiteaClient(); + } + + @Bean + @Primary + CaptchaService fixedCaptcha(CommunityProperties properties) { + return new CaptchaService(properties) { + @Override + protected String generateAnswer() { + return "ABCDE"; + } + }; + } + } + + @Autowired MockMvc mvc; + @Autowired ObjectMapper json; + @Autowired JdbcTemplate jdbc; + @Autowired FakeGiteaClient gitea; + + @BeforeEach + void reset() throws Exception { + SchemaSupport.reset(jdbc); + gitea.reset(); + } + + private JsonNode perform(MockHttpServletRequestBuilder builder, int status) throws Exception { + String body = + mvc.perform(builder) + .andExpect(status().is(status)) + .andReturn() + .getResponse() + .getContentAsString(); + return body.isEmpty() ? json.createObjectNode() : json.readTree(body); + } + + private MockHttpServletRequestBuilder body(MockHttpServletRequestBuilder request, Object body) + throws Exception { + return request.contentType(MediaType.APPLICATION_JSON) + .content(json.writeValueAsBytes(body)); + } + + private JsonNode loginData(String email) throws Exception { + String captcha = + perform(get("/api/auth/captcha"), 200).path("data").path("captchaCode").asText(); + return perform( + body( + post("/api/auth/login"), + Map.of( + "email", + email, + "captchaCode", + captcha, + "captchaAnswer", + "abcde")), + 200) + .path("data"); + } + + private String login(String email) throws Exception { + return loginData(email).path("token").asText(); + } + + private MockHttpServletRequestBuilder auth( + MockHttpServletRequestBuilder request, String token) { + return request.header("Authorization", "Bearer " + token); + } + + private String create(String token, String name) throws Exception { + JsonNode result = + perform( + body( + auth(post("/api/workspace/projects"), token), + Map.of( + "name", + name, + "description", + "测试项目", + "projectType", + "GENERAL")), + 200); + assertThat(result.path("data").has("id")).isFalse(); + return result.path("data").path("projectCode").asText(); + } + + private String head(String token, String code) throws Exception { + return perform(auth(get("/api/workspace/projects/" + code + "/tree"), token), 200) + .path("data") + .path("commitSha") + .asText(); + } + + private String commit(String token, String code, String expected, String content) + throws Exception { + return perform( + body( + auth(post("/api/workspace/projects/" + code + "/commits"), token), + Map.of( + "expectedCommitSha", + expected, + "message", + "修改说明", + "changes", + List.of( + Map.of( + "action", + "UPDATE_FILE", + "path", + "README.md", + "content", + content)))), + 200) + .path("data") + .path("commitSha") + .asText(); + } + + private void publish(String token, String code, String sha) throws Exception { + perform( + body( + auth(put("/api/workspace/projects/" + code + "/publication"), token), + Map.of("commitSha", sha)), + 200); + } + + @Test + void loginNormalizesEmailAndConsumesCaptchaAndLogout() throws Exception { + JsonNode first = loginData("OWNER@example.com"); + JsonNode second = loginData("owner@example.com"); + assertThat(first.path("user").path("userCode").asText()) + .isEqualTo(second.path("user").path("userCode").asText()); + assertThat(jdbc.queryForObject("SELECT COUNT(*) FROM sys_user", Long.class)).isEqualTo(1L); + JsonNode challenge = perform(get("/api/auth/captcha"), 200).path("data"); + assertThat(challenge.path("image").asText()).startsWith("data:image/png;base64,"); + Map input = + Map.of( + "email", + "test@example.com", + "captchaCode", + challenge.path("captchaCode").asText(), + "captchaAnswer", + "WRONG"); + perform(body(post("/api/auth/login"), input), 400); + perform( + body( + post("/api/auth/login"), + Map.of( + "email", + "test@example.com", + "captchaCode", + challenge.path("captchaCode").asText(), + "captchaAnswer", + "ABCDE")), + 400); + String token = first.path("token").asText(); + JsonNode me = perform(auth(get("/api/users/me"), token), 200).path("data"); + assertThat(me.has("id")).isFalse(); + perform(auth(post("/api/auth/logout"), token), 200); + perform(auth(get("/api/users/me"), token), 401); + perform(get("/api/workspace/projects"), 401); + } + + @Test + void openApiMatchesRoutesAndPublicAuthenticationAndOnlyFourTablesExist() throws Exception { + JsonNode spec = perform(get("/v3/api-docs"), 200); + assertThat(spec.path("paths").has("/api/workspace/projects")).isTrue(); + assertThat(spec.path("paths").has("/api/repository-operations/{operationCode}")).isFalse(); + assertThat(spec.path("paths").path("/api/auth/login").path("post").path("security").size()) + .isZero(); + assertThat(spec.path("security").size()).isEqualTo(1); + assertThat( + jdbc.queryForList( + "SELECT table_name FROM information_schema.tables WHERE" + + " table_schema='PUBLIC'", + String.class)) + .containsExactlyInAnyOrder( + "SYS_USER", "PROJECT", "PROJECT_COMMENT", "PROJECT_LIKE"); + } + + @Test + void publishPinsFilesAndForkCopiesOnlyPublishedSnapshot() throws Exception { + String owner = login("owner@example.com"); + String other = login("other@example.com"); + String code = create(owner, "测试项目"); + String a = head(owner, code); + publish(owner, code, a); + String b = commit(owner, code, a, "未发布内容"); + JsonNode file = + perform( + get("/api/community/projects/" + code + "/files") + .param("path", "README.md"), + 200) + .path("data"); + assertThat(file.path("content").asText()).isEqualTo("initial"); + assertThat(file.path("commitSha").asText()).isEqualTo(a); + perform( + get("/api/community/projects/" + code + "/files") + .param("path", "README.md") + .param("commitSha", b), + 400); + JsonNode fork = + perform( + body( + auth( + post("/api/community/projects/" + code + "/forks"), + other), + Map.of("publishedCommitSha", a, "name", "我的副本")), + 200) + .path("data"); + String copy = fork.path("projectCode").asText(); + assertThat(fork.path("sourceProjectCode").asText()).isEqualTo(code); + assertThat( + perform( + auth( + get("/api/workspace/projects/" + copy + "/files") + .param("path", "README.md"), + other), + 200) + .path("data") + .path("content") + .asText()) + .isEqualTo("initial"); + publish(owner, code, b); + assertThat( + perform( + get("/api/community/projects/" + code + "/files") + .param("path", "README.md"), + 200) + .path("data") + .path("content") + .asText()) + .isEqualTo("未发布内容"); + perform( + body( + auth(post("/api/community/projects/" + code + "/forks"), other), + Map.of("publishedCommitSha", a, "name", "过时副本")), + 409); + perform(auth(delete("/api/workspace/projects/" + code), owner), 200); + perform(get("/api/community/projects/" + code), 404); + perform(auth(get("/api/workspace/projects/" + copy + "/tree"), other), 200); + } + + @Test + void permissionsAndFlatCommentsAndIdempotentLikes() throws Exception { + String owner = login("owner@example.com"); + String other = login("other@example.com"); + String code = create(owner, "权限项目"); + perform(auth(get("/api/workspace/projects/" + code), other), 404); + perform(auth(get("/api/workspace/projects/" + code + "/tree"), other), 404); + perform(auth(delete("/api/workspace/projects/" + code), other), 404); + perform(get("/api/community/projects/" + code), 404); + publish(owner, code, head(owner, code)); + perform(put("/api/community/projects/" + code + "/like"), 401); + perform(auth(put("/api/community/projects/" + code + "/like"), other), 200); + perform(auth(put("/api/community/projects/" + code + "/like"), other), 200); + assertThat( + perform(get("/api/community/projects/" + code), 200) + .path("data") + .path("likeCount") + .asLong()) + .isEqualTo(1); + JsonNode comment = + perform( + body( + auth( + post( + "/api/community/projects/" + + code + + "/comments"), + other), + Map.of("content", "纯文本评论")), + 200) + .path("data"); + assertThat(comment.path("author").has("email")).isFalse(); + assertThat(comment.path("author").has("id")).isFalse(); + String commentCode = comment.path("commentCode").asText(); + perform(auth(delete("/api/comments/" + commentCode), owner), 404); + perform(auth(delete("/api/comments/" + commentCode), other), 200); + assertThat( + perform(get("/api/community/projects/" + code + "/comments"), 200) + .path("data") + .path("total") + .asLong()) + .isZero(); + perform(auth(delete("/api/community/projects/" + code + "/like"), other), 200); + perform(auth(delete("/api/community/projects/" + code + "/like"), other), 200); + assertThat(jdbc.queryForObject("SELECT COUNT(*) FROM project_like", Long.class)).isZero(); + perform(auth(delete("/api/workspace/projects/" + code + "/publication"), owner), 200); + perform(get("/api/community/projects/" + code), 404); + perform(auth(get("/api/workspace/projects/" + code + "/tree"), owner), 200); + } + + @Test + void directoriesAndBinaryUploadAndDeletionAndPagination() throws Exception { + String owner = login("files@example.com"); + String code = create(owner, "文件项目"); + String sha = head(owner, code); + JsonNode changed = + perform( + body( + auth( + post( + "/api/workspace/projects/" + + code + + "/commits"), + owner), + Map.of( + "expectedCommitSha", + sha, + "message", + "创建目录和文件", + "changes", + List.of( + Map.of( + "action", + "CREATE_DIRECTORY", + "path", + "models"), + Map.of( + "action", + "CREATE_FILE", + "path", + "src/main.txt", + "content", + "hello")))), + 200) + .path("data"); + byte[] bytes = {0, 1, 2, 3}; + MockMultipartFile upload = + new MockMultipartFile("files", "model.bin", "application/octet-stream", bytes); + JsonNode committed = + perform( + auth( + multipart( + "/api/workspace/projects/" + + code + + "/uploads/commit") + .file(upload) + .param( + "expectedCommitSha", + changed.path("commitSha").asText()) + .param("message", "上传模型") + .param("directory", "models"), + owner), + 200) + .path("data"); + mvc.perform( + auth( + get("/api/workspace/projects/" + code + "/files") + .param("path", "models/model.bin") + .param("download", "true"), + owner)) + .andExpect(status().isOk()) + .andExpect(content().bytes(bytes)); + JsonNode binary = + perform( + auth( + get("/api/workspace/projects/" + code + "/files") + .param("path", "models/model.bin"), + owner), + 200) + .path("data"); + assertThat(binary.path("editable").asBoolean()).isFalse(); + assertThat(binary.path("encoding").asText()).isEqualTo("base64"); + perform( + body( + auth(post("/api/workspace/projects/" + code + "/commits"), owner), + Map.of( + "expectedCommitSha", + committed.path("commitSha").asText(), + "message", + "删除文件", + "changes", + List.of(Map.of("action", "DELETE_FILE", "path", "src/main.txt")))), + 200); + perform( + auth( + get("/api/workspace/projects/" + code + "/files") + .param("path", "src/main.txt"), + owner), + 404); + assertThat( + perform( + auth( + get("/api/workspace/projects/" + code + "/commits") + .param("size", "2"), + owner), + 200) + .path("data") + .path("items") + .size()) + .isEqualTo(2); + perform(auth(get("/api/workspace/projects").param("size", "101"), owner), 400); + } + + @Test + void staleAndConcurrentSubmissionsCannotOverwrite() throws Exception { + String owner = login("concurrent@example.com"); + String code = create(owner, "并发项目"); + String sha = head(owner, code); + ExecutorService executor = Executors.newFixedThreadPool(2); + try { + Callable submit = + () -> + mvc.perform( + body( + auth( + post( + "/api/workspace/projects/" + + code + + "/commits"), + owner), + Map.of( + "expectedCommitSha", + sha, + "message", + "并发提交", + "changes", + List.of( + Map.of( + "action", + "UPDATE_FILE", + "path", + "README.md", + "content", + "new"))))) + .andReturn() + .getResponse() + .getStatus(); + List> results = executor.invokeAll(List.of(submit, submit)); + assertThat(List.of(results.get(0).get(), results.get(1).get())) + .containsExactlyInAnyOrder(200, 409); + } finally { + executor.shutdownNow(); + } + perform( + body( + auth(put("/api/workspace/projects/" + code + "/publication"), owner), + Map.of("commitSha", sha)), + 409); + } + + @Test + void unsafePathsOversizedTextAndUnsupportedTypeAreRejected() throws Exception { + String owner = login("paths@example.com"); + perform( + body( + auth(post("/api/workspace/projects"), owner), + Map.of("name", "x", "projectType", "UNKNOWN")), + 400); + String code = create(owner, "路径项目"); + String sha = head(owner, code); + for (String path : List.of("../secret", "/tmp/secret", ".git/config", "a/../b", "a\\b")) { + perform( + auth( + get("/api/workspace/projects/" + code + "/files").param("path", path), + owner), + 400); + } + perform( + body( + auth(post("/api/workspace/projects/" + code + "/commits"), owner), + Map.of( + "expectedCommitSha", + sha, + "message", + "大文件", + "changes", + List.of( + Map.of( + "action", + "CREATE_FILE", + "path", + "large.txt", + "content", + "x".repeat(1048577))))), + 413); + } + + @Test + void unknownRemoteWritesAreNotRepeatedAndFailedCreatesRemainVisible() throws Exception { + String owner = login("failure@example.com"); + gitea.failNextCreate = true; + JsonNode failure = + perform( + body( + auth(post("/api/workspace/projects"), owner), + Map.of("name", "失败项目", "projectType", "GENERAL")), + 502); + String failed = failure.path("data").path("projectCode").asText(); + assertThat( + perform(auth(get("/api/workspace/projects/" + failed), owner), 200) + .path("data") + .path("repoStatus") + .asText()) + .isEqualTo("FAILED"); + gitea.timeoutNextCreate = true; + JsonNode pending = + perform( + body( + auth(post("/api/workspace/projects"), owner), + Map.of("name", "待核对项目", "projectType", "GENERAL")), + 504); + assertThat( + perform( + auth( + get( + "/api/workspace/projects/" + + pending.path("data") + .path("projectCode") + .asText()), + owner), + 200) + .path("data") + .path("repoStatus") + .asText()) + .isEqualTo("CREATING"); + String code = create(owner, "超时项目"); + String sha = head(owner, code); + gitea.timeoutNextCommit = true; + Map request = + Map.of( + "expectedCommitSha", + sha, + "message", + "超时提交", + "changes", + List.of( + Map.of( + "action", + "UPDATE_FILE", + "path", + "README.md", + "content", + "实际成功"))); + perform( + body(auth(post("/api/workspace/projects/" + code + "/commits"), owner), request), + 504); + perform( + body(auth(post("/api/workspace/projects/" + code + "/commits"), owner), request), + 409); + assertThat( + perform( + auth( + get("/api/workspace/projects/" + code + "/files") + .param("path", "README.md"), + owner), + 200) + .path("data") + .path("content") + .asText()) + .isEqualTo("实际成功"); + perform(auth(delete("/api/workspace/projects/" + code + "/publication"), owner), 200); + perform(auth(delete("/api/workspace/projects/" + code), owner), 200); + } +} diff --git a/community-bean/pom.xml b/community-bean/pom.xml new file mode 100644 index 0000000..3bcfe1b --- /dev/null +++ b/community-bean/pom.xml @@ -0,0 +1,21 @@ + + + 4.0.0 + + com.linkerbot + community + 0.0.1-SNAPSHOT + + community-bean + + + com.baomidou + mybatis-plus-core + ${mybatis-plus.version} + + + org.springframework.boot + spring-boot-starter-validation + + + diff --git a/community-bean/src/main/java/com/linkerbot/community/bean/Contracts.java b/community-bean/src/main/java/com/linkerbot/community/bean/Contracts.java new file mode 100644 index 0000000..20981f2 --- /dev/null +++ b/community-bean/src/main/java/com/linkerbot/community/bean/Contracts.java @@ -0,0 +1,91 @@ +package com.linkerbot.community.bean; + +import jakarta.validation.Valid; +import jakarta.validation.constraints.*; + +import java.time.LocalDateTime; +import java.util.List; + +public final class Contracts { + private Contracts() {} + + public record LoginRequest( + @NotBlank @Email @Size(max = 254) String email, + @NotBlank String captchaCode, + @NotBlank String captchaAnswer) {} + + public record UserView(String userCode, String nickname, String email) {} + + public record PublicUser(String userCode, String nickname) {} + + public record LoginView(String token, String tokenType, long expiresIn, UserView user) {} + + public record CaptchaView(String captchaCode, String image, long expiresIn) {} + + public record ProjectInput( + @NotBlank @Size(max = 100) String name, + @Size(max = 2000) String description, + @NotBlank @Size(max = 64) String projectType) {} + + public record PublicationInput(@NotBlank String commitSha) {} + + public record ForkInput( + @NotBlank String publishedCommitSha, @NotBlank @Size(max = 100) String name) {} + + public record CommentInput(@NotBlank @Size(max = 2000) String content) {} + + public record TypeView(String code, String name) {} + + public record ProjectView( + String projectCode, + String name, + String description, + String projectType, + PublicUser owner, + String repoStatus, + String publishStatus, + String publishedCommitSha, + LocalDateTime publishedAt, + String sourceProjectCode, + String sourceCommitSha, + long likeCount, + long commentCount, + boolean liked, + LocalDateTime createdAt, + LocalDateTime updatedAt) {} + + public record CommentView( + String commentCode, PublicUser author, String content, LocalDateTime createdAt) {} + + public enum ChangeAction { + CREATE_FILE, + UPDATE_FILE, + DELETE_FILE, + CREATE_DIRECTORY + } + + public record FileChange(@NotNull ChangeAction action, @NotBlank String path, String content) {} + + public record CommitInput( + @NotBlank String expectedCommitSha, + @NotBlank @Size(max = 1000) String message, + @NotEmpty @Size(max = 500) List<@Valid FileChange> changes) {} + + public record CommitView(String commitSha, String message) {} + + public record TreeEntry(String path, String name, String type, long size, String blobSha) {} + + public record TreeView(String commitSha, String path, List entries) {} + + public record FileView( + String commitSha, + String path, + String blobSha, + long size, + String encoding, + String content, + boolean editable) {} + + public record HistoryEntry( + String commitSha, String message, String authorName, String authorDate) {} +} diff --git a/community-bean/src/main/java/com/linkerbot/community/bean/entity/BaseEntity.java b/community-bean/src/main/java/com/linkerbot/community/bean/entity/BaseEntity.java new file mode 100644 index 0000000..c0e976f --- /dev/null +++ b/community-bean/src/main/java/com/linkerbot/community/bean/entity/BaseEntity.java @@ -0,0 +1,19 @@ +package com.linkerbot.community.bean.entity; + +import com.baomidou.mybatisplus.annotation.IdType; +import com.baomidou.mybatisplus.annotation.TableId; + +import lombok.Getter; +import lombok.Setter; + +import java.time.LocalDateTime; + +@Getter +@Setter +public abstract class BaseEntity { + @TableId(type = IdType.AUTO) + private Long id; + + private LocalDateTime createdAt; + private LocalDateTime updatedAt; +} diff --git a/community-bean/src/main/java/com/linkerbot/community/bean/entity/Project.java b/community-bean/src/main/java/com/linkerbot/community/bean/entity/Project.java new file mode 100644 index 0000000..d726f5d --- /dev/null +++ b/community-bean/src/main/java/com/linkerbot/community/bean/entity/Project.java @@ -0,0 +1,29 @@ +package com.linkerbot.community.bean.entity; + +import com.baomidou.mybatisplus.annotation.TableName; + +import lombok.Getter; +import lombok.Setter; + +import java.time.LocalDateTime; + +@Getter +@Setter +@TableName("project") +public class Project extends BaseEntity { + private String projectCode; + private Long ownerUserId; + private String name; + private String description; + private String projectType; + private Long giteaRepoId; + private String giteaOwner; + private String giteaRepoName; + private String repoStatus; + private String publishStatus; + private String publishedCommitSha; + private LocalDateTime publishedAt; + private Long sourceProjectId; + private String sourceCommitSha; + private Boolean deleted; +} diff --git a/community-bean/src/main/java/com/linkerbot/community/bean/entity/ProjectComment.java b/community-bean/src/main/java/com/linkerbot/community/bean/entity/ProjectComment.java new file mode 100644 index 0000000..7acff7b --- /dev/null +++ b/community-bean/src/main/java/com/linkerbot/community/bean/entity/ProjectComment.java @@ -0,0 +1,17 @@ +package com.linkerbot.community.bean.entity; + +import com.baomidou.mybatisplus.annotation.TableName; + +import lombok.Getter; +import lombok.Setter; + +@Getter +@Setter +@TableName("project_comment") +public class ProjectComment extends BaseEntity { + private String commentCode; + private Long projectId; + private Long userId; + private String content; + private Boolean deleted; +} diff --git a/community-bean/src/main/java/com/linkerbot/community/bean/entity/ProjectLike.java b/community-bean/src/main/java/com/linkerbot/community/bean/entity/ProjectLike.java new file mode 100644 index 0000000..68f37bd --- /dev/null +++ b/community-bean/src/main/java/com/linkerbot/community/bean/entity/ProjectLike.java @@ -0,0 +1,22 @@ +package com.linkerbot.community.bean.entity; + +import com.baomidou.mybatisplus.annotation.IdType; +import com.baomidou.mybatisplus.annotation.TableId; +import com.baomidou.mybatisplus.annotation.TableName; + +import lombok.Getter; +import lombok.Setter; + +import java.time.LocalDateTime; + +@Getter +@Setter +@TableName("project_like") +public class ProjectLike { + @TableId(type = IdType.AUTO) + private Long id; + + private Long projectId; + private Long userId; + private LocalDateTime createdAt; +} diff --git a/community-bean/src/main/java/com/linkerbot/community/bean/entity/User.java b/community-bean/src/main/java/com/linkerbot/community/bean/entity/User.java new file mode 100644 index 0000000..846b7cf --- /dev/null +++ b/community-bean/src/main/java/com/linkerbot/community/bean/entity/User.java @@ -0,0 +1,16 @@ +package com.linkerbot.community.bean.entity; + +import com.baomidou.mybatisplus.annotation.TableName; + +import lombok.Getter; +import lombok.Setter; + +@Getter +@Setter +@TableName("sys_user") +public class User extends BaseEntity { + private String userCode; + private String email; + private String nickname; + private String status; +} diff --git a/community-common/pom.xml b/community-common/pom.xml new file mode 100644 index 0000000..4124d10 --- /dev/null +++ b/community-common/pom.xml @@ -0,0 +1,20 @@ + + + 4.0.0 + + com.linkerbot + community + 0.0.1-SNAPSHOT + + community-common + + + org.springframework.boot + spring-boot-starter-web + + + org.springframework.boot + spring-boot-starter-validation + + + diff --git a/community-common/src/main/java/com/linkerbot/community/common/ApiResponse.java b/community-common/src/main/java/com/linkerbot/community/common/ApiResponse.java new file mode 100644 index 0000000..6cd2c4c --- /dev/null +++ b/community-common/src/main/java/com/linkerbot/community/common/ApiResponse.java @@ -0,0 +1,14 @@ +package com.linkerbot.community.common; + +import org.slf4j.MDC; + +public record ApiResponse(String code, String message, T data, String requestId) { + public static ApiResponse success(T data) { + return new ApiResponse<>("OK", "成功", data, MDC.get("requestId")); + } + + public static ApiResponse failure(BusinessException error) { + return new ApiResponse<>( + error.code(), error.getMessage(), error.details(), MDC.get("requestId")); + } +} diff --git a/community-common/src/main/java/com/linkerbot/community/common/BusinessException.java b/community-common/src/main/java/com/linkerbot/community/common/BusinessException.java new file mode 100644 index 0000000..9a67d63 --- /dev/null +++ b/community-common/src/main/java/com/linkerbot/community/common/BusinessException.java @@ -0,0 +1,42 @@ +package com.linkerbot.community.common; + +public class BusinessException extends RuntimeException { + private final int status; + private final String code; + private final Object details; + + public BusinessException(int status, String code, String message) { + this(status, code, message, null); + } + + public BusinessException(int status, String code, String message, Object details) { + super(message); + this.status = status; + this.code = code; + this.details = details; + } + + public int status() { + return status; + } + + public String code() { + return code; + } + + public Object details() { + return details; + } + + public static BusinessException badRequest(String message) { + return new BusinessException(400, "BAD_REQUEST", message); + } + + public static BusinessException notFound() { + return new BusinessException(404, "NOT_FOUND", "资源不存在或不可访问"); + } + + public static BusinessException conflict(String message) { + return new BusinessException(409, "CONFLICT", message); + } +} diff --git a/community-common/src/main/java/com/linkerbot/community/common/Codes.java b/community-common/src/main/java/com/linkerbot/community/common/Codes.java new file mode 100644 index 0000000..96b8b49 --- /dev/null +++ b/community-common/src/main/java/com/linkerbot/community/common/Codes.java @@ -0,0 +1,11 @@ +package com.linkerbot.community.common; + +import java.util.UUID; + +public final class Codes { + private Codes() {} + + public static String next() { + return UUID.randomUUID().toString().replace("-", ""); + } +} diff --git a/community-common/src/main/java/com/linkerbot/community/common/FilePaths.java b/community-common/src/main/java/com/linkerbot/community/common/FilePaths.java new file mode 100644 index 0000000..8845d06 --- /dev/null +++ b/community-common/src/main/java/com/linkerbot/community/common/FilePaths.java @@ -0,0 +1,38 @@ +package com.linkerbot.community.common; + +import java.util.Locale; + +public final class FilePaths { + private FilePaths() {} + + public static String directory(String path) { + return path == null || path.isEmpty() ? "" : file(path); + } + + public static String file(String path) { + if (path == null + || path.isBlank() + || path.length() > 1024 + || path.startsWith("/") + || path.contains("\\") + || path.chars().anyMatch(c -> c < 32 || c == 127)) { + throw BusinessException.badRequest("文件路径必须是合法的相对路径"); + } + for (String part : path.split("/", -1)) { + if (part.isEmpty() + || part.equals(".") + || part.equals("..") + || part.toLowerCase(Locale.ROOT).equals(".git") + || part.contains(":")) { + throw BusinessException.badRequest("文件路径包含禁止的目录或字符"); + } + } + return path; + } + + public static String sha(String sha) { + if (sha == null || !sha.matches("[0-9a-fA-F]{40}|[0-9a-fA-F]{64}")) + throw BusinessException.badRequest("Commit SHA 格式错误"); + return sha.toLowerCase(Locale.ROOT); + } +} diff --git a/community-common/src/main/java/com/linkerbot/community/common/GlobalExceptionHandler.java b/community-common/src/main/java/com/linkerbot/community/common/GlobalExceptionHandler.java new file mode 100644 index 0000000..94606f0 --- /dev/null +++ b/community-common/src/main/java/com/linkerbot/community/common/GlobalExceptionHandler.java @@ -0,0 +1,68 @@ +package com.linkerbot.community.common; + +import jakarta.validation.ConstraintViolationException; + +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import org.springframework.http.ResponseEntity; +import org.springframework.http.converter.HttpMessageNotReadableException; +import org.springframework.web.HttpMediaTypeNotSupportedException; +import org.springframework.web.HttpRequestMethodNotSupportedException; +import org.springframework.web.bind.MethodArgumentNotValidException; +import org.springframework.web.bind.MissingServletRequestParameterException; +import org.springframework.web.bind.annotation.ExceptionHandler; +import org.springframework.web.bind.annotation.RestControllerAdvice; +import org.springframework.web.method.annotation.HandlerMethodValidationException; +import org.springframework.web.method.annotation.MethodArgumentTypeMismatchException; +import org.springframework.web.multipart.MaxUploadSizeExceededException; +import org.springframework.web.multipart.support.MissingServletRequestPartException; +import org.springframework.web.servlet.resource.NoResourceFoundException; + +@RestControllerAdvice +public class GlobalExceptionHandler { + private static final Logger log = LoggerFactory.getLogger(GlobalExceptionHandler.class); + + @ExceptionHandler(BusinessException.class) + public ResponseEntity> business(BusinessException error) { + return ResponseEntity.status(error.status()).body(ApiResponse.failure(error)); + } + + @ExceptionHandler({ + MethodArgumentNotValidException.class, + ConstraintViolationException.class, + HttpMessageNotReadableException.class, + HandlerMethodValidationException.class, + MissingServletRequestParameterException.class, + MethodArgumentTypeMismatchException.class, + MissingServletRequestPartException.class + }) + public ResponseEntity> invalid(Exception error) { + return business(BusinessException.badRequest("请求参数不合法")); + } + + @ExceptionHandler(MaxUploadSizeExceededException.class) + public ResponseEntity> oversized(Exception error) { + return business(new BusinessException(413, "UPLOAD_TOO_LARGE", "上传超过大小限制")); + } + + @ExceptionHandler(HttpRequestMethodNotSupportedException.class) + public ResponseEntity> method(Exception error) { + return business(new BusinessException(405, "METHOD_NOT_ALLOWED", "不支持此请求方法")); + } + + @ExceptionHandler(HttpMediaTypeNotSupportedException.class) + public ResponseEntity> media(Exception error) { + return business(new BusinessException(415, "UNSUPPORTED_MEDIA_TYPE", "请求内容类型不支持")); + } + + @ExceptionHandler(NoResourceFoundException.class) + public ResponseEntity> missing(Exception error) { + return business(BusinessException.notFound()); + } + + @ExceptionHandler(Exception.class) + public ResponseEntity> unexpected(Exception error) { + log.error("未处理异常 type={}", error.getClass().getName()); + return business(new BusinessException(500, "INTERNAL_ERROR", "服务暂时不可用,请提供 requestId 排查")); + } +} diff --git a/community-common/src/main/java/com/linkerbot/community/common/PageResponse.java b/community-common/src/main/java/com/linkerbot/community/common/PageResponse.java new file mode 100644 index 0000000..ca7b1f4 --- /dev/null +++ b/community-common/src/main/java/com/linkerbot/community/common/PageResponse.java @@ -0,0 +1,5 @@ +package com.linkerbot.community.common; + +import java.util.List; + +public record PageResponse(List items, long page, long size, long total) {} diff --git a/community-common/src/main/java/com/linkerbot/community/common/RequestIdFilter.java b/community-common/src/main/java/com/linkerbot/community/common/RequestIdFilter.java new file mode 100644 index 0000000..dddc576 --- /dev/null +++ b/community-common/src/main/java/com/linkerbot/community/common/RequestIdFilter.java @@ -0,0 +1,32 @@ +package com.linkerbot.community.common; + +import jakarta.servlet.FilterChain; +import jakarta.servlet.ServletException; +import jakarta.servlet.http.HttpServletRequest; +import jakarta.servlet.http.HttpServletResponse; + +import org.slf4j.MDC; +import org.springframework.core.Ordered; +import org.springframework.core.annotation.Order; +import org.springframework.stereotype.Component; +import org.springframework.web.filter.OncePerRequestFilter; + +import java.io.IOException; + +@Component +@Order(Ordered.HIGHEST_PRECEDENCE) +public class RequestIdFilter extends OncePerRequestFilter { + @Override + protected void doFilterInternal( + HttpServletRequest request, HttpServletResponse response, FilterChain chain) + throws ServletException, IOException { + String requestId = Codes.next(); + MDC.put("requestId", requestId); + response.setHeader("X-Request-Id", requestId); + try { + chain.doFilter(request, response); + } finally { + MDC.remove("requestId"); + } + } +} diff --git a/community-common/src/main/resources/logback-spring.xml b/community-common/src/main/resources/logback-spring.xml new file mode 100644 index 0000000..501e825 --- /dev/null +++ b/community-common/src/main/resources/logback-spring.xml @@ -0,0 +1,52 @@ + + + + + + + + + + ${LOG_PATTERN} + UTF-8 + + + + + ${LOG_PATH}/${APP_NAME}.log + + ${LOG_PATTERN} + UTF-8 + + + ${LOG_PATH}/archive/${APP_NAME}.%d{yyyy-MM-dd,Asia/Shanghai}.%i.log.gz + 100MB + 30 + 10GB + + + + + ${LOG_PATH}/${APP_NAME}-error.log + + ERROR + + + ${LOG_PATTERN} + UTF-8 + + + ${LOG_PATH}/archive/${APP_NAME}-error.%d{yyyy-MM-dd,Asia/Shanghai}.%i.log.gz + 50MB + 60 + 5GB + + + + + + + + + diff --git a/community-security/pom.xml b/community-security/pom.xml new file mode 100644 index 0000000..6762240 --- /dev/null +++ b/community-security/pom.xml @@ -0,0 +1,25 @@ + + + 4.0.0 + + com.linkerbot + community + 0.0.1-SNAPSHOT + + community-security + + + com.linkerbot + community-service + ${project.version} + + + org.springframework.boot + spring-boot-starter-security + + + com.github.ben-manes.caffeine + caffeine + + + diff --git a/community-security/src/main/java/com/linkerbot/community/security/BearerTokenFilter.java b/community-security/src/main/java/com/linkerbot/community/security/BearerTokenFilter.java new file mode 100644 index 0000000..4ab5278 --- /dev/null +++ b/community-security/src/main/java/com/linkerbot/community/security/BearerTokenFilter.java @@ -0,0 +1,54 @@ +package com.linkerbot.community.security; + +import com.fasterxml.jackson.databind.ObjectMapper; +import com.linkerbot.community.common.*; +import com.linkerbot.community.service.UserService; + +import jakarta.servlet.FilterChain; +import jakarta.servlet.ServletException; +import jakarta.servlet.http.*; + +import lombok.RequiredArgsConstructor; + +import org.springframework.security.authentication.UsernamePasswordAuthenticationToken; +import org.springframework.security.core.authority.SimpleGrantedAuthority; +import org.springframework.security.core.context.SecurityContextHolder; +import org.springframework.stereotype.Component; +import org.springframework.web.filter.OncePerRequestFilter; + +import java.io.IOException; +import java.util.List; + +@Component +@RequiredArgsConstructor +public class BearerTokenFilter extends OncePerRequestFilter { + private final TokenService tokens; + private final UserService users; + private final ObjectMapper json; + + @Override + protected void doFilterInternal( + HttpServletRequest request, HttpServletResponse response, FilterChain chain) + throws ServletException, IOException { + String header = request.getHeader("Authorization"); + if (header != null && header.startsWith("Bearer ")) { + try { + Long id = tokens.resolve(header.substring(7)); + if (id == null) throw new BusinessException(401, "UNAUTHORIZED", "登录已失效,请重新登录"); + users.require(id); + UsernamePasswordAuthenticationToken auth = + new UsernamePasswordAuthenticationToken( + new CurrentUser.Principal(id), + null, + List.of(new SimpleGrantedAuthority("ROLE_USER"))); + SecurityContextHolder.getContext().setAuthentication(auth); + } catch (BusinessException error) { + response.setStatus(error.status()); + response.setContentType("application/json;charset=UTF-8"); + json.writeValue(response.getOutputStream(), ApiResponse.failure(error)); + return; + } + } + chain.doFilter(request, response); + } +} diff --git a/community-security/src/main/java/com/linkerbot/community/security/CaptchaService.java b/community-security/src/main/java/com/linkerbot/community/security/CaptchaService.java new file mode 100644 index 0000000..a7f23ac --- /dev/null +++ b/community-security/src/main/java/com/linkerbot/community/security/CaptchaService.java @@ -0,0 +1,95 @@ +package com.linkerbot.community.security; + +import com.github.benmanes.caffeine.cache.Cache; +import com.github.benmanes.caffeine.cache.Caffeine; +import com.linkerbot.community.bean.Contracts.CaptchaView; +import com.linkerbot.community.common.*; +import com.linkerbot.community.service.config.CommunityProperties; + +import org.springframework.stereotype.Service; + +import java.awt.*; +import java.awt.image.BufferedImage; +import java.io.ByteArrayOutputStream; +import java.io.IOException; +import java.nio.charset.StandardCharsets; +import java.security.MessageDigest; +import java.security.SecureRandom; +import java.util.Base64; +import java.util.Locale; + +import javax.imageio.ImageIO; + +@Service +public class CaptchaService { + private final SecureRandom random = new SecureRandom(); + private final Cache challenges; + private final CommunityProperties config; + + public CaptchaService(CommunityProperties config) { + this.config = config; + this.challenges = + Caffeine.newBuilder() + .maximumSize(10000) + .expireAfterWrite(config.getCaptchaTtl()) + .build(); + } + + protected String generateAnswer() { + String alphabet = "23456789ABCDEFGHJKLMNPQRSTUVWXYZ"; + StringBuilder result = new StringBuilder(); + for (int i = 0; i < 5; i++) + result.append(alphabet.charAt(random.nextInt(alphabet.length()))); + return result.toString(); + } + + public CaptchaView issue() { + String answer = generateAnswer(); + BufferedImage image = new BufferedImage(180, 60, BufferedImage.TYPE_INT_RGB); + Graphics2D graphics = image.createGraphics(); + try { + graphics.setColor(new Color(245, 247, 250)); + graphics.fillRect(0, 0, 180, 60); + for (int i = 0; i < 10; i++) { + graphics.setColor( + new Color(random.nextInt(160), random.nextInt(160), random.nextInt(160))); + graphics.drawLine( + random.nextInt(180), + random.nextInt(60), + random.nextInt(180), + random.nextInt(60)); + } + graphics.setFont(new Font(Font.SANS_SERIF, Font.BOLD, 30)); + for (int i = 0; i < answer.length(); i++) { + graphics.setColor( + new Color(random.nextInt(100), random.nextInt(100), random.nextInt(100))); + graphics.drawString( + String.valueOf(answer.charAt(i)), 15 + i * 30, 38 + random.nextInt(8)); + } + } finally { + graphics.dispose(); + } + try (ByteArrayOutputStream bytes = new ByteArrayOutputStream()) { + ImageIO.write(image, "png", bytes); + String code = Codes.next(); + challenges.put(code, answer); + return new CaptchaView( + code, + "data:image/png;base64," + + Base64.getEncoder().encodeToString(bytes.toByteArray()), + config.getCaptchaTtl().toSeconds()); + } catch (IOException error) { + throw new BusinessException(500, "CAPTCHA_ERROR", "验证码生成失败"); + } + } + + public void verify(String code, String answer) { + String expected = challenges.asMap().remove(code); + String actual = answer == null ? "" : answer.trim().toUpperCase(Locale.ROOT); + if (expected == null + || !MessageDigest.isEqual( + expected.getBytes(StandardCharsets.UTF_8), + actual.getBytes(StandardCharsets.UTF_8))) + throw new BusinessException(400, "CAPTCHA_INVALID", "图片验证码错误、已使用或已过期"); + } +} diff --git a/community-security/src/main/java/com/linkerbot/community/security/CurrentUser.java b/community-security/src/main/java/com/linkerbot/community/security/CurrentUser.java new file mode 100644 index 0000000..c9ac27f --- /dev/null +++ b/community-security/src/main/java/com/linkerbot/community/security/CurrentUser.java @@ -0,0 +1,25 @@ +package com.linkerbot.community.security; + +import com.linkerbot.community.common.BusinessException; + +import org.springframework.security.core.Authentication; +import org.springframework.security.core.context.SecurityContextHolder; + +public final class CurrentUser { + private CurrentUser() {} + + public record Principal(long userId) {} + + public static Long optional() { + Authentication auth = SecurityContextHolder.getContext().getAuthentication(); + return auth != null && auth.getPrincipal() instanceof Principal principal + ? principal.userId() + : null; + } + + public static long required() { + Long id = optional(); + if (id == null) throw new BusinessException(401, "UNAUTHORIZED", "请先登录"); + return id; + } +} diff --git a/community-security/src/main/java/com/linkerbot/community/security/SecurityConfiguration.java b/community-security/src/main/java/com/linkerbot/community/security/SecurityConfiguration.java new file mode 100644 index 0000000..4438d04 --- /dev/null +++ b/community-security/src/main/java/com/linkerbot/community/security/SecurityConfiguration.java @@ -0,0 +1,84 @@ +package com.linkerbot.community.security; + +import com.fasterxml.jackson.databind.ObjectMapper; +import com.linkerbot.community.common.*; + +import org.springframework.boot.web.servlet.FilterRegistrationBean; +import org.springframework.context.annotation.*; +import org.springframework.http.HttpMethod; +import org.springframework.security.config.annotation.web.builders.HttpSecurity; +import org.springframework.security.config.http.SessionCreationPolicy; +import org.springframework.security.web.SecurityFilterChain; +import org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter; + +@Configuration +public class SecurityConfiguration { + @Bean + public FilterRegistrationBean disableServletRegistration( + BearerTokenFilter filter) { + FilterRegistrationBean registration = + new FilterRegistrationBean<>(filter); + registration.setEnabled(false); + return registration; + } + + @Bean + public SecurityFilterChain securityFilterChain( + HttpSecurity http, BearerTokenFilter tokenFilter, ObjectMapper json) throws Exception { + http.csrf(csrf -> csrf.disable()) + .sessionManagement( + session -> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS)) + .formLogin(form -> form.disable()) + .httpBasic(basic -> basic.disable()) + .logout(logout -> logout.disable()) + .authorizeHttpRequests( + auth -> + auth.requestMatchers( + "/api/auth/captcha", + "/api/auth/login", + "/v3/api-docs/**", + "/swagger-ui/**", + "/swagger-ui.html", + "/error") + .permitAll() + .requestMatchers( + HttpMethod.GET, + "/api/community/**", + "/api/project-types") + .permitAll() + .requestMatchers(HttpMethod.OPTIONS, "/**") + .permitAll() + .anyRequest() + .authenticated()) + .exceptionHandling( + errors -> + errors.authenticationEntryPoint( + (request, response, error) -> { + response.setStatus(401); + response.setContentType( + "application/json;charset=UTF-8"); + json.writeValue( + response.getOutputStream(), + ApiResponse.failure( + new BusinessException( + 401, + "UNAUTHORIZED", + "请先登录"))); + }) + .accessDeniedHandler( + (request, response, error) -> { + response.setStatus(403); + response.setContentType( + "application/json;charset=UTF-8"); + json.writeValue( + response.getOutputStream(), + ApiResponse.failure( + new BusinessException( + 403, + "FORBIDDEN", + "无权访问"))); + })) + .addFilterBefore(tokenFilter, UsernamePasswordAuthenticationFilter.class); + return http.build(); + } +} diff --git a/community-security/src/main/java/com/linkerbot/community/security/TokenService.java b/community-security/src/main/java/com/linkerbot/community/security/TokenService.java new file mode 100644 index 0000000..394172e --- /dev/null +++ b/community-security/src/main/java/com/linkerbot/community/security/TokenService.java @@ -0,0 +1,40 @@ +package com.linkerbot.community.security; + +import com.github.benmanes.caffeine.cache.Cache; +import com.github.benmanes.caffeine.cache.Caffeine; +import com.linkerbot.community.service.config.CommunityProperties; + +import org.springframework.stereotype.Service; + +import java.security.SecureRandom; +import java.util.Base64; + +@Service +public class TokenService { + private final Cache sessions; + private final SecureRandom random = new SecureRandom(); + + public TokenService(CommunityProperties config) { + sessions = + Caffeine.newBuilder() + .maximumSize(10000) + .expireAfterWrite(config.getTokenTtl()) + .build(); + } + + public String issue(long userId) { + byte[] bytes = new byte[32]; + random.nextBytes(bytes); + String token = Base64.getUrlEncoder().withoutPadding().encodeToString(bytes); + sessions.put(token, userId); + return token; + } + + public Long resolve(String token) { + return sessions.getIfPresent(token); + } + + public void revoke(String token) { + if (token != null) sessions.invalidate(token); + } +} diff --git a/community-security/src/test/java/com/linkerbot/community/security/SessionTest.java b/community-security/src/test/java/com/linkerbot/community/security/SessionTest.java new file mode 100644 index 0000000..428775c --- /dev/null +++ b/community-security/src/test/java/com/linkerbot/community/security/SessionTest.java @@ -0,0 +1,45 @@ +package com.linkerbot.community.security; + +import static org.assertj.core.api.Assertions.*; + +import com.linkerbot.community.common.BusinessException; +import com.linkerbot.community.service.config.CommunityProperties; + +import org.junit.jupiter.api.Test; + +import java.time.Duration; + +class SessionTest { + @Test + void expiredCaptchaAndTokenCannotBeUsed() throws Exception { + CommunityProperties properties = new CommunityProperties(); + properties.setCaptchaTtl(Duration.ofMillis(1)); + properties.setTokenTtl(Duration.ofMillis(1)); + CaptchaService captcha = + new CaptchaService(properties) { + @Override + protected String generateAnswer() { + return "ABCDE"; + } + }; + String code = captcha.issue().captchaCode(); + TokenService tokens = new TokenService(properties); + String token = tokens.issue(1L); + Thread.sleep(20); + assertThatThrownBy(() -> captcha.verify(code, "ABCDE")) + .isInstanceOf(BusinessException.class); + assertThat(tokens.resolve(token)).isNull(); + } + + @Test + void tokensAreRandomAndRevocable() { + TokenService tokens = new TokenService(new CommunityProperties()); + String a = tokens.issue(1L); + String b = tokens.issue(1L); + assertThat(a).isNotEqualTo(b); + assertThat(tokens.resolve(a)).isEqualTo(1L); + tokens.revoke(a); + assertThat(tokens.resolve(a)).isNull(); + assertThat(tokens.resolve(b)).isEqualTo(1L); + } +} diff --git a/community-service/pom.xml b/community-service/pom.xml new file mode 100644 index 0000000..1759b76 --- /dev/null +++ b/community-service/pom.xml @@ -0,0 +1,30 @@ + + + 4.0.0 + + com.linkerbot + community + 0.0.1-SNAPSHOT + + community-service + + + com.linkerbot + community-common + ${project.version} + + + com.linkerbot + community-bean + ${project.version} + + + com.baomidou + mybatis-plus-spring-boot3-starter + + + com.baomidou + mybatis-plus-jsqlparser + + + diff --git a/community-service/src/main/java/com/linkerbot/community/service/FileService.java b/community-service/src/main/java/com/linkerbot/community/service/FileService.java new file mode 100644 index 0000000..b3fe5a6 --- /dev/null +++ b/community-service/src/main/java/com/linkerbot/community/service/FileService.java @@ -0,0 +1,264 @@ +package com.linkerbot.community.service; + +import com.linkerbot.community.bean.Contracts.*; +import com.linkerbot.community.bean.entity.Project; +import com.linkerbot.community.bean.entity.User; +import com.linkerbot.community.common.*; +import com.linkerbot.community.service.config.CommunityProperties; +import com.linkerbot.community.service.gitea.*; + +import lombok.RequiredArgsConstructor; + +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import org.springframework.stereotype.Service; +import org.springframework.web.multipart.MultipartFile; + +import java.io.IOException; +import java.nio.ByteBuffer; +import java.nio.charset.*; +import java.util.*; + +@Service +@RequiredArgsConstructor +public class FileService { + private static final Logger log = LoggerFactory.getLogger(FileService.class); + private final ProjectService projects; + private final UserService users; + private final GiteaClient gitea; + private final CommunityProperties config; + + public TreeView ownerTree(long userId, String code, String path, String commitSha) { + Project project = projects.readyOwner(userId, code); + String sha = + commitSha == null + ? gitea.head(projects.repository(project)) + : FilePaths.sha(commitSha); + return tree(project, sha, path); + } + + public TreeView communityTree(String code, String path) { + Project project = projects.published(code); + return tree(project, project.getPublishedCommitSha(), path); + } + + private TreeView tree(Project project, String sha, String path) { + String normalized = FilePaths.directory(path); + return new TreeView( + sha, normalized, gitea.tree(projects.repository(project), sha, normalized)); + } + + public GiteaClient.StoredFile ownerFile( + long userId, String code, String path, String commitSha) { + Project project = projects.readyOwner(userId, code); + String sha = + commitSha == null + ? gitea.head(projects.repository(project)) + : FilePaths.sha(commitSha); + return gitea.file(projects.repository(project), sha, FilePaths.file(path)); + } + + public FileView ownerFileView(long userId, String code, String path, String commitSha) { + Project project = projects.readyOwner(userId, code); + String sha = + commitSha == null + ? gitea.head(projects.repository(project)) + : FilePaths.sha(commitSha); + return fileView(sha, gitea.file(projects.repository(project), sha, FilePaths.file(path))); + } + + public GiteaClient.StoredFile communityFile(String code, String path) { + Project project = projects.published(code); + return gitea.file( + projects.repository(project), + project.getPublishedCommitSha(), + FilePaths.file(path)); + } + + public FileView communityFileView(String code, String path) { + Project project = projects.published(code); + return fileView( + project.getPublishedCommitSha(), + gitea.file( + projects.repository(project), + project.getPublishedCommitSha(), + FilePaths.file(path))); + } + + private String text(byte[] bytes) { + if (bytes.length > config.getMaxTextBytes()) return null; + for (byte value : bytes) if (value == 0) return null; + try { + return StandardCharsets.UTF_8 + .newDecoder() + .onMalformedInput(CodingErrorAction.REPORT) + .onUnmappableCharacter(CodingErrorAction.REPORT) + .decode(ByteBuffer.wrap(bytes)) + .toString(); + } catch (CharacterCodingException error) { + return null; + } + } + + private FileView fileView(String sha, GiteaClient.StoredFile file) { + String content = text(file.bytes()); + return new FileView( + sha, + file.path(), + file.blobSha(), + file.bytes().length, + content == null ? "base64" : "utf-8", + content == null ? Base64.getEncoder().encodeToString(file.bytes()) : content, + content != null); + } + + private void size(long bytes, long max) { + if (bytes > max) throw new BusinessException(413, "FILE_TOO_LARGE", "文件或请求超过大小限制"); + } + + private String expected(Project project, String expectedSha) { + String sha = FilePaths.sha(expectedSha); + if (!sha.equals(gitea.head(projects.repository(project)))) + throw BusinessException.conflict("工作区版本已变化,请刷新后重新提交"); + return sha; + } + + public CommitView commit(long userId, String code, CommitInput input) { + return projects.write( + userId, + code, + project -> { + projects.ready(project); + String sha = expected(project, input.expectedCommitSha()); + GiteaClient.Repository repo = projects.repository(project); + List changes = new ArrayList<>(); + Set paths = new HashSet<>(); + long bytes = 0; + for (FileChange item : input.changes()) { + String path = FilePaths.file(item.path()); + if (item.action() == ChangeAction.CREATE_DIRECTORY) path += "/.gitkeep"; + if (!paths.add(path)) throw BusinessException.badRequest("一次提交不能重复修改同一路径"); + switch (item.action()) { + case CREATE_FILE, CREATE_DIRECTORY -> { + String content = + item.action() == ChangeAction.CREATE_DIRECTORY + ? "" + : item.content(); + if (content == null) + throw BusinessException.badRequest("新文件必须提供 content"); + byte[] data = content.getBytes(StandardCharsets.UTF_8); + size(data.length, config.getMaxTextBytes()); + changes.add(new GiteaClient.Change("create", path, null, data)); + bytes += data.length; + } + case UPDATE_FILE -> { + if (item.content() == null) + throw BusinessException.badRequest("修改文件必须提供 content"); + GiteaClient.StoredFile old = gitea.file(repo, sha, path); + if (text(old.bytes()) == null) + throw BusinessException.badRequest("该文件不支持在线文本编辑,请通过上传替换"); + byte[] data = item.content().getBytes(StandardCharsets.UTF_8); + size(data.length, config.getMaxTextBytes()); + changes.add( + new GiteaClient.Change( + "update", path, old.blobSha(), data)); + bytes += data.length; + } + case DELETE_FILE -> { + GiteaClient.StoredFile old = gitea.file(repo, sha, path); + changes.add( + new GiteaClient.Change( + "delete", path, old.blobSha(), null)); + } + } + } + size(bytes, config.getMaxRequestBytes()); + User user = users.require(userId); + CommitView result = + gitea.commit( + repo, + changes, + input.message(), + user.getNickname(), + user.getUserCode()); + log.info( + "文件提交 projectCode={} commitSha={} fileCount={}", + code, + result.commitSha(), + changes.size()); + return result; + }); + } + + public CommitView upload( + long userId, + String code, + String expectedSha, + String message, + String directory, + List files, + List paths) { + if (message == null || message.isBlank() || message.length() > 1000) + throw BusinessException.badRequest("提交说明不合法"); + if (files == null + || files.isEmpty() + || files.size() > 500 + || (paths != null && paths.size() != files.size())) + throw BusinessException.badRequest("文件和路径数量不合法"); + String prefix = FilePaths.directory(directory); + return projects.write( + userId, + code, + project -> { + projects.ready(project); + String sha = expected(project, expectedSha); + GiteaClient.Repository repo = projects.repository(project); + List changes = new ArrayList<>(); + Set unique = new HashSet<>(); + long bytes = 0; + for (int i = 0; i < files.size(); i++) { + MultipartFile file = files.get(i); + String relative = + FilePaths.file( + paths == null ? file.getOriginalFilename() : paths.get(i)); + String path = + FilePaths.file( + prefix.isEmpty() ? relative : prefix + "/" + relative); + if (!unique.add(path)) throw BusinessException.badRequest("上传路径不能重复"); + size(file.getSize(), config.getMaxFileBytes()); + bytes += file.getSize(); + size(bytes, config.getMaxRequestBytes()); + byte[] data; + try { + data = file.getBytes(); + } catch (IOException error) { + throw BusinessException.badRequest("读取上传文件失败"); + } + String blob = null; + try { + blob = gitea.file(repo, sha, path).blobSha(); + } catch (GiteaFailure missing) { + if (missing.status() != 404) throw missing; + } + changes.add( + new GiteaClient.Change( + blob == null ? "create" : "update", path, blob, data)); + } + User user = users.require(userId); + CommitView result = + gitea.commit( + repo, changes, message, user.getNickname(), user.getUserCode()); + log.info( + "文件上传 projectCode={} commitSha={} fileCount={}", + code, + result.commitSha(), + changes.size()); + return result; + }); + } + + public PageResponse history(long userId, String code, long page, long size) { + ProjectService.pageCheck(page, size); + return gitea.history(projects.repository(projects.readyOwner(userId, code)), page, size); + } +} diff --git a/community-service/src/main/java/com/linkerbot/community/service/InteractionService.java b/community-service/src/main/java/com/linkerbot/community/service/InteractionService.java new file mode 100644 index 0000000..8359a40 --- /dev/null +++ b/community-service/src/main/java/com/linkerbot/community/service/InteractionService.java @@ -0,0 +1,106 @@ +package com.linkerbot.community.service; + +import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper; +import com.baomidou.mybatisplus.core.conditions.update.LambdaUpdateWrapper; +import com.baomidou.mybatisplus.extension.plugins.pagination.Page; +import com.linkerbot.community.bean.Contracts.*; +import com.linkerbot.community.bean.entity.*; +import com.linkerbot.community.common.*; +import com.linkerbot.community.service.mapper.*; + +import lombok.RequiredArgsConstructor; + +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import org.springframework.dao.DuplicateKeyException; +import org.springframework.stereotype.Service; + +@Service +@RequiredArgsConstructor +public class InteractionService { + private static final Logger log = LoggerFactory.getLogger(InteractionService.class); + private final ProjectService projects; + private final UserService users; + private final CommentMapper comments; + private final LikeMapper likes; + + public PageResponse list(String code, long page, long size) { + ProjectService.pageCheck(page, size); + Project project = projects.published(code); + Page result = + comments.selectPage( + new Page<>(page, size), + new LambdaQueryWrapper() + .eq(ProjectComment::getProjectId, project.getId()) + .eq(ProjectComment::getDeleted, false) + .orderByDesc(ProjectComment::getCreatedAt) + .orderByDesc(ProjectComment::getId)); + return new PageResponse<>( + result.getRecords().stream().map(this::view).toList(), + page, + size, + result.getTotal()); + } + + private CommentView view(ProjectComment comment) { + return new CommentView( + comment.getCommentCode(), + users.publicView(comment.getUserId()), + comment.getContent(), + comment.getCreatedAt()); + } + + public CommentView comment(long userId, String code, CommentInput input) { + users.require(userId); + Project project = projects.published(code); + ProjectComment comment = new ProjectComment(); + comment.setCommentCode(Codes.next()); + comment.setProjectId(project.getId()); + comment.setUserId(userId); + comment.setContent(input.content().trim()); + comment.setDeleted(false); + comment.setCreatedAt(ProjectService.now()); + comment.setUpdatedAt(comment.getCreatedAt()); + comments.insert(comment); + log.info("新增评论 projectCode={} commentCode={}", code, comment.getCommentCode()); + return view(comment); + } + + public void deleteComment(long userId, String code) { + int count = + comments.update( + null, + new LambdaUpdateWrapper() + .eq(ProjectComment::getCommentCode, code) + .eq(ProjectComment::getUserId, userId) + .eq(ProjectComment::getDeleted, false) + .set(ProjectComment::getDeleted, true) + .set(ProjectComment::getUpdatedAt, ProjectService.now())); + if (count == 0) throw BusinessException.notFound(); + log.info("删除评论 commentCode={}", code); + } + + public void like(long userId, String code) { + users.require(userId); + Project project = projects.published(code); + ProjectLike like = new ProjectLike(); + like.setProjectId(project.getId()); + like.setUserId(userId); + like.setCreatedAt(ProjectService.now()); + try { + likes.insert(like); + } catch (DuplicateKeyException duplicate) { + return; + } + log.info("点赞 projectCode={}", code); + } + + public void unlike(long userId, String code) { + Project project = projects.published(code); + likes.delete( + new LambdaQueryWrapper() + .eq(ProjectLike::getProjectId, project.getId()) + .eq(ProjectLike::getUserId, userId)); + log.info("取消点赞 projectCode={}", code); + } +} diff --git a/community-service/src/main/java/com/linkerbot/community/service/ProjectLocks.java b/community-service/src/main/java/com/linkerbot/community/service/ProjectLocks.java new file mode 100644 index 0000000..3b9c252 --- /dev/null +++ b/community-service/src/main/java/com/linkerbot/community/service/ProjectLocks.java @@ -0,0 +1,45 @@ +package com.linkerbot.community.service; + +import com.linkerbot.community.common.BusinessException; + +import org.springframework.stereotype.Component; + +import java.util.Set; +import java.util.concurrent.ConcurrentHashMap; +import java.util.concurrent.locks.ReentrantLock; +import java.util.function.Supplier; + +@Component +public class ProjectLocks { + private final ReentrantLock[] locks = new ReentrantLock[128]; + private final Set uncertain = ConcurrentHashMap.newKeySet(); + + public ProjectLocks() { + for (int i = 0; i < locks.length; i++) locks[i] = new ReentrantLock(); + } + + public T write(String code, Supplier action) { + return serial( + code, + () -> { + if (uncertain.contains(code)) + throw new BusinessException( + 409, "REMOTE_RESULT_UNKNOWN", "上次仓库写入结果待人工核对,暂不能继续写入"); + return action.get(); + }); + } + + public T serial(String code, Supplier action) { + ReentrantLock lock = locks[Math.floorMod(code.hashCode(), locks.length)]; + lock.lock(); + try { + return action.get(); + } finally { + lock.unlock(); + } + } + + public void markUncertain(String code) { + uncertain.add(code); + } +} diff --git a/community-service/src/main/java/com/linkerbot/community/service/ProjectService.java b/community-service/src/main/java/com/linkerbot/community/service/ProjectService.java new file mode 100644 index 0000000..66d110d --- /dev/null +++ b/community-service/src/main/java/com/linkerbot/community/service/ProjectService.java @@ -0,0 +1,389 @@ +package com.linkerbot.community.service; + +import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper; +import com.baomidou.mybatisplus.extension.plugins.pagination.Page; +import com.linkerbot.community.bean.Contracts.*; +import com.linkerbot.community.bean.entity.*; +import com.linkerbot.community.common.*; +import com.linkerbot.community.service.config.CommunityProperties; +import com.linkerbot.community.service.gitea.*; +import com.linkerbot.community.service.mapper.*; + +import lombok.RequiredArgsConstructor; + +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import org.springframework.stereotype.Service; + +import java.time.Clock; +import java.time.LocalDateTime; +import java.util.*; +import java.util.function.Function; + +@Service +@RequiredArgsConstructor +public class ProjectService { + private static final Logger log = LoggerFactory.getLogger(ProjectService.class); + private final ProjectMapper projects; + private final LikeMapper likes; + private final CommentMapper comments; + private final UserService users; + private final GiteaClient gitea; + private final CommunityProperties config; + private final ProjectLocks locks; + + public static LocalDateTime now() { + return LocalDateTime.now(Clock.systemUTC()); + } + + public static void pageCheck(long page, long size) { + if (page < 1 || page > 100000 || size < 1 || size > 100) + throw BusinessException.badRequest("分页参数不合法"); + } + + public List types() { + return config.getTypes().entrySet().stream() + .map(e -> new TypeView(e.getKey(), e.getValue())) + .toList(); + } + + private void validateInput(ProjectInput input) { + if (!config.getTypes().containsKey(input.projectType())) + throw BusinessException.badRequest("项目类型不在可选列表中"); + } + + public Project owner(long userId, String code) { + Project project = + projects.selectOne( + new LambdaQueryWrapper() + .eq(Project::getProjectCode, code) + .eq(Project::getOwnerUserId, userId) + .eq(Project::getDeleted, false)); + if (project == null) throw BusinessException.notFound(); + return project; + } + + public Project readyOwner(long userId, String code) { + Project project = owner(userId, code); + ready(project); + return project; + } + + public void ready(Project project) { + if (!"READY".equals(project.getRepoStatus())) + throw BusinessException.conflict("仓库尚未就绪,请核对项目创建状态"); + } + + public Project published(String code) { + Project project = + projects.selectOne( + new LambdaQueryWrapper() + .eq(Project::getProjectCode, code) + .eq(Project::getDeleted, false) + .eq(Project::getRepoStatus, "READY") + .eq(Project::getPublishStatus, "PUBLISHED")); + if (project == null) throw BusinessException.notFound(); + return project; + } + + public GiteaClient.Repository repository(Project project) { + return new GiteaClient.Repository( + project.getGiteaRepoId(), project.getGiteaOwner(), project.getGiteaRepoName()); + } + + public ProjectView view(Project project, Long currentUser) { + Project source = + project.getSourceProjectId() == null + ? null + : projects.selectById(project.getSourceProjectId()); + long likeCount = + likes.selectCount( + new LambdaQueryWrapper() + .eq(ProjectLike::getProjectId, project.getId())); + long commentCount = + comments.selectCount( + new LambdaQueryWrapper() + .eq(ProjectComment::getProjectId, project.getId()) + .eq(ProjectComment::getDeleted, false)); + boolean liked = + currentUser != null + && likes.selectCount( + new LambdaQueryWrapper() + .eq(ProjectLike::getProjectId, project.getId()) + .eq(ProjectLike::getUserId, currentUser)) + > 0; + return new ProjectView( + project.getProjectCode(), + project.getName(), + project.getDescription(), + project.getProjectType(), + users.publicView(project.getOwnerUserId()), + project.getRepoStatus(), + project.getPublishStatus(), + project.getPublishedCommitSha(), + project.getPublishedAt(), + source == null ? null : source.getProjectCode(), + project.getSourceCommitSha(), + likeCount, + commentCount, + liked, + project.getCreatedAt(), + project.getUpdatedAt()); + } + + public PageResponse list( + Long ownerId, String type, String keyword, long page, long size, Long currentUser) { + pageCheck(page, size); + LambdaQueryWrapper query = + new LambdaQueryWrapper().eq(Project::getDeleted, false); + if (ownerId == null) + query.eq(Project::getRepoStatus, "READY") + .eq(Project::getPublishStatus, "PUBLISHED") + .orderByDesc(Project::getPublishedAt); + else query.eq(Project::getOwnerUserId, ownerId).orderByDesc(Project::getCreatedAt); + if (type != null && !type.isBlank()) query.eq(Project::getProjectType, type); + if (keyword != null && !keyword.isBlank()) { + if (keyword.length() > 200) throw BusinessException.badRequest("关键词过长"); + query.and( + q -> + q.like(Project::getName, keyword) + .or() + .like(Project::getDescription, keyword)); + } + query.orderByDesc(Project::getId); + Page result = projects.selectPage(new Page<>(page, size), query); + return new PageResponse<>( + result.getRecords().stream().map(p -> view(p, currentUser)).toList(), + page, + size, + result.getTotal()); + } + + private Project initialize(long userId, ProjectInput input, Project source) { + validateInput(input); + Project project = new Project(); + project.setProjectCode(Codes.next()); + project.setOwnerUserId(userId); + project.setName(input.name().trim()); + project.setDescription(input.description() == null ? "" : input.description()); + project.setProjectType(input.projectType()); + project.setGiteaOwner(config.getGitea().getOwner()); + project.setGiteaRepoName("p_" + project.getProjectCode()); + project.setRepoStatus("CREATING"); + project.setPublishStatus("UNPUBLISHED"); + project.setDeleted(false); + project.setCreatedAt(now()); + project.setUpdatedAt(project.getCreatedAt()); + if (source != null) { + project.setSourceProjectId(source.getId()); + project.setSourceCommitSha(source.getPublishedCommitSha()); + } + projects.insert(project); + return project; + } + + public ProjectView create(long userId, ProjectInput input) { + users.require(userId); + Project project = initialize(userId, input, null); + return locks.write(project.getProjectCode(), () -> createRemote(project, null)); + } + + public ProjectView fork(long userId, String sourceCode, ForkInput input) { + User user = users.require(userId); + Project source = published(sourceCode); + if (!source.getPublishedCommitSha().equals(FilePaths.sha(input.publishedCommitSha()))) + throw BusinessException.conflict("社区版本已更新,请刷新后 Fork"); + ProjectInput data = + new ProjectInput(input.name(), source.getDescription(), source.getProjectType()); + Project project = initialize(userId, data, source); + return locks.write( + project.getProjectCode(), + () -> createRemote(project, new ForkContext(source, user))); + } + + private record ForkContext(Project source, User user) {} + + private ProjectView createRemote(Project project, ForkContext fork) { + try { + GiteaClient.Repository repo = + gitea.createRepository(project.getGiteaRepoName(), fork == null); + project.setGiteaRepoId(repo.id()); + if (fork != null) + copySnapshot( + repository(fork.source()), + fork.source().getPublishedCommitSha(), + repo, + fork.user()); + project.setRepoStatus("READY"); + project.setUpdatedAt(now()); + projects.updateById(project); + log.info("仓库创建完成 projectCode={} fork={}", project.getProjectCode(), fork != null); + return view(project, project.getOwnerUserId()); + } catch (GiteaFailure error) { + project.setRepoStatus(error.uncertain() ? "CREATING" : "FAILED"); + project.setUpdatedAt(now()); + projects.updateById(project); + if (error.uncertain()) locks.markUncertain(project.getProjectCode()); + log.warn( + "仓库创建异常 projectCode={} code={} uncertain={}", + project.getProjectCode(), + error.code(), + error.uncertain()); + throw new BusinessException( + error.status(), + error.code(), + error.getMessage(), + Map.of("projectCode", project.getProjectCode())); + } catch (BusinessException error) { + project.setRepoStatus("FAILED"); + project.setUpdatedAt(now()); + projects.updateById(project); + log.warn("项目初始化拒绝 projectCode={} code={}", project.getProjectCode(), error.code()); + throw new BusinessException( + error.status(), + error.code(), + error.getMessage(), + Map.of("projectCode", project.getProjectCode())); + } catch (RuntimeException error) { + log.error( + "仓库创建或回写异常 projectCode={} type={}", + project.getProjectCode(), + error.getClass().getSimpleName()); + throw new BusinessException( + 500, + "PROJECT_INITIALIZATION_ERROR", + "项目初始化未完成,请按项目编码人工核对", + Map.of("projectCode", project.getProjectCode())); + } + } + + private void copySnapshot( + GiteaClient.Repository source, String sha, GiteaClient.Repository target, User user) { + Deque directories = new ArrayDeque<>(); + directories.add(""); + List batch = new ArrayList<>(); + long batchBytes = 0; + while (!directories.isEmpty()) { + for (TreeEntry entry : gitea.tree(source, sha, directories.removeFirst())) { + FilePaths.file(entry.path()); + if (entry.type().equals("dir")) { + directories.add(entry.path()); + continue; + } + if (!entry.type().equals("file")) + throw BusinessException.badRequest("Fork 暂不支持符号链接或子模块"); + GiteaClient.StoredFile file = gitea.file(source, sha, entry.path()); + if (!batch.isEmpty() + && (batchBytes + file.bytes().length > config.getMaxRequestBytes() + || batch.size() >= 100)) { + gitea.commit( + target, + batch, + "Fork community snapshot", + user.getNickname(), + user.getUserCode()); + batch.clear(); + batchBytes = 0; + } + batch.add(new GiteaClient.Change("create", file.path(), null, file.bytes())); + batchBytes += file.bytes().length; + } + } + if (!batch.isEmpty()) + gitea.commit( + target, + batch, + "Fork community snapshot", + user.getNickname(), + user.getUserCode()); + else if (batchBytes == 0) throw BusinessException.badRequest("不能 Fork 空仓库"); + } + + public T write(long userId, String code, Function action) { + return locks.write( + code, + () -> { + Project project = owner(userId, code); + try { + return action.apply(project); + } catch (GiteaFailure error) { + if (error.uncertain()) locks.markUncertain(code); + log.warn( + "仓库访问异常 projectCode={} code={} uncertain={}", + code, + error.code(), + error.uncertain()); + throw new BusinessException( + error.status(), + error.code(), + error.getMessage(), + Map.of("projectCode", code)); + } + }); + } + + public ProjectView update(long userId, String code, ProjectInput input) { + validateInput(input); + return metadata( + userId, + code, + project -> { + project.setName(input.name().trim()); + project.setDescription(input.description() == null ? "" : input.description()); + project.setProjectType(input.projectType()); + project.setUpdatedAt(now()); + projects.updateById(project); + return view(project, userId); + }); + } + + public void delete(long userId, String code) { + metadata( + userId, + code, + project -> { + project.setDeleted(true); + project.setPublishStatus("UNPUBLISHED"); + project.setUpdatedAt(now()); + projects.updateById(project); + log.info("删除项目 projectCode={}", code); + return null; + }); + } + + public ProjectView publish(long userId, String code, String expectedSha) { + return write( + userId, + code, + project -> { + ready(project); + String head = gitea.head(repository(project)); + if (!head.equals(FilePaths.sha(expectedSha))) + throw BusinessException.conflict("工作区版本已变化,请刷新后发布"); + project.setPublishedCommitSha(head); + project.setPublishStatus("PUBLISHED"); + project.setPublishedAt(now()); + project.setUpdatedAt(now()); + projects.updateById(project); + log.info("发布社区 projectCode={} commitSha={}", code, head); + return view(project, userId); + }); + } + + public void withdraw(long userId, String code) { + metadata( + userId, + code, + project -> { + project.setPublishStatus("UNPUBLISHED"); + project.setUpdatedAt(now()); + projects.updateById(project); + log.info("撤回社区 projectCode={}", code); + return null; + }); + } + + private T metadata(long userId, String code, Function action) { + return locks.serial(code, () -> action.apply(owner(userId, code))); + } +} diff --git a/community-service/src/main/java/com/linkerbot/community/service/UserService.java b/community-service/src/main/java/com/linkerbot/community/service/UserService.java new file mode 100644 index 0000000..d4fadcc --- /dev/null +++ b/community-service/src/main/java/com/linkerbot/community/service/UserService.java @@ -0,0 +1,70 @@ +package com.linkerbot.community.service; + +import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper; +import com.linkerbot.community.bean.Contracts.*; +import com.linkerbot.community.bean.entity.User; +import com.linkerbot.community.common.*; +import com.linkerbot.community.service.mapper.UserMapper; + +import lombok.RequiredArgsConstructor; + +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import org.springframework.dao.DuplicateKeyException; +import org.springframework.stereotype.Service; + +import java.time.Clock; +import java.time.LocalDateTime; +import java.util.Locale; + +@Service +@RequiredArgsConstructor +public class UserService { + private static final Logger log = LoggerFactory.getLogger(UserService.class); + private final UserMapper users; + + public User login(String email) { + String normalized = email.trim().toLowerCase(Locale.ROOT); + User user = users.selectOne(new LambdaQueryWrapper().eq(User::getEmail, normalized)); + if (user == null) { + User candidate = new User(); + candidate.setUserCode(Codes.next()); + candidate.setEmail(normalized); + candidate.setNickname("用户_" + candidate.getUserCode().substring(0, 8)); + candidate.setStatus("ACTIVE"); + candidate.setCreatedAt(LocalDateTime.now(Clock.systemUTC())); + candidate.setUpdatedAt(candidate.getCreatedAt()); + try { + users.insert(candidate); + user = candidate; + log.info("创建用户 userCode={}", user.getUserCode()); + } catch (DuplicateKeyException duplicate) { + user = + users.selectOne( + new LambdaQueryWrapper().eq(User::getEmail, normalized)); + } + } + if (user == null || !"ACTIVE".equals(user.getStatus())) + throw new BusinessException(403, "ACCOUNT_DISABLED", "账号不可用"); + log.info("用户登录 userCode={}", user.getUserCode()); + return user; + } + + public User require(long id) { + User user = users.selectById(id); + if (user == null || !"ACTIVE".equals(user.getStatus())) + throw new BusinessException(401, "UNAUTHORIZED", "请重新登录"); + return user; + } + + public UserView view(User user) { + return new UserView(user.getUserCode(), user.getNickname(), user.getEmail()); + } + + public PublicUser publicView(long id) { + User user = users.selectById(id); + return user == null + ? new PublicUser(null, "已删除用户") + : new PublicUser(user.getUserCode(), user.getNickname()); + } +} diff --git a/community-service/src/main/java/com/linkerbot/community/service/config/CommunityProperties.java b/community-service/src/main/java/com/linkerbot/community/service/config/CommunityProperties.java new file mode 100644 index 0000000..db7af23 --- /dev/null +++ b/community-service/src/main/java/com/linkerbot/community/service/config/CommunityProperties.java @@ -0,0 +1,44 @@ +package com.linkerbot.community.service.config; + +import lombok.Getter; +import lombok.Setter; + +import org.springframework.boot.context.properties.ConfigurationProperties; +import org.springframework.stereotype.Component; + +import java.time.Duration; +import java.util.LinkedHashMap; +import java.util.Map; + +@Getter +@Setter +@Component +@ConfigurationProperties(prefix = "community") +public class CommunityProperties { + private Map types = defaultTypes(); + private long maxTextBytes = 1024 * 1024; + private long maxFileBytes = 10 * 1024 * 1024; + private long maxRequestBytes = 50 * 1024 * 1024; + private Duration captchaTtl = Duration.ofMinutes(2); + private Duration tokenTtl = Duration.ofHours(24); + private Gitea gitea = new Gitea(); + + private static Map defaultTypes() { + Map types = new LinkedHashMap<>(); + types.put("GENERAL", "通用"); + types.put("HUMANOID", "人形"); + types.put("QUADRUPED", "四足"); + types.put("WHEELED", "轮式"); + return types; + } + + @Getter + @Setter + public static class Gitea { + private String baseUrl = "http://localhost:3000"; + private String owner = "community"; + private String token = ""; + private Duration connectTimeout = Duration.ofSeconds(5); + private Duration requestTimeout = Duration.ofSeconds(30); + } +} diff --git a/community-service/src/main/java/com/linkerbot/community/service/config/MybatisConfiguration.java b/community-service/src/main/java/com/linkerbot/community/service/config/MybatisConfiguration.java new file mode 100644 index 0000000..329b3d2 --- /dev/null +++ b/community-service/src/main/java/com/linkerbot/community/service/config/MybatisConfiguration.java @@ -0,0 +1,18 @@ +package com.linkerbot.community.service.config; + +import com.baomidou.mybatisplus.annotation.DbType; +import com.baomidou.mybatisplus.extension.plugins.MybatisPlusInterceptor; +import com.baomidou.mybatisplus.extension.plugins.inner.PaginationInnerInterceptor; + +import org.springframework.context.annotation.Bean; +import org.springframework.context.annotation.Configuration; + +@Configuration +public class MybatisConfiguration { + @Bean + public MybatisPlusInterceptor paginationInterceptor() { + MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor(); + interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL)); + return interceptor; + } +} diff --git a/community-service/src/main/java/com/linkerbot/community/service/gitea/GiteaClient.java b/community-service/src/main/java/com/linkerbot/community/service/gitea/GiteaClient.java new file mode 100644 index 0000000..366db71 --- /dev/null +++ b/community-service/src/main/java/com/linkerbot/community/service/gitea/GiteaClient.java @@ -0,0 +1,31 @@ +package com.linkerbot.community.service.gitea; + +import com.linkerbot.community.bean.Contracts.*; +import com.linkerbot.community.common.PageResponse; + +import java.util.List; + +public interface GiteaClient { + record Repository(long id, String owner, String name) {} + + record StoredFile(String path, String blobSha, byte[] bytes) {} + + record Change(String operation, String path, String blobSha, byte[] bytes) {} + + Repository createRepository(String name, boolean initialize); + + String head(Repository repository); + + List tree(Repository repository, String sha, String path); + + StoredFile file(Repository repository, String sha, String path); + + CommitView commit( + Repository repository, + List changes, + String message, + String authorName, + String authorCode); + + PageResponse history(Repository repository, long page, long size); +} diff --git a/community-service/src/main/java/com/linkerbot/community/service/gitea/GiteaFailure.java b/community-service/src/main/java/com/linkerbot/community/service/gitea/GiteaFailure.java new file mode 100644 index 0000000..ce9b6a4 --- /dev/null +++ b/community-service/src/main/java/com/linkerbot/community/service/gitea/GiteaFailure.java @@ -0,0 +1,16 @@ +package com.linkerbot.community.service.gitea; + +import com.linkerbot.community.common.BusinessException; + +public class GiteaFailure extends BusinessException { + private final boolean uncertain; + + public GiteaFailure(int status, String code, String message, boolean uncertain) { + super(status, code, message); + this.uncertain = uncertain; + } + + public boolean uncertain() { + return uncertain; + } +} diff --git a/community-service/src/main/java/com/linkerbot/community/service/gitea/RestGiteaClient.java b/community-service/src/main/java/com/linkerbot/community/service/gitea/RestGiteaClient.java new file mode 100644 index 0000000..d218869 --- /dev/null +++ b/community-service/src/main/java/com/linkerbot/community/service/gitea/RestGiteaClient.java @@ -0,0 +1,249 @@ +package com.linkerbot.community.service.gitea; + +import com.fasterxml.jackson.databind.JsonNode; +import com.fasterxml.jackson.databind.ObjectMapper; +import com.linkerbot.community.bean.Contracts.*; +import com.linkerbot.community.common.BusinessException; +import com.linkerbot.community.common.FilePaths; +import com.linkerbot.community.common.PageResponse; +import com.linkerbot.community.service.config.CommunityProperties; + +import org.springframework.stereotype.Component; + +import java.io.IOException; +import java.net.URI; +import java.net.URLEncoder; +import java.net.http.HttpClient; +import java.net.http.HttpRequest; +import java.net.http.HttpResponse; +import java.nio.charset.StandardCharsets; +import java.util.*; + +@Component +public class RestGiteaClient implements GiteaClient { + private final CommunityProperties properties; + private final ObjectMapper json; + private final HttpClient http; + + public RestGiteaClient(CommunityProperties properties, ObjectMapper json) { + this.properties = properties; + this.json = json; + this.http = + HttpClient.newBuilder() + .connectTimeout(properties.getGitea().getConnectTimeout()) + .followRedirects(HttpClient.Redirect.NEVER) + .build(); + } + + private static String encode(String value) { + return URLEncoder.encode(value, StandardCharsets.UTF_8).replace("+", "%20"); + } + + private String repoPath(Repository repo) { + return "/repos/" + encode(repo.owner()) + "/" + encode(repo.name()); + } + + private String filePath(String path) { + return Arrays.stream(path.split("/")) + .map(RestGiteaClient::encode) + .reduce((a, b) -> a + "/" + b) + .orElse(""); + } + + private HttpResponse request(String method, String path, Object body) { + if (properties.getGitea().getToken().isBlank()) + throw new GiteaFailure(503, "GITEA_NOT_CONFIGURED", "请配置 Gitea Token", false); + try { + String base = properties.getGitea().getBaseUrl().replaceAll("/+$", ""); + HttpRequest.Builder builder = + HttpRequest.newBuilder(URI.create(base + "/api/v1" + path)) + .timeout(properties.getGitea().getRequestTimeout()) + .header("Accept", "application/json") + .header("Authorization", "token " + properties.getGitea().getToken()); + if (body == null) builder.method(method, HttpRequest.BodyPublishers.noBody()); + else + builder.header("Content-Type", "application/json") + .method( + method, + HttpRequest.BodyPublishers.ofByteArray( + json.writeValueAsBytes(body))); + HttpResponse response = + http.send(builder.build(), HttpResponse.BodyHandlers.ofByteArray()); + int status = response.statusCode(); + if (status < 200 || status >= 300) { + if (status == 404) throw new GiteaFailure(404, "NOT_FOUND", "仓库文件或版本不存在", false); + if (status == 409 || status == 422) + throw new GiteaFailure(409, "GITEA_CONFLICT", "仓库内容冲突,请刷新后重试", false); + throw new GiteaFailure( + 502, + "GITEA_ERROR", + "仓库服务返回异常,请通过 requestId 排查", + !method.equals("GET") && status >= 500); + } + return response; + } catch (InterruptedException error) { + Thread.currentThread().interrupt(); + throw new GiteaFailure( + 504, "REMOTE_RESULT_UNKNOWN", "仓库调用被中断,写入结果需核对", !method.equals("GET")); + } catch (IOException error) { + throw new GiteaFailure( + 504, "REMOTE_RESULT_UNKNOWN", "仓库连接异常或超时,写入结果需核对", !method.equals("GET")); + } + } + + private JsonNode parse(byte[] bytes, boolean writing) { + try { + return json.readTree(bytes); + } catch (IOException error) { + throw new GiteaFailure(502, "GITEA_INVALID_RESPONSE", "仓库响应格式异常", writing); + } + } + + @Override + public Repository createRepository(String name, boolean initialize) { + Map body = new LinkedHashMap<>(); + body.put("name", name); + body.put("private", true); + body.put("auto_init", initialize); + body.put("default_branch", "main"); + if (initialize) body.put("readme", "Default"); + String owner = properties.getGitea().getOwner(); + JsonNode data = + parse(request("POST", "/orgs/" + encode(owner) + "/repos", body).body(), true); + if (data.path("id").asLong() <= 0 || !data.path("private").asBoolean()) + throw new GiteaFailure(502, "GITEA_INVALID_RESPONSE", "仓库创建结果异常,需人工核对", true); + return new Repository(data.path("id").asLong(), owner, name); + } + + @Override + public String head(Repository repo) { + JsonNode branch = + parse(request("GET", repoPath(repo) + "/branches/main", null).body(), false); + return FilePaths.sha(branch.path("commit").path("id").asText()); + } + + private JsonNode contents(Repository repo, String sha, String path) { + String suffix = path.isEmpty() ? "" : "/" + filePath(path); + return parse( + request( + "GET", + repoPath(repo) + + "/contents" + + suffix + + "?ref=" + + FilePaths.sha(sha), + null) + .body(), + false); + } + + @Override + public List tree(Repository repo, String sha, String path) { + JsonNode nodes = contents(repo, sha, FilePaths.directory(path)); + if (!nodes.isArray()) throw BusinessException.badRequest("路径不是目录"); + List result = new ArrayList<>(); + for (JsonNode node : nodes) + result.add( + new TreeEntry( + node.path("path").asText(), + node.path("name").asText(), + node.path("type").asText(), + node.path("size").asLong(), + node.path("sha").asText())); + result.sort( + Comparator.comparing((TreeEntry entry) -> !entry.type().equals("dir")) + .thenComparing(TreeEntry::name)); + return result; + } + + @Override + public StoredFile file(Repository repo, String sha, String path) { + FilePaths.file(path); + JsonNode node = contents(repo, sha, path); + if (!node.isObject() || !node.path("type").asText().equals("file")) + throw BusinessException.badRequest("仅支持普通文件,不支持符号链接或子模块"); + if (node.path("size").asLong() > properties.getMaxFileBytes()) + throw new BusinessException(413, "FILE_TOO_LARGE", "文件超过读取限制"); + byte[] bytes; + try { + if (node.path("encoding").asText().equals("base64") && node.hasNonNull("content")) + bytes = Base64.getMimeDecoder().decode(node.path("content").asText()); + else + bytes = + request( + "GET", + repoPath(repo) + "/raw/" + filePath(path) + "?ref=" + sha, + null) + .body(); + } catch (IllegalArgumentException error) { + throw new GiteaFailure(502, "GITEA_INVALID_RESPONSE", "仓库文件编码异常", false); + } + if (bytes.length > properties.getMaxFileBytes()) + throw new BusinessException(413, "FILE_TOO_LARGE", "文件超过读取限制"); + return new StoredFile(path, node.path("sha").asText(), bytes); + } + + @Override + public CommitView commit( + Repository repo, + List changes, + String message, + String authorName, + String authorCode) { + List> files = new ArrayList<>(); + for (Change change : changes) { + Map item = new LinkedHashMap<>(); + item.put("operation", change.operation()); + item.put("path", FilePaths.file(change.path())); + if (change.blobSha() != null) item.put("sha", change.blobSha()); + if (!change.operation().equals("delete")) + item.put("content", Base64.getEncoder().encodeToString(change.bytes())); + files.add(item); + } + Map body = + Map.of( + "branch", + "main", + "files", + files, + "message", + message, + "author", + Map.of( + "name", + authorName, + "email", + authorCode + "@users.community.invalid")); + JsonNode result = parse(request("POST", repoPath(repo) + "/contents", body).body(), true); + String sha = result.path("commit").path("sha").asText(); + if (sha.isBlank()) + throw new GiteaFailure(502, "GITEA_INVALID_RESPONSE", "仓库未返回提交版本,需人工核对", true); + return new CommitView(FilePaths.sha(sha), message); + } + + @Override + public PageResponse history(Repository repo, long page, long size) { + HttpResponse response = + request( + "GET", + repoPath(repo) + "/commits?sha=main&page=" + page + "&limit=" + size, + null); + JsonNode data = parse(response.body(), false); + List items = new ArrayList<>(); + for (JsonNode node : data) { + JsonNode commit = node.path("commit"); + items.add( + new HistoryEntry( + node.path("sha").asText(), + commit.path("message").asText(), + commit.path("author").path("name").asText(), + commit.path("author").path("date").asText())); + } + long total = + response.headers() + .firstValue("X-Total-Count") + .map(Long::parseLong) + .orElse((long) items.size()); + return new PageResponse<>(items, page, size, total); + } +} diff --git a/community-service/src/main/java/com/linkerbot/community/service/mapper/CommentMapper.java b/community-service/src/main/java/com/linkerbot/community/service/mapper/CommentMapper.java new file mode 100644 index 0000000..4e5df66 --- /dev/null +++ b/community-service/src/main/java/com/linkerbot/community/service/mapper/CommentMapper.java @@ -0,0 +1,9 @@ +package com.linkerbot.community.service.mapper; + +import com.baomidou.mybatisplus.core.mapper.BaseMapper; +import com.linkerbot.community.bean.entity.ProjectComment; + +import org.apache.ibatis.annotations.Mapper; + +@Mapper +public interface CommentMapper extends BaseMapper {} diff --git a/community-service/src/main/java/com/linkerbot/community/service/mapper/LikeMapper.java b/community-service/src/main/java/com/linkerbot/community/service/mapper/LikeMapper.java new file mode 100644 index 0000000..138a1d7 --- /dev/null +++ b/community-service/src/main/java/com/linkerbot/community/service/mapper/LikeMapper.java @@ -0,0 +1,9 @@ +package com.linkerbot.community.service.mapper; + +import com.baomidou.mybatisplus.core.mapper.BaseMapper; +import com.linkerbot.community.bean.entity.ProjectLike; + +import org.apache.ibatis.annotations.Mapper; + +@Mapper +public interface LikeMapper extends BaseMapper {} diff --git a/community-service/src/main/java/com/linkerbot/community/service/mapper/ProjectMapper.java b/community-service/src/main/java/com/linkerbot/community/service/mapper/ProjectMapper.java new file mode 100644 index 0000000..19c084e --- /dev/null +++ b/community-service/src/main/java/com/linkerbot/community/service/mapper/ProjectMapper.java @@ -0,0 +1,9 @@ +package com.linkerbot.community.service.mapper; + +import com.baomidou.mybatisplus.core.mapper.BaseMapper; +import com.linkerbot.community.bean.entity.Project; + +import org.apache.ibatis.annotations.Mapper; + +@Mapper +public interface ProjectMapper extends BaseMapper {} diff --git a/community-service/src/main/java/com/linkerbot/community/service/mapper/UserMapper.java b/community-service/src/main/java/com/linkerbot/community/service/mapper/UserMapper.java new file mode 100644 index 0000000..281d09f --- /dev/null +++ b/community-service/src/main/java/com/linkerbot/community/service/mapper/UserMapper.java @@ -0,0 +1,9 @@ +package com.linkerbot.community.service.mapper; + +import com.baomidou.mybatisplus.core.mapper.BaseMapper; +import com.linkerbot.community.bean.entity.User; + +import org.apache.ibatis.annotations.Mapper; + +@Mapper +public interface UserMapper extends BaseMapper {} diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 0000000..b9e9eb6 --- /dev/null +++ b/docs/api.md @@ -0,0 +1,965 @@ +# Community 前端接口对接文档 + +供社区列表、项目详情、登录、我的工作区和在线文件编辑页面使用。前端通过 Community 后端完成所有业务操作;登录 Token 是平台 Token,前端不连接 Gitea、不持有 Gitea 凭据。 + +当前支持项目、文件、目录、提交、手动发布、快照 Fork、评论和点赞。项目发布后,后续提交只更新工作区,需要再次调用发布接口才更新社区代码。没有服务端草稿保存、AI 检索、独立工作区实体或项目类型表。 + +## 阅读导航 + +- [接入约定](#接入约定) +- [接口总览](#接口总览) +- [响应数据结构](#响应数据结构) +- [登录和用户](#登录和用户) +- [类型与项目列表](#类型与项目列表) +- [我的项目管理](#我的项目管理) +- [目录和文件读取](#目录和文件读取) +- [文件编辑与上传提交](#文件编辑与上传提交) +- [社区发布和撤回](#社区发布和撤回) +- [社区详情和 Fork](#社区详情和-fork) +- [评论和点赞](#评论和点赞) +- [错误码与前端处理](#错误码与前端处理) +- [页面调用顺序](#页面调用顺序) +- [前端请求示例](#前端请求示例) +- [后端人工核对](#后端人工核对) + +## 接入约定 + +### 地址和请求头 + +本机默认后端地址为 `http://localhost:8993`,接口前缀为 `/api`。实际端口可由 `SERVER_PORT` 或 `PORT` 覆盖,部署环境地址由后端提供。 + +| 项目 | 约定 | +| --- | --- | +| JSON 请求 | `Content-Type: application/json` | +| 登录凭据 | `Authorization: Bearer <平台 token>`,注意 `Bearer` 的大小写和空格 | +| 上传 | `multipart/form-data`,浏览器使用 FormData,不手动设置 Content-Type | +| 业务标识 | 使用 `projectCode`、`commentCode`、`userCode`,不使用数据库 ID | +| 接口调试 | `/swagger-ui.html` | +| OpenAPI | `/v3/api-docs` | + +当前后端没有配置跨域白名单。开发时通过前端开发服务器代理 `/api`,部署时通过同域反向代理访问;仅允许 OPTIONS 请求不代表已经支持浏览器跨域访问。 + +### 统一响应 + +除成功的文件下载外,响应为以下 JSON 结构。所有成功接口使用 HTTP 200,创建、删除、退出登录也不返回 201 或 204。 + +```json +{ + "code": "OK", + "message": "成功", + "data": null, + "requestId": "44444444444444444444444444444444" +} +``` + +| 字段 | 类型 | 说明 | +| --- | --- | --- | +| code | string | 成功为 `OK`,失败为业务错误码 | +| message | string | 可用于提示用户,不要通过中文 message 判断错误类型 | +| data | 对象、数组或 null | 成功数据;失败通常为 null,部分仓库错误包含 projectCode | +| requestId | string | 本次请求的排查标识,与响应头 `X-Request-Id` 一致 | + +下面标为“data 示例”的代码块只展示 `data`,实际响应仍有上面的包装。示例业务编码和 SHA 均为虚构,调用时必须使用接口返回的真实值。 + +分页接口的 data 为: + +```json +{ + "items": [], + "page": 1, + "size": 20, + "total": 0 +} +``` + +`page` 从 1 开始,范围为 1~100000;`size` 默认 20,范围为 1~100。`total` 为数字,不返回额外的 `pages` 字段。空列表是 `items: []`。 + +### 时间和版本 + +项目和评论的时间字段按 UTC 保存,JSON 格式为 `2026-10-13T08:30:00`,可能带小数秒,**没有时区后缀**。前端解析这些字段时应按 UTC 处理,再转换成用户时区;不要直接当成本地时间。历史提交的 `authorDate` 来自仓库服务,可带 `Z` 或时区偏移。 + +Git SHA 使用完整的 40 或 64 位十六进制字符串,不使用缩写。几个版本字段的用途不同: + +| 字段 | 来源 | 用途 | +| --- | --- | --- | +| commitSha | 目录、文件、提交结果、历史提交 | 读取指定版本;提交结果中的值是新版本 | +| expectedCommitSha | 提交请求 | 编辑或上传所基于的工作区版本,防止覆盖其他提交 | +| publishedCommitSha | 项目详情 | 社区当前发布版本;Fork 时原样提交此值 | +| blobSha | 文件或目录条目 | 文件或目录对应的 Git 对象标识,前端不用它提交文件 | + +项目详情不包含工作区当前 main 的 SHA。进入编辑器、提交或发布前,从工作区目录或文件接口获取 `commitSha`。 + +## 接口总览 + +“可选登录”表示匿名也能访问;带有效 Token 时项目响应可返回当前用户的 `liked` 状态。公开接口携带已失效的 Bearer Token 仍会返回 401。 + +| 方法 | 路径 | 登录 | 成功 data | +| --- | --- | --- | --- | +| GET | `/api/auth/captcha` | 否 | Captcha | +| POST | `/api/auth/login` | 否 | Login | +| POST | `/api/auth/logout` | 是 | null | +| GET | `/api/users/me` | 是 | User | +| GET | `/api/project-types` | 否 | ProjectType[] | +| GET | `/api/workspace/projects` | 是 | PageResult<Project> | +| POST | `/api/workspace/projects` | 是 | Project | +| GET | `/api/workspace/projects/{projectCode}` | 是 | Project | +| PATCH | `/api/workspace/projects/{projectCode}` | 是 | Project | +| DELETE | `/api/workspace/projects/{projectCode}` | 是 | null | +| GET | `/api/workspace/projects/{projectCode}/tree` | 是 | Tree | +| GET | `/api/workspace/projects/{projectCode}/files` | 是 | ProjectFile 或下载二进制 | +| POST | `/api/workspace/projects/{projectCode}/commits` | 是 | Commit | +| GET | `/api/workspace/projects/{projectCode}/commits` | 是 | PageResult<HistoryEntry> | +| POST | `/api/workspace/projects/{projectCode}/uploads/commit` | 是 | Commit | +| PUT | `/api/workspace/projects/{projectCode}/publication` | 是 | Project | +| DELETE | `/api/workspace/projects/{projectCode}/publication` | 是 | null | +| GET | `/api/community/projects` | 可选 | PageResult<Project> | +| GET | `/api/community/projects/{projectCode}` | 可选 | Project | +| GET | `/api/community/projects/{projectCode}/tree` | 可选 | Tree | +| GET | `/api/community/projects/{projectCode}/files` | 可选 | ProjectFile 或下载二进制 | +| POST | `/api/community/projects/{projectCode}/forks` | 是 | Project | +| GET | `/api/community/projects/{projectCode}/comments` | 可选 | PageResult<Comment> | +| POST | `/api/community/projects/{projectCode}/comments` | 是 | Comment | +| DELETE | `/api/comments/{commentCode}` | 是 | null | +| PUT | `/api/community/projects/{projectCode}/like` | 是 | null | +| DELETE | `/api/community/projects/{projectCode}/like` | 是 | null | + +## 响应数据结构 + +以下 TypeScript 类型与当前 JSON 字段对应。项目列表、工作区详情、社区详情、创建、修改、发布和 Fork 共用 Project 结构。 + +```typescript +/** 无时区后缀,按 UTC 解释。 */ +export type UtcDateTime = string; + +export interface ApiResponse { + code: string; + message: string; + data: T | null; + requestId: string; +} + +export interface PageResult { + items: T[]; + page: number; + size: number; + total: number; +} + +export interface PublicUser { + userCode: string | null; // 用户记录不可用时可能为 null + nickname: string; +} + +export interface User { + userCode: string; + nickname: string; + email: string; +} + +export interface Captcha { + captchaCode: string; + image: string; // PNG data URL,可直接作为 img 的 src + expiresIn: number; // 秒 +} + +export interface Login { + token: string; + tokenType: 'Bearer'; + expiresIn: number; // 秒 + user: User; +} + +export interface ProjectType { + code: string; + name: string; +} + +export interface Project { + projectCode: string; + name: string; + description: string; + projectType: string; + owner: PublicUser; + repoStatus: 'CREATING' | 'READY' | 'FAILED'; + publishStatus: 'UNPUBLISHED' | 'PUBLISHED'; + publishedCommitSha: string | null; + publishedAt: UtcDateTime | null; + sourceProjectCode: string | null; + sourceCommitSha: string | null; + likeCount: number; + commentCount: number; + liked: boolean; + createdAt: UtcDateTime; + updatedAt: UtcDateTime; +} + +export interface TreeEntry { + path: string; // 从仓库根目录开始的完整相对路径 + name: string; + type: string; // 普通目录为 dir,普通文件为 file + size: number; // 字节 + blobSha: string; +} + +export interface Tree { + commitSha: string; + path: string; // 根目录为 "" + entries: TreeEntry[]; // 当前目录的直接子项 +} + +export interface ProjectFile { + commitSha: string; + path: string; + blobSha: string; + size: number; // 字节 + encoding: 'utf-8' | 'base64'; + content: string; + editable: boolean; +} + +export interface Commit { + commitSha: string; + message: string; +} + +export interface HistoryEntry { + commitSha: string; + message: string; + authorName: string; + authorDate: string; // 仓库服务返回的日期字符串 +} + +export interface Comment { + commentCode: string; + author: PublicUser; + content: string; + createdAt: UtcDateTime; +} +``` + +### 项目示例与状态含义 + +已发布项目的 data 示例: + +```json +{ + "projectCode": "22222222222222222222222222222222", + "name": "机器人示例项目", + "description": "模型、配置和说明文件", + "projectType": "GENERAL", + "owner": { + "userCode": "11111111111111111111111111111111", + "nickname": "用户_11111111" + }, + "repoStatus": "READY", + "publishStatus": "PUBLISHED", + "publishedCommitSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + "publishedAt": "2026-10-13T08:30:00", + "sourceProjectCode": null, + "sourceCommitSha": null, + "likeCount": 3, + "commentCount": 2, + "liked": false, + "createdAt": "2026-10-13T08:00:00", + "updatedAt": "2026-10-13T08:30:00" +} +``` + +| 状态或字段 | 前端使用方式 | +| --- | --- | +| repoStatus = CREATING | 仓库初始化未完成,可能需要人工核对;关闭文件读取、提交和发布入口 | +| repoStatus = READY | 仓库已就绪,可进入文件操作;仍需处理版本冲突或写入待核对错误 | +| repoStatus = FAILED | 初始化失败,显示失败状态;仍可修改项目信息或删除项目 | +| publishStatus = UNPUBLISHED | 当前不在社区展示;这是私有项目状态,不是草稿 | +| publishStatus = PUBLISHED | 当前在社区展示 | +| publishedCommitSha / publishedAt | 撤回后可能仍保留上一次发布值,是否公开必须判断 publishStatus | +| sourceProjectCode / sourceCommitSha | Fork 来源及复制的源版本;普通新项目为 null | +| liked | 当前请求用户是否点赞,匿名访问为 false | + +工作区归属由 `owner.userCode` 判断,不存在 `workspaceCode`。`updatedAt` 不代表仓库最新提交时间。来源项目撤回或删除后,sourceProjectCode 仍可能存在,访问该来源的社区详情会返回 404。 + +## 登录和用户 + +### 获取图片验证码 + +`GET /api/auth/captcha`,无需登录,无参数。 + +data 示例中 image 仅展示格式前缀,实际值为完整图片: + +```json +{ + "captchaCode": "55555555555555555555555555555555", + "image": "data:image/png;base64,...", + "expiresIn": 120 +} +``` + +将 image 作为图片 src,将 captchaCode 与用户输入答案一起提交。有效期默认 120 秒,以接口返回值为准。验证码只使用一次,答案错误也会消耗验证码;失败后重新获取图片。答案校验忽略首尾空格和大小写。 + +### 邮箱登录 + +`POST /api/auth/login`,无需登录。 + +| 请求字段 | 必填 | 约束 | +| --- | --- | --- | +| email | 是 | 合法邮箱,最多 254 字符,前端提交前去掉首尾空格 | +| captchaCode | 是 | 验证码接口返回的标识 | +| captchaAnswer | 是 | 用户输入的图片验证码 | + +请求: + +```json +{ + "email": "user@example.com", + "captchaCode": "55555555555555555555555555555555", + "captchaAnswer": "ABCDE" +} +``` + +响应示例: + +```json +{ + "code": "OK", + "message": "成功", + "data": { + "token": "example-platform-token", + "tokenType": "Bearer", + "expiresIn": 86400, + "user": { + "userCode": "11111111111111111111111111111111", + "nickname": "用户_11111111", + "email": "user@example.com" + } + }, + "requestId": "44444444444444444444444444444444" +} +``` + +首次登录自动创建用户,邮箱统一转成小写。当前只验证邮箱格式与图片验证码,不发送邮件、不使用密码,也不验证邮箱归属。Token 有效期默认 24 小时,以 expiresIn 为准,不是 JWT,没有刷新 Token 接口;服务重启后需要重新登录。 + +### 当前用户和退出登录 + +`GET /api/users/me`,需要登录,data 为 User;只有本人用户接口和登录响应包含邮箱,公开作者信息不包含邮箱。 + +`POST /api/auth/logout`,需要登录,无请求体,成功 data 为 null。前端清除本地登录状态。已失效 Token 调用退出接口会返回 401,同样可以清除本地登录状态。 + +## 类型与项目列表 + +### 可选项目类型 + +`GET /api/project-types`,无需登录,无参数,data 为 ProjectType[]: + +```json +[ + { "code": "GENERAL", "name": "通用" }, + { "code": "HUMANOID", "name": "人形" }, + { "code": "QUADRUPED", "name": "四足" }, + { "code": "WHEELED", "name": "轮式" } +] +``` + +左侧类型导航和创建项目下拉框使用这个接口,不在前端写死类型码。“全部”筛选不传 type。当前内置 GENERAL(通用)、HUMANOID(人形)、QUADRUPED(四足)、WHEELED(轮式),创建或修改项目时通过 projectType 提交对应 code,列表筛选时通过 type 提交对应 code。 + +### 我的项目列表和社区项目列表 + +- `GET /api/workspace/projects`:需要登录,返回本人所有未删除项目,包括 CREATING、FAILED 项目。 +- `GET /api/community/projects`:可选登录,仅返回 READY 且 PUBLISHED 的项目。 + +两者查询参数相同: + +| 参数 | 必填 | 默认 | 说明 | +| --- | --- | --- | --- | +| page | 否 | 1 | 页码 | +| size | 否 | 20 | 每页数量 | +| type | 否 | 无 | 项目类型 code;注意查询字段叫 type,不是 projectType | +| keyword | 否 | 无 | 名称或描述的模糊查询,最多 200 字符;空白值不筛选 | + +请求示例:`GET /api/community/projects?page=1&size=20&type=GENERAL&keyword=机器人`。使用 URLSearchParams 编码中文等查询值。 + +成功 data 为 PageResult<Project>。工作区按创建时间倒序,社区按最近发布时间倒序;不支持客户端指定排序。更换类型或关键词时,把 page 重置为 1。 + +## 我的项目管理 + +以下接口需要登录,且只能操作当前用户的项目。项目不存在、已删除或属于其他用户,均返回 404。 + +### 创建项目 + +`POST /api/workspace/projects`。 + +| 请求字段 | 必填 | 约束 | +| --- | --- | --- | +| name | 是 | 非空,最多 100 字符,保存时去掉首尾空格 | +| description | 否 | 最多 2000 字符,省略或 null 时保存为空字符串 | +| projectType | 是 | 类型接口返回的 code,必须精确匹配,最多 64 字符 | + +```json +{ + "name": "机器人示例项目", + "description": "模型、配置和说明文件", + "projectType": "GENERAL" +} +``` + +成功 data 为 Project,状态为 READY、UNPUBLISHED。后端已创建私有仓库、main 分支和 README.md。使用返回的 projectCode 进入工作区详情,然后读取根目录获取当前 commitSha。 + +创建是同步请求,没有任务编号、202 响应或操作进度查询接口。请求失败可能已经留下项目记录;先查看错误 data.projectCode 和工作区列表,不要自动重发创建请求。 + +### 项目详情 + +`GET /api/workspace/projects/{projectCode}`,无额外参数,data 为 Project。 + +### 修改项目信息 + +`PATCH /api/workspace/projects/{projectCode}`。请求字段与创建项目相同,data 为更新后的 Project。 + +虽然方法为 PATCH,当前接口要求同时提交 name、projectType;description 省略或 null 会清空描述。前端编辑表单应提交完整的三个字段。 + +已发布项目的名称、描述、类型会直接更新社区展示,不生成文件 Commit。 + +### 删除项目 + +`DELETE /api/workspace/projects/{projectCode}`,无请求体,成功 data 为 null。 + +项目逻辑删除并从社区撤回,已有独立 Fork 不受影响。再次操作已删除项目返回 404。 + +## 目录和文件读取 + +### 工作区目录 + +`GET /api/workspace/projects/{projectCode}/tree`,需要登录。 + +| 参数 | 必填 | 说明 | +| --- | --- | --- | +| path | 否 | 目录相对路径,省略或空字符串表示根目录 | +| commitSha | 否 | 省略时读取当前 main;传入时读取该项目指定提交 | + +data 示例: + +```json +{ + "commitSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + "path": "", + "entries": [ + { + "path": "models", + "name": "models", + "type": "dir", + "size": 0, + "blobSha": "cccccccccccccccccccccccccccccccccccccccc" + }, + { + "path": "README.md", + "name": "README.md", + "type": "file", + "size": 5, + "blobSha": "dddddddddddddddddddddddddddddddddddddddd" + } + ] +} +``` + +entries 仅包含当前目录的直接子项,目录在前,名称升序。展开子目录时传条目的完整 path。需要一致的历史文件视图时,目录和文件读取都使用同一个 commitSha。 + +### 工作区文件 + +`GET /api/workspace/projects/{projectCode}/files`,需要登录。 + +| 参数 | 必填 | 默认 | 说明 | +| --- | --- | --- | --- | +| path | 是 | 无 | 普通文件的相对路径 | +| commitSha | 否 | 当前 main | 指定历史提交 | +| download | 否 | false | true 返回文件附件 | + +文本文件 data 示例: + +```json +{ + "commitSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + "path": "README.md", + "blobSha": "dddddddddddddddddddddddddddddddddddddddd", + "size": 5, + "encoding": "utf-8", + "content": "hello", + "editable": true +} +``` + +二进制文件 data 示例: + +```json +{ + "commitSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + "path": "models/data.bin", + "blobSha": "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee", + "size": 3, + "encoding": "base64", + "content": "AAEC", + "editable": false +} +``` + +只有 UTF-8、没有 NUL 字节且不超过文本编辑限制的文件返回 editable=true。二进制文件或超过编辑限制的文本返回 base64,不能直接把 base64 放进编辑器提交;使用上传替换。文件和下载均受单文件读取上限限制。 + +`download=true` 成功返回 `application/octet-stream`,带 `Content-Disposition: attachment`,不套 JSON。工作区下载需要带 Bearer Token,应使用 fetch 获取 Blob,直接使用 a 标签或 window.open 无法附加该请求头。失败时按 JSON 错误响应处理。 + +### 社区目录和文件 + +- `GET /api/community/projects/{projectCode}/tree`:path 用法与工作区一致,data 为 Tree。 +- `GET /api/community/projects/{projectCode}/files`:支持 path、download,返回与工作区相同的文件数据或二进制。 + +均可匿名访问,固定读取当前 publishedCommitSha。**不要传 commitSha 参数,即使传空字符串也会返回 400。** 社区页面只读,需要编辑时先 Fork 到自己的工作区。撤回、删除或未发布项目返回 404。 + +### 路径限制 + +文件和非根目录路径必须为相对路径,最长 1024 字符。支持中文、空格和多级目录,例如 `models/轮式机器人/底盘.stl`;不加开头或结尾斜杠。根目录在目录接口和上传 directory 中用空字符串。 + +禁止绝对路径、反斜杠、空路径段、`.`、`..`、`.git` 路径段、冒号及控制字符。读取普通文件接口不支持符号链接或 Git 子模块。使用 URLSearchParams 处理查询编码,不自行拼接未编码的 path。 + +## 文件编辑与上传提交 + +### 多文件提交 + +`POST /api/workspace/projects/{projectCode}/commits`,需要登录。 + +| 请求字段 | 必填 | 约束 | +| --- | --- | --- | +| expectedCommitSha | 是 | 当前编辑所基于的完整工作区 SHA | +| message | 是 | 非空,最多 1000 字符 | +| changes | 是 | 1~500 个文件变更 | + +每个 changes 元素使用以下字段: + +| 字段 | 说明 | +| --- | --- | +| action | CREATE_FILE、UPDATE_FILE、DELETE_FILE、CREATE_DIRECTORY | +| path | 文件或新目录的相对路径 | +| content | CREATE_FILE、UPDATE_FILE 必填,UTF-8 文本;可为 `""` 创建或替换为空文件 | + +请求示例中的路径必须符合仓库实际情况:创建路径应尚不存在,修改或删除目标必须存在。 + +```json +{ + "expectedCommitSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + "message": "更新说明并添加文件", + "changes": [ + { "action": "UPDATE_FILE", "path": "README.md", "content": "新的说明" }, + { "action": "CREATE_FILE", "path": "src/main.txt", "content": "hello" }, + { "action": "CREATE_DIRECTORY", "path": "models" }, + { "action": "DELETE_FILE", "path": "old.txt" } + ] +} +``` + +成功 data 为 Commit: + +```json +{ + "commitSha": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", + "message": "更新说明并添加文件" +} +``` + +一次请求生成一个 Commit。保存成功后,更新编辑器基准 SHA 并重新加载目录和受影响的文件。编辑器输入只存在于当前前端状态中,后端没有自动保存或草稿接口。 + +新建空目录实际创建 `{path}/.gitkeep`,目录和文件会在提交时进入仓库。一批不能重复操作同一路径,包含新目录转换成 .gitkeep 后的实际路径。DELETE_FILE、CREATE_DIRECTORY 不需要 content。没有单独的删除目录或重命名接口;删除目录需提交其所有文件的删除操作,包括 .gitkeep,并遵守每批 500 个变更限制。 + +如果 expectedCommitSha 已不是最新 main,返回 409 CONFLICT。前端保留当前未提交输入,重新读取工作区版本,让用户处理差异后再提交;不要只替换 SHA 后自动覆盖内容。浏览历史版本时应使用只读模式,回到最新版本后再编辑。 + +### 上传并提交 + +`POST /api/workspace/projects/{projectCode}/uploads/commit`,需要登录,使用 FormData。 + +| multipart 字段 | 必填 | 说明 | +| --- | --- | --- | +| expectedCommitSha | 是 | 基于的当前工作区版本 | +| message | 是 | 非空,最多 1000 字符 | +| directory | 否 | 目标目录,省略或空字符串表示根目录 | +| files | 是 | 重复使用同名 files 字段,1~500 个文件 | +| paths | 否 | 重复使用同名 paths 字段,与 files 顺序和数量一一对应 | + +不传 paths 时使用各文件的原始文件名;传入时每个值是相对于 directory 的路径。例:directory=`models`、paths=`robot/body.stl`,最终路径为 `models/robot/body.stl`,不要重复添加 directory 前缀。 + +同名文件会替换,界面应说明覆盖行为。所有文件生成一个 Commit,成功 data 与文本提交相同。上传用于二进制文件和较大文本文件的新增或替换。 + +### 默认大小限制 + +| 限制 | 数值 | +| --- | --- | +| 在线创建或编辑的单个文本内容 | 1 MiB,1048576 字节 | +| 上传或读取的单文件 | 10 MiB,10485760 字节 | +| 本次上传文件或提交内容总量 | 50 MiB,52428800 字节 | +| multipart 整个请求 | 52 MiB,包含传输开销 | +| 单批变更或上传文件数量 | 500 | + +大小按字节计算,文本使用 UTF-8 编码长度,不使用 JavaScript 字符串 length 计算文件体积。以上是当前默认配置,超限返回 413。后端调整业务上传大小时还需同步调整 multipart 配置。 + +### 提交历史 + +`GET /api/workspace/projects/{projectCode}/commits?page=1&size=20`,需要登录。 + +data 为 PageResult<HistoryEntry>,只读取 main 的历史,不提供分支切换。历史条目示例: + +```json +{ + "commitSha": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", + "message": "更新说明并添加文件", + "authorName": "用户_11111111", + "authorDate": "2026-10-13T08:40:00Z" +} +``` + +点击历史条目,把 commitSha 传给工作区 tree、files 接口。历史 total 依赖仓库服务的统计响应头,未提供时退化为本页条数;前端也可结合本页 items 数量提供下一页操作。 + +## 社区发布和撤回 + +### 首次发布和更新社区版本 + +`PUT /api/workspace/projects/{projectCode}/publication`,需要登录。 + +请求: + +```json +{ + "commitSha": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" +} +``` + +commitSha 必须为当前 main 的完整 SHA,不能发布历史提交。成功 data 为 Project,publishStatus=PUBLISHED,publishedCommitSha 为提交的版本,publishedAt 更新为本次发布时间。 + +同一路径用于首次发布和以后手动更新社区版本。发布后继续提交、上传或创建目录,都不会自动更新社区代码。需要更新时,取得最新工作区 SHA,再调用此接口。项目名称、描述和类型的修改直接更新展示。 + +例:发布版本 A 后,在工作区提交得到 B,工作区展示 B,社区仍展示 A;再次用 B 调用 publication 后,社区才展示 B。前端可比较工作区 tree.commitSha 与项目 publishedCommitSha,显示“有未发布的更新”。 + +工作区 SHA 已变化时返回 409 CONFLICT,刷新版本后由用户重新确认发布。成功后刷新工作区详情和社区列表或详情。 + +### 撤回社区 + +`DELETE /api/workspace/projects/{projectCode}/publication`,需要登录,无请求体,成功 data 为 null。 + +撤回后项目留在工作区,社区列表、详情、目录、文件、评论列表及新增互动不可访问。原有评论、点赞和发布记录保留,再次发布继续使用;已有独立 Fork 不受影响。 + +## 社区详情和 Fork + +### 项目详情 + +`GET /api/community/projects/{projectCode}`,可选登录,data 为 Project。 + +列表项点击后用 projectCode 进入前端详情路由,再请求本接口。可并行请求根目录和评论列表。需要当前用户的点赞状态时携带有效 Token。前端页面 URL 由前端定义,后端不返回可直接跳转的页面地址。 + +### Fork 到我的工作区 + +`POST /api/community/projects/{projectCode}/forks`,需要登录。 + +| 请求字段 | 必填 | 说明 | +| --- | --- | --- | +| name | 是 | 新项目名称,非空,最多 100 字符 | +| publishedCommitSha | 是 | 当前社区详情返回的完整发布版本 | + +```json +{ + "name": "我的机器人副本", + "publishedCommitSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" +} +``` + +成功 data 为当前用户的新 Project,状态 READY、UNPUBLISHED;使用返回的新 projectCode 跳转工作区。类型和描述继承源项目,sourceProjectCode、sourceCommitSha 记录来源。 + +Fork 复制发布版本的所有普通文件,不复制源仓库提交历史,不自动同步上游。允许同一用户多次 Fork。所有文件复制完成才返回 READY;不支持符号链接或子模块。 + +源项目发布版本已变化时返回 409 CONFLICT,刷新社区详情后由用户重新确认。Fork 是同步请求,可能耗时较长;提交期间显示加载状态并防止重复点击。超时、网络断开或失败后先查询工作区,不要自动重发。 + +## 评论和点赞 + +### 评论列表 + +`GET /api/community/projects/{projectCode}/comments?page=1&size=20`,可选登录。 + +data 为 PageResult<Comment>,按创建时间倒序,平铺展示,不提供回复层级。评论 data 示例: + +```json +{ + "commentCode": "33333333333333333333333333333333", + "author": { + "userCode": "11111111111111111111111111111111", + "nickname": "用户_11111111" + }, + "content": "这个项目的结构很清楚", + "createdAt": "2026-10-13T08:45:00" +} +``` + +### 新增评论 + +`POST /api/community/projects/{projectCode}/comments`,需要登录。 + +```json +{ + "content": "这个项目的结构很清楚" +} +``` + +content 非空,最多 2000 字符,保存时去掉首尾空格。成功 data 为新 Comment。只支持纯文本,没有富文本、评论编辑或回复接口;前端以文本渲染。提交成功后刷新评论列表和项目 commentCount,不要自动重试新增评论请求。 + +### 删除自己的评论 + +`DELETE /api/comments/{commentCode}`,需要登录,无请求体,成功 data 为 null。 + +比较 `comment.author.userCode === currentUser.userCode` 决定是否显示删除入口,后端仍会校验作者身份。删除他人的、已删除的或不存在的评论返回 404。删除成功后刷新评论列表和项目统计。 + +### 点赞和取消点赞 + +- `PUT /api/community/projects/{projectCode}/like`:需要登录,点赞。 +- `DELETE /api/community/projects/{projectCode}/like`:需要登录,取消点赞。 + +均无请求体,成功 data 为 null,两者幂等。点赞接口不返回最新计数,成功后重新请求社区详情获取 liked、likeCount;可以先做乐观更新,失败时恢复并刷新详情。 + +## 错误码与前端处理 + +### 错误响应示例 + +版本冲突通常不带 data: + +```json +{ + "code": "CONFLICT", + "message": "工作区版本已变化,请刷新后重新提交", + "data": null, + "requestId": "44444444444444444444444444444444" +} +``` + +部分创建、Fork 或仓库调用错误携带关联项目: + +```json +{ + "code": "REMOTE_RESULT_UNKNOWN", + "message": "仓库连接异常或超时,写入结果需核对", + "data": { + "projectCode": "22222222222222222222222222222222" + }, + "requestId": "44444444444444444444444444444444" +} +``` + +### 错误处理对照 + +| HTTP | code | 前端处理 | +| --- | --- | --- | +| 400 | BAD_REQUEST | 参数、分页、类型、路径、SHA 或文件操作不合法,展示 message 并检查请求 | +| 400 | CAPTCHA_INVALID | 验证码错误、已使用或过期,刷新验证码 | +| 401 | UNAUTHORIZED | 清除登录状态,受保护页面进入登录流程;公开 GET 可移除失效 Token 后重新读取 | +| 403 | ACCOUNT_DISABLED | 登录账号不可用,停止登录流程并展示提示 | +| 403 | FORBIDDEN | 无权访问,展示权限提示 | +| 404 | NOT_FOUND | 项目不可访问、目标文件或版本不存在;停止加载目标资源并展示不可用状态 | +| 405 | METHOD_NOT_ALLOWED | 检查请求方法 | +| 409 | CONFLICT | 工作区或发布版本变化,或仓库未就绪,按 message 刷新版本或核对状态 | +| 409 | GITEA_CONFLICT | 仓库内容冲突,刷新目录和文件后由用户处理 | +| 409 | REMOTE_RESULT_UNKNOWN | 上一次仓库写入结果待核对,暂不能继续该项目的仓库写入 | +| 413 | FILE_TOO_LARGE | 文件读取、编辑或上传内容超限,提示大小限制 | +| 413 | UPLOAD_TOO_LARGE | 整体 multipart 请求超限 | +| 415 | UNSUPPORTED_MEDIA_TYPE | 检查 Content-Type,JSON 与 FormData 不要混用 | +| 500 | CAPTCHA_ERROR | 验证码生成失败,可重新获取并记录 requestId | +| 500 | PROJECT_INITIALIZATION_ERROR | 项目初始化或回写未完成,查看 data.projectCode 和工作区,请后端核对 | +| 500 | INTERNAL_ERROR | 展示服务异常并保留 requestId | +| 502 | GITEA_ERROR | 仓库服务异常;写请求先核对结果,避免自动重试 | +| 502 | GITEA_INVALID_RESPONSE | 仓库响应无法确认;写请求先核对结果,避免自动重试 | +| 503 | GITEA_NOT_CONFIGURED | 后端缺少仓库配置,请后端处理 | +| 504 | REMOTE_RESULT_UNKNOWN | 仓库连接异常或超时;读请求可重新读取,写请求需先核对结果 | + +通过 HTTP 状态和 code 判断行为,保留 requestId 供排查。通用请求封装不要自动重试创建项目、Fork、评论或文件写入。浏览器超时、取消请求、连接中断不保证后端没有执行成功。 + +写入结果待核对时,同一进程内会阻止该项目后续仓库写入或发布;仍可读取可用文件、修改项目信息、撤回和删除。CREATING 项目因仓库尚未 READY,不能读取文件。没有 repository_operation 查询接口、自动恢复接口或跨重启完整幂等保证。 + +## 页面调用顺序 + +| 页面或操作 | 调用顺序 | +| --- | --- | +| 社区首页 | project-types → community/projects;选类型和关键词时重置页码 | +| 社区详情 | community 项目详情、根目录、评论列表;展开目录或点击文件再读取对应内容 | +| 登录页 | captcha → login;失败后刷新验证码;成功后保存平台登录状态 | +| 我的工作区 | users/me → workspace/projects,分别显示仓库状态和发布状态 | +| 创建项目 | POST workspace/projects → 使用返回 projectCode 进入详情 → tree 获取当前版本 | +| 文件编辑 | workspace 详情与 tree → files → 判断 editable → commits → 刷新版本、目录和文件 | +| 上传文件 | tree 获取基准 SHA → uploads/commit → 刷新目录和当前版本 | +| 发布或更新社区 | 获取最新工作区 SHA → publication → 刷新项目和社区页面 | +| Fork | 获取社区详情中的发布 SHA → forks → 使用新 projectCode 进入工作区 | +| 评论或点赞 | 完成写请求 → 刷新评论或项目详情中的统计字段 | + +## 前端请求示例 + +以下示例使用浏览器 fetch 和 TypeScript,类型声明见前面的响应结构。API_BASE 使用 `/api`,配合同域反向代理或开发代理。 + +### JSON 与 FormData 请求封装 + +```typescript +const API_BASE = '/api'; + +class ApiError extends Error { + constructor( + readonly status: number, + readonly code: string, + message: string, + readonly requestId: string | null, + readonly data: unknown = null, + ) { + super(message); + this.name = 'ApiError'; + } +} + +async function request( + path: string, + options: { + method?: string; + token?: string; + body?: unknown; + signal?: AbortSignal; + } = {}, +): Promise { + const headers = new Headers({ Accept: 'application/json' }); + if (options.token) headers.set('Authorization', `Bearer ${options.token}`); + + let body: BodyInit | undefined; + if (options.body instanceof FormData) { + body = options.body; // 浏览器自动设置 multipart boundary + } else if (options.body !== undefined) { + headers.set('Content-Type', 'application/json'); + body = JSON.stringify(options.body); + } + + const response = await fetch(`${API_BASE}${path}`, { + method: options.method ?? 'GET', + headers, + body, + signal: options.signal, + }); + + let result: ApiResponse; + try { + result = await response.json(); + } catch { + throw new ApiError( + response.status, + 'BAD_RESPONSE', // 前端封装错误码,不是后端业务错误码 + '接口未返回有效 JSON', + response.headers.get('X-Request-Id'), + ); + } + if (!response.ok || result.code !== 'OK') { + throw new ApiError( + response.status, result.code, result.message, + result.requestId ?? response.headers.get('X-Request-Id'), result.data, + ); + } + return result.data as T; // 返回 null 的接口使用 request +} +``` + +调用处捕获 ApiError,按照错误码表处理。fetch 的网络错误和 AbortError 也需要处理;对于写请求,这些错误同样先核对结果。此封装不自动重试,也不用于下载二进制。 + +### 列表和文件读取 + +```typescript +async function loadProjects(type: string | undefined, keyword: string) { + const query = new URLSearchParams({ page: '1', size: '20' }); + if (type) query.set('type', type); + if (keyword.trim()) query.set('keyword', keyword.trim()); + return request>(`/community/projects?${query}`); +} + +async function readWorkspaceFile(projectCode: string, path: string, token: string) { + const query = new URLSearchParams({ path }); + return request( + `/workspace/projects/${encodeURIComponent(projectCode)}/files?${query}`, + { token }, + ); +} +``` + +需要 liked 状态时,列表请求也传入有效 token。 + +### 上传示例 + +```typescript +async function uploadFiles( + projectCode: string, + expectedCommitSha: string, + files: File[], + token: string, +) { + const form = new FormData(); + form.append('expectedCommitSha', expectedCommitSha); + form.append('message', '上传模型文件'); + form.append('directory', 'models'); + for (const file of files) { + form.append('files', file, file.name); + form.append('paths', file.name); // 也可改为相对于 models 的多级路径 + } + return request( + `/workspace/projects/${encodeURIComponent(projectCode)}/uploads/commit`, + { method: 'POST', token, body: form }, + ); +} +``` + +### 工作区下载示例 + +```typescript +async function downloadWorkspaceFile(projectCode: string, path: string, token: string) { + const query = new URLSearchParams({ path, download: 'true' }); + const response = await fetch( + `${API_BASE}/workspace/projects/${encodeURIComponent(projectCode)}/files?${query}`, + { headers: { Authorization: `Bearer ${token}` } }, + ); + if (!response.ok) { + const result = await response.json(); + throw new ApiError( + response.status, result.code, result.message, + result.requestId ?? response.headers.get('X-Request-Id'), result.data, + ); + } + const objectUrl = URL.createObjectURL(await response.blob()); + const link = document.createElement('a'); + link.href = objectUrl; + link.download = path.split('/').pop() || 'download'; + document.body.appendChild(link); + link.click(); + link.remove(); + setTimeout(() => URL.revokeObjectURL(objectUrl), 0); +} +``` + +### UTC 时间解析 + +只对项目、评论中不带时区的 UTC 字段使用这个函数;历史 authorDate 已带时区时按其原值解析。 + +```typescript +function parseUtcTime(value: UtcDateTime): Date { + const hasTimezone = /(?:Z|[+-]\d{2}:\d{2})$/i.test(value); + return new Date(hasTimezone ? value : `${value}Z`); +} +``` + +### 开发代理示例 + +使用 Vite 时可在现有配置中加入以下 server 配置,保留 `/api` 路径,不进行 rewrite: + +```typescript +export default { + server: { + proxy: { + '/api': { + target: 'http://localhost:8993', + changeOrigin: true, + }, + }, + }, +}; +``` + +## 后端人工核对 + +本节供前端遇到写入结果不明时与后端协作使用。记录 projectCode、requestId、接口路径及操作时间,提供给后端;不要在日志或工单中记录 Token、验证码答案、邮箱或文件内容。 + +后端先按 projectCode 对应的固定仓库名核对仓库、文件与提交历史。初始化未完成的项目核对后修正 repo_status 和仓库映射;确认没有远端写入仍在执行后,再重启后端解除本机待核对标记。超时不能直接视为未提交后再次写入。数据库结构见 [四表数据库说明](database.md)。 diff --git a/docs/database.md b/docs/database.md new file mode 100644 index 0000000..76cd72b --- /dev/null +++ b/docs/database.md @@ -0,0 +1,80 @@ +# 数据库初始化 + +业务数据库名为 `community`,只包含以下四张表。由人工执行;应用不运行迁移或自动建表。以下 SQL 面向 MySQL 8。 + +```sql +CREATE DATABASE IF NOT EXISTS community CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; +USE community; + +CREATE TABLE sys_user ( + id BIGINT NOT NULL AUTO_INCREMENT COMMENT '内部用户主键', + user_code CHAR(32) NOT NULL COMMENT '用户业务编码', + email VARCHAR(254) NOT NULL COMMENT '规范化后的登录邮箱', + nickname VARCHAR(100) NOT NULL COMMENT '用户昵称', + status VARCHAR(16) NOT NULL DEFAULT 'ACTIVE' COMMENT '账号状态', + created_at DATETIME(3) NOT NULL COMMENT '创建时间 UTC', + updated_at DATETIME(3) NOT NULL COMMENT '更新时间 UTC', + PRIMARY KEY (id), + UNIQUE KEY uk_user_code (user_code), + UNIQUE KEY uk_user_email (email) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='平台用户'; + +CREATE TABLE project ( + id BIGINT NOT NULL AUTO_INCREMENT COMMENT '内部项目主键', + project_code CHAR(32) NOT NULL COMMENT '项目业务编码', + owner_user_id BIGINT NOT NULL COMMENT '所属平台用户', + name VARCHAR(100) NOT NULL COMMENT '项目名称', + description TEXT NOT NULL COMMENT '项目描述', + project_type VARCHAR(64) NOT NULL COMMENT '配置中的项目类型编码', + gitea_repo_id BIGINT NULL COMMENT 'Gitea 仓库标识', + gitea_owner VARCHAR(100) NOT NULL COMMENT 'Gitea 仓库所属组织', + gitea_repo_name VARCHAR(100) NOT NULL COMMENT 'Gitea 仓库名称', + repo_status VARCHAR(16) NOT NULL DEFAULT 'CREATING' COMMENT '仓库状态 CREATING READY FAILED', + publish_status VARCHAR(16) NOT NULL DEFAULT 'UNPUBLISHED' COMMENT '社区状态 UNPUBLISHED PUBLISHED', + published_commit_sha VARCHAR(64) NULL COMMENT '社区已发布 Commit SHA', + published_at DATETIME(3) NULL COMMENT '最近发布时间 UTC', + source_project_id BIGINT NULL COMMENT 'Fork 来源项目', + source_commit_sha VARCHAR(64) NULL COMMENT 'Fork 来源已发布 Commit SHA', + deleted TINYINT(1) NOT NULL DEFAULT 0 COMMENT '逻辑删除标识', + created_at DATETIME(3) NOT NULL COMMENT '创建时间 UTC', + updated_at DATETIME(3) NOT NULL COMMENT '更新时间 UTC', + PRIMARY KEY (id), + UNIQUE KEY uk_project_code (project_code), + UNIQUE KEY uk_project_repo (gitea_owner, gitea_repo_name), + UNIQUE KEY uk_project_repo_id (gitea_repo_id), + KEY idx_project_owner (owner_user_id, deleted, created_at), + KEY idx_project_community (publish_status, deleted, published_at), + KEY idx_project_type (publish_status, deleted, project_type, published_at), + CONSTRAINT fk_project_owner FOREIGN KEY (owner_user_id) REFERENCES sys_user(id), + CONSTRAINT fk_project_source FOREIGN KEY (source_project_id) REFERENCES project(id) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='用户项目与社区发布'; + +CREATE TABLE project_comment ( + id BIGINT NOT NULL AUTO_INCREMENT COMMENT '内部评论主键', + comment_code CHAR(32) NOT NULL COMMENT '评论业务编码', + project_id BIGINT NOT NULL COMMENT '所属项目', + user_id BIGINT NOT NULL COMMENT '评论用户', + content TEXT NOT NULL COMMENT '纯文本评论内容', + deleted TINYINT(1) NOT NULL DEFAULT 0 COMMENT '逻辑删除标识', + created_at DATETIME(3) NOT NULL COMMENT '创建时间 UTC', + updated_at DATETIME(3) NOT NULL COMMENT '更新时间 UTC', + PRIMARY KEY (id), + UNIQUE KEY uk_comment_code (comment_code), + KEY idx_comment_project (project_id, deleted, created_at), + CONSTRAINT fk_comment_project FOREIGN KEY (project_id) REFERENCES project(id), + CONSTRAINT fk_comment_user FOREIGN KEY (user_id) REFERENCES sys_user(id) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='项目评论'; + +CREATE TABLE project_like ( + id BIGINT NOT NULL AUTO_INCREMENT COMMENT '内部点赞主键', + project_id BIGINT NOT NULL COMMENT '所属项目', + user_id BIGINT NOT NULL COMMENT '点赞用户', + created_at DATETIME(3) NOT NULL COMMENT '点赞时间 UTC', + PRIMARY KEY (id), + UNIQUE KEY uk_like_project_user (project_id, user_id), + CONSTRAINT fk_like_project FOREIGN KEY (project_id) REFERENCES project(id), + CONSTRAINT fk_like_user FOREIGN KEY (user_id) REFERENCES sys_user(id) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='项目点赞'; +``` + +内部 ID 仅用于数据库关联,对外使用业务编码。时间均由后端写入 UTC。`CREATING` 项目表示仓库初始化未完成,不代表编辑草稿。Gitea 数据库与业务库分离,不修改 Gitea 内部表。 diff --git a/pom.xml b/pom.xml new file mode 100644 index 0000000..a6c34a6 --- /dev/null +++ b/pom.xml @@ -0,0 +1,58 @@ + + + 4.0.0 + + org.springframework.boot + spring-boot-starter-parent + 3.5.7 + + + com.linkerbot + community + 0.0.1-SNAPSHOT + pom + + community-common + community-bean + community-service + community-security + community-api + + + 21 + 3.5.11 + 2.8.14 + UTF-8 + + + + + com.baomidou + mybatis-plus-spring-boot3-starter + ${mybatis-plus.version} + + + com.baomidou + mybatis-plus-jsqlparser + ${mybatis-plus.version} + + + org.springdoc + springdoc-openapi-starter-webmvc-ui + ${springdoc.version} + + + + + + org.projectlombok + lombok + true + + + org.springframework.boot + spring-boot-starter-test + test + + + diff --git a/scripts/run-local.sh b/scripts/run-local.sh new file mode 100644 index 0000000..e8a148d --- /dev/null +++ b/scripts/run-local.sh @@ -0,0 +1,12 @@ +#!/usr/bin/env bash +set -euo pipefail +COMMUNITY_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +if [[ -f "$COMMUNITY_ROOT/.env" ]]; then + set -a + source "$COMMUNITY_ROOT/.env" + set +a +fi +export SPRING_PROFILES_ACTIVE="${SPRING_PROFILES_ACTIVE:-test}" +cd "$COMMUNITY_ROOT" +mvn -q -DskipTests package +exec java -Djava.awt.headless=true -jar community-api/target/community-api-0.0.1-SNAPSHOT.jar "$@" diff --git a/scripts/test-gitea.py b/scripts/test-gitea.py new file mode 100644 index 0000000..facf48c --- /dev/null +++ b/scripts/test-gitea.py @@ -0,0 +1,24 @@ +#!/usr/bin/env python3 +"""在临时 H2 数据库运行真实 Gitea 测试,清理本次创建的临时仓库。""" +import os +from pathlib import Path +import shlex +import subprocess + +root = Path(__file__).resolve().parent.parent +environment = os.environ.copy() +config = root / ".env" +if config.exists(): + for line in config.read_text().splitlines(): + if not line or line.startswith("#") or "=" not in line: + continue + key, value = line.split("=", 1) + parsed = shlex.split(value) + if parsed: + environment[key] = parsed[0] +if not environment.get("GITEA_TOKEN"): + raise SystemExit("请先配置 GITEA_TOKEN 和 GITEA_ORGANIZATION") +environment["COMMUNITY_LIVE_GITEA"] = "true" +raise SystemExit(subprocess.call([ + "mvn", "-q", "-Dtest=GiteaLiveTest", "-Dsurefire.failIfNoSpecifiedTests=false", "test" +], cwd=root, env=environment))