create-yss-spec 3.4.5 → 3.4.7

package/template/.codex/skills/yss-ui/SKILL.md

@@ -5,7 +5,7 @@ description: "选择和核验 YSS Vue 生产页面组件及 Ant Design Vue 兼
 
 # YSS UI 统一路由与交付门禁
 
-本技能是 YSS Vue 生产页面的统一入口。它负责组件路由、版本预检、跨组件约束和交付证据；具体组件、请求、表单和高度实现交给最小专项 skill，避免重复维护 API 细节。
+本技能是 YSS Vue 生产页面的统一入口。它负责组件与导入来源路由、版本预检、跨组件约束和交付证据；具体页面、组件、请求和表单实现交给最小专项 skill，避免重复维护 API 细节。
 
 ## 1. 权威事实顺序
 
@@ -51,16 +51,19 @@ pnpm why vue @yss-ui/components @yss-ui/hooks ant-design-vue vxe-table
 - `YFormily` 是新代码 canonical name；`YssFormily` 仅作为已确认导出的历史兼容 alias。
 - `YSplitPane`、`YButton`、`YCard` 等已有封装优先使用 YSS。
 
+导入来源必须可追溯：优先使用当前会话的 yss-ui MCP 查询真实组件、Hook、Utils 与导出包；不可用时再读取与安装版本匹配的本地文档、`llms-full.txt`、源码 `src/index.ts` 和已编译用法。已导出的能力分别从 `@yss-ui/components`、`@yss-ui/hooks`、`@yss-ui/utils` 导入；确认未封装的 `Modal`、`Drawer`、`Popconfirm`、`Input` 等才从 `ant-design-vue` 导入。禁止臆造 `YModal`、`YDrawer`、`YInput`、`YPopconfirm` 或直接导入 `@formily/antdv` 业务 UI。
+
 ## 4. 最小专项 skill 路由
 
 | 任务 | 必须路由 |
 |---|---|
 | 新建或改造完整业务页面 | `yss-ui-business-page-generation` |
-| 页面布局与无独立 Skill 的专项组件 | `page-skeleton`、`component-selection-imports`、`references/specialized-components.md` |
+| 页面布局与无独立 Skill 的专项组件 | `yss-ui-business-page-generation`、`references/component-routing.md`、`references/specialized-components.md` |
 | 请求、分页、参数、树数据映射 | `yss-hook` |
 | Formily schema、联动、校验、详情态 | `yss-formily` |
-| 表格高度 | `yss-use-table-height` |
-| 树高度 | `yss-use-tree-height` |
+| YTable 与表格高度 | `ytable-usage` |
+| YEditTable 与表格高度 | `yedit-table-usage` |
+| YTree 与树高度 | `ytree-usage` |
 | Orval、API、useRequest 接入 | `yss-api-integration` |
 | 视觉、token、响应式体验 | `yss-design-system` |
 
@@ -133,7 +136,7 @@ verification: pnpm type-check
 3. 搭页面目录和布局。
 4. 接 `YFormily`、`YTable`、`YTree` 等 YSS 主体组件。
 5. 下沉请求、分页和映射到 `yss-hook`。
-6. 接高度、主题、locale、浮层和无障碍约束。
+6. 按组件专项接高度，再接主题、locale、浮层和无障碍约束。
 7. 联调冻结 API、Mock、路由和权限。
 8. 按 `references/verification.md` 完成分层验证。
 
@@ -142,7 +145,7 @@ verification: pnpm type-check
 - [ ] 已记录 Vue、YSS UI、AntDV、VXE 实际版本。
 - [ ] 组件选型符合 `component-routing.md`，回退有证据。
 - [ ] 新代码使用 `YFormily` 和真实存在的 `yss-hook`。
-- [ ] YTable/YTree/Formily/高度 Hook 遵循专项 skill。
+- [ ] YTable/YEditTable/YTree/Formily 及其高度 Hook 遵循对应组件专项 skill。
 - [ ] 主题、locale、浮层容器和微应用隔离已检查。
 - [ ] loading/empty/error/no-access/selected 状态按影响面覆盖。
 - [ ] 键盘、焦点、标签和颜色对比度已检查。

package/template/.codex/skills/yss-ui/references/component-routing.md

@@ -6,11 +6,11 @@
 |---|---|---|---|---|
 | 普通按钮、权限按钮 | `YButton` | AntDV Button | required | 权限、主题和统一动作语义；不得直接导入 Button |
 | 卡片 | `YCard` | AntDV Card | required | YSS 布局与间距扩展 |
-| 数据表格 | `YTable` | VXE Table + AntDV Pagination | specialized | 使用 `ytable-usage`；远程分页交给 `page-list-module`，高度交给 `yss-use-table-height` |
-| 编辑表格 | `YEditTable` | VXE Table | specialized | 使用 `yedit-table-usage`，不要把编辑与普通展示表格混为一套 API |
-| 树 | `YTree` | AntDV Tree | specialized | 使用 `ytree-usage`；高度交给 `yss-use-tree-height` |
+| 数据表格 | `YTable` | VXE Table + AntDV Pagination | specialized | 使用 `ytable-usage`；远程分页与高度均由该专项和 `yss-hook` 协作 |
+| 编辑表格 | `YEditTable` | VXE Table | specialized | 使用 `yedit-table-usage`，包括添加按钮偏移与弹层高度；不要和展示表格混用 API |
+| 树 | `YTree` | AntDV Tree | specialized | 使用 `ytree-usage`，包括搜索区偏移、隐藏容器重算和左树右表联动 |
 | Schema 表单 | `YFormily` | Formily + AntDV | specialized | `YFormily` 为 canonical；`YssFormily` 仅为历史兼容名；加载 `yss-formily` |
