diff --git a/.agents/notes/implemented/architecture/2026-05-27-tenant-line-row-isolation.md b/.agents/notes/implemented/architecture/2026-05-27-tenant-line-row-isolation.md new file mode 100644 index 0000000..b91ef2a --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-05-27-tenant-line-row-isolation.md @@ -0,0 +1,43 @@ +# Agent Note: 行级数据隔离由租户拦截器统一注入,业务代码不写 created_by + +Status: implemented + +## Problem + +多租户表全靠手写 `WHERE created_by = #{当前用户}`。漏一处就是一个越权读:查询单条记录时不带条件, +别人的任务、报告、残片就会被正主之外的请求读到,而且这类缺口在单模块测试里看不出来——测试用的都是同一个 +登录用户。逐个 mapper 补条件也不可行:新增查询随时会漏,评审也盯不住。 + +## Decision + +持久层统一挂 `TenantLineInnerInterceptor`(`MybatisPlusConfig`),在 SELECT / UPDATE / DELETE 上自动追加 +`WHERE created_by = #{当前用户}`,业务代码与 mapper XML 一律不写这个条件。 + +- 租户列固定为 `created_by`,取值优先 `TenantContext` 里显式声明的身份(后台线程:AI 任务、定时收敛), + 没有就走 `StpUtil.getLoginIdAsString()`。 +- 免过滤表白名单 `EXCLUDE_TABLES`:`user`、`flyway_schema_history`、`databasechangelog`、 + `databasechangeloglock`、`ai_usage_records`。加表进白名单等于放弃该表的隔离,必须附带「为什么这张表不是租户表」。 +- 拦截器注册顺序固定为「多租户 → 分页」。分页的 `count` 语句从当前已处理的 SQL 派生,顺序颠倒会让 `total` + 把其他用户的行也算进去——`records` 仍然正确,只有总数错,靠肉眼几乎发现不了。`MybatisPlusConfigTest` + 守住这个顺序。 + +## Alternatives considered + +- **每个 mapper 手写 `created_by` 条件** — 最直白,也不引入 SQL 改写。放弃的原因是覆盖面靠人记忆:所有查询 + (含以后新增的)都要记得加,漏一处就是一个静默的越权读,而这类错误不会让任何测试变红。 +- **Service 层统一用 AOP 在方法入口校验归属** — 能在业务语义上给出更清楚的报错。但它只管「已取出的记录」, + 集合查询(列表、分页、汇总)依然会在 SQL 层返回别人的行,等于把越权数据读进内存再挑出去。 + +## Consequences + +- **收益**:新增查询默认就是安全的,越权读从「写测试才能发现」变成「默认不存在」。归属校验也顺带免费: + 查不到别人的记录,自然返回空。 +- **代价与已知上限**:所有绕过 SQL 的路径都不受保护——手写 JDBC、直接执行的原生 SQL、跨表 join 里别名的列 + 需要人工确认;免过滤表白名单是一处集中的风险点,改它等于改安全边界。出现「某接口查不到数据但库里明明有」 + 时,先查是不是白名单或 `TenantContext` 没设置,而不是去业务代码里找条件。 + +## Verification + +- 配置与顺序:`lpt-be/src/main/java/com/guo/learningprogresstracker/config/MybatisPlusConfig.java`, + `MybatisPlusConfigTest` 断言「租户拦截器先于分页拦截器」。 +- 白名单:同一个类里的 `EXCLUDE_TABLES`,静默新增表项即改动安全边界。 diff --git a/.agents/notes/implemented/architecture/2026-10-10-ai-usage-accounting-rules.md b/.agents/notes/implemented/architecture/2026-10-10-ai-usage-accounting-rules.md new file mode 100644 index 0000000..9d059f2 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-10-10-ai-usage-accounting-rules.md @@ -0,0 +1,47 @@ +# Agent Note: AI 用量口径——null 不等于 0,计价在 lpt-ai 侧冻结 + +Status: implemented + +## Problem + +lpt-ai 的调用会把 token 用量报回 lpt-be,供白名单管理员看总量与费用。这里有三个容易写错、写错还不会报错的地方: + +1. 上游有时候根本不返回 `usage`。如果把「没上报」记成 0,用量面板会把一批**未知消耗**显示成「这几次调用没花钱」, + 账单与面板永远对不上,而且没人能发现差了。 +2. 价格会变。若聚合时按当期价目回算历史,改一次价历史账全部重写,月度对账失去意义。 +3. `ai_usage_records` 里还有 `/fetch-title` 这类不消耗 LLM 的记录,混进统计会把「调用次数」和「模型成本」搅在一起。 + +## Decision + +- **`null` 与 `0` 严格区分**:`prompt_tokens` / `completion_tokens` 等列为 `NULL` 表示上游未上报,`0` 表示上游 + 明确上报为 0。不得用 0 顶替 null。`unreported_usage_calls` 正是靠这个区分统计出来的。 +- **计价在 lpt-ai 侧冻结**:`cost_usd` 在任务结算时按当期价目算好随记录落库,lpt-be 只做聚合与汇率换算 + (`lpt.ai-usage.usd-to-cny`),改价不重写历史账。 +- **统计口径只看 `is_llm_call = 1`**:不消耗 LLM 的调用照常落库(用于调用量排查),但不进用量面板。 +- **`user_id` 只是分组维度,不是租户列**:本表在 `EXCLUDE_TABLES` 中,`user_id` 用于按用户分组与筛选; + 若改成租户过滤,管理员只能看到自己触发的调用,面板等于永远是空的。 +- **上报幂等交给出库方**:`POST /internal/ai-usage/records` 以 `record_id` 唯一索引去重,因此「推送成功但响应 + 丢失」的重复推送是安全的;失败重试由 lpt-ai 侧 outbox 负责,4xx 属确定性拒绝,丢弃该批并计数,不无限重试。 + +## Alternatives considered + +- **在 lpt-be 侧按当期价目聚合时现算成本** — 少存一列,改价立刻全局生效。放弃是因为它把历史账变成了易变量: + 一次调价会让过去几个月的报表同时变化,月初对账没有稳定基线,而账本该是只读的。 +- **把「未上报」压成 0,只留一个总数** — 面板实现最简单,表结构也少一列。放弃是因为它抹掉了「我们不知道花了多少」 + 这个事实:额度异常时无法区分「真的没用量」和「上游没给 usage」。 +- **让 lpt-be 反查 lpt-ai 面板取历史用量** — 不用落库,也不必设计上报协议。但面板只是最近若干条的环形缓冲, + 进程重启即丢,「长期账本」这个诉求直接落空。 + +## Consequences + +- **收益**:用量面板的数字可以对账——已知消耗、未知消耗、非 LLM 调用分得开;改价不动历史。 +- **代价与已知上限**:lpt-be 必须相信 lpt-ai 报来的 `cost_usd`,价目正确性完全取决于 lpt-ai 的 `admin/pricing.ts` + 与节假日表(每年需更新)。出现「面板金额与上游账单对不上」时,先核 lpt-ai 的价目与峰谷窗口,再怀疑聚合逻辑。 + +## Verification + +- 表结构与索引:`lpt-be/src/main/resources/db/migration/V20261010_4__add_ai_usage_records.sql`、 + `V20261010_5__add_user_id_to_ai_usage_records.sql`。 +- 口径与 null 处理:`src/main/resources/mapper/AiUsageRecordMapper.xml`(`is_llm_call = 1` 过滤、 + `unreported_usage_calls` 用 `CASE WHEN prompt_tokens IS NULL`),`AiUsageServiceImpl` 的聚合。 +- 白名单与令牌:`AiUsageProperties`、`WebMvcConfig` 对 `POST /internal/ai-usage/records` 的排除。 diff --git a/.agents/notes/implemented/architecture/2026-10-10-usage-attribution-callerref.md b/.agents/notes/implemented/architecture/2026-10-10-usage-attribution-callerref.md new file mode 100644 index 0000000..8e9c777 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-10-10-usage-attribution-callerref.md @@ -0,0 +1,50 @@ +# Agent Note: 用量归属 mark 跟着请求走,路由信息不进 params + +Status: implemented + +## Problem + +用量要能按用户切分,但 lpt-ai 不知道调用方是谁:它只收到一个 `POST /ai/tasks` 的请求体(`type` + `params`)。 +在 lpt-be 侧「提交后再写回归属」也不成立——lpt-ai 可能比 lpt-be 的写回更早结算,形成归属与账目赛跑。 + +## Decision + +归属标记由调用方带过来:`POST /ai/tasks` 接受**顶层**可选字段 `callerRef`(限 64 字符),lpt-be 的 +`AiServiceClient` 填当前用户 id,lpt-ai 原样透传,结算时写进用量记录,lpt-be 落到 `user_id`。 + +三条硬约束,改动时必须同时守住: + +1. **不放进 `params`** —— `params` 会喂给 prompt 模板,混进去等于把内部 id 塞进模型输入; +2. **不参与幂等键** —— 幂等键是 `type + params`,`callerRef` 进去会让同一份输入因调用方不同而重复调 LLM; +3. **不进 prompt** —— 它只是记账标记,不是上下文。 + +配套两条: + +- **取不到身份就不带**:`currentCallerRef()` 拿不到登录态时返回 null,请求体里整个键都不写,这笔用量记为「未归属」。 + 绝不能因为取不到用户让 AI 调用失败。 +- **复用已有任务沿用原 `callerRef`**:那次 LLM 调用只发生了一次,账算在原调用方头上;复用方没有产生新 token, + 也就不会有新的用量记录。 + +## Alternatives considered + +- **lpt-be 提交任务后写回归属,等结算时再查** — 不用改 AI 侧协议。但它依赖「写回早于结算」的时序假设, + 而任务是异步的,lpt-ai 完全可能先结算;一旦发生就是归属丢失或错挂,且没有信号提示。 +- **把 `callerRef` 塞进 `params` 顺带透传** — 不必新增顶层字段,实现最省事。放弃是因为 `params` 同时是 prompt + 模板输入和幂等键的组成部分,一个记账字段混进去会同时污染模型输入和去重语义。 +- **让 lpt-ai 反查 lpt-be 拿归属** — 归属只在一处定义。但那是服务间反向依赖,AI 服务要为此持有一个 lpt-be 的 + 查询凭据与失败降级路径,为一个记账字段引入的耦合远大于收益。 + +## Consequences + +- **收益**:归属在 LLM 调用之前就已确定,没有「上报先到、归属还没写回」的竞态;AI 服务不需要知道 lpt-be 的任何 + 用户概念,只透传一个不透明字符串。 +- **代价与已知上限**:归属完全依赖调用方老实带上,`callerRef` 是自由字符串——lpt-ai 不做校验也不该做校验, + 伪造与错填由 lpt-be 侧负责(它填的是 `StpUtil` 里取到的登录 id)。未归属记录必须作为单独一行存在, + 不能为了报表好看塞给某个用户。 + +## Verification + +- 调用方:`src/main/java/com/guo/learningprogresstracker/service/impl/AiServiceClient.java` 的 `currentCallerRef()` + 与请求体组装(顶层 `callerRef`),`AiServiceClientAttributionTest`。 +- 承接方:lpt-ai `src/routes/ai.ts` 与 `src/task-queue.ts` 的 `callerRef` 透传,报表侧 + `breakdown?groupBy=user`(未归属 `key` 为 null、`label` 为「未归属」)。 diff --git a/.agents/notes/implemented/architecture/2026-11-16-current-recall-storage.md b/.agents/notes/implemented/architecture/2026-11-16-current-recall-storage.md new file mode 100644 index 0000000..08dc5b6 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-11-16-current-recall-storage.md @@ -0,0 +1,56 @@ +# Agent Note: 自由回忆只保存当前导图与本次资料 + +Status: implemented + +## Problem + +自由回忆需要持续保存当前输入、提供本次资料,并允许下次接着最后的导图回忆。为每次自动保存维护内容历史,会把编辑、恢复、原文查看和 AI 请求都绑定到版本模型。业务只要求每次回忆的最终内容;不兼容的回忆数据允许一次性删除。 + +## Decision + +每次回忆的 `RecallDocument` 只保存当前 `detail.expression` 和单一 `reference` 来源集合。自动保存覆盖当前导图,不保存中间导图、表达历史、资料历史或对应的版本字段。不同回忆仍是独立记录,各自保留最后保存的导图;“只保留当前内容”不表示整个账号只能有一条回忆记录。 + +本次资料在创建回忆时取一次,来源不可访问时原地清除正文及依赖它的 AI 结果。下一次创建回忆重新取材。DTO 名称 `ReferenceSnapshot` 只表示本次唯一来源集合,不包含版本号、历史列表或切换入口;普通查询和保存不会生成另一份资料。 + +`writeToken` 是覆盖写入保护:成功写入替换当前随机令牌,不维护递增内容编号或旧令牌列表。草稿只保留最近一次写入的请求编号与摘要,响应丢失时允许同一请求重试。其他业务收据只保存标识和摘要,不保存历史正文。 + +创建回忆时,服务端按当前用户、规范化标签集合及并集/交集方式选择最近已结束记录。标签顺序、空格或大小写不构成不同范围,组合方式不同则范围不同。新回忆复制最后导图的文字、节点标识及结构,清空此前帮助标记;资料、提示请求和累计耗时从本次重新建立。没有可用记录时初始化空白根节点。未完成草稿通过恢复接口编辑。 + +资料目录由 `GET /review/recalls/{num}/references` 分页返回标题与摘要,正文由同一路径下的 `/sources/{sourceId}` 获取。详情只返回资料汇总,避免每次草稿上传都携带全量正文。资料接口不接受版本参数。 + +AI 执行期间可以暂存一份提交输入,以便重启接手和结果引用校验;终态成功写回后清除 `params_json`,不能据此建立可回看的编辑过程。成功结果保留提示/查漏内容及必要请求信息,不替换当前导图。已显示帮助或原文的事实单独保留,供 AI 区分资料与已知帮助;这些事实不带表达版本或中间导图。具体输出与重试规则归属[AI 协议决策](../../../../../lpt-ai/.agents/notes/implemented/architecture/2026-11-16-recall-strict-protocol.md)。 + +## 删除范围与同步升级 + +`V20261116_1__replace_recall_storage.sql` 删除 `review_recall_records`,重建自由回忆的当前记录、请求、收据与所有者锁表,清除 `RECALL_COMPARE`、`TAG_RECALL_COMPARE`、`RECALL_HINT` 和 `RECALL_CHECK` 的既存任务。迁移不回填不兼容的表达历史与资料历史,已执行的历史 Flyway 脚本保持不变。 + +任务标准导图 `review_standard_mind_maps` 与标签导图 `review_tag_mind_maps` 保留,`StartTask` 的生成和编辑能力保留。被移除的是依赖旧对比记录表的查询、写入、统计和浏览链路,不能重新从旧任务类型写入该表。 + +表达式与提示结果增加字段后,旧版 `document_json` 不做读取兼容:`V20261118_1__clear_incompatible_recall_data.sql` 清空既有回忆、回忆请求/收据与回忆 AI 任务;运行中遇到无法解析的残留行直接逻辑删除并返回 `STORED_DATA_INVALID`,不保留、不隐藏。旧格式 AI 结果读取失败时按“旧版本格式,请重新请求”展示,不再冒充核验失败。 + +前端、后端与 AI 服务需要在同一环境同步升级;内容协议没有旧形状兼容适配。技术协议标识、模型名和计价信息保留,它们不表示用户内容版本。 + +## 关联记录与归属 + +本篇维护当前内容存储、范围匹配、写入保护、临时 AI 输入和删除迁移。[前端工作区决策](../../../../../lpt-fe/.agents/notes/implemented/feature/2026-11-16-current-recall-workspace.md)维护入口与交互,[AI 协议决策](../../../../../lpt-ai/.agents/notes/implemented/architecture/2026-11-16-recall-strict-protocol.md)维护严格输出和调用预算。三篇部分相关,分别保留;[租户隔离](2026-05-27-tenant-line-row-isolation.md)和[计费规则](2026-10-10-ai-usage-accounting-rules.md)继续维护各自决定。 + +## Alternatives considered + +- 只隐藏编号和历史入口:可以复用已有异步绑定,改动面较小;但后端仍保存编辑过程,与只保留当前内容的业务要求冲突,因此删除整个内容版本模型。 +- 把不兼容回忆回填为当前结构:能保留个人历史;但需要维护旧格式转换与历史引用,业务已允许删除这些数据,因此使用一次性清理迁移。 +- 无写入保护地覆盖当前图:实现更短,也没有内容版本;但两个页面可能静默覆盖彼此输入,因此使用单个随机写入令牌与请求幂等控制。 + +## Consequences + +覆盖保存把正文存储限制在每次回忆的一份当前内容,写入保护继续防止多页面静默覆盖。代价是无法恢复某一步编辑,也不能在本次回忆里刷新或切换资料历史;写入令牌与幂等摘要只能解决请求冲突,不能提供内容回滚。 + +删除迁移会清除既存对比记录和不兼容的自由回忆记录。保留任务标准导图和标签导图不意味着保留依赖这些图的旧回忆对比记录。代码回退不能还原已删除内容,发布时需要明确接受这个数据结果。 + +若业务以后确实需要编辑回滚、回忆内更新资料或长期保留请求输入,必须重新评估存储与清理规则;不得以恢复编号字段或长期保留 `params_json` 的方式隐式引入历史。 + +## Verification + +- `ReviewRecallServiceIntegrationTest` 校验多次覆盖后先前正文不再落盘、同范围自动带入、范围差异、租户隔离、资料分页,以及 AI 终态清除临时输入。 +- `ReviewRecallControllerIntegrationTest` 校验无版本 DTO、原文读取与旧请求拒绝;`RecallAiResultValidatorTest` 校验引用是否确实来自本次输入。异步结果不能覆盖后续编辑由服务集成测试验证。 +- `RecallStorageMigrationTest` 验证重建存储并删除旧记录、保留任务标准导图和标签导图。迁移在 H2 的 MySQL 模式执行;`MigrationIndexKeyLengthTest` 额外复算 InnoDB 索引键长度,不能替代真实 MySQL 的 DDL 验证。 +- 使用 JDK 17 运行 `./mvnw clean test`。 diff --git a/.agents/notes/implemented/architecture/2026-11-16-recall-actual-duration.md b/.agents/notes/implemented/architecture/2026-11-16-recall-actual-duration.md new file mode 100644 index 0000000..4d3526b --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-11-16-recall-actual-duration.md @@ -0,0 +1,39 @@ +# Agent Note: 自由回忆记录实际用时与有效时间 + +Status: implemented + +## Problem + +自由回忆页需要同时显示“实际用时”和“有效时间”,并按在场段与有交互活动分别累计。记录原先只有 `activeDurationMs`(有效时间)一个累计值,页面既拿不到“服务端已确认 + 本段未上传”的实时总量,也没有实际用时可展示。 + +直接用 `createdAt → endedAt` 推实际用时实现最省,但草稿允许跨天恢复,会把离开的时间全部算进去。实际用时只用于单条回忆展示,不参与任务统计,没有必要像 `active_duration_ms` 那样为聚合新增数据库列。 + +## Decision + +回忆计时同时累计两个值,契约与页面口径详见[前端工作区决策](../../../../../lpt-fe/.agents/notes/implemented/feature/2026-11-16-recall-time-metrics-and-break.md): + +- `Timing` 增加 `segmentActualMs`,与 `segmentActiveMs` 一样是当前编辑段的累计值,单调递增。缺省时取 `segmentActiveMs` 与已确认实际用时的较大值,滚动发布中的旧前端仍可保存并保持单调。 +- `RecallDocument` 增加 `acceptedSegmentActualMs`,与 `acceptedSegmentMs` 一同在草稿/结束时累加;`resume` 把两者都归零,开启新编辑段。 +- `RecallDetail` / `RecallSummary` 增加可空 `actualDurationMs`。旧记录读不到该字段时为 `null`,不回填;旧草稿第一次携带实际用时后从 0 开始累计。 +- 服务端只校验 `0 <= segmentActiveMs <= segmentActualMs`,且两者都不超过本次编辑段墙钟(保留 5 秒容差)。闲置截断和休息冻结由客户端计时器决定,服务端不推断。 +- 实际用时只存在回忆文档 JSON 中,不新增 `actual_duration_ms` 列:它不参与 `sumTaskDuration` 聚合,列表与回看都从文档读取。以后确实需要聚合再加列。 +- 每次保存成功后,前端把本次上传的段值记为已确认基线,展示值 = 服务端累计 + 未确认增量;恢复草稿重置基线。 + +## Alternatives considered + +- **用 `createdAt → endedAt` 作为实际用时**:不需要改契约;但跨天草稿会把离开时间全算进去,显示几十小时,因此否掉。 +- **新增 `actual_duration_ms` 列**:查询与聚合更直接;但当前没有按实际用时聚合的需求,SQL 迁移和冗余同步的代价换不来收益,因此只存文档 JSON。 +- **客户端只上报增量**:服务端无需保存 accepted 值;但请求丢失重试、幂等重放和并发写入会让增量边界不可验证,因此沿用累计值 + 服务端 accepted 基线。 +- **完全由服务端按墙钟推算实际用时**:不需要客户端计时;但服务端不知道标签页隐藏、休息和闲置,会把整夜算进去,因此保留客户端段计时,服务端只做上限校验。 + +## Consequences + +实际用时的精度依赖前端时钟与闲置窗口,服务端只能拒绝超过编辑段墙钟的值,不能识别一段“5 分钟宽限”是否合理。换设备或清缓存不会丢失已上传的累计值,但未上传的当前段本来就不属于服务端记录。 + +旧记录没有 `actualDurationMs` 时,前端只显示有效时间,不显示错误的 0。服务端与前端需要同批发布;旧前端缺少 `segmentActualMs` 时按有效时间处理,旧记录不会被补算。 + +## Verification + +- `ReviewRecallServiceIntegrationTest#actualDurationAccumulatesAcrossSegmentsAndNeverDropsBelowActive` 校验跨段累加、恢复归零、旧载荷兼容、实际小于有效与实际超过墙钟被拒绝。 +- `ReviewRecallControllerIntegrationTest` 校验接口序列化与既有行为不回退。 +- 使用 JDK 17 运行 `./mvnw clean test`。 diff --git a/.agents/notes/implemented/architecture/2026-11-16-recall-hint-anchor-and-verification.md b/.agents/notes/implemented/architecture/2026-11-16-recall-hint-anchor-and-verification.md new file mode 100644 index 0000000..6e686cf --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-11-16-recall-hint-anchor-and-verification.md @@ -0,0 +1,38 @@ +# Agent Note: 自由回忆提示锚点、表达式配色与核验原因 + +Status: implemented + +## Problem + +提示结果缺少挂载位置:`HintNode.parentId` 只描述提示内部,前端只能挂到根节点。表达式也没有配色字段,用户改色无法持久化。同时 BE 对空提示、判定引文和精确偏移的规则比 AI 服务更严,正常结果可能被判为 `INVALID_AI_RESULT`;失败原因被压缩成一句泛化文案,用户不知道哪条规则没过。`claimPendingTasks()` 每次扫描都执行 RUNNING 回收,条件 UPDATE 在无匹配行时也产生大量日志。 + +## Decision + +- `HintItem` 增加 `anchorNodeId`。LEAF/TREE 必须引用本次提交表达式中的真实节点(根节点 id 也可);KEYWORD/QUESTION 必须为 null。LEAF 恰好 1 个节点;TREE 继续校验单根、无环、≤5 节点。 +- 表达式节点增加可选 `style {background, color}`,只接受两个 `#RRGGBB`。配色是展示信息:`RecallAiService.bounded` 在构造 AI 输入时剥掉 style,模型契约保持不变;`carryContent` 复制到新回忆时保留用户显式配色,但清空提示 provenance。 +- 核验范围此后收窄:结构、提示锚点、LEAF/TREE 形状先由 lpt-ai 校验,BE 侧只复核引文是否真的来自本次输入,见[校验归属决策](2026-11-18-recall-validation-ownership.md)。 +- 校验失败返回可核验的原因(结构与字段/分析判定/提示结构/查漏依据/表达依据/分析覆盖等)。`RecallAiFailure.fromException` 保留校验器/客户端的固定安全文案;`RecallAiService.fail` 使用它;`RecallAiClient.remoteFailure` 只从 AI 服务的固定阶段标记中提取原因,不读取供应商原文。 +- `claimPendingTasks()` 的回收最多每 60 秒执行一次;扫描仍为 3 秒,抢占与结果回写不变,只有真正回收任务时打日志。 + +## Alternatives considered + +- **继续挂根节点**:无需契约变更;但树/叶的结构关系无法落到用户导图,因此增加锚点。 +- **不持久化配色,只做来源默认色**:实现最小;但用户无法按自己的习惯整理视觉,因此增加 style 字段并剥离 AI 输入。 +- **把判定引文限制成只能本单位**:语义更整齐;但 AI 服务允许跨单位上下文,模型正常输出会被 BE 误杀,因此对齐为 EXCLUDED 必须有本单位引文。 +- **保留泛化错误**:实现简单;但用户无法定位规则,因此返回固定阶段原因。 +- **每次扫描都回收任务**:恢复最快;但正常运行时只会制造 SQL 噪声,因此 60 秒节流。 + +## Consequences + +锚点让叶/树能挂到用户已有结构下,但 AI 等待期间用户删除锚点时会回退根节点;前端需要显示这个回退。 +配色进入表达式文档,但没有新增数据库列;新格式记录未选色时按来源默认色或普通节点显示。上一版本保存的文档缺少新增 record 组件,按破坏性变更处理:迁移清空既有回忆,运行中遇到无法解析的残留行直接逻辑删除并返回 `STORED_DATA_INVALID`,不增加读取兼容分支。AI 输入剥离 style 后,模型无法感知用户配色,这是刻意的展示/语义分离。 +空提示和跨单位判定引文不再被误判为失败;真正不合规的结果仍失败,并返回具体类别。 +回收节流最多延迟约一分钟发现崩溃任务;这是可接受的恢复时间。 + +## Verification + +- `RecallAiResultValidatorTest` 现只覆盖引用一致性与结构错乱 fail-closed,结构类断言由 lpt-ai 的 `recall.test.ts` 承担(见[校验归属决策](2026-11-18-recall-validation-ownership.md))。 +- `ReviewRecallServiceIntegrationTest` 覆盖 style 合法/非法、实际用时与有效时间的既有累加不回退。 +- `AiTaskServiceImplTest#claimPendingTasks_reclaimsStuckRowsAtMostOncePerMinute` 覆盖回收节流。 +- `RecallAiClientTest` 保持错误分类与远程清理行为;`ReviewRecallControllerIntegrationTest` 覆盖接口序列化。 +- 使用 JDK 17 运行 `./mvnw clean test`。 diff --git a/.agents/notes/implemented/architecture/2026-11-18-recall-validation-ownership.md b/.agents/notes/implemented/architecture/2026-11-18-recall-validation-ownership.md new file mode 100644 index 0000000..095b8d5 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-11-18-recall-validation-ownership.md @@ -0,0 +1,40 @@ +# Agent Note: 记忆回忆链路的校验归属与严格解析收窄 + +Status: implemented + +## Problem + +回忆链路的 JSON 出入口原先用一份自建严格 ObjectMapper 覆盖了三个方向:前端请求、落盘的 `document_json`、lpt-ai 返回的 AI 结果。这份严格同时打开 `FAIL_ON_UNKNOWN_PROPERTIES` 与 `FAIL_ON_MISSING_CREATOR_PROPERTIES`,后者在 record 上对**每个构造器组件**生效(`PropertyValueBuffer._findMissing` 在 `isRequired()` 之后立即检查该 feature),因此可空组件也变成必填。 + +后果是一个正常主流程被整单拒绝:`ExpressionNode.style` 在契约里是可选的(前端类型 `style?: NodeStyle | null`,`fromRecallElixirNode` 只在用户显式选色时才写),而「用 AI 提示把节点挂到导图」产生的节点不带 `style`。只要导图里有一个未配色的非根节点,`PUT /review/recalls/{num}/draft` 与 `POST .../end` 都返回 `400 INVALID_INPUT`「这些内容没能读取」。这个问题只有前端真实请求会触发——Java 测试用 record 序列化生成 body,`style` 永远以 `null` 出现而不是缺席,因此全部单测是绿的。 + +进一步的审计发现:`RecallAiResultValidator` 把 lpt-ai 的 `normalizeRecallResult` 又重新实现了一遍(结构、条数上限、字段枚举、提示树形状、锚点存在性、分析状态归一、长度上限),而且两套规则已经分叉(限制说明 lpt-ai 上限 5 条、后端 12 条;exclusion 引文的后端判定比 AI 服务更严)。2026-11-16 那次「正常结果被判 `INVALID_AI_RESULT`」的事故正是分叉的直接代价。 + +## Decision + +校验按「谁产出、谁保证」划分,同一个规则不写两遍。 + +- **外部请求(HTTP body)**:`RecallJson.readInput` 只拒绝未知字段、标量强转与浮点转整,不再要求可选字段必须出现。必填语义由 `ReviewRecallService.validateExpression` / `timing` / `ReviewRecallStore.guard` 承担,它们能给出比 Jackson 更具体的理由。 +- **落盘读取(`document_json` / AI 结果回读)**:`RecallJson.readStored` 不做结构限制,形状由写入方保证;读不出来即视为数据损坏。`ReviewRecallStore.load` 与 `RecallPrivacyService.readable` 的 catch 从 `IllegalStateException` 扩到 `IllegalStateException | NullPointerException | ClassCastException`,继续维持「损坏即删行」而不静默隐藏——但仍不捕获任意的 `RuntimeException`,数据库与事务异常必须照常上抛,不能因为一次读失败就删掉用户数据。 +- **AI 结果**:结构、条数、枚举、提示树形状、锚点、分析覆盖全部归 lpt-ai 的 `normalizeRecallResult`。后端 `RecallAiResultValidator` 只保留一条不变量:模型声称的引文与表达依据,必须能在本次输入原文里按偏移逐字取回(含不切开代理对)。本服务是落库与展示的边界,这条线必须自己持有,不能靠上游自证。 +- **序列化配置不动**:`RecallJson.write` 同时产出幂等摘要(`receipt_key` / `payload_hash`),任何序列化 feature、Module 或字段顺序的变动都会让既有收据失配、把重试判成 `REQUEST_ID_CONFLICT`。因此本轮只调整反序列化侧,并在类注释里写明这条约束。 + +## Alternatives considered + +- **继续让后端做全套 AI 结果校验**:后端确实是落库边界,多一层防线看起来更保险;但两套规则已经分叉并误杀过正常结果,维护成本随每次协议调整翻倍,因此只保留引文一致性这条不可替代的复核,其余交给产出方。 +- **整体删掉 `RecallAiResultValidator`,完全信任 lpt-ai**:代码与测试最少,最符合「各服务自证」;但 lpt-ai 的回归或部署漂移会让伪造引文直接进库并展示给用户,而「引文确实来自本次资料」正是这套功能对用户的核心承诺,因此保留最小复核。 +- **在前端补 `style: null` 了事**:一行改动即可让当前页面不再 400;但契约里 `style` 本来就是可选的,旧版本地草稿(`recallCache` 里的 `pendingSave`)与任何第三方客户端仍会被打回,服务端「少一个 key 就拒」的陷阱也还在,因此改在接收侧。 +- **保留 `FAIL_ON_MISSING_CREATOR_PROPERTIES`,改用 `@JsonProperty(required = true)` 标注必填字段**:能精确表达必填;但实测 Jackson 2.15 下该 feature 仍会否决未被 `required` 标注的缺席组件(`required=false` 也不生效),要真正生效必须去掉这个 feature,因此等价于本方案,只是多一层注解。 + +## Consequences + +前端按 TS 类型省略可选字段不再被拒,`PUT /draft` 与 `/end` 对真实页面恢复可用;后端不再因为协议细微差异误杀 AI 结果,`INVALID_AI_RESULT` 现在只表示「引文不可回溯」这一种情况。 + +代价是:AI 结果的条数与枚举约束在后端不再有第二道检查,若 lpt-ai 的解析器回归,后端只能靠引文一致性挡掉一部分问题;`RecallAiResultValidatorTest` 的覆盖面相应收窄,原来的结构类断言改为引用 lpt-ai 的 `recall.test.ts`。存储侧的损坏判定从「序列化异常」扩到「形状类异常」,能覆盖字段缺失导致的 `NullPointerException` 与类型不符导致的 `ClassCastException`;数据库与事务异常仍会上抛,排查时从日志里的 `recallNum` 与「旧版本或不兼容文档已删除」入手区分两种情况。 + +## Verification + +- `ReviewRecallControllerIntegrationTest#draftAcceptsOmittedOptionalStyleAndRejectsMissingRequiredFields` 用**手写 JSON 字符串**(不经 Java 序列化)验证:子节点省略 `style` 返回 200;缺 `schemaVersion`、缺节点 `id`、缺 `provenance`、出现未知字段 `carryFrom` 仍返回 400 `INVALID_INPUT`。 +- `RecallAiResultValidatorTest` 保留伪造引文、未知 `unitId`、切开代理对、表达依据越界、提示引文伪造与结构错乱 fail-closed 的用例。 +- `ReviewRecallServiceIntegrationTest#legacyDocumentsAreDeletedInsteadOfSkippedAndNewRecallStartsEmpty` 改为写入非法 JSON 来构造损坏文档,继续验证「损坏即删除并返回 `STORED_DATA_INVALID`」。 +- 使用 JDK 17 运行 `./mvnw test`,全量 602 个用例通过。 diff --git a/.agents/notes/implemented/process/2026-11-08-branch-bound-deploy.md b/.agents/notes/implemented/process/2026-11-08-branch-bound-deploy.md new file mode 100644 index 0000000..e74e166 --- /dev/null +++ b/.agents/notes/implemented/process/2026-11-08-branch-bound-deploy.md @@ -0,0 +1,44 @@ +# Agent Note: 出包环境由分支绑定,不靠参数切换 + +Status: implemented + +## Problem + +同一份代码要出 dev 与 prod 两个包。如果只靠流水线参数(或本地配置)区分环境,那么「用 dev 的代码发到 +prod 的 namespace」只是一次手滑——而这类手滑的代价最大:库表迁移已经跑上去、前端已经指到生产后端, +回滚时数据形状已经不匹配。 + +## Decision + +一个分支对一个环境,绑定关系写进流水线第一步并**直接拒绝**不匹配的组合,而不是打印警告。 + +| 仓库 | dev 分支 | prod 分支 | 说明 | +|---|---|---|---| +| lpt-be / lpt-fe / lpt-ai | `dev` | `master` | `main`(lpt-ai)仅作历史冻结点,不再发版 | +| lpt-android | `dev` | `master` | 两个分支只差默认 API 地址,不参与 k8s 部署 | +| lpt-infra | `master` | `master` | 单分支,靠 `dev/` 与 `prod/` 目录区分清单 | + +- 触发方式固定为 `workflow_dispatch` + 选择 `environment`,流水线首步校验「分支 ↔ 环境」,不匹配即 `exit 1`。 +- 网关地址、registry 等推动参数全部来自流水线的环境分支开关;**禁止用 tag 触发部署**(tag 打出来就跟分支脱钩了)。 +- 跨仓库同环境同批发:`dev` 配 `dev`、`master` 配 `master`。lpt-ai 的结果字段与 lpt-be 的读取形状是硬耦合, + 跨环境出包会让旧版读取方**静默降级**,界面不报错。 + +## Alternatives considered + +- **单分支 + 部署参数区分环境** — 不必维护两条长期分支,也少了合并这一步。放弃是因为环境成了「一次运行里的一个 + 字符串」:谁都能选错,代码里哪一行是生产配置也无从判断,出事后连「线上跑的是哪份代码」都要翻流水线记录才能答。 +- **出包后打 tag,用 tag 决定环境** — 发布形态更接近常规 CI。但本项目的分支本身就是环境契约,再叠一层 tag 会让 + 两个事实源打架;且 tag 一旦从错误分支打出,校验分支就再也拦不住。 + +## Consequences + +- **收益**:环境错配从一个「可能发生的事故」变成一个「跑不起来的流水线」;线上代码与分支一一对应,可以直接回答。 +- **代价与已知上限**:每次上生产都要「`dev` 合并进 `master`」这一次显式动作,合并冲突要自己解;`dev` 上验证过的 + 东西与 `master` 上的形态之间隔了一次合并,必须同批升级关联仓库才不会错配。历史例外:lpt-ai 的 `main` 停在 + 冻结点 `7c751bf`,看见它在仓库列表里不代表还能发版。 + +## Verification + +- 规则位置:`lpt-be/.gitea/workflows/deploy.yml`、`lpt-fe/.gitea/workflows/deploy.yml`、 + `lpt-ai/.gitea/workflows/deploy.yml` 的 `Validate branch ↔ environment` 首步。 +- 清单分区:`lpt-infra/dev/` 与 `lpt-infra/prod/`。 diff --git a/roles/ai-integration.md b/.agents/roles/ai-integration.md similarity index 100% rename from roles/ai-integration.md rename to .agents/roles/ai-integration.md diff --git a/roles/api-response.md b/.agents/roles/api-response.md similarity index 100% rename from roles/api-response.md rename to .agents/roles/api-response.md diff --git a/roles/data-access.md b/.agents/roles/data-access.md similarity index 100% rename from roles/data-access.md rename to .agents/roles/data-access.md diff --git a/roles/database-migration.md b/.agents/roles/database-migration.md similarity index 100% rename from roles/database-migration.md rename to .agents/roles/database-migration.md diff --git a/roles/ownership-and-markers.md b/.agents/roles/ownership-and-markers.md similarity index 100% rename from roles/ownership-and-markers.md rename to .agents/roles/ownership-and-markers.md diff --git a/skills/comment-cleanup/SKILL.md b/.agents/skills/comment-cleanup/SKILL.md similarity index 100% rename from skills/comment-cleanup/SKILL.md rename to .agents/skills/comment-cleanup/SKILL.md diff --git a/skills/comment-cleanup/agents/openai.yaml b/.agents/skills/comment-cleanup/agents/openai.yaml similarity index 100% rename from skills/comment-cleanup/agents/openai.yaml rename to .agents/skills/comment-cleanup/agents/openai.yaml diff --git a/.rgignore b/.rgignore new file mode 100644 index 0000000..6bffdc1 --- /dev/null +++ b/.rgignore @@ -0,0 +1,2 @@ +# Frozen Agent Notes are historical snapshots, not current search authority. +/.agents/notes/archived/ diff --git a/AGENTS.md b/AGENTS.md index 2d2d05d..0289e26 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,13 +5,16 @@ ## 规则与技能位置 - 通用规则(跨仓库):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`) +- 命名:业务概念的英文名以 `lpt-docs/docs/concepts/README.md` 术语表为准,库表、实体、DTO 字段由它派生,不另起别名(规则见 meta `.agents/roles/business-terminology.md`)。 +- 本仓库专属规则:`.agents/roles/` + - `.agents/roles/database-migration.md`:数据库迁移(Flyway Migration) + - `.agents/roles/data-access.md`:编码规范 · 数据访问层 + - `.agents/roles/api-response.md`:响应规范、DTO 转换 + - `.agents/roles/ownership-and-markers.md`:内容归属与结构化报告(归属-01 / 报告-01)、标记(标记-01) + - `.agents/roles/ai-integration.md`:学习引导(复习-06)、AI 异步链路(AI-02) + - 跨服务校验归属:不写在本仓库,统一按 meta 仓库 `.agents/roles/service-boundaries-and-validation.md` + (结构由产出方保证、LLM 输出在调用模型的那侧校验、接收方只做映射) +- 本仓库专属技能:`.agents/skills/`(如 `comment-cleanup`);决策笔记:`.agents/notes/`(见下节「重要改动必须留笔记」) ## 技术栈