gouki
deb32f8fab
Build and Publish Server / build (push) Successful in 4m30s
- 新增商业化模块：Stripe/Binance Pay 支付、邮箱登录、订单管理 - 新增数据模型：ReportProduct, ReportEntitlement, ReportSnapshot, PaymentEvent, EmailLoginCode - 新增 API：/api/commerce/checkout, /api/commerce/webhooks/*, /api/commerce/orders/* - 新增管理后台：订单列表、统计图表、统一 AdminHeader 组件 - 新增中间件测试：RateLimit, Auth, CORS 共 7 个测试用例 - 新增 AGENTS.md 项目代理指令文件 - 新增 REMINDER.md 商业化功能开发规范 - 修复 JWT 解析：添加 WithValidMethods 限制 HS256 - 修复 GetPayStatus：增加用户权限校验 - 更新 .gitignore 和 README.md
81 lines
3.2 KiB
Markdown
81 lines
3.2 KiB
Markdown
# 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` — 开发提醒（商业化功能规范）
|