-| 分栏布局 | `YSplitPane` | YSS layout | required | 页面骨架使用 `page-skeleton`；组件边界见 `specialized-components.md` |
+| 分栏布局 | `YSplitPane` | YSS layout | required | 页面编排使用 `yss-ui-business-page-generation`；组件边界见 `specialized-components.md` |
 | 文件导入 | `YFileImport` | Upload/业务适配 | required | 两步导入边界见 `specialized-components.md` |
 | 条件构建 | `YConditionBuilder` | YSS domain component | required | 标准模型与校验边界见 `specialized-components.md` |
 | 月历 | `YMonthCalendar` | YSS domain component | required | 日期、月份、高度与事件边界见 `specialized-components.md` |
@@ -27,6 +27,13 @@
 
 YSS `required` wrapper 缺少必要能力时，记录组件、能力缺口、依赖版本、替代方案、主题/locale/浮层影响和验证证据。没有记录不得回退。
 
+## 导入来源判定
+
+1. MCP 可用时，先用 `list_components` 校正名称，再用 `get_component_docs` 确认导出包、Props、Events 和 Slots；复杂场景再查 Demo。
+2. MCP 不可用或结果与目标工程版本不一致时，以 lockfile、当前源码可编译导出、TypeScript 类型和已通过测试的用法为准。
+3. 已封装组件从 `@yss-ui/components` 导入，公开 Hook 和 Utils 分别从 `@yss-ui/hooks`、`@yss-ui/utils` 导入；确认未封装后才回退 `ant-design-vue`。
+4. 禁止仅凭名称猜测 `Y*` 导出，禁止因文档暂时不可达就把猜测实现当作已验证事实。
+
 ## 更新规则
 
 新增或变更 YSS Wrapper 时同步：本表、组件 docs、至少一个已验证 demo、三个索引、兼容矩阵和验证脚本。

package/template/.codex/skills/yss-ui-business-page-generation/SKILL.md

@@ -31,6 +31,7 @@ description: "生成或改造完整 YSS UI CRUD、列表、表单、详情或左
 - 主题 Token 与换肤：`../theme-token-usage/SKILL.md`
 - 文件导出下载：`../file-export-download/SKILL.md`
 - Orval 接口与错误处理：`../yss-api-integration/SKILL.md`
+- 请求、分页、参数与异步竞态：`../yss-hook/SKILL.md`
 
 ## 文档检索顺序
 
@@ -56,6 +57,9 @@ description: "生成或改造完整 YSS UI CRUD、列表、表单、详情或左
 - 删除确认默认使用 `YTable actionConfig.buttons[].isConfirm` 按钮项或 AntDV `Popconfirm` 气泡确认，禁止默认使用居中 `Modal.confirm`。
 - 样式抽离到 `style.less`，在 SFC 中使用 `<style scoped lang="less">@import './style.less';</style>`。
 - `index.vue` 原则上不超过 150 行；状态、API、副作用和处理方法进入 `hooks/`，列定义和静态配置进入 `constant.ts`。
+- 页面目录默认使用 `index.vue + constant.ts + style.less + hooks/`；只有存在多个私有视图或大量独立类型时才增加 `components/` 和 `type.ts`。`index.vue` 只做 Hook 组合、视图编排和事件转发。
+- 列表查询只维护一份 `currentParams`；查询、重置、树节点切换均回到第一页，翻页保留筛选条件，批量操作成功后清空选中态。组件 API 服从 `ytable-usage` / `ytree-usage`，请求和竞态服从 `yss-hook`。
+- Modal/Drawer 表单的 `open/mode/currentId/formModel/submitting`、回填、提交和关闭收敛在同一业务 Hook。新增/编辑数据在打开容器前准备，容器关闭时销毁并清理；默认依赖响应式 `mode`/model，不用动态 `:key` 强制重挂载。
 - 所有导出函数、hooks、类型和静态配置必须使用中文 JSDoc。
 - Orval 请求必须使用真实生成导出和 DTO；禁止 `if (res?.success)` 冗余包裹，也禁止在 `else`/`catch` 重复 `message.error`。
 - 页面、公共组件、内联样式、TS 渲染配置和 SVG 必须遵循 `theme-token-usage`；禁止硬编码品牌色及 hover/active/selected/focus 色阶，主色透明态必须由真实动态 Token 派生。
@@ -83,7 +87,7 @@ src/views/{module-name}/
 1. 读取本 skill 的三个 reference，并按上述文档检索顺序核对真实 API 与导出，禁止根据旧示例猜测。
 2. 读取 `theme-token-usage`，检查项目真实主题变量与运行时同步链路。
 3. 若有截图或旧项目路径，先读取已批准且 digest 当前的 Visual Baseline manifest 和 `frontend_implementation_plan`，按 `case_id` 提取布局、状态、交互、响应式与控件类型验收项；缺失或摘要漂移时返回 `blocked`，不得凭目录或截图猜测。
-4. 按需求类型加载细分 skill：列表读 `page-list-module` 和 `ytable-usage`；表单读 `yss-formily`；编辑表格读 `yedit-table-usage`；树读 `ytree-usage`；导出下载读 `file-export-download`。
+4. 按需求类型加载细分 skill：列表读 `ytable-usage` 与 `yss-hook`；表单读 `yss-formily`；编辑表格读 `yedit-table-usage`；树读 `ytree-usage`；导出下载读 `file-export-download`。
 5. 先设计 `constant.ts`、`style.less` 和 hooks；独立类型或私有视图确有需要时再增加 `type.ts`/`components/`，最后写 `index.vue` 组合视图。
 6. 对 API 请求使用 Orval 真实生成类型和导出，在 hooks 内封装 loading、分页映射和失败后状态；错误 Toast 由 mutator 统一处理。
 7. 交付前检查导入来源、真实组件 API、分页字段、Formily schema 层级、主题 Token、查询按钮右下角布局、表格工具栏、样式作用域、删除确认和原型对照清单。

