XYKJ/xykj-plus

Fork 0

liuhuayong 7e90ae7e14 fix: add actual files (remove submodule refs)

2026-06-13 13:48:51 +08:00

7.0 KiB

Raw Blame History

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`）

# 本地运行（默认 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`）

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/`）

./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/`）

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

7.0 KiB Raw Blame History Unescape Escape