create-yss-spec 3.2.0 → 3.3.1

package/template/.claude/skills/yss-implementation-contract-compiler/references/compiler-contract.yaml

@@ -138,8 +138,33 @@ context_plan:
   context_stop_rule: minimal-sufficient-evidence
   missing_context_action: [blocked, reroute]
 
+project_scaffold_contract_schema:
+  schema_version: 4
+  schema_ref: docs/process/schemas/project-scaffold-contract.schema.json
+  identity: project-engineering-baseline
+  discriminant: delivery_role
+  delivery_roles:
+    backend:
+      scaffold_kinds: [backend-ddd, backend-layered-mvc]
+      generators: [yss-ddd-scaffold-generator, yss-layered-mvc-scaffold-generator]
+      requires: [scaffold_request_id, architecture_family, decision_ref, decision_id, decision_digest, project_name, base_package, maven_coordinates, profiles, module_profile]
+    frontend:
+      scaffold_kinds: [frontend-yss-vue3]
+      generators: [yss-frontend-scaffold-generator]
+      requires: [frontend, repository_scope, init_git]
+      openapi_modes: [frozen, not-applicable]
+  common_required: [contract_id, contract_version, status, persisted_ref, current_version, delivery_role, scaffold_kind, generator_skill, implementation_repository, target_output_dir, repository_scope, init_git, allowed_write_paths, expected_evidence_files, verification_commands, approval, generation_policy]
+  approved_by: yss-product-lifecycle
+  generation_mode: controlled-generation
+  target_policy: nonexistent-or-empty
+  force_overwrite: forbidden
+  compatibility:
+    backend_schema_v3: read-only-and-complete-approved-generation
+    frontend_before_v4: unsupported
+
 scaffold_contract_schema:
   schema_version: 3
+  compatibility_status: legacy-backend-read-only
   identity: service-engineering-baseline
   compiled_by: yss-implementation-contract-compiler
   approved_by: yss-product-lifecycle

package/template/.claude/skills/yss-layered-mvc-scaffold-generator/SKILL.md

@@ -11,7 +11,7 @@ description: 用于在生命周期已批准的脚手架合同下生成通用 YSS
 
 - backend `scaffold_status=required`，目标目录已确认且不存在。
 - `scaffold-architecture-decisions.yaml` 中对应项目已达到 `lifecycle-approved`，确认架构为 `layered-mvc`。
-- `yss-implementation-contract-compiler` 已编译 scaffold contract schema v3，生命周期已批准并持久化。
+- `yss-implementation-contract-compiler` 已编译统一 Project Scaffold Contract schema v4；已批准且当前的后端 schema v3 可完成兼容生成。合同须由生命周期批准并持久化。
 - 合同中的 `decision_id`、文件 digest、Profile、能力闭包、写路径和验证命令仍为当前版本。
 
 任一条件缺失时返回 `blocked`。本生成器无交互、无默认回退；用户选择由 `yss-product-lifecycle` 在 `work-unit.technical-analysis` 的工程基线内完成。
@@ -55,7 +55,7 @@ node scripts/generate_and_verify_scaffold.mjs \
 
 ## 硬约束
 
-- 只接受 scaffold contract schema v3 和 Manifest schema v3；历史 v2 只读兼容，不用于新生成。
+- 接受统一 schema v4，兼容已批准后端 schema v3；验证器接受对应 Manifest v3/v4。历史 v2 只读兼容，不用于新生成。
 - `architecture_family` 必须为 `layered-mvc`，`generator_skill` 必须为本 skill。
 - 目标存在、`--force`、旧项目迁移、模板升级均为 `unsupported`。
 - Harness 内只允许以 `apps/backend/` 为输出父容器；外部实现仓库使用已登记真实路径。

