diff --git a/AGENTS.md b/AGENTS.md index 0d57298..fd40eb9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,10 +2,18 @@ > Java Spring Boot 后端,提供 REST API、数据库访问、认证鉴权。 -## Git 提交规范 +## 规则与技能位置 -- 提交信息必须简短且使用中文,不要使用英文长句。 -- 格式:`类型: 简述`,例如 `feat: 新增用户登录接口`、`fix: 修复多租户拦截器空指针`、`docs: 补充API文档`。 +- 通用规则(跨仓库):meta 仓库 `.agents/roles/`。本仓库的 Git 提交规范也由该处管理: + - 提交信息必须简短且使用中文,不要使用英文长句。 + - 格式:`类型: 简述`,例如 `feat: 新增用户登录接口`、`fix: 修复多租户拦截器空指针`、`docs: 补充API文档`。 +- 本仓库专属规则:`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`) ## 技术栈 @@ -63,53 +71,6 @@ lpt-be/src/main/java/com/guo/learningprogresstracker/ `users`, `tasks`, `study_sessions`, `study_reports`, `study_report_fragments`, `study_expectations`, `task_applications`, `review_standard_mind_maps`, `review_recall_records`, `user_priority_weights` -## 内容归属与结构化报告(归属-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`)。 - -## 学习引导(复习-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 期间不得占用数据库连接。 - ## 关键机制 - 多租户隔离:`TenantLineInnerInterceptor` 自动注入 `WHERE created_by = #{当前用户}`,排除 `user`/`flyway_schema_history` 表。 @@ -118,20 +79,25 @@ lpt-be/src/main/java/com/guo/learningprogresstracker/ - 响应格式:`CommonResult` 统一包装 `{ code, message, data }`。 - CORS:可配置,local profile 允许所有来源。 -## 响应规范 +### 行级数据隔离(多租户拦截器) -- 成功:`CommonResult.success(data)`,code=200。 -- 业务错误:`CommonResult.error(msg)`,code=400,HTTP 200。 -- 未登录:`GlobalExceptionHandler.handleNotLogin()`,HTTP 401 + code=401。 -- 参数校验失败:`MethodArgumentNotValidException`,code=400。 -- 用户可见错误文案必须口语化、可理解,避免“无法生成”“不存在”等技术化表述;技术细节写入日志。例如无学习报告时应提示“这个任务还没开始学习哦,学习后产生学习报告后再来吧”,而不是“没有学习报告,无法生成思维导图”。 +- **配置类:** `MybatisPlusConfig` 注册 `TenantLineInnerInterceptor` +- **租户字段:** `created_by`(每个业务表的创建人字段) +- **租户值来源:** `StpUtil.getLoginIdAsString()`(当前登录用户) +- **自动注入:** 所有 SELECT/UPDATE/DELETE 语句自动追加 `WHERE created_by = #{当前用户}` +- **归属校验:** 查询单条记录时拦截器自动校验 `created_by`,非本人数据直接返回空 +- **排除表:** `user`、`flyway_schema_history`、`databasechangelog`、`databasechangeloglock` -## DTO 转换 +### 自动填充(MetaObjectHandler) -- MapStruct 编译期生成 `*ConvertImpl.java`,同名属性自动映射。 -- 默认 `unmappedTargetPolicy = IGNORE`。 -- 自定义映射使用 `@Mapping(source, target)`。 -- 增删 DTO 字段后必须重新编译,否则生成代码不含新字段。 +- **created_by / updated_by:** 插入/更新时自动填充为当前登录用户 +- **created_time / updated_time:** 插入/更新时自动填充当前时间 + +### 认证鉴权(Sa-Token) + +- **会话管理:** 基于 `StpUtil` 的登录/登出/会话查询 +- **权限校验:** `@SaCheckPermission` 注解式权限控制 +- **未登录处理:** 全局异常处理器捕获 `NotLoginException` 返回 401 ## CORS @@ -180,73 +146,3 @@ mvn spring-boot:run # 启动(默认 profile: local) |------|------|------|------| | lpt-fe | `../lpt-fe/` | 5158 | Vue 3 前端,通过 `/api` 代理调用本服务 | | lpt-ai | `../lpt-ai/` | 5199 | AI 服务,本服务通过 HTTP 调用其异步任务接口 | - -## 项目规范 - -## 数据库迁移(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` - -## 框架机制 - -### 行级数据隔离(多租户拦截器) - -- **配置类:** `MybatisPlusConfig` 注册 `TenantLineInnerInterceptor` -- **租户字段:** `created_by`(每个业务表的创建人字段) -- **租户值来源:** `StpUtil.getLoginIdAsString()`(当前登录用户) -- **自动注入:** 所有 SELECT/UPDATE/DELETE 语句自动追加 `WHERE created_by = #{当前用户}` -- **归属校验:** 查询单条记录时拦截器自动校验 `created_by`,非本人数据直接返回空 -- **排除表:** `user`、`flyway_schema_history`、`databasechangelog`、`databasechangeloglock` - -### 自动填充(MetaObjectHandler) - -- **created_by / updated_by:** 插入/更新时自动填充为当前登录用户 -- **created_time / updated_time:** 插入/更新时自动填充当前时间 - -### 认证鉴权(Sa-Token) - -- **会话管理:** 基于 `StpUtil` 的登录/登出/会话查询 -- **权限校验:** `@SaCheckPermission` 注解式权限控制 -- **未登录处理:** 全局异常处理器捕获 `NotLoginException` 返回 401 - -## 编码规范 - -### 数据访问层 - -- **优先使用纯 MyBatis-Plus Java API**(`Wrappers.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` 里显式声明(已配置),不要依赖框架默认值;出现别名、计算列或列名与属性不一致时必须写显式 `` - - **自定义 SQL 不会被 `@TableLogic` 自动追加逻辑删除条件**,必须显式写 `deleted = 0`;租户条件 `created_by = ?` 仍由 `TenantLineInnerInterceptor` 自动追加 - - 上述两条不能只靠 mock 单测,需落库集成测试守住(参考 `ReviewDurationIntegrationTest`) - - 反向约束:`Wrapper` 能表达的查询不要为「类型安全」提前下沉为自定义 SQL;确实要下沉时,SQL 只留在 Mapper 层,不要在 service 里拼字符串 diff --git a/roles/ai-integration.md b/roles/ai-integration.md new file mode 100644 index 0000000..131e8f6 --- /dev/null +++ b/roles/ai-integration.md @@ -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 期间不得占用数据库连接。 diff --git a/roles/api-response.md b/roles/api-response.md new file mode 100644 index 0000000..aef3c8e --- /dev/null +++ b/roles/api-response.md @@ -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 字段后必须重新编译,否则生成代码不含新字段。 diff --git a/roles/data-access.md b/roles/data-access.md new file mode 100644 index 0000000..6b59aea --- /dev/null +++ b/roles/data-access.md @@ -0,0 +1,19 @@ +# 数据访问层编码规范 + +- **功能**:规定数据访问层的实现方式,避免手写 SQL 与字符串 key 取值带来的跨库隐患。 +- **何时用**:编写 Mapper 或查询逻辑、需要聚合或联表、评审数据访问代码时。 + +## 编码规范 + +### 数据访问层 + +- **优先使用纯 MyBatis-Plus Java API**(`Wrappers.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` 里显式声明(已配置),不要依赖框架默认值;出现别名、计算列或列名与属性不一致时必须写显式 `` + - **自定义 SQL 不会被 `@TableLogic` 自动追加逻辑删除条件**,必须显式写 `deleted = 0`;租户条件 `created_by = ?` 仍由 `TenantLineInnerInterceptor` 自动追加 + - 上述两条不能只靠 mock 单测,需落库集成测试守住(参考 `ReviewDurationIntegrationTest`) + - 反向约束:`Wrapper` 能表达的查询不要为「类型安全」提前下沉为自定义 SQL;确实要下沉时,SQL 只留在 Mapper 层,不要在 service 里拼字符串 diff --git a/roles/database-migration.md b/roles/database-migration.md new file mode 100644 index 0000000..e197f90 --- /dev/null +++ b/roles/database-migration.md @@ -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` diff --git a/roles/ownership-and-markers.md b/roles/ownership-and-markers.md new file mode 100644 index 0000000..fc73ef8 --- /dev/null +++ b/roles/ownership-and-markers.md @@ -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`)。