Files
youlai-boot/AGENTS.md
T

16 KiB
Raw Blame History

AGENTS.md

本仓库是 youlai-boot 的 TTSTD 定制分支,用于老年平板设备管理:设备端(sn)、家属端(client)、运营后台(device / app)。

1. 与 Gitee 上游的关系(最高优先级)

远程仓库:

remote 地址 用途
gitee git@gitee.com:youlaiorg/youlai-boot.git 上游只读(push 已禁用),只用于比对/同步
origin ssh://git@gitea.ttstd.com:2222/tt/youlai-boot.git 我方仓库

只有以下目录是我方新增的业务代码,可自由新增/修改:

目录 职责
src/main/java/com/youlai/boot/app/ 客户端应用管理:应用分类、应用包(APK/XAPK/APKM 解析、上传、Mongo 存储)
src/main/java/com/youlai/boot/client/ 家属端:App 用户、通讯录、设备操作、文件
src/main/java/com/youlai/boot/device/ 设备管理:sn 设备、截图、壁纸、策略、告警、APK 安装、硬件/网络/安全/系统信息
src/main/java/com/youlai/boot/open/ 家属端开放认证:短信登录、密码登录、注册、重置密码
src/main/java/com/youlai/boot/common/config/ StorageDir(对象存储业务目录)

其余所有目录(auth/、system/、framework/、support/、config/、module/、codegen/ 等)都来自上游,尽量保持不动。

修改前必做检查

git fetch gitee
git ls-tree -r --name-only gitee/master -- src/main/java/com/youlai/boot/xxx   # 上游是否存在该文件
git log --oneline gitee/master -- src/main/java/com/youlai/boot/xxx            # 上游是否有近期改动
  • 上游存在该文件 → 尽量不改。优先在五个自有目录内新增类/扩展点(继承、实现接口、新增 Controller)来满足需求。
  • 确实必须改上游文件时:只做最小必要改动,不做格式化/重命名/顺带重构,提交信息注明原因,例如 chore(upstream): 安全配置放行 /api/v1/xxx 以支持新模块。
  • 上游不存在该文件 → 可新增,但应落在上述五个目录内。

已登记的例外清单

以下改动位于上游目录,属结构性必要或历史遗留。请勿删除、重构或格式化,修改前先确认调用方。

A. 上游目录中新增的文件(上游不存在,因框架结构必须留在原包)