package/template/.codex/skills/yss-ui-business-page-generation/references/hooks-map.md

@@ -10,25 +10,26 @@ const { tableHeight, isReady, recalculateHeight } = useTableHeight(tableAreaRef,
   withPagination: true,
   withToolbar: true,
   withAddButton: false,
-  extraOffset: 16,
 });
 ```
 
 - 必须传入表格父容器 `ref`。
 - 返回值是 `recalculateHeight`，不要使用旧的错误返回名。
 - 可选项：`boundaryRef`、`minHeight`、`defaultHeight`、`extraOffset`、`withPagination`、`withToolbar`、`withAddButton`、`paginationHeight`、`toolbarHeight`、`addButtonHeight`。
+- 被观察区域若会被表格内容撑开，使用更外层稳定的 `boundaryRef`，避免尺寸反馈循环；`extraOffset` 只能对应可说明的实际布局占位。
 
 ## useTreeHeight
 
 ```ts
 const treeAreaRef = ref<HTMLDivElement>();
 const { treeHeight, recalculateHeight } = useTreeHeight(treeAreaRef, {
-  extraOffset: YTREE_SEARCH_HEIGHT + 16,
+  extraOffset: YTREE_SEARCH_HEIGHT,
 });
 ```
 
 - 必须传入树区域父容器 `ref`。
 - 搜索树可引入 `YTREE_SEARCH_HEIGHT`。
+- 内置搜索已由 `YTREE_SEARCH_HEIGHT` 扣除，不得再叠加无依据的 `+16`；Tab/Drawer 可见后按需 `nextTick(recalculateHeight)`。
 
 ## useLoading
 

package/template/.codex/skills/yss-up-springboot3/SKILL.md

@@ -5,24 +5,33 @@ description: "审查或迁移 YSS Spring Boot 2 到 3 的依赖、Jakarta 与 Sp
 
 # yss-up-springboot3
 
-Use this skill for YSS backend upgrade analysis and migration tasks around Spring Boot 3 / Spring Cloud compatibility.
+Use this skill for catalog-driven YSS backend upgrade analysis and approved migrations from an exact Spring Boot 2 platform to an exact Spring Boot 3 platform.
 
-中文说明：这个技能是升级核查入口，不替代具体组件技能。遇到缓存、审计、MyBatis、DTO、Excel、JDBC 等组件细节时，应同时读取对应专项技能和源码索引。
+中文说明：这个技能是平台迁移编排入口，不替代具体组件 Skill。源平台、目标平台和组件能力只从 `docs/engineering/backend-platforms.json`、批准的 `platform_configuration`、工程 Manifest、effective POM 与实际依赖树解析，不按版本记忆或源码可编译状态推断兼容。
 
 ## When To Use
 
-- The user asks to upgrade YSS backend code to Spring Boot 3 or newer Spring Cloud baselines.
+- The user asks to assess or migrate a YSS backend from Spring Boot 2 to Spring Boot 3.
 - The task mentions `javax.*` to `jakarta.*`, Spring Security migration, validation changes, Servlet API changes, Gateway/OpenFeign compatibility, or dependency BOM changes.
 - The task involves checking whether a YSS component can run on Spring Boot 3.
 
+## 准入与阻断
+
+- 先运行 `scripts/backend-platforms` 查询精确 profile。目标 profile 不可选择、缺 compatibility 条目或任一必需 `component_capabilities` 不是 `verified` 时，只能输出差距分析，迁移实现返回 `component-unavailable-for-platform` 或对应组件绑定错误。
+- Spring Boot 4 不属于本 Skill 的 2→3 迁移执行范围。Boot 4 命中 Jackson 3、starter/自动配置结构或现有 YSS 组件时返回 `blocked`，建立独立平台迁移工作单元；不得把已完成的 Boot 3 改造解释为 Boot 4 兼容。
+- 既有工程的源码编译、单元测试或 `javax`→`jakarta` 替换不等于平台认证。没有目标架构的真实构件、启动和组件 seam 证据时不得宣称迁移完成。
+- 平台迁移不得夹带业务重构、架构族转换或组件替换。发现这些影响时返回 `new_impacts`，交实现合同编译器重新路由。
+
 ## Workflow
 
-1. Identify affected modules and current dependency versions from the local repository.
-2. Check for Jakarta namespace changes (`javax.servlet`, `javax.validation`, `javax.annotation`, JPA APIs, and related imports).
-3. Check Spring Security configuration style, deprecated adapters, authorization server dependencies, and filter registration behavior.
-4. Check component-specific integration by loading specialist skills such as `yss-mybatis`, `yss-dto`, `yss-cache`, `yss-audit-log`, `yss-excel-mvc`, or `yss-jdbc`.
-5. Prefer source-backed evidence from the local workspace or a source root resolved via `yss-skill-source-index-refresh/references/source-location.md` before recommending code changes.
-6. Produce an upgrade checklist or patch with explicit compatibility risks and verification commands.
+1. 从工程登记、Manifest、父/BOM、effective POM 和依赖树冻结源 `platform_configuration`、架构 Profile、全部 YSS GAV、组件绑定及基线验证命令；缺失或相互冲突时停止。
+2. 从平台目录选择一个精确 Spring Boot 3 目标 profile，记录 compatibility id/digest；不得使用 `3.x`、`latest`、范围版本或自行拼装父/BOM。
+3. 由当前 Slice/迁移合同解析所需 capability，再逐项核验目标 profile 的组件状态、架构证据、timestamped SNAPSHOT、POM/JAR 摘要和源码 tree。未登记的 JDBC 等能力记为缺口，不虚构 `yss-jdbc` Skill 或绕过 catalog。
+4. 按命中能力加载已登记专项 Skill，例如 `yss-mybatis`、`yss-dto`、`yss-validation`、`yss-exception`、`yss-cache`、`yss-audit-log`、`yss-excel-mvc`、`yss-userinfo`、`yss-resilience4j` 和 `yss-security-algorithm`；分别用 `boot2-java8` 与 `boot3-java17` 索引核验源/目标组件 tree，源码索引只用于定位风险，不代替 compatibility evidence。
+5. 编制迁移增量：Java 与编译插件、Servlet/Validation/JPA namespace、Spring Security、Spring Cloud/OpenFeign、MyBatis starter、自动配置注册、配置属性、Jackson 2 wire 行为、测试工具和打包方式。`javax.sql`、`javax.crypto` 等 Java SE API 不迁移。
+6. 在批准的迁移工作单元内分批实施，每批保持可构建和可回滚；组件坐标或平台配方发生变化时重新编译合同，不在业务代码中临时替换依赖。
+7. 使用工程根 `./mvnw` 记录 effective POM、依赖树、`validate`、`test`、`package`、随机端口启动和真实组件 seam；DDD 与 MVC 证据不可互相代替。
+8. 重新解析全部组件绑定并比较摘要；通过只表示该工程的批准迁移结果，不自动把共享平台或其他工程标记为 verified。
 
 ## Common Checks
 
@@ -32,9 +41,14 @@ Use this skill for YSS backend upgrade analysis and migration tasks around Sprin
 - Validation annotations and exception handlers still map to the expected DTO/Result contract.
 - MyBatis interceptors, auto configurations, and starter metadata are compatible with Spring Boot 3 auto-configuration loading.
 - Tests or sample modules are updated together with framework code.
+- Jackson 2 的 Result/PageResult、日期、枚举、nullability 和错误响应 wire fixture 与冻结 OpenAPI 一致。
+- `spring.factories` 与 `AutoConfiguration.imports` 的目标机制以真实 starter 为准，不能仅移动文件名后宣称自动配置生效。
+- 输出包含源/目标 profile、compatibility digest、组件逐项结论、阻塞项、实际命令与回滚点。
 
 ## Do Not
 
 - Do not blindly rewrite all `javax.*` imports without checking whether the dependency still uses the old namespace.
 - Do not mix unrelated business refactors into migration patches.
 - Do not assume component compatibility from memory; inspect source and specialist skill indexes.
+- Do not bypass a blocked component by excluding its starter, copying component code into the service, or substituting an unapproved third-party dependency.
+- Do not execute a Boot 4 migration under this Skill or reuse Boot 3 evidence for Boot 4.

package/template/.codex/skills/yss-userinfo/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yss-userinfo
-description: "接入或排查 YSS AuthUserInfoUtil、用户头透传、JWT、Redis 用户缓存与后台用户上下文。"
+description: "接入或排查 YSS CurrentUserProvider、已认证 SecurityContext、受信网关头适配与后台用户上下文。"
 ---
 
 # yss-userinfo
@@ -19,31 +19,38 @@ Read `references/source-index.md` as a path-hint index whenever the task depends
 
 ## Workflow
 
-1. Identify whether the task is current-user lookup, request header propagation, JWT parsing, Redis user cache lookup, or non-REST/background fallback behavior.
-2. Read `references/source-index.md`, then inspect `AuthUserInfoUtil`, `DmUser`, and `DmUserDetails`.
-3. Prefer `AuthUserInfoUtil.userInfo()`, `userName()`, `userCode()`, or `currentUserJson()` over manually parsing headers in business code, but treat the result as propagated context, not as JWT signature verification.
-4. Check lookup order before debugging: `X-Username`/`X-Usercode`/`X-LoginDisplayName` headers, Bearer JWT payload, then Redis cache via `CacheManagerCompose`.
-5. For scheduled/background tasks, expect fallback behavior such as default `system` user unless the caller explicitly provides context.
+1. 先按已批准平台线读取对应索引；以下当前行为针对 `boot3-java17`，Boot 2 旧工程只按其独立索引做只读分诊和迁移。
+2. Identify whether the task is authenticated current-user lookup, an explicitly trusted gateway adapter, a custom `CurrentUserProvider`, or non-REST/background fallback behavior.
+3. Read `references/source-index.md`, then inspect `CurrentUserProvider`, `SecurityContextCurrentUserProvider`, `TrustedGatewayHeaderCurrentUserProvider`, `AuthUserInfoUtil`, `DmUser`, and `DmUserDetails`.
+4. 默认使用 `SecurityContextCurrentUserProvider`，只消费 Spring Security 已认证且非 anonymous 的 `Authentication`。JWT 的 signature、issuer、audience、expiry 与算法校验必须在资源服务器认证链完成。
+5. `AuthUserInfoUtil` 是由 `CurrentUserProvider` 驱动的兼容 facade；业务代码可继续调用 `userInfo()`、`userName()`、`userCode()` 或 `currentUserJson()`，但不得自行解析 Header、JWT payload 或 Redis 身份缓存。
+6. 只有显式启用 `yss.userinfo.trusted-gateway.enabled` 且配置非空 `trusted-proxies` 时，才启用 `TrustedGatewayHeaderCurrentUserProvider`；它只接受 remote address 在 allow-list 中的请求，并且 SecurityContext 结果优先。
+7. For scheduled/background tasks, an empty provider result causes the compatibility facade to return the distinct `system` fallback; do not represent it as an authenticated system principal.
 
 ## Source-Backed Notes
 
-- Header names include `X-Username`, `X-Usercode`, and `X-LoginDisplayName`.
-- Bearer token parsing reads payload fields such as `sub`, `loginDisplayName`, `email`, and `userCode` without verifying signature/issuer/audience/expiry in this utility. Authentication decisions must use a verified security context.
-- The current source has a known reversed `userCode` header assignment condition; do not claim that header path is reliable until fixed and tested.
-- Redis cache lookup uses the JWT user-info cache key path; load `yss-cache` if changing cache behavior.
+- `SecurityContextCurrentUserProvider` supports a `UserInfo` principal and an authenticated `OAuth2AuthenticatedPrincipal`; claim mapping happens only after authentication.
+- Trusted gateway header names are `X-Username`, `X-Usercode`, and `X-LoginDisplayName`; the adapter requires a trusted proxy allow-list and a nonblank username.
+- `UserInfoAutoConfiguration` installs SecurityContext as the default and composes the optional gateway provider behind it. A project-supplied `CurrentUserProvider` remains the explicit extension seam.
+- The Boot 3 component does not parse an unverified Bearer payload and does not use Redis as an authentication fallback. Cache behavior is outside this identity provider contract.
 
 ## Checklist
 
 - Required dependency or starter module is present.
 - Request context exists before relying on servlet headers.
-- Gateway/auth service forwards expected user headers or Authorization token.
-- Cache fallback is checked when headers exist but detailed user info is incomplete.
-- Business code does not duplicate JWT parsing logic.
-- Header/JWT/cache/background precedence and overwrite behavior are covered by tests; `system` fallback is distinguished from an authenticated system user.
+- Spring Security has authenticated the request before the provider reads the principal.
+- When trusted gateway mode is enabled, at least one proxy address is allow-listed and untrusted remote addresses are rejected.
+- Business code does not duplicate JWT or header parsing logic.
+- SecurityContext/gateway/background precedence and empty-result behavior are covered by tests; `system` fallback is distinguished from an authenticated system user.
 - User info propagation is tested for REST calls and async/background execution separately.
 
 ## Do Not
 
 - Do not invent class names or configuration keys without checking the source index.
 - Do not replace component extension points with business-local framework code.
+- Do not treat raw `Authorization` payloads or gateway headers as authenticated identity.
 - Do not broaden the task into unrelated YSS components unless the user asks.
+
+## 平台与源码门禁
+
+接入、修改、代码生成或给出精确类名/配置前，读取 [后端组件平台与源码门禁](../yss-skill-source-index-refresh/references/backend-component-platform-compatibility.md)，从批准的 `platform_configuration.component_platform_line` 选择 `source-index.boot2-java8.md` 或 `source-index.boot3-java17.md`，并以 `--skill yss-userinfo --platform-line <line> --source-root <matching-root>` 运行统一 freshness 校验。平台线与源码根不匹配、组件 tree 不一致、组件子树 dirty、索引缺少平台信号，或 Manifest / 组件 GAV 缺少 verified 兼容证据时返回 `blocked`；不得回退另一代索引，也不在业务实现中升级、降级或替换 YSS 组件。既有工程只读分诊可继续，但不得据此宣称跨 Boot/JDK 兼容。

package/template/.codex/skills/yss-userinfo/references/source-index.boot2-java8.md

@@ -0,0 +1,49 @@
+# yss-userinfo Source Index
+
+Index schema: `backend-component-source-index-v2`
+Platform line: `boot2-java8`
+Generated: 2026-09-18T18:40:26.031Z
+Source commit: `a3be2b2e33dca4545782e2b31894aaa00d0305cd`
+Component worktree: `clean`
+Component tree `yss-microservice-components/yss-component-userinfo-starter`: `fc77d57e0be6ee81b10247c0746baed6a09c6bb4`
+Indexed source root: resolved at refresh time; set `YSS_SOURCE_ROOT_BOOT2_JAVA8` 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 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
+
+- `yss-microservice-components/yss-component-userinfo-starter` (existed when indexed)
+
+## Documentation Files
+
+- No component documentation files found.
+
+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-userinfo-starter/pom.xml` — GAV `com.yss.cloud:yss-component-userinfo-starter:2.0.0-SNAPSHOT`; parent `com.yss.cloud:yss-microservice-components:2.0.0-SNAPSHOT`
+
+## Platform Signals
+
+- Inherited Java signals: `1.8`.
+- Inherited Spring Boot signals: `2.7.18`.
+- Namespace source signals: `javax.*` in 1 main Java files; `jakarta.*` in 0 main Java files.
+- Auto-configuration metadata: 0 `spring.factories`; 0 `AutoConfiguration.imports` files.
+- These are source observations, not compatibility certification. Use the approved `platform_configuration` and verified compatibility evidence before integration or generation.
+
+## Key Java Entry Points
+
+- `yss-microservice-components/yss-component-userinfo-starter/src/main/java/com/yss/cloud/domain/DmUser.java` — `sha256:c25b546485977a7e28c23ed22735e0ea43eb166f6a856e43159b7d40677570fe`
+- `yss-microservice-components/yss-component-userinfo-starter/src/main/java/com/yss/cloud/domain/DmUserDetails.java` — `sha256:ab34afc0f0e28fe85b405e56b12ee08b57884cfc120b6bd5d8b0e8e095e51a2c`
+- `yss-microservice-components/yss-component-userinfo-starter/src/main/java/com/yss/cloud/user/AuthUserInfoUtil.java` — `sha256:2ed38a6357a7cc5a057cdb8c6e105c3d2c7455ede0ec1e822d36b7dbcd04df83`
+
+## Freshness and Use
+
+- Locate the current source root using `YSS_SOURCE_ROOT_BOOT2_JAVA8`, 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.
+- Run `node ../yss-skill-source-index-refresh/scripts/check-backend-skill-source-index.mjs --skill <skill-id> --platform-line boot2-java8 --source-root <root>` from the canonical skill root before exact integration 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.

