goukiandDevin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
12fa2b0d19
小程序接口（lunar.neatcn.com）与商业版 Web（kepo.net）此前共用一个 二进制，导致小程序域名暴露商业后台与 Stripe Webhook，商业站点也 暴露了许愿树等小程序接口。现拆为两个入口： - cmd/mini：微信登录、生辰档案、许愿树、百科、版本号 - cmd/web：邮箱登录、commerce、报告/订单、/admin 后台、商业前端 静态托管与 SPA 回退 - internal/app 承载共用启动与路由注册；图片资源移至 internal/assets CI：server-deploy.yml 改构建 cmd/mini 并随包移除后台静态资源； 新增 web-deploy.yml 构建 cmd/web + web-commercial 前端，发布 web-v* Release；deploy-watch.sh 支持 TAG_PREFIX/ASSET_NAME 变量； 新增 deploy-web.sh（systemd 版）与 kepo 一次性配置文档 .gitea/docs/PULL_DEPLOY_WEB.md。 Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
85 lines
4.0 KiB
Markdown
85 lines
4.0 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/cmd/mini/` | 小程序接口入口（lunar.neatcn.com） | `main.go` |
|
||
| `server/cmd/web/` | 商业版 Web 入口（kepo.net，含后台与前端静态托管） | `main.go` |
|
||
| `server/internal/app/` | 两个入口的路由注册与共用启动逻辑 | `app.go`, `mini.go`, `web.go` |
|
||
| `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 后端：6 个已跟踪测试文件（`server/internal/service/` 3 个：baike_term_sync_test.go、payment_provider_test.go、wiki_sync_test.go；`server/internal/handler/` 2 个：commerce_test.go、本次新增的邮箱验证码测试 email_auth_test.go；`server/internal/middleware/` 1 个：middleware_test.go）
|
||
- web 前端核心（`web/packages/core/`）：10 个 TypeScript 测试文件（`src/__tests__/` 下：bazi、boneWeight、day、elementStrength、fortune、fortuneLuck、plumBlossom、relationship、shensha、yearMonths）
|
||
- 小程序前端：0 个测试文件
|
||
- 商业前端：0 个测试文件
|
||
|
||
## 相关文档
|
||
|
||
- `server/README.md` — 后端服务详细说明
|
||
- `web/docs/ARCHITECTURE.md` — 前端架构文档
|
||
- `web/docs/REQUIREMENTS.md` — 需求文档
|
||
- `REMINDER.md` — 开发提醒（商业化功能规范）
|