# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

医梦AI OKR绩效考核系统 — an internal performance review system using OKR (40%) + KPI (60%) dual-model scoring, tree-based reporting hierarchy, and split-panel UI. Single JAR deployment with embedded SQLite.

## Development Commands

### Frontend (Vue 3 + Vite + Element Plus)

```bash
cd frontend
npm install                    # first time only
npm run dev                    # dev server on :5173, proxies /api to :18080
npm run build                  # production build → dist/
```

### Backend (Spring Boot 3.2 + Maven)

```bash
cd backend
mvn spring-boot:run            # dev mode, expects data/ dir at project root
mvn clean package -DskipTests  # produces target/okr-performance-1.0.0.jar
```

### Full build & run

```bash
./scripts/start.sh             # builds frontend → copies to backend/static → packages → java -jar
```

Backend starts on port **18080**. Default super-admin: `admin` / `emoon123456`.

### Data

SQLite database at `data/okr-performance.db`. WAL mode enabled. Schema auto-created on startup from `backend/src/main/resources/schema.sql`. Delete the `.db` file to reset all data.

## Architecture

### Backend Layers (package: `com.emoon.okr`)

```
controller/  → REST endpoints, delegates to services
service/     → business logic, transactional
mapper/      → MyBatis-Plus BaseMapper interfaces (no XML — annotations only)
entity/      → database entities with MyBatis-Plus @TableName
dto/         → request/response objects, ApiResult<T> wrapper
security/    → JwtTokenProvider, JwtAuthenticationFilter, SecurityUtils
config/      → SecurityConfig (permitAll /api/auth/**, auth required for /api/**),
               DatabaseInitializer (runs schema.sql), DataInitializer (seed admin user),
               MybatisPlusConfig (pagination plugin), MyMetaObjectHandler (auto-fill time fields)
exception/   → BusinessException + GlobalExceptionHandler (@RestControllerAdvice)
schedule/    → PeriodScheduler (daily 2am auto-advances period statuses)
enums/       → UserRole, PeriodStatus, PeriodType, KrStatus, Grade, ScoreType, ObjectiveType
```

### API Pattern

- Base path: `/api/*`
- Response wrapper: `ApiResult<T>` with `code` (200 = success), `message`, `data`
- Auth: JWT Bearer token. `/api/auth/**` is public, all other `/api/**` require authentication.
- `SecurityUtils.getCurrentUserId()` provides the authenticated user's ID in services.

### Frontend Structure

```
src/router/index.js   → hash-mode routes, auth guard on all except /login
src/api/index.js      → axios instance (baseURL /api), per-module API functions
src/stores/auth.js    → Pinia auth store (accessToken, refreshToken, user)
src/components/       → shared components (MainLayout.vue is the shell with sidebar)
src/views/
  auth/LoginView      → login/register
  period/             → assessment period management, KPI templates
  okr/MyOkrView       → personal OKR editing
  scoring/            → ScoringListView (subordinate list), ScoringEditView (split-panel), MyResultView
  feedback/           → interview notes / reply
  org/OrgView         → department tree, user management (super-admin only)
  system/LogView      → operation log viewer
```

### Key Design Decisions

- **Single JAR deployment**: Vue build output is copied into `backend/src/main/resources/static/` before packaging. Spring Boot serves it as static resources.
- **Soft delete**: Entities use `deleted` field (MyBatis-Plus logic-delete, 0=active, 1=deleted).
- **Snapshot archival**: OKR objectives and KPI configs write `snapshot_json` at archive time — historical data survives later edits.
- **Audit corrections**: Score modifications are logged in `audit_correction` table before changing `performance_score` — "不可修改" semantics via audit trail.
- **Period state machine**: DRAFT → OKR_ALIGN → EXECUTING → ASSESSING → ARCHIVED. Manual triggers from admin, auto-advance at 2am for period-end transitions.
- **Permissions**: Not role-based. Derived from `sys_user.superior_id` tree — having subordinates grants review/scoring rights over direct reports. `role=SUPER_ADMIN` bypasses all checks.
- **Responsive split-panel**: Scoring pages use side-by-side layout at ≥1440px (48%/52%), stacked layout below — SSR not required, CSS media queries only.

### Theme

Primary: `#2b1f99` (deep indigo, sidebar/accents), Secondary: `#3ad4d8` (teal, highlights/CTA). Sidebar width: 220px.