package/template/.codex/skills/yss-userinfo/references/source-index.boot3-java17.md

@@ -0,0 +1,54 @@
+# yss-userinfo Source Index
+
+Index schema: `backend-component-source-index-v2`
+Platform line: `boot3-java17`
+Generated: 2026-09-18T18:40:26.031Z
+Source commit: `5041c41fbe96c25821bbc15f688c0521b8c97a3d`
+Component worktree: `clean`
+Component tree `yss-microservice-components/yss-component-userinfo-starter`: `96c79dcb754df0dbcc59a465e45d6871601275ff`
+Indexed source root: resolved at refresh time; set `YSS_SOURCE_ROOT_BOOT3_JAVA17` 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 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
+
+- `yss-microservice-components/yss-component-userinfo-starter` (existed when indexed)
+
+## Documentation Files
+
+- No component documentation files found.
+
+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-userinfo-starter/pom.xml` — GAV `com.yss.cloud:yss-component-userinfo-starter:3.0.0-SNAPSHOT`; parent `com.yss.cloud:yss-microservice-components:3.0.0-SNAPSHOT`
+
+## Platform Signals
+
+- Inherited Java signals: `17`.
+- Inherited Spring Boot signals: `3.5.16`.
+- Namespace source signals: `javax.*` in 0 main Java files; `jakarta.*` in 1 main Java files.
+- Auto-configuration metadata: 0 `spring.factories`; 1 `AutoConfiguration.imports` files.
+- These are source observations, not compatibility certification. Use the approved `platform_configuration` and verified compatibility evidence before integration or generation.
+
+## Key Java Entry Points
+
+- `yss-microservice-components/yss-component-userinfo-starter/src/main/java/com/yss/cloud/domain/DmUser.java` — `sha256:c25b546485977a7e28c23ed22735e0ea43eb166f6a856e43159b7d40677570fe`
+- `yss-microservice-components/yss-component-userinfo-starter/src/main/java/com/yss/cloud/domain/DmUserDetails.java` — `sha256:ab34afc0f0e28fe85b405e56b12ee08b57884cfc120b6bd5d8b0e8e095e51a2c`
+- `yss-microservice-components/yss-component-userinfo-starter/src/main/java/com/yss/cloud/user/AuthUserInfoUtil.java` — `sha256:e3c8cd0f18754644a95ccccb76a7ae66d5446af35f683a212daf7566b13a7eaf`
+- `yss-microservice-components/yss-component-userinfo-starter/src/main/java/com/yss/cloud/user/CurrentUserProvider.java` — `sha256:4f76eab3eb10a24af0a3f40eacfbac6a7f1d367af532c6c30cf25d118ba4d1fa`
+- `yss-microservice-components/yss-component-userinfo-starter/src/main/java/com/yss/cloud/user/SecurityContextCurrentUserProvider.java` — `sha256:fd83da91f69c016623c13efc33ef85de3dcc5864fb7ee42de3a0054a7c6d9e70`
+- `yss-microservice-components/yss-component-userinfo-starter/src/main/java/com/yss/cloud/user/TrustedGatewayHeaderCurrentUserProvider.java` — `sha256:72c8e5e1f60e90f02685ec2e494efc0271ee35ddf2df989b96f3b76aa0401737`
+- `yss-microservice-components/yss-component-userinfo-starter/src/main/java/com/yss/cloud/user/config/TrustedGatewayUserInfoProperties.java` — `sha256:30f34ac4b4d43f854e46d5078dd6ed84e86280a4c0150508091cd557919ddab2`
+- `yss-microservice-components/yss-component-userinfo-starter/src/main/java/com/yss/cloud/user/config/UserInfoAutoConfiguration.java` — `sha256:4bfc378fcba4f6dbb8f1bcc8e3ea4ee7c8fc9908f68cfb187c7945ebeee4dead`
+
+## Freshness and Use
+
+- Locate the current source root using `YSS_SOURCE_ROOT_BOOT3_JAVA17`, 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.
+- Run `node ../yss-skill-source-index-refresh/scripts/check-backend-skill-source-index.mjs --skill <skill-id> --platform-line boot3-java17 --source-root <root>` from the canonical skill root before exact integration 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.

package/template/.codex/skills/yss-userinfo/references/source-index.md

@@ -1,34 +1,10 @@
-# yss-userinfo Source Index
+# yss-userinfo Source Index Router
 
-Generated: 2026-08-17T12:03:37.436Z
-Source commit: `38b556a5081e6c66c0c538cbc1ef839b19996ed3`
-Source worktree: `dirty`
-Indexed source root: resolved at refresh time; set `YSS_SOURCE_ROOT` to reproduce or refresh.
+Index schema: `backend-component-source-index-router-v1`
 
-This file is generated by `yss-skill-source-index-refresh/scripts/refresh-yss-skill-index.mjs`. Do not hand-edit generated sections.
+Select the source index from the approved `platform_configuration.component_platform_line`; do not infer a line from imports, a branch name or a requested upgrade.
 
-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.
+- `boot2-java8` — [Spring Boot 2.7 / Java 8 maintenance line](source-index.boot2-java8.md)
+- `boot3-java17` — [Spring Boot 3.5 / Java 17 mainline](source-index.boot3-java17.md)
 
-## Component Path Hints
-
-- `yss-microservice-components/yss-component-userinfo-starter` (existed when indexed)
-
-## Documentation Files
-
-- No component documentation files found.
-
-## Maven Modules
-
-- `yss-microservice-components/yss-component-userinfo-starter`
-
-## Key Java Entry Points
-
-- `yss-microservice-components/yss-component-userinfo-starter/src/main/java/com/yss/cloud/domain/DmUser.java`
-- `yss-microservice-components/yss-component-userinfo-starter/src/main/java/com/yss/cloud/domain/DmUserDetails.java`
-- `yss-microservice-components/yss-component-userinfo-starter/src/main/java/com/yss/cloud/user/AuthUserInfoUtil.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.
+Run the freshness checker with the same explicit `--platform-line` and its matching clean source root before exact integration guidance.

