xykj-plus/claude-ecc/AGENTS.md

# AGENTS.md

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

## 仓库概览

本仓库是一个 monorepo，包含两个相互独立的子项目：

- `admin-xy/` —— 企业管理系统，后端（Spring Boot 3 + Java 21）+ 前端（React 18 + Vite + TypeScript），统一通过 Docker Compose 部署。
- `log-analyzer/` —— 纯前端（Vite + React + TypeScript）工具，用于解析 `.Codex/logs/` 下的 hook trace JSONL 文件，通过 Vite 自定义插件 `logApiPlugin` 暴露 `/api/folders`、`/api/files` 等接口读取本地日志。

两个子项目互不依赖，构建命令、依赖、部署方式都应分别执行。

## 常用命令

### admin-xy 后端（`admin-xy/server`）

```bash
# 本地运行（默认 dev profile，H2 内存库 + Flyway 迁移，端口 9010）
mvn spring-boot:run

# 打包（跳过测试）
mvn -DskipTests clean package

# 运行全部测试
mvn test

# 运行单个测试类 / 单个方法
mvn test -Dtest=AuthServiceTest
mvn test -Dtest=AuthServiceTest#shouldLoginWithValidCredentials
```

- 入口：`com.adminxy.AdminXyApplication`
- 数据库迁移：`src/main/resources/db/migration/V*.sql`（Flyway 管理，`ddl-auto=validate`，**禁止**改已发布的 V 脚本，新增请递增版本号）
- Profile：默认 `dev`（H2）；生产通过 `SPRING_PROFILES_ACTIVE=prod` 切到 MySQL，连接与密钥全部来自环境变量（`SPRING_DATASOURCE_ADMIN_*`、`JWT_SECRET`）。

### admin-xy 前端（`admin-xy/web`）

```bash
npm install
npm run dev       # Vite dev server，端口 9001，/api 反代到 http://localhost:9010
npm run build     # tsc 严格类型检查 + vite build
npm run preview
```

- 路径别名：`@` → `admin-xy/web/src`
- 状态管理：Zustand（`src/stores/`），表单：react-hook-form + Zod，UI：Radix + Tailwind（shadcn 风格，组件放 `src/components/ui`）

### admin-xy 整体部署（`admin-xy/`）

```bash
./build-images.sh                # 构建 admin-xy-server:latest、admin-xy-web:latest
./build-images.sh --no-cache

sudo ./deploy.sh                 # 生产部署：初始化 /opt/admin-xy → 构建镜像 → docker compose up
sudo ./deploy.sh --stop          # 停止并移除容器
sudo ./deploy.sh --restart       # 重启容器（不重建镜像）
```

生产配置存放于 `/opt/admin-xy/.env`（首次运行 `deploy.sh` 会生成模板）。`deploy.sh` 会把本目录下的 `docker-compose.yml` 同步到 `/opt/admin-xy/`。

### log-analyzer（`log-analyzer/`）

```bash
npm install
npm run dev       # Vite dev server；自定义插件读取 ../.Codex/logs
npm run build     # tsc -b && vite build
```

## 架构要点

### admin-xy 后端分层（Spring Boot）

```
com.adminxy
├── AdminXyApplication          # 启用 @EnableJpaAuditing
├── common/                     # ApiResponse<T>、PageResult<T>、BaseEntity、全局异常
├── config/                     # SecurityConfig、CorsConfig、JwtProperties、DataInitializer
├── security/                   # JwtAuthenticationFilter、JwtTokenProvider、CustomUserDetailsService
├── permission/                 # 权限注解/校验
└── module/
    ├── auth/   ├── user/   ├── role/   └── menu/
        └── 每个模块：Entity + Repository + Service + Controller + dto/
```

重要约定：

