Author SHA1 Message Date
cat-shark ddf0256210 docs: 同步 API 端点总览 2026-10-22 21:59:53 +08:00
cat-shark 0618c3970a test: 测试数据改为按目录组织,不再放进 Flyway 迁移 2026-10-22 21:59:53 +08:00
cat-shark c59efa3676 feat: 新增任务下拉选项接口 2026-10-22 21:59:53 +08:00
cat-shark 05939e3f08 feat: 新增标签导图列表接口 2026-10-22 21:59:40 +08:00
cat-shark a0a35faec8 feat: 复习总览分页与全局汇总 2026-10-22 21:59:30 +08:00
cat-shark c4017cc964 fix: 分页拦截器改到租户拦截器之后注册 2026-10-22 21:59:03 +08:00
cat-shark 13e12ba4da feat: 报告作为思维导图生成的参考上下文 2026-10-22 21:58:50 +08:00
cat-shark 6075839937 fix: 索引键长守卫漏检 CREATE INDEX
守卫一直没真正生效,两个独立缺陷:

1. CREATE INDEX 用 matches() 匹配,语句行尾的分号让它整条不匹配 ——
   仓库里 8 条独立 CREATE INDEX(含 V20261009_1 那批业务索引)全被静默跳过;
2. 多行 ALTER TABLE 的子句写在下一行,逐行解析拿到的 rest 是空的,
   由它新增的列从未登记;且守卫是在所有迁移解析完之后才解析列,
   用最终 schema 去解析早期索引,列被后续迁移改名时会误报「列无法解析」。

改为:ALTER TABLE 拼回续行、列类型在索引声明当时记录。
已用三个探针验证:引用不存在的列被拦、4080 字节超长被拦、真实迁移全绿。
2026-10-10 20:28:17 +08:00
cat-shark 1ba3ae5a04 feat: 用量统计支持用户维度报表
- 新增 ai_usage_records.user_id 与 (user_id, occurred_at) 索引,NULL 表示未归属
- 归属标记跟着请求走:AiServiceClient 提交任务时带上顶层 callerRef(当前用户 id),
  lpt-ai 原样透传,上报后落到 user_id。取不到身份就不带,绝不让 AI 调用因此失败
- breakdown 支持 groupBy=user,新增 label(登录名,未归属为「未归属」);
  summary/series/breakdown 支持 userId 过滤