package/template/.codex/skills/yss-validation/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yss-validation
-description: "接入或排查 YSS Bean Validation、校验消息、LiteFlow EL 解析器与校验错误映射。"
+description: "接入或排查 YSS Bean Validation、校验消息与校验错误映射；不存在的历史 EL 组件路由保持阻断。"
 ---
 
 # yss-validation
@@ -13,40 +13,35 @@ Use this skill for YSS 校验组件. Keep implementation grounded in the local p
 
 - Backend source location is environment-specific; resolve it with `yss-skill-source-index-refresh/references/source-location.md`.
 - Generated index: `references/source-index.md`
-- Component path hints: `yss-microservice-components/yss-component-validation-engine-parent`, `yss-microservice-components/yss-component-validation-jsr303`
+- Component path hints: `yss-microservice-components/yss-component-validation-jsr303`
 
 Read `references/source-index.md` as a path-hint index whenever the task depends on exact modules, annotations, auto configuration, properties, controllers, clients, repositories, DTOs, handlers, or troubleshooting.
 
 ## Workflow
 
-1. Identify whether the task is JSR-303 annotation validation, validation engine expression parsing, LiteFlow EL parsing, or parser extension.
+1. Identify whether the task is JSR-303 annotation validation or an expression/EL parser request.
 2. Read `references/source-index.md`; for JSR-303 behavior, read `yss-component-validation-jsr303/readme.md` first.
