一条知识库项目描述怎么改：职责、实现、验证与边界
这是一份由作者 IT枫斗者填写的教学示范，使用当前 Java 知识库检索服务及合成文档。下文第一人称用于说明作者如何表达项目实现，不是读者的既有经历，也没有对应的企业客户、生产上线或业务收益。读者应按实际参与改写；下载、启动或阅读源码，不能直接变成“我独立实现了整套系统”。
修改前：技术名词很多，责任无法核对
负责企业级 AI 知识库架构，使用 Java、RAG、多租户和权限控制，提升检索准确率。
这句空泛描述取自既有项目经历样例的反例。问题在于：“负责”没有说明具体交付，“企业级”没有部署与运营证据，“提升准确率”没有题集、基线与判定规则。既有样例讲的是 Java 单文件实验；这里改用当前具有 HTTP、数据库与认证的知识库服务，重新核对事实，不挪用单文件实验的七个回放场景。
修改后：作者对当前教学实现的表达
在使用合成文档的 Java 21 / Spring Boot 知识库教学服务中，我负责服务端身份约束、文档版本管理与带引用检索的实现。
通过数据库会话取得租户和角色，检索仅使用当前未删除且当前身份可见的文档；更新、删除检查 expectedVersion，更新通过事务写入新版本并切换当前版本指针，响应返回文档 ID、版本和原文引用。
验证以本地 H2、演示身份和合成输入为条件；公开报告记录了默认 17 项测试通过，以及独立进程 23 次 HTTP 检查和重启验证，可据此核对跨租户、权限收紧、旧版本与删除场景。
默认回答来自本地词项匹配和原文摘录；可选 pgvector 的三维 fixture 验证不代表真实模型或线上语义质量，当前没有生产性能与业务收益结论。
这四句话是一条项目描述的完整展开稿，便于教学核对。实际简历可以压缩篇幅，但保留“个人做了什么、如何实现、在什么条件下验证、结论到哪里为止”。这里的测试数字引用已有公开报告，不表示读者执行过，也不表示本页另做了一轮测试。
逐句为什么这样改
| 句子 | 改写理由 | 对应的实现或证据 |
|---|---|---|
| 第一句：教学性质与负责范围 | 把合成项目的性质放在前面，用三个具体模块替代无法核对的“企业级架构”；实现主语仅适用于作者示范 | 源码包的 README.md；Auth.java、Knowledge.java、Api.java |
| 第二句：身份、状态与响应 | 描述请求怎样获得身份、选取文档、避免旧版本覆盖；“有权限”落实到服务端判断，引用落实到具体字段 | Auth.security；Knowledge.list、update、delete、search；API.md |
| 第三句：验证条件与结果 | 测试通过只说明对应输入与断言成立；写清 H2、本地身份和合成数据，避免让读者误解为线上验收 | 公开报告的 defaultMaven、httpSmoke；包内 verification/smoke.json 与 JUnit XML |
| 第四句：检索与质量边界 | 原文摘录不能写成模型生成；fixture 不能写成真实 embedding 质量评测，未测的收益不能补数字 | Knowledge.tokens/search；PgVectorIntegrationTest；报告的 profiles、docker |
默认检索会对问题与文档标题、正文提取词项，用“命中的问题词项数 / 问题词项数”评分，阈值为 0.6；中文连续文本通常取二元词项。answer 使用最高分证据的原文，citations 带文档 ID、当前版本、标题、完整正文与分数。这个比例衡量词项覆盖，不能据此说“答案正确率为 60%”。文档可能包含词项，却没有回答问题。
把一条描述落到可检查的场景
以 ApiIntegrationTest.permissionChangeCannotFallBackToPublicOldVersion 为入口：测试创建正文含 cobalt、访问级别为 READER 的文档，再用 expectedVersion=1 更新为 ADMIN 可见的当前版本；reader 查询 cobalt 应拒答，直接读取该文档应得到 404。公开报告记录该测试通过。其重点是当前版本不可见时，不能转而读取仍保存在历史表中的旧公开版本。
下面是按现有接口组合的复练步骤。表中是应核对的预期，不是替你生成的运行日志。用本机响应中的真实 ID 和版本执行，并保存自己的请求条件。
| 步骤 | 操作和身份 | 应检查什么 |
|---|---|---|
| 建立基线 | alpha 的 admin 创建 READER 文档，正文 cobalt public then private；reader 搜索 cobalt | 引用指向刚创建的文档与版本 1，quote 对应保存后的正文 |
| 收紧权限 | admin 更新为正文 cobalt private、minRole 为 ADMIN，携带 expectedVersion=1 | 返回版本 2；reader 搜索该词时不回退 v1，直接读取返回 404 |
| 区分权限与词项 | admin 搜索 cobalt，再用 beta 的 other 读取同一文档 | admin 可引用 v2；other 读取为 404，不能因角色是 ADMIN 就跨租户 |
| 检查冲突与删除 | admin 用 expectedVersion=1 删除，再用 2 删除 | 前者 409，后者 204；删除后 admin 再搜索应 refused=true 且 citations 为空 |
实现依据是 Knowledge.list 只连接 current_version 并排除墓碑，再检查角色。更新和删除先按租户锁定文档行，再核对预期版本；旧版本冲突返回 409。删除保留历史与墓碑，不提供历史内容回退接口，也不能声称物理擦除。独立进程 smoke 另有 oldmarker/newmarker 的更新、权限、重启和删除记录；它与上表组合练习不是同一份运行记录。
如何替换成自己实际参与的内容
先把职责写成三个栏位：“我改过的文件或测试”“我运行过的步骤”“我只读懂的部分”。每个实现动词对应提交或差异，每个运行结论对应自己的原始输出。以下是不同参与范围的填写示例，只有实际完成所述动作才能使用；不要为了保留作者的完整段落扩大职责。
只做过运行与阅读的表达示例：“在 Java 知识库教学项目中，按 API 完成登录、建文档、收紧访问级别与删除的本地复现，保存 reader 与 admin 的响应；结合 Knowledge.list/search 说明当前版本与角色过滤的关系。未修改后端实现，尚未验证向量模式。”它把贡献限定为复现和分析，前提是你真的保存了这些记录。
确实补充过测试后才能使用的表达示例：“基于公开教学项目，为已有的权限收紧测试补充 reader 检索引用列表必须为空的断言，保留测试差异及本机复跑输出；认证和版本管理沿用原实现。”原来的 permissionChangeCannotFallBackToPublicOldVersion 已检查拒答与读取 404，这个示例只把新增贡献限定为补充空引用断言。尚未修改时应写“拟补充”；仅运行原有测试，应写“复跑”，不能写“新增”。
实际修改过代码时的填写方法：指出原有行为、触发输入、本人改动位置和改后输出，再注明没有改动的模块。当前仓库已经有版本与权限检查，不能杜撰“原系统存在泄露、由我修复”的故事。没有可定位的差异时，保留复现表述。项目性质仍应是基于公开源码的个人实践，不填写虚构公司、客户或上线时间。
面试追问：至少能回答到这些位置
- 租户是谁决定的？ Bearer token 经数据库会话关联用户，每个请求重新取得租户与角色；文档
minRole是访问级别，不能当作调用者角色。请求体不能注入自己的 tenant。 - 为何不能检索所有历史版本再按权限挑一条？ 新版本收紧权限或删除后，旧公开版本仍可能命中词项。当前实现先确定当前状态，再允许检索；可以打开上面的测试说明风险。
- expectedVersion 是否证明处理了所有并发问题？ 它配合行锁和事务处理当前文档的旧版本写入冲突；已有测试检查陈旧版本得到 409，不能据此宣布完整分布式并发正确性。
- pgvector 通过能否说明同义问法也正确？ 不能。公开报告中的 fixture 按固定规则生成三维向量，检查真实存储、过滤和旧候选处理；真实模型 API 与语义题集没有测试。
- 有什么还没做到？ 默认每份正文是一个检索单元，未分块；词项覆盖可能误命中或漏召回。没有生产负载、客户效果或求职结果数据，后续改进要另建评测后再写结论。
来源与完成自查
源码来自已验证源码包：解压后的 knowledge-service/README.md、API.md、src/main/java/cn/itfeng/knowledge/{Auth,Knowledge,Api}.java，以及 src/test/java/cn/itfeng/knowledge/ApiIntegrationTest.java。向量边界对应 src/ai/java/cn/itfeng/knowledge/AiConfiguration.java 和 src/ai-test/java/cn/itfeng/knowledge/PgVectorIntegrationTest.java。这些文件对应站内仓库的 examples/knowledge-service/。
公开报告对应仓库 docs/verification/knowledge-service/report.json，最终 ai 编译验证共 22 项：21 通过、1 跳过，失败与错误均为 0；跳过的是 LiveEmbeddingTest。默认 17 项与最终 22 项有重叠，23 次 HTTP 检查也属于另一种验证口径，不能相加成独立功能覆盖数或质量百分比。
提交自己的描述前，逐项检查：实现动词有本人证据；结果附环境和输入；引用能定位当前版本；未执行的内容写“未测”；删除企业客户、性能提升和求职结果等无依据结论。再按项目简历指南复核主语。
下一步读三分钟讲解与五个追问，用项目表达资料保存材料，并按项目到简历路线补齐实践。也可返回修改室目录或知识库项目页核对运行条件。