# AGENTS.md — lunar 项目代理指令

## 项目概述

lunar 是一个融合中国传统文化（农历、八字、许愿树）的现代化应用，包含：
- **mini/**: 微信小程序前端（农历日历、八字排盘、许愿树、百科）
- **server/**: Go 后端服务（Gin + GORM + MySQL，提供小程序 API 和商业版支付）
- **web/**: 前端工程化包（core + web）
- **web-commercial/**: 商业版前端（React + Vite）
- **wishing-tree-pages/**: 许愿树独立页面（Next.js）

## 核心路径导航

| 路径 | 说明 | 关键文件 |
|------|------|----------|
| `server/internal/handler/` | HTTP API 处理器 | `user.go`, `commerce.go`, `pay.go`, `wiki.go` |
| `server/internal/service/` | 业务逻辑层 | `user.go`, `commerce.go`, `payment_provider.go`, `wish.go` |
| `server/internal/model/` | 数据模型 | `user.go`, `order.go`, `commerce.go`, `wish.go` |
| `server/internal/middleware/` | 中间件 | `middleware.go`（认证、CORS、限流） |
| `server/internal/config/` | 配置管理 | `config.go`, `database.go` |
| `server/migrations/` | 数据库迁移 | `001_init.sql`, `002_commerce.sql` |
| `mini/pages/` | 小程序页面 | `home/`, `calendar/`, `wish-tree/`, `bazi/`, `wiki/` |
| `mini/utils/` | 小程序工具 | `lunar.js`, `request.js`, `birth-profile.js` |
| `mini/components/` | 小程序组件 | `calendar-grid/`, `score-ring/`, `badge/` |
| `mini/ci/` | 小程序 CI 脚本 | `preview-ci.cjs`, `upload-ci.cjs` |

## 高频变更热点

- `mini/pages/wish-tree/wish-tree.js` — 许愿树页面（30 天 churn 4549 行）
- `mini/utils/core/index.js` — 核心工具（churn 1734 行）
- `server/internal/handler/user.go` — 用户 API（churn 488 行）
- `server/internal/middleware/middleware.go` — 中间件（churn 259 行）

## 启动与验证命令

### 后端（server/）
```bash
cd server
cp .env.example .env.local   # 首次运行
go mod download
go run ./cmd                  # 开发启动，默认 :8080
go test ./...                 # 运行测试
go build -o bin/server ./cmd  # 构建
```

### 小程序（mini/）
```bash
cd mini
npm install
npm run dev                   # 开发模式（微信开发者工具预览）
npm run upload                # 上传体验版（需配置 CI）
```

### 商业前端（web-commercial/）
```bash
cd web-commercial
pnpm install
pnpm dev                      # 开发服务器
pnpm build                    # 构建
```

## 高风险操作警示

- **生产部署**: 禁止 SSH 直连服务器，使用 Gitea Actions + Release 拉取式部署
- **数据库**: 禁止执行 `fresh` 或 `refresh`，新环境用 AutoMigrate，已有库手动执行 migrations
- **支付**: 任何支付功能必须同时具备真实下单、Webhook 验签、订单状态机、幂等处理、退款处理
- **密钥**: 所有支付与邮件密钥必须通过环境变量注入，禁止提交到 Git

## 测试覆盖现状

- Go 后端：2 个测试文件（`server/internal/service/` 下）
- 小程序前端：0 个测试文件
- 商业前端：0 个测试文件

## 相关文档

- `server/README.md` — 后端服务详细说明
- `web/docs/ARCHITECTURE.md` — 前端架构文档
- `web/docs/REQUIREMENTS.md` — 需求文档
- `REMINDER.md` — 开发提醒（商业化功能规范）