-3. For expression parsing, inspect `ExpressParserFactory` and concrete `ExpressParser` implementations before adding syntax.
-4. Register new parsers as Spring beans; `ExpressParserFactory` auto-registers available parser beans by `parserType().getType()`.
-5. Keep validation failures mapped to the service/API error contract used by the local project.
-6. 消费工程基线选择 javax/jakarta，不自行升级 Java/Boot。MVC 输入校验放在 server/client，业务不变量由 service/core 验证；不生成 DDD Domain。HTTP 失败形态由 server 的合同测试验证。
+3. 当前组件仓不存在历史 `yss-component-validation-engine-parent`；表达式、LiteFlow EL 或 `ExpressParserFactory` 请求返回 `blocked`，先确认真实组件来源和生命周期影响，不以旧索引或通用知识生成实现。
+4. Keep validation failures mapped to the service/API error contract used by the local project.
+5. 消费工程基线选择 javax/jakarta，不自行升级 Java/Boot。MVC 输入校验放在 server/client，业务不变量由 service/core 验证；不生成 DDD Domain。HTTP 失败形态由 server 的合同测试验证。
 
 ## Capability Split
 
 - `validation-jsr303`: currently a dependency/message-resource aggregation module; it has no local Validator, Advice, or auto-configuration Java implementation.
