zeronline
7.7 KiB
7.7 KiB
仓库指南
寸进（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 规范：
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：
powershell -ExecutionPolicy Bypass -F .\scripts\setup-skills.ps1
- 运行后 skills/ 下的每个技能目录会链接到 ~/.codex/skills/
- 编辑项目内的技能文件会实时同步，不需要重新安装
- 当前已注册的项目技能：pdf / playwright / playwright-interactive
- 如需还原全局安装，删除 Junction 并将 .bak 重命名回去即可