source-kb 0.2.2__py3-none-any.whl

skills/_shared/doc-quality-standard.md

@@ -0,0 +1,1058 @@
+# 知识库文档质量标准
+
+> 通用部分 — 适用于所有语言和项目结构。语言特定的检查维度见 `presets/{lang}/audit_dimensions.md`。
+>
+> **Preset 适配说明**：本文档中的示例以 Java/Spring Boot 项目为主（如包路径 `controller/`、`service/`，注解 `@Transactional` 等）。
+> 使用其他 preset 时，应将这些示例替换为对应语言/框架的等价概念：
+> - Java 包路径 → Python 模块路径 / Go package / Rust module
+> - Java 注解 → Python 装饰器 / Go struct tag / Rust attribute
+> - pom.xml → requirements.txt / go.mod / Cargo.toml
+> - Maven artifact → pip package / Go module / Rust crate
+>
+> 可选文档（caching.md、messaging.md、external-integrations.md）的触发条件由 preset 的 `audit_dimensions.md` 定义。
+> 不使用对应中间件的项目无需生成这些文档。
+
+## 1. 标准文件集
+
+每个模块的知识库文档包含以下文件，按三层依赖关系生成：
+
+**第一层：结构文档**（最先生成，后续文档依赖其文件清单和模块概述）
+
+| # | 文件 | 说明 | 必需 |
+|---|------|------|------|
+| 1 | source-tree-analysis.md | 源码目录结构分析 | ✅ |
+| 2 | index.md | 模块概览 + 文档导航 | ✅ |
+
+**第二层 A：数据模型文档**（最先生成，其他中立文档依赖它的类型定义）
+
+| # | 文件 | 说明 | 必需 |
+|---|------|------|------|
+| 3 | data-models.md | 数据模型（实体、DTO、VO） | ✅ |
+| 4 | enums-and-constants.md | 枚举定义 + 常量定义 | ✅ |
+
+**第二层 B：其他中立事实文档**（描述"是什么"，依赖 data-models.md，互相之间无依赖，可并行生成）
+
+| # | 文件 | 说明 | 必需 |
+|---|------|------|------|
+| 5 | api-contracts.md | API 接口契约 | ✅（有 API 时） |
+| 6 | architecture.md | 架构设计 + 技术栈 + 依赖 | ✅ |
+| 7 | caching.md | 缓存设计（Key/TTL/策略） | 可选（有缓存时） |
+| 8 | messaging.md | 消息队列事件架构 | 可选（有消息队列时） |
+| 9 | external-integrations.md | 外部集成 | 可选 |
+
+**第三层：业务逻辑文档**（描述"怎么做"，必须引用第二层文档，禁止重复其内容）
+
+| # | 文件 | 说明 | 必需 |
+|---|------|------|------|
+| 10 | business-logic.md | 核心业务逻辑 | ✅ |
+| 11 | utils.md | 工具类方法级文档 | ✅（有工具类时） |
+
+**生成顺序原则**：data-models.md 和 enums-and-constants.md 是所有中立文档的基础（接口参数/响应引用 DTO/VO 字段，Redis Value 引用 Domain 字段，Kafka 消息体引用 DTO 字段，业务逻辑引用枚举值和常量），必须在其他中立文档之前完成。enums-and-constants.md 与 data-models.md 同批生成（第二层 A）。business-logic.md 和 utils.md 是最后生成的文档，它们通过引用链接关联第二层文档中的事实定义（字段表、Key 规则、消息体、接口签名、枚举值等），避免内容重复。详见 5.1.1 节。
+
+## 2. Markdown 格式规范
+
+- 标题层级：`#` 文档标题 → `##` 大章节（类/模块） → `###` 方法/子节
+- 编号：`## 1. 业务流程名` → `### 1.1 子流程/类名` → `#### 方法名`（business-logic.md）；其他文档按各自 5.x 节的章节结构
+- 代码块：方法签名用 ` ``` ` 包裹，注明语言
+- 表格：字段列表、参数列表用表格
+- 增量修改时保持原有编号，新增内容追加到对应章节末尾
+
+## 3. 文档生成流程（Write-as-you-go）
+
+写盘纪律详见 [doc-subagent-rules.md](./doc-subagent-rules.md) §8.5.1。核心原则：每个文档生成完毕立即写盘，写盘后读取验证编码正常，禁止攒到最后一次性写入。
+
+## 4. 模块类型与跳过规则
+
+模块类型由 `kb-project.yaml` 中的 `type` 字段定义，跳过规则由 preset 的 `module_types` 配置：
+
+```yaml
+# 示例（presets/java-spring/preset.yaml）
+module_types:
+  service:
+    skip: []                    # 不跳过任何文档
+  api-contract:
+    skip: ["business-logic.md"] # 契约包无业务逻辑
+  base-lib:
+    skip: ["api-contracts.md"]  # 基础库无 API
+  frontend:
+    skip: ["source-tree-analysis.md", "api-contracts.md"]
+  demo:
+    skip: ["*"]                 # 跳过所有文档（"*" 为通配符，匹配所有文档名）
+```
+
+## 5. 文档质量标准
+
+以下标准适用于所有文档类型。5.1-5.3 针对 business-logic.md，5.4 针对 api-contracts.md，5.5 针对 data-models.md，5.6 针对 architecture.md，5.7 针对 source-tree-analysis.md，5.8 针对 index.md，5.9 针对 caching.md，5.10 针对 messaging.md，5.11 针对外部依赖。
+
+### 通用禁止事项（所有文档类型）
+
+- 禁止"需要确认"、"待补充"等占位文字
+- 禁止省略分支逻辑（每个 if/else 都要写）
+- 禁止脱离源码编造逻辑
+- 禁止用模糊描述代替具体值（如"某个配置项"应写为 `app.query.isReturnExpirePointSwitch`）
+- 禁止纯代码翻译式文档（逐方法罗列签名和调用树但不提炼业务语义）
+- 禁止文档导航链接标注"待补充"、"待完善"等未清理的生成痕迹
+
+### 核心原则：提炼知识而非翻译代码
+
+文档的价值在于**业务知识的提炼**，不是源码的另一种表达。具体要求：
+
+1. **信息密度优先**：30KB 的高密度业务提炼 > 100KB 的代码调用树展开。每段文字都应传递源码中不直观的业务语义
+2. **标注设计决策和风险点**：如"push 发送在事务内部，事务回滚时消息已发出（潜在不一致）"、"负数账户仅对正数部分计算过期记录"
+3. **横切面汇总必须有**：每个模块的 business-logic.md 末尾必须包含汇总表（详见 5.3.1 节）
+4. **业务规则用人话说**：如"仅支持整单返还"、"撤销仅支持 ORDER_ADD/ACT_ADD，权益发积分不支持撤销"，而非只写 `if (operation != ORDER_ADD && operation != ACT_ADD) throw ...`
+
+### 核心原则：RAG 检索闭环（省略判断的唯一标准）
+
+文档最终通过 RAG 向量检索被消费。**省略的唯一判断标准是：检索到这段内容后，读者能否得到闭环的逻辑，不需要再翻源码。**
+
+- **可以省略**：纯样板代码（getter/setter）、框架生成的模板方法、与业务无关的基础设施代码
+- **不可省略**：任何影响业务理解的信息——即使它看起来"简单"或"辅助"
+
+具体判断方法：假设用户问了一个关于该类/方法/字段的问题，RAG 检索命中了这段文档。用户能否仅凭这段内容理解完整逻辑？
+- 能 → 当前深度足够
+- 不能，还需要翻源码 → 必须补充细节
+
+**典型的"看似可省略但不可省略"场景**：
+1. 辅助实体的字段列表 — 省略后检索到该实体时不知道有哪些字段，无法理解关联逻辑
+2. Mapper 的 SQL 条件 — 省略后检索到该方法时不知道 WHERE 条件和 SET 子句，无法理解数据变更逻辑
+3. Redis key 的 TTL 和数据结构类型 — 省略后检索到该 key 时不知道过期策略和存储格式
+4. Lua 脚本的比较逻辑和返回值 — 省略后检索到 CAS 操作时不知道成功/失败条件
+5. 配置项的默认值 — 省略后检索到该配置时不知道未配置时的行为
+
+### 5.1 内容组织原则
+
+business-logic.md 按业务流程组织，不是按代码结构罗列：
+
+- `##` 章节标题用业务域/功能域命名（如"积分发放"、"账户管理"），不是类名
+- 同一业务流程涉及多个类时，合并到一个章节，说明调用链路
+- 类名作为 `###` 子节标题，方法作为 `####` 或列表项
+- 章节内按业务流程顺序排列，不是按类的字母序
+
+**base-lib 模块特殊规则**（以下内容仅适用于 java-spring preset，其他 preset 请按对应语言的数据访问层模式调整）：base-lib 没有 Controller 入口，DAO/Service 层就是它的"业务流程"载体。business-logic.md 必须完整覆盖：
+- 每个 DAO 的 public 方法签名和业务逻辑（含分支、排序、日志记录等）
+- 每个 Mapper 的自定义 SQL 方法，必须包含：
+  - 方法名 + SQL 类型（SELECT/UPDATE/INSERT/DELETE）
+  - WHERE 条件字段列表（如 `WHERE point_account_id = #{id} AND version = #{version}`）
+  - UPDATE 的 SET 子句逻辑（如 `SET available_point = available_point + #{amount}`，区分"覆盖赋值"和"增量运算"）
+  - 并发控制方式（乐观锁 version 字段 / 无 / 其他）
+  - 返回值语义（如 `返回影响行数，0 表示版本冲突`）
+  - 禁止只列方法名 — 检索到该 Mapper 方法时必须能理解它的 SQL 行为
+- RedisService/StringRedisService 等中间件封装类的完整方法清单（方法签名 + Sentinel 资源名 + 校验逻辑）
+- 按功能域组织章节（如"数据访问层"、"缓存服务层"、"ID 生成服务"），不按类名逐个罗列
+
+反例（禁止）：
+```markdown
+## QueryController          ← 错误：用类名做章节标题
+### queryAccount
+### queryAccountList
+## QueryServiceImpl         ← 错误：按类逐个罗列
+### queryPointAccount
+```
+
+#### 公共方法与辅助逻辑（兜底章节）
+
+文档末尾增加 `## 公共方法与辅助逻辑` 章节，收录不属于任何单一业务流程的方法：
+
+- 被 ≥ 3 个不同业务流程调用的公共工具方法
+- 不在任何入口（Controller/Scheduled/KafkaListener/Feign）调用链上的独立方法
+- 配置类、初始化方法、框架回调等
+
+兜底章节内部按类分组（`### 类名 → #### 方法名`）。
+
+被 2 个业务流程共用的方法：在首次出现的流程中详写，在第二个流程中用 2-3 行摘要简述。
+
+**工具类深度要求**（`*Util`、`*Helper`、`*Tool` 类）：工具类的每个 public 方法必须包含：
+- 方法签名
+- 核心实现逻辑（不是一句话概述），如 KeyUtil.generate 的拼接规则、ObjectUtil 的反射遍历逻辑
+- 特殊配置（如 JsonUtil 的 ObjectMapper 全局配置项列表）
+- 边界校验逻辑（如 `delta < 0` 抛异常的具体异常信息）
+- 禁止只写一行概述就结束
+
+每个 `##` 业务流程章节必须包含：
+
+1. **模块概述**（首个 `##` 前或每个 `##` 开头）：一段话说明该业务流程的整体功能、支持的模式、核心类/函数
+2. **入口信息**：入口函数/类名、路由路径 + HTTP 方法、流控/限流资源名（如有）
+3. **调用链树形图**（调用深度 ≥ 3 层时必须画）：用 ASCII 树形缩进展示完整调用路径，包含每一层的分支逻辑
+4. **关键业务规则**（独立小节）：调用链之后，用编号列表总结该流程的核心规则
+
+示例结构：
+```markdown
+## 1. 积分账户查询（单账户，含缓存）
+
+### 入口
+- 入口：`QueryController.queryAccount(String customerId, Integer currency)`
+- 路由：`GET /account/{customerId}?currency={currency}`
+- 流控：`PointsQueryAccount`
+
+### 完整执行路径
+
+​```
+QueryController.queryAccount(customerId, currency)
+  └─ QueryServiceImpl.queryPointAccount(customerId, currency)
+       ├─ 1. PointAccountBiz.queryPointAccount2B(customerId, currency)
+       │     └─ queryPointAccountFromCache(customerId, currency)
+       │          ├─ 2. 构造缓存 Key: "crm:point:account:base:" + customerId + ":" + currency
+       │          ├─ 3. 尝试从缓存读取
+       │          │     ├─ 命中 → 解析 JSON
+       │          │     └─ 未命中 → 查数据库 → 写入缓存（CAS）
+       │          ├─ 4. 穿透判断: customerId == null → 返回 null
+       │          └─ 5. 构建 VO（含过期计算）
+       ├─ 2. accountVO == null → 返回错误码 CRMPNT015010
+       └─ 3. 构建响应 → 返回成功
+​```
+
+### 关键业务规则
+1. 缓存优先：Key 格式 `crm:point:account:base:{customerId}:{currency}`
+2. 缓存值格式：`{JSON}|{version}`，CAS 机制保证并发安全
+3. 缓存 TTL：默认 18000 秒，通过配置中心 `point.query.accountExpireTimeSecond` 动态调整
+4. 缓存穿透防护：不存在时写入空值缓存（customerId=null）
+5. 可用积分 = DB可用积分 - 昨日过期积分
+```
+
+### 5.1.1 跨文档引用规则（去重核心机制）
+
+business-logic.md 是最后生成的文档（第三层），它必须引用而非重复第二层中立文档的内容。第二层 B 的中立文档也必须引用 data-models.md（第二层 A）的类型定义，而非重复。
+
+**中立文档之间的引用**（第二层 B → 第二层 A）：
+
+| 文档 | 引用 data-models.md 的场景 | 写法 |
+|------|--------------------------|------|
+| api-contracts.md | 请求参数类型（Param/DTO）、响应类型（VO） | 参数表只写类名 + 关键字段摘要（3-5 个），引用：`完整字段详见 [data-models.md §X](./data-models.md#锚点)` |
+| caching.md | Value 中序列化的 Domain/VO 对象 | 只写类名 + 序列化格式，引用字段定义 |
+| messaging.md | 消息体中的 DTO/Domain 对象 | 消息体示例只写 JSON 骨架（关键字段），引用完整定义 |
+| architecture.md | 一般不直接引用 data-models.md | — |
+
+**business-logic.md 的引用**（第三层 → 第二层）：
+
+| 内容类型 | 唯一归属文档 | business-logic.md 的写法 |
+|---------|------------|------------------------|
+| 实体/DTO/VO 字段定义 | data-models.md | 只写类名，引用：`（字段定义详见 [data-models.md §X.X](./data-models.md#锚点)）` |
+| 枚举值完整列表 | data-models.md | 只写枚举名 + 当前分支用到的值，引用全表 |
+| 常量具体值 | data-models.md | 只写常量名，引用：`（值详见 [data-models.md §5](./data-models.md#5-常量定义)）` |
+| 接口签名/参数/响应结构 | api-contracts.md | 只写方法名 + 路径，引用：`（完整契约详见 [api-contracts.md §X](./api-contracts.md#锚点)）` |
+| 错误码完整列表 | api-contracts.md | 只写当前分支抛出的错误码枚举名，引用汇总表 |
+| 缓存 Key 拼接规则/TTL/CAS 流程 | caching.md | 只写 Key 名称和操作类型（读/写/删），引用：`（详见 [caching.md §X](./caching.md#锚点)）` |
+| 消息队列消息体 JSON/消费逻辑 | messaging.md | 只写 topic 名 + 消息类名，引用：`（详见 [messaging.md §X](./messaging.md#锚点)）` |
+| 技术栈版本/依赖清单 | architecture.md | 不在 business-logic.md 中提及 |
+| 线程池配置参数 | architecture.md | 只写线程池 Bean 名称，引用 architecture.md |
+| Sentinel 资源名/限流配置 | architecture.md | 只写资源名，引用 architecture.md |
+
+**跨模块引用**（依赖模块的文档已生成时）：
+
+| 内容类型 | 写法 |
+|---------|------|
+| 依赖模块的 Domain 字段 | `PointAccount（详见 [point-base/data-models.md §1.1](../point-base/data-models.md#11-pointaccount)）` |
+| 依赖模块的枚举定义 | `TransactionStatusEnum（详见 [point-base/data-models.md §4.2](../point-base/data-models.md#42-transactionstatusenum)）` |
+| 依赖模块的 DAO 方法 | `accountDao.addPointWithVersion()（来源: point-base）` — 不展开 SQL 细节 |
+
+**引用格式规范**：
+- 使用 Markdown 锚点链接：`[文档名 §章节号](./文件名.md#锚点)`
+- 锚点由 Markdown 标题自动生成（小写、空格转 `-`、去除特殊字符）
+- 如果目标文档尚未生成（不应发生，因为中立文档先生成），写 `（待生成：文件名）` 并在覆盖率校验时报错
+
+**引用规则的例外**（必须在 business-logic.md 中展开，不能只写引用链接）：
+1. 同一中间件在不同业务流程中的行为差异（如"单账户查询走缓存，批量查询直接查 DB"、"buildBackendPointAccountVO 不受开关控制，buildBackendPointAccountVoNew 受 expiredPointPushSwitch 控制"）
+2. 已知 bug 或设计风险（如"ZSet add 传入 list 而非单条导致序列化异常"、"事务内发 MQ 的不一致风险"），必须用 ⚠️ 标注
+3. 业务开关对逻辑分支的影响（如"expiredPointPushSwitch 控制过期积分计算是否执行"）
+4. 错误码的触发条件和业务语义（错误码值引用 api-contracts.md，但"什么条件下触发哪个错误码"必须在业务流程中说明）
+5. 不同查询方式的数据源差异（如"getLastDayExpirePoint 直接查 TiDB，getLastDayExpirePointFromCache 走 Redis"）
+
+原则：中立文档定义"是什么"（Key 格式、字段定义、接口签名），business-logic.md 解释"为什么这样用"和"不同场景有什么区别"。
+
+**反例（禁止）**：
+```markdown
+## 积分发放
+...
+Redis Key 格式：`crm:point:account:base:{customerId}:{currency}`
+数据类型：String（版本化 JSON）
+TTL：18000 秒（Nacos 配置 point.query.accountExpireTimeSecond）
+CAS 写入流程：
+1. 构造 accountKey = POINT_ACCOUNT_BASE_INFO + customerId + ":" + currency
+2. 构造 value = JSON(account) + "|" + version
+3. 调用 redisService.compareAndSetCache(...)
+...
+```
+↑ 这些内容已经在 caching.md 中完整描述，business-logic.md 重复了。
+
+**正例（要求）**：
+```markdown
+## 积分发放
+...
+├── accountCacheBiz.deleteAccountCache()（删除账户缓存，详见 [caching.md §2.5](./caching.md#25-积分账户基础信息缓存版本化)）
+├── pointExpiredRecordBiz.rollExpireCompute()（滚动过期计算，详见 [caching.md §2.6](./caching.md#26-积分过期记录缓存版本化)）
+...
+```
+
+### 5.2 方法级质量维度
+
+每个方法章节应包含：
+
+| # | 维度 | 说明 | 必需 |
+|---|------|------|------|
+| 1 | 方法签名 | 完整签名（访问修饰符、返回类型、参数） | ✅ |
+| 2 | 业务目的 | 一句话说明这个方法做什么 | ✅ |
+| 3 | 核心流程 | 主要步骤（编号列表） | ✅ |
+| 4 | 分支逻辑 | 所有 if/else/switch 分支的条件和行为 | ✅ |
+| 5 | 外部调用 | 调用了哪些外部服务/中间件 | ✅ |
+| 6 | 数据变更 | 写了哪些表/缓存/消息队列 | ✅ |
+| 7 | 关键注解/装饰器 | 事务、异步、定时、缓存等框架注解及其配置参数 | ✅ |
+| 8 | 常量/配置引用 | 业务常量的具体值、配置中心配置项名称及默认值 | ✅ |
+| 9 | 错误处理 | 异常类型、错误码、降级策略 | ✅ |
+| 10 | 并发控制 | 分布式锁 key+过期时间、幂等机制、重试策略、线程池/协程池名称 | high |
+
+标注 `high` 的维度：low/medium 复杂度方法可省略，high 复杂度方法必须全部覆盖。其余维度所有 public 业务方法都必须覆盖。
+
+**具体数值准确性要求（铁律）**：骨架 JSON 不包含方法调用的具体参数值。文档中涉及具体数值的描述，必须从源码验证后才能写入，无论方法复杂度等级：
+- 超时时间、缓存 TTL、线程池参数、锁参数（waitTime/leaseTime）、注解默认值、重试次数、批量大小 → 必须 Read 源码确认
+- 日期/时间处理逻辑 → 必须 Read 源码确认（方法名容易误导）
+- 锁 key 拼接规则、序列化格式 → 必须 Read 源码确认
+- 执行方式：遇到需要写数值 → 暂停 → Read 源码 → 确认后写入
+- 禁止从骨架推断、凭方法名猜测、凭经验填写"常见值"
+- 无法读源码时写 `⚠️ 待验证`
+
+### 5.3 内容深度要求
+
+- 每个 public 业务方法至少 5-10 行描述（签名 + 目的 + 流程 + 调用 + 变更）
+- 禁止只写方法签名 + 一句话概述就结束
+- 核心流程必须是编号步骤列表，不是一段话
+- 调用深度 ≥ 3 层的方法，必须画 ASCII 调用链树形图
+- 涉及中间件的方法，必须写明具体名称：
+  - 消息队列：topic 名称、消息体类型、消费者 group
+  - 缓存：key 完整拼接规则、value 格式、TTL 及来源（硬编码/配置中心配置项名）
+  - 搜索引擎：index 名称、文档类型
+- 涉及配置中心的方法，必须写明配置项 key 和默认值
+- 涉及异步/并行的方法，必须写明线程池/协程池/worker 名称
+- 每个业务流程章节末尾必须有独立的"关键业务规则"小节，用编号列表总结
+- 涉及设计风险或已知坑点的，必须用 `⚠️` 标注（如"事务内发 MQ 的不一致风险"、"先 ACK 再异步处理导致消息丢失风险"）
+
+### 5.3.1 横切面汇总表（business-logic.md 末尾必须包含）
+
+business-logic.md 文档末尾必须包含以下横切面汇总章节，将分散在各业务流程中的共性信息归纳为表格，便于快速查阅：
+
+#### 1. 并发控制汇总表（必须）
+
+汇总模块中所有并发控制机制：
+
+```markdown
+## 并发控制汇总
+
+| 机制 | 粒度 | 使用场景 |
+|------|------|----------|
+| Redisson 分布式锁 | customerId + currency | 加积分（含人工补发） |
+| DB 乐观锁（version） | 表行级 | 所有账户更新操作 |
+| Redis CAS（version 比较） | 缓存 Key 级 | 账户/过期缓存更新与删除 |
+| @Idempotent 注解 | 接口级 | Controller 所有交易接口 |
+```
+
+#### 2. 错误码汇总表（必须）
+
+汇总模块中所有业务错误码：
+
+```markdown
+## 错误码汇总
+
+| 错误码枚举 | 含义 | 触发场景 |
+|-----------|------|----------|
+| TRANSACTION_ACCOUNT_NOT_FOUND | 账户不存在 | 查询账户为空或已注销 |
+| LOCK_FAIL | 获取锁失败 | Redisson tryLock 失败 |
+```
+
+#### 3. Kafka 事件汇总表（有消息队列时必须）
+
+汇总模块中所有 Kafka Topic 的生产和消费关系：
+
+```markdown
+## Kafka 事件汇总
+
+| Topic | 生产者 | 消费者 | 说明 |
+|-------|--------|--------|------|
+| point-incr | PointIncrServiceImpl.addPoint | IncrPointHandlerListener | 加积分异步处理 |
+```
+
+#### 4. Feign 调用汇总表（有 Feign 调用时必须，仅适用于 java-spring preset）
+
+汇总模块的所有 Feign 调用关系（含被调用和主动调用）：
+
+```markdown
+## Feign 调用汇总
+
+| 调用方 | 被调方 | 接口 | 说明 |
+|--------|--------|------|------|
+| point-batch | point-transation | RetryApi | 补偿重试 |
+```
+
+#### 5. 线程资源总览表（有自定义线程池时必须）
+
+汇总模块中所有线程池配置：
+
+```markdown
+## 线程资源总览
+
+| 线程池 | 线程数 | 用途 |
+|--------|--------|------|
+| Undertow Worker | 256 | HTTP 请求处理 |
+| updateCacheExecutorService | 100 | 账户缓存异步更新 |
+| IncrPointHandler 线程池 | 120 | 加积分批量消费并行处理 |
+| **合计** | **~892** | |
+```
+
+**汇总表数据来源**：从前面各业务流程章节中提取归纳，不需要重新读源码。如果前面章节遗漏了某些信息，在编写汇总表时补充。
+
+### 5.3.2 体量控制与信噪比
+
+**文件体量上限**：
+
+| 文件 | 单模块上限 | 超限处理 |
+|------|-----------|---------|
+| business-logic.md | 50 KB | 按业务域拆分为多个文件（如 business-logic-incr.md、business-logic-decr.md） |
+| source-tree-analysis.md | 25 KB | 按复杂度分级（见 5.7.3），low 复杂度类必须用行内注释格式 |
+| architecture.md | 35 KB | 正常，不太可能超 |
+| data-models.md | 30 KB | 兄弟模块类用简化表格（字段名+类型），不省略字段（见 5.5.3 RAG 自包含原则） |
+
+**信噪比规则**：
+
+1. **low 复杂度方法**（纯 CRUD、getter/setter、简单委托、单行转发）：
+   - 在调用链中一行提及即可，格式：`→ AccountBiz.queryValidAccount()（查 DB，DISABLE 则抛异常）`
+   - 禁止为 low 方法写独立的"步骤列表"或"调用链树形图"
+2. **medium 复杂度方法**：2-5 行描述（签名 + 目的 + 关键分支），不画调用链树
+3. **high 复杂度方法**：完整步骤 + 调用链树 + 所有分支 + 风险标注
+4. **辅助/工具方法**（如 getQueryParameterRecord、buildXxxVO）：仅在被调用处一句话内联，不单独成节
+
+**跨文档去重规则**（与 5.1.1 配合执行）：
+
+| 内容类型 | 唯一归属文档 | 其他文档的引用方式 |
+|---------|------------|------------------|
+| 缓存 Key 完整读写流程 | caching.md | business-logic.md 写一行引用链接 |
+| 消息队列消息体 JSON 示例 | messaging.md | business-logic.md 只写 topic 名 + 消息类名 |
+| Domain/Entity 字段表 | data-models.md（或引用兄弟模块） | business-logic.md 不重复列字段 |
+| 枚举值完整列表 | data-models.md | 其他文档只写枚举名 + 关键值 |
+| 线程池配置参数 | architecture.md | business-logic.md 只写线程池名称 |
+
+### 5.3.3 RAG 检索友好性
+
+知识库文档的最终消费者是 embedding 模型 + 向量检索。以下原则提升检索命中率：
+
+1. **每个 `##` 章节开头用一句自然语言总结**：如"积分兑换是同步扣减操作，校验可用余额后直接扣减账户，不允许扣为负数"。这句话是 embedding 的主要命中目标
+2. **关键业务规则用独立小节汇总**：不要散落在步骤描述中，集中的规则列表更容易被检索命中
+3. **避免大段纯表格**：embedding 模型对表格的语义理解弱于自然语言段落。表格前加一段文字概述
+4. **信息密度 > 信息量**：30KB 的高密度文档在 RAG 中的表现优于 100KB 的低密度文档，因为 chunk 切分后每个 chunk 的信息浓度更高
+
+## 5.4 api-contracts.md 质量标准
+
+### 5.4.1 内容组织
+
+按 Controller 分大章节（外部接口 / 内部接口），每个接口独立小节。
+
+每个接口必须包含：
+
+| # | 内容 | 必需 |
+|---|------|------|
+| 1 | HTTP 方法 + 路径 | ✅ |
+| 2 | 请求参数表（参数名、位置、类型、必填、校验规则、说明） | ✅ |
+| 3 | 响应类型 + VO 字段说明表（字段名、类型、业务含义） | ✅ |
+| 4 | 响应 JSON 示例 | ✅ |
+| 5 | 错误码（该接口可能返回的错误码 + 触发条件） | ✅ |
+| 6 | Sentinel 资源名 / 限流配置 | 有则写 |
+| 7 | 注解说明（@ApiAnnotation、@Validated 等） | 有则写 |
+
+### 5.4.2 必须包含的汇总章节
+
+文档末尾必须有以下汇总章节：
+
+1. **统一响应结构**：`Result<T>` 的 JSON 示例 + 字段说明
+2. **错误码汇总表**：所有接口可能返回的错误码、中文描述、触发场景
+3. **枚举值定义**：接口参数/返回值中涉及的枚举类型及其取值（如币种枚举、操作类型枚举）
+4. **接口总览表**：所有接口的 HTTP 方法、URL、说明、类型（外部/内部）
+
+### 5.4.3 VO 字段来源
+
+- 本模块源码中有 VO 定义 → 直接从源码提取字段
+- VO 定义在外部 JAR 中 → 从 `.skeleton-deps/` 骨架提取，标注来源
+- 都找不到 → 从 Controller/Service 的使用代码推断，标注"字段从使用代码推断"
+
+## 5.5 data-models.md 质量标准
+
+### 5.5.1 内容组织
+
+按类型分大章节，每个类独立小节：
+
+| # | 章节 | 内容 | 必需 |
+|---|------|------|------|
+| 1 | Domain 领域实体 | 数据库表对应的实体类，每个字段的类型、说明、数据库列名 | ✅ |
+| 2 | VO 响应模型 | 接口返回的 VO 类，每个字段的类型和业务含义 | ✅ |
+| 3 | Param/DTO 请求模型 | 接口入参类，每个字段的类型、校验注解、说明 | ✅ |
+| 4 | 继承关系 | VO/Entity 的继承关系图（ASCII 或列表） | 有则写 |
+
+> 枚举定义和常量定义已独立为 `enums-and-constants.md`，不在 data-models.md 中。
+
+**实体字段表深度要求（RAG 闭环原则）**：
+- **所有实体类**（不只是核心实体）都必须有完整字段表（字段名 + 类型 + 说明）
+- 禁止对辅助实体只写一句话概述——检索到该实体时必须能看到它的字段结构
+- 字段数 ≤ 5 的简单实体可以用行内格式：`含 customerId(String) / currency(Integer) / amount(Long) 等字段`
+- 字段数 > 5 的实体必须用表格
+- 聚合/统计类实体（如 XxxAggregation、XxxCensus）必须说明聚合维度和聚合字段
+
+**枚举深度要求**（已移至 §5.5A enums-and-constants.md 质量标准）
+
+### 5.5.2 字段表格式
+
+每个类的字段用表格描述：
+
+```markdown
+| 字段 | 类型 | 说明 | 注解/约束 |
+|------|------|------|----------|
+| customerId | String | 会员ID | @NotNull |
+```
+
+### 5.5.3 外部依赖类
+
+**同知识库兄弟模块的类**（依赖模块文档已生成时）：
+- 写类名 + 一句话职责 + 跨模块引用链接
+- 格式：`### PointAccount（来源: point-base）`，正文写 `完整定义详见 [point-base/data-models.md §1.1](../point-base/data-models.md#11-pointaccount)`
+- **列出本模块实际使用的所有字段**（不是 3-5 个），用简化表格（字段名 + 类型，不含注解列）
+- **枚举类**：列出所有枚举值的 code 和 name（完整列表，不省略），以及枚举类的 public 静态方法签名和返回值说明
+- **常量类**：列出本模块引用的所有常量名和值
+- 只有当依赖模块的 data-models.md 尚未生成时，才需要额外展开注解/约束等完整字段信息
+
+**RAG 检索自包含原则**：向量检索按模块目录分 chunk，跨模块引用链接在检索时不可达。每个模块的 data-models.md 必须自包含足够的字段信息，使得用户问该模块相关的数据模型问题时能命中正确答案。"只写类名 + 链接"会导致检索完全失效。
+
+**外部 JAR 的类**（.skeleton-deps 存在，且不属于同知识库兄弟模块时）：
+- 完整列出字段表，标注来源（如 `### QueryPointAccountVO（来源: point-api:1.3.18）`）
+- 这些类没有独立文档可引用，必须在本模块展开
+
+**都找不到时**：
+- 从使用代码推断字段，标注 `⚠️ 字段从使用代码推断，完整定义在 {artifact}:{version} JAR 中`
+
+## 5.5A enums-and-constants.md 质量标准
+
+### 5.5A.1 文件定位
+
+独立文件，与 data-models.md 同批生成（第二层 A）。将枚举和常量从 data-models.md 中分离，提升 RAG 检索精度——检索枚举值或错误码时直接命中本文件，不会混杂实体字段信息。
+
+### 5.5A.2 内容组织
+
+| # | 章节 | 内容 | 必需 |
+|---|------|------|------|
+| 1 | 枚举定义 | 所有业务枚举类，按重要度排序（核心枚举在前） | ✅ |
+| 2 | 常量定义 | RedisKeyConstants、SystemConstants 等常量类 | ✅ |
+
+### 5.5A.3 枚举深度要求
+
+每个枚举类必须包含：
+- 所有枚举值的完整字段表（code、name、info 等所有字段，不省略任何枚举值）
+- 枚举类的 public 静态方法签名和返回值说明（如 `isIncr(int operation)` → 判断是否为增加积分操作，返回 true 的 operation 值列表：`{1, 3, 4, 9, 12, 13, 14}`）
+- 枚举类的实例方法（如 `amountCovert()` → 金额转换逻辑说明）
+- 禁止只列枚举值而忽略静态方法——枚举的静态方法是业务规则的核心载体，RAG 检索中最常被查询
+- 错误码枚举（ErrorCodeEnum 等）必须按前缀分组，列出所有 code + 中文消息，不省略
+
+### 5.5A.4 常量深度要求
+
+每个常量类必须包含：
+- 所有 public static final 常量的名称、值、用途说明
+- 常量值必须从源码验证（数值验证铁律）
+- Redis key 常量必须标注对应的 key 模式和用途
+- 系统常量必须标注单位（秒/毫秒/分钟等）
+
+### 5.5A.5 体量参考
+
+- 枚举类 ≤ 5 个的小模块：8-15KB
+- 枚举类 5-15 个的中模块：15-25KB
+- 枚举类 > 15 个的大模块：25-40KB（如 point-base 有 17 个枚举 + 6 个常量类）
+
+## 5.5B utils.md 质量标准
+
+### 5.5B.1 文件定位
+
+独立文件，与 business-logic.md 同批生成（第三层）。将工具类从 business-logic.md 中分离，避免业务逻辑文档过于臃肿，同时提升工具类方法的 RAG 检索精度。
+
+### 5.5B.2 内容组织
+
+每个工具类独立章节，按字母序排列。每个工具类必须包含：
+- 类的一句话职责说明
+- 源码行数（便于判断复杂度）
+- 全局配置（如 ObjectMapper 的 configure 项、静态常量）
+
+每个 public 方法必须包含：
+- 方法签名（完整参数类型和返回值）
+- 核心实现逻辑（不是一句话概述，要写清楚算法/流程）
+- 边界校验（null 检查、异常抛出条件）
+- 特殊行为（如精度处理、编码方式）
+
+### 5.5B.3 典型工具类覆盖要求
+
+| 工具类类型 | 必须包含的细节 |
+|-----------|--------------|
+| 日期工具 | 每个方法的时间精度（天/秒/毫秒）、时区处理、null 行为 |
+| JSON 工具 | ObjectMapper 全局配置项、泛型反序列化方式、异常处理 |
+| 加密/Hash 工具 | 算法名称、编码方式（hex/base64）、输入拼接规则 |
+| 反射工具 | 遍历范围（本类/父类）、null/空串判断逻辑、异常类型 |
+| 分页工具 | 默认值、自动计算逻辑（offset = (page-1) * rows） |
+| Spring 工具 | 实现的 Aware 接口、占位符解析方式、异常降级 |
+
+### 5.5B.4 体量参考
+
+- 工具类 ≤ 3 个的小模块：3-5KB
+- 工具类 3-7 个的中模块：5-12KB
+- 工具类 > 7 个的大模块：12-20KB
+
+## 5.6 architecture.md 质量标准
+
+### 5.6.1 必须包含的章节
+
+| # | 章节 | 内容 | 必需 |
+|---|------|------|------|
+| 1 | 整体架构 | ASCII 分层架构图（从 HTTP 入口到数据访问层），标注每层的核心类名 | ✅ |
+| 2 | 技术栈版本 | 框架、中间件、数据库的具体版本号（表格） | ✅ |
+| 3 | 依赖清单 | pom.xml / build.gradle / requirements.txt / go.mod 中的关键依赖（表格：包名、版本、说明） | ✅ |
+| 4 | 分层职责详解 | 每层的职责、核心类、依赖注入方式、关键注解/装饰器 | ✅ |
+| 5 | 中间件策略详解 | 每种中间件的完整读写流程（不只是配置项） | ✅ |
+| 6 | 架构模式与设计决策 | 交易状态机、幂等设计、补偿机制、线程模型等（详见 5.6.5 节） | ✅ |
+| 7 | Feign 接口契约 | 本模块实现的 Feign 接口表（仅适用于 java-spring preset） | 有则写 |
+| 8 | Feign 调用关系 | 本模块调用了哪些外部服务，被哪些服务调用（仅适用于 java-spring preset） | 有则写 |
+| 9 | 流量防护配置 | Sentinel 全局配置 + 端点级限流资源表（仅适用于 java-spring preset） | 有则写 |
+| 10 | 配置管理 | 分小节：Nacos 动态配置表（配置项、类型、默认值、说明、是否热更新）+ 本地配置表 + 数据源配置表 + Redis 配置表 + Web 容器配置表 | ✅ |
+| 11 | 技术栈依赖关系 | ASCII 依赖树（从模块根节点展开，标注每个依赖的版本和排除项） | ✅ |
+| 12 | 启动入口 | 启动类名、启用的注解（@MapperScan、@EnableFeignClients 等）及其参数 | ✅ |
+| 13 | 部署架构 | Docker 基础镜像、JVM 参数（完整参数字符串）、工作目录、日志路径、健康检查配置 | 有则写 |
+
+### 5.6.2 中间件策略详解要求
+
+不能只罗列配置项，必须写完整的读写流程。每种中间件按以下结构描述：
+
+**Redis 缓存策略**（每种缓存模式独立小节）：
+
+当模块同时生成 caching.md 时，architecture.md 的缓存章节写策略概述（每种缓存的 Key 格式、数据结构、TTL、并发控制方式，各 3-5 行），并在章节末尾加 `详见 [缓存设计](./caching.md)`。完整读写流程放在 caching.md 中。
+
+当模块不生成 caching.md 时，architecture.md 必须写完整内容：
+- Key 格式（完整拼接规则，含常量名和变量）
+- 数据结构（String/Hash/ZSet/List）
+- Value 格式（如 `{JSON}|{version}`）
+- TTL（具体值 + 来源：硬编码/Nacos 配置项名）
+- 并发控制（CAS/分布式锁/无）
+- 完整读取流程（编号步骤：构造 Key → 查缓存 → 命中/未命中分支 → 反序列化 → 返回）
+- 完整写入流程（编号步骤：序列化 → 写入方式 → 异常处理）
+- 缓存穿透防护（如有：空值写入策略、判断逻辑）
+- 注意事项（已知 bug、数据一致性风险等）
+
+**数据库**：
+- 连接池类型和配置表（max-pool-size、min-idle、max-lifetime、connection-timeout 等）
+- 读写分离策略（如有）
+- ORM 框架配置（Mapper 扫描路径、XML 位置、type-aliases-package）
+
+**消息队列**（如有）：
+- 生产/消费模式、Topic 列表、消费者 groupId、并发数
+- 重试策略、死信队列配置
+
+**Sentinel**（如有，仅适用于 java-spring preset）：
+- 全局配置（yaml 代码块，含 projectName、sqlMonitor、httpFilter 等）
+- 所有 `@SentinelResource` 资源名列表（表格：资源名、对应接口、入口类型、忽略异常）
+- 限流规则来源（Nacos 动态下发 / 本地配置）
+
+### 5.6.3 配置项汇总要求
+
+配置项必须按来源分小节，每小节用表格：
+
+1. **Nacos 动态配置**（仅适用于 java-spring preset）：配置项 key、类型、默认值、说明、是否支持热更新（@RefreshScope）
+2. **Nacos 连接配置**（仅适用于 java-spring preset）：server-addr、namespace、prefix、group、file-extension
+3. **本地配置（application.yaml / bootstrap.yaml）**：配置项、默认值、说明
+4. **数据源配置**：JDBC URL、驱动、连接池参数表
+5. **Redis 配置**：timeout、pool 参数表、client-name
+6. **Web 容器配置**：io-threads、worker-threads、buffer-size 等
+
+禁止把所有配置混在一个大表里。
+
+### 5.6.4 内容深度基准
+
+architecture.md 的目标是让一个新人仅凭此文档就能理解模块的技术全貌。参考基准：
+- 一个有 4 种 Redis 缓存策略的查询服务，architecture.md 应在 15-20KB
+- 一个有 Kafka 消费者 + Redis + Sentinel 的写服务，architecture.md 应在 20-30KB
+- 一个 base-lib 基础库（有 Redis + Kafka + Redisson + 多种条件装配），architecture.md 应在 8-15KB
+- 如果生成的文档 < 8KB，几乎一定是内容不足，需要补充
+
+**RAG 闭环检查清单**（生成后自检）：
+- 技术栈版本表是否有具体版本号？缺失 → 检索架构问题时不知道用的什么版本
+- 条件装配表的配置项是否有默认值和来源？缺失 → 检索到该组件时不知道什么条件下启用
+- Maven 关键依赖是否列出？缺失 → 检索依赖问题时无法定位
+- 配置文件结构（profile 切换机制）是否说明？缺失 → 检索配置问题时不知道多环境如何切换
+
+### 5.6.5 架构模式与设计决策（第 6 章节详细要求）
+
+第 6 章节从"有则写"升级为**必须**，因为架构模式分析是理解模块设计意图的关键。即使模块没有显式声明架构模式，也必须从源码中提炼出以下内容（按适用性选择）：
+
+#### 1. 交易/业务状态机（有状态流转时必须）
+
+用 ASCII 状态图画出核心实体的状态流转，包含：
+- 所有状态值（从枚举或常量中提取）
+- 状态转换条件（哪个方法触发）
+- 子状态（如有）
+
+示例：
+```
+                    ┌──────────┐
+                    │   NEW    │ ← 初始状态
+                    └────┬─────┘
+                         │ (异步处理完成)
+                         ▼
+                    ┌──────────┐
+                    │ COMPLETE │ ← 最终状态
+                    └──────────┘
+```
+
+#### 2. 幂等设计全景（有幂等机制时必须）
+
+按层级汇总模块的所有幂等机制：
+
+```markdown
+| 层级 | 机制 | 覆盖范围 | 说明 |
+|------|------|----------|------|
+| 接口级 | @Idempotent 注解 | Controller 所有交易接口 | 框架层拦截 |
+| 业务级 | DuplicateKeyException 捕获 | 加积分 initTransaction | 数据库唯一键 |
+| 业务级 | 状态查询判断 | 兑换/冻结/撤销/返还 | 已存在则直接返回 |
+| 消费者级 | transaction 状态校验 | Kafka 消费者 | 非预期状态则跳过 |
+```
+
+#### 3. 补偿机制（有重试/补偿时必须）
+
+说明补偿的触发方式、重试接口、重试间隔配置：
+
+```markdown
+| 重试方法 | 功能 | 触发方式 |
+|----------|------|----------|
+| retryAddPointHandler | 批量加积分重试 | xxl-job 定时扫描失败记录 |
+```
+
+#### 4. 线程模型总览（有自定义线程池时必须）
+
+汇总模块所有线程资源（含 Web 容器、自定义线程池、Consumer 内部线程池），给出合计数：
+
+```markdown
+| 线程池 | 核心/最大线程数 | 队列 | 用途 |
+|--------|---------------|------|------|
+| Undertow Worker | 256 | - | HTTP 请求处理 |
+| IncrPointHandler | 120 | LinkedBlockingQueue(无界) | 加积分批量消费并行 |
+| **合计** | **~892** | | |
+```
+
+⚠️ 无界队列 + 大线程池的组合需要标注 OOM 风险。
+
+#### 5. 事件驱动架构（有 Kafka/MQ 时必须）
+
+说明同步 vs 异步操作的划分原则，用表格列出每种操作的同步部分和异步部分：
+
+```markdown
+| 操作类型 | 同步部分 | 异步部分 |
+|----------|----------|----------|
+| 加积分 | 保存 transaction(NEW) | Kafka→加锁→写 record→更新账户→推送 |
+| 积分兑换 | 扣减账户→写 record→发溯源 MQ | 溯源处理→推送 |
+```
+
+#### 6. CQRS 模式（读写分离时必须）
+
+说明模块是读侧还是写侧，数据同步机制（Kafka/binlog/缓存更新）。
+
+**注意**：如果模块确实没有上述任何模式（纯 CRUD 无状态流转、无幂等、无补偿、无自定义线程池、无 MQ），第 6 章节写一段话说明"本模块采用标准分层架构，无特殊架构模式"即可。但这种情况在实际业务系统中极少出现。
+
+## 5.7 source-tree-analysis.md 质量标准
+
+### 5.7.1 内容组织
+
+source-tree-analysis.md 必须是完整的文件树 + 每个文件的一行职责说明。
+
+**必须包含的章节**：
+
+| # | 章节 | 内容 | 必需 |
+|---|------|------|------|
+| 1 | 模块目录结构总览 | 完整的 ASCII 文件树（从模块根目录开始，包含所有文件） | ✅ |
+| 2 | 源码文件详解 | 按目录分组，每个 Java/源码文件独立描述（类名、类型、职责、核心方法列表、代码行数、依赖） | ✅ |
+| 3 | 资源文件说明 | application.yaml、bootstrap.yaml、logback、mapper XML 等配置文件的用途 | ✅ |
+| 4 | 测试文件说明 | test 目录下的测试类及其覆盖范围 | 有则写 |
+| 5 | 构建与部署文件 | pom.xml、Dockerfile、Jenkinsfile、docker-compose 等的用途 | 有则写 |
+| 6 | 依赖模块文件 | 被本模块直接使用的外部类（Domain/Enum/VO/Constant/DAO 等），按来源分组 | 有则写 |
+
+**依赖模块文件的数据来源规则**（按优先级）：
+
+1. **`.skeleton-deps/` 存在**（通过 `resolve_jar_sources.py` 反编译的外部 JAR）→ 从依赖骨架提取关键类，每个类列出：类名、类型、职责一句话
+2. **依赖模块在同一知识库中**（`kb-project.yaml` 的 repos 中有对应 artifactId）→ 写交叉引用链接 + 摘要：
+   - 链接格式：`详见 [{module} 模块](../{module}/source-tree-analysis.md)`
+   - 同时从兄弟模块的 `.skeleton/` 或 `.skeleton.json` 中提取被本模块直接 import 的关键类（Domain/Enum/Constant/DAO），每个类列出：类名、类型、职责一句话
+   - 判断"被本模块直接 import"的方法：扫描本模块源码的 import 语句，匹配兄弟模块骨架中的类名
+3. **两者都不存在**（未配置 maven_repo 或下载失败）→ 从本模块源码的 import 语句推断外部类，标注 `来源: {artifactId}:{version}（未反编译，从使用代码推断）`
+
+**注意**：即使依赖模块在同一知识库中有独立文档，仍需在本模块的 source-tree 中列出被使用的关键类摘要。原因：读者查看单个模块文档时不应被迫跳转到其他模块才能理解依赖关系
+
+### 5.7.2 文件树格式要求
+
+文件树必须使用 ASCII 树形格式，包含模块根目录下的所有文件和目录：
+
+```markdown
+module-name/
+├── .gitignore
+├── Dockerfile
+├── Jenkinsfile
+├── README.md
+├── docker-compose.local.yml
+├── pom.xml
+├── src/
+│   ├── main/
+│   │   ├── java/com/example/
+│   │   │   ├── Application.java
+│   │   │   ├── biz/
+│   │   │   │   ├── AccountBiz.java
+│   │   │   │   └── RecordBiz.java
+│   │   │   └── controller/
+│   │   │       └── QueryController.java
+│   │   └── resources/
+│   │       ├── application.yaml
+│   │       ├── bootstrap.yaml
+│   │       └── mapper/
+│   │           └── AccountMapper.xml
+│   └── test/
+│       └── java/com/example/
+│           └── AccountTest.java
+```
+
+**禁止事项**：
+- 禁止用省略号（`...`）代替文件列表
+- 禁止用模糊计数（如"15+ 个文件"）
+- 禁止虚构不存在的文件名
+- 禁止只列 Java 文件而忽略 resources、test、构建文件
+
+**数据来源**：文件树必须从 `git ls-tree -r --name-only` 或 `.source-cache` 目录获取，不能凭记忆编写。
+
+### 5.7.3 源码文件详解格式
+
+每个源码文件按复杂度分级描述：
+
+**high 复杂度类**（骨架标记 complexity=high，或 line_count > 200，或核心业务类）：完整多行描述块：
+
+```markdown
+### 2.1 PointAccountBiz
+
+- **文件路径**：`src/main/java/com/example/app/biz/PointAccountBiz.java`
+- **类型**：class（@Component）
+- **代码行数**：~425 行
+- **职责**：积分账户查询业务逻辑，管理账户缓存（Redis String + CAS）
+- **依赖注入**：PointTypeBiz, PointAccountDao, PointExpiredRecordDao, RedisService, PointQueryNacosConfig
+- **核心方法**：
+  - `queryPointAccount2B` — 查询后台积分账户信息（含缓存）
+  - `queryPointAccountFromCache` — 从 Redis 缓存查询账户
+  - `queryPointAccountExpire` — 查询积分过期信息
+  - `buildBackendPointAccountVoNew` — 构建账户 VO（含过期积分计算）
+  - `setPointAccountCache` — 写入账户缓存（CAS + 穿透防护）
+```
+
+**medium 复杂度类**（line_count 50-200，非纯数据类）：2 行紧凑描述：
+
+```markdown
+### 2.5 PointAccountConvert
+`src/.../convert/PointAccountConvert.java` — class(@Component), ~120行 — 积分账户 VO 构建转换器，核心方法：initBuild, buildBackendPointAccountVO, buildBackendPointAccountVoNew
+```
+
+**low 复杂度类**（纯 POJO/DTO/Enum/Config/简单 Util，line_count < 50）：1 行行内注释：
+
+```markdown
+PointAccount.java # Domain实体，积分账户，18字段，@TableName("point_account")
+PointAccountStatusEnum.java # 枚举，账户状态（ENABLE=1/DISABLE=2/BINDCANCEL=3）
+RedisKeyConstants.java # 常量类，8个Redis Key常量
+```
+
+**必须包含**（所有级别）：文件路径、类型（class/interface/enum/abstract）、职责（一句话）。**high 级别额外必须**：关键注解、代码行数、依赖注入的组件、核心 public 方法列表。**有则写**（仅 high/medium）：实现的接口、继承的父类。
+
+**分级判定规则**：
+- 50+ 文件的模块：low 复杂度类必须用行内注释格式，否则必然超 25KB 上限
+- 骨架 JSON 中 complexity=high 的类 → high 格式
+- 骨架 JSON 中 total_lines > 200 的类 → high 格式
+- Controller/Service/Biz/Consumer 类 → 至少 medium 格式
+- Domain/Entity/DTO/VO/Param/Enum/Constant/Config 类 → low 格式（除非 line_count > 200）
+- Mapper 接口 → low 格式（方法列表在 data-models.md 中覆盖）
+
+### 5.7.4 内容深度基准
+
+- 一个 15 个 Java 文件的模块，source-tree-analysis.md 应在 12-18KB
+- 一个 50+ 文件的模块，应在 20-30KB
+- 如果生成的文档 < 8KB，几乎一定是内容不足
+
+## 5.8 index.md 质量标准
+
+### 5.8.1 必须包含的章节
+
+| # | 章节 | 内容 | 必需 |
+|---|------|------|------|
+| 1 | 基本信息 | 表格：模块名、artifactId、groupId、版本、模块类型、上下文路径、端口、启动入口、基础包路径、JDK 版本、数据库、缓存、Web 容器、JVM 配置（生产） | ✅ |
+| 2 | 模块定位 | 一段话说明模块在系统中的角色、架构模式、核心能力 | ✅ |
+| 3 | 核心能力 | 编号列表，列出模块提供的主要功能（5-10 项） | ✅ |
+| 4 | 技术栈 | 表格：技术名、版本、用途 | ✅ |
+| 5 | 数据源 | 列出所有数据源（数据库、缓存、消息队列等）及其用途 | ✅ |
+| 6 | 接口总览 | 分外部接口和内部接口两个子表，每个接口一行：序号、HTTP 方法、路径、说明、Sentinel 资源名、状态（正常/已废弃）。数据从骨架 JSON 的 Controller 类和 `.source-cache` 中的 Controller 源码直接提取，不依赖 api-contracts.md | ✅（有 API 时） |
+| 7 | 枚举速查 | 关键业务枚举的值表（如币种枚举、操作类型枚举） | 有则写 |
+| 8 | 缓存策略概览 | 表格：缓存类型、Redis 数据结构、Key 模式、TTL、特殊机制 | 有则写（有 Redis 时） |
+| 9 | 核心业务流程速览 | 表格：流程名、关键路径一句话描述（从入口到最终状态的核心步骤） | ✅ |
+| 10 | 文档导航 | 表格：文档名（带链接）、说明 | ✅ |
+
+### 5.8.2 基本信息表格式
+
+```markdown
+| 属性 | 值 |
+|------|-----|
+| 模块名称 | point-query |
+| artifactId | point-query |
+| groupId | com.example.app |
+| 当前版本 | 1.3.0 |
+| 模块类型 | 只读查询服务（CQRS 读侧） |
+| 上下文路径 | `/points/query` |
+| 服务端口 | 8080 |
+| 启动入口 | `com.example.app.SpringBootStarter` |
+| 基础包路径 | `com.example.app` |
+| JDK 版本 | 8 |
+| 数据库 | TiDB（兼容 MySQL 协议） |
+| 缓存 | Redis（Lettuce 5.3.6 客户端） |
+| Web 容器 | Undertow（16 IO 线程，256 工作线程） |
+| JVM 配置（生产） | -Xmx12g -Xms12g -Xmn5g -XX:+UseG1GC |
+```
+
+这些信息从 pom.xml、application.yaml、bootstrap.yaml、Dockerfile 中提取。以上为 point-query 的示例值，实际必须从源码提取替换。如果某项信息在源码中找不到，标注"继承自父 POM"或省略该行，禁止编造。
+
+### 5.8.3 接口总览表格式
+
+```markdown
+### 外部接口（QueryController）
+
+| 序号 | HTTP 方法 | 路径 | 说明 | Sentinel 资源名 | 状态 |
+|------|-----------|------|------|----------------|------|
+| 1 | GET | `/account/{customerId}` | 查询积分账户信息 | PointsQueryAccount | 正常 |
+| 2 | GET | `/records/{customerId}` | 查询积分记录 | PointsQueryRecords | 已废弃 |
+```
+
+接口信息从 Controller 源码的 `@RequestMapping`/`@GetMapping`/`@PostMapping` 和 `@SentinelResource` 注解提取。Feign 接口定义在外部 JAR 时，从 `.skeleton-deps/` 骨架或 Controller 实现代码推断。
+
+### 5.8.4 文档导航格式
+
+```markdown
+| 文档 | 说明 |
+|------|------|
+| [源码树分析](./source-tree-analysis.md) | 完整源码树，每个文件一行说明 |
+| [架构设计](./architecture.md) | 分层架构、缓存策略详解、配置项、部署参数 |
+| [接口契约](./api-contracts.md) | 全部接口的请求参数、响应结构、错误码 |
+| [业务逻辑详解](./business-logic.md) | 每个方法的完整业务逻辑、分支、缓存策略 |
+| [数据模型](./data-models.md) | Domain/VO/Param/Enum 的完整字段定义 |
+| [缓存设计](./caching.md) | 缓存 Key 设计、TTL、读写策略 |
+```
+
+只链接实际存在的文档文件，禁止链接未生成的文档。
+
+### 5.8.5 内容深度基准
+
+- index.md 是模块的"首页"，目标是让读者在 2 分钟内了解模块全貌
+- 一个有 9 个接口 + 4 种缓存策略的服务模块，index.md 应在 4-6KB
+- 如果生成的文档 < 3KB，几乎一定是内容不足
+
+## 5.9 caching.md 质量标准（可选文档）
+
+### 5.9.1 内容组织
+
+按缓存 Key/Cache 逐个描述，文档开头有总览表。
+
+**必须包含的章节**：
+
+| # | 章节 | 内容 | 必需 |
+|---|------|------|------|
+| 1 | 总览 | 表格：序号、Key Pattern/Cache Name、数据类型、来源类 | ✅ |
+| 2 | 逐 Key/Cache 详解 | 每个缓存项独立小节（见 5.9.2） | ✅ |
+| 3 | 缓存策略说明 | 按缓存模式分组，说明读写策略、一致性保证、穿透防护 | ✅ |
+
+### 5.9.2 逐 Key/Cache 详解格式
+
+每个缓存项必须包含：
+
+- **Key Pattern / Cache Name**：完整拼接规则（含常量名引用和变量占位符）
+- **常量引用**：对应的常量名（如 `RedisKeyConstants.POINT_ACCOUNT_BASE_INFO`）
+- **拼接规则**：代码级拼接表达式
+- **数据类型/结构**：String / Hash / ZSet / List / Set / Object / Map 等
+- **TTL/过期策略**：具体值 + 来源（硬编码 / 配置项名及默认值）
+- **Value 格式**：序列化格式（JSON / Protobuf / JDK / 自定义），含分隔符说明
+- **写入方式**：普通 SET / CAS / HMSET / ZADD / put / computeIfAbsent 等
+- **使用场景**：哪些类的哪些方法读取、哪些方法写入
+- **防穿透/击穿**（如有）：空值写入策略、判断逻辑、布隆过滤器
+
+### 5.9.3 内容深度基准
+
+- 一个有 4 种缓存策略的模块，caching.md 应在 4-8KB
+- 如果生成的文档 < 3KB，几乎一定是内容不足
+
+**RAG 闭环检查清单**（生成后自检）：
+- 每个缓存项的数据类型是否标注？缺失 → 检索到该 key 时不知道用什么命令/API 操作
+- 每个缓存项的 TTL 是否有具体值或"无过期"？`—` 不是有效值 → 必须从源码确认是永不过期还是遗漏
+- 原子操作/Lua 脚本是否有伪代码级逻辑（比较什么、成功做什么、失败返回什么）？一句话概述不够 → 检索到 CAS 操作时无法理解成功/失败条件
+- Value 格式是否说明了序列化方式和分隔符？缺失 → 检索到该 key 时不知道怎么解析值
+
+## 5.10 messaging.md 质量标准（可选文档）
+
+messaging.md 是消息驱动模块的核心文档，其质量直接决定 RAG 检索对消息队列相关问题的命中率。禁止只写消费者/生产者列表就结束。
+
+### 5.10.1 必须包含的章节
+
+| # | 章节 | 内容 | 必需 |
+|---|------|------|------|
+| 1 | 消息中间件配置总览 | 集群/实例说明、Producer 配置（acks/retries/batch-size）、Consumer 配置（group-id/auto-offset-reset/enable-auto-commit）、自定义 Consumer 配置组 | ✅ |
+| 2 | Topic/Queue 清单 | 表格：Topic/Queue 配置 Key、默认名称、生产者类、消费者类、消费者组、并发数 | ✅ |
+| 3 | 消费者详细说明 | 每个消费者独立小节（见 5.10.2） | ✅ |
+| 4 | 生产者详细说明 | 每个生产者独立小节（见 5.10.3） | ✅ |
+| 5 | 事件流转全景图 | ASCII 图展示所有 Topic/Queue 的生产→消费→下游的完整链路 | ✅ |
+
+### 5.10.2 消费者详细说明格式
+
+每个消费者必须包含以下内容（不是 5-10 行概述就结束）：
+
+- **Topic/Queue**：配置项名 + 默认值
+- **GroupId/Subscription**：配置项名 + 默认值（标注是否独立 group）
+- **ContainerFactory/Listener 容器**：使用的容器名称
+- **Concurrency**：并发数
+- **内部线程池**（如有）：线程数、队列类型、队列容量
+- **消息体**：完整 JSON 示例（含所有字段）
+- **消息 Key / Header / Properties**：Key 的含义、Header/Properties 中的字段
+- **完整消费逻辑**：编号步骤列表，从接收消息到处理完成的每一步，包含：
+  - ACK 时机（先 ACK 再处理 / 处理完再 ACK）
+  - 幂等校验逻辑（如状态检查）
+  - 核心业务调用链
+  - 异常处理策略（catch 后记日志不抛出 / 抛出触发重试 / 走补偿）
+- **自动启动**：是否默认启动，启停控制方式
+- **错误处理**：消费失败后的行为（重试/死信/跳过/补偿任务）
+
+⚠️ 特别关注"先 ACK 再异步处理"这类设计决策，必须明确标注其消息丢失风险。
+
+### 5.10.3 生产者详细说明格式
+
+每个生产者必须包含：
+
+- **生产位置**：哪个类的哪个方法发送
+- **发送方式**：同步 / 异步 / 异步带 Header
+- **消息 Key**：Key 的生成规则
+- **消息 Header/Properties**：Header 中的字段（如 TRACE_ID、EXT_INFO）
+- **消息体**：消息体类名 + 关键字段说明
+- **目标集群/实例**：使用哪套消息中间件实例
+
+### 5.10.4 算法详解（有复杂消费逻辑时必须）
+
+当消费者内部有复杂算法（如溯源算法、聚合算法）时，必须独立小节详细说明：
+- 算法步骤（编号列表）
+- 新旧算法对比（如有切换开关）
+- 边界条件处理（如"最后一条记录可以扣成负数"）
+
+### 5.10.5 内容深度基准
+
+- 一个有 7 个消费者 + 8 个生产者的模块，messaging.md 应在 15-25KB
+- 如果生成的文档 < 8KB，几乎一定是内容不足（只写了列表没写消费逻辑）
+- 参考标准：每个消费者的详细说明至少 30-50 行（含消息体示例和完整消费逻辑）
+
+## 5.11 外部依赖源码处理
+
+当 VO、Param、DTO、API 接口定义在外部 JAR 依赖中（不在本模块源码中）时：
+
+1. **自动提取**（配置了 `maven_repo` 时）：
+   kb-init 自动从 pom.xml 发现内部依赖，通过 `resolve_jar_sources.py` 下载并反编译。
+   依赖骨架存放在 `{module_dir}/.skeleton-deps/{artifactId}.json`。
+   文档中使用完整类定义，标注 `来源: {artifactId}:{version}`。
+
+2. **降级标注**（未配置 `maven_repo` 或下载失败时）：
+   从使用代码推断字段，标注 `⚠️ 字段从使用代码推断，完整定义在 {artifact}:{version} JAR 中`。