# 仓库指南

寸进（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 重命名回去即可