# 项目记忆包 — go_win_template

> 此目录为 AI 辅助开发项目的记忆索引。
> 核心工具：**CodeGraph**（代码知识图谱），用于快速检索项目符号和调用关系。
> 当 `.codegraph/` 目录存在时，优先使用 CodeGraph 探索代码，而非 grep/find。

---

## 📋 项目概述

| 属性 | 值 |
|------|-----|
| 项目类型 | Wails v2 + React + TypeScript 桌面应用 |
| 目标平台 | Windows (amd64) |
| 框架版本 | Wails v2.16.0 |
| 前端框架 | React 19 + Vite 7 + TypeScript 5 |
| Go 版本 | Go 1.25.0 |

### 技术栈
- **后端**: Go 原生，Wails IPC (进程内通信，不走 HTTP)
- **前端**: React + TypeScript + Vite
- **系统托盘**: Windows Win32 API (`shell32.dll::Shell_NotifyIconA`)
- **插件系统**: build tag 控制编译，`config/plugin.json` 运行时配置
- **支付模块**: HTTP 客户端 + 自动 token 续期 + HMAC 签名
- **高并发**: 任务池、批量处理器、限流器、环形缓冲、管道

---

## 🕸️ CodeGraph 使用指南

### 安装状态
```
已全局安装: @colbymchenry/codegraph@1.6.0
项目索引: .codegraph/ (25 files, 431 nodes, 947 edges)
MCP 集成: opencode (已配置)
```

### 核心命令

```bash
# 初始化/重建索引
codegraph init [path]

# 查看项目文件结构
codegraph files

# 查看索引状态和统计
codegraph status

# 搜索符号
codegraph query <search_term>

# 探索代码区域（源码 + 调用路径）—— 最常用的命令
codegraph explore "<topic>"

# 构建任务上下文（相关符号、关系、代码块）
codegraph context "<task>"

# 查看单个符号的源码和调用链
codegraph node <symbol_name>

# 查找谁调用了某个函数
codegraph callers <symbol>

# 查找某个函数调用了什么
codegraph callees <symbol>

# 分析修改某符号的影响范围
codegraph impact <symbol>

# 查找受影响的测试文件
codegraph affected [files...]

# 更新索引（增量同步）
codegraph sync
```

### 典型工作流

```bash
# 开发新功能前，先构建上下文
codegraph context "实现新的插件功能"

# 查看关键入口函数的完整调用链
codegraph node "App.Startup"

# 探索某个模块的架构
codegraph explore "payment service architecture"

# 修改代码前确认影响范围
codegraph impact "CreateUser"
```

### 在 AI 对话中的使用

当需要理解或修改代码时，**优先使用 CodeGraph 而不是 grep**：

```bash
# ❌ 不要这样（慢且碎片化）
grep -r "FunctionName" --include="*.go" .

# ✅ 应该这样（精准且带上下文）
codegraph explore "FunctionName"
codegraph node "FunctionName"
codegraph callees "FunctionName"
```

---

## 📁 项目结构