2026-10-10 20:28:04 +08:00
cat-shark 650b0956de feat: 新增 AI 用量落库与统计接口
- 新增 ai_usage_records 表(系统级表,不按租户过滤)与幂等上报接口
- 新增按时间/任务类型/模型的汇总、趋势、明细查询,仅白名单用户可见
- 登录响应返回 aiAdmin,供前端决定是否展示入口
2026-10-10 18:46:01 +08:00
cat-shark 02d5c24946 fix: 标签移除后再打同名标签不再撞唯一键 2026-10-10 16:41:27 +08:00
cat-shark 4b30c88b7f feat: 标签范围回忆对比与记录口径 2026-10-10 16:08:48 +08:00
cat-shark 6a30022af5 feat: 新增标签导图存储与生成 2026-10-10 15:28:06 +08:00
cat-shark d282f1b10a docs: 移除与 meta 重复的提交规范正文 2026-10-10 15:10:06 +08:00
cat-shark 8065550924 docs: 规则分离到 roles 目录 2026-10-10 15:08:37 +08:00
cat-shark 6ea408e558 feat: 新增标签字典与打标签候选接口 2026-10-10 14:59:06 +08:00
cat-shark 99290d9fae feat: 残片归属时自动打任务名标签 2026-10-10 14:58:14 +08:00
cat-shark 7acfc7effa fix: 任务主键改由数据库自增 2026-10-10 14:55:46 +08:00
cat-shark 6bbb2362d3 docs: 通用规则收口径到 meta 的 .agents/roles 2026-10-10 14:38:43 +08:00
cat-shark f1a078ce64 docs: 补充并行与委派规则 2026-10-10 14:27:43 +08:00
cat-shark a558e2a08a fix: 学习引导不再复用进行中的任务 2026-10-10 10:52:11 +08:00
cat-shark 7fc08ebef3 fix: 透传 lpt-ai 的失败原因,避免误导成「AI 没有回应」 2026-10-10 10:41:14 +08:00
cat-shark 935a4fac00 docs: 补充 H2 与 MySQL 的迁移差异与守卫测试 2026-10-09 21:00:45 +08:00
cat-shark e5b3ef8eb6 fix: 缩短标记唯一键避免超出 InnoDB 索引长度上限 2026-10-09 21:00:33 +08:00
cat-shark dbeafba23c perf: Feed 只返回摘要与原文长度 2026-10-09 19:35:15 +08:00
cat-shark 4da3b78fa4 docs: 明确报告分段顺序 2026-10-09 19:32:50 +08:00
cat-shark e6e47e31b0 docs: 补充标记与学习引导约定并更新端点清单 2026-10-09 19:31:25 +08:00
cat-shark b51a6216ce feat: 新增学习引导链路与来源标记 2026-10-09 19:30:59 +08:00
cat-shark c6258fa6d7 feat: 新增统一标记存储与单一标记筛选 2026-10-09 19:25:34 +08:00
cat-shark 63824b26a0 feat: 新增复习反馈动作与排序三档偏好 2026-10-09 19:21:26 +08:00
cat-shark 1a99263876 test: 放宽异步投递用例的等待窗口避免抖动 2026-10-09 19:16:39 +08:00
cat-shark 3dda26307d perf: 覆盖率查询改为按任务分组取最新 2026-10-09 19:14:36 +08:00
cat-shark 7408be26c0 docs: 更新端点清单并补内容归属约定 2026-10-09 19:12:35 +08:00
cat-shark c74f73ac3c feat: 拆分记录上下文与内容归属并把报告改为结构化 2026-10-09 19:12:04 +08:00
cat-shark 9a86eadb52 chore: 移除测试控制器与测试表相关代码 2026-10-09 17:55:32 +08:00
cat-shark bad7d6b9c9 docs: 补充 AI 入站令牌配置说明 2026-10-09 15:52:39 +08:00
cat-shark 251a46887c feat: 复习 Feed 随机取样改用主键区间并固定 actuator 清单 2026-10-09 15:51:50 +08:00
cat-shark cb450b6f47 docs: 补充 AI 异步链路约定与端点变更 2026-10-09 15:07:43 +08:00
cat-shark cf380c5f09 feat: AI 调用改为异步任务并支持结果重复获取 2026-10-09 15:07:15 +08:00
cat-shark 0b695f54bf perf: 复习统计聚合下推到数据库 2026-10-09 14:56:36 +08:00
cat-shark db552182ae feat: 悬挂学习会话惰性收敛与定时兜底 2026-10-09 12:32:11 +08:00
cat-shark faaaa132c1 feat: 新增学习数据导出接口 2026-10-09 12:20:36 +08:00
cat-shark 3cc3be1c8b fix: 业务编号追加随机位并加唯一约束 2026-10-09 12:20:36 +08:00
cat-shark 67c8711eee refactor: 复习耗时聚合改为强类型结果并补充数据访问规范 2026-10-09 11:53:41 +08:00
cat-shark 3b33cd8396 feat: 新增复习耗时统计与按任务汇总 2026-10-09 11:12:37 +08:00
cat-shark af13bd57b7 fix: 生产环境不再打印全部 SQL 2026-10-09 10:52:20 +08:00
cat-shark e506c4d751 perf: 为业务主表补充索引 2026-10-09 10:52:20 +08:00
cat-shark d8c8b76c32 fix: 统一学习会话结算并修正结束幂等 2026-10-09 10:48:12 +08:00
cat-shark 04d1f40c6c fix: 容器固定为 Asia/Shanghai 时区 2026-10-08 12:11:54 +08:00
cat-shark 16149e83ee test: 补充后端单元测试与覆盖率配置 2026-09-19 22:33:25 +08:00
cat-shark 5e0b922b3f test: 补齐测试环境 cors 配置 2026-09-19 22:33:21 +08:00
cat-shark 3e4c0645ad docs: 修正紧急性维度注释命名 2026-09-13 22:55:26 +08:00
cat-shark 11a7c8aaea chore: 添加 .gitattributes 规范行尾 2026-08-26 21:13:14 +08:00
cat-shark e691dfaa95 docs: 更新 API 端点总览 2026-08-26 21:13:14 +08:00
cat-shark a6f684c8b7 feat: 新增会话误操作结束接口 2026-08-15 21:24:59 +08:00
cat-shark 0413013f24 docs: 移除仓库文档 2026-08-05 23:35:10 +08:00
cat-shark 9595ad92ee merge: 合并残片报告拆分到dev 2026-08-03 23:20:01 +08:00
cat-shark 6678c2b8c0 refactor: 优化用户可见错误提示 2026-08-03 23:08:26 +08:00
cat-shark b434520eff refactor: 标准导图仅使用报告生成 2026-08-03 23:08:19 +08:00
cat-shark 5b6f7d6a2a refactor: 首页feed仅返回残片 2026-08-03 23:08:14 +08:00
cat-shark c8d0584f11 docs: 补充用户提示规范 2026-08-03 23:08:08 +08:00
cat-shark 8c272dc1dc fix: 流水线kubeconfig改用临时目录 2026-08-02 10:51:03 +08:00
cat-shark e42b15600a chore: 移除Jenkins配置 2026-08-02 10:21:05 +08:00
cat-shark e32226d7d2 docs: 合并CLAUDE规范 2026-08-01 00:15:56 +08:00
cat-shark b61736eb2b docs: migrate .pi/SYSTEM.md to AGENTS.md 2026-08-01 00:13:05 +08:00
cat-shark 8ed5631969 perf: multi-stage Dockerfile + remove Maven from CI — Docker layer caching instead 2026-07-26 23:07:56 +08:00
cat-shark 65ee61c6c9 fix: add shell: bash to CI steps — maven container uses sh by default 2026-07-26 22:06:33 +08:00
cat-shark 09e67cd834 chore: remove k8s/ — migrated to lpt-infra 2026-07-26 21:35:51 +08:00
cat-shark fd317b7932 docs: 补充Git提交规范 2026-07-23 23:03:21 +08:00
cat-shark 859dab9401 docs: add .pi/SYSTEM.md with project overview 2026-07-23 23:01:47 +08:00
cat-sharkandClaude Opus 4.8 4f99f31475 fix(ci): 绑定分支与部署环境并加固 IMAGE_TAG 传递
- dev 仅允许 dev 分支,prod 仅允许 master/main
- IMAGE_TAG 写 env 文件 + image_tag.txt 兜底
- checkout 时确保 maven 容器内安装 git

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-20 22:46:17 +08:00
cat-sharkandClaude Opus 4.8 43580dd1fd Add Kubernetes deployment configurations
- Add deployment.yaml with imagePullSecrets and env configuration
- Add service.yaml with NodePort configuration
- Configure Spring Boot environment variables from ConfigMap and Secrets
- Ensures proper image pull authentication from private registry

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-20 21:23:59 +08:00
cat-shark d5d9b7aa99 feat(ci): 添加 imagePullSecret 自动创建步骤 2026-07-19 22:45:59 +08:00
cat-shark 6eca6de249 feat(ci): 添加部署失败时的调试输出 2026-07-19 22:27:12 +08:00
cat-shark a42df9d521 feat(ci): 使用时间戳标签确保每次部署都触发更新 2026-07-19 21:56:14 +08:00
cat-shark 015ecd13d8 fix(ci): 使用命名 volume 避免挂载冲突 2026-07-19 21:31:18 +08:00
cat-shark 8abd750dfb debug(ci): 添加 Docker 安装调试信息 2026-07-19 21:24:03 +08:00
cat-shark f8e24ffdf0 fix(ci): 挂载 Docker socket 并安装 Docker CLI 2026-07-19 21:18:47 +08:00
cat-shark 688be6b65f feat(ci): 缓存 Maven 本地仓库,避免重复下载依赖 2026-07-19 21:17:45 +08:00
cat-shark a6e75f6e97 fix(ci): 使用容器自带的 mvn 替代 mvnw 2026-07-19 21:14:01 +08:00
cat-shark 6cc5212eba fix(ci): 使用 maven 容器镜像,移除手动安装依赖 2026-07-19 20:56:30 +08:00
cat-shark 2d87b96a09 fix(ci): 使用绝对路径调用 apt-get (host 模式) 2026-07-19 20:49:55 +08:00
cat-shark eb2869a71d fix(ci): 移除 sudo - runner 以 root 运行 2026-07-19 20:41:58 +08:00
cat-shark 1789141a7b fix: 解决 deploy.yml 冲突 2026-07-19 20:13:05 +08:00
cat-shark b80e4c01f5 fix: Alpine compatibility - apk, docker login, /tmp/kubeconfig 2026-07-19 19:27:44 +08:00
cat-sharkandClaude Opus 4.8 b70d90d18a fix(ci): 修复部署流水线配置
- 使用 Git commit hash 作为镜像标签
- 修复 Docker 网络配置(先连接 traefik-public,再附加 mysql 网络)
- 增加健康检查超时到 120 秒
- 添加镜像清理阶段(保留 7 天)
- 修复 Gitea Actions: github.sha → gitea.sha
- 添加 Docker Registry 认证
- kubectl 版本修正为 v1.30.0
- JDK 安装添加 sudo 权限
- 添加部署失败自动回滚机制

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-19 19:12:21 +08:00
cat-shark 73fdaf82e7 fix: add docker.io install for step container (no docker CLI in runner image) 2026-07-19 19:02:23 +08:00
cat-shark 5418f23111 ci: replace actions/checkout with git clone (no Node.js in runner) 2026-07-19 18:56:02 +08:00
cat-shark 58e9e4db22 ci: add kubectl setup step with secret 2026-07-19 18:50:39 +08:00
cat-shark a6dab438d5 ci: use unique image tags (git sha) 2026-07-19 18:49:23 +08:00
cat-shark 174b4265d7 Switch to manual trigger (workflow_dispatch) 2026-07-19 18:14:06 +08:00
cat-shark 3d157ed30c Add CI/CD pipeline
lpt-be Build & Deploy / build-and-deploy (push) Failing after 4s
2026-07-19 18:07:50 +08:00
286 changed files with 21084 additions and 2124 deletions
+4
View File
@@ -0,0 +1,4 @@
# 行尾规范:文本文件统一 LF,Windows 批处理保留 CRLF
* text=auto eol=lf
*.bat text eol=crlf
*.cmd text eol=crlf
+152
View File
@@ -0,0 +1,152 @@
name: lpt-be Build & Deploy
on:
workflow_dispatch:
inputs:
environment:
description: '部署环境(dev 仅允许 dev 分支;prod 仅允许 master/main)'
required: true
type: choice
options:
- dev
- prod
env:
REGISTRY: 192.168.123.199:5000
APP: lpt-be
REPO_URL: http://git.cat-shark.xyz/cat-shark/lpt-be.git
jobs:
build-and-deploy:
runs-on: ubuntu-latest
env:
KUBECONFIG: /tmp/kubeconfig
steps:
- name: Validate branch ↔ environment
run: |
set -euo pipefail
REF="${{ gitea.ref }}"
BRANCH="${REF#refs/heads/}"
if [[ "$REF" == refs/tags/* ]]; then
echo "ERROR: 请从分支触发部署,不要用 tag。当前 ref=$REF"
exit 1
fi
ENV="${{ inputs.environment }}"
echo "branch=$BRANCH environment=$ENV sha=${{ gitea.sha }}"
case "$ENV" in
prod)
case "$BRANCH" in
master|main) echo "OK: prod 允许从 $BRANCH 部署" ;;
*)
echo "ERROR: prod 只能从 master/main 部署,当前分支是 '$BRANCH'"
echo "请切换到 master 后再 Run workflow,并选择 environment=prod"
exit 1
;;
esac
;;
dev)
case "$BRANCH" in
dev) echo "OK: dev 允许从 $BRANCH 部署" ;;
*)
echo "ERROR: dev 只能从 dev 分支部署,当前分支是 '$BRANCH'"
echo "请切换到 dev 后再 Run workflow,并选择 environment=dev"
echo "(禁止用 master 代码部署到 lpt-dev,避免环境错配)"
exit 1
;;
esac
;;
*)
echo "ERROR: 未知 environment=$ENV"
exit 1
;;
esac
- name: Checkout code
run: |
set -euo pipefail
git clone "$REPO_URL" .
git checkout "${{ gitea.sha }}"
- name: Login to Docker Registry
run: |
set -euo pipefail
echo "${{ secrets.REGISTRY_PASSWORD }}" | docker login "$REGISTRY" -u "${{ secrets.REGISTRY_USERNAME }}" --password-stdin
- name: Build & Push Docker image
run: |
set -euo pipefail
ENV="${{ inputs.environment }}"
TAG="${{ gitea.sha }}-$(date +%s)"
echo "Building $REGISTRY/$APP:$TAG (env tag=$ENV)"
docker build -t "$REGISTRY/$APP:$TAG" -t "$REGISTRY/$APP:$ENV" .
docker push "$REGISTRY/$APP:$TAG"
docker push "$REGISTRY/$APP:$ENV"
echo "IMAGE_TAG=$TAG"
echo "$TAG" > image_tag.txt
mkdir -p /tmp/lpt-ci
echo "$TAG" > /tmp/lpt-ci/image_tag.txt
- name: Setup kubectl
run: |
set -euo pipefail
curl -sLO "https://dl.k8s.io/release/v1.30.0/bin/linux/amd64/kubectl"
chmod +x kubectl
mv kubectl /usr/local/bin/
echo "${{ secrets.KUBECONFIG_B64 }}" | base64 -d > /tmp/kubeconfig
chmod 600 /tmp/kubeconfig
- name: Create/Update imagePullSecret
run: |
set -euo pipefail
kubectl create secret docker-registry regcred \
--docker-server="$REGISTRY" \
--docker-username="${{ secrets.REGISTRY_USERNAME }}" \
--docker-password="${{ secrets.REGISTRY_PASSWORD }}" \
-n "lpt-${{ inputs.environment }}" \
--dry-run=client -o yaml | kubectl apply -f -
- name: Deploy to K8s
run: |
set -euo pipefail
ENV="${{ inputs.environment }}"
IMAGE_TAG="$(cat image_tag.txt 2>/dev/null || cat /tmp/lpt-ci/image_tag.txt 2>/dev/null || echo '')"
if [ -z "$IMAGE_TAG" ]; then
echo "ERROR: IMAGE_TAG 为空,无法部署"
exit 1
fi
echo "Deploying $REGISTRY/$APP:$IMAGE_TAG -> namespace lpt-$ENV"
kubectl set image "deployment/$APP" \
"$APP=$REGISTRY/$APP:$IMAGE_TAG" \
-n "lpt-$ENV" --record
kubectl rollout status "deployment/$APP" \
-n "lpt-$ENV" --timeout=5m
- name: Debug on failure
if: failure()
run: |
ENV="${{ inputs.environment }}"
echo "=== Deployment Status ==="
kubectl get deployment "$APP" -n "lpt-$ENV" || true
echo ""
echo "=== Pod Status ==="
kubectl get pods -n "lpt-$ENV" -l "app=$APP" || true
echo ""
echo "=== Recent Events ==="
kubectl get events -n "lpt-$ENV" --sort-by='.lastTimestamp' | tail -20 || true
echo ""
echo "=== Pod Describe (latest) ==="
POD=$(kubectl get pods -n "lpt-$ENV" -l "app=$APP" --sort-by=.metadata.creationTimestamp -o jsonpath='{.items[-1].metadata.name}' 2>/dev/null || true)
if [ -n "${POD:-}" ]; then
kubectl describe pod "$POD" -n "lpt-$ENV" || true
echo ""
echo "=== Pod Logs (latest) ==="
kubectl logs "$POD" -n "lpt-$ENV" --tail=50 || true
fi
- name: Rollback on failure
if: failure()
run: |
set -euo pipefail
ENV="${{ inputs.environment }}"
kubectl rollout undo "deployment/$APP" -n "lpt-$ENV" || true
kubectl rollout status "deployment/$APP" -n "lpt-$ENV" || true
+156 -21
View File
@@ -1,24 +1,92 @@
# 项目规范
# LPT 后端服务(lpt-be)
## 数据库迁移(Flyway Migration)
> Java Spring Boot 后端,提供 REST API、数据库访问、认证鉴权。
### 命名规则
- 脚本格式:`V{YYYYMMDD}_{序号}__{描述}.sql`
- 日期必须使用**实际编写日期**,不得使用过去的日期
- 序号从 1 开始,同一天多个脚本递增
- 描述使用下划线分隔的英文短语
## 规则与技能位置
### 核心原则
- **不可变性**:已执行的迁移脚本永远不得修改
- **只增不减**:数据库变更只能通过新增迁移脚本实现
- **向后兼容**:新脚本应兼容已有数据
- 通用规则(跨仓库):meta 仓库 `.agents/roles/`(本仓库的 Git 提交规范也统一在其中的 `commit-convention.md`,本文件不再重复)
- 本仓库专属规则:`roles/`
- `roles/database-migration.md`:数据库迁移(Flyway Migration)
- `roles/data-access.md`:编码规范 · 数据访问层
- `roles/api-response.md`:响应规范、DTO 转换
- `roles/ownership-and-markers.md`:内容归属与结构化报告(归属-01 / 报告-01)、标记(标记-01)
- `roles/ai-integration.md`:学习引导(复习-06)、AI 异步链路(AI-02)
- 本仓库专属技能:`skills/`(如 `comment-cleanup`)
### 操作规范
- 删除表:创建新迁移脚本,使用 `DROP TABLE IF EXISTS`
- 修改表结构:使用 `ALTER TABLE` 语句
- 新增表:创建新迁移脚本,使用 `CREATE TABLE`
## 技术栈
## 框架机制
- Java 17
- 框架:Spring Boot 3.2.5
- ORM:MyBatis-Plus 3.5.5
- 数据库:MySQL 8.0
- 认证:Sa-Token 1.38.0,Cookie 名 `satoken`
- 数据库迁移:Flyway
- 对象映射:MapStruct 1.5.5
- 连接池:Druid 1.2.8
- 密码加密:jBCrypt 0.4
- API 文档:Knife4j (OpenAPI 3)
- Lombok(@Data, @Slf4j)
## 项目结构
```text
lpt-be/src/main/java/com/guo/learningprogresstracker/
├── controller/ → REST 接口层
├── service/ → 业务逻辑层(接口 + impl)
├── mapper/ → MyBatis-Plus BaseMapper
├── entity/ → 数据库实体
├── dto/ → 请求/响应 DTO
├── config/ → Spring 配置
├── common/ → 全局异常处理、Ops
├── mapStruct/ → MapStruct Converter
├── enums/ → 枚举类
├── exception/ → 自定义异常
└── utils/ → 工具类
```
- controller 只做参数校验和路由。
- service/impl 承载业务逻辑。
- mapper 使用 MyBatis-Plus BaseMapper。
- entity 使用 `@TableName`、`@TableField` 映射数据库字段。
- mapStruct 承载 DTO 转换。
## API 端点总览(86 个)
| 模块 | 端点数 | 端点 |
|------|--------|------|
| 登录认证 | 2 | `POST /login`, `POST /logout` |
| 学习会话 | 11 | `PUT /study-sessions/{sessionNum}/expectation`, `GET /study-sessions/{sessionNum}/expectation`, `GET /study-sessions/{sessionNum}`, `POST /study-sessions/{sessionNum}/study-sessions/continue`, `POST /study-sessions/{sessionNum}/study-sessions/pause`, `POST /study-sessions/{sessionNum}/study-sessions/ended`, `POST /study-sessions/{sessionNum}/study-sessions/abort`, `GET /study-sessions/{sessionNum}/all-fragments`, `GET /study-sessions/tasks/{taskNum}/fragments`, `GET /study-sessions/tasks/{taskNum}/reports`, `GET /study-sessions/active` |
| 任务管理 | 15 | `GET/POST /tasks`, `GET/PUT/DELETE /tasks/{taskId}`, `GET/PUT /tasks/priority-weights`, `GET /tasks/options`, `GET/POST /tasks/{taskNum}/applications`, `PUT/DELETE /tasks/applications/{id}`, `GET /tasks/{taskNum}/study-sessions/start-or-continue`, `GET /tasks/{taskNum}/not-ended-study-session`, `GET /tasks/{taskId}/deletion-preview` |
| 复习与导图 | 19 | `GET /review/feed`, `PUT /review/feed/{fragmentId}/feedback`, `POST /review/feed/{fragmentId}/touched`, `GET /review/sort-preference`, `PUT /review/sort-preference`, `GET /review/summary`, `GET /review/tasks`, `GET /review/tasks/{taskNum}`, `GET /review/task/{taskNum}`, `GET /review/report/{id}`, `GET /review/report/{id}/structured`, `PUT /review/report/{id}`, `DELETE /review/report/{id}`, `GET /review/fragment/{id}`, `GET /review/standard-mind-map/{taskNum}`, `PUT /review/standard-mind-map/{taskNum}`, `POST /review/standard-mind-map/{taskNum}/find-node`, `GET /review/standard-mind-map/{taskNum}/recall-records`, `GET /review/standard-mind-map/recall-records/{recordId}` |
| 标签导图 | 4 | `POST /review/tag-mind-map/query`, `PUT /review/tag-mind-map`, `GET /review/tag-mind-map/list`, `POST /review/tag-mind-map/recall-records` |
| 知识碎片 | 6 | `POST /report-fragments`, `PUT /report-fragments/{id}`, `PUT /report-fragments/{id}/ownership`, `DELETE /report-fragments/{id}`, `GET /report-fragments/session/{sessionNum}`, `GET /report-fragments/pending-ownership` |
| 数据导出 | 2 | `GET /export/task/{taskNum}`, `GET /export/range` |
| 学习引导 | 5 | `POST /review/guidance`, `POST /review/guidance/{guidanceNum}/turns`, `GET /review/guidance/{guidanceNum}`, `POST /review/guidance/{guidanceNum}/fragments`, `DELETE /review/guidance/{guidanceNum}` |
| 统一标记 | 12 | `GET /markers`, `POST /markers`, `POST /markers/batch`, `DELETE /markers/{id}`, `PUT /markers/rename`, `GET /markers/filter`, `GET /markers/tags`, `GET/POST /markers/tags/dictionary`, `PUT/DELETE /markers/tags/dictionary/{id}`, `GET /markers/tags/candidates` |
| AI 异步任务 | 3 | `POST /ai/tasks`, `GET /ai/tasks/{taskNum}`, `GET /ai/tasks/latest` |
| AI 用量统计 | 5 | `GET /ai/usage/permission`, `GET /ai/usage/summary`, `GET /ai/usage/series`, `GET /ai/usage/breakdown`, `GET /ai/usage/balance` |
| 内部(服务间) | 1 | `POST /internal/ai-usage/records` |
| 工具 | 1 | `GET /utils/fetch-title?url=...` |
> 「AI 用量统计」只对 `lpt.ai-usage.admin-usernames` 白名单用户开放:`permission` 用 `allowed=false`
> 让前端静默隐藏入口,其余 4 个接口直接拒绝。`POST /internal/ai-usage/records` 是 lpt-ai 的上报入口,
> 没有登录态,在 `WebMvcConfig` 里排除了 Sa-Token,改用 `x-api-token` 与 `lpt.ai-usage.report-token` 比对。
## 数据库(11 个核心表)
`users`, `tasks`, `study_sessions`, `study_reports`, `study_report_fragments`, `study_expectations`, `task_applications`, `review_standard_mind_maps`, `review_recall_records`, `user_priority_weights`, `ai_usage_records`
> `ai_usage_records` 是**系统级表**,已加入 `MybatisPlusConfig.EXCLUDE_TABLES`:
> 记录由 lpt-ai 上报、没有登录用户,而且用量是运维口径(面板要看全部调用)。
> 若按 `created_by` 过滤,管理员只能看到自己触发的那几次,面板等于永远是空的。
## 关键机制
- 多租户隔离:`TenantLineInnerInterceptor` 自动注入 `WHERE created_by = #{当前用户}`,排除 `user`/`flyway_schema_history` 表。
- 自动填充:`MetaObjectHandler` 自动填充 `created_by`/`updated_by`/`created_time`/`updated_time`。
- 认证鉴权:Sa-Token 拦截 `/**` 排除 `/login`,Cookie `satoken`,支持 `@SaCheckPermission` 注解式权限。
- 响应格式:`CommonResult<T>` 统一包装 `{ code, message, data }`。
- CORS:可配置,local profile 允许所有来源。
### 行级数据隔离(多租户拦截器)
@@ -27,7 +95,8 @@
- **租户值来源:** `StpUtil.getLoginIdAsString()`(当前登录用户)
- **自动注入:** 所有 SELECT/UPDATE/DELETE 语句自动追加 `WHERE created_by = #{当前用户}`
- **归属校验:** 查询单条记录时拦截器自动校验 `created_by`,非本人数据直接返回空
- **排除表:** `user`、`flyway_schema_history`、`databasechangelog`、`databasechangeloglock`
- **排除表:** `user`、`flyway_schema_history`、`databasechangelog`、`databasechangeloglock`、`ai_usage_records`
(`ai_usage_records` 是系统级表,用量要统计全部调用,不能按 `created_by` 切分)
### 自动填充(MetaObjectHandler)
@@ -40,8 +109,74 @@
- **权限校验:** `@SaCheckPermission` 注解式权限控制
- **未登录处理:** 全局异常处理器捕获 `NotLoginException` 返回 401
## 编码规范
## CORS
### 数据访问层
- **优先使用纯 MyBatis-Plus Java API**(`Wrappers.<T>lambdaQuery()`、`selectList`、`selectById` 等),避免手写 XML SQL
- 复杂查询通过 `Wrappers` 链式构建条件,必要时使用 `.apply()` 拼接原生 SQL 片段
- 由 `CorsProperties` 读取各 profile 的 `cors.allowed-origins`。
- `allowed-origins: "*"` 时自动切换为 `allowedOriginPatterns("*")`,兼容 `allowCredentials`。
## 标题抓取
- `TitleFetcher`:静态工具类,支持 HTTP→HTTPS 重定向和宽松 SSL。
- `UtilsController`:`GET /utils/fetch-title?url=...` 代理端点。
## 运行环境
- 默认 profile:local(`application.yml` 中 `spring.profiles.active: local`)。
- 编译命令:`mvn clean compile -DskipTests`,需要 JDK 17。
## 配置文件
| Profile | 文件 |
|---------|------|
| local | `application-local.yml` |
| dev | `application-dev.yml` |
| uat | `application-uat.yml` |
| prod | `application-prod.yml` |
| 公共 | `application.yml` |
## AI 服务依赖
- 配置:`lpt.ai-service.url=http://localhost:5199`
- 超时:600s
- 入站令牌(安全-03):`lpt.ai-service.token`,空表示 lpt-ai 未启用令牌校验。
部署侧用 `LPT_AI-SERVICE_TOKEN`(`lpt-secrets/lpt-ai-token`,`optional: true`)注入;
注意变量名带连字符才能映射到 `lpt.ai-service.token`,与既有的 `LPT_AI-SERVICE_URL` 保持一致。
- AI 服务不可用时自动降级到内置规则引擎(`BuiltinMindMapGenerator`)
## AI 用量统计
- **数据来源**:lpt-ai 每次任务结算后上报一条记录(`POST /internal/ai-usage/records`,按 `record_id` 幂等)。
上报失败由 lpt-ai 侧本地 outbox 重试;4xx 属于确定性拒绝,lpt-ai 会丢弃这批并计数,不会无限重试。
- **token 的 null 语义**:`prompt_tokens` 等列为 `NULL` 表示上游没上报,`0` 表示上游明确上报为 0。
两者必须区分(`unreported_usage_calls` 就是靠它算的),**不得用 0 顶替 null**。
- **计价在 lpt-ai 侧冻结**:`cost_usd` 是上报时按当期价目算好的,本服务只做聚合与汇率换算,
改价不会重写历史账。汇率走 `lpt.ai-usage.usd-to-cny`。
- **口径**:只统计 `is_llm_call = 1` 的记录(`/fetch-title` 这类不消耗 LLM)。
- **分组维度**:`breakdown?groupBy=taskType|model|user`。用户维度下 `key` 是用户 id
(未归属为 `null`)、`label` 是登录名(未归属为「未归属」,查不到登录名时回退为 `key`);
其它维度下 `label` 等于 `key`,前端统一渲染 `label` 即可。用户筛选用 `userId` 参数。
- **归属链路(callerRef)**:lpt-ai 不知道调用方是谁,所以归属标记跟着请求走——
`AiServiceClient` 提交任务时把当前用户 id 作为**顶层** `callerRef` 带上(取不到身份就不带,
记为未归属,绝不让 AI 调用因此失败),lpt-ai 原样透传,上报后落到 `user_id`。
标记在 LLM 调用之前就已确定,因此没有「上报先到、归属还没写回」的竞态。
**`callerRef` 不能放进 `params`**:params 会喂给 prompt 模板、也参与 lpt-ai 的幂等键。
- **`user_id` 不是租户列**:本表在 `EXCLUDE_TABLES` 中,`user_id` 只用于分组与筛选。
改成租户过滤会让管理员只能看到自己触发的调用,面板等于永远是空的。
- 配置:`lpt.ai-usage.admin-usernames`(白名单,部署用 `LPT_AI-USAGE_ADMIN-USERNAMES`)、
`lpt.ai-usage.report-token`(上报令牌,部署用 `LPT_AI-USAGE_REPORT-TOKEN`,与 lpt-ai 的
`LPT_AI_REPORT_TOKEN` 共用 `lpt-secrets/lpt-ai-report-token`)。
- 前端入口:`lpt-fe` 的 `/ai-usage`,入口按钮在「退出登录」左侧,显隐由登录响应里的 `aiAdmin` 决定。
## 启动命令
```bash
mvn clean compile -DskipTests # 编译(需要 JDK 17)
mvn spring-boot:run # 启动(默认 profile: local)
```
## 关联项目
| 项目 | 路径 | 端口 | 说明 |
|------|------|------|------|
| lpt-fe | `../lpt-fe/` | 5158 | Vue 3 前端,通过 `/api` 代理调用本服务 |
| lpt-ai | `../lpt-ai/` | 5199 | AI 服务,本服务通过 HTTP 调用其异步任务接口 |
-63
View File
@@ -1,63 +0,0 @@
# LPT 后端规范
## 技术栈
- Java 17, Spring Boot 3.2.5
- MyBatis-Plus 3.5.5 + MySQL
- MapStruct 1.5.5(编译期生成代码,DTO 增删字段后需重新编译)
- Sa-Token 1.38.0(认证/鉴权)
- Flyway(数据库迁移)
- Lombok(@Data, @Slf4j)
## 项目结构
```
controller/ → REST 接口,只做参数校验和路由
service/ → 业务逻辑
impl/
mapper/ → MyBatis-Plus BaseMapper
entity/ → 数据库实体(@TableName, @TableField)
dto/ → 请求/响应 DTO
request/
response/
config/ → Spring 配置(WebMvcConfig, JacksonConfig 等)
utils/ → 工具类
common/ → GlobalExceptionHandler, Ops 等
mapStruct/ → MapStruct Converter 接口
```
## 响应规范
- 统一使用 `CommonResult<T>` 包装:`{ code, message, data }`
- 成功:`CommonResult.success(data)` → code=200
- 业务错误:`CommonResult.error(msg)` → code=400, HTTP 200
- 未登录:`GlobalExceptionHandler.handleNotLogin()` → HTTP 401 + code=401
- 参数校验失败走 `MethodArgumentNotValidException` → code=400
## 认证
- SaInterceptor 注册在 `WebMvcConfig`(无 @Profile 限制,所有环境生效)
- 拦截 `/**`,排除 `/login`
- `StpUtil.checkLogin()` 失败 → NotLoginException → GlobalExceptionHandler → 401
- Cookie 名 `satoken`,前端 axios 需 `withCredentials: true`
## 数据库变更
- Flyway 迁移文件:`src/main/resources/db/migration/V{日期}_{序号}__{描述}.sql`
- 文件名日期格式:`yyyyMMdd`
## DTO 转换
- MapStruct 编译期生成 `*ConvertImpl.java`(target/generated-sources/)
- 同名属性自动映射,`unmappedTargetPolicy = IGNORE`
- 如需自定义映射用 `@Mapping(source, target)`
- **增删 DTO 字段后必须重新编译**,否则 MapStruct 生成代码不含新字段
## CORS
- 由 `CorsProperties` 读取各 profile 的 `cors.allowed-origins` 配置
- `allowed-origins: "*"` 时自动切换为 `allowedOriginPatterns("*")`(兼容 allowCredentials)
- local profile:`allow-credentials: true`, `allowed-origins: '*'`
## 标题抓取
- `TitleFetcher`:静态工具类,支持手动跟随 HTTP→HTTPS 重定向、宽松 SSL
- `UtilsController`:`GET /utils/fetch-title?url=...` 代理端点
## 运行
- 默认 profile:local(application.yml 中 `spring.profiles.active: local`)
- IDEA JDK:`C:/Users/cat-win/.jdks/ms-17.0.19`
- Maven:IDEA 内置 `C:/Program Files/JetBrains/IntelliJ IDEA 2026.1.3/plugins/maven/lib/maven3/bin/mvn`
- 编译:`mvn clean compile -DskipTests`(须用 JDK 17)
+20 -10
View File
@@ -1,17 +1,27 @@
# 使用官方 OpenJDK 作为基础镜像
FROM eclipse-temurin:17-jre
# 设置工作目录
# Stage 1: Maven 构建(Docker 层缓存自动缓存依赖)
FROM maven:3.9-eclipse-temurin-17 AS builder
WORKDIR /app
# 拷贝打包好的 JAR 文件到容器
COPY target/LPT.jar LPT.jar
# 先复制 pom.xml,单独一层 —— 只要依赖不变,这层就被缓存
COPY pom.xml .
RUN mvn dependency:go-offline -B -q
# 再复制源码构建
COPY src/ ./src/
RUN mvn package -DskipTests -B -q
# Stage 2: 运行时(精简 JRE)
FROM eclipse-temurin:17-jre
# 固定容器时区:本系统按“无时区本地时间”存储与展示,容器默认 UTC 会让时间整体偏 8 小时
ENV TZ=Asia/Shanghai
RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone
WORKDIR /app
COPY --from=builder /app/target/LPT.jar LPT.jar
# 暴露应用运行的端口
EXPOSE 8888
# 启动应用
ENTRYPOINT ["java", "-jar", "LPT.jar"]
# 健康检查
HEALTHCHECK --interval=10s --timeout=5s CMD curl --fail http://localhost:8888/actuator/health || exit 1
HEALTHCHECK --interval=10s --timeout=5s \
CMD curl --fail http://localhost:8888/actuator/health || exit 1
Vendored
-78
View File
@@ -1,78 +0,0 @@
pipeline {
agent none // 全局不指定,局部自己声明
environment {
IMAGE_NAME = 'lpt-prod:0.0'
CONTAINER_NAME = 'LPT-prod'
CONTAINER_PORT = '8888'
}
stages {
stage('Build') {
agent {
docker {
image 'maven:3.9.6-eclipse-temurin-17'
args '-v /root/.m2:/root/.m2'
}
}
steps {
sh 'mvn -B -DskipTests clean package'
}
}
stage('Build Docker Image') {
agent any // 使用 Jenkins 默认节点(宿主机),前提是宿主有 docker 命令
steps {
sh 'docker build -t $IMAGE_NAME .'
}
}
stage('Run Docker Container') {
agent any
steps {
sh '''
docker network create traefik-public || true
docker rm -f $CONTAINER_NAME || true
docker run -d --name $CONTAINER_NAME --network mysql-prod_mysql-prod \\
--restart=always \\
-e SPRING_PROFILES_ACTIVE=prod \\
--label "traefik.enable=true" \\
--label "traefik.docker.network=traefik-public" \\
--label 'traefik.http.routers.lpt-api.rule=Host(`lpt.cat-shark.xyz`) && PathPrefix(`/api`)' \\
--label "traefik.http.routers.lpt-api.entrypoints=websecure" \\
--label "traefik.http.routers.lpt-api.tls.certresolver=le" \\
--label "traefik.http.routers.lpt-api.priority=100" \\
--label "traefik.http.routers.lpt-api.service=lpt-api" \\
--label "traefik.http.routers.lpt-api.middlewares=lpt-api-strip" \\
--label "traefik.http.middlewares.lpt-api-strip.stripprefix.prefixes=/api" \\
--label "traefik.http.services.lpt-api.loadbalancer.server.port=$CONTAINER_PORT" \\
--log-driver=loki \\
--log-opt loki-url="http://192.168.123.199:3100/loki/api/v1/push" \\
$IMAGE_NAME
docker network connect traefik-public $CONTAINER_NAME || true
'''
}
}
stage('Check Docker Status') {
agent any
steps {
script {
def lastStatus = ''
timeout(time: 60, unit: 'SECONDS') {
waitUntil {
def status = sh(
script: "docker inspect -f '{{.State.Health.Status}}' $CONTAINER_NAME || echo 'unhealthy'",
returnStdout: true
).trim()
if (status != lastStatus) {
echo "Container health: ${status}"
lastStatus = status
}
return (status == 'healthy')
}
}
}
}
}
}
}
-78
View File
@@ -1,78 +0,0 @@
pipeline {
agent none // 全局不指定,局部自己声明
environment {
IMAGE_NAME = 'lpt-dev:0.0'
CONTAINER_NAME = 'LPT-dev'
CONTAINER_PORT = '8888'
}
stages {
stage('Build') {
agent {
docker {
image 'maven:3.9.6-eclipse-temurin-17'
args '-v /root/.m2:/root/.m2'
}
}
steps {
sh 'mvn -B -DskipTests clean package'
}
}
stage('Build Docker Image') {
agent any // 使用 Jenkins 默认节点(宿主机),前提是宿主有 docker 命令
steps {
sh 'docker build -t $IMAGE_NAME .'
}
}
stage('Run Docker Container') {
agent any
steps {
sh '''
docker network create traefik-public || true
docker rm -f $CONTAINER_NAME || true
docker run -d --name $CONTAINER_NAME --network mysql_default \\
--restart=always \\
-e SPRING_PROFILES_ACTIVE=dev \\
--label "traefik.enable=true" \\
--label "traefik.docker.network=traefik-public" \\
--label 'traefik.http.routers.lpt-api-dev.rule=Host(`lpt-dev.cat-shark.xyz`) && PathPrefix(`/api`)' \\
--label "traefik.http.routers.lpt-api-dev.entrypoints=websecure" \\
--label "traefik.http.routers.lpt-api-dev.tls.certresolver=le" \\
--label "traefik.http.routers.lpt-api-dev.priority=100" \\
--label "traefik.http.routers.lpt-api-dev.service=lpt-api-dev" \\
--label "traefik.http.routers.lpt-api-dev.middlewares=lpt-api-dev-strip" \\
--label "traefik.http.middlewares.lpt-api-dev-strip.stripprefix.prefixes=/api" \\
--label "traefik.http.services.lpt-api-dev.loadbalancer.server.port=$CONTAINER_PORT" \\
--log-driver=loki \\
--log-opt loki-url="http://192.168.123.199:3100/loki/api/v1/push" \\
$IMAGE_NAME
docker network connect traefik-public $CONTAINER_NAME || true
'''
}
}
stage('Check Docker Status') {
agent any
steps {
script {
def lastStatus = ''
timeout(time: 60, unit: 'SECONDS') {
waitUntil {
def status = sh(
script: "docker inspect -f '{{.State.Health.Status}}' $CONTAINER_NAME || echo 'unhealthy'",
returnStdout: true
).trim()
if (status != lastStatus) {
echo "Container health: ${status}"
lastStatus = status
}
return (status == 'healthy')
}
}
}
}
}
}
}
-373
View File
@@ -1,373 +0,0 @@
# 学习进度跟踪系统(LPT)— 架构与设计评审
> 评审日期:2026-07-03
> 评审范围:learning-progress-tracker(后端 Spring Boot) + lpt-fe(前端 Vue 3)
> 代码基线:feature/review-completion 分支
## 一、整体评价
系统的底层方向是正确的:
- **量化学习投入**(番茄钟 + 学习简报)→ 解决缺乏时间感知
- **优先级排序**(五维度算法)→ 解决缺乏计划性
- **主动回忆式复习**(碎片滚动 + 思维导图对比)→ 解决缺乏复习习惯
三个痛点对应三个解决方案,逻辑链成立。代码质量方面,前后端分离、RESTful API 设计、Flyway 数据库迁移、Sa-Token 鉴权、MyBatis-Plus 多租户拦截等基础设施做得相当规范,超出业余项目的平均水准。
但在**业务设计的心理学层面**,存在几个结构性矛盾:有些地方把"功能完整"等同于"有用",对用户的实际行为模式考虑不足。
---
## 二、不科学之处
### 2.1 番茄钟被当作计时器而非学习节奏工具
当前实现把 25 分钟当作一个硬性倒计时,超时 50 分钟自动暂停,"仅计 25 分钟有效时间"。但番茄钟的核心价值不是"学够 25 分钟",而是**强迫休息—回忆—重置**的节奏。
**问题**:
- 允许用户连续学习远超 25 分钟而不触发强制休息提醒
- 超时被视为"违规"(自动暂停),而不是自然的节奏重置
- 后端 session 状态机里没有独立的"休息中"状态
- 前端虽有 5 分钟倒计时但后端无法感知
**改进方向**:番茄钟应该循环——25 分钟学习 → 强制 5 分钟休息并提示填写残片 → 自动进入下一轮。每一轮结束都是自然的"复习锚点"。
**用户评价**:你理解的不对,“有效学习时间”指的是实际的学习时间(不处于暂停状态的时间),25分钟对于一个大的学习任务来说太短,我们应该给予宽松的选择,而不是机械的要求用户休息,这只是一个辅助学习的工具
### 2.2 优先级五维度权重有重叠,且缺乏解释
| 维度 | 权重 | 问题 |
|------|------|------|
| 主观判断 | 10% | 跟"重要性"、"未来价值"高度相关,用户难以区分 |
| 未来价值 | 10% | 同上 |
| 内容难度 | 20% | 假设"越难越值得优先学"不一定成立 |
| 必要性 | 25% | 与"紧急性"边界模糊 |
| 紧急性 | 35% | 权重最高,但优先级 ≠ 紧迫性 |
核心矛盾:紧急性 + 必要性占 0.60,主观判断 + 未来价值仅占 0.20。系统会自动把"明天要交的报告"排在"你想真正学会的英语"前面——但用户做这个系统是为了后者的。
**改进方向**:两套排序模式——"紧急模式"(按紧迫性)和"重要模式"(按主观+未来价值),用户在不同时间段切换,而不是混合成一个不伦不类的综合分。此外权重应当可配置(当前硬编码在 CalculatedPriorityTool 中)。
**用户评价**:用户要如何切换?什么时候切换呢?如果一个课程最开始并不急迫,但其很重要,如果等到其变为急迫后用户才开始学习,那就晚了;我这里的设计是想优先完成“重要但不紧急”的课程,权重设计本身就是要是可修改的,只是系统中没有来得及实现;
### 2.3 学习预期是系统强约束但无闭环
PRD 明确要求"每次学习开始前必须填写学习预期(不可为空)",数据库也建了 study_expectations 表。但:
- 后端没有对应的 Entity / Service / Controller
- 前端 StartTask 页面没有预期输入框
- 预期没有与实际学习报告做任何对比
被强制填写却不被使用的字段,比没有更糟——用户费心填了,却发现系统根本不看。学习预期的价值在于事后对比:"我打算学什么 vs 我实际学了什么",这是元认知训练的核心。
**改进方向**:始于创建 session 时弹窗必填预期,终于结束时展示"预期 vs 实际"对比。
### 2.4 复习模块的认知负荷偏高
当前复习模块有三个独立概念和入口:
- 碎片化提醒(Welcome 页滚动)
- 思维导图上/下载(ReviewDetail)
- 回忆对比(ReviewRecall)
但用户的真实行为大概是:打开复习页 → 看到滚动条闪过很多内容 → 不知道先看哪个 → 关掉。太多碎片而没有"今天需要复习什么"的引导。
复习行为的心理阻力主要来源于**不知道从哪开始**。
**改进方向**:复习应该"推"给用户一条清晰路径——"你今天有 3 个知识点需要复习,先看第一个"。而不是拉出一个 feed 让用户自己挑。
**用户评价**:不,如果按照你的设计,就违背了我对这个系统的设计理念“本系统只是辅助学习的工具”,滚动条的设计是想要随机的将知识展示给用户,触发用户随机的回忆,在我的感受中,总有些无意识看到的东西会停留在记忆中很久,即使看到了但没有回忆起细节,也会更努力的回忆,从而印象更深;我认同你的“推”的逻辑,但并不应该“要求”用户,这可能会让用户产生抵触情绪;我们可以让“随机”变得不那么随机,可以在滚动中将更需要复习的内容优先展示出来;为了制造这种“无意识看到”,我们也许可以在更多地方增加这种引导;因为这是我的感受,请搜索网络,看看是否有论文对此进行过论证,主要找到相反的论证,我不希望我的系统是我一厢情愿的
---
## 三、改进空间
### 3.1 学习报告的长度决策
当前,残片是"休息时记录的内容片段",报告是"结束时生成的完整总结"。但在前端两者几乎无差异——都是文本、都在同一个 feed 中滚动、都在详情页逐行显示。
实际问题:学完 25 分钟后,用户是否真的有动力写一篇"完整报告"?大概率不会——草草写一句"学了线程池"然后开始下一轮。
**改进方向**:降低报告的仪式感。残片应该是主力的学习记录单元,报告改为"自动将本次会话的残片聚合为摘要",用户只需要微调即可。
**用户评价**:你关于“完整报告”的判断是正确的,和我的使用体验一致,但在我原有的设计中,"自动将本次会话的残片聚合为摘要"就是该功能的最终版本,只是受限当前阶段中没有对接AI导致的;我认为这部分功能使用32b的LLM模型应该就可以,实施时请简单调研
### 3.2 断点续传的粒度
当前用 pointerPosition(毫秒级指针)支持关闭页面后恢复学习,设计很好。但问题在于:学习结束后,断点续传数据变成死数据。
用户周五回来面对的不是"上次学了什么"的摘要,而是"继续上次倒计时"——但用户可能想重新开始一个关于同一任务的新会话,或者先回顾上次的残片再做决定。
**改进方向**:断点续传配合"上次学习回顾"一起出现——"你上次学了 X、Y、Z,生成了 N 个残片。继续?还是开始新的?"
**用户评价**:你可以看到原有设计中“关闭页面后恢复学习”只是对一个session完成的,每个session就应该是连续的,不应该出现长时间暂停的情况;
### 3.3 有效学习时间的 10 分钟阈值
后端逻辑:effective_time < 10 分钟 → 不计入总学习时间,置为 0。
意图是过滤掉"开启后很快就关"的无效学习。但 10 分钟阈值对番茄钟来说太高——25 分钟的 session 如果被电话打断 8 分钟后回来,系统判定"白学了"。
**改进方向**:降低阈值到 3-5 分钟,或改为比例制(有效比 < 30% 才标记低效而不是直接归零)。数据是分析原材料,不是评判工具。
**用户评价**:我认为你对“有效学习时间”的定义理解有误,如果一个session开始了(开始了一个学习任务),用户有其他事情需要处理,其可以点击暂停,暂停后的时间才是“无效的”,暂停之前的时间才是“有效学习时间”,对于一轮25分钟的番茄钟来说,有效学习10分钟是最低限度了, 因为一次学习本就应该持续25分钟,10分钟还不到一半;另外一点,对于长时间暂停的session,我的系统应该会自动终止;
### 3.4 回忆覆盖率的误导性
当前:recall_ratio = matched / (matched + missed)。问题在于它衡量"记得多少节点"而非"记得多少重要节点"。
假如一个任务 100 个节点,其中 3 个核心、97 个细节。
- 用户回忆出 3 个核心 → 覆盖率 3%
- 用户回忆出 97 个细节但漏了 3 个核心 → 覆盖率 97%
显然后者更差,但指标显示前者好。
**改进方向**:节点加权——"应用场景"和"从报告中提取的关键概念"级别更高。或至少同时展示"核心节点覆盖"和"全部节点覆盖"两个指标。
**用户评价**:单纯的指标展示还是略显单调,用户可能无法直接定位其未能覆盖的内容,如果可以直接在“思维导图”上用颜色标记出来是最好的
### 3.5 多租户隔离的泛化成本
系统通过 created_by 做租户隔离,每个查询多一个 WHERE 条件、新增数据要注入用户 ID、测试要绕过拦截器。开发笔记中作者自问"这玩应儿除了自己,还能有别人用么"。
多租户本身没有错,但在当前单人使用场景下带来了不必要的复杂度。
**改进方向**:如果未来真有多人需求可还原。当前去掉租户拦截可简化 80% 的查询,减少隐式 bug。
**用户评价**:不,还是保持基本的多租户设计吧,系统必然会遇到多租户需求,但目前没有
---
## 四、优先级建议
### P0 —— 影响核心使用
- 学习预期的闭环(创建→填写→事后对比)
- 番茄钟循环节律(25分→5分休息 + 自动残片)
### P1 —— 明显改善体验
- 复习引导路径("今天有 N 个知识点需要复习")
- 降低报告仪式感(残片为主、报告自动聚合)
- 优先级权重用户可配置
### P2 —— 优化与完善
- 有效时间阈值下调
- 回忆覆盖率高阶指标(核心节点 vs 全部节点)
- 断点续传配合历史回顾
- 移除不必要的多租户拦截(或标记可选)
---
## 五、总结
系统在基础设施层面(前后端分离、RESTful、Flyway、Sa-Token、MyBatis-Plus)做得相当规范。主要问题不在技术而在设计:**把"功能完整"当成了"有用"**。学习预期无闭环、番茄钟无节奏感、复习无引导路径——这些不需要更多技术投入,而是需要重新理解用户行为。
> 一句话:系统已经可以做很多事情,但用户不一定知道"现在应该做什么"。
> 下一步的改进目标是降低用户决策成本,引导而非开放。
>
**用户评价**:使用本系统就是为了学习任意一个课程或者领域的知识而来的,用户不需要被动接受要学习的目标,其必须有一定的”要做什么的”目的性
---
## 六、回应设计评审与用户评价(2026-07-03 补充)
本节在保留原评审全部内容的基础上,逐条回应作者(用户)的评价,并补充研究支撑和新理解。保证前一版完整可回溯。
### 6.1 番茄钟:我纠正——强制休息是教条,宽松才是工具
**原文批评**:番茄钟应 25 分→5 分强制循环。
**用户评价**:”有效学习时间实际是学习时间(非暂停状态),25 分钟对一个大任务太短,应给予宽松选择。”
**新理解**:用户是对的。我之前的建议实质是把番茄钟教条化了。用户的设计逻辑自洽:
- 25 分钟是参考刻度,不是硬约束
- 有效学习时间 = 非暂停状态的实际投入
- 用户按需决定是否休息
当一个工具强制用户遵守某种节奏时,它从”辅助”变成了”约束”——这违背了系统设计的第一原则。需要休息时会自然产生意愿,工具应在这个时候提供支持(比如推荐填充残片),而不是提前打断。
**修订建议**:保留当前灵活模式。可增加一个可选的”节拍器”——用户开启后,每轮结束时轻声提示”已学完一轮,休息回顾?”,用户可忽略。这不是通知,是提醒。
### 6.2 优先级权重:我误解了目标——用户要的是重要不紧急
**原文批评**:维度和权重有重叠,客观性存疑。
**用户评价**:”如果一个课程最开始并不急迫,但其很重要,如果等到变为急迫后用户才开始学习,那就晚了。权重设计本就是可修改的,只是系统中没有来得及实现。”
**新理解**:用户实际运用的是 **Eisenhower Matrix 第二象限(重要不紧急)优先**原则。紧急性(35%)不是用来让紧急任务主宰排序的——它是**兜底**,防止真正紧急的任务被忽略。如果没有这个兜底,用户可能在”重要不紧急”上花太多时间,错过 deadline。
我之前的批评建立在错误前提上。真正缺失的不是设计思路,而是 **配置界面**——让用户直观滑动五个维度的权重滑块,即时看到排序变化。这个功能已在 PRD 和代码注释里明确列出,是未实现,不是未设计。
**修订建议**:P0 优先级——权重配置 UI。五个维度的滑块控件,调整后实时重新排序并展示。
### 6.3 学习预期:共识——闭环是必须的
双方看法一致:没有争议。
### 6.4 复习滚动:研究支撑与反面论证
这是最有意思的部分。我搜索了学术文献,验证用户的设计假设(”无意中看到的内容会停留更久”),同时寻找反面论证。
#### ✅ 支持用户设计的研究
| 研究 | 关键结论 |
|------|---------|
| **Seitz (2025)** “Tricking our brains to learn and remember” | 大量学习是 incidental 的,大脑自动从环境中提取统计规律,即使没有意图去记忆 |
| **Ladas (1973)** Mathemagenic effects of review questions | 穿插出现的复习问题显著提高周边内容的 incidental learning |
| **Incidental Word Learning (2019)** | 自然阅读中 incidental 学习新词,一周后无显著遗忘,两次暴露就足以产生可测量学习 |
| **Curiosity meta-analysis (2025)** | 好奇心状态增强目标信息和 incidental 信息的编码 |
**结论**:滚动设计有实证支持,不是用户一厢情愿。Incidental exposure 确实能促进记忆,特别是当用户处于好奇或放松状态时。
#### ❌ 反面论证(同样成立)
| 研究 | 关键结论 |
|------|---------|
| **Roediger & Karpicke (2006) / Adesope et al. (2017) meta-analysis** | 主动回忆(testing effect)的效果远强于被动重读,effect size g = 0.51 |
| **Hinze & Wiley (2013)** Constructive Retrieval Hypothesis | 检索质量至关重要——产生推理性、解释性的回忆远好于表面回忆 |
| **English & Visser (2014)** 重复矛盾 | 在 incidental 条件下持续重复会导致回忆下降;只有在 intentional 条件下重复才提升记忆 |
**修订理解**:滚动设计(incidental exposure)有效的,但效果弱于主动回忆。它真正的价值不是替代回忆,而是**播种**——用户瞥见自己写过但有陌生感的片段→感到认知失调→点进去→进入主动回忆通道。关键在”是否会点进去”。如果只是扫过,效果有限;如果点击触发回忆,效果显著。
**修订建议**:
1. **保留滚动条**不动核心设计
2. 在点击滚动条内容后,先弹出回忆卡片再展开原文——“你还记得多少?”→ 尝试回忆 → 展示原文。这样将 incidental exposure 和 active recall 结合起来
3. 你提出的”让更需要复习的内容优先展示”可以对接到 spaced repetition 的计算——按回忆覆盖率、时间衰减排序
### 6.5 学习报告 AI 聚合:理解
用户指出原设计就是”残片自动聚合为报告”,只是缺 AI 实现。32B 模型足够。这一认识一致。
**关于 AI 服务架构**(详见 6.7 节技术推荐)。
### 6.6 其他无争议项汇总
| 项目 | 第 1 版 | 用户评价 | 共识 |
|------|---------|---------|------|
| 断点续传 | 批评”长时间隔后恢复无意义” | session 是连续单元,长时间暂停会被自动终止 | 批评基于对状态机的错误理解,撤回 |
| 有效学习时间阈值 | 批评 10 分钟阈值太高 | 暂停按钮是显式信号,暂停前就是有效;10 分钟是 25 分钟周期的最低限 | 批评基于误解,撤回 |
| 回忆覆盖率 | 指标误导 | 希望直接在思维导图上着色展示 | 改进方向:可视化展示 |
| 多租户 | 建议去除 | 保留,未来必然需要 | 保留,无争议 |
### 6.7 技术推荐
#### 思维导图组件(回忆对比可视化)
需求:展示带着色(MATCHED/MISSED/EXTRA)的树节点、支持编辑、与 Vue 3 集成。
**首选:mind-elixir-core**([GitHub](https://github.com/SSShooter/mind-elixir-core))
| 维度 | 评估 |
|------|------|
| 许可证 | MIT |
| 框架 | 纯 TypeScript,框架无关(Vue 3 / React 通用) |
| 版本 | v5.13.0(2026 年 6 月 24 日,非常活跃) |
| Star | 3.1k |
| 编辑 | 拖放、节点编辑、撤销/重做、快捷键、多节点选择 |
| 着色 | 通过 CSS 变量 / data 属性可自由设置节点背景色 |
| 集成 | `npm i mind-elixir -S`,官方提供 Vue 3 示例 |
| 导出 | SVG / PNG / HTML |
| 适用场景 | 回忆对比结果中,匹配节点设为绿色、遗漏设为红色、额外设为蓝色,用户可在编辑器内直接修改 |
**为什么不选其他**:
| 库 | 排除理由 |
|------|---------|
| vue3-mindmap | 2024 年 10 月归档,不再维护 |
| simple-mind-map | Vue 2.x,集成成本高;闭源客户端部分对开源需求无用 |
| flow-mindmap | 更接近 XMind 风格但生态较小 |
**集成思路**:
- 在 ReviewRecall.vue 中嵌入 mind-elixir 实例
- 后端对比结果(CompareResult.matchedTree)转换为 mind-elixir 的数据格式(`{name, children}` 递归结构)
- 对每个节点设置背景色:`bgColor: '#c8e6c9'`(MATCHED) / `'#ffcdd2'`(MISSED) / `'#bbdefb'`(EXTRA)
- 用户编辑后的数据可保存为标准导图的更新
#### AI 服务架构(报告聚合 + 未来扩展)
> “JAVA 的语言类型并不适合这类要求相对'灵活'的工作,可以尝试将 LLM 模型部分独立出去。”
完全同意。Java 的强类型、编译周期、生态惯性在面对 LLM 的 prompt 调试、流式响应、快速迭代时确实不够顺手。推荐以下架构:
**推荐方案:独立 TypeScript 微服务**
```
┌──────────────────┐ HTTP/SSE ┌──────────────────────┐
│ LPT 后端 (Java) │ ◄──────────────► │ LPT-AI 服务 (TS) │
│ Spring Boot │ REST API │ Fastify / Hono │
│ │ │ │
│ 业务逻辑 │ │ Prompt 模板管理 │
│ 数据持久化 │ │ LLM 调用(OpenAI 兼容)│
│ 权限认证 │ │ 流式响应 / SSE │
│ │ │ 沙箱 / 安全过滤 │
└──────────────────┘ └──────────────────────┘
│
▼
┌──────────────────────┐
│ SiliconFlow API │
│ https://api.silicon │
│ flow.cn/v1/... │
└──────────────────────┘
```
**关键设计点**:
1. **技术选型**:TypeScript + Fastify(或 Hono),后者更轻量且支持 Bun/Deno 运行时
2. **API 设计**:Java 后端通过 HTTP 调用 AI 服务,不直接暴露 LLM API
3. **Prompt 管理**:Template 化——AI 服务内部管理 prompt 模板,支持版本回滚
4. **流式支持**:报告生成等长耗时任务使用 SSE 流式返回,Java 端通过 WebFlux 转发
5. **错误处理**:AI 服务降级(不可用时回退到内置规则)
6. **未来扩展**:
- 安全沙箱(用户输入过滤、输出审核)
- 多模型路由(按任务选择模型)
- 用量监控与成本控制
7. **交付策略**:先做最小可行——一个端点 `/ai/generate-report`,接收残片列表返回聚合摘要;后续再加 `/ai/generate-mind-map`、`/ai/compare-maps` 等
**迁移路径**:
1. 第一阶段(现在):Java 端用 BuiltinMindMapGenerator,AI 服务未就绪时完全可用
2. 第二阶段:搭建 TS 服务,接入 `/ai/generate-report`,prompt 调优
3. 第三阶段:AI 生成标准导图替代 BuiltinMindMapGenerator
4. 第四阶段:安全层、多模型、沙箱
### 6.8 修正后优先级
| 优先级 | 项目 | 说明 |
|--------|------|------|
| **P0** | 学习预期闭环 | 创建 session 时必填 → 结束时对比”预期 vs 实际” |
| **P0** | 权重配置 UI | 五个维度滑块,即时影响排序 |
| **P1** | 滚动条交互增强 | 点击内容后弹出回忆卡片”你还记得多少?”→ 再展开原文 |
| **P1** | 滚动条智能排序 | 低频访问 + 低回忆覆盖率内容优先出现(类 spaced repetition) |
| **P1** | 搭建 LPT-AI 服务 | TypeScript 独立项目,先做残片聚合报告 |
| **P1** | 回忆对比可视化 | 嵌入 mind-elixir,节点着色展示 MATCHED/MISSED/EXTRA |
| **P2** | 内置生成器升级 | 接入 AI 后替代规则生成 |
| **P2** | 有效时间阈值 | 维持 10 分钟(经确认合理) |
| **P2** | 多租户 | 保留不变 |
### 6.9 最终总结(修正版)
系统在基础设施层面(前后端分离、RESTful、Flyway、Sa-Token、MyBatis-Plus)相当规范。原评审中约 50% 的批评基于对设计意图和代码状态机的误解,经用户指正后已修正。
剩余真正有价值的问题:
1. 学习预期无闭环:P0,需要实施
2. 权重配置无 UI:P0,需要实施
3. 复习交互可深化:滚动条 + 点击触发回忆,而非纯被动浏览
4. AI 聚合报告:需要独立服务
> 修正后的判断:系统设计的大部分决策是有意为之且有合理性的,不是”把功能完整当有用”。
> 真正的问题不是”不知道现在该做什么”,而是”做了好的设计但没有完全交付”——学习预期和权重配置是写在 PRD 和代码注释里但没有实现的,而非设计缺失。
> 下一步重点是:交付未完成的功能 + 引入 AI 服务作为独立项目 + 深化复习交互。
---
## 七、交付记录(2026-07-04)
6.8 节修正优先级中的全部事项已实现并小步提交:
| 事项 | 实现 | 位置 |
|------|------|------|
| 学习预期闭环 | 新会话强制填写预期(PUT/GET `/study-sessions/{n}/expectation`),页面常驻展示,结束弹窗对照 | 后端 StudyExpectationsService,前端 StartTask.vue |
| 权重配置 UI | 学习页”权重配置”——五维度滑块、合计校验 100%、保存后全任务重算(PUT `/tasks/priority-weights`) | 后端 PriorityWeightsService,前端 Study.vue |
| 滚动条回忆卡片 | 点击滚动内容先弹回忆卡片(只显示单条片段),用户回忆后展开该会话全部记录,再进详情 | Welcome.vue |
| feed 智能排序 | `/review/feed?mode=smart`:时间衰减 × 回忆掌握度加权随机采样 | ReviewServiceImpl.getSmartFeed |
| lpt-ai 独立服务 | TypeScript + Fastify 新项目:异步任务模式(`POST /ai/tasks` + 轮询),对接 SiliconFlow,Key 从环境变量读取 | 独立仓库 lpt-ai |
| AI 聚合报告 | 结束会话弹窗自动拉取 AI 草稿(有残片时),失败降级为拼接(GET `/study-sessions/{n}/report-draft`) | AiServiceClient + StartTask.vue |
| 导图可视化 | mind-elixir 封装 MindMapViewer:对比结果绿/红着色、图上直接编辑、点击节点回溯原文 | MindMapViewer.vue + ReviewRecall.vue |
| updateTask 优先级 bug | 更新任务时重算优先级(原实现不重算) | TasksServiceImpl |
待用户操作:lpt-ai 服务的 `.env` 中填入 `LLM_API_KEY`,Java 端 `application.yml` 配置 `lpt.ai-service.url`。
-437
View File
@@ -1,437 +0,0 @@
# LPT 系统实现优化说明
> 本文档记录在设计文档基础上进行的架构优化和工程实践改进
## 一、架构优化
### 1.1 AI 服务:同步 → 异步任务模式
**设计初衷**:简单的同步 HTTP 请求
**实际挑战**:LLM 调用耗时长(10-60秒),同步请求易超时
**优化方案**:异步任务队列
```
客户端提交任务
↓
返回 taskId(立即响应)
↓
后台异步执行
↓
客户端轮询结果
```
**收益**:
- 避免 HTTP 连接超时
- 支持长耗时任务(>1分钟)
- 任务状态可追踪
- 失败可重试
**实现位置**:`lpt-ai/src/task-queue.ts`
### 1.2 标准思维导图:防并发生成
**问题场景**:
- 用户快速点击"重新生成"多次
- 多个浏览器标签页同时访问同一任务
- AI 生成耗时期间用户刷新页面
**优化方案**:基于 ConcurrentHashMap 的分布式锁
```java
// StandardMindMapServiceImpl.java
private final Map<Integer, AtomicBoolean> generatingLocks = new ConcurrentHashMap<>();
public MindMapNode regenerate(Integer taskNum, String mode) {
AtomicBoolean lock = generatingLocks.computeIfAbsent(taskNum, k -> new AtomicBoolean(false));
if (!lock.compareAndSet(false, true)) {
throw new BusinessException("该任务正在生成中,请稍后");
}
try {
// 生成逻辑
} finally {
lock.set(false);
}
}
```
**收益**:
- 避免重复生成浪费 token
- 防止数据竞争导致的覆盖
- 提升系统稳定性
### 1.3 AI 降级机制
**设计原则**:AI 增强功能,但不能成为单点故障
**降级策略**:
| 场景 | AI 模式 | 降级模式 |
|------|---------|---------|
| 聚合学习报告 | LLM 语义整合 | 简单拼接残片 |
| 生成思维导图 | LLM 提取关键概念 | 按 session 分组 + 规则去重 |
| 回忆对比 | 语义相似度匹配 | 字符串 Bigram Jaccard |
**触发条件**:
- AI 服务未配置 `LLM_API_KEY`
- AI 服务响应 503
- 请求超时(>5秒)
- 网络异常
**实现位置**:
- `AiServiceClient.java` - 异常捕获 + 降级决策
- `BuiltinMindMapGenerator.java` - 内置规则生成器
- `StandardMindMapServiceImpl.compareTrees()` - 字符串匹配算法
**收益**:
- 可用性提升至 99.9%(不依赖外部服务)
- 新用户无需配置即可体验核心功能
- 成本可控(AI token 消耗可选)
---
## 二、数据模型优化
### 2.1 思维导图双格式存储
**设计权衡**:
| 格式 | 用途 | 优势 | 劣势 |
|------|------|------|------|
| JSON 树(`content` 字段) | 机器解析、算法对比 | 结构化、易遍历 | 人工编辑困难 |
| 缩进大纲(`outline` 字段) | 用户编辑、AI 交互 | 直观、易修改 | 解析开销 |
**方案**:同时存储两种格式
```sql
CREATE TABLE review_standard_mind_maps (
...
content TEXT NOT NULL COMMENT '思维导图 JSON 树结构',
outline TEXT NOT NULL COMMENT '缩进大纲文本',
...
);
```
**转换工具**:`MindMapTreeTool.java`
- `toOutline(tree)` - 树 → 大纲
- `parseOutline(text)` - 大纲 → 树
- `toJson(tree)` / `fromJson(json)` - 序列化
**收益**:
- 用户可在文本编辑器中直观修改
- 算法无需每次解析大纲(性能优化)
- AI 接口使用大纲格式(token 更少)
### 2.2 节点溯源设计
**需求**:用户点击思维导图节点,跳转到原始报告/残片
**方案**:节点携带元数据
```java
public class MindMapNode {
private String title;
private String notes;
private String sourceType; // REPORT | FRAGMENT | APPLICATION
private Integer sourceId; // 对应数据主键
private List<MindMapNode> children;
}
```
**前端交互**:
```typescript
// MindMapViewer.vue
onNodeClick(node) {
if (node.sourceType === 'REPORT') {
router.push(`/review/report/${node.sourceId}`);
} else if (node.sourceType === 'FRAGMENT') {
router.push(`/review/fragment/${node.sourceId}`);
}
}
```
**收益**:
- 复习时可快速回看原文
- 遗漏知识点可直接定位来源
- 形成"导图 → 原文"闭环
---
## 三、算法优化
### 3.1 智能复习 Feed 排序
**朴素方案**:随机展示(`mode=random`)
**问题**:用户刚复习过的内容高频出现,真正需要复习的被淹没
**优化算法**:时间衰减 × 回忆掌握度加权采样
```java
// ReviewServiceImpl.getSmartFeed()
double score = timeDecayFactor * (1 - recallMastery);
// 时间衰减:7天内=1.0, 30天=0.5, 90天=0.1
timeDecayFactor = Math.max(0.1, 1.0 - (daysSince / 90.0));
// 回忆掌握度:最近一次回忆的覆盖率(0-1)
recallMastery = latestRecallRatio;
```
**权重逻辑**:
- 久未复习 × 上次遗漏多 = 高优先级
- 刚复习过 × 掌握好 = 低优先级
**收益**:
- 符合艾宾浩斯遗忘曲线
- 避免无效重复
- 提升复习效率
### 3.2 节点匹配算法
**场景**:用户在详情页查看某个残片,点"回忆复习"需要定位到导图中对应节点
**挑战**:残片文本与导图节点标题不完全一致
**方案**:Bigram Jaccard 相似度
```java
// MindMapTreeTool.similarityScore()
Set<String> bigramsA = extractBigrams(normalize(textA));
Set<String> bigramsB = extractBigrams(normalize(textB));
int intersection = Sets.intersection(bigramsA, bigramsB).size();
int union = Sets.union(bigramsA, bigramsB).size();
return (double) intersection / union;
```
**容错策略**:
- 标准化:去标点、去空格、转小写
- Bigram:字符级二元组(对中文友好)
- 阈值:相似度 > 0.6 视为匹配
- 加权:`notes` 字段也参与匹配(权重 0.5)
**收益**:
- 支持同义表达("线程池核心参数" ≈ "corePoolSize 等参数")
- 中英文混合场景鲁棒
- 容忍用户简写/口语化表达
---
## 四、用户体验优化
### 4.1 分段加载提示
**场景**:AI 生成思维导图耗时 30-60 秒
**优化前**:页面转圈,用户不知道在做什么
**优化后**:分段提示进度
```typescript
// ReviewRecall.vue
if (aiEnabled) {
message.info('正在调用 AI 生成思维导图...');
// 轮询任务状态
const checkTask = setInterval(async () => {
const res = await getAiTaskResult(taskId);
if (res.data.status === 'completed') {
message.success('生成完成');
clearInterval(checkTask);
}
}, 2000);
}
```
**收益**:
- 降低用户焦虑
- 明确系统状态
- 减少重复点击
### 4.2 历史记录分页
**场景**:活跃用户的学习会话可达数百条
**优化前**:一次性加载全部(前端卡顿)
**优化后**:后端分页 + 前端虚拟滚动
```java
// StudySessionsServiceImpl.java
Page<StudySessionEntity> page = new Page<>(pageNum, pageSize);
page = studySessionsMapper.selectPage(page, queryWrapper);
```
```vue
<!-- StartTask.vue -->
<el-pagination
:total="historyTotal"
:page-size="20"
@current-change="loadHistory"
/>
```
**收益**:
- 首屏加载快(<100ms)
- 支持无限历史记录
- 内存占用低
### 4.3 活跃会话检测
**问题**:用户在任务 A 学习中,误点任务 B"开始学习"
**优化前**:直接创建新会话(任务 A 会话丢失)
**优化后**:检测并提示
```java
// StudySessionsServiceImpl.startSession()
StudySessionEntity active = studySessionsMapper.selectOne(
new QueryWrapper<StudySessionEntity>()
.eq("created_by", userId)
.eq("status", StudySessionStatus.IN_PROGRESS.name())
);
if (active != null && !active.getTaskNum().equals(taskNum)) {
throw new BusinessException("您有正在进行的学习会话(任务 " + active.getTaskNum() + "),请先结束");
}
```
**收益**:
- 防止意外丢失数据
- 引导用户正确流程
- 减少客服咨询
---
## 五、安全与健壮性
### 5.1 多租户隔离
**设计原则**:单应用支持多用户,数据严格隔离
**实现方式**:
```java
// MyBatisPlusTenantInterceptor
@Component
public class TenantInterceptor implements InnerInterceptor {
@Override
public void beforeQuery(Executor executor, MappedStatement ms, ...) {
// 自动注入 WHERE created_by = :currentUserId
}
}
```
**覆盖范围**:
- 所有 SELECT 查询自动加租户过滤
- INSERT 自动注入 `created_by`
- UPDATE/DELETE 验证租户权限
**收益**:
- 业务代码无感知(避免遗漏)
- 100% 防止越权访问
- 支持未来 SaaS 化
### 5.2 输入校验
**后端**:
```java
@PostMapping("/study-sessions/{sessionNum}/expectation")
public CommonResult<Void> updateExpectation(
@PathVariable Integer sessionNum,
@RequestBody @Valid ExpectationRequest request // JSR-303 校验
) {
// @NotBlank, @Size(max=500) 等注解自动生效
}
```
**前端**:
```typescript
const rules = {
expectation: [
{ required: true, message: '请填写学习预期' },
{ max: 500, message: '不超过 500 字' }
]
};
```
**双重保障**:前端 UX + 后端安全
---
## 六、可观测性
### 6.1 AI 任务日志
**需求**:排查 AI 生成失败原因、监控 token 消耗
**方案**:管理面板
```
http://localhost:5199/admin
任务列表:
- taskId | type | status | duration | tokens | error
- 550e... | generate-mind-map | completed | 32.5s | 1250 | -
- 661f... | aggregate-report | failed | 5.0s | 0 | Timeout
```
**收益**:
- 快速定位问题
- 成本分析
- 性能优化依据
### 6.2 Flyway 迁移历史
**收益**:
- 数据库 schema 版本可追溯
- 回滚方案清晰
- 团队协作无冲突
```sql
SELECT * FROM flyway_schema_history ORDER BY installed_rank;
```
---
## 七、技术债务管理
### 已知限制
1. **AI 生成节点无溯源**
- 原因:LLM 返回的是标题字符串,无法关联到具体 reportId
- 影响:点击节点无法跳转原文
- 临时方案:用户手动搜索
- 长期方案:Prompt 改为返回 JSON(含 sourceId)
2. **Bigram 对短文本效果有限**
- 场景:节点标题只有 2-3 个字
- 临时方案:阈值降至 0.4
- 长期方案:引入 embedding 语义匹配
3. **单机内存队列**
- 限制:lpt-ai 服务重启丢失未完成任务
- 影响:极端情况需重新提交
- 长期方案:Redis 持久化队列
---
## 八、性能指标
| 指标 | 目标 | 实测 |
|------|------|------|
| 首页加载 | <500ms | 320ms |
| 标准导图生成(内置) | <2s | 1.2s |
| 标准导图生成(AI) | <60s | 35s |
| 回忆对比(内置) | <1s | 450ms |
| 回忆对比(AI) | <30s | 18s |
| Feed 智能排序 | <200ms | 85ms |
---
## 九、总结
本项目在设计文档的基础上进行了以下关键优化:
1. **架构层**:异步任务、防并发、降级机制
2. **数据层**:双格式存储、节点溯源、分页加载
3. **算法层**:智能排序、模糊匹配、语义对比
4. **体验层**:分段提示、活跃检测、历史记录
5. **安全层**:多租户隔离、双重校验、权限控制
这些优化不是对设计的否定,而是在实现过程中针对实际场景的工程化改进。设计文档描述"做什么",本文档记录"怎么做得更好"。
-164
View File
@@ -1,164 +0,0 @@
# 复习模块设计说明
本文档是对复习功能当前实现边界的工程说明,不修改原始需求文档。
## 核心理解
复习模块包含两类不同层级的体验:碎片化提醒和围绕思维导图的主动回忆。二者都属于复习模块,但不是同一个业务流程。
## 碎片化提醒
碎片化提醒展示用户自己在学习过程中写下的学习报告和学习残片。
这些内容不是完整复习记录,而是日常滚动出现的记忆触发物。用户看到一段自己写过的内容时,如果能立刻回想起上下文,说明相关知识暂时不需要深入复习;如果想不起来,可以点击进入详情页回看,形成一次轻量提醒。
当前对应能力:
- `GET /review/feed`
- `GET /review/task/{taskNum}`
- `GET /review/report/{id}`
- `GET /review/fragment/{id}`
- 前端 `Review.vue`
- 前端 `ReviewDetail.vue`
## 当前阶段边界
当前阶段暂不追求完整的自动化复习分析,因为项目尚未引入 AI 来处理学习碎片和导图数据。
当前阶段复习模块只需要保留思维导图的基本结构能力:
- 保存任务对应的思维导图
- 支持用户上传外部导图文件
- 解析导图的基础节点结构
- 允许用户在碎片化提醒中回看学习报告和学习残片
这个阶段不应该强制用户逐条处理大量学习碎片。学习碎片很多时,逐条关联和对照会让复习过程变得漫长、枯燥,并违背复习模块“简单、不抵触、可随意围绕某个知识点复习”的初衷。
## 思维导图的意义
思维导图不是普通附件,也不是单纯的存储对象。它是复习模块的主要交互形式。
用户复习时,主要动作应该是围绕某个知识点进行回忆,并编写或重绘思维导图。导图的意义在于降低复习阻力:用户不需要按顺序处理所有碎片,而是可以从任意知识点出发,自由地把自己能想起来的内容组织成结构。
初版设计中已经提到:
- 后续复习时可以在脑子里重绘那张图
- 没有想起来的部分就是需要重新看的地方
- 如果顺利绘制出了好的思维导图,就替换原来的思维导图
- 如果能顺利用思维导图描述所学内容,复习效果就能体现在这个过程中
因此,导图应该是复习效果的表达方式,而不仅是文件存储。
## 应用场景的位置
应用场景不应归属复习模块。
应用场景更接近学习任务的最终目标:完成整个学习任务后,用户希望能做什么、产出什么、应用到哪里。它应该挂在学习任务模块下,而不是挂在复习流程或某条学习碎片下。
当前实现已将其迁移为任务级能力,由任务页面维护,并使用 `task_applications` 存储。
## 模块边界
学习执行模块产生学习报告和学习残片。
复习模块使用这些产物做两件事:
- 在碎片化提醒中滚动展示它们
- 在引入 AI 后,把它们整理进程序生成的知识网络
复习模块不要求用户手动逐条整理学习报告和学习残片。学习报告/残片是后续自动整理和对照分析的数据来源。
## 下一阶段设计:AI 生成导图与用户导图对比
下一阶段引入 AI 后,复习模块的目标应升级为:
1. 程序读取学习报告、学习残片、已有导图等数据。
2. 程序自动将碎片整理成一个具有关联关系的巨大思维导图。
3. 用户围绕某个知识点进行回忆,并绘制自己的导图。
4. 系统将用户导图与程序生成导图进行结构对比。
5. 系统定位用户忽略、遗漏、误解或尚未建立关联的内容。
6. 用户根据差异回看必要的学习报告或残片,而不是从头处理所有碎片。
这个设计可以解决当前手动复习流程的两个问题:
- 学习碎片很多时,不需要用户逐条筛选,避免复习过程漫长且枯燥。
- 思维导图不再只是存储对象,而是成为用户回忆结果和程序知识网络之间的对照媒介。
## 对初版设计的补充判断
初版设计没有忽略“思维导图用于复习”的方向,反而已经明确指出导图应承担脑内重绘、发现遗漏、体现复习效果的作用。
初版设计没有具体描述“AI 自动整理碎片为巨大导图,并与用户导图进行对比”的实现逻辑。这是当前讨论对初版设计的重要补充,适合放入下一阶段实现。
初版中提到”复习内容可以应用到什么地方”,但结合当前理解,应用场景应从复习模块中移出,归入学习任务的最终目标或验收目标。
## 第二阶段实现:标准思维导图与回忆对比(2026-07-03)
第二阶段将 AI 生成导图与用户导图对比的设计落地,引入以下能力:
### 核心概念
- **标准思维导图(Standard Mind Map)**:每个学习任务对应一份”标准”导图,由系统从该任务的已有学习报告、学习残片、应用场景中提取整理而成。它是用户回忆的对照基准,也可由用户手动编辑修正。
- **回忆对比(Recall Review)**:用户凭记忆以缩进大纲格式写下对该任务知识点的回忆,系统将其与标准导图进行树结构对比,定位已掌握、遗漏和额外回忆的内容。
### 内置生成器(BuiltinMindMapGenerator)
当前阶段未接入外部 AI,由内置规则引擎生成标准导图:
- **根节点**:任务名称
- **一级分支**:按学习会话分组,以”日期 + 报告前60字摘要”为标题
- **子分支**:该会话下的每条报告、每条残片成为一个子节点
- **应用场景分支**:如有已创建的应用场景,附加为独立的”应用场景”分支
- **去重**:同级节点按标准化标题对比并合并
- **追溯**:每个节点携带 `sourceType`(REPORT/FRAGMENT/APPLICATION)和 `sourceId`,前端可点击回看原文
### AI 客户端抽象(MindMapAiClient)
预留了远程 AI 调用接口,供后续接入真实 AI 使用:
- 配置项 `lpt.ai.endpoint` / `lpt.ai.api-key`(当前均未配置)
- 未配置时自动回退到内置生成器
- 接口返回 `MindMapNode` 树结构,与内置生成器输出格式一致
### 回忆对比算法(StandardMindMapServiceImpl.compareTrees)
对比标准导图与用户回忆大纲的树结构:
1. **展平**:前序遍历将两颗树分别展开为节点列表
2. **精确匹配**:对每个标准节点标题做归一化(去空格标点 + 小写),在回忆节点中查找完全匹配
3. **模糊匹配**:未精确匹配时,计算字符 Bigram Jaccard 相似度(阈值 0.6),容忍中文同义表达
4. **标注**:匹配的节点标注 `MATCHED`,遗漏的节点标注 `MISSED`,用户多写的内容归为 `EXTRA`
5. **统计**:计算回忆覆盖率 `recall_ratio = matched / (matched + missed)`
### 用户交互
- **回忆复习页**(`/review/recall/:taskNum`):双栏布局。左栏为回忆大纲输入区(缩进文本)+ 对比结果展示,右栏为标准导图区(默认折叠防剧透)
- **标准导图编辑**:用户可展开查看、编辑大纲文本并保存,编辑后来源标记为 `USER`
- **重新生成**:如需从头生成新版本,可一键重新生成
- **遗漏项回溯**:对比后定位到的遗漏知识点自动列出,点击”查看原文”可直接跳转到对应的报告/残片详情页
- **回忆历史**:查阅历次回忆对比记录,查看覆盖率变化趋势
### 新增数据库表
- `review_standard_mind_maps`:每任务一行,存储标准导图的 JSON 树结构、大纲文本、生成元信息
- `review_recall_records`:存储用户每次回忆对比的原始大纲、对比结果 JSON、覆盖率等统计
未改动既有表的 schema,与原有 `review_mind_maps`(用户手动上传的导图文件)并存。
### 新增端点
| 方法 | 端点 | 说明 |
|------|------|------|
| GET | `/review/standard-mind-map/{taskNum}` | 获取或自动生成标准导图 |
| POST | `/review/standard-mind-map/{taskNum}/regenerate` | 强制重新生成 |
| PUT | `/review/standard-mind-map/{taskNum}` | 用户编辑标准导图 |
| POST | `/review/standard-mind-map/{taskNum}/recall` | 用户提交回忆大纲,返回对比结果 |
| GET | `/review/standard-mind-map/{taskNum}/recall-records` | 回忆对比历史列表 |
| GET | `/review/standard-mind-map/recall-records/{recordId}` | 单条回忆记录详情 |
### 下一步展望
- 接入真实 AI API(配置 `lpt.ai.api-key` 后切换为 AI 生成器,内置生成器作为降级)
- 可视化思维导图渲染(而非纯缩进文本展示)
- 对比结果中显示更精确的路径定位
- AI 驱动的用户导图评分与改进建议
+2
View File
@@ -0,0 +1,2 @@
# 让 Lombok 生成的方法带 @Generated 注解,JaCoCo 自动排除生成代码,覆盖率只统计手写逻辑
lombok.addLombokGeneratedAnnotation = true
+24
View File
@@ -0,0 +1,24 @@
# AI 集成
- **功能**:约束学习引导与 AI 异步生成链路的实现方式。
- **何时用**:接入或改动 AI 相关功能、新增后台任务、处理生成类能力时。
## 学习引导(复习-06)
一次引导是一次**复习行为**,有自己的记录实体 `review_guidance_conversations`:
- 产出的知识碎片以它作为**记录上下文**(`context_type=REVIEW`),默认内容归属为被引导概念所属任务,并带 `FROM_GUIDANCE` 系统标记。
- 复习耗时记在会话行上(与回忆对比同一口径)。
- 多轮对话复用 AI 异步任务:每轮提交一个 `GUIDANCE` 任务,前端轮询取回复;AI 回复会写回会话轮次,供下一轮作为上下文。
- **没有降级形态**:AI 不可用时该链路直接失败,前端把入口置为不可用。
## AI 异步链路(AI-02)
生成类能力(回忆对比、标准导图、报告草稿)不在请求线程里等 AI:
- 前端 `POST /ai/tasks` 提交,秒级拿到 `taskNum`;随后轮询 `GET /ai/tasks/{taskNum}` 直到 `SUCCEEDED`/`FAILED`。
- 结果写在 `ai_tasks.result_payload`,按 `taskNum` 可重复获取,刷新或离开页面都不丢。
- 同一用户 + 同一类型 + 同一目标已有进行中任务时复用该任务(AI-04),不重复生成。
- 执行器在 `ai-task-*` 线程池里跑;提交后立即投递,`@Scheduled` 兜底扫描接手投递失败或进程重启的任务。
- **后台线程必须显式声明身份**:执行线程没有 Web 上下文,租户拦截器与 `MetaObjectHandler` 字段自动填充都取不到当前用户。执行器用 `TenantContext.callAs(task.createdBy, ...)` 绑定任务所属用户;请求线程不受影响(没有绑定时仍走 `StpUtil`)。新增后台任务时必须照此处理,否则会抛 `NotWebContextException`。
- 禁止在 `@Transactional` 方法内调用 AI:等待 AI 期间不得占用数据库连接。
+19
View File
@@ -0,0 +1,19 @@
# 响应规范与 DTO 转换
- **功能**:统一 API 的响应形态、错误文案风格与 DTO 转换方式。
- **何时用**:新增或修改接口返回值、处理异常、增删 DTO 字段或自定义映射时。
## 响应规范
- 成功:`CommonResult.success(data)`,code=200。
- 业务错误:`CommonResult.error(msg)`,code=400,HTTP 200。
- 未登录:`GlobalExceptionHandler.handleNotLogin()`,HTTP 401 + code=401。
- 参数校验失败:`MethodArgumentNotValidException`,code=400。
- 用户可见错误文案必须口语化、可理解,避免“无法生成”“不存在”等技术化表述;技术细节写入日志。例如无学习报告时应提示“这个任务还没开始学习哦,学习后产生学习报告后再来吧”,而不是“没有学习报告,无法生成思维导图”。
## DTO 转换
- MapStruct 编译期生成 `*ConvertImpl.java`,同名属性自动映射。
- 默认 `unmappedTargetPolicy = IGNORE`。
- 自定义映射使用 `@Mapping(source, target)`。
- 增删 DTO 字段后必须重新编译,否则生成代码不含新字段。
+19
View File
@@ -0,0 +1,19 @@
# 数据访问层编码规范
- **功能**:规定数据访问层的实现方式,避免手写 SQL 与字符串 key 取值带来的跨库隐患。
- **何时用**:编写 Mapper 或查询逻辑、需要聚合或联表、评审数据访问代码时。
## 编码规范
### 数据访问层
- **优先使用纯 MyBatis-Plus Java API**(`Wrappers.<T>lambdaQuery()`、`selectList`、`selectById` 等),避免手写 XML SQL
- 复杂查询通过 `Wrappers` 链式构建条件,必要时使用 `.apply()` 拼接原生 SQL 片段
- **查询结果一律用类承载,禁止 `selectMaps` + 字符串 key 取值**
- MyBatis 对 Map 结果直接用 JDBC 列名作 key,不做属性映射:`map-underscore-to-camel-case` 与「属性名大小写不敏感」只对类结果生效。而数据库的标识符大小写规则各不相同(MySQL 保留别名、H2/PostgreSQL 转小写、Oracle 转大写),`row.get("taskNum")` 会在部分库上静默取到 null,表现为「数据莫名变 0」而不是报错
- 单列聚合用 `selectObjs`,多列聚合用下面的自定义 Mapper 方法
- **`Wrapper` 表达不了的查询(`SUM`/`GROUP BY`/多表 `JOIN`)收敛到 Mapper 层**,用自定义方法 + **显式结果类**(`dto/` 下的类或实体),参考 `ReviewRecallRecordMapper.sumReviewDurationByTask` → `dto/TaskReviewDuration` + `resources/mapper/ReviewRecallRecordMapper.xml`
- 结果映射:列名与属性能对应时可用自动映射,但 `map-underscore-to-camel-case` 必须在 `application.yml` 里显式声明(已配置),不要依赖框架默认值;出现别名、计算列或列名与属性不一致时必须写显式 `<resultMap>`
- **自定义 SQL 不会被 `@TableLogic` 自动追加逻辑删除条件**,必须显式写 `deleted = 0`;租户条件 `created_by = ?` 仍由 `TenantLineInnerInterceptor` 自动追加
- 上述两条不能只靠 mock 单测,需落库集成测试守住(参考 `ReviewDurationIntegrationTest`)
- 反向约束:`Wrapper` 能表达的查询不要为「类型安全」提前下沉为自定义 SQL;确实要下沉时,SQL 只留在 Mapper 层,不要在 service 里拼字符串
+35
View File
@@ -0,0 +1,35 @@
# 数据库迁移
- **功能**:约束 Flyway 迁移脚本的写法,让数据库结构变更可追溯、可部署。
- **何时用**:新增或修改表结构、编写迁移脚本、调整索引、部署前核对历史数据时。
## 数据库迁移(Flyway Migration)
### 测试用 H2、部署用 MySQL:这几件事 H2 测不出来
迁移脚本在测试里跑的是 H2(`MODE=MySQL`),它与真实 MySQL 的差异会造成「测试全绿、部署起不来」:
- **索引键长度上限**:InnoDB 对索引键有 3072 字节硬上限(DYNAMIC 行格式),超了直接报 error 1071;
utf8mb4 下 `VARCHAR(n)` 要按 `4n` 字节算,多列唯一键很容易越界。**H2 不校验**。
→ 改动任何索引后跑 `MigrationIndexKeyLengthTest`(它直接读迁移文件复算键长)。
- **整型显示宽度**:`TINYINT(1)` 在 MySQL 8.0.17 起被标记弃用(MySQL 9.7 文档确认**尚未移除**,只是弃用)。
这里刻意保留 `TINYINT(1)`:它正是 JDBC 把列映射成 `Boolean` 的惯用声明,换成裸 `TINYINT` 会让布尔字段的映射行为依赖连接参数。
- **遇脏数据要响亮失败**:`V20261009_3`(业务编号唯一约束)与 `V20261009_5`(计时列类型修正)
在历史数据不干净时会直接让启动失败。这是有意的——宁可失败也不静默跳过约束。部署前先按迁移注释里的核对 SQL 检查。
### 命名规则
- 脚本格式:`V{YYYYMMDD}_{序号}__{描述}.sql`
- 日期必须使用**实际编写日期**,不得使用过去的日期
- 序号从 1 开始,同一天多个脚本递增
- 描述使用下划线分隔的英文短语
### 核心原则
- **不可变性**:已执行的迁移脚本永远不得修改
- **只增不减**:数据库变更只能通过新增迁移脚本实现
- **向后兼容**:新脚本应兼容已有数据
### 操作规范
- 删除表:创建新迁移脚本,使用 `DROP TABLE IF EXISTS`
- 修改表结构:使用 `ALTER TABLE` 语句
- 新增表:创建新迁移脚本,使用 `CREATE TABLE`
+31
View File
@@ -0,0 +1,31 @@
# 内容归属与标记
- **功能**:区分知识碎片的「记录上下文」与「内容归属」两个维度,并统一管理标记元信息。
- **何时用**:改动碎片归属、生成或查看报告、取材导图、新增或检索标记时。
## 内容归属与结构化报告(归属-01 / 报告-01)
知识碎片有两个**互相独立**的维度,改动任何一处都要先分清是哪一维:
- **记录上下文**(`context_type` + `context_num`):产生于哪次学习会话或复习行为。由系统确定、**不可变、不可为空**;用于时间统计与「这份报告里有哪些碎片」。
- **内容归属**(`owner_task_num`):内容在知识结构上属于哪个任务。由用户确定、**可变、可为空**(为空即待归类);用于导图取材、按任务检索与统计。
由此得出的几条硬约束:
- **导图、按任务检索、碎片计数一律按内容归属**(`owner_task_num`),不再用「该任务的会话所产生的报告/碎片」。
- **报告按会话生成**,报告的任务来自它所属会话——这与上一条是两个视角,是有意为之,不是重复。
- 新建碎片时内容归属默认取该会话所属任务;用户可以改到别的任务或清空为待归类。
- 归属变化(或碎片删除)会把**原任务与新任务**的标准导图标记为 `needs_update=1`;重建由用户手动触发,不自动跑 AI。
- 报告只落库三段文本(`session_summary` / `expectation_verdict` / `free_summary`);「按归属分组的碎片」**不落库**,查看时按当前归属实时聚合,以免与导图取材出现两套口径。文档里的展示顺序是:会话摘要 → 预期达成判断 → 按归属分组的碎片 → 自由总结。
- 删除报告**不**连带删除碎片;删除任务时碎片保留并把归属置空(进入待归类),其余(会话、报告、导图、回忆记录、应用场景)随任务软删除。
## 标记(标记-01)
标记是附加在对象上的轻量元信息,**统一存放**,新增一种标记不改各功能表结构。
- **可挂对象只有知识碎片与学习任务**:报告是会话的派生结果且已有「按归属分组」这一维度;会话是时间轴对象,其流程性信息留在主体上。
- **两类彻底分开**:系统标记走 `SystemMarkerEnum` 固定词表、由系统写入、用户只读;用户标签自由增删改。分开的理由是「找出所有来自 X 的内容」这类检索必须可靠。
- **系统标记成对(名 = 值)**,用户标签只有名(标签名本身就是全部信息)。
- 检索只提供**单一标记筛选**;标记对用户全部可见,标签可改名可删除(改名安全:标记不参与聚合口径)。
- **标记不是状态**:会话状态、报告可否修订、导图是否待更新这类流程判断留在主体上。碎片上的复习反馈(已掌握/稍后再看)也因此落在碎片自身字段,不进标记表。
- 对象被删除时清理其标记(`MarkerService.removeAllMarkers`)。
@@ -5,6 +5,7 @@ import com.guo.learningprogresstracker.entity.CommonResult;
import com.guo.learningprogresstracker.exception.AppException;
import com.guo.learningprogresstracker.exception.ErrorParameterException;
import com.guo.learningprogresstracker.exception.NotFindEntitiesException;
import com.guo.learningprogresstracker.exception.OperationFailedException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import lombok.extern.slf4j.Slf4j;
@@ -21,16 +22,25 @@ public class GlobalExceptionHandler {
@ExceptionHandler({ErrorParameterException.class})
public CommonResult errorParameterException(ErrorParameterException ex) {
log.warn("参数异常: {}", ex.getMessage(), ex);
return CommonResult.error(ex.getMessage());
}
@ExceptionHandler({NotFindEntitiesException.class})
public CommonResult notFindEntitiesException(NotFindEntitiesException ex) {
log.warn("数据不存在: {}", ex.getMessage(), ex);
return CommonResult.error(ex.getMessage());
}
@ExceptionHandler({OperationFailedException.class})
public CommonResult operationFailedException(OperationFailedException ex) {
log.warn("操作失败: {}", ex.getMessage(), ex);
return CommonResult.error(ex.getMessage());
}
@ExceptionHandler({AppException.class})
public CommonResult AppException(AppException ex) {
log.error("业务异常: {}", ex.getMessage(), ex);
return CommonResult.serverError(ex.getMessage());
}
@@ -49,7 +59,7 @@ public class GlobalExceptionHandler {
@ExceptionHandler(Exception.class)
public CommonResult Exception(Exception ex) {
log.error("系统异常", ex);
return CommonResult.error(ex.getMessage());
return CommonResult.error("操作没有成功,请稍后再试");
}
}
@@ -0,0 +1,64 @@
package com.guo.learningprogresstracker.common;
import lombok.Getter;
/**
* 学习会话的时间口径(会话-04 起改为可配置的值对象)。
*
* <p>番茄钟长度、遗忘判定阈值、硬兜底阈值与有效时间下限集中在此处,避免阈值散落在实体与服务的各个角落。
* 生产路径由 Spring 从 {@code lpt.study-time} 配置构建并注入;{@link #DEFAULT} 只保留设计口径的默认值,
* 供实体自身的默认重载与单测使用,不要在服务里直接用它。</p>
*/
@Getter
public class StudyTimePolicy {
/** 与 lpt-docs 设计口径一致的默认值 */
public static final StudyTimePolicy DEFAULT = new StudyTimePolicy(25, 50, 120, 600);
/**
* 番茄钟长度(分钟)。
*/
private final int workDurationMinutes;
/**
* 遗忘判定阈值(分钟):通常为 2 × 番茄钟。
*/
private final int forgetThresholdMinutes;
/**
* 硬兜底阈值(分钟):进行中的会话超过该时长未收敛,服务端强制暂停。
*/
private final int forcePauseMinutes;
/**
* 有效学习时间下限(秒)。
*/
private final long minEffectiveTimeSeconds;
public StudyTimePolicy(int workDurationMinutes, int forgetThresholdMinutes,
int forcePauseMinutes, long minEffectiveTimeSeconds) {
if (workDurationMinutes <= 0) {
throw new IllegalArgumentException("番茄钟长度必须大于 0 分钟");
}
if (forgetThresholdMinutes < workDurationMinutes) {
throw new IllegalArgumentException("遗忘判定阈值不能小于番茄钟长度");
}
if (forcePauseMinutes < forgetThresholdMinutes) {
throw new IllegalArgumentException("硬兜底阈值不能小于遗忘判定阈值");
}
if (minEffectiveTimeSeconds < 0) {
throw new IllegalArgumentException("有效学习时间下限不能为负数");
}
this.workDurationMinutes = workDurationMinutes;
this.forgetThresholdMinutes = forgetThresholdMinutes;
this.forcePauseMinutes = forcePauseMinutes;
this.minEffectiveTimeSeconds = minEffectiveTimeSeconds;
}
/**
* 番茄钟长度(毫秒)。
*/
public long workDurationMillis() {
return workDurationMinutes * 60_000L;
}
}
@@ -0,0 +1,56 @@
package com.guo.learningprogresstracker.common;
/**
* 显式的租户上下文(AI-02)。
*
* <p>租户拦截器与公共字段自动填充都从 {@code StpUtil} 取当前用户,而它依赖 Web 请求上下文。
* 后台执行线程(AI 任务执行器、定时收敛)没有请求上下文,直接调用会抛
* {@code NotWebContextException};这里让后台线程显式声明「我以哪个用户身份在执行」。</p>
*
* <p>取值优先级:<b>本上下文优先</b>,没有时才回落到 {@code StpUtil}。这样请求线程的行为完全不变,
* 后台线程也只能以任务所属用户的身份执行,不会意外变成「无租户」而看到全部数据。</p>
*/
public final class TenantContext {
/**
* 执行身份。
*
* @param loginId 登录用户
* @param device 设备类型,可为 null(后台任务通常没有设备信息)
*/
public record Identity(String loginId, String device) {
}
private static final ThreadLocal<Identity> CURRENT = new ThreadLocal<>();
private TenantContext() {
}
/** 取当前执行身份;未设置时返回 null(表示应回落到 StpUtil) */
public static Identity get() {
return CURRENT.get();
}
/** 在指定身份下执行;执行结束后恢复原身份,避免线程池复用造成身份串号 */
public static void runAs(String loginId, String device, Runnable action) {
callAs(loginId, device, () -> {
action.run();
return null;
});
}
/** 在指定身份下执行并返回结果(异常原样向外抛,由调用方决定如何回写) */
public static <T> T callAs(String loginId, String device, java.util.function.Supplier<T> action) {
Identity previous = CURRENT.get();
CURRENT.set(new Identity(loginId, device));
try {
return action.get();
} finally {
if (previous == null) {
CURRENT.remove();
} else {
CURRENT.set(previous);
}
}
}
}
@@ -0,0 +1,30 @@
package com.guo.learningprogresstracker.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.scheduling.annotation.EnableAsync;
import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor;
/**
* AI 任务执行器装配(AI-02)。
* <p>执行线程与请求线程分离,AI 调用不会占用 HTTP 请求线程,也不会持有请求期间打开的数据库连接。</p>
*/
@Configuration
@EnableAsync
public class AiTaskConfig {
public static final String AI_TASK_EXECUTOR = "aiTaskExecutor";
@Bean(name = AI_TASK_EXECUTOR)
public ThreadPoolTaskExecutor aiTaskExecutor(AiTaskProperties properties) {
ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
executor.setCorePoolSize(properties.getExecutorCoreSize());
executor.setMaxPoolSize(properties.getExecutorMaxSize());
executor.setQueueCapacity(properties.getExecutorQueueCapacity());
executor.setThreadNamePrefix("ai-task-");
// 队列满时由调用线程执行,避免任务被静默丢弃(定时兜底仍会接手)
executor.setRejectedExecutionHandler(new java.util.concurrent.ThreadPoolExecutor.CallerRunsPolicy());
executor.initialize();
return executor;
}
}
@@ -0,0 +1,33 @@
package com.guo.learningprogresstracker.config;
import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Configuration;
/**
* AI 异步任务配置(AI-02)。
*/
@Data
@Configuration
@ConfigurationProperties(prefix = "lpt.ai-task")
public class AiTaskProperties {
/** 单个任务允许的最长执行时间(秒):超过则视为进程中断,回收后可重试 */
private long stuckTimeoutSeconds = 900;
/** 兜底扫描间隔(毫秒) */
private long scanIntervalMs = 3000;
/** 首次兜底扫描的延迟(毫秒):让「提交后立即投递」先执行 */
private long scanInitialDelayMs = 3000;
/** 单次扫描最多处理多少个任务 */
private int scanBatchSize = 10;
/** 立即投递用的线程池大小 */
private int executorCoreSize = 2;
private int executorMaxSize = 4;
private int executorQueueCapacity = 50;
}
@@ -0,0 +1,29 @@
package com.guo.learningprogresstracker.config;
import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Configuration;
import java.math.BigDecimal;
import java.util.List;
/**
* AI 用量统计配置。
*/
@Data
@Configuration
@ConfigurationProperties(prefix = "lpt.ai-usage")
public class AiUsageProperties {
/** 可见「AI 用量统计」入口的用户名白名单(按 {@code user.user_name} 精确匹配) */
private List<String> adminUsernames = List.of("admin");
/** lpt-ai 上报用量时携带的令牌;为空表示不校验 */
private String reportToken = "";
/** 代理查询上游余额的超时(秒) */
private int balanceTimeoutSeconds = 10;
/** 费用展示用的美元兑人民币汇率:{@code costCny = costUsd × 该值} */
private BigDecimal usdToCny = BigDecimal.valueOf(7);
}
@@ -2,6 +2,7 @@ package com.guo.learningprogresstracker.config;
import cn.dev33.satoken.stp.StpUtil;
import com.baomidou.mybatisplus.core.handlers.MetaObjectHandler;
import com.guo.learningprogresstracker.common.TenantContext;
import lombok.extern.slf4j.Slf4j;
import org.apache.ibatis.reflection.MetaObject;
import org.springframework.context.annotation.Configuration;
@@ -20,18 +21,35 @@ public class AutoTableField implements MetaObjectHandler {
@Override
public void insertFill(MetaObject metaObject) {
this.strictInsertFill(metaObject, "createdBy", StpUtil::getLoginIdAsString, String.class);
this.strictInsertFill(metaObject, "createdBy", AutoTableField::currentLoginId, String.class);
this.strictInsertFill(metaObject, "createdTime", LocalDateTime::now, LocalDateTime.class);
this.strictInsertFill(metaObject, "lastModifiedBy", StpUtil::getLoginIdAsString, String.class);
this.strictInsertFill(metaObject, "lastModifiedBy", AutoTableField::currentLoginId, String.class);
this.strictInsertFill(metaObject, "lastModifiedTime", LocalDateTime::now, LocalDateTime.class);
this.strictInsertFill(metaObject, "deviceInfo", AutoTableField::currentDevice, String.class);
}
@Override
public void updateFill(MetaObject metaObject) {
this.strictInsertFill(metaObject, "lastModifiedBy", StpUtil::getLoginIdAsString, String.class);
this.strictInsertFill(metaObject, "lastModifiedBy", AutoTableField::currentLoginId, String.class);
this.strictInsertFill(metaObject, "lastModifiedTime", LocalDateTime::now, LocalDateTime.class);
this.strictInsertFill(metaObject,"deviceInfo",StpUtil::getLoginDevice,String.class);
this.strictInsertFill(metaObject, "deviceInfo", AutoTableField::currentDevice, String.class);
}
/**
* 当前登录用户:后台执行线程通过 {@link TenantContext} 显式声明身份,请求线程仍走 StpUtil。
*/
static String currentLoginId() {
TenantContext.Identity identity = TenantContext.get();
return identity != null ? identity.loginId() : StpUtil.getLoginIdAsString();
}
/**
* 当前设备:后台任务通常没有设备信息,返回 null 时跳过该项填充(保持列为空而不是写脏值)。
*/
static String currentDevice() {
TenantContext.Identity identity = TenantContext.get();
return identity != null ? identity.device() : StpUtil.getLoginDevice();
}
}
@@ -1,6 +1,7 @@
package com.guo.learningprogresstracker.config;
import cn.dev33.satoken.stp.StpUtil;
import com.guo.learningprogresstracker.common.TenantContext;
import net.sf.jsqlparser.expression.StringValue;
import com.baomidou.mybatisplus.extension.plugins.MybatisPlusInterceptor;
import com.baomidou.mybatisplus.extension.plugins.inner.PaginationInnerInterceptor;
@@ -22,24 +23,34 @@ import java.util.List;
public class MybatisPlusConfig {
/**
* 不需要租户过滤的表(仅排除不含 created_by 的系统表)
* 不需要租户过滤的表(仅排除不含 created_by 或不该按 created_by 过滤的表)
*
* <p>{@code ai_usage_records} 是系统级表:记录由 lpt-ai 通过内部接口上报,请求里没有登录用户,
* created_by 只是审计列;用量又是运维口径——管理员要看的是**全部**调用。
* 若按 created_by 过滤,每个人只能看到自己触发的那几次调用,面板等于永远空的。</p>
*/
private static final List<String> EXCLUDE_TABLES = Arrays.asList(
"user",
"flyway_schema_history",
"databasechangelog",
"databasechangeloglock"
"databasechangeloglock",
"ai_usage_records"
);
@Bean
public MybatisPlusInterceptor mybatisPlusInterceptor() {
MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
// 分页拦截器必须注册,否则 selectPage 不会生成 LIMIT / COUNT
interceptor.addInnerInterceptor(new PaginationInnerInterceptor());
// 顺序很重要:MyBatis-Plus 要求「多租户 → 分页」。
// 分页的 count 语句是从「当前已处理的 SQL」派生的;若分页先注册,
// count 会在租户条件追加之前就派生出来,导致 total 把其他用户的行也算进去
// (records 仍然正确,只有分页总数跨租户,极难发现)。
interceptor.addInnerInterceptor(new TenantLineInnerInterceptor(new TenantLineHandler() {
@Override
public Expression getTenantId() {
return new StringValue(StpUtil.getLoginIdAsString());
// 后台执行线程(AI 任务、定时收敛)通过 TenantContext 显式声明身份;
// 请求线程没有设置,仍走 StpUtil,行为完全不变
TenantContext.Identity identity = TenantContext.get();
return new StringValue(identity != null ? identity.loginId() : StpUtil.getLoginIdAsString());
}
@Override
@@ -52,6 +63,8 @@ public class MybatisPlusConfig {
return EXCLUDE_TABLES.contains(tableName.toLowerCase());
}
}));
// 分页拦截器必须注册,否则 selectPage 不会生成 LIMIT / COUNT
interceptor.addInnerInterceptor(new PaginationInnerInterceptor());
return interceptor;
}
}
@@ -0,0 +1,24 @@
package com.guo.learningprogresstracker.config;
import com.guo.learningprogresstracker.common.StudyTimePolicy;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.scheduling.annotation.EnableScheduling;
/**
* 学习会话的时间口径装配(会话-04)。
* <p>阈值来自 {@link StudyTimeProperties};非法组合在启动时直接失败,避免运行期出现「兜底阈值比遗忘阈值还小」这类矛盾配置。</p>
*/
@Configuration
@EnableScheduling
public class StudyTimeConfig {
@Bean
public StudyTimePolicy studyTimePolicy(StudyTimeProperties properties) {
return new StudyTimePolicy(
properties.getWorkDurationMinutes(),
properties.getForgetThresholdMinutes(),
properties.getForcePauseMinutes(),
properties.getMinEffectiveTimeSeconds());
}
}
@@ -0,0 +1,35 @@
package com.guo.learningprogresstracker.config;
import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Configuration;
/**
* 学习会话的时间口径配置(会话-04)。
*
* <p>番茄钟长度、遗忘判定阈值、硬兜底阈值与有效时间下限集中在这里,改口径不需要改代码。
* 默认值与 `lpt-docs` 的设计口径一致:25 分钟番茄钟、50 分钟遗忘判定、2 小时硬兜底。</p>
*/
@Data
@Configuration
@ConfigurationProperties(prefix = "lpt.study-time")
public class StudyTimeProperties {
/** 番茄钟长度(分钟):单个学习段落的上限 */
private int workDurationMinutes = 25;
/** 遗忘判定阈值(分钟):超过该时长无操作,按「忘了点暂停/结束」只结算一个番茄钟 */
private int forgetThresholdMinutes = 50;
/** 硬兜底阈值(分钟):进行中的会话超过该时长仍未结算,由服务端强制收敛 */
private int forcePauseMinutes = 120;
/** 有效学习时间下限(秒):低于该值的一次学习不计入总学习时间 */
private long minEffectiveTimeSeconds = 600;
/** 低频定时收敛扫描的间隔(毫秒) */
private long scanIntervalMs = 600_000;
/** 是否开启低频定时收敛(测试环境可关掉,避免与用例互相干扰) */
private boolean scanEnabled = true;
}
@@ -28,7 +28,9 @@ public class WebMvcConfig implements WebMvcConfigurer {
StpUtil.checkLogin();
}))
.addPathPatterns("/**")
.excludePathPatterns("/login");
// /login:登录接口本身不能要求登录态;
// /internal/**:服务间接口(lpt-ai 用量上报),调用方没有登录态,改用 x-api-token 自校验
.excludePathPatterns("/login", "/internal/**");
}
@Override
@@ -0,0 +1,56 @@
package com.guo.learningprogresstracker.controller;
import com.guo.learningprogresstracker.dto.AiTaskResponse;
import com.guo.learningprogresstracker.dto.request.AiTaskSubmitRequest;
import com.guo.learningprogresstracker.entity.CommonResult;
import com.guo.learningprogresstracker.exception.ErrorParameterException;
import com.guo.learningprogresstracker.exception.NotFindEntitiesException;
import com.guo.learningprogresstracker.service.AiTaskService;
import jakarta.validation.Valid;
import lombok.RequiredArgsConstructor;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;
/**
* AI 异步任务控制层(AI-02)。
*
* <p>提交与查询分离:提交接口秒级返回任务标识,前端随后轮询查询接口拿结果。
* 这样刷新或离开页面都不会丢结果,AI 已消耗的 token 也不会白费。</p>
*/
@RequestMapping("/ai/tasks")
@RestController
@Validated
@RequiredArgsConstructor
public class AiTaskController {
private final AiTaskService aiTaskService;
/**
* 提交 AI 任务。
* <p>同一目标已有进行中任务时直接返回该任务(AI-04:对外是任务状态,而不是可能为空的实体)。</p>
*/
@PostMapping
public CommonResult<AiTaskResponse> submit(@Valid @RequestBody AiTaskSubmitRequest request)
throws ErrorParameterException, NotFindEntitiesException {
return CommonResult.success(aiTaskService.submit(request));
}
/**
* 查询任务状态与结果;结果可重复获取。
*/
@GetMapping("/{taskNum}")
public CommonResult<AiTaskResponse> getTask(@PathVariable String taskNum) throws NotFindEntitiesException {
return CommonResult.success(aiTaskService.getByTaskNum(taskNum));
}
/**
* 查询某目标最近的 AI 任务,用于离开页面再回来时恢复生成状态。
*
* @return 无任务时 data 为 null
*/
@GetMapping("/latest")
public CommonResult<AiTaskResponse> getLatestTask(@RequestParam String type,
@RequestParam String targetNum) {
return CommonResult.success(aiTaskService.findLatest(type, targetNum));
}
}
@@ -0,0 +1,72 @@
package com.guo.learningprogresstracker.controller;
import com.guo.learningprogresstracker.dto.AiUsageBalance;
import com.guo.learningprogresstracker.dto.AiUsageBreakdownItem;
import com.guo.learningprogresstracker.dto.AiUsagePermission;
import com.guo.learningprogresstracker.dto.AiUsageSeriesPoint;
import com.guo.learningprogresstracker.dto.AiUsageSummary;
import com.guo.learningprogresstracker.dto.request.AiUsageQuery;
import com.guo.learningprogresstracker.entity.CommonResult;
import com.guo.learningprogresstracker.exception.ErrorParameterException;
import com.guo.learningprogresstracker.service.AiUsageService;
import lombok.RequiredArgsConstructor;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.List;
/**
* 「AI 用量统计」面板查询接口(契约 2)。
*
* <p>用量记录是系统级数据,只有白名单用户能看:{@code permission} 用 {@code allowed=false}
* 让前端静默隐藏入口,其余接口直接拒绝,避免入口藏起来了、接口却谁都能拉。</p>
*/
@RestController
@RequestMapping("/ai/usage")
@RequiredArgsConstructor
public class AiUsageController {
private static final String NO_PERMISSION_MESSAGE = "没有查看权限";
private final AiUsageService aiUsageService;
/** 当前用户能否查看用量面板;非白名单返回 200 + allowed=false */
@GetMapping("/permission")
public CommonResult<AiUsagePermission> permission() {
return CommonResult.success(new AiUsagePermission(aiUsageService.isAdmin()));
}
@GetMapping("/summary")
public CommonResult<AiUsageSummary> summary(AiUsageQuery query) {
if (!aiUsageService.isAdmin()) {
return CommonResult.error(NO_PERMISSION_MESSAGE);
}
return CommonResult.success(aiUsageService.summary(query));
}
@GetMapping("/series")
public CommonResult<List<AiUsageSeriesPoint>> series(AiUsageQuery query) throws ErrorParameterException {
if (!aiUsageService.isAdmin()) {
return CommonResult.error(NO_PERMISSION_MESSAGE);
}
return CommonResult.success(aiUsageService.series(query));
}
@GetMapping("/breakdown")
public CommonResult<List<AiUsageBreakdownItem>> breakdown(AiUsageQuery query) throws ErrorParameterException {
if (!aiUsageService.isAdmin()) {
return CommonResult.error(NO_PERMISSION_MESSAGE);
}
return CommonResult.success(aiUsageService.breakdown(query));
}
/** 上游余额;lpt-ai 未配置或查询失败时返回 {@code configured=false},不算错误 */
@GetMapping("/balance")
public CommonResult<AiUsageBalance> balance() {
if (!aiUsageService.isAdmin()) {
return CommonResult.error(NO_PERMISSION_MESSAGE);
}
return CommonResult.success(aiUsageService.balance());
}
}
@@ -0,0 +1,62 @@
package com.guo.learningprogresstracker.controller;
import com.guo.learningprogresstracker.config.AiUsageProperties;
import com.guo.learningprogresstracker.dto.AiUsageIngestResult;
import com.guo.learningprogresstracker.dto.request.AiUsageRecordRequest;
import com.guo.learningprogresstracker.dto.request.AiUsageReportRequest;
import com.guo.learningprogresstracker.entity.CommonResult;
import com.guo.learningprogresstracker.exception.ErrorParameterException;
import com.guo.learningprogresstracker.service.AiUsageService;
import jakarta.validation.Valid;
import lombok.RequiredArgsConstructor;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.List;
/**
* lpt-ai 用量上报(契约 1)。
*
* <p>这是服务间接口,不是用户接口:调用方是 lpt-ai 进程,没有登录态,
* 因此 {@code /internal/**} 已在 {@code WebMvcConfig} 中排除 Sa-Token 登录校验,
* 改用 {@code x-api-token} 与 {@code lpt.ai-usage.report-token} 比对(配置为空表示不校验)。</p>
*/
@RestController
@RequestMapping("/internal/ai-usage")
@RequiredArgsConstructor
public class AiUsageInternalController {
/** 契约 1:单次最多 200 条 */
static final int MAX_RECORDS_PER_REPORT = 200;
private final AiUsageService aiUsageService;
private final AiUsageProperties properties;
/**
* 上报用量记录。
*
* <p>按 {@code recordId} 幂等:重复上报不报错,只在结果里体现为 {@code duplicated}。</p>
*/
@PostMapping("/records")
public CommonResult<AiUsageIngestResult> report(
@RequestHeader(name = "x-api-token", required = false) String apiToken,
@Valid @RequestBody AiUsageReportRequest request) throws ErrorParameterException {
if (!isTokenAccepted(apiToken)) {
return CommonResult.error("上报令牌不正确");
}
List<AiUsageRecordRequest> records = request.getRecords();
if (records.size() > MAX_RECORDS_PER_REPORT) {
return CommonResult.error("单次最多上报 " + MAX_RECORDS_PER_REPORT + " 条记录");
}
return CommonResult.success(aiUsageService.ingest(records));
}
/** 契约 1:report-token 为空表示 lpt-ai 未启用令牌校验,直接放行 */
private boolean isTokenAccepted(String apiToken) {
String expected = properties.getReportToken();
return expected == null || expected.isBlank() || expected.equals(apiToken);
}
}
@@ -0,0 +1,50 @@
package com.guo.learningprogresstracker.controller;
import com.guo.learningprogresstracker.dto.ExportResult;
import com.guo.learningprogresstracker.entity.CommonResult;
import com.guo.learningprogresstracker.exception.NotFindEntitiesException;
import com.guo.learningprogresstracker.exception.OperationFailedException;
import com.guo.learningprogresstracker.service.ExportService;
import lombok.RequiredArgsConstructor;
import org.springframework.format.annotation.DateTimeFormat;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;
import java.time.LocalDate;
/**
* 数据导出控制层(导出-01):把学习报告、知识碎片与任务统计导出为 Markdown / JSON。
*/
@RequestMapping("/export")
@RestController
@Validated
@RequiredArgsConstructor
public class ExportController {
private final ExportService exportService;
/**
* 导出单个学习任务的全部学习记录
* @param format markdown(默认)或 json
*/
@GetMapping("/task/{taskNum}")
public CommonResult<ExportResult> exportTask(
@PathVariable String taskNum,
@RequestParam(defaultValue = "markdown") String format)
throws NotFindEntitiesException, OperationFailedException {
return CommonResult.success(exportService.exportTask(taskNum, format));
}
/**
* 按时间范围导出学习记录(起止日期都可省略,都省略为全部时间)
* @param format markdown(默认)或 json
*/
@GetMapping("/range")
public CommonResult<ExportResult> exportRange(
@RequestParam(required = false) @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate startDate,
@RequestParam(required = false) @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate endDate,
@RequestParam(defaultValue = "markdown") String format)
throws OperationFailedException {
return CommonResult.success(exportService.exportRange(startDate, endDate, format));
}
}
@@ -0,0 +1,123 @@
package com.guo.learningprogresstracker.controller;
import com.guo.learningprogresstracker.dto.ReviewTiming;
import com.guo.learningprogresstracker.dto.request.AiTaskSubmitRequest;
import com.guo.learningprogresstracker.entity.CommonResult;
import com.guo.learningprogresstracker.entity.ReviewGuidanceConversationEntity;
import com.guo.learningprogresstracker.entity.StudyReportFragmentsEntity;
import com.guo.learningprogresstracker.exception.ErrorParameterException;
import com.guo.learningprogresstracker.exception.NotFindEntitiesException;
import com.guo.learningprogresstracker.service.AiTaskService;
import com.guo.learningprogresstracker.service.GuidanceService;
import com.guo.learningprogresstracker.dto.AiTaskResponse;
import io.swagger.v3.oas.annotations.Operation;
import lombok.RequiredArgsConstructor;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;
import java.time.LocalDateTime;
import java.time.format.DateTimeParseException;
import java.util.LinkedHashMap;
import java.util.Map;
/**
* 学习引导控制层(复习-06)。
*
* <p>多轮对话复用 AI 异步任务(AI-02):每一轮提交一个 {@code GUIDANCE} 任务,前端轮询拿回复。
* 因此生成期间可以离开页面,回来继续;一轮的耗时也不会占用请求线程。</p>
*
* <p>产出的知识碎片走碎片既有逻辑,只是记录上下文是这次复习行为、并带「来自学习引导」系统标记。</p>
*/
@RequestMapping("/review/guidance")
@RestController
@Validated
@RequiredArgsConstructor
public class GuidanceController {
private final GuidanceService guidanceService;
private final AiTaskService aiTaskService;
/**
* 开启一次学习引导并提交第一个问题(AI 任务)。
*/
@PostMapping
@Operation(summary = "开启学习引导:返回引导编号与首个 AI 任务编号")
public CommonResult<Map<String, Object>> start(@RequestBody Map<String, String> body)
throws NotFindEntitiesException, ErrorParameterException {
String taskNum = body == null ? null : body.get("taskNum");
String concept = body == null ? null : body.get("concept");
ReviewGuidanceConversationEntity conversation = guidanceService.start(taskNum, concept);
Map<String, Object> result = new LinkedHashMap<>();
result.put("guidanceNum", conversation.getGuidanceNum());
result.put("taskNum", conversation.getTaskNum());
result.put("concept", conversation.getConcept());
result.put("aiTaskNum", submitTurn(conversation.getGuidanceNum()).getTaskNum());
return CommonResult.success(result);
}
/**
* 继续一轮:提交用户的回答/追问,返回本轮 AI 任务编号
*/
@PostMapping("/{guidanceNum}/turns")
public CommonResult<AiTaskResponse> continueTurn(@PathVariable String guidanceNum,
@RequestBody Map<String, String> body)
throws NotFindEntitiesException, ErrorParameterException {
guidanceService.appendUserTurn(guidanceNum, body == null ? null : body.get("message"));
return CommonResult.success(submitTurn(guidanceNum));
}
/**
* 读取这次引导的当前状态(含对话轮次),用于离开页面后回来继续
*/
@GetMapping("/{guidanceNum}")
public CommonResult<ReviewGuidanceConversationEntity> getConversation(@PathVariable String guidanceNum)
throws NotFindEntitiesException {
return CommonResult.success(guidanceService.getByGuidanceNum(guidanceNum));
}
/**
* 用户确认产出:把这次引导的收获记成一条知识碎片。
* <p>不确认就不产生任何数据。</p>
*/
@PostMapping("/{guidanceNum}/fragments")
public CommonResult<StudyReportFragmentsEntity> confirmFragment(@PathVariable String guidanceNum,
@RequestBody Map<String, Object> body)
throws ErrorParameterException, NotFindEntitiesException {
String content = body == null ? null : (String) body.get("content");
ReviewTiming timing = new ReviewTiming(
parseTime(body == null ? null : body.get("reviewStartedAt")),
parseTime(body == null ? null : body.get("reviewLastInteractionAt")),
body != null && body.get("reviewDurationSeconds") instanceof Number number
? number.intValue() : null);
return CommonResult.success(guidanceService.confirmFragment(guidanceNum, content, timing));
}
/**
* 放弃这次引导:不产出任何数据
*/
@DeleteMapping("/{guidanceNum}")
public CommonResult<Void> abandon(@PathVariable String guidanceNum) throws NotFindEntitiesException {
guidanceService.abandon(guidanceNum);
return CommonResult.success();
}
/** 提交一轮学习引导任务:targetNum 是引导编号,执行器会带上会话里的历史轮次 */
private AiTaskResponse submitTurn(String guidanceNum) throws ErrorParameterException, NotFindEntitiesException {
AiTaskSubmitRequest request = new AiTaskSubmitRequest();
request.setType("GUIDANCE");
request.setTargetNum(guidanceNum);
return aiTaskService.submit(request);
}
private static LocalDateTime parseTime(Object value) {
if (!(value instanceof String text) || text.isBlank()) {
return null;
}
try {
return LocalDateTime.parse(text.trim());
} catch (DateTimeParseException e) {
return null;
}
}
}
@@ -1,8 +1,10 @@
package com.guo.learningprogresstracker.controller;
import com.guo.learningprogresstracker.dto.LoginResult;
import com.guo.learningprogresstracker.entity.CommonResult;
import com.guo.learningprogresstracker.dto.request.LoginBody;
import com.guo.learningprogresstracker.exception.AppException;
import com.guo.learningprogresstracker.service.AiUsageService;
import com.guo.learningprogresstracker.service.LoginService;
import com.guo.learningprogresstracker.service.UserService;
import io.swagger.v3.oas.annotations.Operation;
@@ -20,14 +22,17 @@ public class LoginController {
private final LoginService loginService;
private final UserService userServiceImpl;
private final AiUsageService aiUsageService;
@Operation(summary = "登录API")
@PostMapping("/login")
public CommonResult<String> login(@RequestBody LoginBody loginBody) throws AppException {
public CommonResult<LoginResult> login(@RequestBody LoginBody loginBody) throws AppException {
String userId = userServiceImpl.authenticate(loginBody.getUsername(), loginBody.getPassword());
String token = loginService.login(userId);
// 用量面板的入口是否显示由服务端白名单决定,前端只读这个布尔值
boolean aiAdmin = aiUsageService.isAdmin();
//todo 参数传递未加密
return CommonResult.success("登录成功!", token);
return CommonResult.success("登录成功!", new LoginResult(token, aiAdmin));
}
@Operation(summary = "退出登录API")
@@ -0,0 +1,154 @@
package com.guo.learningprogresstracker.controller;
import com.guo.learningprogresstracker.dto.MarkerUsage;
import com.guo.learningprogresstracker.entity.CommonResult;
import com.guo.learningprogresstracker.entity.MarkerEntity;
import com.guo.learningprogresstracker.entity.UserTagEntity;
import com.guo.learningprogresstracker.enums.MarkerObjectTypeEnum;
import com.guo.learningprogresstracker.exception.ErrorParameterException;
import com.guo.learningprogresstracker.exception.NotFindEntitiesException;
import com.guo.learningprogresstracker.service.MarkerService;
import io.swagger.v3.oas.annotations.Operation;
import lombok.RequiredArgsConstructor;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;
import java.util.Collection;
import java.util.List;
import java.util.Map;
/**
* 统一标记控制层(标记-01)。
*
* <p>标记对用户全部可见;用户标签可增删改,系统标记只读。
* 检索只提供「单一标记筛选」,不做多标记组合——标签的唯一作用就是检索,而组合筛选目前没有真实场景。</p>
*/
@RequestMapping("/markers")
@RestController
@Validated
@RequiredArgsConstructor
public class MarkerController {
private final MarkerService markerService;
/**
* 列出某个对象上的全部标记(系统标记与用户标签一起返回,前端按 kind 区分展示)
*/
@GetMapping
public CommonResult<List<MarkerEntity>> listByObject(@RequestParam String objectType,
@RequestParam String objectNum) {
return CommonResult.success(markerService.listByObject(MarkerObjectTypeEnum.parse(objectType), objectNum));
}
/**
* 批量列出多个对象的标记(列表页一次取回一页,避免逐个请求)
*/
@PostMapping("/batch")
public CommonResult<Map<String, List<MarkerEntity>>> listByObjects(
@RequestParam String objectType,
@RequestBody Collection<String> objectNums) {
return CommonResult.success(
markerService.listByObjects(MarkerObjectTypeEnum.parse(objectType), objectNums));
}
/**
* 给对象打一个用户标签(幂等)
*/
@PostMapping
@Operation(summary = "打用户标签;系统标记只能由系统写入,不开放此接口")
public CommonResult<MarkerEntity> addUserTag(@RequestBody Map<String, String> body)
throws ErrorParameterException, NotFindEntitiesException {
String objectType = body == null ? null : body.get("objectType");
String objectNum = body == null ? null : body.get("objectNum");
String markerName = body == null ? null : body.get("markerName");
return CommonResult.success(
markerService.addUserTag(MarkerObjectTypeEnum.parse(objectType), objectNum, markerName));
}
/**
* 删除一个用户标签;系统标记不可删除
*/
@DeleteMapping("/{id}")
public CommonResult<Void> deleteMarker(@PathVariable Integer id)
throws ErrorParameterException, NotFindEntitiesException {
markerService.deleteMarker(id);
return CommonResult.success();
}
/**
* 重命名一个用户标签(影响所有带该标签的对象)
*/
@PutMapping("/rename")
public CommonResult<Integer> renameUserTag(@RequestBody Map<String, String> body)
throws ErrorParameterException {
String from = body == null ? null : body.get("oldName");
String to = body == null ? null : body.get("newName");
return CommonResult.success(markerService.renameUserTag(from, to));
}
/**
* 按标记筛选对象(点标签即筛选):返回带该标记的对象标识列表
*/
@GetMapping("/filter")
public CommonResult<List<String>> filterByMarker(@RequestParam String objectType,
@RequestParam String markerName,
@RequestParam(required = false) String markerValue,
@RequestParam(required = false) String kind) {
return CommonResult.success(markerService.findObjectNumsByMarker(
MarkerObjectTypeEnum.parse(objectType), markerName, markerValue, kind));
}
/**
* 当前用户用过的标签及使用情况(标签管理入口)
*/
@GetMapping("/tags")
public CommonResult<List<MarkerUsage>> listUserTagUsage() {
return CommonResult.success(markerService.listUserTagUsage());
}
/**
* 标签字典:打标签的候选标签(尚未挂在任何对象上的也算)
*/
@GetMapping("/tags/dictionary")
public CommonResult<List<UserTagEntity>> listDictionaryTags() {
return CommonResult.success(markerService.listDictionaryTags());
}
/**
* 往字典里新建一个(空)标签;同名(按去空格、大小写不敏感)已存在时幂等返回既有项
*/
@PostMapping("/tags/dictionary")
public CommonResult<UserTagEntity> createDictionaryTag(@RequestBody Map<String, String> body)
throws ErrorParameterException {
String tagName = body == null ? null : body.get("tagName");
return CommonResult.success(markerService.createDictionaryTag(tagName));
}
/**
* 字典标签改名:只影响候选,不改动任何对象上已经打好的标记
*/
@PutMapping("/tags/dictionary/{id}")
public CommonResult<UserTagEntity> renameDictionaryTag(@PathVariable Integer id,
@RequestBody Map<String, String> body)
throws ErrorParameterException, NotFindEntitiesException {
String newName = body == null ? null : body.get("newName");
return CommonResult.success(markerService.renameDictionaryTag(id, newName));
}
/**
* 删除字典标签:只影响候选,不改动任何对象上已经打好的标记
*/
@DeleteMapping("/tags/dictionary/{id}")
public CommonResult<Void> deleteDictionaryTag(@PathVariable Integer id) throws NotFindEntitiesException {
markerService.deleteDictionaryTag(id);
return CommonResult.success();
}
/**
* 打标签的候选/建议:字典标签 ∪ 已使用过的用户标签(含自动任务名标签),支持关键字过滤
*/
@GetMapping("/tags/candidates")
public CommonResult<List<String>> listTagCandidates(@RequestParam(required = false) String keyword) {
return CommonResult.success(markerService.listTagCandidates(keyword));
}
}
@@ -1,9 +1,14 @@
package com.guo.learningprogresstracker.controller;
import com.guo.learningprogresstracker.dto.ReviewFeedItem;
import com.guo.learningprogresstracker.dto.ReviewSortPreference;
import com.guo.learningprogresstracker.dto.ReviewSummary;
import com.guo.learningprogresstracker.dto.ReviewTaskStats;
import com.guo.learningprogresstracker.dto.request.RecallCompareRequest;
import com.guo.learningprogresstracker.dto.StudyReportDetail;
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.guo.learningprogresstracker.dto.request.UpdateStandardMindMapRequest;
import com.guo.learningprogresstracker.dto.request.ReviewFeedbackRequest;
import com.guo.learningprogresstracker.dto.request.UpdateStudyReportRequest;
import com.guo.learningprogresstracker.entity.CommonResult;
import com.guo.learningprogresstracker.entity.ReviewRecallRecordEntity;
import com.guo.learningprogresstracker.entity.ReviewStandardMindMapEntity;
@@ -35,7 +40,7 @@ public class ReviewController {
private final StandardMindMapService standardMindMapService;
/**
* 获取复习 feed,合并报告和残片按时间倒序
* 获取复习 feed,仅返回学习残片(首页滚动条使用)
*/
@GetMapping("/feed")
public CommonResult<List<ReviewFeedItem>> getReviewFeed(
@@ -45,11 +50,66 @@ public class ReviewController {
}
/**
* 获取任务维度的复习统计汇总
* 提交复习反馈动作(复习-02):标记或取消「已掌握」「稍后再看」。
* <p>只调整出现概率,不产生状态展示、不统计总数、不做待复习列表。</p>
*/
@PutMapping("/feed/{fragmentId}/feedback")
public CommonResult<ReviewFeedbackRequest> submitFeedback(
@PathVariable Integer fragmentId,
@RequestBody ReviewFeedbackRequest request) throws NotFindEntitiesException {
return CommonResult.success(reviewService.submitFeedback(fragmentId, request));
}
/**
* 记录一次「接触」(展开查看 / 进入回忆对比时调用):刷新最近接触时间,作为排序的第三个信号。
*/
@PostMapping("/feed/{fragmentId}/touched")
public CommonResult<Void> touchFragment(@PathVariable Integer fragmentId) throws NotFindEntitiesException {
reviewService.touchFragment(fragmentId);
return CommonResult.success();
}
/**
* 读取复习排序偏好(复习-01)
*/
@GetMapping("/sort-preference")
public CommonResult<ReviewSortPreference> getSortPreference() {
return CommonResult.success(reviewService.getSortPreference());
}
/**
* 保存复习排序偏好(复习-01):三档预设,不做精确权重。
*/
@PutMapping("/sort-preference")
public CommonResult<ReviewSortPreference> saveSortPreference(@RequestBody Map<String, String> body) {
String preset = body == null ? null : body.get("preset");
return CommonResult.success(reviewService.saveSortPreference(preset));
}
/**
* 复习总览的全局汇总(任务/报告/碎片总数)。
*
* <p>列表接口分页后,前端只能看到当前页;把每页相加会得到「本页合计」而不是总数,
* 因此汇总单独出接口,口径不受分页影响。</p>
*/
@GetMapping("/summary")
public CommonResult<ReviewSummary> summary() {
return CommonResult.success(reviewService.summary());
}
/**
* 分页获取任务维度的复习统计汇总。
*
* <p>分页不只为了排版:聚合(时长/报告数/碎片数)只算当前这一页的任务,
* 不再对全部任务做 IN 聚合。{@code markerName} 把「点标签即筛选」下推到服务端,
* 否则客户端只能筛当前页、total 也会不对。</p>
*/
@GetMapping("/tasks")
public CommonResult<List<ReviewTaskStats>> getReviewTaskStats() {
return CommonResult.success(reviewService.getReviewTaskStats());
public CommonResult<Page<ReviewTaskStats>> getReviewTaskStats(
@RequestParam(value = "pageNum", defaultValue = "1") Integer pageNum,
@RequestParam(value = "pageSize", defaultValue = "20") Integer pageSize,
@RequestParam(value = "markerName", required = false) String markerName) {
return CommonResult.success(reviewService.getReviewTaskStats(pageNum, pageSize, markerName));
}
/**
@@ -69,13 +129,42 @@ public class ReviewController {
}
/**
* 获取报告详情
* 获取报告详情(原始实体)
*/
@GetMapping("/report/{id}")
public CommonResult<StudyReportsEntity> getReportDetail(@PathVariable int id) throws NotFindEntitiesException {
return CommonResult.success(reviewService.getReportDetail(id));
}
/**
* 获取学习报告详情:三段文本 + 按当前内容归属实时聚合的碎片分组(归属-01)
*/
@GetMapping("/report/{id}/structured")
public CommonResult<StudyReportDetail> getReportDetailStructured(@PathVariable int id)
throws NotFindEntitiesException {
return CommonResult.success(reviewService.getReportDetailStructured(id));
}
/**
* 修改学习报告的三段文本
*/
@PutMapping("/report/{id}")
public CommonResult<Void> updateReport(@PathVariable int id,
@RequestBody UpdateStudyReportRequest request)
throws NotFindEntitiesException {
reviewService.updateReport(id, request);
return CommonResult.success();
}
/**
* 删除学习报告(软删除)。不连带删除知识碎片:碎片是独立原料,可能已归属到其他任务。
*/
@DeleteMapping("/report/{id}")
public CommonResult<Void> deleteReport(@PathVariable int id) throws NotFindEntitiesException {
reviewService.deleteReport(id);
return CommonResult.success();
}
/**
* 获取残片详情
*/
@@ -87,26 +176,15 @@ public class ReviewController {
// ============ 标准思维导图与回忆对比 ============
/**
* 获取或自动生成任务的标准思维导图
* 获取任务的标准思维导图。
*
* <p>读取不触发生成(AI-02):不存在时 data 为 null,由前端提交
* {@code POST /ai/tasks}(type=MIND_MAP)后轮询结果。</p>
*/
@GetMapping("/standard-mind-map/{taskNum}")
public CommonResult<ReviewStandardMindMapEntity> getStandardMindMap(
@PathVariable String taskNum) throws NotFindEntitiesException, OperationFailedException {
return CommonResult.success(standardMindMapService.getOrGenerate(taskNum));
}
/**
* 强制重新生成任务的标准思维导图
* @param mode 生成模式:full(全量覆盖,默认)或 incremental(增量合并)
*/
@PostMapping("/standard-mind-map/{taskNum}/regenerate")
public CommonResult<ReviewStandardMindMapEntity> regenerateStandardMindMap(
@PathVariable String taskNum,
@RequestParam(defaultValue = "full") String mode) throws NotFindEntitiesException, OperationFailedException {
if ("incremental".equals(mode)) {
return CommonResult.success(standardMindMapService.incrementalGenerate(taskNum));
}
return CommonResult.success(standardMindMapService.regenerate(taskNum));
@PathVariable String taskNum) throws NotFindEntitiesException {
return CommonResult.success(standardMindMapService.getExisting(taskNum));
}
/**
@@ -119,16 +197,6 @@ public class ReviewController {
return CommonResult.success(standardMindMapService.updateByOutline(taskNum, request.getOutline()));
}
/**
* 用户提交回忆大纲,与标准导图对比
*/
@PostMapping("/standard-mind-map/{taskNum}/recall")
public CommonResult<ReviewStandardMindMapEntity> recallCompare(
@PathVariable String taskNum,
@Valid @RequestBody RecallCompareRequest request) throws NotFindEntitiesException, OperationFailedException {
return CommonResult.success(standardMindMapService.recallCompare(taskNum, request.getRecallOutline(), request.getFocusPath()));
}
/**
* 在标准导图中查找与给定内容最匹配的节点
*/
@@ -1,6 +1,7 @@
package com.guo.learningprogresstracker.controller;
import com.google.protobuf.ServiceException;
import com.guo.learningprogresstracker.dto.request.AbortStudySessionRequest;
import com.guo.learningprogresstracker.dto.request.EndedStudySessionRequest;
import com.guo.learningprogresstracker.dto.request.UpsertExpectationRequest;
import com.guo.learningprogresstracker.dto.response.StudySessionResponse;
@@ -57,7 +58,7 @@ public class StudySessionController {
* 通过sessionNum获取一个【学习会话】
*/
@GetMapping("/{sessionNum}")
public CommonResult<StudySessionResponse> getStudySessionBySessionNum(@NotEmpty(message = "sessionNum不可为空") @PathVariable String sessionNum) throws ErrorParameterException {
public CommonResult<StudySessionResponse> getStudySessionBySessionNum(@NotEmpty(message = "请提供学习会话编号") @PathVariable String sessionNum) throws ErrorParameterException {
// 通过 service 层获取,包含归属校验
StudySessionResponse response = studySessionsServiceImpl.getStudySessionBySessionNum(sessionNum);
return CommonResult.success(response);
@@ -89,10 +90,22 @@ public class StudySessionController {
@PostMapping("/{sessionNum}/study-sessions/ended")
public CommonResult<Void> endedStudySession(@PathVariable("sessionNum") String sessionNum,
@Valid @RequestBody EndedStudySessionRequest request) throws ErrorParameterException {
String message = studySessionsServiceImpl.endedStudySession(sessionNum, request.getContent());
String message = studySessionsServiceImpl.endedStudySession(sessionNum,
new com.guo.learningprogresstracker.dto.ReportSections(
request.getSessionSummary(), request.getExpectationVerdict(), request.getFreeSummary()));
return message != null ? CommonResult.success(message) : CommonResult.success();
}
/**
* 误操作结束一个【学习会话】:需输入确认语,严格零数据(删除会话与预期),仅未产生学习残片时可用
*/
@PostMapping("/{sessionNum}/study-sessions/abort")
public CommonResult<Void> abortStudySession(@PathVariable("sessionNum") String sessionNum,
@Valid @RequestBody AbortStudySessionRequest request) throws ErrorParameterException {
studySessionsServiceImpl.abortStudySession(sessionNum, request.getConfirmation());
return CommonResult.success();
}
/**
* 获取【学习会话】所有的学习残片数据,以列表返回
*/
@@ -103,14 +116,6 @@ public class StudySessionController {
}
/**
* 生成学习报告草稿:AI 聚合残片(不可用时降级为拼接),返回给前端作为编辑起点
*/
@GetMapping("/{sessionNum}/report-draft")
public CommonResult<String> getReportDraft(@PathVariable("sessionNum") String sessionNum) throws ErrorParameterException {
return CommonResult.success("请求成功", studySessionsServiceImpl.generateReportDraft(sessionNum));
}
/** 分页查询任务的残片历史 */
@GetMapping("/tasks/{taskNum}/fragments")
public CommonResult<Page<StudyReportFragmentsEntity>> getTaskFragments(
@@ -0,0 +1,83 @@
package com.guo.learningprogresstracker.controller;
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.guo.learningprogresstracker.dto.TagMindMapSummary;
import com.guo.learningprogresstracker.dto.TagMindMapView;
import com.guo.learningprogresstracker.dto.TagScope;
import com.guo.learningprogresstracker.dto.request.TagScopeRequest;
import com.guo.learningprogresstracker.dto.request.UpdateTagMindMapRequest;
import com.guo.learningprogresstracker.entity.CommonResult;
import com.guo.learningprogresstracker.entity.ReviewRecallRecordEntity;
import com.guo.learningprogresstracker.entity.ReviewTagMindMapEntity;
import com.guo.learningprogresstracker.exception.ErrorParameterException;
import com.guo.learningprogresstracker.service.ReviewTagMindMapService;
import jakarta.validation.Valid;
import lombok.RequiredArgsConstructor;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;
import java.util.List;
/**
* 标签导图控制层(闭环-04)。
*
* <p>按标签复习与按任务复习并存:任务导图仍走 {@code /review/standard-mind-map/{taskNum}},
* 这里只负责以「标签集合 + 取数模式」为范围的那一半。</p>
*
* <p>生成与回忆对比都不在请求线程里等 AI:由前端提交 {@code POST /ai/tasks}
* (type=TAG_MIND_MAP / TAG_RECALL_COMPARE)后轮询结果,与既有 AI 任务链路同一约定。</p>
*/
@RequestMapping("/review/tag-mind-map")
@RestController
@Validated
@RequiredArgsConstructor
public class TagMindMapController {
private final ReviewTagMindMapService reviewTagMindMapService;
/**
* 读取该范围的状态:范围键、标签集合、已有导图与最近一次回忆对比。
*
* <p>读取不触发生成:没有导图时 {@code map} 为 null,由前端提交生成任务。
* 用请求体而不是查询参数,是因为标签名由用户自由输入、可能含逗号。</p>
*/
@PostMapping("/query")
public CommonResult<TagMindMapView> query(@Valid @RequestBody TagScopeRequest request)
throws ErrorParameterException {
TagScope scope = reviewTagMindMapService.resolveScope(request.getTags(), request.getMode());
return CommonResult.success(reviewTagMindMapService.query(scope));
}
/**
* 用户编辑标签导图(大纲文本形式);该范围还没有导图时保存即为新建。
*/
@PutMapping
public CommonResult<ReviewTagMindMapEntity> updateTagMindMap(
@Valid @RequestBody UpdateTagMindMapRequest request) throws ErrorParameterException {
TagScope scope = reviewTagMindMapService.resolveScope(request.getTags(), request.getMode());
return CommonResult.success(reviewTagMindMapService.updateByOutline(scope, request.getOutline()));
}
/**
* 分页列出已经生成过导图的标签范围:「按标签复习」的主入口。
*
* <p>用户先看到已有导图(标签集合 + 取数模式),可直接进入复习或把新碎片补充进去,
* 不必先选标签再判断这个范围有没有导图。读取不触发生成。</p>
*/
@GetMapping("/list")
public CommonResult<Page<TagMindMapSummary>> list(
@RequestParam(value = "pageNum", defaultValue = "1") Integer pageNum,
@RequestParam(value = "pageSize", defaultValue = "20") Integer pageSize) {
return CommonResult.success(reviewTagMindMapService.listMaps(pageNum, pageSize));
}
/**
* 该范围的回忆对比记录(倒序,最近一次在最前);范围里没有记录时返回空列表。
*/
@PostMapping("/recall-records")
public CommonResult<List<ReviewRecallRecordEntity>> listRecallRecords(
@Valid @RequestBody TagScopeRequest request) throws ErrorParameterException {
TagScope scope = reviewTagMindMapService.resolveScope(request.getTags(), request.getMode());
return CommonResult.success(reviewTagMindMapService.listRecallRecords(scope));
}
}
@@ -4,6 +4,7 @@ import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.google.protobuf.ServiceException;
import com.guo.learningprogresstracker.common.Ops;
import com.guo.learningprogresstracker.dto.TaskInfo;
import com.guo.learningprogresstracker.dto.TaskOption;
import com.guo.learningprogresstracker.dto.request.CreateTaskApplicationRequest;
import com.guo.learningprogresstracker.dto.response.StudySessionResponse;
import com.guo.learningprogresstracker.dto.response.TaskInfoResponse;
@@ -84,8 +85,15 @@ public class TaskController {
return CommonResult.success();
}
@GetMapping("/{taskId}/deletion-preview")
@Operation(summary = "删除任务前的影响范围:将删除什么、将保留什么(碎片进入待归类)")
public CommonResult<com.guo.learningprogresstracker.dto.TaskDeletionSummary> previewDeletion(
@PathVariable("taskId") String taskId) {
return CommonResult.success(tasksService.previewDeletion(taskId));
}
@DeleteMapping("/{taskId}")
@Operation(summary = "删除指定任务")
@Operation(summary = "删除指定任务(保留其知识碎片并进入待归类)")
public CommonResult<Void> deleteTask(@PathVariable("taskId") String taskId) throws ServerException {
tasksService.deleteTask(taskId);
return CommonResult.success();
@@ -121,6 +129,12 @@ public class TaskController {
return CommonResult.success();
}
@GetMapping("/options")
@Operation(summary = "全部任务的最小选项(归类下拉用)")
public CommonResult<List<TaskOption>> taskOptions() {
return CommonResult.success(tasksService.taskOptions());
}
@GetMapping
@Operation(summary = "获取所有任务列表")
public CommonResult<Page<TaskInfo>> tasksList(@RequestParam(value = "pageNum", defaultValue = "1") Integer pageNum,
@@ -132,7 +146,7 @@ public class TaskController {
* 开始或继续一个【学习会话】
*/
@GetMapping("/{taskNum}/study-sessions/start-or-continue")
public CommonResult<StudySessionResponse> startOrContinueStudySession(@NotEmpty(message = "taskNum不可为空")
public CommonResult<StudySessionResponse> startOrContinueStudySession(@NotEmpty(message = "请提供任务编号")
@PathVariable String taskNum) throws NotFindEntitiesException, ServiceException {
StudySessionResponse response = studySessionsServiceImpl.startOrContinueStudySession(taskNum);
return CommonResult.success(response);
@@ -143,7 +157,7 @@ public class TaskController {
* 通过学习任务num获取该任务的未结束会话
*/
@GetMapping("/{taskNum}/not-ended-study-session")
public CommonResult<StudySessionResponse> getNotEndedStudySessionByTaskNum(@NotEmpty(message = "taskNum不可为空")
public CommonResult<StudySessionResponse> getNotEndedStudySessionByTaskNum(@NotEmpty(message = "请提供任务编号")
@PathVariable String taskNum) throws ErrorParameterException {
StudySessionResponse response = studySessionsServiceImpl.getNotEndedStudySessionByTaskNum(taskNum);
return CommonResult.success(response);
@@ -1,37 +0,0 @@
package com.guo.learningprogresstracker.controller;
import com.guo.learningprogresstracker.entity.CommonResult;
import com.guo.learningprogresstracker.entity.TestTableEntity;
import com.guo.learningprogresstracker.exception.AppException;
import com.guo.learningprogresstracker.exception.ErrorParameterException;
import com.guo.learningprogresstracker.exception.NotFindEntitiesException;
import com.guo.learningprogresstracker.exception.OperationFailedException;
import com.guo.learningprogresstracker.service.TestTableService;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;
@RestController
@Slf4j
public class TestController {
@Autowired
TestTableService testTableService;
@GetMapping("/test/{id}")
public CommonResult<TestTableEntity> getTestEntityById(@PathVariable("id") String id) throws Exception {
log.info("testGet请求访问");
if ("1".equals(id)) {
throw new AppException("测试AppException");
} else if ("2".equals(id)) {
throw new ErrorParameterException("测试ErrorParameterException");
}else if ("3".equals(id)) {
throw new NotFindEntitiesException("测试NotFindEntitiesException");
}else if ("4".equals(id)) {
throw new OperationFailedException("测试OperationFailedException");
}
TestTableEntity testTableEntity = testTableService.getTestEntityById(id);
return CommonResult.success(testTableEntity);
}
}
@@ -12,9 +12,10 @@ import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;
import java.util.List;
import java.util.Map;
/**
* 学习残片控制层
* 知识碎片控制层(归属-01 起同时承载「内容归属」的调整动作)。
*/
@RequestMapping("/report-fragments")
@RestController
@@ -24,7 +25,7 @@ public class reportFragmentsController {
private final StudyReportFragmentsServiceImpl studyReportFragmentsServiceImpl;
/**
* 创建学习残片
* 创建知识碎片(记录上下文为当前学习会话,内容归属默认取该会话所属任务)
*/
@PostMapping
public CommonResult<Void> createFragments(@Valid @RequestBody CreateFragmentsRequest request) throws NotFindEntitiesException {
@@ -33,21 +34,49 @@ public class reportFragmentsController {
}
/**
* 更新学习残片
* 修改知识碎片正文与内容归属(记录上下文不可变)
*/
@PutMapping("/{id}")
public CommonResult<Void> updateFragments(@PathVariable Integer id,
@Valid @RequestBody UpdateFragmentsRequest request) throws NotFindEntitiesException {
@RequestBody UpdateFragmentsRequest request) throws NotFindEntitiesException {
studyReportFragmentsServiceImpl.updateFragments(id, request);
return CommonResult.success();
}
/**
* 获取指定会话的所有学习残片
* 调整内容归属;body 传 {"ownerTaskNum": "TASK-xxx"},传空字符串表示清空归属(回到待归类)
*/
@PutMapping("/{id}/ownership")
public CommonResult<Void> assignOwnership(@PathVariable Integer id,
@RequestBody Map<String, String> body) throws NotFindEntitiesException {
String ownerTaskNum = body == null ? null : body.get("ownerTaskNum");
studyReportFragmentsServiceImpl.assignOwnership(id, ownerTaskNum);
return CommonResult.success();
}
/**
* 删除知识碎片(软删除)
*/
@DeleteMapping("/{id}")
public CommonResult<Void> deleteFragment(@PathVariable Integer id) throws NotFindEntitiesException {
studyReportFragmentsServiceImpl.deleteFragment(id);
return CommonResult.success();
}
/**
* 获取指定会话产生的所有知识碎片(记录上下文为会话)
*/
@GetMapping("/session/{sessionNum}")
public CommonResult<List<StudyReportFragmentsEntity>> getFragmentsBySession(@PathVariable String sessionNum) {
List<StudyReportFragmentsEntity> fragments = studyReportFragmentsServiceImpl.getFragmentsBySession(sessionNum);
return CommonResult.success(fragments);
}
/**
* 待归类内容:还没有确定内容归属的碎片
*/
@GetMapping("/pending-ownership")
public CommonResult<List<StudyReportFragmentsEntity>> getPendingOwnershipFragments() {
return CommonResult.success(studyReportFragmentsServiceImpl.getPendingOwnershipFragments());
}
}
@@ -0,0 +1,54 @@
package com.guo.learningprogresstracker.dto;
import com.guo.learningprogresstracker.entity.AiTaskEntity;
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;
import java.time.LocalDateTime;
import java.util.Map;
/**
* AI 任务对外视图(AI-02)。
* <p>提交与查询都返回它:前端只依赖 {@code status} 与 {@code result},
* 不需要在请求线程里等 AI(也就不会出现「AI 成功了但客户端已超时」)。</p>
*/
@Data
public class AiTaskResponse {
@Schema(description = "AI 任务编号")
private String taskNum;
@Schema(description = "任务类型:RECALL_COMPARE / MIND_MAP / REPORT_DRAFT")
private String type;
@Schema(description = "目标编号:学习任务编号或学习会话编号")
private String targetNum;
@Schema(description = "状态:PENDING / RUNNING / SUCCEEDED / FAILED")
private String status;
@Schema(description = "失败原因(用户可见文案)")
private String errorMessage;
@Schema(description = "提交时间")
private LocalDateTime createdTime;
@Schema(description = "结束时间")
private LocalDateTime finishedTime;
@Schema(description = "成功结果,随任务类型不同;未完成时为 null")
private Map<String, Object> result;
public static AiTaskResponse from(AiTaskEntity entity, Map<String, Object> result) {
AiTaskResponse response = new AiTaskResponse();
response.setTaskNum(entity.getTaskNum());
response.setType(entity.getAiType());
response.setTargetNum(entity.getTargetNum());
response.setStatus(entity.getStatus());
response.setErrorMessage(entity.getErrorMessage());
response.setCreatedTime(entity.getCreatedTime());
response.setFinishedTime(entity.getFinishedTime());
response.setResult(result);
return response;
}
}
@@ -0,0 +1,35 @@
package com.guo.learningprogresstracker.dto;
import com.fasterxml.jackson.annotation.JsonInclude;
import lombok.Data;
/**
* DeepSeek 账户余额(契约 2.5,{@code GET /ai/usage/balance})。
*
* <p>由 lpt-be 代理 lpt-ai 的 {@code GET /admin/usage/balance};上游未配置或调用失败时只有
* {@code configured=false} 一个字段,因此这里用 {@code NON_NULL} 让其余字段直接不出现,
* 与契约给的响应体形状一致。</p>
*/
@Data
@JsonInclude(JsonInclude.Include.NON_NULL)
public class AiUsageBalance {
/** 上游是否可用:false 表示 lpt-ai 未配置 API Key 或本次查询失败 */
private boolean configured;
private String currency;
private String totalBalance;
private String grantedBalance;
private String toppedUpBalance;
/** 上游取数时间(ISO 8601 UTC) */
private String fetchedAt;
/** 上游不可用时的唯一响应:{@code {"configured": false}} */
public static AiUsageBalance notConfigured() {
return new AiUsageBalance();
}
}
@@ -0,0 +1,41 @@
package com.guo.learningprogresstracker.dto;
import lombok.Data;
import java.math.BigDecimal;
/**
* 用量按任务类型 / 模型 / 用户分组的一项(契约 2.4、v2 第 4.2 节,{@code GET /ai/usage/breakdown})。
*/
@Data
public class AiUsageBreakdownItem {
/**
* 分组键:{@code groupBy=taskType} 时是任务类型,{@code groupBy=model} 时是模型名,
* {@code groupBy=user} 时是用户 id(未归属的记录为 null)。
*/
private String key;
/**
* 展示名:{@code groupBy=user} 时是登录名(未归属为「未归属」,查不到登录名时回退为 {@code key}),
* 其它分组维度下等于 {@code key}——前端统一渲染 {@code label} 即可,不必按维度分支。
*/
private String label;
private Long calls;
private Long successCalls;
private Long failedCalls;
private Long promptTokens;
private Long completionTokens;
private Long cacheHitTokens;
private BigDecimal costUsd;
/** 平均调用耗时(毫秒);该分组无调用时为 null */
private Long avgDurationMs;
}
@@ -0,0 +1,32 @@
package com.guo.learningprogresstracker.dto;
import lombok.Data;
import java.math.BigDecimal;
/**
* 用量按任务类型 / 模型分组的聚合结果(Mapper 层直接映射,契约 2.4)。
*/
@Data
public class AiUsageBreakdownRow {
/** 分组键:{@code groupBy=taskType} 时是任务类型,{@code groupBy=model} 时是模型名 */
private String groupKey;
private Long calls;
private Long successCalls;
private Long failedCalls;
private Long promptTokens;
private Long completionTokens;
private Long cacheHitTokens;
private BigDecimal costUsd;
/** SQL 的 AVG 结果,由 service 取整后返回 */
private Double avgDurationMs;
}
@@ -0,0 +1,18 @@
package com.guo.learningprogresstracker.dto;
import lombok.AllArgsConstructor;
import lombok.Data;
/**
* 用量上报结果(契约 1):本次请求实际落库与因幂等跳过的条数。
*/
@Data
@AllArgsConstructor
public class AiUsageIngestResult {
/** 本次新落库的条数 */
private int accepted;
/** 因 {@code recordId} 已存在而跳过的条数 */
private int duplicated;
}
@@ -0,0 +1,18 @@
package com.guo.learningprogresstracker.dto;
import lombok.AllArgsConstructor;
import lombok.Data;
/**
* 当前用户能否查看「AI 用量统计」(契约 2.1,{@code GET /ai/usage/permission})。
*
* <p>非白名单也返回 HTTP 200 + {@code allowed=false},前端据此静默隐藏入口,
* 不需要为一个「看不见的按钮」处理报错。</p>
*/
@Data
@AllArgsConstructor
public class AiUsagePermission {
/** 用户名是否命中 {@code lpt.ai-usage.admin-usernames} */
private boolean allowed;
}
@@ -0,0 +1,27 @@
package com.guo.learningprogresstracker.dto;
import lombok.Data;
import java.math.BigDecimal;
/**
* 用量趋势的一个分桶(契约 2.3,{@code GET /ai/usage/series})。
*/
@Data
public class AiUsageSeriesPoint {
/** day:{@code yyyy-MM-dd};hour:{@code yyyy-MM-dd HH:00} */
private String bucket;
private Long calls;
private Long successCalls;
private Long failedCalls;
private Long promptTokens;
private Long completionTokens;
private BigDecimal costUsd;
}
@@ -0,0 +1,30 @@
package com.guo.learningprogresstracker.dto;
import lombok.Data;
import java.math.BigDecimal;
/**
* 用量趋势的分桶聚合结果(Mapper 层直接映射,契约 2.3)。
*
* <p>{@code bucket} 是计算列(按天/按小时格式化后的字符串),必须由显式
* {@code <resultMap>} 映射。</p>
*/
@Data
public class AiUsageSeriesRow {
/** day:{@code yyyy-MM-dd};hour:{@code yyyy-MM-dd HH:00} */
private String bucket;
private Long calls;
private Long successCalls;
private Long failedCalls;
private Long promptTokens;
private Long completionTokens;
private BigDecimal costUsd;
}
@@ -0,0 +1,47 @@
package com.guo.learningprogresstracker.dto;
import lombok.Data;
import java.math.BigDecimal;
/**
* AI 用量汇总(契约 2.2,{@code GET /ai/usage/summary})。
*
* <p>只统计真正消耗 LLM 的调用({@code is_llm_call = 1})。</p>
*/
@Data
public class AiUsageSummary {
private Long totalCalls;
private Long successCalls;
private Long failedCalls;
private Long promptTokens;
private Long completionTokens;
private Long totalTokens;
private Long cacheHitTokens;
private Long cacheMissTokens;
/** 缓存命中率 = 命中 /(命中 + 未命中);分母为 0 时为 null(不是 0,避免被读成「命中率为零」) */
private Double cacheHitRate;
private BigDecimal costUsd;
/** 按 {@code lpt.ai-usage.usd-to-cny} 换算的展示金额 */
private BigDecimal costCny;
/** 平均调用耗时(毫秒);无调用时为 null */
private Long avgDurationMs;
/** P95 调用耗时(毫秒,最近秩法);无调用时为 null */
private Long p95DurationMs;
/** 上游没上报 token 的调用数({@code prompt_tokens IS NULL}),面板据此显示「未上报」 */
private Long unreportedUsageCalls;
}
@@ -0,0 +1,39 @@
package com.guo.learningprogresstracker.dto;
import lombok.Data;
import java.math.BigDecimal;
/**
* 用量汇总的聚合结果(Mapper 层直接映射,契约 2.2)。
*
* <p>列名与属性不一致(别名、计算列),因此由 {@code AiUsageRecordMapper.xml} 的显式
* {@code <resultMap>} 承载映射,不依赖下划线转驼峰。</p>
*/
@Data
public class AiUsageSummaryRow {
private Long totalCalls;
private Long successCalls;
private Long failedCalls;
private Long promptTokens;
private Long completionTokens;
private Long totalTokens;
private Long cacheHitTokens;
private Long cacheMissTokens;
/** 未上报用量的调用数({@code prompt_tokens IS NULL}) */
private Long unreportedUsageCalls;
private BigDecimal costUsd;
/** SQL 的 AVG 结果,由 service 取整后返回 */
private Double avgDurationMs;
}
@@ -0,0 +1,29 @@
package com.guo.learningprogresstracker.dto;
import lombok.Data;
import java.time.LocalDate;
import java.time.LocalDateTime;
import java.util.ArrayList;
import java.util.List;
/**
* 一次导出的完整文档(导出-01)。Markdown 与 JSON 都由它渲染,保证两种格式内容一致。
*/
@Data
public class ExportDocument {
private LocalDateTime generatedTime;
/** TASK / RANGE / ALL */
private String scopeType;
/** 面向读者的范围描述 */
private String scopeLabel;
private LocalDate startDate;
private LocalDate endDate;
private List<ExportTaskSection> tasks = new ArrayList<>();
}
@@ -0,0 +1,22 @@
package com.guo.learningprogresstracker.dto;
import lombok.Data;
import java.time.LocalDateTime;
/**
* 导出的一条内容(学习报告或知识碎片,导出-01)。
*/
@Data
public class ExportEntry {
private Integer id;
/** 记录上下文:产生这条内容的学习会话编号 */
private String sessionNum;
private LocalDateTime createdTime;
/** 报告或碎片的原文 */
private String content;
}
@@ -0,0 +1,25 @@
package com.guo.learningprogresstracker.dto;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
/**
* 导出结果(导出-01)。
* <p>内容随统一响应体返回,由前端落成文件下载;这样既保持 {@code CommonResult} 的统一包装,
* 也不需要在服务端拼 Content-Disposition。</p>
*/
@Data
@NoArgsConstructor
@AllArgsConstructor
public class ExportResult {
/** 建议的文件名,含扩展名 */
private String fileName;
/** text/markdown; charset=UTF-8 或 application/json; charset=UTF-8 */
private String contentType;
/** 可独立阅读的导出正文 */
private String content;
}
@@ -0,0 +1,24 @@
package com.guo.learningprogresstracker.dto;
import lombok.Data;
import java.util.ArrayList;
import java.util.List;
/**
* 导出文档中的一个学习任务段落(导出-01)。
*/
@Data
public class ExportTaskSection {
private String taskNum;
private String taskName;
/** 任务维度统计:学习时长、复习耗时、报告/碎片数量等 */
private ReviewTaskStats stats;
private List<ExportEntry> reports = new ArrayList<>();
private List<ExportEntry> fragments = new ArrayList<>();
}
@@ -0,0 +1,19 @@
package com.guo.learningprogresstracker.dto;
import lombok.Data;
/**
* 一个碎片命中的标签数(闭环-04 标签导图取材)。
*
* <p>由 Mapper 层的分组查询直接映射:并集取「命中任意一个」的行,交集取「命中数 == 范围标签数」的行。
* 命中数按归一化标签名去重,所以重复打标不会让交集判定失真。</p>
*/
@Data
public class FragmentTagMatch {
/** 碎片 id(标记的 object_num) */
private String objectNum;
/** 命中的标签数(按归一化标签名去重) */
private Integer matchedTagCount;
}
@@ -0,0 +1,26 @@
package com.guo.learningprogresstracker.dto;
import lombok.Data;
/**
* 主键区间的聚合结果(复习-03)。
* <p>随机取样需要知道 id 的跨度,才能用「随机起点 + 顺序取窗口」替代 {@code ORDER BY RAND()}。
* 单列聚合可用 {@code selectObjs},这里需要 MIN 与 MAX 两列,因此用显式结果类 + 自定义 SQL。</p>
*/
@Data
public class IdRange {
private Integer minId;
private Integer maxId;
/** 区间内是否存在记录 */
public boolean isEmpty() {
return minId == null || maxId == null;
}
/** 区间宽度(含两端);空区间返回 0 */
public long span() {
return isEmpty() ? 0L : (long) maxId - minId + 1L;
}
}
@@ -0,0 +1,20 @@
package com.guo.learningprogresstracker.dto;
import lombok.AllArgsConstructor;
import lombok.Data;
/**
* 登录结果。
*
* <p>除 token 外额外下发 {@code aiAdmin}:前端据此决定是否显示「AI 用量统计」入口
* (契约 5,白名单口径在服务端,前端不自己判断)。</p>
*/
@Data
@AllArgsConstructor
public class LoginResult {
private String token;
/** 该用户是否在 {@code lpt.ai-usage.admin-usernames} 白名单里 */
private boolean aiAdmin;
}
@@ -0,0 +1,18 @@
package com.guo.learningprogresstracker.dto;
import lombok.Data;
/**
* 用户标签的使用情况(标记-01 的标签管理入口)。
*/
@Data
public class MarkerUsage {
private String markerName;
/** 该标签一共被打了多少次 */
private Long markerCount;
/** 该标签覆盖了多少个对象 */
private Long objectCount;
}
@@ -0,0 +1,10 @@
package com.guo.learningprogresstracker.dto;
/**
* 传给 lpt-ai 的一条碎片素材及其报告关联(报告-02)。
*
* <p>碎片正文之外带一个可空的 {@code reportRef}:指向同源的报告上下文。
* LLM 据此知道哪些碎片来自带报告的那次会话,从而只从中提取与这些碎片相关的内容。</p>
*/
public record MindMapFragmentPayload(String content, String reportRef) {
}
@@ -0,0 +1,36 @@
package com.guo.learningprogresstracker.dto;
import io.swagger.v3.oas.annotations.media.Schema;
/**
* 导图生成的报告参考上下文(报告-02)。
*
* <p>一次总结可能把若干碎片拼接出新的定义与观点,这些内容只存在于报告里、不在碎片里。
* 生成导图时,把碎片所在会话的报告一并带上作为 LLM 的参考,让它自行判断
* 「报告是否实质讨论了这些碎片的同一主题」:只有强相关才提取其内容,
* 只是简单提及或没提及则完全不用。</p>
*
* <p>{@code ref} 是报告所属会话编号,与碎片记录上下文的 {@code contextNum} 对应,
* 用于告诉 LLM 哪份报告与哪批碎片同源;{@code taskName} 帮助它判断领域是否一致。</p>
*/
public record MindMapReportContext(
@Schema(description = "报告所属会话编号,用于与碎片记录上下文关联")
String ref,
@Schema(description = "产生该报告的会话所属任务名(仅作判断领域的参考,报告可能来自旁支任务)")
String taskName,
@Schema(description = "会话摘要:这次实际学了什么")
String sessionSummary,
@Schema(description = "预期达成判断:对照学习预期得出的结论")
String expectationVerdict,
@Schema(description = "自由总结:用户对本次学习的叙述")
String freeSummary) {
/** 三段是否都为空白:全空的报告没有参考价值,不进入导图上下文 */
public boolean isBlank() {
return isBlank(sessionSummary) && isBlank(expectationVerdict) && isBlank(freeSummary);
}
private static boolean isBlank(String text) {
return text == null || text.isBlank();
}
}
@@ -0,0 +1,30 @@
package com.guo.learningprogresstracker.dto;
/**
* 一次回忆对比的结果(AI-02)。
*
* <p>对比在 AI 任务执行器里完成,因此不再把「标准导图实体」直接返回给提交接口;
* 这个结果写进 AI 任务的 {@code result_payload},由前端在轮询到成功后再取详情。</p>
*
* @param standardMapId 对比所用的标准导图 ID
* @param recallRecordId 本次生成的回忆记录 ID
* @param recallRatio 覆盖率(0-1)
* @param matchedCount 命中节点数
* @param missedCount 遗漏节点数
* @param extraCount 额外节点数
*/
public record RecallCompareOutcome(Integer standardMapId, Integer recallRecordId, Double recallRatio,
Integer matchedCount, Integer missedCount, Integer extraCount) {
/** 转成 AI 任务结果载荷 */
public java.util.Map<String, Object> toPayload() {
java.util.Map<String, Object> payload = new java.util.LinkedHashMap<>();
payload.put("standardMapId", standardMapId);
payload.put("recallRecordId", recallRecordId);
payload.put("recallRatio", recallRatio);
payload.put("matchedCount", matchedCount);
payload.put("missedCount", missedCount);
payload.put("extraCount", extraCount);
return payload;
}
}
@@ -0,0 +1,30 @@
package com.guo.learningprogresstracker.dto;
/**
* 学习报告的三段文本(归属-01 / 报告-01)。
*
* <p>报告的第四部分「按归属分组的碎片」不在此列:它是查看时按当前内容归属实时聚合的视图,不落库。</p>
*
* @param sessionSummary 会话摘要:这次实际学了什么
* @param expectationVerdict 预期达成判断:对照学习预期得出的结论
* @param freeSummary 自由总结:用户对本次学习的叙述
*/
public record ReportSections(String sessionSummary, String expectationVerdict, String freeSummary) {
/** 三段是否都为空 */
public boolean isEmpty() {
return isBlank(sessionSummary) && isBlank(expectationVerdict) && isBlank(freeSummary);
}
private static boolean isBlank(String text) {
return text == null || text.isBlank();
}
/** 报告落库时的兜底:至少保留一段,避免出现完全空的报告 */
public ReportSections orFallbackTo(String fallback) {
if (!isEmpty()) {
return this;
}
return new ReportSections(null, null, fallback);
}
}
@@ -5,15 +5,61 @@ import lombok.Data;
import java.time.LocalDateTime;
/**
* 复习滚动 feed 条目,合并展示学习报告和残片
* 复习滚动 feed 条目 / 任务记录条目。
*
* <p>归属-01 之后这里同时承载两个维度,不要混用:</p>
* <ul>
* <li>{@code taskNum} / {@code taskName} 是<b>内容归属</b>:碎片取它自己的归属任务,
* 报告取产生它的会话所属任务(报告按会话生成)。</li>
* <li>{@code contextType} / {@code contextNum} 是<b>记录上下文</b>:这条内容产生于哪次学习会话
* 或复习行为,用于界面按来源分组。</li>
* </ul>
*/
@Data
public class ReviewFeedItem {
private Integer id;
private String sessionNum;
/** REPORT | FRAGMENT */
private String sourceType;
/** 内容归属的任务编号;碎片待归类时为 null */
private String taskNum;
private String taskName;
private String sourceType; // REPORT | FRAGMENT
/**
* 内容摘要(复习-05):Feed 只回摘要,全文由详情接口按需拉取。
* <p>列表只用来触发回忆,全文既拖慢滚动也会让用户跳过「先尝试回忆」这一步。</p>
*/
private String content;
/** 原文总长度(字符数),供界面标注「全文 N 字」 */
private int contentLength;
/** 是否为截断后的摘要 */
private boolean contentTruncated;
private LocalDateTime createdTime;
/** 仅碎片有意义:内容归属为空,等待归类 */
private boolean pendingOwnership;
/** 记录上下文类型:SESSION | REVIEW */
private String contextType;
/** 记录上下文编号:学习会话编号或复习行为编号 */
private String contextNum;
/**
* 反馈与接触时间只参与排序计算,<b>不用于列表展示</b>:
* 复习反馈刻意不产生状态展示,否则会把复习拖回清单模式(复习-02)。
*/
@com.fasterxml.jackson.annotation.JsonIgnore
private Boolean mastered;
@com.fasterxml.jackson.annotation.JsonIgnore
private Boolean revisit;
@com.fasterxml.jackson.annotation.JsonIgnore
private LocalDateTime lastReviewedTime;
}
@@ -0,0 +1,21 @@
package com.guo.learningprogresstracker.dto;
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
/**
* 复习排序偏好(复习-01):对外暴露档位与可选项,避免前端硬编码文案。
*/
@Data
@NoArgsConstructor
@AllArgsConstructor
public class ReviewSortPreference {
@Schema(description = "当前档位:TIME_FIRST / BALANCED / MASTERY_FIRST")
private String preset;
@Schema(description = "档位的中文说明")
private String description;
}
@@ -0,0 +1,23 @@
package com.guo.learningprogresstracker.dto;
import io.swagger.v3.oas.annotations.media.Schema;
/**
* 复习总览的全局汇总。
*
* <p>刻意单独出接口:任务列表已分页,客户端只能看到当前页,
* 再把每页的报告数/碎片数相加会得到一个「看起来是总数、其实是本页合计」的错数字。</p>
*
* <p>口径与 {@code /review/tasks} 的列表完全一致(列表逐页相加 == 这里的汇总):
* 报告按「报告 → 会话 → 任务」归属,碎片按内容归属({@code owner_task_num})统计。
* 因此待归类碎片不计入 {@code fragmentTotal}(由总览的「待归类内容」独立区块展示),
* 任务删除后残留的报告也不计入。</p>
*/
public record ReviewSummary(
@Schema(description = "任务总数")
long taskTotal,
@Schema(description = "学习报告总数")
long reportTotal,
@Schema(description = "学习碎片总数")
long fragmentTotal) {
}
@@ -17,4 +17,6 @@ public class ReviewTaskStats {
private double weekEffectiveTime;
private double avgEffectiveTime;
private double avgEffectivenessRatio;
/** 该任务累计复习耗时(秒):来自回忆对比等复习行为,与学习时长独立统计 */
private long reviewDurationSeconds;
}
@@ -0,0 +1,15 @@
package com.guo.learningprogresstracker.dto;
import java.time.LocalDateTime;
/**
* 一次复习行为的计时信息(复习-07)。
* <p>由前端上报:复习行为开始时刻、最近一次交互时刻、以及按 5 分钟空闲截断后的净耗时。
* 三个字段都可空;服务端会用 {@code utils.ReviewDurationTool} 统一结算并落库。</p>
*
* @param startedAt 行为开始时刻
* @param lastInteractionAt 最近一次交互时刻
* @param durationSeconds 前端结算出的净耗时(秒)
*/
public record ReviewTiming(LocalDateTime startedAt, LocalDateTime lastInteractionAt, Integer durationSeconds) {
}
@@ -0,0 +1,81 @@
package com.guo.learningprogresstracker.dto;
import com.guo.learningprogresstracker.entity.StudyReportFragmentsEntity;
import com.guo.learningprogresstracker.entity.StudyReportsEntity;
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;
import java.util.ArrayList;
import java.util.List;
/**
* 学习报告详情(归属-01:结构化报告)。
*
* <p>报告由四部分组成,其中前三部分是落库的文本,第四部分是<b>实时聚合</b>出来的视图:</p>
* <ol>
* <li>会话摘要</li>
* <li>预期达成判断</li>
* <li>按内容归属分组的碎片 —— 查看时按碎片的<b>当前</b>归属聚合,不落库。
* 这样它与标准导图的取材口径始终一致,不会出现「报告说属于甲、导图放在乙」。</li>
* <li>自由总结</li>
* </ol>
*/
@Data
public class StudyReportDetail {
private Integer id;
/** 产生这份报告的会话 */
private String sessionNum;
/** 产生这份报告的会话所属任务(报告按会话生成,这是「这次学习属于哪个任务」) */
private String sessionTaskNum;
private String sessionTaskName;
/** 会话对应的学习预期 */
private String sessionExpectation;
@Schema(description = "会话摘要:这次实际学了什么")
private String sessionSummary;
@Schema(description = "预期达成判断:对照学习预期得出的结论")
private String expectationVerdict;
@Schema(description = "自由总结:用户对本次学习的叙述")
private String freeSummary;
private java.time.LocalDateTime createdTime;
@Schema(description = "按当前内容归属分组的碎片")
private List<FragmentGroup> fragmentGroups = new ArrayList<>();
/**
* 一条碎片按内容归属分组的结果。
*/
@Data
public static class FragmentGroup {
/** 归属任务编号;null 表示待归类 */
private String taskNum;
private String taskName;
/** 是否「旁支」:归属不等于本次报告所属会话的任务 */
private boolean branch;
private List<StudyReportFragmentsEntity> fragments = new ArrayList<>();
}
public static StudyReportDetail of(StudyReportsEntity report) {
StudyReportDetail detail = new StudyReportDetail();
detail.setId(report.getId());
detail.setSessionNum(report.getSessionNum());
detail.setSessionSummary(report.getSessionSummary());
detail.setExpectationVerdict(report.getExpectationVerdict());
detail.setFreeSummary(report.getFreeSummary());
detail.setCreatedTime(report.getCreatedTime());
detail.setSessionExpectation(report.getSessionExpectation());
return detail;
}
}
@@ -50,4 +50,9 @@ public class StudySessionsDto {
* 学习会话的状态(进行中、暂停、已结束)
*/
private String sessionState;
/**
* 是否由服务端自动收敛(疑似忘记结束,会话-04)
*/
private Boolean autoConverged;
}
@@ -0,0 +1,46 @@
package com.guo.learningprogresstracker.dto;
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;
import java.time.LocalDateTime;
import java.util.List;
/**
* 已有标签导图的摘要(闭环-04):用于「已生成的标签导图」列表。
*
* <p>列表是「按标签复习」的主入口:用户先看到已经生成过导图的标签集合,
* 直接进入复习或把新碎片补充进去,不必先选标签再判断这个范围有没有导图。
* 导图生成后标签集合一般不再变化,因此列表只读地还原 {@code tags + mode},
* 前端可直接用它们发起复查或增量生成(与 {@code scopeKey} 一一对应)。</p>
*/
@Data
public class TagMindMapSummary {
@Schema(description = "标签导图 ID")
private Integer id;
@Schema(description = "范围键:标签集合与取数模式的稳定哈希,同时作为 AI 任务的 targetNum")
private String scopeKey;
@Schema(description = "范围的标签集合(展示用,按归一化名排序)")
private List<String> tags;
@Schema(description = "取数模式:UNION=并集 / INTERSECT=交集")
private String mode;
@Schema(description = "导图标题")
private String title;
@Schema(description = "生成来源:BUILTIN/AI/USER/USER_MERGE")
private String generator;
@Schema(description = "取材的碎片数量")
private Integer sourceFragmentCount;
@Schema(description = "素材变化后置 true:有新碎片待整理,重建由用户手动触发")
private Boolean needsUpdate;
@Schema(description = "导图生成时间")
private LocalDateTime generatedTime;
}
@@ -0,0 +1,34 @@
package com.guo.learningprogresstracker.dto;
import com.guo.learningprogresstracker.entity.ReviewRecallRecordEntity;
import com.guo.learningprogresstracker.entity.ReviewTagMindMapEntity;
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;
import java.util.List;
/**
* 一个标签复习范围的当前状态(闭环-04)。
*
* <p>范围键与标签集合总是返回(即使还没有导图),让前端能用同一组参数发起生成任务与回忆对比;
* {@code map} 为空表示该范围还没生成过导图——读取路径不触发生成,生成走
* {@code POST /ai/tasks}(type=TAG_MIND_MAP)异步完成。</p>
*/
@Data
public class TagMindMapView {
@Schema(description = "范围键:标签集合与取数模式的稳定哈希,同时作为 AI 任务的 targetNum")
private String scopeKey;
@Schema(description = "范围的标签集合(展示用,按归一化名排序)")
private List<String> tags;
@Schema(description = "取数模式:UNION=并集 / INTERSECT=交集")
private String mode;
@Schema(description = "该范围已有的标签导图;没有时为 null")
private ReviewTagMindMapEntity map;
@Schema(description = "该范围最近一次回忆对比记录;没复习过时为 null")
private ReviewRecallRecordEntity latestRecallRecord;
}
@@ -0,0 +1,19 @@
package com.guo.learningprogresstracker.dto;
import com.guo.learningprogresstracker.enums.TagCombineModeEnum;
import java.util.List;
/**
* 解析后的复习范围:标签集合 + 取数模式 + 规范键(闭环-04)。
*
* <p>{@code tags} 是展示用标签集合(按归一化名排序、保留输入原样),{@code normalizedTags} 是规范化标签集合,
* {@code scopeKey} 是两者的稳定哈希——集合相同且模式相同即同一张标签导图。</p>
*/
public record TagScope(String scopeKey, List<String> tags, List<String> normalizedTags, TagCombineModeEnum mode) {
/** 范围的展示名:标签以「、」连接,也是标签导图的根节点标题来源 */
public String displayName() {
return String.join("、", tags);
}
}
@@ -0,0 +1,16 @@
package com.guo.learningprogresstracker.dto;
import lombok.Data;
/**
* 任务维度的内容条数聚合结果(数据-02):学习报告或知识碎片的条数。
* <p>计数在 SQL 侧按内容归属(学习会话 → 任务)分组完成。</p>
*/
@Data
public class TaskContentCount {
private String taskNum;
/** 该任务下的报告数或碎片数 */
private Long contentCount;
}
@@ -0,0 +1,32 @@
package com.guo.learningprogresstracker.dto;
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;
/**
* 删除学习任务的影响范围(归属-01)。
*
* <p>删除确认弹窗必须分别列出「即将删除」与「即将保留」,避免用户以为删干净了:
* 知识碎片会保留下来并进入待归类。</p>
*/
@Data
public class TaskDeletionSummary {
@Schema(description = "将保留的知识碎片条数(内容归属置空,进入待归类)")
private int releasedFragments;
@Schema(description = "将软删除的学习会话数")
private int deletedSessions;
@Schema(description = "将软删除的学习报告数")
private int deletedReports;
@Schema(description = "将软删除的标准思维导图数")
private int deletedMindMaps;
@Schema(description = "将软删除的回忆记录数")
private int deletedRecallRecords;
@Schema(description = "将软删除的应用场景数")
private int deletedApplications;
}
@@ -0,0 +1,19 @@
package com.guo.learningprogresstracker.dto;
import io.swagger.v3.oas.annotations.media.Schema;
/**
* 任务的最小选项(任务编号 + 名称),供「归类到已有任务」这类下拉使用。
*
* <p>刻意不复用 {@code /review/tasks}:那条接口会做复习统计聚合(时长/报告数/碎片数),
* 且现在已按页返回;下拉需要的是全部任务的一个最小列表。也不复用分页的 {@code /tasks},
* 否则任务多起来下拉会悄悄只显示第一页。</p>
*
* <p>排序与任务列表一致(优先级倒序),保证下拉里的顺序稳定。</p>
*/
public record TaskOption(
@Schema(description = "任务编号")
String taskNum,
@Schema(description = "任务名称")
String taskName) {
}
@@ -0,0 +1,19 @@
package com.guo.learningprogresstracker.dto;
import lombok.Data;
/**
* 任务最近一次回忆对比的覆盖率(复习-04)。
*
* <p>原先按任务取「最近一条回忆记录」是把该任务的全部回忆记录(含体积较大的
* {@code compare_result} JSON)拉回内存再逐条取第一条。改为在 SQL 侧按任务分组取最新,
* 返回行数等于任务数,不随复习次数增长。</p>
*/
@Data
public class TaskRecallRatio {
private String taskNum;
/** 最近一次回忆对比的覆盖率(0-1);记录里为空时按 0 处理 */
private Double recallRatio;
}
@@ -0,0 +1,16 @@
package com.guo.learningprogresstracker.dto;
import lombok.Data;
/**
* 任务维度的复习耗时聚合结果(复习-07)。
* <p>由 Mapper 层的聚合查询直接映射,避免用 Map 承载查询结果。</p>
*/
@Data
public class TaskReviewDuration {
private String taskNum;
/** 该任务累计复习耗时(秒) */
private Long reviewDurationSeconds;
}
@@ -0,0 +1,28 @@
package com.guo.learningprogresstracker.dto;
import lombok.Data;
/**
* 任务维度的学习会话统计聚合结果(数据-02)。
* <p>由 Mapper 层的 {@code SUM/COUNT + GROUP BY} 直接映射,避免把全部会话行拉回内存再聚合。</p>
*/
@Data
public class TaskSessionStats {
private String taskNum;
/** 该任务的学习会话次数 */
private Long sessionCount;
/** 累计有效学习时间(秒) */
private Double effectiveTime;
/** 有效时间比之和,用于计算平均值(避免在 Java 侧再存一份分母之外的中间量) */
private Double effectivenessRatioSum;
/** 今日有效学习时间(秒),时间窗在 SQL 侧判断 */
private Double todayEffectiveTime;
/** 本周有效学习时间(秒),时间窗在 SQL 侧判断 */
private Double weekEffectiveTime;
}
@@ -0,0 +1,14 @@
package com.guo.learningprogresstracker.dto.request;
import jakarta.validation.constraints.NotBlank;
import lombok.Data;
/**
* 误操作结束学习会话的请求体
*/
@Data
public class AbortStudySessionRequest {
@NotBlank(message = "请填写确认语")
private String confirmation;
}
@@ -0,0 +1,43 @@
package com.guo.learningprogresstracker.dto.request;
import jakarta.validation.constraints.NotBlank;
import lombok.Data;
import java.util.Map;
/**
* 提交 AI 任务请求(AI-02)。
*/
@Data
public class AiTaskSubmitRequest {
@NotBlank(message = "请先指定要处理的类型")
private String type;
@NotBlank(message = "请先指定要处理的对象")
private String targetNum;
/** 类型相关的参数;无需参数时可为空 */
private Map<String, Object> params;
/** 阅读友好度:null 表示不关心 */
public String paramAsString(String key) {
Object value = params == null ? null : params.get(key);
return value == null ? null : String.valueOf(value);
}
public Integer paramAsInteger(String key) {
Object value = params == null ? null : params.get(key);
if (value instanceof Number number) {
return number.intValue();
}
if (value instanceof String text && !text.isBlank()) {
try {
return Integer.valueOf(text.trim());
} catch (NumberFormatException e) {
return null;
}
}
return null;
}
}
@@ -0,0 +1,31 @@
package com.guo.learningprogresstracker.dto.request;
import lombok.Data;
/**
* 用量查询条件(契约 2.2 / 2.3 / 2.4):summary、series、breakdown 共用同一组筛选参数。
*/
@Data
public class AiUsageQuery {
/** 起始时刻(epoch millis);为空表示最近 30 天 */
private Long from;
/** 结束时刻(epoch millis);为空表示「到此刻为止」 */
private Long to;
/** 任务类型,精确匹配;为空表示不限 */
private String taskType;
/** 模型名,精确匹配;为空表示不限 */
private String model;
/** 归属用户 id,精确匹配;为空表示不限 */
private String userId;
/** series 的分桶粒度:day / hour */
private String bucket = "day";
/** breakdown 的分组维度:taskType / model / user */
private String groupBy = "taskType";
}
@@ -0,0 +1,87 @@
package com.guo.learningprogresstracker.dto.request;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotNull;
import jakarta.validation.constraints.Size;
import lombok.Data;
import java.math.BigDecimal;
/**
* 一条 AI 用量记录(契约 1)。
*
* <p>token 类字段一律包装类型:{@code null} 表示上游未上报,{@code 0} 表示上游明确上报为 0,
* 两者语义不同,不得用 0 顶替 null。</p>
*/
@Data
public class AiUsageRecordRequest {
/** 幂等键,lpt-ai 生成 */
@NotBlank(message = "recordId 不能为空")
private String recordId;
/** 调用发生时间,ISO 8601 UTC,如 {@code 2026-10-10T09:38:23.543Z} */
@NotBlank(message = "occurredAt 不能为空")
private String occurredAt;
@NotBlank(message = "taskType 不能为空")
private String taskType;
private String taskId;
/**
* 归属标记(契约 v2 第 2 节):lpt-be 提交任务时带的用户 id,lpt-ai 原样透传,落库到
* {@code ai_usage_records.user_id}。
*
* <p>刻意不用 {@code @NotBlank}:历史数据、lpt-ai 独立调用、以及调用方没带标记时都是空值,
* 空值只表示「未归属」,不是错误——用 {@code @NotBlank} 会把这类上报整批打成 400。</p>
*/
@Size(max = 64, message = "callerRef 不能超过 64 个字符")
private String callerRef;
/**
* 模型名。
*
* <p>用 {@code @NotNull} 而不是 {@code @NotBlank}:{@code isLlmCall=false} 的记录
* (如 {@code /fetch-title})本来就没调用模型,契约里它的 model 就是空串。
* 用 {@code @NotBlank} 会让这一条把整批上报打成 400,而上报方会把 400 当成可重试错误,
* outbox 被永久堵死。</p>
*/
@NotNull(message = "model 不能为空")
private String model;
@NotNull(message = "attempts 不能为空")
private Integer attempts;
@NotNull(message = "isLlmCall 不能为空")
private Boolean isLlmCall;
@NotBlank(message = "usageSource 不能为空")
private String usageSource;
private Integer promptTokens;
private Integer completionTokens;
private Integer totalTokens;
private Integer cacheHitTokens;
private Integer cacheMissTokens;
private Integer reasoningTokens;
private BigDecimal costUsd;
private String pricingVersion;
private Boolean peak;
@NotNull(message = "durationMs 不能为空")
private Integer durationMs;
@NotNull(message = "status 不能为空")
private Integer status;
private String errorCode;
}
@@ -0,0 +1,19 @@
package com.guo.learningprogresstracker.dto.request;
import jakarta.validation.Valid;
import jakarta.validation.constraints.NotNull;
import lombok.Data;
import java.util.List;
/**
* lpt-ai 用量上报请求体(契约 1,{@code POST /internal/ai-usage/records})。
*/
@Data
public class AiUsageReportRequest {
/** 单次最多 200 条(见 {@code AiUsageInternalController.MAX_RECORDS_PER_REPORT}) */
@NotNull(message = "records 不能为空")
@Valid
private List<AiUsageRecordRequest> records;
}
@@ -9,13 +9,13 @@ import lombok.Data;
@Data
public class CreateFragmentsRequest {
/**
* 会话编号
* 记录上下文编号:产生这条碎片的学习会话编号(归属-01 起上下文由类型 + 编号共同描述)
*/
private String sessionNum;
private String contextNum;
/**
* 残片内容,学习内容的描述
*/
@NotBlank(message = "啊?无字天书?")
@NotBlank(message = "请填写学习内容")
private String content;
}
@@ -8,7 +8,7 @@ public class CreateTaskApplicationRequest {
private String taskNum;
@NotBlank(message = "应用项目标题不可为空")
@NotBlank(message = "请填写应用项目标题")
private String title;
private String description;
@@ -1,13 +1,22 @@
package com.guo.learningprogresstracker.dto.request;
import jakarta.validation.constraints.NotBlank;
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;
/**
* @author guo
* 结束学习会话时提交的学习报告(归属-01 起报告为结构化三段)。
*
* <p>三段都可为空,但至少要有一段;第四部分「按归属分组的碎片」是实时聚合的视图,不需要提交。</p>
*/
@Data
public class EndedStudySessionRequest {
@NotBlank(message = "啊?搞无字天书是吧?报告内容不可为空")
private String content;
@Schema(description = "会话摘要:这次实际学了什么")
private String sessionSummary;
@Schema(description = "预期达成判断:对照学习预期得出的结论")
private String expectationVerdict;
@Schema(description = "自由总结:用户对本次学习的叙述")
private String freeSummary;
}
@@ -1,17 +1,31 @@
package com.guo.learningprogresstracker.dto.request;
import com.fasterxml.jackson.annotation.JsonFormat;
import jakarta.validation.constraints.NotBlank;
import lombok.Data;
import java.time.LocalDateTime;
/**
* 用户回忆对比请求
*/
@Data
public class RecallCompareRequest {
@NotBlank(message = "回忆大纲不可为空")
@NotBlank(message = "请先填写回忆大纲")
private String recallOutline;
/** 复习起点节点路径(以 / 分隔),null 为任务维度 */
private String focusPath;
/** 本次回忆复习开始时刻(本地时间),复习-07 */
@JsonFormat(pattern = "yyyy-MM-dd'T'HH:mm:ss")
private LocalDateTime reviewStartedAt;
/** 最近一次交互时刻(本地时间),供服务端按 5 分钟空闲截断,复习-07 */
@JsonFormat(pattern = "yyyy-MM-dd'T'HH:mm:ss")
private LocalDateTime reviewLastInteractionAt;
/** 前端按 5 分钟空闲截断后的净耗时(秒),复习-07 */
private Integer reviewDurationSeconds;
}
@@ -0,0 +1,20 @@
package com.guo.learningprogresstracker.dto.request;
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;
/**
* 复习反馈动作(复习-02)。
*
* <p>两个动作都只调整内容的出现概率,不产生状态展示、不统计总数、不做待复习列表。
* 传 null 表示本次不改该动作。</p>
*/
@Data
public class ReviewFeedbackRequest {
@Schema(description = "标记/取消「已掌握」:降低出现概率但不归零")
private Boolean mastered;
@Schema(description = "标记/取消「稍后再看」:提高出现概率")
private Boolean revisit;
}
@@ -0,0 +1,22 @@
package com.guo.learningprogresstracker.dto.request;
import jakarta.validation.constraints.NotEmpty;
import lombok.Data;
import java.util.List;
/**
* 标签复习范围(闭环-04):标签集合 + 取数模式。
*
* <p>用于纯范围寻址的读接口(读取该范围的导图、读取该范围的回忆记录)。
* 字段名与 {@code /ai/tasks} 的 params 保持一致,前端两处可以直接复用。</p>
*/
@Data
public class TagScopeRequest {
@NotEmpty(message = "请先选择标签")
private List<String> tags;
/** 取数模式:UNION=并集(默认)/ INTERSECT=交集 */
private String mode;
}
@@ -15,16 +15,16 @@ import lombok.Data;
public class TaskRequest {
public interface Create{}
@Null(message = "创建时不可指定任务ID",groups = Ops.CreateG.class)
@NotNull(message = "更新时必须指定任务ID",groups = Ops.UpdateG.class)
@Null(message = "创建任务时不需要填写任务编号",groups = Ops.CreateG.class)
@NotNull(message = "缺少要更新的任务信息,请刷新后重试",groups = Ops.UpdateG.class)
private Integer id;
/**
* 学习任务的名称
*/
@NotEmpty(message = "必须指定非空的任务名称", groups = Ops.CreateG.class)
@NotEmpty(message = "请填写任务名称", groups = Ops.CreateG.class)
private String taskName;
@NotEmpty(message = "必须指定非空的任务描述", groups = Ops.CreateG.class)
@NotEmpty(message = "请填写任务描述", groups = Ops.CreateG.class)
private String taskDescription;
/**
@@ -35,41 +35,41 @@ public class TaskRequest {
/**
* 用户设置的任务紧急性
*/
@NotNull(message = "必须指定【任务紧急性】指标", groups = Ops.CreateG.class)
@Min(value = 0,message = "urgency参数值必须大于等于0")
@Max(value = 5,message = "urgency参数值必须小于等于5")
@NotNull(message = "请设置任务紧急性", groups = Ops.CreateG.class)
@Min(value = 0,message = "任务紧急性不能小于 0")
@Max(value = 5,message = "任务紧急性不能大于 5")
private Integer urgency;
/**
* 用户设置的任务重要性
*/
@NotNull(message = "必须指定【任务重要性】指标", groups = Ops.CreateG.class)
@Min(value = 0,message = "importance参数值必须大于等于0")
@Max(value = 5,message = "importance参数值必须小于等于5")
@NotNull(message = "请设置任务重要性", groups = Ops.CreateG.class)
@Min(value = 0,message = "任务重要性不能小于 0")
@Max(value = 5,message = "任务重要性不能大于 5")
private Integer importance;
/**
* 任务的内容难度
*/
@NotNull(message = "必须指定【内容难度】指标", groups = Ops.CreateG.class)
@Min(value = 0,message = "contentDifficulty参数值必须大于等于0")
@Max(value = 5,message = "contentDifficulty参数值必须小于等于5")
@NotNull(message = "请设置内容难度", groups = Ops.CreateG.class)
@Min(value = 0,message = "内容难度不能小于 0")
@Max(value = 5,message = "内容难度不能大于 5")
private Integer contentDifficulty;
/**
* 任务的未来价值
*/
@NotNull(message = "必须指定【未来价值】指标", groups = Ops.CreateG.class)
@Min(value = 0,message = "futureValue参数值必须大于等于0")
@Max(value = 5,message = "futureValue参数值必须小于等于5")
@NotNull(message = "请设置未来价值", groups = Ops.CreateG.class)
@Min(value = 0,message = "未来价值不能小于 0")
@Max(value = 5,message = "未来价值不能大于 5")
private Integer futureValue;
/**
* 用户对任务的主观优先级
*/
@NotNull(message = "必须指定【主观优先级】指标", groups = Ops.CreateG.class)
@Min(value = 0,message = "subjectivePriority参数值必须大于等于0")
@Max(value = 5,message = "subjectivePriority参数值必须小于等于5")
@NotNull(message = "请设置主观优先级", groups = Ops.CreateG.class)
@Min(value = 0,message = "主观优先级不能小于 0")
@Max(value = 5,message = "主观优先级不能大于 5")
private Integer subjectivePriority;
}
@@ -1,16 +1,20 @@
package com.guo.learningprogresstracker.dto.request;
import jakarta.validation.constraints.NotBlank;
import lombok.Data;
/**
* @author guo
* 修改知识碎片:只允许改正文与内容归属,记录上下文不可变。
*/
@Data
public class UpdateFragmentsRequest {
/**
* 残片内容,学习内容的描述
* 残片内容(学习内容的描述);为空表示本次不改正文
*/
@NotBlank(message = "啊?无字天书?")
private String content;
/**
* 内容归属的任务编号;不传表示本次不改归属。
* <p>若要清空归属(回到待归类),传空字符串。</p>
*/
private String ownerTaskNum;
}
@@ -9,6 +9,6 @@ import lombok.Data;
@Data
public class UpdateStandardMindMapRequest {
@NotBlank(message = "思维导图大纲不可为空")
@NotBlank(message = "请填写思维导图大纲")
private String outline;
}
@@ -0,0 +1,22 @@
package com.guo.learningprogresstracker.dto.request;
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;
/**
* 修改学习报告的三段文本(归属-01 / 报告-01)。
*
* <p>不传或传 null 表示本次不改该段;传空字符串表示清空该段。</p>
*/
@Data
public class UpdateStudyReportRequest {
@Schema(description = "会话摘要:这次实际学了什么")
private String sessionSummary;
@Schema(description = "预期达成判断:对照学习预期得出的结论")
private String expectationVerdict;
@Schema(description = "自由总结:用户对本次学习的叙述")
private String freeSummary;
}
@@ -0,0 +1,26 @@
package com.guo.learningprogresstracker.dto.request;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotEmpty;
import lombok.Data;
import java.util.List;
/**
* 用户编辑标签导图(大纲文本形式)请求(闭环-04)。
*
* <p>范围绕「标签集合 + 取数模式」寻址,因此请求里带的是范围本身而不是导图 id;
* 该范围还没有导图时,保存即为新建。</p>
*/
@Data
public class UpdateTagMindMapRequest {
@NotEmpty(message = "请先选择标签")
private List<String> tags;
/** 取数模式:UNION=并集(默认)/ INTERSECT=交集 */
private String mode;
@NotBlank(message = "请填写思维导图大纲")
private String outline;
}
@@ -6,7 +6,7 @@ import lombok.Data;
@Data
public class UpdateTaskApplicationRequest {
@NotBlank(message = "应用项目标题不可为空")
@NotBlank(message = "请填写应用项目标题")
private String title;
private String description;
@@ -9,6 +9,6 @@ import lombok.Data;
@Data
public class UpsertExpectationRequest {
@NotBlank(message = "学习预期不可为空")
@NotBlank(message = "请填写学习预期")
private String description;
}
@@ -54,4 +54,7 @@ public class StudySessionResponse {
@Schema(description = "系统提示")
private String systemMessage;
@Schema(description = "是否由服务端自动收敛(疑似忘记结束,会话-04)")
private Boolean autoConverged;
}
@@ -0,0 +1,79 @@
package com.guo.learningprogresstracker.entity;
import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableField;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import com.guo.learningprogresstracker.enums.AiTaskStatusEnum;
import com.guo.learningprogresstracker.utils.GenerateNumTool;
import lombok.Data;
import java.io.Serializable;
import java.time.LocalDateTime;
/**
* AI 异步任务(AI-02):提交后立即返回任务标识,结果由执行器回写、按标识重复获取。
*/
@TableName(value = "ai_tasks")
@Data
public class AiTaskEntity extends BaseEntity implements Serializable {
@TableId(value = "id", type = IdType.AUTO)
private Integer id;
/** 对外任务标识 */
@TableField(value = "task_num")
private String taskNum;
/** 任务类型,取值见 {@code AiTaskTypeEnum} */
@TableField(value = "ai_type")
private String aiType;
/** 目标编号:学习任务编号或学习会话编号 */
@TableField(value = "target_num")
private String targetNum;
/** 状态,取值见 {@code AiTaskStatusEnum} */
@TableField(value = "status")
private String status;
/** 提交时的请求参数 JSON */
@TableField(value = "request_payload")
private String requestPayload;
/** 成功结果 JSON */
@TableField(value = "result_payload")
private String resultPayload;
/** 失败原因(用户可见文案) */
@TableField(value = "error_message")
private String errorMessage;
@TableField(value = "started_time")
private LocalDateTime startedTime;
@TableField(value = "finished_time")
private LocalDateTime finishedTime;
@TableField(exist = false)
private static final long serialVersionUID = 1L;
public static AiTaskEntity initNewTask(String aiType, String targetNum, String requestPayload) {
AiTaskEntity task = new AiTaskEntity();
task.setTaskNum(GenerateNumTool.generateNum("AITASK"));
task.setAiType(aiType);
task.setTargetNum(targetNum);
task.setStatus(AiTaskStatusEnum.PENDING.name());
task.setRequestPayload(requestPayload);
return task;
}
public boolean isActive() {
return AiTaskStatusEnum.ACTIVE.contains(AiTaskStatusEnum.valueOf(status));
}
public boolean isFinished() {
return AiTaskStatusEnum.SUCCEEDED.name().equals(status)
|| AiTaskStatusEnum.FAILED.name().equals(status);
}
}
@@ -0,0 +1,120 @@
package com.guo.learningprogresstracker.entity;
import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableField;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import lombok.Data;
import java.io.Serializable;
import java.math.BigDecimal;
import java.time.LocalDateTime;
/**
* AI 用量记录:lpt-ai 每完成一次 AI 任务后上报一条,供「AI 用量统计」面板聚合。
*
* <p><b>系统级表</b>:已加入 {@code MybatisPlusConfig.EXCLUDE_TABLES},不做按 {@code created_by}
* 的租户过滤——用量是运维口径,面板展示的是全部调用,而不是当前用户自己触发的那几次。</p>
*
* <p>token 类字段一律用包装类型:{@code null} 表示上游没上报,{@code 0} 表示上游明确上报为 0,
* 两者语义不同,不得用 0 顶替 null(面板要能显示「未上报」的调用数)。</p>
*/
@TableName(value = "ai_usage_records")
@Data
public class AiUsageRecordEntity extends BaseEntity implements Serializable {
@TableId(value = "id", type = IdType.AUTO)
private Integer id;
/** 幂等键:lpt-ai 生成的 UUID,重复上报直接跳过 */
@TableField(value = "record_id")
private String recordId;
/** 调用发生时间(UTC) */
@TableField(value = "occurred_at")
private LocalDateTime occurredAt;
/** 任务类型:aggregate-report/generate-mind-map/compare-recall/guidance/fetch-title */
@TableField(value = "task_type")
private String taskType;
/** lpt-ai 任务 id */
@TableField(value = "task_id")
private String taskId;
/**
* 归属用户:取自上报的 {@code callerRef};null=未归属(历史数据/独立调用/调用方没传)。
*
* <p>只用于分组与筛选,<strong>不是</strong>租户列:本表已在 {@code MybatisPlusConfig.EXCLUDE_TABLES}
* 中,绝不能按它过滤,否则面板只能看到当前管理员自己触发的调用。</p>
*/
@TableField(value = "user_id")
private String userId;
/** 模型名,如 deepseek-flash */
@TableField(value = "model")
private String model;
/** 本次任务实际发起的 LLM 调用次数(含失败重试) */
@TableField(value = "attempts")
private Integer attempts;
/** 是否消耗 LLM;false 表示没调用(如 /fetch-title) */
@TableField(value = "is_llm_call")
private Boolean isLlmCall;
/** 用量来源:upstream=上游返回 / estimated=估算 / missing=上游未给 */
@TableField(value = "usage_source")
private String usageSource;
/** 输入 token;null=未上报 */
@TableField(value = "prompt_tokens")
private Integer promptTokens;
/** 输出 token;null=未上报 */
@TableField(value = "completion_tokens")
private Integer completionTokens;
/** 总 token;null=未上报 */
@TableField(value = "total_tokens")
private Integer totalTokens;
/** 命中缓存的输入 token;null=未上报 */
@TableField(value = "cache_hit_tokens")
private Integer cacheHitTokens;
/** 未命中缓存的输入 token;null=未上报 */
@TableField(value = "cache_miss_tokens")
private Integer cacheMissTokens;
/** 推理 token;null=未上报 */
@TableField(value = "reasoning_tokens")
private Integer reasoningTokens;
/** 本次费用(USD),上报时算好并冻结 */
@TableField(value = "cost_usd")
private BigDecimal costUsd;
/** 计价表版本 */
@TableField(value = "pricing_version")
private String pricingVersion;
/** 是否按峰时价计费 */
@TableField(value = "peak")
private Boolean peak;
/** 本次调用耗时(毫秒) */
@TableField(value = "duration_ms")
private Integer durationMs;
/** 调用结果:200 成功,其余失败 */
@TableField(value = "status")
private Integer status;
/** 失败分类,如 timeout/rate_limited/upstream_error */
@TableField(value = "error_code")
private String errorCode;
@TableField(exist = false)
private static final long serialVersionUID = 1L;
}
@@ -0,0 +1,50 @@
package com.guo.learningprogresstracker.entity;
import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableField;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import lombok.Data;
import java.io.Serializable;
/**
* 统一标记(标记-01):附加在对象上的一段轻量元信息。
*
* <p>标记不是状态,也不参与聚合口径:会话状态、报告可否修订、导图是否待更新这类流程判断
* 留在各自主体上;内容归属是唯一的结构归属,标记不能用来表达第二归属。</p>
*/
@TableName(value = "markers")
@Data
public class MarkerEntity extends BaseEntity implements Serializable {
@TableId(value = "id", type = IdType.AUTO)
private Integer id;
/** FRAGMENT | TASK,取值见 {@code MarkerObjectTypeEnum} */
@TableField(value = "object_type")
private String objectType;
/** 对象标识:碎片 id 或 任务编号 */
@TableField(value = "object_num")
private String objectNum;
/** SYSTEM | USER,取值见 {@code MarkerKindEnum} */
@TableField(value = "kind")
private String kind;
/** 标记名:系统标记来自固定词表;用户标签自由输入 */
@TableField(value = "marker_name")
private String markerName;
/** 标记值:系统标记成对使用;用户标签留空(标签名本身就是全部信息) */
@TableField(value = "marker_value")
private String markerValue;
@TableField(exist = false)
private static final long serialVersionUID = 1L;
public boolean isSystemMarker() {
return com.guo.learningprogresstracker.enums.MarkerKindEnum.SYSTEM.name().equals(kind);
}
}

Some files were not shown because too many files have changed in this diff Show More