首次提交

2026-06-25 08:39:47 +08:00
parent 20a93c703a
commit c5cccd346b
169 changed files with 24720 additions and 0 deletions
@@ -0,0 +1,151 @@
+# 仓库指南
+
+寸进（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 重命名回去即可