---
name: tofly-memory-system
description: AI 记忆系统配置入口 — 3层架构动态加载 + rules 系统注入，按任务类型精确路由，安全红线只读不可覆盖
---

# AI 记忆系统 — 配置入口

> **这是 AI 每次对话首先加载的唯一配置文件。** 其余配置按需动态加载。
>
> 设计目标：**默认只消耗 ~40 行 token**（规则已由 rules/ 注入不计入），根据任务类型按需加载其余配置。

---

## 一、始终生效的底线规则（Tier 0）

> 核心行为与安全规则已由 `rules/always-on-rule.md` 系统自动注入，**每次对话始终生效，无需 AI 主动读取**。
> 此处仅保留与路由相关的项目级入口和用户习惯指引。

### 1.0 当前项目情况（严格执行）

- **必读**：仓库根目录下的 [current_project_config.md](../../../current_project_config.md)（勿与 `.cursor/` 下模板混淆）。任何代码任务须先解析其中的 **「项目标签（路由）」** 单行，再按 §2.1 映射加载；禁止仅凭 L2 通用技术栈表猜测框架。
- **项目事实优先级**（与安全红线无关的技术栈/UI/库/目录）：根目录 `current_project_config.md` **优先于** [L2 §一](./warehouse_shared_config.md#L9-L47) 与 L1 非安全章节；**不得**用 L2 中的通用组件库/框架表述覆盖本项目已声明事实。
- **「项目标签（路由）」格式**（须为单独一行，便于解析）：`项目标签（路由）：<token>/<token>[/<token>...]`，token 为下表关键字，全小写，例如 `vben3/java1`、`vue3/java3`、`vben3/java1/uniapp`。该行可与下方的自然语言「补充说明」并存，**路由仅以本行 token 为准**。
- **目录与命名（强制）**：**后端、PC 前端、移动端**的**顶层放置位置、子应用划分、微服务/模块目录名**一律以 [L1 §七 项目目录与命名规范](./company_unified_config.md#L446-L680) 为准（§7.1 总则、§7.2 根目录、§7.3 后端、§7.4 前端、§7.5 移动端含 UniApp、§7.6–7.8）。须落实：**小写 + 短横线**的微服务名（§7.3）、`backend/` / `frontend/` / `mobile/` 一级约定、`frontend` 下 `admin`/`client` 等子应用划分、`mobile` 下全小写 app 名、§7.4 `src/` 下目录与组件 **PascalCase / kebab-case** 等规则。[L2 §二](./warehouse_shared_config.md#L49-L113) 中的 `java/`、`web/`、`app/` **不得**作为**新建**目录或**新服务命名**的依据，仅用于描述与 L1 不一致的**存量物理路径**；**新建骨架、新微服务、新前端应用、新 App 子目录**必须按 L1 字面创建（空仓库禁止用 L2 字面替代 L1 公司树）。**L1 ↔ L2 ↔ 实际** 三方对照须在 **§2.0** 当轮回复中以四列表交付；存量路径与 L1 不一致时须在表中标注 **`待用户确认迁移`** 或 **`存量仅修补`**，不得默认可长期新建在违规路径下。

### 1.1 用户习惯记录
- 每次对话开始时，应读取 [L3 §五 用户习惯记录](./local_private_config.md#L129-L172)，了解用户的历史偏好和纠正
- 用户说"记住这个""以后都这样"时，必须更新该节

---

## 二、动态加载路由表（Tier 1+）

> 收到用户问题后，AI 先判断**任务类型**，再从下表决定需要额外读取哪些配置。
> 使用 Read 工具**精确读取指定文件的对应章节**，不要全量加载。

### 路由决策流程

```
用户提问
  │
  ├─→ 判断任务类型（可多选匹配）
  │     │
  │     ├─ 【项目初始化 / 整体目录对齐】？ ──→ 见 §2.0（回复内四列表交付）
  │     ├─ 【代码编写】？           ──→ 见 §2.1（含 §2.1.1 DDL 深度审查）
  │     ├─ 【技术选型/架构】？       ──→ 见 §2.2
  │     ├─ 【Git 操作】？           ──→ 见 §2.3
  │     ├─ 【调试/排错】？          ──→ 见 §2.4
  │     ├─ 【构建/运行/部署】？      ──→ 见 §2.5
  │     ├─ 【测试】？              ──→ 见 §2.6
  │     ├─ 【纯问答/解释】？        ──→ 无需额外加载 ✅
  │     └─ 【文档生成】？           ──→ 仅当用户明确要求时处理
  │
  └─→ 根据匹配的类型，读取对应的配置片段
```

> 用户习惯读取已在 §1.1 声明，此处不重复。

### 2.0 项目整体目录对齐（执行前置 · L1 §七 命名强制）

触发关键词：`新建项目` `初始化` `脚手架` `目录对齐` `Monorepo` `仓库结构` `整体搭建` `拉齐目录` `项目骨架`

#### L1 §七、L2 §二 与物理目录的关系（必读）

| 概念 | 文件与范围 | 含义 |
|---|---|---|
| **公司规范树（唯一命名准绳）** | [L1 §七](./company_unified_config.md#L446-L680) 全文 | **后端 / PC 前端 / 移动端** 目录**怎么起名、放哪一层**只认本节：根级 `backend/`、`frontend/`、`mobile/`、`shared/`、`docs/`、`scripts/` 等（§7.2），微服务 `backend/{业务域}-{角色}/`（§7.3），前端 `frontend/admin|client|shared` 与 §7.4 `src/` 结构，移动 `mobile/{app}/` 与 UniApp 树（§7.5） |
| **技能示例树（L2）** | [L2 §二](./warehouse_shared_config.md#L49-L113) | **非命名规范**：`java/`、`web/`、`app/` 等仅为文档中的示例物理布局；**新建**服务/应用/目录时 **禁止**以 L2 字面作为合规依据 |
| **物理树** | Glob 结果 | **存量事实**；在路径与 L1 不一致时，允许在**不扩大违规命名范围**的前提下做最小修补；**新增**业务目录、新微服务、新前端子应用须在 **L1 规定路径** 下创建（空仓库 **必须** 直接按 L1 §7.2 起目录） |

**对照表（须在 §2.0 本轮回复中输出的四列表骨架；列名不变，内容须体现 L1 为强制目标）**：

| L1 §七（规范路径 · 新建须用） | L2 示例（非规范 · 勿用于新命名） | 备注 |
|---|---|---|
| `backend/{service}/`（§7.3，短横线全小写） | `java/`、`java/{service}/` | 新服务 **必须** 落在 `backend/` 下并满足 §7.3；存量 `java/` 仅记录为差异，新代码优先新路径或经用户确认迁移 |
| `frontend/admin/`、`frontend/client/`（§7.4） | `web/`、`app/` | 新 PC 前端应用 **必须** 在 `frontend/` 下建子目录；存量 `web/`/`app/` 内 **新建业务模块** 仍须遵守 §7.4 `src/` 下命名（api、views、components 等） |
| `mobile/{app}/` 及 `uniapp/` 子树（§7.5） | 同左 | App 名 **全小写**（如 `manage`、`meter`）；UniApp 子目录与 §7.5 一致 |
| `shared/openapi/` 等（§7.6） | — | 契约文件落点按 §7.6 |
| `docs/`、`scripts/`（§7.7） | 同左 | 文档与脚本目录按 §7.7 |

#### 强制执行顺序

1. **读规范**：精确 Read [L1 §七 项目目录与命名规范](./company_unified_config.md#L446-L680)（**全文**，含 §7.2–7.8：根目录、后端、前端、移动、共享模块、文档与脚本、`.gitignore`）；叠加 [L2 §二 目录与架构](./warehouse_shared_config.md#L49-L113)；再读根目录 `current_project_config.md` §二（本项目实际路径与 UniApp 根）。
2. **扫实际**：用 Glob / 目录列举核对仓库顶层及 `java/`、`web/`、`app/`、`frontend/`、`backend/`、`mobile/`、`shared/`、`docs/`、`scripts/` 等**真实存在**的路径，禁止假设尚未创建的目录。
3. **差异表**：在思考或回复中输出 **「L1 规范树 ↔ L2 示例树 ↔ 本仓库实际树」** 三方对照，标出与 **L1 §七 命名与层级** 不符的项；凡将**新建**目录、微服务、前端子应用或 `mobile` 下 app，须逐条引用 L1 条款号（§7.x）说明命名与放置。
4. **目录说明（必交付，仅对话内）**：在本轮**回复正文**中输出一张 **「L1 路径 | L2 示例路径 | 本仓库实际路径 | 对齐策略」** Markdown 四列表格（对齐策略填：`保持` / `本次新建（按 L1）` / `待用户确认迁移` / `存量仅修补` 等），并辅以简短文字说明：
   - 根目录一级结构须对照 **L1 §7.2**；**空仓库** 下 **对齐策略** 对新建一级目录应为 **「本次新建（按 L1）」**，不得优先建 `java/`/`web/` 替代 `backend/`/`frontend/`；
   - 后端、PC 前端、UniApp 根路径须标明是否符合 **§7.3 / §7.4 / §7.5**；**新建**路径必须与 L1 **字面一致**（含微服务短横线命名、前端 `frontend/admin` 等）；
   - 接口契约目录（如 `shared/openapi/`）若存在则注明；若不存在且需联调，注明计划落点（§7.6）。  
   > **禁止**因本 SKILL 在仓库内主动新建「目录结构说明」类 Markdown 文件；若用户**显式要求**落盘到某路径，仅允许该用户指定的**单一路径**，且仍须遵守 always-on「未点名不主动建 md」。
5. **与 L1 不一致时的处置**：
   - **空仓库 / 全新骨架**：**必须**按 **L1 §7.2** 创建 `backend/`、`frontend/`、`mobile/`、`shared/`、`docs/`、`scripts/` 等一级目录；**禁止**以 L2 的 `java/`+`web/` 作为公司规范替代品起盘。
   - **已有非 L1 字面路径**（如已有 `java/`、`web/`）：**禁止**在未获用户明确指令下批量重命名或移动整个业务树；**新增**微服务、新前端应用、新 `mobile` 子 app **须**在 L1 规定路径下创建（例如在 `backend/new-service/`、`frontend/admin/` 新建模块）；若用户仅要求在旧路径内修补，须在四列表标 **`存量仅修补`**，且**不得**在旧根下新增与 §7.3/§7.4 **命名规则相违**的子目录（如含大写、无短横线的服务文件夹名等）。
   - **缺项补全**：若缺少 L1 要求的 **`docs/`**、**`scripts/`** 等，可按 §7.7 **创建**（不擅自搬迁已有代码）。
6. **与后续任务衔接**：目录任务完成后，凡涉及库表、接口、页面实现，须再执行 **§2.7 交付前必复查** 中与本仓库已落地结构相关的条目。

### 2.1 代码编写

触发关键词：`写` `实现` `创建` `新增` `修改` `重构` `开发` `功能` `接口` `组件` `页面` `Activity` `Fragment` `UniApp` `uniapp` `小程序` `表格` `分页` `pageSize` `pageSizeOptions` `条/页` `弹窗` `表单` `查询` `列表` `不换行` `Select` `选择器` `allow-clear` `树` `Tree` `parent_id` `上下级`

#### 严格执行清单（代码任务落地前自检）

1. 已用 Read 读取根目录 `current_project_config.md` 中的 **项目标签（路由）** 行并完成 token 拆分。
2. 已按下方「按目标语言」表加载 **全部**「必须加载」列中的文件（可用章节 Read，**禁止**跳过项目独占 UI/数据库声明所在节）。
3. **目录与命名**：凡**新建、重命名或新增**后端/PC 前端/移动端相关目录（含微服务文件夹、`frontend` 子应用、`mobile` 下 app、`src/` 下业务模块目录等），须符合 [L1 §七](./company_unified_config.md#L446-L680) **§7.1–§7.5**（小写短横线微服务名、`backend/`/`frontend/`/`mobile/` 层级、§7.4 组件与目录命名等）；**禁止**仅以 L2 的 `java/`、`web/` 字面作为新建依据。若任务仅为存量路径内修补，须在回复中注明并仍遵守 §7.3/§7.4 命名规则。
4. **PC 管理端**：规范落点为 L1 **`frontend/`** 下子应用（如 `admin/`，§7.4）；若仓库**存量**为 `web/`、`app/` 等，实现时仍须遵守 §7.4 **`src/`** 内目录与文件命名约定，**非** `mobile/**/uniapp/`。**根目录 `current_project_config.md` 一旦包含 `### 2.2 前端`（本项目为常态）**，凡改动 PC 端 `.vue` / 表格 / 弹窗 / 查询 / 按钮等，**必须**在编码前 **Read 该节全文**（自 **§二 2.2** 起，经 **「#### 5 界面规范」** 至 **「#### 6 常用控件规范」**；其中表格/统计表/按钮/输入/时间/条件查询/表单/删除/无数据/异步加载等见 **约 L69–L125**，常用控件见 **约 L127 起**）。**条件查询**若规定 **「文案与控件不换行」**，须在查询条用 **flex-nowrap** 等落地（见 **§2.1.2**）。**禁止**仅凭 `vben3.md` / `vue3.md` 通用模板省略上述独占 UI 条款。
5. **UniApp / `mobile/**/uniapp/`**：**禁止**加载 [vben3.md](./language/vue/vben3.md)（仅 PC 管理端）；必须加载 UniApp 行所列全部引用；`mobile` 下 app 目录须 **全小写**（§7.5）。
6. 涉及数据库表结构/DDL 或 SQL/性能时，必须 Read 仓库内规范正文：`.cursor/rules/db/database-design.mdc` 与/或 `.cursor/rules/db/database-development-performance.mdc`（勿依赖损坏的相对链接猜测路径）。
7. 变更提交前执行 always-on 规定的 `lint` + `typecheck`（前端）或 `mvn compile`（后端）。
8. 若本次变更落入 **§2.7** 任一触发条件，交付前**必须**完成 §2.7 核对，并在回复摘要附带「必复查核对表」（✓ / NA / 待办）。

#### 2.1.1 DDL / 库表深度审查（database-design.mdc 落地）

> 触发：`建表` `DDL` `迁移` `COMMENT` `审计字段` `is_delete` `schema.sql` `Liquibase` `Flyway` 或与库表结构相关的评审、重构。

在已 Read `database-design.mdc` 的前提下，对**每张新建/变更表**逐项自检（回复中可摘要，冲突须标 **待办**）：

| 维度 | 要点 |
|------|------|
| **注释 §5.3.1** | PostgreSQL：`COMMENT ON TABLE` + **每一列** `COMMENT ON COLUMN`；枚举/状态写明取值；`is_delete` 写明 0/1；非 `w` 后缀表在表注释声明**不含 create_dept** |
| **主键 §4.2 / §5.2** | 默认 **单列 `id`** 类型 **BIGINT**（BIGSERIAL / IDENTITY / 雪花等）；业务展示用字符串（设备号 `device_id`、登记 `record_uid`、订单号等）须 **单独列 + UNIQUE**，**禁止**用 `VARCHAR` 占位列名 `id` 冒充 §4.2 主键；**禁止**把业务键当 `id` 却让 ORM `@TableId` 与规范 BIGINT 语义长期不一致 |
| **审计列 §4.2** | 具有**业务语义**的表：`create_time`、`create_user`、`update_time`、`update_user`、`is_delete` 齐全且列名不可替换为 `create_by`/`del_flag` 等；`create_dept` **仅**分类后缀为 **`w`** 的业务信息表必填 |
| **规范例外** | **仅** `database-design.mdc` **§4.2** 已写明的情形可省略审计列：**纯粹多对多关系表**（双外键、无独立语义），且须在 **表注释** 写明省略理由。**序号表、缓存表、Job 控制表、技术中间表**等 **不适用**「多对多」默认可免责；须 **(A)** 按上表补齐 `id` + 审计 + `is_delete`，或 **(B)** 在表注释 + 设计评审中逐条对照规范写明偏离原因并经项目确认——AI 发现 (B) 倾向时须在 §2.7 标 **待办** 或推动改为 (A) |
| **双环境 DDL** | 若项目同时维护 **H2 初始化** 与 **PostgreSQL** 脚本（如 `schema.sql` + `schema-postgresql.sql`），**须同步**结构与注释，避免一端合规一端遗漏 |
| **实体对齐** | Java/MyBatis-Plus：`@TableId` 仅绑定 **BIGINT `id`**；业务唯一键用 `selectOne(Wrappers.eq(业务列, ...))`；对外 DTO/REST 仍可用字符串业务键作 `id` 字段时，须在注释或 API 文档标明其对应库列名（如 `record_uid`），避免读者误以为数据库主键为 VARCHAR |

#### 2.1.2 项目 PC 独占 UI（根目录 `current_project_config.md` §二 2.2）

> **触发**：编辑或新增 **`frontend/**`（及存量 `web/`、`app/` 等 PC 管理端）** 的 `.vue` / 表格 / 弹窗 / 抽屉 / 查询区 / 统计块 / 按钮文案等；或用户显式提到「界面规范」「表格规范」「成堪 / vben 列表」等。

**硬要求**：

1. **必须先 Read**：仓库根目录 [`current_project_config.md`](../../../current_project_config.md) 自 **`### 2.2 前端`** 起，**经「#### 5 界面规范」至「#### 6 常用控件规范」** 的**完整**正文（行号会随文件编辑漂移；**不得以「若存在」为由跳过**——凡文件中含 `### 2.2 前端` 即视为存在）。其中 **「#### 5 界面规范」** 内 **表格 / 统计表 / 按钮 / 输入 / 时间 / 条件查询 / 表单 / 删除 / 无数据 / 异步加载** 等条款（用户规范中常见落点 **约 L69–L125**）与 **「#### 6」** 尺寸色值等，须与 **vben2 / vben3 / vue3** 语言包**同时**满足；**禁止**仅用通用 CRUD 模板色替代表格行高、分页默认、序号列、空值展示、删除确认话术、查询「文案 + 中文冒号 + 控件」等独占约定。**条件查询**小节若含 **「文案与控件不换行显示」**，须在 **查询条/筛选项** 用 **`flex` + `flex-wrap: nowrap`**（或等价布局）+ 标签 **`white-space: nowrap`** 等实现，**禁止**在常规视宽下将「标签与控件」拆成上下两行；控件区可用 **`min-width: 0` + `flex: 1`** 避免撑破栅格。**表格分页**若规定 **每页条数控件内仅显示数字、`条/页` 文案紧挨选择框右侧**（如 **约 L72**），须通过 **`pagination.buildOptionText` 仅渲染数字** + **样式后缀（如 `::after`）或等价结构** 实现，**禁止**在条数下拉项与收起态重复堆叠两处「条/页」导致歧义。
2. **根目录 §二 2.2 与 `#### 5` / `#### 6` 字面须逐项落实（与语言包并行，禁止只写「约 Lxx」而不实现）**：
   - **表格 · 分页（`#### 5`，对应正文如「每页显示条数统一支持…默认 30…数字在控件中…条/页在控件右侧…不换行」）**：列表 **`pageSize` 默认 `30`**；**`pageSizeOptions` 必须且仅能**为 **`10` / `20` / `30` / `50` / `100` / `200` / `300` / `500` / `1000`**（字符串或数字与之一致，**禁止**擅自增删档位）；**收起态**条数控件内**仅阿拉伯数字**；**「条/页」** 文案在**选择框收起态外侧、紧贴其右**，并与「跳转」等控件**同一行不换行**（Ant Design Vue 等栈：`buildOptionText` **只返回数字**；`vc-pagination` 默认会把 `items_per_page` 拼进**下拉项**——自定义 `buildOptionText` 后下拉项也须**仅为数字**，**不得**再在 option 文案里拼接第二处「条/页」；整行用 **`flex` + `nowrap`** 等防断行）。**禁止**漏配 `buildOptionText` 却仅用 CSS 遮盖，导致下拉项仍出现「数字 + 条/页」与外侧 `::after` **双重「条/页」**。**Ant Design Vue `a-table`**：`class` 通常落在 **`ant-table-wrapper`**，分页 **`ul.ant-pagination`** 在其下 **`Spin` 容器内与 `div.ant-table` 同级**（样式选择器须写 **`.ant-table-wrapper.{业务类名} .ant-pagination`**，勿误用「仅 `.ant-table` 后代」导致匹配不到分页条）。Table 注入的 **`.ant-table-pagination` 默认 `flex-wrap: wrap`**，与 **不换行**、**L73 左下角与表格左对齐**冲突，须 **`flex-wrap: nowrap !important` + `justify-content: flex-start !important`**（或与 `ant-table-pagination-left` 等效左对齐）覆盖。若 **`a-table` 设 `size="small"` 或 `middle`**，Table 渲染分页时会**覆盖传入的 pagination.size**、强制 **`Pagination` 为 `small`（mini）**，条数控件高度低于 **34px**，与 **#### 6** 及「条/页」与控件**同高对齐**冲突；表格行高若已由项目 CSS 按 §二 2.2 控制，**推荐不使用 `small|middle`**，或在复查表写明例外与补救 CSS。
   - **树（组织 / 部门-设备 / 分类树）**：**后端**须按 **`parent_id`（或等价）** 组装 **`children`**，设备/叶子挂在 **所属部门节点**下；**禁止**在存在父子部门关系时仍返回 **平级根列表**（会导致前端无法表达上下级）。**前端（Ant Design Vue `Tree`）**：`treeData` 与接口层级一致；**`show-line`**（如 `{ showLeafIcon: true }`）+ **`block-node`** 强化层级视觉；**`isLeaf`**：仅 **设备/真叶子** 为 `true`，**尚有子部门的部门节点** 须 `false`；关键字过滤时保留 **命中节点的祖先链**（避免子节点与根断开）。若需默认展开，可用 **`default-expand-all`** 或 **`v-model:expandedKeys`**；过滤后重挂载可用 **`:key`** 绑定过滤条件摘要。
   - **Select（`#### 6`，正文如「可清空单选，高度 34px，圆角 4px，宽度最小 60px」）**：凡 **单选** 且业务允许清空（含查询条件「全部」语义），须 **`allow-clear`**；**必填**单选若产品不允许清空，须在 **`提交/查询` 校验**中明确报错，并在复查表说明例外。**高度 `34px`、圆角 `4px`、`min-width: 60px`** 须在 **`ConfigProvider` token（如 `controlHeight`、`borderRadius`）+ 页面级样式** 对齐；**多选 / `mode="tags"`** 用 **`min-height: 34px`**，允许内容增高不换行策略按查询区规范。
   - **Ant Design Vue 4 + `dayjs`（与 `ConfigProvider` 配套，易漏项）**：仅配置 **`a-config-provider :locale="zh_CN"`** 往往**不足以**让 `DatePicker` / `RangePicker` / `Calendar` 面板内的**月份、星期**显示为中文——须在入口（如 `main.ts`）增加 **`import 'dayjs/locale/zh-cn'`** 与 **`dayjs.locale('zh-cn')`**（或等价 `locale` 对象中的 `locale` 字段），并视需要为控件设置 **`format`**。业务要求筛选 **「YYYY-MM」** 时，优先 **`a-date-picker picker="month" format="YYYY-MM"`**（配合已选标签多选），避免仅用 **`a-select mode="tags"`** 手敲月份。**表格/表单内展示上传图**：接口常返回 **`public-base-url` + `/uploads/...`** 的绝对 URL；若开发态 Vite **仅代理同源路径** `/uploads`，列表中应将展示地址规范化为 **`/uploads/...`**（或保证代理覆盖后端完整域名），否则易出现**裂图**；多图预览须使用 **`a-image-preview-group`** 包裹多个 **`a-image`**，以支持预览时左右切换。**`a-tree` 自定义节点字段**（如 `kind`）应挂在 **`treeData` 节点顶层**；`#title` 插槽参数在部分版本下需同时读 **`dataRef`**；若层级线/缩进异常，在业务容器内检查 **`reset.css` / 全局 `ul` 样式** 对 `.ant-tree-indent` 的影响，用窄选择器修正。
3. **交付前**：若命中 **§2.7** 触发条件 3（PC 前端），核对表中 **「PC 前端」** 行须显式勾选已对照 **§二 2.2**（不可仅写「已按 vben3」）。

#### 2.1.3 代码审查与走查（Review · 触发：`/review`、走查、审计、上线前安全核对）

> **与 §2.7 关系**：§2.7 偏「规范与契约是否落地」；本节偏「缺陷、回归、安全、测试债」的**审查方法论**。二者可同时命中；审查轮**默认只读**，**除非用户明确要求改代码**，不擅自提交实现性修复。

**输出格式（须按严重度排序，高优先在前）**：

1. **P0 / 严重**：可导致越权、数据泄露、伪造身份、绕过业务不变量的逻辑缺陷。
2. **P1 / 高**：确定或高概率 Bug、行为回归、错误数据写入、破坏幂等/唯一性。
3. **P2 / 中**：边缘条件、性能隐患（如无前缀的 `LIKE %%`、大列表无上限）、可维护性与双端不一致。
4. **P3 / 低**：缺测、文档/注释与实现偏差、演示环境已知债未标注。

**本仓库（tf-ylsw 演示栈）高频核对点**（实现替换后应删除或改写对应审查结论）：

| 域 | 核对要点 |
|---|---|
| **数据权限与身份** | `UserContextHolder.authorizedDeptIds()` **空列表 = 不限制（演示全开）**；请求头 **`X-User-Id` / `X-Auth-Depts` / `X-User-Name` 客户端可伪造**。接生产 JWT/会话后须重新定义「空列表」语义（常见：**空=无任何部门权限**），并禁止仅靠前端传头作为信任根。 |
| **HTTP 面** | 全局 **CORS** `allowedOriginPatterns("*")` 类宽放、**multipart 大小**、静态 **`/uploads`** 暴露范围；上传接口须有 **服务端** 类型/大小校验（前端校验不能替代）。 |
| **Vue 3 生命周期** | `watch` 内 **`setTimeout` 防抖**、轮询、异步 `await` 后 `ref` 赋值：组件卸载时须在 **`onBeforeUnmount`** 清理定时器/置 **取消标记**，避免卸载后改状态告警与幽灵请求。 |
| **搜索与正则** | 用户关键字进入 **`RegExp`** 前须 **转义**；超长关键字注意 ReDoS 与请求频率（防抖 + 后端分页上限）。 |
| **MP 与并发** | `@TableLogic` 下 **`selectCount`/列表** 是否自动带逻辑删除条件；业务编号若仅靠 **`synchronized`** 分配，集群/多实例下须依赖 **数据库唯一约束**（若 DDL 中唯一索引被注释，须在审查中标为 **待办**）。 |
| **测试** | 关键写路径（创建/更新/删除/409 冲突/403 权限）、导出与上传，是否有单测/接口测/手测记录；无则列入 **P3 缺测** 并建议最小用例。 |

**补充规则**：若用户指令含 **review、走查、Code Review、`/review`、安全审计**，除已触发的 §2.1.x 外，须执行本节并可在 §2.7 核对表中增加 **「Code Review」** 行（见 §2.7 表）。

#### 加载策略：按目标语言选择

| 目标语言 | 必须加载 | 文件 + 位置 |
|---|---|---|
| **Java** | 技术栈 + Java 语言约束 + **L1 §7.3 后端目录与微服务命名** | [L2 §一](./warehouse_shared_config.md#L9-L47) + [L1 §7.3](./company_unified_config.md#L504-L539) + [language/java/](./language/java/) |
| **Vue 2 / Tofly** | 技术栈 + Vue2 + **L1 §7.4** + **根目录 §二 2.2 PC 独占 UI（若该文件含 `### 2.2 前端` 则强制全文至 #### 6）** | [L2 §一](./warehouse_shared_config.md#L9-L47) + [L1 §7.4](./company_unified_config.md#L541-L590) + [language/vue/vue2.md](./language/vue/vue2.md) + [根目录 `current_project_config.md`](../../../current_project_config.md) **§二 2.2** |
| **Vue 3 / Vben 5.0** | 技术栈 + Vue3 + **L1 §7.4** + **根目录 §二 2.2 PC 独占 UI（同上）** | [L2 §一](./warehouse_shared_config.md#L9-L47) + [L1 §7.4](./company_unified_config.md#L541-L590) + [language/vue/vue3.md](./language/vue/vue3.md) + [根目录 `current_project_config.md`](../../../current_project_config.md) **§二 2.2** |
| **Vben v2 (Vue3)** | 技术栈 + Vben2 + **L1 §7.4** + **根目录 §二 2.2 PC 独占 UI（同上）** | [L2 §一](./warehouse_shared_config.md#L9-L47) + [L1 §7.4](./company_unified_config.md#L541-L590) + [language/vue/vben2.md](./language/vue/vben2.md) + [根目录 `current_project_config.md`](../../../current_project_config.md) **§二 2.2** |
| **Vben v3 (成堪数智)** | 技术栈 + Vben3 + **L1 §7.4** + **根目录 §二 2.2 PC 独占 UI（同上，与 vben3 模板联合落地）** | [L2 §一](./warehouse_shared_config.md#L9-L47) + [language/vue/vben3.md](./language/vue/vben3.md) + [L1 §7.4](./company_unified_config.md#L541-L590) + [根目录 `current_project_config.md`](../../../current_project_config.md) **§二 2.2（`### 2.2 前端` → `#### 6 常用控件规范` 全文）** |
| **UniApp（Vue 3 移动端）** | 目录约定 + 项目移动端事实 + **L1 §7.5 命名** + 通用 Vue3 语法（**不**套用 Vben 页模板） | [L1 §7.5](./company_unified_config.md#L592-L619) + 根目录 `current_project_config.md` **§二 2.3 移动端（UniApp）**（若存在）；可选节选 [language/vue/vue3.md](./language/vue/vue3.md) 中 **组合式 API / setup** 通用段落（**禁止**按其中 Ant Design Vben 管理台模板实现 UniApp 页面） |
| **Python** | Python 语言约束 | [language/python/python.md](./language/python/python.md) |
| **Android (Ylgs)** | Android 项目约定 + 代码模板 | [language/android/java.md](./language/android/java.md) |
| **TypeScript** | TS 类型严格度 | [L3 §三 TypeScript](./local_private_config.md#L86-L92) |
| **任意语言** | 个人编码习惯微调 | [L3 §三](./local_private_config.md#L61-L93) |

#### 补充规则
- 如果涉及**新建文件或目录结构**：额外加载 [L2 §二 目录结构](./warehouse_shared_config.md#L49-L113)（**仅作物理布局参考**）+ [L1 §七](./company_unified_config.md#L446-L680)（**命名与层级强制**）；新建须以 L1 为准
- 如果涉及**新建项目、微服务命名、包名设计**：额外加载 [L1 §七 项目目录与命名规范](./company_unified_config.md#L446-L680)（**全文**，含 §7.6 共享、§7.7 文档与脚本、§7.8 忽略文件）；并与 [L2 §二](./warehouse_shared_config.md#L49-L113) 对照，在**当轮回复**中写明 **L1 ↔ L2 ↔ 实际** 映射（可与 §2.0 四列表合并），禁止只读 L2 忽略 L1
- 如果涉及**后端分层架构**（Controller/Service/Repository）：额外加载 [L2 §二 架构原则](./warehouse_shared_config.md#L97-L111)
- 如果涉及**数据库设计**（建表、字段、索引、DDL）：额外加载规范正文 [database-design.mdc](../../rules/db/database-design.mdc)；索引入口 [language/database/db-design.md](./language/database/db-design.md)；并执行 **§2.1.1 DDL / 库表深度审查** 自检清单
- 如果涉及**数据库 SQL/性能/事务/分页/慢查询**：额外加载规范正文 [database-development-performance.mdc](../../rules/db/database-development-performance.mdc)；索引入口 [language/database/database_development_performance_guidelines.md](./language/database/database_development_performance_guidelines.md)
- 如果涉及 **PC 管理端界面**（`frontend/**/*.vue` 等，含列表、分页、弹窗表单、查询条、统计表、删除确认）：除对应 **vue2 / vue3 / vben2 / vben3** 语言包外，**必须**执行 **§2.1.2**，并 Read 根目录 `current_project_config.md` **§二 2.2 全文**（至 **#### 6**）；查询区须落实 **「文案 + 中文冒号 + 控件」且同一行不换行**（见 §2.1.2 第 1 条末段）。
- 如果涉及**接口设计 / REST 契约 / Controller 契约 / OpenAPI**：除 Java 语言包外，额外加载 [L2 §二 架构原则](./warehouse_shared_config.md#L97-L111) 与按需 [rules/java-tf-ylsw-backend.mdc](../../rules/java/java-tf-ylsw-backend.mdc)、[rules/java-crud-common.mdc](../../rules/java/java-crud-common.mdc)；前端侧须核对 `api/` 或项目约定请求封装路径与后端 URL 一致。
- 如果用户要求 **Code Review、`/review`、走查、安全审计**：执行 **§2.1.3**；默认**只出结论**、**不改代码**（除非用户明确要求修复）。

#### 语言检测优先级
```
用户明确提到语言/框架 > 文件扩展名(.java/.vue/.py/.ts) > 项目上下文 > 默认按项目主栈(Java+Vue)

项目标签优先匹配（来自根目录 `current_project_config.md` 的 **项目标签（路由）** 行）：
  读取字段：该行中 `/` 分隔的各 token（示例：vben3/java1、vue2/java2、vben3/java1/uniapp）
  匹配规则：按 token 映射到 `language/<lang>/<subdir>/` 或 `language/<lang>/<file>.md`；**多 token 取并集**（如同时含 vben3 与 java1 则加载两路）
  示例映射：
    java1 -> language/java/java1/
    java2 -> language/java/java2/
    java3 -> language/java/java3/
    java4 -> language/java/java4/
    java5 -> language/java/java5/
    java6 -> language/java/java6/
    vue2  -> language/vue/vue2.md
    vue3  -> language/vue/vue3.md
    vben2 -> language/vue/vben2.md
    vben3 -> language/vue/vben3.md
    uniapp -> 触发上表「UniApp」行（不映射到单个 vue 文件）
    android -> language/android/java.md
  路径命中 `mobile/**/uniapp/` 的编辑任务：即使未写 uniapp token，也**必须**按「UniApp」行加载，且**禁止**加载 vben3.md
  标签无法映射时：回退到对应语言目录的默认加载策略，并向用户确认

Java 子版本判断（当语言已判定为 Java）：
  当前项目标识包含 java2（如 vue2/java2）                      → 优先加载 language/java/java2/ 下全部 .md
  当前项目标识包含 java1                                       → 优先加载 language/java/java1/ 下全部 .md
  当前项目标识包含 java3                                       → 优先加载 language/java/java3/ 下全部 .md
  当前项目标识包含 java6（如表务 ylsw-bw / water-meter）        → 优先加载 language/java/java6/ 下全部 .md
  无法判断或子目录缺失                                         → 回退加载 language/java/ 目录下相关 .md

Vue 3 框架版本判断（**在根目录未提供「项目标签（路由）」时**才依赖本节启发式；若已提供该行，**必须以 token 为准**）：
  项目使用 defineComponent + setup() + /@/ 路径别名 + defHttp           → Vben v2 → 加载 vben2.md
  项目使用 <script setup> + #/ 路径别名 + requestClient                 → Vben 5.0 或 Vben v3
    ├─ Element Plus + EditTable + AddForm + qiankun + @ums: 权限  → Vben v3 → 加载 vben3.md
    └─ Ant Design Vue / Vben 标准组件                               → Vben 5.0 → 加载 vue3.md
  项目使用 Vue 2 + Element UI + Options API                           → Tofly Vue2 → 加载 vue2.md
  路径或 manifest 表明 UniApp（`pages.json`、`uni_modules` 等）         → 按「UniApp」行，**不**使用 vben3.md
  无法判断时 → 检查项目 package.json 和目录结构后决定，仍不明确则 **AskUserQuestion**，禁止盲选 vben3/vue3

Android 判断：
  项目标识包含 android 或项目使用 LatteActivity + ViewBinding + Fastjson  → 加载 language/android/java.md
  项目使用原生 Android / Kotlin                                        → 暂无专属约束，遵循 L1 编码底线
```

### 2.2 技术选型 / 架构决策

触发关键词：`选型` `用什么` `框架` `比较` `推荐` `架构` `设计` `方案` `技术栈``怎么样`

| 场景 | 加载内容 |
|---|---|
| 选择技术/框架/库 | [L1 §二 技术栈偏好](./company_unified_config.md#L48-L113)（首选/备选表） |
| 评估新技术是否可用 | [L1 §二 技术选型原则](./company_unified_config.md#L48-L80)（决策框架 + 硬性条件） |
| 项目内架构约定 | [L2 §二 架构原则](./warehouse_shared_config.md#L97-L111) |

### 2.3 Git 操作

触发关键词：`commit` `提交` `分支` `merge` `PR` `MR` `push` `pull` `rebase` `cherry-pick` `回滚`

| 操作类型 | 加载内容 |
|---|---|
| 提交格式 / 分支命名 | [L1 §四 Git 规范](./company_unified_config.md#L148-L167)（基础规范） |
| PR/MR 要求 / Code Review | [L1 §四 CR](./company_unified_config.md#L169-L173) + [L2 §四 项目补充](./warehouse_shared_config.md#L154-L172) |
| 仅查看 git status / diff | 无需额外加载 |

### 2.4 调试 / 排错

触发关键词：`报错` `错误` `bug` `异常` `失败` `不通` `排查` `调试` `为什么` `console` `日志` `乱码` `编码`

| 排错场景 | 加载内容 |
|---|---|
| 后端报错（Spring Boot） | [L3 §二 调试偏好](./local_private_config.md#L43-L49)（后端排错顺序） |
| 前端报错（浏览器/样式/状态） | [L3 §二 调试偏好](./local_private_config.md#L43-L49)（前端排错顺序） |
| 控制台 / 日志 **中文乱码**（尤其 Windows） | **§2.5** 下「Windows 中文乱码」段落 + [L3 §四 · Windows 终端 UTF-8](./local_private_config.md#L109-L120) |
| 涉及具体代码修改 | 同时触发 **§2.1 代码编写** 的对应语言加载 |

### 2.5 构建 / 运行 / 部署

触发关键词：`启动` `运行` `构建` `打包` `部署` `docker` `mvn` `pnpm` `npm` `install` `dev` `build` `乱码` `编码` `charset` `UTF-8` `中文乱码` `控制台`

| 操作 | 加载内容 |
|---|---|
| 启动后端服务 | [L3 §四 后端命令](./local_private_config.md#L95-L100) |
| 启动前端服务 | [L3 §四 前端命令](./local_private_config.md#L87-L93) |
| Docker 中间件 | [L3 §四 Docker](./local_private_config.md#L102-L107) |
| 完整构建流程（含 lint/test） | [L2 §三 构建命令](./warehouse_shared_config.md#L115-L151) |
| **Windows 控制台中文乱码** | 精读本节下一段「四层编码」；若仓库含 `scripts/restart-dev.ps1` 或后端 `README` 编码说明，一并 Read 并按项目脚本/配置落地，**禁止**只改业务代码却忽略 JVM/终端 |

> **Windows 中文乱码（Maven / Spring 日志 / PowerShell 输出）**  
> **成因**：控制台常为 **代码页 936（GBK）**，而源码与日志按 **UTF-8** 输出，字节被误解码即乱码。  
> **排查顺序（四层一致）**：① **终端**：`chcp 65001`、PowerShell `[Console]::OutputEncoding` / `$OutputEncoding` 为 UTF-8；② **JVM**：`-Dfile.encoding=UTF-8`（`MAVEN_OPTS`、`spring-boot-maven-plugin` 的 `jvmArguments`、`.mvn/jvm.config`）；③ **日志**：Logback 控制台 encoder 显式 `charset=UTF-8`；④ **HTTP**：`server.servlet.encoding` 等 Spring 字符集；⑤ **库**：JDBC URL / PG 客户端编码（按需）。仍异常时引导用户开启 Windows「使用 Unicode UTF-8 提供全球语言支持」或换 **Windows Terminal**。  
> **与本仓库对齐**：优先使用根目录 `scripts/restart-dev.ps1` 启动后端、PC 前端及 `mobile/manage/uniapp` 的 **`npm run dev:h5`**（UniApp H5，默认 **5174**；首次需在 `mobile/manage/uniapp` 执行 `npm install`）；后端模块见 `README` 中「Windows 控制台中文乱码」小节。

> **变更后自动验证规则**（已由 rules/always-on-rule.md §七 系统注入，此处为路由提醒）：
> - 前端改动 → 自动运行 `lint` + `typecheck`
> - 后端改动 → 自动运行 `mvn compile`

### 2.6 测试

触发关键词：`测试` `单测` `单元测试` `集成测试` `e2e` `覆盖率` `jest` `vitest` `junit` `pytest`

| 测试类型 | 加载内容 |
|---|---|
| 后端测试 | [L2 §五 后端测试](./warehouse_shared_config.md#L178-L184) |
| 前端测试 | [L2 §五 前端测试](./warehouse_shared_config.md#L186-L193) |

> ⚠️ 注意：**不在计划任务中规划测试动作**，测试仅按需执行。

### 2.7 交付前必复查（数据库 / 接口 / 多端）

> **硬要求**：凡命中下列**任一触发条件**，在结束本轮实现前必须完成核对；在回复**末尾**输出「**必复查核对表**」Markdown 表格（列：`项` | `结果` | `说明`），`结果` 仅允许 `✓`（已核对无误）、`NA`（本变更不涉及）、`待办`（已知缺口须跟进）。禁止省略该表或全填 NA 敷衍。

**触发条件**（命中即要复查，可多选）：

1. 变更或新增 **DDL / 迁移 / 实体字段影响库表**；
2. 变更或新增 **HTTP 接口**（路径、方法、参数、响应体、错误码、鉴权）或 **OpenAPI / 共享契约**；
3. 变更 **PC 前端** 调用链（`api/`、`views/` 等与后端路径或 DTO 对齐）或 **任意 PC 界面呈现**（表格/表单/弹窗等）；
4. 变更 **UniApp / 移动端** 请求封装或页面与后端契约；
5. 变更 **跨端** 同一业务的字段名、枚举、时间格式、分页参数；
6. 调整 **Monorepo 一级目录**、新建与 L1 §七相关的顶层文件夹，或**在本轮输出中修订**目录四列表对照；
7. 用户显式 **Code Review、走查、审计、`/review`**（可与 1–6 叠加；**审查轮默认不自动改代码**，除非用户另行要求实现修复）。

**核对内容**（按涉及端勾选执行；未涉及的行填 NA）：

| 项 | 复查要点 |
|---|---|
| L1/L2/物理 目录 | **新建**路径与命名符合 L1 §7.1–§7.5；四列表与 Glob 一致；未在存量根下新增违反 §7.3/§7.4 命名的子目录；未擅自批量重命名除非用户明确要求 |
| 数据库设计 | 对照 `.cursor/rules/db/database-design.mdc`：表/字段命名、主键、索引、可空性、审计字段、与 PostgreSQL/项目声明一致；**含 §2.1.1**：注释全覆盖、**`id` 须 BIGINT 代理主键**、业务字符串编号独立列、辅助表不得滥用「多对多」例外、H2/PG 双脚本一致 |
| 数据库性能 | 若含复杂 SQL、批量、事务边界：对照 `.cursor/rules/db/database-development-performance.mdc` |
| 接口与契约 | Controller / Feign / DTO 与路由到的 `rules/java-*.mdc`；URL 与前端 `api` 模块一致；统一响应与异常约定 |
| PC 前端 | 路由到的 `vben3`/`vue3`/`vue2`/`vben2` 约束 + **强制**：根目录 `current_project_config.md` **§二 2.2**（`### 2.2 前端` → **#### 5** 含分页 **DOM 选择器（`ant-table-wrapper` 下 `ul.ant-pagination`）**、**`flex-wrap: nowrap` 覆盖 Table 默认 wrap**、**默认 30**、**`pageSizeOptions` 仅** 10/20/30/50/100/200/300/500/1000、**收起态仅数字**、**「条/页」贴选择框右侧且与跳转同行**、**慎 `a-table size="small|middle"`**（会 mini 分页与 34px 冲突）；**组织/部门树**：后端 **`parent_id`→`children`**、禁止有父子部门时仍平铺根列表；前端 **`Tree`：`show-line`（如 `{ showLeafIcon: true }`）、`block-node`、`isLeaf` 区分设备与含子部门的节点、过滤保留祖先链**；→ **#### 6** 含 **Select：可清空单选 `allow-clear`、34px 高、4px 圆角、min-width 60px** 等与 token/CSS 一致；另含序号列、空值 `/`、统计表 `-`、删除二次确认、Loading、**条件查询「文案：」+ 控件且不换行**、弹窗布局等；**Ant Design Vue + dayjs**：入口 **`dayjs.locale('zh-cn')`**、`DatePicker`/`RangePicker` 的 **`format`**，避免面板英文月/周；**`/uploads` 展示 URL** 与 Vite 代理一致；**`a-image-preview-group`** 多图预览；**禁止**仅声明「按 vben3」而未对照 §2.2 |
| 后端实现 | `language/java/java{n}/` + 已加载的 `java-crud-common` / `java-tf-ylsw-backend` 等 |
| UniApp | **禁止** vben 管理台模板；L1 §7.5 + 根目录 §二 2.3 |
| 多端一致性 | 同一业务字段、状态码、日期格式、分页 `current/size` 等与各端一致 |
| Code Review | 命中 **触发条件 7** 或用户要求审查时：按 **§2.1.3** 严重度输出发现项；区分 **演示环境已知语义** 与 **上线前须修**；将 **缺测、性能、防抖/卸载清理** 等单独列出，避免与「规范未读」混为一谈 |

---

## 三、配置文件索引

| 层级 | 文件 | 权重 | 主要用途 | 预估大小 |
|---|---|---|---|---|
| **Rules** | [rules/always-on-rule.md](../../rules/always-on-rule.md) | 系统注入 | 行为规范、安全红线、沟通风格、编码质量底线、全局禁用、SKILL路由强制、变更验证 | ~120 行 |

| **Rules** | [rules/java-crud-common.mdc](../../rules/java/java-crud-common.mdc) | 系统/按需 | Java CRUD 通用规范（分层、SQL/XML、Mapper、实体、Swagger、注入） | ~80 行 |
| **Rules** | [rules/java-tf-ylsw-backend.mdc](../../rules/java/java-tf-ylsw-backend.mdc) | 按需 | tf-ylsw MUST/SHOULD（ResultRespone、ToFlyAppLog、Wrappers/XML 等） | ~130 行 |
| **Rules** | [rules/java-pom-governance.mdc](../../rules/java/java-pom-governance.mdc) | 按需 | Maven 多模块 POM 必须/禁止/推荐 | ~35 行 |
| **L1+** | [language/java/](./language/java/) | 27 | Java skill 目录（`java1/`～`java6/`、`pom-factory-skill.md`）；**通用条文以 `rules/java-*.mdc` 为准** | ~500+ 行 |
| **L1+** | [language/vue/vue2.md](./language/vue/vue2.md) | 25 | Tofly Vue2 详细约束与模板 | ~240 行 |
| **L1+** | [language/vue/vue3.md](./language/vue/vue3.md) | 25 | Vue 3 + Vben Admin 5.0 详细约束与模板 | ~260 行 |
| **L1+** | [language/vue/vben2.md](./language/vue/vben2.md) | 25 | Vben Admin v2 CRUD 页面生成技能 | ~1180 行 |
| **L1+** | [language/vue/vben3.md](./language/vue/vben3.md) | 25 | Vben v3 成堪数智 CRUD 页面生成技能 | ~1189 行 |
| **L1+** | [language/python/python.md](./language/python/python.md) | 25 | Python 编码规范 | ~20 行 |
| **L1+** | [language/android/java.md](./language/android/java.md) | 25 | Android (Ylgs) 项目约定与代码模板 | ~260 行 |
| **Rules** | [rules/database-design.mdc](../../rules/db/database-design.mdc) | 按需 | 数据库设计规范（命名、表字段索引、跨库兼容） | ~330 行 |
| **Rules** | [rules/database-development-performance.mdc](../../rules/db/database-development-performance.mdc) | 按需 | 数据库开发与性能约束（SQL、分页、事务、慢 SQL） | ~320 行 |
| **L1+** | [language/database/db-design.md](./language/database/db-design.md) | 25 | 数据库设计**索引**（指向 `rules/database-design.mdc`） | ~10 行 |
| **L1+** | [language/database/database_development_performance_guidelines.md](./language/database/database_development_performance_guidelines.md) | 25 | 数据库性能规范**索引**（指向 `rules/database-development-performance.mdc`） | ~10 行 |
| **L2** | [warehouse_shared_config.md](./warehouse_shared_config.md) | 75 | 项目技术栈、架构约定、构建命令、Git 补充、测试约定 | ~240 行 |
| **L3** | [local_private_config.md](./local_private_config.md) | 100 | 本地环境、个人偏好、用户习惯记录 | ~225 行 |

### 各文件核心章节速查锚点

```
Rules (系统注入，始终生效)
  always-on-rule.md  行为规范 + 安全红线 + 沟通风格 + 编码质量底线 + 全局禁用 + SKILL路由强制 + 变更验证  系统注入

L1 (公司统一配置)
  §一  安全红线（只读）              # L9-L46
  §二  技术选型原则 + 技术栈偏好      # L48-L113
  §三  编码质量底线                  # L116-L144
  §四  Git 规范 + CR 标准            # L148-L173
  §五  协作沟通 + AI 行为             # L177-L326
  §六  前端通用规范                  # L329-L443
  §七  项目目录与命名规范（canonical）  # L446-L680（含 7.6–7.8）
  §八  语言约束索引                  # L682-L698
  §九  与 L2/L3 的关系               # L699-L719

L1+ language/ (语言约束，按需加载)
  java/            Java 规则目录（读取目录内全部 .md）
  android/java.md  Android (Ylgs) 项目约定与代码模板  全文
  rules/database-design.mdc           数据库设计规范（跨数据库通用）  规范正文
  rules/database-development-performance.mdc  数据库开发与性能约束  规范正文
  database/db-design.md             数据库设计索引（入口）
  database/database_development_performance_guidelines.md  数据库性能索引（入口）
  python/python.md  Python                        全文
  vue/vue2.md       Tofly Vue2                    全文
  vue/vue3.md       Vue 3 + Vben Admin 5.0           全文
  vue/vben2.md      Vben Admin v2 CRUD 页面生成       全文
  vue/vben3.md      Vben v3 成堪数智 CRUD 页面生成（**仅 PC**，与 UniApp 互斥）  全文；**须与根目录 `current_project_config.md` §二 2.2 联合落地**（§2.1.2）
  （UniApp）         L1 §7.5（L592-L619）+ 根目录 current_project_config §二 2.3；**禁止** vben3 管理台模板

L2 (仓库共享配置)
  §一  项目技术栈                    # L9-L47
  §二  目录结构与架构约定             # L49-L113
  §三  构建与开发命令                 # L115-L151
  §四  Git 协作补充                  # L154-L172
  §五  测试约定                      # L176-L194
  §六  项目特定知识库                 # L197-L209
  §七  与 L1/L3 的关系               # L213-L241

L3 (本地私有配置)
  §一  工作行为规范                  # L10-L34
  §二  本地开发环境偏好              # L36-L59
  §三  个人编码习惯微调              # L61-L93
  §四  常用快捷操作映射              # L96-L124
  §五  用户习惯记录                  # L127-L171
  §六  与 L1/L2 的关系               # L173-L212
```

---

## 四、三层权重体系与约束分类

> 权重覆盖规则和安全红线摘要已由 `rules/always-on-rule.md` 系统注入，此处仅保留索引和分类说明。

```
L3 本地私有配置 (权重:100) ← 最高优先级，覆盖 L1/L2
    ↓ 覆盖
L2 仓库共享配置 (权重:75)  ← 项目级技术事实 + 架构约定
    ↓ 覆盖
L1 公司统一配置 (权重:25)  ← 安全红线（只读不可覆盖）+ 技术规范 + 语言约束
```

### 约束分类

| 类别 | 示例 | 层级 |
|---|---|---|
| 安全红线 | 禁止硬编码密钥、SQL注入防护 | L1（只读） |
| 编码底线 | 命名自解释、单一职责、DRY | L1 |
| 技术选型原则 | 活跃维护、社区规模、安全记录 | L1 |
| 技术栈偏好 | React/Vue 选择、工具链配置 | L1 |
| 项目事实 | Java 17 + Vue 3 + Spring Cloud | L2 |
| 语言详细规范 | Java 命名约定、Vue2/Vben2/Vue3 组件模板、Tofly 约束、Android 约束、数据库设计规范 | L1 language/*/ |
| 项目目录命名 | 根目录命名（pcs-/sds-）、微服务模块命名、前后端移动端目录结构 | L1 |
| 本地环境 | 端口配置、调试习惯、注释偏好 | L3 |

### 自动化机制（已实现）
- **规则自动注入**：rules/ 目录下的硬性规则由系统自动注入，无需 AI 主动读取
- **权重覆盖**：冲突时自动选择高优先级规则（详见 rules/always-on-rule.md §六）
- **动态路由**：按任务类型精确加载配置片段
- **质量门禁**：前端改动自动运行 `lint` + `typecheck`，后端运行 `compile`（详见 rules/always-on-rule.md §七）
- **用户习惯记录**：L3 §五 持续学习和更新

---

## 五、配置文件职责边界

| 层级 | 文件 | 核心职责 | 独有内容 |
|---|---|---|---|
| **Rules** | rules/always-on-rule.md | 系统自动注入的硬性规则与路由强制 | 行为规范、安全红线、沟通风格、编码质量底线、全局禁用、SKILL路由强制、变更验证 |
| **L1** | company_unified_config.md | 安全红线完整版 + 技术选型原则 + 编码底线 + 沟通 AI 行为 + 项目目录与命名规范 | 安全红线（只读）、Git 规范、技术栈偏好、目录命名规范 |
| **L1+** | language/*/*.md | 各语言详细编码规范和框架约束 | Java 命名/分层、Tofly 约束、Vue2/Vben2/Vue3 组件模板、Android 约束、数据库设计规范 |
| **L2** | warehouse_shared_config.md | 项目技术事实 + 团队共识 | 具体技术栈、架构约定、构建命令、PR 补充 |
| **L3** | local_private_config.md | 本地环境 + 个人偏好 + 用户习惯 | 调试习惯、注释偏好、习惯记录 |

**职责划分原则**：
- **Rules（rules/）**定义"每次对话必须遵守的硬性规则"，由系统自动注入
- L1 定义"原则与底线 + 语言约束"，语言细节委托 language/*/
- L2 声明项目技术事实和团队共识
- L3 仅定义本地临时偏好和个人习惯，不重复上层内容

---

## 六、Token 消耗估算

| 任务类型 | 需加载内容 | 额外 Token（估算） |
|---|---|---|
| **项目初始化 / 目录对齐** | 入口 + L1 §七（L446-L680）+ L2 §二 + 根目录 current_project_config §二 + **回复内**四列表交付 | ~+200~450 行 |
| **纯问答 / 解释** | 入口 + L3 §五（用户习惯） | **~+10 行**（基线 ~40 行，规则已由 rules/ 注入不计入） |
| **写 Java 代码** | 入口 + L2 §一 + language/java/（目录内相关 .md）+ L3 §三 + L3 §五 | ~+130~700+ 行（按读取范围） |
| **写 Vue 2 代码** | 入口 + L2 §一 + language/vue2.md + L3 §三 + L3 §五 | ~+130 行 |
| **写 Vue 3 代码** | 入口 + L2 §一 + language/vue3.md + L3 §三 + L3 §五 | ~+260 行 |
| **写 Vben v2 代码** | 入口 + L2 §一 + language/vben2.md + L3 §三 + L3 §五 | ~+1180 行 |
| **写 Vben v3 代码** | 入口 + L2 §一 + vben3.md + 根目录 current_project_config §二 2.2 前端（若存在）+ L3 §三 + L3 §五 | ~+1189+ 行 |
| **写 Android 代码** | 入口 + language/android/java.md + L3 §三 + L3 §五 | ~+260 行 |
| **写 UniApp 代码** | 入口 + L1 §7.5 UniApp + 根目录 current_project_config 移动端节 + L3 §三 + L3 §五（可选 vue3 节选） | ~+80~350 行 |
| **写 Python 脚本** | 入口 + language/python.md + L3 §三 + L3 §五 | ~+30 行 |
| **数据库设计** | [database-design.mdc](../../rules/db/database-design.mdc) + 索引 db-design.md | ~+330 行 |
| **数据库性能/SQL** | [database-development-performance.mdc](../../rules/db/database-development-performance.mdc) + 索引 database_development_performance_guidelines.md | ~+320 行 |
| **Git 提交** | 入口 + L1 §四 + L3 §五 | ~+30 行 |
| **调试排错** | 入口 + L3 §二 + L3 §五 | ~+20 行 |
| **启动服务** | 入口 + L3 §四 + L3 §五 | ~+30 行 |
| **技术选型讨论** | 入口 + L1 §二 + L2 §二 + L3 §五 | ~+90 行 |
| **新建项目/目录** | 入口 + L1 §七 目录与命名规范 + L2 §二 | ~+200 行 |
| **全量加载（最差情况）** | 全部文件 + language/ | ~+2900 行（应避免）|

> **对比**：4层架构版全量加载约 945 行；3层架构版纯问答仅 **~40 行**（规则已由 rules/ 注入），写代码约 **170-200 行**。

---

## 七、使用指南

### AI Agent 使用流程

```
1. 系统自动注入 rules/ 下的硬性规则（行为规范、安全红线、沟通风格等）
2. 加载本文件（SKILL.md）获取路由表
3. 读取仓库根目录 current_project_config.md 的「项目标签（路由）」行及与本任务相关的技术事实节（如 2.2 前端 / 2.3 移动端 / 数据库）
4. 若为 **§2.0 目录初始化/对齐**：按 §2.0 顺序执行并在**本轮回复**中交付四列表
5. 读取 L3 §五 用户习惯记录，了解历史偏好
6. 收到用户问题后判断任务类型
7. 根据路由表精确加载对应配置片段（代码任务对照 §2.1「严格执行清单」）
8. 执行任务时遵循权重覆盖规则（已由 rules/ 注入）
9. 完成后运行质量门禁（lint/typecheck/compile，已由 rules/ 注入）；若命中 **§2.7** 触发条件，输出「必复查核对表」；若命中 **§2.7 触发条件 7** 或 **§2.1.3**，在正文优先输出 **按严重度排序的审查结论**（默认不改代码）
10. 如用户有新偏好，更新 L3 §五 用户习惯记录
11. 简要总结做了什么
```

### 配置维护指南

| 场景 | 应修改的文件 | 示例 |
|---|---|---|
| 行为/安全/沟通规则变更 | rules/always-on-rule.md | 新增禁止行为、调整沟通风格 |
| 公司安全策略变更 | L1（安全红线部分） | 新增禁止使用的依赖 |
| 技术栈偏好调整 | L1 §二 | 从 React 切换到 Vue |
| 语言/框架编码规范 | language/xxx.md | 更新 Java 命名约定 |
| 项目技术栈升级 | L2 §一 | Spring Boot 2.x → 3.x |
| 项目构建命令变更 | L2 §三 | 新增 Docker Compose 服务 |
| 公司目录/命名规范变更 | L1 §七 | 新增行业标识、调整目录结构 |
| 本地调试临时配置 | L3 | 开启 verbose 日志 |
| 项目路由 token 与根目录事实变更 | 根目录 `current_project_config.md` 的 **项目标签（路由）** 行及 §二 | 与 L2 冲突时以根目录为准 |
| 用户习惯/偏好记录 | L3 §五 | "记住数组用 List 后缀" |

### 冲突解决原则

```
1. 安全红线（L1 §一）优先级最高，任何层级不可覆盖
2. 根目录 current_project_config.md 中已声明的本项目技术事实（数据库种类、组件栈、独占 UI、UniApp 根路径等）优先于 L2 warehouse_shared_config.md 及 L1 非安全章节；不得用 L2 的「通用技术栈表」覆盖之。**后端/PC 前端/移动端的目录命名与层级**以 **L1 §七** 为强制规范；`current_project_config` 中路径描述用于业务事实时，**新建**代码仍须在 L1 允许的路径与命名规则下落地（与 §2.0 一致）。**L1 §七 顶层字面**与物理仓库不一致时，以 **§2.0 当轮已给出的四列表映射 + 已存在代码路径** 为存量依据；**新增**服务与应用须按 L1 创建，不得擅自批量重命名存量根目录，除非用户在对话中**明确指令**迁移并接受风险。
3. L3 本地私有配置（含用户习惯）在**不违反**第 1、2 条的前提下优先于 L2/L1 其余内容
4. 同一内容在不同层级出现时，在符合上述顺序下高权重层级优先
5. 同层级内隐式冲突时，遵循"后定义覆盖先定义"原则
6. 无法确定时，主动询问用户确认，禁止猜测框架版本
```

---

*最后更新：2026-05-15*
*版本：5.5.0（新增 §2.1.3 Code Review 严重度输出与本仓库高频核对表；§2.7 触发条件 7 +「Code Review」核对行；执行流第 9 步衔接审查）*