位置 说明
common/constant/ClientTypeConstants.java 端标识(admin / client)
common/util/{HashUtils, FileUtils, RedisSafeOps, CodeGeneratorUtil}.java 校验值、文件、Redis 安全操作、编码生成工具
config/{DataSourceConfig, RedissonConfig, MqttConfig, RedisHealthConfig}.java、config/property/MqttProperties.java 多数据源、分布式锁、MQTT、Redis 健康检查
framework/security/filter/{MobileApiSignatureFilter, CachedBodyRequestWrapper}.java 设备端 ECDSA 验签过滤器与请求体缓存
framework/security/signature/DeviceSignatureVerifier.java 设备签名校验
framework/security/authorization/ClientAccessAuthorizationManager.java 家属端令牌隔离
support/mqtt/{MqttController, MqttMessageHandler, MqttProducer}.java MQTT 上报/推送
support/webrtc/** WebRTC 信令(/ws/signal)
support/sms/SmsResult.java 短信发送结果
resources/mapper/system/DeviceMapper.xml 设备分页查询
test/java/com/youlai/boot/app/packages/component/ApkMetaParserTest.java 安装包解析测试

B. 被修改的上游文件(只允许最小增补,不做重构/格式化)

文件 允许的改动范围
config/SecurityConfig.java 放行 /api/v1/sn/**、/api/v1/open/**、/ws/signal;/api/v1/client/** 走 ClientAccessAuthorizationManager
config/JacksonConfig.java 保持上游原样(不得添加未使用的 import / 注释代码)
config/RedisConfig.java 仅 @Lazy 延迟初始化;序列化方式必须与上游一致
framework/security/config/SecurityProperties.java client 端令牌 TTL 两个字段
framework/security/model/{SecurityUser, SecurityUserDetails}.java clientType 字段
framework/security/token/JwtTokenManager.java client 端 TTL 解析、clientType claim、校验失败日志
common/constant/JwtClaimConstants.java、common/constant/RedisConstants.java clientType claim、设备在线 key、短信验证码 key
common/enums/{ActionTypeEnum, LogModuleEnum}.java、common/result/ResultCode.java 仅追加新枚举值/错误码
framework/web/advice/GlobalExceptionHandler.java Redis 相关异常、SSE 超时、静态资源 404
framework/web/log/OperationLogAspect.java 设备无登录会话时的操作人兜底;error_msg 上限 2000
system/service/impl/ConfigServiceImpl.java 缓存预热失败不阻断启动
support/file/model/FileInfo.java、support/file/service/impl/LocalFileServiceImpl.java md5/sha1/sha256 校验值
support/file/service/FileService.java、support/file/service/impl/{AliyunFileServiceImpl, S3FileServiceImpl, LocalFileServiceImpl}.java 仅新增 uploadFile(MultipartFile, String directory) 重载(供我方新增接口使用);阿里云 domain 配置及 deleteFile 的 key 解析适配(兼容自定义域名)。uploadFile(MultipartFile) 保持上游日期目录行为;system/controller/FileController.java 保持上游原样
support/sms/{SmsTypeEnum, service/SmsService, service/impl/AliyunSmsServiceImpl}.java sendWithResult,按响应码判定成败
support/sse/{SseService, SseSessionManager, constant/SseEventConstants}.java 设备事件主题
pom.xml 新增依赖(websocket、mongodb、mqtt、apk-parser、apkanalyzer、redisson 等)
.gitignore 目前仅新增 /uploadFile/
resources/application-dev.yml、resources/application-prod.yml 数据源(mysql/tdengine)、redis、mongodb、oss、sms、mqtt、安全白名单、令牌 TTL
sql/youlai-admin.sql sys_log.error_msg 由 1000 调整为 2000

C. 数据与运维脚本(非 Java 代码,允许新增)

  • sql/ttstd/*.sql:业务建表、菜单/权限、数据修复等脚本统一放这里。
  • docs/sql/*.sql:部署/运维类脚本(如 TDengine、EMQX 规则)。
  • docker/*。

D. 禁止事项

  • 上游文件里做格式化、重命名、import 重排、注释掉代码等无关改动。
  • 配置文件提交真实凭证:密码/AccessKey 一律用环境变量或本地 profile 覆盖,不写入版本库。
  • 在上游目录新增 Java 类(应放到自有目录,例如 ByteArrayMultipartFile 放在 app/packages/component/)。
  • 为适配我方上传规则去改 gitee 上游已有的上传接口(POST /api/v1/files、system/controller/FileController):上游已有的不管,规则只加在我方新增接口上。

2. 技术栈

Java 17 · Spring Boot 4.0.5 · Spring Security · MyBatis-Plus 3.5.15 · MySQL · Redis + Redisson · MongoDB(spring-boot-starter-data-mongodb) · WebSocket · knife4j/springdoc · MapStruct + Lombok · Hutool · apk-parser / apkanalyzer

3. 构建与运行

mvn -DskipTests clean package                                  # 打包,产物 target/youlai-boot-4.12.0.jar
mvn test                                                       # 测试
java -jar target/youlai-boot-4.12.0.jar --spring.profiles.active=dev
  • 默认 profile 为 dev(application.yml),配置见 application-dev.yml / application-prod.yml;代码生成配置在 codegen.yml。
  • 数据库连接请使用本地 / 环境变量 覆盖,不要提交真实账号密码。
  • Windows 上 shell 为 PowerShell,勿使用 head/tail/cd /d 等 cmd/Unix 语法。

4. 代码约定

包结构(自有模块统一遵循):

xxx/
├── controller/         # @RestController,路径 /api/v1/...
├── service/            # 接口
│   └── impl/           # 实现,继承 MyBatis-Plus ServiceImpl<Mapper, Entity>
├── converter/          # MapStruct 转换器
├── mapper/             # MyBatis-Plus Mapper(自有模块一般不写 XML)
├── repository/         # Mongo 仓储(接口 + impl,用 MongoTemplate)
└── model/
    ├── entity/         # MySQL 实体(设备相关以 Sn 前缀命名,如 SnDeviceInfo)
    ├── document/       # Mongo 文档(如 AppPackageDocument)
    ├── form/ req/ query/   # 入参
    └── vo/ dto/        # 出参
  • 统一返回 Result<T> / PageResult<T>,分页参数用 PageQuery,分页结果用 IPage。
  • 构造器注入:类加 @RequiredArgsConstructor,字段 private final。
  • 接口文档:@Tag(name = "序号.名称") + @Operation(summary = ...)。
  • 操作日志:@Log(module = LogModuleEnum.X, value = ActionTypeEnum.Y)。
  • 鉴权分区:
    • /api/v1/sn/**:设备端,MobileApiSignatureFilter 做 ECDSA 设备签名校验(非 JWT)
    • /api/v1/client/**:家属端,仅接受 clientType=client 的令牌
    • /api/v1/open/**:免登录(登录/注册/找回密码)
    • 后台接口(/api/v1/device、/api/v1/app/**、/api/v1/developers 等):走 Spring Security,按需 @PreAuthorize
  • 我方新增接口的业务文件统一通过 FileService#uploadFile(MultipartFile, String directory) 存到 StorageDir 定义的固定目录(app/icon、app/package-icon、app/package、app/screenshot、app/avatar、app/wallpaper、app/category-icon、app/file、tablet/screenshot),实际存储由 storage.type(s3 / aliyun / local)决定;不按上传日期分目录。
  • 上游 FileService#uploadFile(MultipartFile) 及其 Aliyun/S3/Local 三个实现保持 gitee 行为(yyyyMMdd/ 日期目录,本地实现不算哈希),只由上游 POST /api/v1/files 使用,不得修改其语义。
  • 头像:家属端走 POST /api/v1/client/files/avatar,落 app/avatar。管理端头像继续用上游 POST /api/v1/files,system/controller/FileController 保持 gitee 原样(不再提供 /api/v1/files/avatar)。
  • 文件上传规则的改动边界:涉及存储目录、对象命名、扩展名校验、URL 生成等上传规则调整时,只允许改我方新增的接口与实现(/api/v1/client/files/**、/api/v1/sn/** 等);gitee 上游已有的上传接口(POST /api/v1/files、system/controller/FileController 及其调用的 FileService 原方法)保持上游原样,不因我方需求改其入参、出参、校验与行为。
  • 所有业务文件(安装包、图标、截图、壁纸、头像等)统一经 FileService 落 StorageDir 目录,不落本地磁盘、不提供 /static 访问映射。
  • 新增后台菜单/表结构请补充 sql/ttstd/ 脚本,保持与代码同步。

5. 提交约定

采用 Conventional Commits(feat(device): ...、fix(client): ...、refactor(config): ...、chore: ...)。涉及上游文件的改动需在正文说明原因。

6. 不做兼容(强制)

变更直接定案,不写向后兼容代码:

  • 接口入参/出参、字段语义、存储路径变更时,直接改成目标形态;禁止可选参数、双分支、"不传则走旧逻辑"、"新老格式都支持"之类的兜底写法。
  • 禁止为旧前端/旧设备端保留旧接口、旧字段或旧 URL 前缀;需要它们同步修改时,在提交说明中列明改动点。
  • 存储位置由业务语义决定:一类资源对应 StorageDir 中的一个固定常量,使用专用接口落盘(如 POST /api/v1/client/files/avatar),不得让调用方通过 directory 之类的参数决定目录。该约定仅约束我方新增接口,不改动上游 POST /api/v1/files。
  • 存量历史数据(旧本地路径、旧对象目录、旧字段格式)只允许用一次性迁移脚本或管理接口处理,不得在业务代码中长期保留运行时回退分支。

7. 生产部署(k3s)

7.1 环境

项 值
服务器 175.178.213.60,root 登录(密码/密钥不写入仓库,走本地运维渠道)
集群 单节点 k3s,namespace youlai
工作负载 deploy/youlai-boot,单副本,Recreate 策略
端口 容器 8000,Service NodePort 30800
公网入口 https://api.ttstd.com(服务器 nginx 反代到 30800)
健康检查 /api/v1/health(readiness 45s 起、liveness 120s 起)
Spring Profile prod(配置见 src/main/resources/application-prod.yml)

7.2 服务器上的文件与变量位置

路径 作用
/opt/youlai-boot/redeploy.sh 部署入口:追加 jar 层 → 导入 k3s containerd → set image + rollout restart
/opt/youlai-boot/build_image.py 被 redeploy.sh 调用,拼装镜像 manifest
/opt/youlai-boot/deploy.yaml Namespace / Deployment / Service 清单(JVM 参数、资源限额、探针、envFrom 均在此)
/opt/youlai-boot/app.jar 当前生产 jar(部署成功后替换)
/opt/youlai-boot/app.jar.new 新 jar 上传暂存路径
/opt/youlai-boot/app-*.jar、album-*、profile-* 历史 jar / 版本留档,回滚时使用
  • redeploy.sh 内变量:JAR、TAG(参数)、IMG=docker.io/library/youlai-boot:<TAG>、BASE=docker.m.daocloud.io/library/eclipse-temurin:17-jre、W=/opt/imgwork。
  • 运行参数在 deploy.yaml:-Xms128m -Xmx384m -XX:MaxMetaspaceSize=192m -XX:+UseSerialGC,requests 300m/384Mi、limits 1500m/768Mi。
  • 敏感配置不在仓库:短信等密钥由 Secret youlai-sms 通过 envFrom 注入;数据源、Redis、MQTT 等在 application-prod.yml,改动后随 jar 一起发布。
  • 不要用 docker build:服务器无法访问 Docker Hub,脚本改为把 jar 作为新层追加到已缓存的 eclipse-temurin:17-jre 上;该基础镜像必须已存在于节点 containerd。

7.3 部署步骤

# 1. 本地打包(会包含工作区未提交改动,发布前先确认 git status)
mvn -B -DskipTests clean package
sha256sum target/youlai-boot.jar

# 2. 上传到暂存路径
pscp -P 22 target/youlai-boot.jar root@175.178.213.60:/opt/youlai-boot/app.jar.new

# 3. 校验上传完整性
plink -ssh root@175.178.213.60 "sha256sum /opt/youlai-boot/app.jar.new"

# 4. 构建镜像并滚动重启
plink -ssh root@175.178.213.60 "bash /opt/youlai-boot/redeploy.sh /opt/youlai-boot/app.jar.new <tag>"

# 5. 验收
plink -ssh root@175.178.213.60 "kubectl -n youlai get pods -o wide; \
  kubectl -n youlai get deploy youlai-boot -o jsonpath='{.spec.template.spec.containers[0].image}{\"\n\"}'; \
  curl -s -o /dev/null -w 'health:%{http_code}\n' http://127.0.0.1:30800/api/v1/health; \
  kubectl -n youlai exec deploy/youlai-boot -- sha256sum /app/app.jar"

# 6. 用新 jar 覆盖现网留档
plink -ssh root@175.178.213.60 "cd /opt/youlai-boot && mv -f app.jar.new app.jar"
  • Tag 约定:<pom 版本>-<主题>-<yyyymmdd>-<短提交号>,如 4.14.1-wip-20261109-4dd7d98c;同一 tag 重建必须依赖脚本内的 rollout restart,否则 kubelet 继续用旧镜像。
  • Recreate + 单副本:发布期间服务短暂不可用;新 Pod 冷启动约 1–2 分钟,这段时间 health:000、rollout status 超时属正常,等 Pod Running 后复查。
  • redeploy.sh 不 kubectl apply deploy.yaml;改 JVM 参数、资源、探针、环境变量时,先改 deploy.yaml 再 kubectl apply -f /opt/youlai-boot/deploy.yaml。
  • 回滚:kubectl -n youlai set image deploy/youlai-boot app=docker.io/library/youlai-boot:<上一 tag> 后 kubectl -n youlai rollout restart deploy/youlai-boot,再走第 5 步验收。
  • 排障:kubectl -n youlai logs deploy/youlai-boot --tail=200、kubectl -n youlai describe pod -l app=youlai-boot、journalctl -u k3s --since '1 hour ago'。节点内存较紧(3.6Gi,容器上限 768Mi),关注探针超时与 OOM。