132 lines
7.0 KiB
Markdown
132 lines
7.0 KiB
Markdown
# 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` 的做法——以脚本自身路径定位，避免写到子项目目录。
|