kintone-customize-manager/AGENTS.md

AGENTS.md

Kintone Customize Manager - Electron + React 应用，用于管理 Kintone 自定义资源。

1. 构建命令

# 开发（HMR + 热重载）
npm run dev

# 类型检查
npx tsc --noEmit

# 构建
npm run build

# 打包
npm run package:win    # Windows
npm run package:mac    # macOS
npm run package:linux  # Linux

# 代码质量
npm run lint           # ESLint 检查
npm run format         # Prettier 格式化

# 测试
npm test               # 运行测试
npm run test:watch     # 监听模式
npm run test:coverage  # 测试覆盖率

重要: 修改 src/main/ 目录下的文件后，必须运行 npm test 确保测试通过。

2. 项目架构

src/
├── main/           # Electron 主进程
│   ├── index.ts          # 入口，创建窗口
│   ├── ipc-handlers.ts   # IPC 处理器（所有通信入口）
│   ├── storage.ts        # 文件存储 + 密码加密
│   ├── kintone-api.ts    # Kintone REST API 封装
│   └── __tests__/        # 主进程测试
├── preload/        # Preload 脚本
│   ├── index.ts          # 暴露 API 到渲染进程
│   └── index.d.ts        # 类型声明
├── shared/         # 跨进程共享代码
│   └── types/            # 共享类型定义
├── renderer/       # React 渲染进程
│   └── src/
│       ├── main.tsx      # React 入口
│       ├── App.tsx       # 根组件
│       ├── components/   # React 组件
│       └── stores/       # Zustand Stores
└── tests/          # 测试配置
    ├── setup.ts          # 测试环境设置
    └── mocks/            # Mock 文件

3. 路径别名

别名	路径
@renderer/*	src/renderer/src/*
@main/*	src/main/*
@preload/*	src/preload/*
@shared/*	src/shared/*

4. 代码风格

导入顺序

// 1. Node.js 内置模块
import { join } from "path";
import { app, BrowserWindow } from "electron";

// 2. 第三方库
import React, { useState, useEffect } from "react";
import { Button, Layout } from "antd";

// 3. 项目内部模块（别名）
import { useDomainStore } from "@renderer/stores";

// 4. 相对导入
import "./styles.css";

命名规范

• 组件文件/名: PascalCase (e.g., DomainManager.tsx)
• 工具函数文件: camelCase (e.g., formatDate.ts)
• Store 文件: camelCase + Store (e.g., domainStore.ts)
• 函数/变量: camelCase (e.g., handleSubmit)
• 常量: UPPER_SNAKE_CASE (e.g., MAX_FILE_SIZE)
• 类型/接口: PascalCase (e.g., DomainConfig)

TypeScript 规范

• 显式类型定义，避免 any
• 使用字面量联合类型（如 authType: "password" | "api_token"）
• 异步函数返回 Promise<T>
• 使用类型守卫处理 unknown

React 组件规范

• Hooks 放在组件顶部
• 事件处理函数使用 useCallback
• 使用 TypeScript 显式定义 props 类型

Zustand Store 规范

• 使用 persist 中间件持久化状态
• 定义接口明确 state 和 actions 类型

5. IPC 通信规范

type Result<T> = { success: true; data: T } | { success: false; error: string };

• IPC 调用使用 invoke 返回 Result<T>
• Preload 通过 contextBridge.exposeInMainWorld 暴露 API

6. UI 组件规范

UI Kit 优先使用 LobeHub UI (@lobehub/ui)，其次使用 Ant Design 6 + antd-style：

import { Button } from '@lobehub/ui';
import { createStyles } from 'antd-style';

// antd-style 仅用于自定义样式
export const useStyles = createStyles(({ token, css }) => ({
  container: css`padding: ${token.paddingLG}px;`
}));

• 国际化：使用日文默认 import jaJP from 'antd/locale/ja_JP'
• 禁止使用 Tailwind

7. 安全规范

• 密码使用 electron 的 safeStorage 加密存储
• WebPreferences 必须：contextIsolation: true, nodeIntegration: false, sandbox: false

8. 错误处理

• 所有 IPC 返回 Result<T> 格式
• 渲染进程检查 result.success 处理错误

9. fnm 环境配置

所有 npm/npx 命令需加载 fnm 环境：

# 使用 fnm wrapper（推荐）
~/.config/opencode/node-fnm-wrapper.sh npm run dev

# 或手动加载 fnm
eval "$(fnm env --use-on-cd)" && npm run dev

10. 注意事项

1. ESM Only: LobeHub UI 仅支持 ESM
2. React 19: 使用 @types/react@^19.0.0
3. CSS 方案: 使用 antd-style，禁止 Tailwind
4. 禁止 as any: 使用类型守卫或 unknown
5. 函数组件优先: 禁止 class 组件

11. 沟通规范

1. 人设: 在回答的末尾加上「🦐」，用于确认上下文是否被正确保留
2. 语言: 使用中文进行回答

12. MVP Phase - Breaking Changes

This is MVP phase - breaking changes are acceptable for better design. However, you MUST:

• Explain what will break and why: Document which components/APIs/workflows will be affected
• Compare old vs new approach: Show the differences and improvements
• Document the tradeoffs: What are the pros and cons of this change
• Ask for confirmation: If the change is significant (affects multiple modules or core architecture)
• 对于代码修改，必须将相关的、不再需要的代码全部删除，不需要保留，保持代码洁净

Examples of acceptable breaking changes during MVP:

• Refactoring data structures for better type safety
• Changing IPC communication patterns
• Restructuring component hierarchy
• Modifying store architecture
• Updating API interfaces

Process for breaking changes:

1. Identify the change and its impact scope
2. Document the breaking change in code comments
3. Explain the reasoning and benefits
4. If significant, ask user for confirmation before implementing
5. Update related documentation after implementation

13. 测试规范

测试框架

使用 Vitest 作为测试框架，与 Vite 原生集成。

测试文件结构

src/main/__tests__/    # 主进程测试
tests/
├── setup.ts           # 全局测试设置
└── mocks/
    └── electron.ts    # Electron API Mocks

测试要求

1. 修改 src/main/ 目录下的文件后，必须运行 npm test 确保测试通过
2. 新增 API 功能时，应在 src/main/__tests__/ 中添加对应测试
3. 测试文件命名：*.test.ts

Mock Electron API

测试中需要 Mock Electron 的 API（如 safeStorage、app 等），已在 tests/mocks/electron.ts 中提供。

// tests/setup.ts 中自动 Mock
vi.mock("electron", () => import("./mocks/electron"));