jsharness 1.0.0

package/.harness/dev-map/frontend/state-management.md

@@ -0,0 +1,170 @@
+# 前端分区 — 状态管理方式
+
+## 当前方案
+
+本项目采用 **Pinia** 作为主要状态管理方案（Vue 官方推荐）。
+
+### 为什么选择 Pinia
+
+| 对比项 | Vuex 4 | Pinia | 选择原因 |
+|--------|-------|-------|----------|
+| 样板代码 | 多 (mutations/actions) | 极少（无 mutation） | 减少样板代码 |
+| Bundle Size | ~5KB (gzip) | ~1KB (gzip) | 更小的包体积 |
+| TypeScript 支持 | 需要额外装饰器 | 原生推断优秀 | 类型推断更自然 |
+| DevTools | Vue DevTools 原生集成 | Vue DevTools 原生集成 | 足够用 |
+| 学习曲线 | 较陡 | 平极低（与 Composition API 一致） | 降低上手门槛 |
+| Vue3 组合式友好度 | ★★ | ★★★★★ | 与 `<script setup>` 风格一致 |
+
+## Store 结构
+
+```
+stores/
+├── modules/
+│   ├── useAuthStore.ts      # 认证状态（token, user info）
+│   ├── useUIStore.ts        # UI 状态（sidebar, theme, modals）
+│   └── useUserStore.ts      # 用户相关缓存
+├── index.ts                 # Pinia 实例创建与统一导出
+└── types.ts                 # Store 类型定义
+```
+
+## Store 编写规范
+
+```typescript
+// stores/modules/useAuthStore.ts
+import { defineStore } from 'pinia';
+import type { User } from '@/types/user';
+import { authService } from '@/api/auth';
+
+interface AuthState {
+  user: User | null;
+  token: string | null;
+  isAuthenticated: boolean;
+}
+
+export const useAuthStore = defineStore('auth', {
+  state: (): AuthState => ({
+    user: null,
+    token: '',
+    isAuthenticated: false,
+  }),
+
+  getters: {
+    isLoggedIn: (state): boolean => !!state.token && !!state.user,
+    userName: (state): string => state.user?.name ?? '匿名用户',
+    userRoles: (state): string[] => state.user?.roles ?? [],
+  },
+
+  actions: {
+    async login(credentials: LoginCredentials) {
+      const result = await authService.login(credentials);
+      this.token = result.accessToken;
+      this.user = result.user;
+      this.isAuthenticated = true;
+    },
+
+    logout() {
+      this.$reset(); // Pinia 内置重置方法
+    },
+
+    updateUser(data: Partial<User>) {
+      if (this.user) {
+        Object.assign(this.user, data);
+      }
+    },
+  },
+});
+```
+
+## 数据获取策略
+
+### 服务端状态管理 — Pinia + Composable 封装
+
+Vue3 项目使用 **Pinia Store** 管理服务端状态，配合 **Composable** 封装数据获取逻辑：
+
+```typescript
+// composables/useUserList.ts
+import { useAuthStore } from '@/stores/modules/useAuthStore';
+
+/**
+ * 用户列表 Composable
+ * 封装列表查询、分页、刷新等逻辑
+ */
+export function useUserList(params?: Ref<UserListParams>) {
+  const authStore = useAuthStore();
+
+  // 响应式数据
+  const loading = ref(false);
+  const error = ref<Error | null>(null);
+
+  // 使用 computed 自动追踪参数变化
+  const listParams = params || ref({ page: 1, pageSize: 20 });
+
+  const { data: userList, refresh } = useFetch('/api/v1/users', {
+    queryParams: listParams,
+    immediate: true,
+  });
+
+  const pagination = computed(() => ({
+    page: listParams.value.page,
+    pageSize: listParams.value.pageSize,
+    total: userList.value?.total ?? 0,
+  }));
+
+  return {
+    userList: computed(() => userList.value?.list ?? []),
+    pagination,
+    loading,
+    error,
+    refresh,
+    changePage: (page: number) => { listParams.value.page = page; },
+  };
+}
+```
+
+### Query Key 设计规范（Pinia Store 模块化）
+
+```typescript
+// 标准：按业务域拆分 Store
+stores/
+├── modules/
+│   ├── useUserStore.ts         # 用户域
+│   ├── useOrderStore.ts        # 订单域
+│   ├── useProductStore.ts      # 商品域
+│   └── useNotificationStore.ts # 通知域
+
+// 层级关系：
+// useUserStore → 管理用户相关所有状态（列表/详情/权限）
+// useOrderStore → 管理订单相关所有状态（列表/详情/统计）
+
+// 跨 Store 依赖：
+// useOrderStore 可以调用 useUserStore 的 getter 获取用户信息
+```
+
+### 缓存策略
+
+| 数据类型 | 缓存方式 | 过期策略 | 示例 |
+|---------|---------|---------|------|
+| 用户基本信息 | Pinia State + persist 插件 | 登录时刷新 / 手动 invalidate | 用户名、头像、角色 |
+| 字典/枚举数据 | Pinia State + staleTime | 应用生命周期内有效（不频繁变化） | 性别选项、订单状态码 |
+| 列表数据 | Composable (useFetch) | 组件卸载时释放 / 下拉刷新 | 订单列表、消息列表 |
+| 表单临时状态 | `ref()` / `reactive()` 组件内 | 组件销毁即清除 | 表单输入、弹窗开关 |
+
+## 状态流转图
+
+```
+┌─────────────┐  API 调用  ┌─────────────────┐  写入  ┌──────────────┐
+│ Server State │ ◄──────── │  Pinia Store     │ ──────► │   Server     │
+│ (Pinia)     │  缓存     │  (defineStore)   │        │   API        │
+└─────────────┘           └─────────────────┘        └──────────────┘
+       ▲                           │
+       │ 读取                      │ action
+┌──────┴──────┐                   ▼
+│ Component   │           ┌─────────────────┐
+│ (Vue3 SFC)  │ ─────────► │ Local State     │
+└─────────────┘  直接访问   │ (ref/reactive)  │
+                       ┌───┴─────────────────┴───┐
+                       │   URL Route (vue-router) │
+                       │   DOM Ref               │
+                       │   Local component state │
+                       └─────────────────────────┘
+```