package/template/.claude/skills/yss-layered-mvc-scaffold-generator/scripts/generate_scaffold.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-/** 依据生命周期批准的 schema v3 合同生成纯机械 YSS 分层 MVC 后端骨架。 */
+/** 依据生命周期批准的兼容 schema v3 或统一 schema v4 合同生成纯机械 YSS 分层 MVC 后端骨架。 */
 import { assertScaffoldUserDecision } from "../../../../scripts/lib/user-decision.mjs";
 import { createHash } from "node:crypto";
 import { chmod, cp, lstat, mkdir, mkdtemp, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
@@ -10,6 +10,7 @@ import { parseDocument } from "../../../../scripts/vendor/yaml.mjs";
 import { findGitRoot, gitSubmoduleScaffoldViolation, overlayMountViolation } from "../../../../scripts/lib/repository-scope-policy.mjs";
 import { assertLocalDatabaseProfile, localDatabaseConfiguration, scaffoldArchitectureIdentity } from "../../../../scripts/lib/scaffold-local-database.mjs";
 import { validateArchitectureIdentity } from "../../../../scripts/lib/backend-architecture.mjs";
+import { validateJsonSchema } from "../../../../scripts/lib/json-schema.mjs";
 
 const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
 const SKILL_ROOT = path.resolve(SCRIPT_DIR, "..");
@@ -151,11 +152,13 @@ async function validateContract(options, skillId, architectureProfile) {
   const contractText = await readFile(contractFile, "utf8").catch(() => fail(`脚手架合同不可读取: ${contractFile}`));
   let contract;
   try { contract = JSON.parse(contractText); } catch { fail("脚手架合同必须是 JSON 对象"); }
-  if (contract.schema_version !== 3) fail(`unsupported: 新生成只接受 scaffold contract schema v3，收到 v${contract.schema_version}`);
+  if (![3, 4].includes(contract.schema_version)) fail(`unsupported: 只接受兼容 scaffold contract v3 或统一 v4，收到 v${contract.schema_version}`);
+  if (contract.schema_version === 4 && (contract.kind !== "project-scaffold-contract" || contract.delivery_role !== "backend" || contract.scaffold_kind !== "backend-layered-mvc")) fail("schema v4 合同必须绑定 backend/backend-layered-mvc");
+  if (contract.schema_version === 4) validateJsonSchema(contract, path.join(REPOSITORY_ROOT, "docs/process/schemas/project-scaffold-contract.schema.json"), { label: "Project Scaffold Contract v4" });
   const required = ["contract_id", "contract_version", "scaffold_request_id", "status", "compiler_draft_ref", "lifecycle_approval_ref", "persisted_ref", "current_version", "implementation_repository", "backend_repository", "scaffold_status", "project_name", "target_output_dir", "base_package", "architecture_family", "generator_skill", "decision_ref", "decision_id", "decision_digest", "maven_coordinates", "profiles", "module_profile", "allowed_write_paths", "expected_evidence_files", "verification_commands", "approval", "work_unit", "generation_policy"];
   const missing = required.filter((field) => !isPresent(contract[field]));
   if (missing.length) fail(`脚手架合同缺少字段: ${missing.join(", ")}`);
-  if (contract.status !== "approved" || contract.current_version !== contract.contract_version) fail("脚手架合同必须已批准且为当前版本");
+  if (contract.status !== "approved" || (contract.current_version !== contract.contract_version && !(contract.schema_version === 4 && contract.current_version === true))) fail("脚手架合同必须已批准且为当前版本");
   if (contract.contract_id !== options.contractId || contract.contract_version !== options.contractVersion || contract.compiler_draft_ref !== options.compilerDraftRef || contract.lifecycle_approval_ref !== options.approvalRef || contract.persisted_ref !== options.persistedRef) fail("命令行合同元数据与批准合同不一致");
   if (contract.scaffold_status !== "required" || contract.architecture_family !== "layered-mvc" || contract.generator_skill !== skillId) fail("合同必须绑定 layered-mvc 与本生成器");
   if (contract.project_name !== options.projectName || contract.base_package !== options.basePackage || path.resolve(contract.target_output_dir) !== path.resolve(options.outputDir)) fail("项目身份或输出目录与合同不一致");
@@ -244,14 +247,14 @@ export async function generate(options, { skillId = SKILL_ID, architectureProfil
     await cp(wrapper, projectRoot, { recursive: true });
     await chmod(path.join(projectRoot, "mvnw"), 0o755);
     if (finalize) await finalize({ projectRoot, contract, architectureIdentity: scaffoldArchitectureIdentity(contract, sha256(contractText)) });
-    await put(projectRoot, "README.md", `# ${options.projectName}\n\n该工程由 ${skillId} 根据批准的 schema v3 合同生成。模块：${modules.join("、")}。不包含业务 API、SQL 或生产数据库绑定。\n\n本地运行需同时显式启用 Maven -Pscaffold-local 和 Spring scaffold-local Profile；测试独立使用 H2。生产数据库须由后续已批准存储工作单元接入。`);
+    await put(projectRoot, "README.md", `# ${options.projectName}\n\n该工程由 ${skillId} 根据批准的 schema v${contract.schema_version} 合同生成。模块：${modules.join("、")}。不包含业务 API、SQL 或生产数据库绑定。\n\n本地运行需同时显式启用 Maven -Pscaffold-local 和 Spring scaffold-local Profile；测试独立使用 H2。生产数据库须由后续已批准存储工作单元接入。`);
     const generatedFiles = [];
     for (const entry of await fileEntries(projectRoot, new Set([".yss/scaffold-generation.json"]))) generatedFiles.push({ path: entry.relative, owner: "generator", sha256: rawSha256(await readFile(entry.target)) });
     const architectureRuleset = `${serverRoot}/src/test/java/${packagePath}/architecture/LayeredMvcArchitectureTest.java`;
     const downstream = {};
     for (const skill of ["yss-application", "yss-repository", "yss-mybatis", "yss-web-controller", "yss-dto", "yss-exception", "yss-validation", "mapstruct", "lombok", "alibaba-java-code-style"]) downstream[skill] = (await treeDigest(path.join(REPOSITORY_ROOT, ".agents/skills", skill))).replace(/^sha256:/, "");
     const manifest = {
-      schema_version: 3,
+      schema_version: contract.schema_version,
       kind: architectureProfile === "mvc-data-analysis-v1" ? "service-project-initialization" : "backend-scaffold",
       architecture_profile: contract.architecture_profile,
       architecture_identity: scaffoldArchitectureIdentity(contract, sha256(contractText)),

package/template/.claude/skills/yss-layered-mvc-scaffold-generator/scripts/scaffold-generator.test.mjs

@@ -18,7 +18,7 @@ const capabilityModules = {
   combined: { capabilities: ["external-integration", "feign-client"], modules: ["server", "service", "repository", "adapter", "client", "feign-client"] }
 };
 
-async function fixture(t, { profile = capabilityModules.basic, architectureProfile = "layered-mvc-service", skillId = "yss-layered-mvc-scaffold-generator" } = {}) {
+async function fixture(t, { profile = capabilityModules.basic, architectureProfile = "layered-mvc-service", skillId = "yss-layered-mvc-scaffold-generator", schemaVersion = 3 } = {}) {
   const root = await mkdtemp(path.join(os.tmpdir(), "yss-layered-mvc-"));
   t.after(() => rm(root, { recursive: true, force: true }));
   const output = path.join(root, "backend");
@@ -30,7 +30,12 @@ async function fixture(t, { profile = capabilityModules.basic, architectureProfi
   const decisionFile = path.join(root, "scaffold-architecture-decisions.yaml");
   await writeFile(decisionFile, decisionText);
   const contract = {
-    schema_version: 3,
+    schema_version: schemaVersion,
+    kind: "project-scaffold-contract",
+    delivery_role: "backend",
+    scaffold_kind: "backend-layered-mvc",
+    repository_scope: "external-repository",
+    init_git: false,
     contract_id: "scaffold.demo-service.v1",
     contract_version: 1,
     scaffold_request_id: "request.demo-service",
@@ -97,6 +102,16 @@ test("旧数据库和 Mock 参数在写入前被拒绝", async (t) => {
   }
 });
 
+test("统一 Project Scaffold Contract v4 可生成 Layered MVC 后端并保留 v4 Manifest", async (t) => {
+  const data = await fixture(t, { schemaVersion: 4 });
+  data.contract.current_version = true;
+  await writeFile(data.contractFile, JSON.stringify(data.contract));
+  const result = spawnSync(process.execPath, [script, ...data.args], { encoding: "utf8" });
+  assert.equal(result.status, 0, result.stderr);
+  const manifest = JSON.parse(await readFile(path.join(data.project, ".yss/scaffold-generation.json"), "utf8"));
+  assert.equal(manifest.schema_version, 4);
+});
+
 test("可选离线 Maven 可行性检查（不替代受控仓库验收）", { skip: process.env.YSS_BACKEND_OFFLINE_PROBE !== "1" }, async (t) => {
   const data = await fixture(t);
   const generated = spawnSync(process.execPath, [script, ...data.args], { encoding: "utf8" });

package/template/.claude/skills/yss-mybatis/SKILL.md

@@ -1,77 +1,53 @@
 ---
 name: yss-mybatis
-description: 用于 YSS MyBatis 与 MyBatis-Plus 持久层规范、配置和排障。当用户提到 BaseRepository、BasePlusRepository、PageQuery 自动分页、多数据源、批量插入或 MyBatis 配置异常时调用。
+description: 用于 YSS MyBatis / MyBatis-Plus 组件能力核验、接入决策和排障；涉及 Mapper/Repository 基类、分页、批量 SQL、扫描配置或数据源能力时使用，不负责生成持久层结构。
 ---
 
 # yss-mybatis
 
-用于处理 `yss-component-persistence` 相关的持久层规范、接入和问题定位。
+本 Skill 只维护 `yss-component-persistence` 的组件能力、选择条件和排障顺序。PO、Repository、Convertor、Gateway/Query Adapter 的结构与生成边界由 `yss-repository` 负责。
 
-## 何时使用
+## 入口与前置
 
-- 用户要定义新的 Repository。
-- 用户在 MyBatis 与 MyBatis-Plus 两种模式间排查问题。
-- 用户提到自动分页、`PageQuery`、批量插入、多数据源。
-- 用户反馈 Mapper 扫描、分页不生效、批量性能差。
+1. 读取批准且当前的 `architecture_identity`、`persistence_profile`、实现仓登记和 Slice Implementation Contract。没有合同的故障诊断可以继续，但不得据此生成或改变架构。
+2. 精确类名、方法签名、配置 key、默认值或启用条件必须先读 [source-index.md](references/source-index.md)，并按 `yss-skill-source-index-refresh/references/source-location.md` 核验组件 tree 与组件子树 clean 状态。
+3. 组件 tree 不匹配或 persistence 子树为 dirty 时，路径提示只能用于定位；精确实现或审查结论返回 `stale` / `missing_evidence`，刷新索引后再继续。
+4. 新 DDD / MVC scaffold 只支持批准的 `mybatis-plus` Profile。普通 MyBatis 仅用于既有工程维护、兼容与排障；新增支持必须有独立 Profile 和 fixture，不自动猜测或混用。
 
-## 工作方式
+## 稳定决策规则
 
-1. 先读取批准的 `persistence_profile` 和 `architecture_identity`。新 DDD / MVC scaffold 都使用 `mybatis-plus`；普通 MyBatis 必须有独立 fixture 和批准 Profile，禁止自动猜测或混用。模块所有权按 `docs/agents/backend-architecture-profiles.md`；H2 仅用于本地/测试，生产数据库另行批准接入。
-2. 涉及真实类名、配置项、模块依赖或排障时，先读 `references/source-index.md`，再定位源码或文档。
-3. 先复用现有基类与配置，不手搓新的基础设施。
-4. 涉及分页时，先验证 `PageQuery` 传递链路和拦截器是否生效。
+- 基类、Mapper 注解、XML 位置和扫描范围以批准 Profile、当前工程基线及当前组件源码共同决定；不得在既有体系外再造 Mapper 抽象。
+- 一条查询 seam 只能有一个分页责任模型。核对实际插件/切面开关、拦截范围、参数绑定条件和返回 total 的责任，不以“依赖已引入”代替行为验证。
+- 批量写入必须证明是组件当前支持的 SQL 级批量能力，并验证分批大小、字段填充、主键和数据库方言；循环单条写入不能冒充批量 SQL。
+- 多数据源实例创建不等于动态路由、线程上下文切换或事务传播。先做 capability check；组件未提供的路由能力必须由批准的上层适配承担。
+- Mapper/XML、逻辑删除、审计字段、主键策略、动态排序/分组白名单和参数绑定必须与数据合同一致；任何 SQL/DDL/索引新影响返回 `new_impacts`。
+- 事务边界归批准的 Application 用例或 MVC service/core；Repository 不临时声明新的业务事务。
 
-## 源码索引
+## 任务分流
 
-- 源码位置不要假设固定目录；先按 `yss-skill-source-index-refresh/references/source-location.md` 定位。
-- 当前技能索引：`references/source-index.md`
-- 重点源码入口通常包括 `BaseRepository`、`BasePlusRepository`、`EntityQueryAspect`、`PageQueryEntityConfigration`、`MybatisBaseConfiguration`、`MybatisPlusConfiguration`、`MultiDataSourceConfiguration`、`MultiDataSourceHolder`。
-
-当组件源码变化后，用 `yss-skill-source-index-refresh` 刷新索引；刷新或读取前先按源码定位策略确认真实位置。
-
-## 实施建议
-
-- 通用模式优先继承 `BaseRepository`
-- MP 模式优先继承项目既有的 `BasePlusRepository`
-- 批量导入优先使用真正的 SQL 级批量方法，不要默认循环单条插入
-- 多数据源问题优先先看配置和扫描范围，再怀疑业务代码
-- DDD 分页经 Application Query Port 进入 Infrastructure；MVC 经 service/core 进入 Repository。不把 `PageQuery` 带入 Domain Gateway，也不得在 Repository 内临时发明分页参数。
-- 生成或重构持久层时，先看当前模块已有 Repository/Mapper 命名、包路径、XML 位置。
-
-## 检查清单
-
-- Mapper 扫描路径是否正确。
-- XML 路径和接口是否对齐。
-- `PageQuery` 是否真的出现在被拦截的方法参数里。
-- 批量方法是否用了项目推荐实现。
-- 多数据源名称和主从配置是否一致。
-- MyBatis 与 MyBatis-Plus 的基类、分页插件和扫描配置是否混用。
-- 数据源切换是否在事务边界之前完成。
+| 请求 | 本 Skill 动作 | 后续路由 |
+|---|---|---|
+| 组件接入、基类选择、配置核验 | 读取当前 Profile 和源码能力矩阵，给出来源可追踪的选择 | 需要结构实现时转 `yss-repository` |
+| 分页、批量、扫描、XML、数据源故障 | 按下列顺序定位并保留实际证据 | 发现合同或数据影响时返回编译器 |
+| 生成 PO / Repository / Convertor / GatewayImpl | 不生成 | `yss-repository` |
+| 普通 MyBatis 新工程生成 | `unsupported` | 新 Profile / fixture 获批后再进入 |
 
 ## 排障顺序
 
-1. 确认依赖模块：starter、mapper、plus starter、persistence common。
-2. 确认 Mapper/Repository 扫描范围。
-3. 确认分页参数、分页切面或插件是否参与调用。
-4. 确认 XML、方法签名、resultMap/字段映射是否一致。
-5. 确认多数据源配置和当前线程数据源上下文。
-6. 最后再排查 SQL 本身和数据库执行计划。
-
-## 修改约束
-
-- 不要同时引入两套分页机制而不说明谁生效。
-- 不要在已有 Repository 基类体系之外再造一套 Mapper 抽象。
-- 若用户只是要生成持久层骨架，优先衔接 `yss-repository`。
+1. 依赖与 Profile：starter、组件版本、MyBatis/MyBatis-Plus 模式是否与合同一致。
+2. 装配与开关：自动配置、条件属性、Mapper 扫描和 XML location 是否真实生效。
+3. 调用 seam：代理是否命中、分页参数位置/类型、分页插件链和 total 回填责任。
+4. 映射：接口签名、XML namespace、resultMap、字段、逻辑删除和主键策略。
+5. 批量：是否调用当前公开批量入口、分批与方言是否匹配、是否退化为循环单条。
+6. 数据源：先确认组件只提供了什么，再检查上层路由与事务进入顺序；不得假设存在当前线程数据源上下文。
+7. 最后检查 SQL、绑定参数、数据库方言与执行计划。
 
-## 按需读取
+## Review 输入
 
-- 源码索引：`references/source-index.md`
-- 基础 Repository：`assets/BaseRepository.java`
-- 分页切面：`assets/EntityQueryAspect.java`
-- MyBatis 基础配置：`assets/MybatisBaseConfiguration.java`
+仅审查本体项目和合同/实现仓登记的后端研发项目。命中 Mapper、Repository、SQL、分页、批量、扫描配置或数据源能力时，`code-review` Standards 轴必须读取本 Skill 和当前 source index；无持久化影响时显式记录带原因的 `not-applicable`。
 
-## 阶段 7 合同
+## 结果与验证
 
-- 仅在数据架构、Repository 策略和批准合同明确时使用。
-- Mapper/XML 骨架可受控生成；查询语义、分页、数据源切换和事务行为使用 `behavior-tdd`。
-- 按统一 `YSS Skill Execution Result` 返回 Mapper/XML/配置、集成测试、实际 `./mvnw ...` 结果和新增 SQL/DDL/索引影响。
+- 行为变更使用 `behavior-tdd`；纯 Mapper/XML 骨架仅在批准合同明确为 `controlled-generation` 时允许。
+- 使用项目根 `./mvnw ...` 记录实际命令、退出码和时间；H2 只证明本地/测试行为，不证明生产方言。
+- 按 [YSS Skill Execution Result v2](../yss-implementation-contract-compiler/references/yss-skill-execution-result.md) 返回证据、`seam_deferred`、`deviations`、`new_impacts`、`drift` 和 `violation`。

package/template/.claude/skills/yss-mybatis/agents/openai.yaml

@@ -1,5 +1,5 @@
 version: 1
 interface:
   display_name: "YSS MyBatis"
-  short_description: "MyBatis 持久层、多数据源、分页与查询处理规范"
-  default_prompt: "Use $yss-mybatis to implement or debug YSS MyBatis repositories, pagination, and multi-datasource access."
+  short_description: "MyBatis 组件能力、配置、分页、批量与数据源排障"
+  default_prompt: "Use $yss-mybatis to verify or troubleshoot current YSS MyBatis capabilities and configuration; route persistence structure work to $yss-repository."

package/template/.claude/skills/yss-mybatis/references/source-index.md

@@ -1,13 +1,14 @@
 # yss-mybatis Source Index
 
-Generated: 2026-08-17T12:03:37.436Z
-Source commit: `38b556a5081e6c66c0c538cbc1ef839b19996ed3`
-Source worktree: `dirty`
+Generated: 2026-09-08T17:00:36.490Z
+Source commit: `2ccbd3f3f145f9bf74b217a2c211e4bf7a8a2074`
+Component worktree: `clean`
+Component tree `yss-microservice-components/yss-component-persistence`: `274d9f4c948d0bd8a58e7f6fb50685d6de740f7b`
 Indexed source root: resolved at refresh time; set `YSS_SOURCE_ROOT` to reproduce or refresh.
 
 This file is generated by `yss-skill-source-index-refresh/scripts/refresh-yss-skill-index.mjs`. Do not hand-edit generated sections.
 
-Paths below are source path hints captured at refresh time. If they do not exist in the current workspace, locate sources using `YSS_SOURCE_ROOT`, CodeGraph, package/class names, Maven artifact names, or repository search before assuming the source is unavailable.
+Paths are relocatable source hints. Exact guidance requires a matching component tree and a clean indexed component subtree; the repository commit is trace metadata and may differ when unrelated components change.
 
 ## Component Path Hints
 
@@ -19,6 +20,8 @@ Paths below are source path hints captured at refresh time. If they do not exist
 - `yss-microservice-components/yss-component-persistence/README.md`
 - `yss-microservice-components/yss-component-persistence/TECHNICAL_DESIGN.md`
 
+Component documentation is a discovery aid. For API signatures, conditions and defaults, prefer the indexed source facts below when documentation differs.
+
 ## Maven Modules
 
 - `yss-microservice-components/yss-component-persistence`
@@ -27,67 +30,84 @@ Paths below are source path hints captured at refresh time. If they do not exist
 - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter`
 - `yss-microservice-components/yss-component-persistence/yss-component-persistence-common`
 
-## Key Java Entry Points
-
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/config/defaults/UserConfig.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/config/spring/SpringEnvAutoConfiguration.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/mapper/BaseMapper.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/mapper/Mapper.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/mapper/base/EntityMapper.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/mapper/config/MapperUserConfig.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/mapper/example/ExampleMapper.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/mapper/fn/FnMapper.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/mapper/list/ListMapper.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/mapper/logical/LogicalColumn.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/mapper/logical/LogicalMapper.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/mapper/logical/LogicalProvider.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/EntityColumnFactory.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/EntityFactory.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/EntityInfoMapper.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/EntityTableFactory.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/SqlCache.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/SqlScript.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/SqlScriptWrapper.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/SqlSourceCustomize.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/SqlWrapper.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/config/ProviderUserConfig.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/defaults/AnnotationSqlScriptWrapper.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/defaults/AnnotationSqlWrapper.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/defaults/CachingEntityTableFactory.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/defaults/DefaultEntityColumnFactory.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/defaults/DefaultEntityColumnFactoryChain.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/defaults/DefaultEntityTableFactory.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/defaults/DefaultEntityTableFactoryChain.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/defaults/GenericTypeResolver.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/jpa/JpaEntityColumnFactory.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/jpa/JpaEntityTableFactory.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/jpa/SimpleTypeUtil.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/keysql/GenId.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/keysql/GenIdKeyGenerator.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/keysql/GenIdSqlSource.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/keysql/KeySqlMsCustomize.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/keysql/KeySqlSqlSourceCustomize.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/MybatisPlusConfiguration.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/MybatisPlusGlobalProperties.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/PageInterceptorProperties.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/YssMybatisMapperProperties.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/BatchSqlInjector.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/MapperConfiguration.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/MybatisPlusConfig.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/support/BasePlusRepository.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/LogbackImpl.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/MybatisBaseConfiguration.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/aop/EntityQueryAspect.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/config/PageQueryEntityConfigration.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/support/BaseRepository.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-persistence-common/src/main/java/com/yss/cloud/mybatis/MultiDataSourceConfiguration.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-persistence-common/src/main/java/com/yss/cloud/mybatis/MultiDataSourceHolder.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-persistence-common/src/main/java/com/yss/cloud/mybatis/MultiDataSourceProperties.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-persistence-common/src/main/java/com/yss/cloud/mybatis/PrimaryDataSourceConfiguration.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-persistence-common/src/main/java/com/yss/cloud/mybatis/PrimaryDataSourceProperties.java`
-
-## Recommended Next Reads
-
-- Start with the documentation files above when learning component usage.
-- Search the key Java entry points for annotations, auto configuration, properties, aspects, interceptors, handlers, and result objects before changing application code.
-- Prefer existing component extension points over rewriting framework logic in business modules.
+## Capability Matrix
+
+### Repository abstractions
+
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/support/BaseRepository.java` — `sha256:fd6d72ff759b3438a2cf9d8a2ba24e848a9e68995fc8a100a0a53c65ee3500bb`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/support/BaseRepository.java:20` — `public interface BaseRepository<T, D extends Serializable> extends Mapper<T>, BaseMapper<T, D>, ListMapper<T> {`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/support/BaseRepository.java:66` — `<S extends T> int insert(S entity);`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/support/BaseRepository.java:80` — `<S extends T> int insertSelective(S entity);`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/support/BaseRepository.java:85` — `<S extends T> int insertList(@Param("entityList") List<S> entityList);`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/support/BaseRepository.java:96` — `<S extends T> int updateList(@Param("entityList") List<S> entityList);`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/support/BaseRepository.java:108` — `<S extends T> int updateListSelective(@Param("entityList") List<S> entityList);`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/support/BasePlusRepository.java` — `sha256:3c37b73a2a2dcaa1ad47fee42f8fb4f9b9ecf51b095f8d1fef816cf785fcbb05`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/support/BasePlusRepository.java:12` — `public interface BasePlusRepository<T> extends BaseMapper<T> {`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/support/BasePlusRepository.java:21` — `default Integer insertBatchSomeColumn(List<T> entityList) {`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/support/BasePlusRepository.java:29` — `Integer rows = insertBatchSomeColumnInternal(entityList.subList(fromIndex, toIndex));`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/support/BasePlusRepository.java:43` — `Integer insertBatchSomeColumnInternal(List<T> entityList);`
+
+### Pagination and activation
+
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/aop/EntityQueryAspect.java` — `sha256:617d5eba33a8266bfc485c8e5f39f43519dd16f4d89c9fea7f918d87b00293ba`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/aop/EntityQueryAspect.java:22` — `@Around("( (execution(public * (@org.springframework.stereotype.Repository *).*(..)) || execution(* com.yss..*.gateway.impl.*.*(..))))&& (args(pageQuery)||args(pageQuery,..))")`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/aop/EntityQueryAspect.java:27` — `Page<Object> page = PageHelper.offsetPage(pageQuery.getOffset(), pageQuery.getPageSize());`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/config/PageQueryEntityConfigration.java` — `sha256:c2659f417c10db7fd9e1a91f825d3b6396ae949f7858dbd3b3d9f8917ae42031`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/config/PageQueryEntityConfigration.java:15` — `@ConditionalOnProperty(name = "yss.mybatis.page-helper.enabled", havingValue = "true", matchIfMissing = true)`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/YssMybatisMapperProperties.java` — `sha256:2fda7b769434bd6942f680cdc7ffa71030c0d6a0e448d762e0f19b2d0b33cd85`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/YssMybatisMapperProperties.java:8` — `@ConfigurationProperties(value = "yss.mybatis",ignoreUnknownFields = false)`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/YssMybatisMapperProperties.java:10` — `private String mapperLocation = "mappers/*.xml";`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/YssMybatisMapperProperties.java:11` — `private String mapperScan = "com.yss.cloud.**.mapper";`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/YssMybatisMapperProperties.java:15` — `private Integer batchSize = 200;`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/YssMybatisMapperProperties.java:21` — `private PageHelper pageHelper = new PageHelper();`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/YssMybatisMapperProperties.java:27` — `private MybatisPlusPagination mybatisPlusPagination = new MybatisPlusPagination();`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/YssMybatisMapperProperties.java:36` — `private String dbType;`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/YssMybatisMapperProperties.java:164` — `private Boolean enabled = true;`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/YssMybatisMapperProperties.java:183` — `private Boolean enabled = true;`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/MapperConfiguration.java` — `sha256:79509947c12aeac7b9d6d3e8610edea438240b6613368b84b57b492f06a6b7fc`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/MapperConfiguration.java:47` — `PageInterceptor pageInterceptor = new PageInterceptor();`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/MapperConfiguration.java:264` — `batchSqlInjector.setDbType(dbType);`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/MapperConfiguration.java:265` — `BatchInsertSettings.setBatchSize(yssMybatisMapperProperties.getBatchSize());`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/MapperConfiguration.java:275` — `PaginationInnerInterceptor paginationInnerInterceptor = new PaginationInnerInterceptor(dbType);`
+
+### SQL-level batch insertion
+
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/BatchInsertSettings.java` — `sha256:b1ae05aed5f90a97c36ad29d240b05f9f7c5ee5796f2bc293917e09f7d1c8bd2`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/BatchInsertSettings.java:8` — `private static final int DEFAULT_BATCH_SIZE = 200;`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/BatchInsertSettings.java:9` — `private static volatile int batchSize = DEFAULT_BATCH_SIZE;`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/BatchInsertSettings.java:18` — `public static void setBatchSize(Integer configuredBatchSize) {`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/BatchInsertSettings.java:19` — `batchSize = configuredBatchSize == null || configuredBatchSize <= 0`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/BatchInsertSettings.java:20` — `? DEFAULT_BATCH_SIZE : configuredBatchSize;`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/BatchSqlInjector.java` — `sha256:463dfc881c0c33e27ed2a9157041e8b06d2b2e8bbab0dae1a106f467c31fb4ef`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/BatchSqlInjector.java:16` — `public class BatchSqlInjector extends DefaultSqlInjector {`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/BatchSqlInjector.java:28` — `"insertBatchSomeColumnInternal", dbType, i -> FieldFill.UPDATE != i.getFieldFill()));`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/DialectInsertBatchSomeColumn.java` — `sha256:9cc31f71154fffbc99e4f67816b9026f286f864cfb56a57420185f5e0362dca3`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/DialectInsertBatchSomeColumn.java:24` — `public class DialectInsertBatchSomeColumn extends AbstractMethod {`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/DialectInsertBatchSomeColumn.java:82` — `return dbType == DbType.ORACLE`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/DialectInsertBatchSomeColumn.java:83` — `|| dbType == DbType.ORACLE_12C`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/DialectInsertBatchSomeColumn.java:84` — `|| dbType == DbType.DM;`
+
+### Multi-data-source capability boundary
+
+- `yss-microservice-components/yss-component-persistence/yss-component-persistence-common/src/main/java/com/yss/cloud/mybatis/MultiDataSourceHolder.java` — `sha256:d19370f6a63af76ccb0d05084ef9f0aa71488dcc98b320933ffb8ccf9b9bf896`
+  - `yss-microservice-components/yss-component-persistence/yss-component-persistence-common/src/main/java/com/yss/cloud/mybatis/MultiDataSourceHolder.java:10` — `public class MultiDataSourceHolder {`
+  - `yss-microservice-components/yss-component-persistence/yss-component-persistence-common/src/main/java/com/yss/cloud/mybatis/MultiDataSourceHolder.java:12` — `private Map<String, DataSource> multiDataSource;`
+
+### Auto-configuration registration
+
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/resources/META-INF/spring.factories` — `sha256:592ecdc43e8e11f86c6d1c4b335661f7a05ae8faf4ebb206ec49ef25512d5e46`
+  - `org.springframework.boot.autoconfigure.EnableAutoConfiguration=\`
+  - `io.mybatis.config.spring.SpringEnvAutoConfiguration`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/resources/META-INF/spring.factories` — `sha256:22d8e4510b67fffe9a132b20524c1982c530d80594a3c4e9f839e914068e0a58`
+  - `org.springframework.boot.autoconfigure.EnableAutoConfiguration = com.yss.cloud.mybatis.MybatisPlusConfiguration`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/resources/META-INF/spring.factories` — `sha256:ab6be3903a3af9369ecc56d47dac769511e62bc4a7215ebb7171a920415fa23f`
+  - `org.springframework.boot.autoconfigure.EnableAutoConfiguration = com.yss.cloud.mybatis.MybatisBaseConfiguration,com.yss.cloud.mybatis.MybatisPlusConfiguration`
+- `yss-microservice-components/yss-component-persistence/yss-component-persistence-common/src/main/resources/META-INF/spring.factories` — `sha256:59e4a12550a854ad5a5b253ba3300058edc6646b2b221505aab4fb6bfcad1721`
+  - `org.springframework.boot.autoconfigure.EnableAutoConfiguration = com.yss.cloud.mybatis.MultiDataSourceConfiguration`
+
+## Freshness and Use
+
+- Locate the current source root using `YSS_SOURCE_ROOT`, CodeGraph, Maven artifact names or repository search.
+- Compare each indexed `Component tree` with `git rev-parse HEAD:<component-path>` and require the current component subtree to be clean before exact guidance.
+- A repository commit difference alone is not stale when the component tree is unchanged; a component tree mismatch or component-local dirty state is stale.
+- Read only the source entries needed for the current decision or troubleshooting path.