go_win_template/.memory/MEMORY.md

项目记忆包 — 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 (已配置)

核心命令

# 初始化/重建索引
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

典型工作流

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

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

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

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

在 AI 对话中的使用

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

# ❌ 不要这样（慢且碎片化）
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 即可切换插件开关：

{
  "plugins": {
    "payment": {
      "enabled": true,
      "params": { "app_id": "...", "api_key": "...", "base_url": "..." }
    }
  }
}

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

# 仅基础功能
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)	按日期查账单

---

🚀 开发命令

# 开发模式（热更新，自动选端口）
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