package/.harness/dev-map/frontend/structure.md

@@ -0,0 +1,103 @@
+# 前端分区 — 目录结构与路由约定
+
+## 目录结构详情
+
+```
+src/
+├── app/                          # Next.js App Router（页面与布局）
+│   ├── layout.tsx                # 根布局（Header/Footer/Provider）
+│   ├── page.tsx                  # 首页 (/)
+│   ├── loading.tsx               # 全局 Loading 态
+│   ├── error.tsx                 # 全局错误边界
+│   ├── not-found.tsx             # 404 页面
+│   │
+│   ├── (auth)/                   # 认证页面组（不含 Header）
+│   │   ├── layout.tsx            # Auth Layout（简洁版）
+│   │   ├── login/page.tsx        # 登录页 (/login)
+│   │   ├── register/page.tsx     # 注册页 (/register)
+│   │   └── forgot-password/page.tsx # 忘记密码 (/forgot-password)
+│   │
+│   ├── (dashboard)/              # 看板页面组（含侧边栏）
+│   │   ├── layout.tsx            # Dashboard Layout
+│   │   ├── page.tsx              # 看板首页 (/dashboard)
+│   │   ├── settings/page.tsx     # 设置页 (/dashboard/settings)
+│   │   └── profile/page.tsx      # 个人资料 (/dashboard/profile)
+│   │
+│   └── api/                      # API Routes
+│       ├── auth/
+│       │   └── [...nextauth]/route.ts    # NextAuth 处理
+│       ├── users/route.ts                # 用户 API
+│       └── [feature]/route.ts            # 功能 API
+│
+├── components/
+│   ├── ui/                        # [通用 UI 组件](./components.md)
+│   │   ├── button/
+│   │   ├── input/
+│   │   ├── modal/
+│   │   ├── table/
+│   │   └── index.ts               # 统一导出
+│   │
+│   ├── features/                  # [业务功能组件](./components.md)
+│   │   ├── user-card/
+│   │   ├── data-chart/
+│   │   └── ...
+│   │
+│   └── layouts/                   # 布局组件
+│       ├── MainLayout.tsx
+│       ├── AuthLayout.tsx
+│       └── DashboardLayout.tsx
+│
+├── lib/                          # 库级配置
+│   ├── api-client.ts             # [API 调用客户端](./api-integration.md)
+│   ├── auth.ts                   # 认证工具
+│   └── utils.ts                  # 通用工具函数
+│
+├── hooks/                        # 自定义 Hooks
+│   ├── use-auth.ts              # 认证 Hook
+│   ├── use-api.ts              # API 请求 Hook
+│   └── use-debounce.ts         # 防抖 Hook
+│
+└── types/                        # TypeScript 类型定义
+    ├── user.ts
+    ├── api.ts
+    └── index.ts
+```
+
+## 路由约定
+
+### URL 格式规范
+
+```
+# 页面路由
+/login                          → 登录
+/dashboard                      → 看板首页
+/dashboard/settings/:tab       → 设置（带 Tab 参数）
+/users/[id]                    → 用户详情（动态路由）
+/users/[id]/edit              → 编辑用户
+
+# API 路由
+/api/v1/users                  → 用户列表 (GET) / 创建用户 (POST)
+/api/v1/users/:id              → 用户详情 (GET) / 更新 (PUT) / 删除 (DELETE)
+
+# 路径命名规则
+- 使用 kebab-case: /user-profile, /order-history
+- 动态参数使用方括号: /[id], /:slug
+- 可选搜索参数用 ? 分隔: /orders?status=pending&page=1
+```
+
+### 路由分组规则
+
+| 分组名 | 路由前缀 | 共享布局 | 特征 |
+|--------|----------|----------|------|
+| `(auth)` | `/login`, `/register`, ... | AuthLayout | 无导航栏，居中表单 |
+| `(dashboard)` | `/dashboard/*` | DashboardLayout | 含侧边栏，需认证 |
+| `(public)` | `/`, `/about`, ... | MainLayout | 公开访问，含导航栏 |
+| `(admin)` | `/admin/*` | AdminLayout | 管理后台，需管理员权限 |
+
+### 中间件顺序
+
+```
+请求进入 → i18n 检测 → 认证检查 → 权限校验 → 数据预取 → 页面渲染
+                                    ↓ 不通过
+                              重定向到登录/403
+```

