zeronline
152 lines
7.7 KiB
Markdown
152 lines
7.7 KiB
Markdown
# 仓库指南
|
||
|
||
寸进（InchStep）是一个跨场景综合成长打卡平台，覆盖学习、健康、习惯、兴趣、目标五大领域，融合数据可视化与社交比拼机制。
|
||
**前端三端同步**：Web 端（Next.js）、移动端 App（React Native）、微信小程序三端功能对齐、同步上线。
|
||
**后端管理**：独立 Web 管理后台（React），与用户端分离部署。完整需求规格请参见 docs/寸进_InchStep_详细需求说明书.md。
|
||
|
||
## 项目结构与模块组织
|
||
|
||
```
|
||
F:\myProject\InchStep\
|
||
├── docs/ # 设计文档与规格说明
|
||
│ └── 寸进_InchStep_详细需求说明书.md
|
||
├── web/ # Web 端源码（Next.js）
|
||
│ ├── src/
|
||
│ │ ├── app/ # Next.js App Router 页面
|
||
│ │ ├── components/ # 共享 UI 组件
|
||
│ │ ├── services/ # API 客户端与业务逻辑
|
||
│ │ └── utils/ # 辅助函数与常量
|
||
│ ├── __tests__/
|
||
│ └── package.json
|
||
├── mobile/ # 移动端 App 源码（React Native）
|
||
│ ├── src/
|
||
│ │ ├── modules/ # 功能模块（打卡、社交、个人中心等）
|
||
│ │ ├── components/ # 共享 UI 组件
|
||
│ │ ├── services/ # API 客户端与业务逻辑
|
||
│ │ └── utils/ # 辅助函数与常量
|
||
│ ├── __tests__/
|
||
│ └── package.json
|
||
├── miniapp/ # 微信小程序源码
|
||
│ ├── pages/ # 小程序页面
|
||
│ ├── components/ # 小程序自定义组件
|
||
│ ├── services/ # API 客户端
|
||
│ ├── utils/ # 辅助函数
|
||
│ └── project.config.json # 小程序项目配置
|
||
├── admin/ # 后端管理后台源码（React）
|
||
│ ├── src/
|
||
│ │ ├── pages/ # 管理后台页面
|
||
│ │ ├── components/ # 后台通用组件
|
||
│ │ ├── services/ # API 客户端
|
||
│ │ └── utils/ # 辅助函数
|
||
│ ├── __tests__/
|
||
│ └── package.json
|
||
├── server/ # 后端 API（Go + Gin + GORM）
|
||
│ ├── cmd/api/ # 入口 main.go
|
||
│ ├── internal/
|
||
│ │ ├── config/ # 配置加载
|
||
│ │ ├── database/ # 数据库连接与自动迁移
|
||
│ │ ├── models/ # 数据模型（User、CheckInItem、Record 等）
|
||
│ │ ├── middleware/ # JWT 认证、CORS、错误处理
|
||
│ │ ├── services/ # 核心业务逻辑
|
||
│ │ ├── handlers/ # HTTP 处理器
|
||
│ │ └── router/ # 路由注册
|
||
│ ├── __tests__/
|
||
│ ├── go.mod / go.sum
|
||
│ ├── Dockerfile
|
||
│ └── .env.example
|
||
├── shared/ # 三端共享代码（类型定义、常量、工具函数）
|
||
│ ├── types/ # TypeScript 类型定义
|
||
│ ├── constants/ # 共享常量
|
||
│ └── utils/ # 共享工具函数
|
||
├── skills/ # 项目级 Skill（pdf / playwright / playwright-interactive）
|
||
├── scripts/ # 项目工具脚本
|
||
├── docker/ # Docker 配置
|
||
│ └── docker-compose.yml
|
||
├── .env.example # 环境变量模板
|
||
├── .gitignore
|
||
├── AGENTS.md # 本文件
|
||
└── README.md # 项目入口说明
|
||
```
|
||
|
||
## 编码风格与命名规范
|
||
|
||
### Go 后端（server/）
|
||
|
||
- **缩进**：`go fmt` 标准格式化（制表符缩进）。
|
||
- **语言**：Go 1.22，启用 `go vet` 静态检查。
|
||
- **命名规则**：
|
||
- 文件：`snake_case.go`（例如 `checkin_service.go`）。
|
||
- 函数与变量：`camelCase`（私有）、`PascalCase`（导出）。
|
||
- 常量：`PascalCase`（导出常量）。
|
||
- 类型与接口：`PascalCase`。
|
||
- **格式化**：`go fmt`，Go 标准风格。
|
||
- **代码检查**：`go vet`。
|
||
- **构建运行**：`go build ./cmd/api`，`go run ./cmd/api`。
|
||
|
||
### 前端（web/、mobile/、miniapp/、admin/）
|
||
|
||
- **缩进**：2 个空格，不使用制表符。
|
||
- **语言**：TypeScript，严格模式（strict）开启。
|
||
- **命名规则**：
|
||
- 普通文件：`kebab-case.ts`（例如 `checkin-service.ts`）。
|
||
- 移动端组件：`PascalCase.tsx`（例如 `CheckInCard.tsx`）。
|
||
- 函数与变量：`camelCase`。
|
||
- 常量：`UPPER_SNAKE_CASE`。
|
||
- 类型与接口：`PascalCase`，接口以 `I` 开头（例如 `ICheckInItem`）。
|
||
- **格式化**：Prettier，配置 `printWidth: 100`、`singleQuote: true`、`trailingComma: all`。
|
||
- **代码检查**：ESLint，使用 `recommended` 和 `@typescript-eslint/recommended` 配置集。
|
||
|
||
## 测试规范
|
||
|
||
- **测试框架**：Go 后端用 `go test` + `testify`；移动端用 React Native Testing Library。
|
||
- **覆盖率要求**：新增代码行覆盖率达到 80%；核心业务逻辑（打卡服务、连续天数计算、积分计算）需 ≥ 90%。
|
||
- **测试文件命名**：Go 后端 `*_test.go`，前端 `*.test.ts` 或 `*.test.tsx`，与源码同目录放置。
|
||
- **模拟策略**：Go 后端优先使用接口与依赖注入；前端减少模块级 mock。
|
||
- **运行测试**：Go 后端 `go test ./...`，前端项目 `pnpm test`。
|
||
|
||
## 提交与 PR 规范
|
||
|
||
- **提交信息**：遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范：
|
||
- `feat:` — 新功能
|
||
- `fix:` — 缺陷修复
|
||
- `refactor:` — 重构，无行为变更
|
||
- `test:` — 新增或修改测试
|
||
- `docs:` — 仅文档更新
|
||
- `chore:` — 工具链、CI、依赖管理
|
||
- 示例：`feat(checkin): 实现补卡流程及积分扣减`
|
||
- **Pull Request**：
|
||
- 标题必须符合 Conventional Commit 格式。
|
||
- 描述必须包含：变更内容、变更原因、验证方式。
|
||
- 使用 `Closes #123` 关联相关 Issue。
|
||
- UI 变更必须附带截图或录屏。
|
||
- 保持 PR 聚焦——一个 PR 只处理一个关注点。
|
||
- 所有 CI 检查必须通过，覆盖率不得下降，方可请求审查。
|
||
|
||
## 安全与配置注意事项
|
||
|
||
- 严禁提交 `.env` 文件。使用 `.env.example` 并填入占位值。
|
||
- 主要环境变量：`DB_HOST`、`DB_PORT`、`DB_USER`、`DB_PASS`、`DB_NAME`、`JWT_SECRET`、`REDIS_URL`、`S3_BUCKET`。
|
||
- 第三方服务的 API 密钥（微信登录、推送通知等）必须存入 CI/CD 密钥管理，不得出现在源码中。
|
||
- 所有面向用户的 API 路由默认需要认证中间件，除非显式标记公开路由（如 `/api/auth/*`）。
|
||
- 用户密码使用 bcrypt，cost 因子设为 12。
|
||
|
||
## 代理专用说明
|
||
|
||
- 修改数据模型时，必须同步更新 `server/internal/models/` 中的 Go 结构体和 `shared/types/index.ts`。
|
||
- 数据库迁移由 GORM AutoMigrate 自动执行，生产环境应使用版本化迁移脚本。
|
||
- 连续天数计算须考虑时区：以 Asia/Shanghai 为准，非 UTC。见 `server/internal/services/checkin_service.go`。
|
||
- 新功能分支名称须以模块名为前缀，例如：`feat/checkin-makeup`、`fix/social-group-join`。
|
||
|
||
## 项目技能管理
|
||
|
||
项目级技能存放在 skills/ 目录下，通过目录符号链接（Junction）注册到 Codex：
|
||
|
||
```bash
|
||
powershell -ExecutionPolicy Bypass -F .\scripts\setup-skills.ps1
|
||
```
|
||
|
||
- 运行后 skills/ 下的每个技能目录会链接到 ~/.codex/skills/
|
||
- **编辑项目内的技能文件会实时同步**，不需要重新安装
|
||
- 当前已注册的项目技能：pdf / playwright / playwright-interactive
|
||
- 如需还原全局安装，删除 Junction 并将 .bak 重命名回去即可
|