```
go_win_template/
├── main.go                  # 入口：wails.Run + 插件启动
├── app.go                   # IPC 接口层：基础业务 + 支付接口
├── wails.json               # Wails 配置
├── go.mod / go.sum
│
├── config/
│   └── plugin.json          # 插件开关配置（运行时生效）
│
├── assets/icon.png          # 应用图标
├── trayicons/icon.png       # 托盘图标（Wails 标准路径）
│
├── internal/
│   ├── app/app.go           # 全局上下文单例
│   ├── bus/bus.go           # 事件总线（模块间解耦）
│   ├── cache/cache.go       # TTL 内存缓存
│   ├── service/concurrent.go # 高并发：BatchWorker、RateLimiter、RingBuffer、Pipeline
│   ├── worker/pool.go       # 任务并发池（固定工作协程）
│   ├── payment/
│   │   ├── client.go        # HTTP 客户端：自动 token 续期 + HMAC 签名
│   │   └── service.go       # 支付业务层（登录、查订单、退款、账单）
│   ├── plugins/
│   │   ├── plugins.go       # 插件接口 + 全局注册中心
│   │   ├── loader.go        # 配置文件加载器（支持环境变量覆盖）
│   │   ├── iconfont_impl.go # build tag: iconfont
│   │   ├── concurrent_impl.go # build tag: concurrent
│   │   ├── ai_impl.go       # build tag: ai
│   │   └── payment_impl.go  # build tag: payment
│   └── tray/win/tray.go     # Windows 系统托盘（Win32 API）
│
├── frontend/                # React + TypeScript + Vite
│   ├── src/App.tsx          # 主页面（用户管理示例）
│   ├── src/main.tsx         # React 入口
│   ├── wailsjs/             # Go → JS 绑定（自动生成）
│   └── vite.config.ts
│
├── .codegraph/              # CodeGraph 索引（自动生成，勿手动编辑）
│   └── codegraph.db
│
└── .memory/                 # 本记忆包
    └── MEMORY.md
```

---

## 🔌 插件系统

### 插件列表

| 插件名 | Build Tag | 默认状态 | 功能 |
|--------|-----------|----------|------|
| `concurrent` | `-tags concurrent` | ✅ 启用 | 高并发工具集 |
| `payment` | `-tags payment` | ✅ 启用 | 支付授权与订单管理 |
| `iconfont` | `-tags iconfont` | ❌ 禁用 | 阿里IconFont图标库 |
| `ai` | `-tags ai` | ❌ 禁用 | AI大模型集成 |

### 运行时配置（无需重新编译）

编辑 `config/plugin.json` 即可切换插件开关：
```json
{
  "plugins": {
    "payment": {
      "enabled": true,
      "params": { "app_id": "...", "api_key": "...", "base_url": "..." }
    }
  }
}
```

### 编译时启用（完全排除二进制）

```bash
# 仅基础功能
wails build

# 加支付插件
wails build -tags payment

# 加 AI 插件
wails build -tags ai

# 全部启用
wails build -tags "payment,ai,iconfont"

# 环境变量覆盖
PLUGIN_AI=true wails build
```

---

## 💰 支付接口（IPC — 前端可调用）

| Go 方法 | 说明 |
|---------|------|
| `PayLogin()` | 登录授权，获取 access_token |
| `PayCheckAuth()` | 查询授权状态 |
| `PayRefreshToken()` | 主动刷新令牌 |
| `PayGetAccountInfo()` | 获取账号信息 |
| `PayQueryOrder(orderID)` | 查订单 |
| `PayQueryOrderByOutNo(outTradeNo)` | 按商户号查订单 |
| `PayRequestRefund(orderID, amount, reason)` | 申请退款 |
| `PayGetBill(page, pageSize)` | 分页账单 |
| `PayGetBillByDate(start, end)` | 按日期查账单 |

---

## 🚀 开发命令

```bash
# 开发模式（热更新，自动选端口）
wails dev

# 构建 Windows exe
wails build

# 重新生成前端 JS 绑定（新增 IPC 方法后执行）
wails generate module

# 更新 CodeGraph 索引
codegraph sync

# 查看项目结构索引
codegraph files
```

---

## ⚠️ 重要注意事项

1. **端口冲突**: Wails dev 模式 Vite 自动选可用端口（`strictPort: false`），多实例不冲突
2. **生产模式**: 静态资源打包进 exe，无端口暴露，用户无法直接访问端口
3. **托盘图标**: Wails v2 标准路径 `trayicons/icon.png`，名称即 ID（`Image: "icon"`）
4. **支付插件**: 需在 `config/plugin.json` 的 `params` 中配置 `app_id`、`api_key`、`base_url`
5. **CodeGraph**: 索引存储在 `.codegraph/codegraph.db`，修改代码后运行 `codegraph sync` 同步

---

*记忆包创建: 2026-09-17*
*CodeGraph 索引: 25 files, 431 nodes, 947 edges*