- **统一响应**：所有 REST 接口返回 `ApiResponse<T>`（`success/data/error/meta`）；分页用 `PageResult<T>`。
- **认证**：JWT 无状态模式（`SessionCreationPolicy.STATELESS`），CSRF 禁用；`JwtAuthenticationFilter` 从 `Authorization: Bearer <token>` 提取并注入 `SecurityContext`；401 走 `RestAuthenticationEntryPoint`。
- **授权**：`@EnableMethodSecurity` 开启，方法级权限用 `@PreAuthorize` + 自定义 `permission/` 下的校验器。
- **模块划分**：按领域（user/role/menu/auth）分包，每个模块自包含 Controller→Service→Repository→Entity→DTO 一条链，跨模块调用通过 Service 接口而不是 Repository。
- **迁移优先**：表结构一律通过 Flyway V 脚本创建；Entity 注解只做 `validate`，不允许 `update`/`create`。

### admin-xy 前端组织

```
src/
├── main.tsx / routes/          # 路由（react-router-dom v6，含 guards.tsx 做鉴权守卫）
├── pages/                      # 按业务页面：login/dashboard/user/role/menu
├── components/
│   ├── ui/                     # 原子组件（shadcn 风格，封装 Radix）
│   ├── layout/                 # AppShell、侧边栏等
│   └── common/                 # 业务通用组件
├── stores/                     # Zustand：auth-store（token/user）、app-store（全局 UI 状态）
├── schemas/                    # Zod 校验 schema
├── hooks/、lib/、types/         # 复用 hook、axios 实例与工具、共享类型
```

关键约定：

- axios 实例在 `src/lib/` 统一拦截请求头（JWT）和响应错误（401 登出、统一 toast）。
- 所有跨页面状态走 Zustand store，不要用 Context 做可变状态。
- 表单流程：Zod schema → `@hookform/resolvers/zod` → react-hook-form → API 调用。

### log-analyzer 的特殊之处

Vite 配置里内置了 `logApiPlugin`（`vite.config.ts`）——**这是本地日志浏览的后端**。它在 dev server 中间件里暴露 `/api/folders`、`/api/files`、`/api/file`，直接读取仓库根的 `.Codex/logs/`（向上一级解析）。修改日志读取逻辑需同时改 Vite 插件与前端调用方。

### `.Codex/` 目录

- `.Codex/hooks/trace.mjs` —— 所有 Codex hook 事件都通过它写入 `.Codex/logs/trace-<session_id>.jsonl`。关键约束：**必须**把日志写到 `trace.mjs` 自身所在目录的 `../logs`，不能依赖 `cwd`，否则会在各子项目下生成多余 `.Codex/logs`（已在此之前修复过一次）。
- `.Codex/rules/common/*.md` + `.Codex/rules/typescript/*.md` —— 项目级规范，会在对话中以 system reminder 形式注入，遵循即可，不要额外复述。
- `.Codex/logs/` —— 明确加入 git 追踪（见 `.gitignore` 的 `!.Codex/logs/`），用于 log-analyzer 复现会话。

## 开发约定（本仓库特有）

- **Git 远程**：默认 push 到 Gitee（`https://gitee.com/xiangyuetech-d/Codex-ecc.git`）。提交信息按 `.Codex/rules/common/git-workflow.md` 的 Conventional Commits 风格（`feat|fix|refactor|docs|test|chore|perf|ci: <desc>`），**不要**追加自动归因尾行。
- **端口**：后端 9010、前端 9001；前端 dev server 的 `/api` 反代到后端 9010。改端口要同步更新 `vite.config.ts`、`docker-compose.yml`、`application.yml`。
- **密钥**：`JWT_SECRET` 至少 32 字节；生产所有敏感配置必须来自环境变量或 `/opt/admin-xy/.env`，不得硬编码进 yml/代码。
- **前端不允许 `console.log`**：已在 hooks 中配置自动检测，请使用 sonner / 已有 logger 替代。
- **日志写入**：任何新加的 hook 脚本若要写文件，沿用 `trace.mjs` 的做法——以脚本自身路径定位，避免写到子项目目录。