package/.harness/dev-map/overview.md

@@ -0,0 +1,267 @@
+# dev-map — 项目开发导航地图
+
+> **维护原则：谁改代码谁更新地图。** 地图过期会导致 AI 引用错误信息，影响整体开发效率。
+> **最后更新**: 2026-05-21 (对齐 java-backend.md + frontend-vue3.md 规则)
+
+---
+
+## 一句话描述
+
+{项目名称} 是一个面向 {目标用户} 的 **Vue3 + Spring Boot(MyBatis-Plus)** 全栈应用，提供 {核心价值主张}。
+
+## 技术栈速查
+
+### 前端层
+
+| 层 | 技术 | 版本 | 用途 |
+|----|------|------|------|
+| UI 框架 | Vue 3 + Composition API | ^3.4.x | 响应式渲染（强制 `<script setup>`） |
+| 构建工具 | Vite | ^5.x | 开发服务器 / 打包 |
+| 状态管理 | Pinia | ^2.x | 跨组件状态（官方推荐） |
+| UI 组件库 | Element Plus | ^2.x | 企业级 UI 组件 |
+| CSS 方案 | SCSS (scoped) | - | 样式系统 |
+| HTTP 客户端 | Axios | ^1.x | API 调用（拦截器封装） |
+| 路由管理 | Vue Router | ^4.x | 页面路由（懒加载） |
+| 测试框架 | Vitest | ^1.x | 单元测试 |
+| 包管理器 | pnpm | 9.x | 依赖管理 |
+
+### 后端层 (Java — com.jieshun)
+
+| 层 | 技术 | 版本 | 用途 |
+|----|------|------|------|
+| 运行时 | JDK (Virtual Threads) | 21 | Java 环境，虚拟线程并发 |
+| 框架 | Spring Boot | 3.2.x | 服务端框架 |
+| ORM / 数据访问 | **MyBatis-Plus** | 3.5.x | SQL 映射（Mapper 接口 + XML）|
+| 数据库 | MySQL | 8.0+ | 主数据存储（utf8mb4）|
+| 缓存 | Redis + Redisson | 5.x / 6.x | 缓存（仅缓存用途）/ 分布式锁 |
+| 配置中心 / 注册中心 | **Nacos** | 2.x | 动态配置拉取 / 服务发现 |
+| 认证 | JWT + Opaque Refresh Token | - | 身份验证 (Spring Security) |
+| API 文档 | **Knife4j (Swagger/OpenAPI 3)** | - | 接口文档自动生成（@Tag/@Operation）|
+| 工具简化 | Lombok | 1.18.x | @Data/@RequiredArgsConstructor 等 |
+| 工具库 | Hutool | 5.x | 通用工具（按需引入）|
+| 加密 | 国密 SM4 + bcrypt | - | 敏感数据加密 / 密码哈希 |
+| 容器测试 | Testcontainers | - | MySQL/Redis 集成测试隔离 |
+
+### 质量保障工具链
+
+| 维度 | 工具 | 说明 |
+|------|------|------|
+| 单元测试 | JUnit 5 + Mockito 5 | Java 测试框架 + Mock |
+| 覆盖率 | JaCoCo | Maven 插件集成，0% 文件告警，行覆盖率 ≥80% |
+| 代码风格 | Checkstyle 10.x | Google/Sun 规则集（checkstyle.xml）|
+| 复杂度扫描 | PMD 7.x | 圈复杂度 / 代码异味（pmd-ruleset.xml）|
+| Bug 模式检测 | SpotBugs 4.8+ | NPE / 资源泄漏等 Bug 模式 |
+| 持续质检 | SonarQube 9.9+ LTS | Quality Gate 阻断 + 技术债追踪 |
+| API 测试 | REST Assured 5.x | DSL 风格接口测试（MockMvc 对接）|
+| 服务端 Mock | WireMock 3.x | 下游依赖 Stub / 契约测试基础 |
+| 分页插件 | MyBatis-Plus PageHelper | 分页拦截器自动追加 LIMIT |
+| 前端 Lint | ESLint + Prettier | TS / 代码格式检查 |
+| 前端构建 | TypeScript (tsc) | 类型严格检查（strict mode）|
+
+### 基础设施
+
+| 层 | 技术 | 用途 |
+|----|------|------|
+| CI/CD | Jenkins (Maven Pipeline) | 自动化构建部署 |
+| 容器化 | Docker + Docker Compose | 本地开发（MySQL + Redis + App）|
+| 编排 | Kubernetes (可选) | 生产环境运行时 |
+| 制品库 | Nexus / Artifactory | Maven 依赖代理 |
+
+## 目录结构概览
+
+```
+project-root/                          # 项目根目录
+│
+├── backend/                           # ══════ Java 后端微服务 ══════
+│   ├── pom.xml                        #   父 POM（统一依赖版本管理）
+│   │
+│   ├── app/                           #   启动入口模块
+│   │   ├── pom.xml
+│   │   └── src/main/java/com/jieshun/app/
+│   │       ├── JscicdApplication.java #     @SpringBootApplication
+│   │       └── config/                #     启动级配置（WebMvcConfig 等）
+│   │
+│   ├── domain/                        #   业务核心模块（最重）
+│   │   ├── pom.xml
+│   │   └── src/main/java/com/jieshun/domain/
+│   │       ├── controller/            #     Controller 层（只做路由+校验+权限）
+│   │       │   ├── admin/             #       后台管理 Controller
+│   │       │   │   └── UserController.java
+│   │       │   └── app/               #       用户侧 Controller（C 端）
+│   │       │       └── AppUserController.java
+│   │       ├── service/               #     Service 层（业务编排）
+│   │       │   ├── UserService.java   #       接口定义
+│   │       │   └── impl/              #       实现类子包（禁止放接口）
+│   │       │       └── UserServiceImpl.java
+│   │       ├── mapper/                #     Mapper 层（纯接口，SQL 在 XML）
+│   │       │   ├── UserMapper.java    #       不继承 BaseMapper
+│   │       │   └── xml/               #       MyBatis XML 映射文件
+│   │       │       └── UserMapper.xml
+│   │       ├── data/                  #     数据对象层
+│   │       │   ├── entity/            #       DO（@TableName 映射）
+│   │       │   │   └── UserDO.java
+│   │       │   ├── vo/                #       视图对象
+│   │       │   │   ├── UserRespVO.java      # 响应对象（脱敏后返回前端）
+│   │       │   │   └── UserCreateReqVO.java  # 请求对象（JSR303 校验）
+│   │       │   └── dto/               #       数据传输对象（跨层传递）
+│   │       │       └── UserDTO.java
+│   │       └── enums/                 #     枚举定义
+│   │           └── UserStatusEnum.java
+│   │
+│   ├── integration/                   #   第三方集成模块
+│   │   ├── pom.xml
+│   │   └── src/main/java/com/jieshun/integration/
+│   │       ├── client/                #     外部 API 客户端
+│   │       │   └── sms/SmsClient.java
+│   │       └── mq/                    #     消息队列
+│   │           └── producer/MqProducer.java
+│   │
+│   ├── common/                        #   公共工具模块
+│   │   ├── pom.xml
+│   │   └── src/main/java/com/jieshun/common/
+│   │       ├── constant/              #     常量
+│   │       │   ├── ErrorCodeConstants.java  # 错误码枚举（7 个段）
+│   │       │   └── RedisKeyConstants.java   # Redis Key + TTL 定义
+│   │       ├── exception/             #     异常定义
+│   │       │   └── JscicdBizException.java # 业务异常基类
+│   │       ├── util/                  #     工具类
+│   │       └── enums/                 #     通用枚举
+│   │
+│   ├── src/test/java/                 #   单元测试 / 集成测试（JaCoCo 收集）
+│   └── src/main/resources/            #   全局资源
+│       ├── bootstrap.yml              #     本地最小配置（仅 Nacos 地址）
+│       ├── application.yml            #     主配置
+│       └── mapper/                    #     MyBatis XML
+│           └── user/UserMapper.xml
+│
+├── frontend/                          # ══════ Vue3 前端项目 ══════
+│   ├── package.json
+│   ├── vite.config.ts
+│   ├── tsconfig.json
+│   ├── index.html
+│   │
+│   └── src/
+│       ├── api/                       # API 接口封装层
+│       │   ├── client.ts              #   Axios 实例（拦截器/Token注入/统一错误处理）
+│       │   ├── modules/               #   按业务模块拆分的 API 调用
+│       │   │   └── user.ts            #     UserAPI = { page(), create(), ... }
+│       │   └── types/                 #   API TS 类型定义
+│       │       └── user.d.ts          #     ReqVO / RespVO 类型
+│       │
+│       ├── assets/                    # 静态资源
+│       │   ├── styles/                #   全局样式（variables.css / reset.css / global.css）
+│       │   └── images/                #   图片资源
+│       │
+│       ├── components/                # 可复用组件
+│       │   ├── ui/                    #   通用 UI 组件（无业务逻辑）
+│       │   │   ├── Button/Button.vue
+│       │   │   └── Modal/
+│       │   └── business/              #   业务组件（含业务逻辑）
+│       │       └── UserProfileCard/
+│       │
+│       ├── pages/                     # 页面级组件（路由对应，懒加载）
+│       │   ├── user/
+│       │   │   ├── UserList.vue        #   列表页
+│       │   │   ├── UserDetail.vue      #   详情页
+│       │   │   └── UserCreate.vue      #   创建/编辑页
+│       │   └── dashboard/
+│       │
+│       ├── router/                    # 路由配置
+│       │   ├── index.ts               #   路由实例 + 首屏
+│       │   ├── routes/                #   按模块拆分的路由定义
+│       │   │   ├── user.ts
+│       │   │   └── dashboard.ts
+│       │   └── guards/                #   导航守卫（权限校验/登录拦截）
+│       │       └── auth.ts
+│       │
+│       ├── store/                     # Pinia Store
+│       │   ├── index.ts               #   Store 入口
+│       │   └── modules/               #   按业务模块拆分
+│       │       ├── user.ts            #     useUserStore
+│       │       └── app.ts             #     useAppStore
+│       │
+│       ├── types/                     # 全局共享 TS 类型
+│       │   ├── user.d.ts
+│       │   ├── api.d.ts
+│       │   └── env.d.ts
+│       │
+│       ├── utils/                     # 工具函数
+│       │   ├── format.ts
+│       │   ├── request.ts
+│       │   └── storage.ts
+│       │
+│       ├── composables/               # 组合式函数（Vue3 Hooks）
+│       │   ├── useAuth.ts
+│       │   ├── usePagination.ts
+│       │   └── usePermission.ts
+│       │
+│       ├── layouts/                   # 布局组件
+│       │   ├── DefaultLayout.vue      #   默认布局（Header + Sidebar + Content）
+│       │   └── BlankLayout.vue        #   空白布局（登录页等）
+│       │
+│       └── App.vue                    # 根组件
+│
+├── checkstyle.xml                     # Checkstyle 规则集
+├── pmd-ruleset.xml                    # PMD 规则集
+│
+├── .harness/                          # ══════ Harness Engineering 规范体系 ══════
+│   ├── gate/checks/                   #   门禁（路由器 + build-gates-frontend.js + build-gates-java.js）
+│   ├── skills/                        #   技能文档（build/test-unit/lint-check/test-api/test-e2e 双章节）
+│   ├── workflow/definition.yaml       #   工作流定义（条件引用 java-build | vue-frontend-build）
+│   ├── mcp/config.yaml                #   MCP 工具注册（SonarQube/Maven/Jenkins）
+│   ├── agents/                        #   Agent 契约（输出含 .java / *Test.java）
+│   ├── rules/project/                 #   项目规则集
+│   │   ├── java-backend.md            #     后端规范（四层架构/Mapper/XML/SM4/Nacos/VT）
+│   │   └── frontend-vue3.md           #     前端规范（Composition API/Pinia/Element Plus/TS）
+│   └── dev-map/                       #   本文档所在位置
+│
+├── docker-compose.yml                  # 本地开发容器编排（MySQL 8 + Redis + App Server）
+├── tests/                              # E2E / 手动测试用例
+└── files/                              # 外部参考文档源
+```
+
+> **后端基础包名**: `com.jieshun`（禁止 `com.jscicd` 或 `com.example`）  
+> **后端依赖方向**: controller → service → mapper → database（禁止反向/跨层跳跃）  
+> **前端强制要求**: Composition API `<script setup lang="ts">`，禁止 Options API
+
+## 功能域落点表
+
+| 功能域 | 前端页面目录 | 后端模块路径 | 说明 |
+|--------|-------------|------------|------|
+| 用户管理 | `frontend/src/pages/user/` | `backend/domain/controller/app/` + `service/user/` | 注册 / 登录 / 个人信息 |
+| 用户管理(后台) | `frontend/src/pages/admin/user/` | `backend/domain/controller/admin/user/` | 后台用户 CRUD / 分页 |
+| 认证授权 | `frontend/src/pages/auth/` | `backend/domain/security/` + `integration/client/sms/` | JWT 双 Token / 短验证码 / OAuth |
+| 核心业务 A | `frontend/src/pages/{domain-a}/` | `backend/domain/service/{domainA}/` + `mapper/{domainA}/` | 待填充 |
+| 核心业务 B | `frontend/src/pages/{domain-b}/` | `backend/domain/service/{domainB}/` + `mapper/{domainB}/` | 待填充 |
+| 系统管理 | `frontend/src/pages/admin/` | `backend/domain/controller/admin/` + `common/enums/` | 后台管理 / 字典 / 角色 |
+| 公共基础 | `frontend/src/components/ui/` | `backend/common/(constant/exception/util)` | 通用组件 / 错误码 / 异常 / 工具 |
+
+## 各分区入口指引
+
+| 分区 | 文件路径 | 内容概要 |
+|------|----------|----------|
+| 🖥️ 前端分区 | [frontend/](./frontend/) | 目录结构、组件规范、状态管理(Pinia)、编码惯例([conventions.md](./frontend/conventions.md))、Vite配置、Element Plus用法 |
+| 🔧 后端分区 (Java) | [backend/](./backend/) | Maven 四层模块(app/domain/integration/common)、MyBatis-Plus Mapper+XML、REST API 规范(@Tag/@Operation)、安全机制(SM4/脱敏)、Nacos 配置、JDK21 虚拟线程、Java 编码惯例([conventions-java.md](./backend/conventions-java.md)) |
+| 🏗️ 基础设施分区 | [infra/](./infra/) | CI/CD (Jenkins Maven Pipeline)、Docker Compose、环境变量、监控 |
+| 📝 决策记录 | [decisions.md](./decisions.md) | 技术决策 ADR（含双技术栈架构/Gate分流/Workflow去路由/Java工具链选型/Pinia选型等）|
+
+### Harness 流程规范索引
+
+| 规范层级 | 入口 | 与本项目的对应关系 |
+|---------|------|-------------------|
+| ⚡ Gate 门禁 | `.harness/gate/checks/` | 自动检测 pom.xml→Java门禁(build-gates-java.js: mvn compile/test/checkstyle/spotbugs/jacoco) / package.json→前端门禁(build-gates-frontend.js: tsc/npm/eslint/audit) |
+| 📘 Skills 技能 | `.harness/skills/` | test-unit(JUnit5+Mockito+JaCoCo)/lint-check(Checkstyle+PMD+SpotBugs+SonarQube)/test-api(REST Assured+WireMock)/test-e2e(Testcontainers+Spring Profiles) 均含 Java 章节；build 已废弃→分流到 java-build / vue-frontend-build |
+| 🔄 Workflow | `.harness/workflow/definition.yaml` | 条件引用 `java-build \| vue-frontend-build`；output_formats 含 .java；rules 引用 java-backend.md + frontend-vue3.md |
+| 🤖 Agents | `.harness/agents/` | Developer contract 输出格式含 .java / *Test.java；编码流程含双技术栈说明；质量要求双列（前端标准/后端Java标准）|
+| 🔌 MCP 工具 | `.harness/mcp/config.yaml` | 注册 SonarQube(metrics/quality_gate)、Maven(dependency_info/central_search)、Jenkins(maven_job_status) 工具定义 |
+| 📋 Rules | `.harness/rules/project/` | **java-backend.md**(四层架构/9种类后缀/Mapper纯接口/SM4加密/Nacos/VT/22项审查清单) + **frontend-vue3.md**(Composition API强制/Pinia/Element Plus/TS类型安全/7项禁止清单) 双规则集 |
+
+## 维护纪律
+
+1. **新增功能域** → 更新「功能域落点表」+ 对应分区文档
+2. **修改目录结构** → 同步更新「目录结构概览」和对应分区文档
+3. **技术选型变更** → 在 decisions.md 中记录 ADR
+4. **新增 Maven 插件** → 同步更新「质量保障工具链」表 + skills 相关章节
+5. **Gate/Skill 变更** → 同步更新「Harness 流程规范索引」表
+6. **每次版本发布** → 检查所有文档是否与代码一致
+7. **Rules 规则修订** → 同步刷新 tech stack 表和目录结构中对应的描述