-- `validation-el-parser`: LiteFlow/EL expression parser infrastructure.
-- `ExpressParserFactory`: central parser registry backed by a concurrent map.
-- Parser extension point: implement/provide `ExpressParser` with a non-null parser type and register it as a bean.
+- 历史 `validation-el-parser` / `ExpressParserFactory`：当前源码根不存在，状态为 `blocked`，不得作为可用 capability。
 
 ## Troubleshooting Notes
 
-- If a parser is not found, confirm it is a Spring bean and `parserType()` is non-null.
+- If an EL/parser capability is requested, stop and resolve its actual repository/module instead of assuming the removed path.
 - If validation annotations do not fire, check controller/service validation annotations and Spring validation starter wiring before editing parser code.
 - The component README is empty; use the POM, message resources, Controller annotations, and `GlobalExceptionAdvice` as current evidence.
-- Duplicate parser type keys are silently overwritten by `PARSER_MAP.put`; require collision and round-trip tests for extensions.
 - If behavior differs between expression validation and DTO validation, route the problem to the correct submodule first.
 
 ## Checklist
 
 - Required dependency or starter module is present.
-- JSR-303 and expression validation concerns are not mixed in the same fix.
-- New parser implementations have deterministic parser type keys.
-- Parser registration is verified through `ExpressParserFactory.PARSER_MAP`.
+- JSR-303 and unavailable expression-validation requests are not mixed in the same fix.
+- No class, parser or configuration is attributed to the absent historical module.
 - Validation errors preserve readable messages for Chinese business users.
 - Existing project conventions are reused before adding new wrappers.
 
@@ -56,6 +51,6 @@ Read `references/source-index.md` as a path-hint index whenever the task depends
 - Do not replace component extension points with business-local framework code.
 - Do not broaden the task into unrelated YSS components unless the user asks.
 