<!-- superpowers-zh:begin (do not edit between these markers) -->
# Superpowers-ZH 中文增强版

本项目已安装 superpowers-zh 技能框架（20 个 skills）。

## 核心规则

1. **收到任务时，先检查是否有匹配的 skill** — 哪怕只有 1% 的可能性也要检查
2. **设计先于编码** — 收到功能需求时，先用 brainstorming skill 做需求分析
3. **测试先于实现** — 写代码前先写测试（TDD）
4. **验证先于完成** — 声称完成前必须运行验证命令

## 可用 Skills

Skills 位于 `.claude/skills/` 目录，每个 skill 有独立的 `SKILL.md` 文件。

- **brainstorming**: 在任何创造性工作之前必须使用此技能——创建功能、构建组件、添加功能或修改行为。在实现之前先探索用户意图、需求和设计。
- **chinese-code-review**: 中文 review 沟通参考——话术模板、分级标注（必须修复/建议修改/仅供参考）、国内团队常见反模式应对。仅在用户显式 /chinese-code-review 时调用，不要根据上下文自动触发。
- **chinese-commit-conventions**: 中文 commit 与 changelog 配置参考——Conventional Commits 中文适配、commitlint/husky/commitizen 中文模板、conventional-changelog 中文配置。仅在用户显式 /chinese-commit-conventions 时调用，不要根据上下文自动触发。
- **chinese-documentation**: 中文文档排版参考——中英文空格、全半角标点、术语保留、链接格式、中文文案排版指北约定。仅在用户显式 /chinese-documentation 时调用，不要根据上下文自动触发。
- **chinese-git-workflow**: 国内 Git 平台配置参考——Gitee、Coding.net、极狐 GitLab、CNB 的 SSH/HTTPS/凭据/CI 接入差异与镜像同步配置。仅在用户显式 /chinese-git-workflow 时调用，不要根据上下文自动触发。
- **dispatching-parallel-agents**: 当面对 2 个以上可以独立进行、无共享状态或顺序依赖的任务时使用
- **executing-plans**: 当你有一份书面实现计划需要在单独的会话中执行，并设有审查检查点时使用
- **finishing-a-development-branch**: 当实现完成、所有测试通过、需要决定如何集成工作时使用——通过提供合并、PR 或清理等结构化选项来引导开发工作的收尾
- **mcp-builder**: MCP 服务器构建方法论 — 系统化构建生产级 MCP 工具，让 AI 助手连接外部能力
- **receiving-code-review**: 收到代码审查反馈后、实施建议之前使用，尤其当反馈不明确或技术上有疑问时——需要技术严谨性和验证，而非敷衍附和或盲目执行
- **requesting-code-review**: 完成任务、实现重要功能或合并前使用，用于验证工作成果是否符合要求
- **subagent-driven-development**: 当在当前会话中执行包含独立任务的实现计划时使用
- **systematic-debugging**: 遇到任何 bug、测试失败或异常行为时使用，在提出修复方案之前执行
- **test-driven-development**: 在实现任何功能或修复 bug 时使用，在编写实现代码之前
- **using-git-worktrees**: 当需要开始与当前工作区隔离的功能开发或执行实现计划之前使用——创建具有智能目录选择和安全验证的隔离 git 工作树
- **using-superpowers**: 在开始任何对话时使用——确立如何查找和使用技能，要求在任何响应（包括澄清性问题）之前调用 Skill 工具
- **verification-before-completion**: 在宣称工作完成、已修复或测试通过之前使用，在提交或创建 PR 之前——必须运行验证命令并确认输出后才能声称成功；始终用证据支撑断言
- **workflow-runner**: 在 Claude Code / OpenClaw / Cursor 中直接运行 agency-orchestrator YAML 工作流——无需 API key，使用当前会话的 LLM 作为执行引擎。当用户提供 .yaml 工作流文件或要求多角色协作完成任务时触发。
- **writing-plans**: 当你有规格说明或需求用于多步骤任务时使用，在动手写代码之前
- **writing-skills**: 当创建新技能、编辑现有技能或在部署前验证技能是否有效时使用

## 如何使用

当任务匹配某个 skill 时，使用 `Skill` 工具加载对应 skill 并严格遵循其流程。绝不要用 Read 工具读取 SKILL.md 文件。

如果你认为哪怕只有 1% 的可能性某个 skill 适用于你正在做的事情，你必须调用该 skill 检查。
<!-- superpowers-zh:end -->