-## 新脚手架平台约束
+## 平台与源码门禁
 
-消费批准切片架构身份中的 `platform_configuration`，与工程 Manifest 核对后使用对应 YSS 组件。Boot 2.7 使用 `javax` Web/Validation API；Boot 3.5/4.1 使用 `jakarta`。Boot 4 按 Jackson 3、对应自动配置和 starter 适配；不替换 `javax.sql` 等 Java SE 包。平台不一致、兼容条目缺失或候选未验证时回合同编译器阻断，不在业务实现中升级或替换组件。详见 仓库共享合同 `docs/engineering/backend-platforms.md`。
+接入、修改、代码生成或给出精确类名/配置前，读取 [后端组件平台与源码门禁](../yss-skill-source-index-refresh/references/backend-component-platform-compatibility.md)，从批准的 `platform_configuration.component_platform_line` 选择 `source-index.boot2-java8.md` 或 `source-index.boot3-java17.md`，并以 `--skill yss-validation --platform-line <line> --source-root <matching-root>` 运行统一 freshness 校验。平台线与源码根不匹配、组件 tree 不一致、组件子树 dirty、索引缺少平台信号，或 Manifest / 组件 GAV 缺少 verified 兼容证据时返回 `blocked`；不得回退另一代索引，也不在业务实现中升级、降级或替换 YSS 组件。既有工程只读分诊可继续，但不得据此宣称跨 Boot/JDK 兼容。

package/template/.codex/skills/yss-validation/references/source-index.boot2-java8.md

@@ -0,0 +1,47 @@
+# yss-validation Source Index
+
+Index schema: `backend-component-source-index-v2`
+Platform line: `boot2-java8`
+Generated: 2026-09-18T18:40:26.031Z
+Source commit: `a3be2b2e33dca4545782e2b31894aaa00d0305cd`
+Component worktree: `clean`
+Component tree `yss-microservice-components/yss-component-validation-jsr303`: `fe5b36afb474afa41541fe1187a6828bdae080dc`
+Indexed source root: resolved at refresh time; set `YSS_SOURCE_ROOT_BOOT2_JAVA8` 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 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
+
+- `yss-microservice-components/yss-component-validation-jsr303` (existed when indexed)
+
+## Documentation Files
+
+- `yss-microservice-components/yss-component-validation-jsr303/readme.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-validation-jsr303/pom.xml` — GAV `com.yss.cloud:yss-component-validation-jsr303:2.0.0-SNAPSHOT`; parent `com.yss.cloud:yss-cloud-microservice:2.0.0-SNAPSHOT`
+
+## Platform Signals
+
+- Inherited Java signals: `1.8`.
+- Inherited Spring Boot signals: `2.7.18`.
+- Namespace source signals: `javax.*` in 0 main Java files; `jakarta.*` in 0 main Java files.
+- Auto-configuration metadata: 0 `spring.factories`; 0 `AutoConfiguration.imports` files.
+- These are source observations, not compatibility certification. Use the approved `platform_configuration` and verified compatibility evidence before integration or generation.
+
+## Key Java Entry Points
+
+- No key Java entry points matched the configured name patterns.
+
+## Freshness and Use
+
+- Locate the current source root using `YSS_SOURCE_ROOT_BOOT2_JAVA8`, 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.
+- Run `node ../yss-skill-source-index-refresh/scripts/check-backend-skill-source-index.mjs --skill <skill-id> --platform-line boot2-java8 --source-root <root>` from the canonical skill root before exact integration 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.

package/template/.codex/skills/yss-validation/references/source-index.boot3-java17.md

@@ -0,0 +1,47 @@
+# yss-validation Source Index
+
+Index schema: `backend-component-source-index-v2`
+Platform line: `boot3-java17`
+Generated: 2026-09-18T18:40:26.031Z
+Source commit: `5041c41fbe96c25821bbc15f688c0521b8c97a3d`
+Component worktree: `clean`
+Component tree `yss-microservice-components/yss-component-validation-jsr303`: `aee5fea02f5de4d1e459679424f158d7537c5499`
+Indexed source root: resolved at refresh time; set `YSS_SOURCE_ROOT_BOOT3_JAVA17` 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 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
+
+- `yss-microservice-components/yss-component-validation-jsr303` (existed when indexed)
+
+## Documentation Files
+
+- `yss-microservice-components/yss-component-validation-jsr303/readme.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-validation-jsr303/pom.xml` — GAV `com.yss.cloud:yss-component-validation-jsr303:3.0.0-SNAPSHOT`; parent `com.yss.cloud:yss-cloud-microservice:3.0.0-SNAPSHOT`
+
+## Platform Signals
+
+- Inherited Java signals: `17`.
+- Inherited Spring Boot signals: `3.5.16`.
+- Namespace source signals: `javax.*` in 0 main Java files; `jakarta.*` in 0 main Java files.
+- Auto-configuration metadata: 0 `spring.factories`; 0 `AutoConfiguration.imports` files.
+- These are source observations, not compatibility certification. Use the approved `platform_configuration` and verified compatibility evidence before integration or generation.
+
+## Key Java Entry Points
+
+- No key Java entry points matched the configured name patterns.
+
+## Freshness and Use
+
+- Locate the current source root using `YSS_SOURCE_ROOT_BOOT3_JAVA17`, 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.
+- Run `node ../yss-skill-source-index-refresh/scripts/check-backend-skill-source-index.mjs --skill <skill-id> --platform-line boot3-java17 --source-root <root>` from the canonical skill root before exact integration 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.