# Hackton

**Repository Path**: zephyr123_3/hackton

## Basic Information

- **Project Name**: Hackton
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-19
- **Last Updated**: 2026-04-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Fishing Explore

钓鱼主题黑客松项目。具体需求迭代中,架构保持模块化以便扩展。

## 快速开始

```bash
# 1. 复制模板,手动填入密钥
cp .env.example .env
# 打开 .env 填真实密码、APP_SECRET_KEY、第三方 key 等

# 2. 构建并启动(首次 2-3 分钟:拉镜像 + pip install + npm install)
docker compose up -d --build

# 3. 查看日志
docker compose logs -f backend
docker compose logs -f frontend
```

访问:

- 前端:<http://localhost:3188>
- 后端健康检查:`curl http://localhost:8088/api/v1/health` → `{"status":"ok"}`

> 默认端口:PG `5435` / 后端 `8088` / 前端 `3188`。本机大量容器已占用 5432-5434、8000-8100、3000-3101 等常用端口;如本机空闲可在 `.env` 改回常用值。

## 常用命令

所有命令**一律在容器内执行**,不走宿主机 venv / conda / 全局 Node:

```bash
# 启停与重启
docker compose up -d --build       # 全量构建并启动
docker compose down                # 停止并删容器
docker compose restart backend     # 后端热更新失效时重启
docker compose restart frontend    # 前端同上

# 进容器
docker compose exec backend bash
docker compose exec frontend sh

# 后端:测试 / 迁移
docker compose exec backend pytest
docker compose exec backend alembic revision --autogenerate -m "描述"
docker compose exec backend alembic upgrade head

# 前端:类型检查 / 加依赖
docker compose exec frontend npm run typecheck
# 加依赖:改 package.json 再 docker compose up -d --build frontend
```

## 技术栈

- **后端**:Python 3.12 + FastAPI + SQLAlchemy 2.0 + Alembic + PostgreSQL 16
- **前端**:React 18 + TypeScript + Vite + **Tailwind CSS v4**(CSS-first 配置) + React Router 6
- **容器**:Docker + Docker Compose(dev 卷挂载 + HMR)

## 目录结构

```
fishing-explore/
├── CLAUDE.md              # AI 编码协作规范(开工前必读)
├── docker-compose.yml     # 服务编排
├── .env.example           # 密钥与配置模板
├── docs/
│   ├── integrations/      # 第三方 API 集成笔记(如 amap.md)
│   └── images/
├── backend/
│   ├── Dockerfile
│   ├── pyproject.toml
│   ├── alembic/
│   ├── app/
│   │   ├── main.py        # 应用装配入口
│   │   ├── config.py
│   │   ├── database.py
│   │   ├── api/           # 路由层
│   │   ├── services/      # 业务层
│   │   ├── models/        # ORM
│   │   ├── schemas/       # Pydantic 契约
│   │   └── core/          # 通用组件
│   └── tests/
└── frontend/
    ├── Dockerfile
    ├── package.json
    ├── vite.config.ts
    ├── tsconfig.json
    ├── index.html
    └── src/
        ├── main.tsx       # 入口
        ├── App.tsx        # 根组件
        ├── routes.tsx     # 路由集中配置
        ├── layouts/       # 布局(AppShell, PageContainer)
        ├── pages/         # 路由级页面
        ├── components/
        │   ├── ui/        # 通用原语(Button, Card ...)
        │   └── nav/       # 导航(Sidebar, BottomNav, TopBar)
        ├── hooks/
        ├── api/           # 后端 API 客户端
        └── styles/        # Tailwind 入口 + 全局样式(index.css)
```

## 协作规范

开发前请阅读 **[CLAUDE.md](./CLAUDE.md)**,其中约定了 commit、注释、目录分层、密钥管理、容器内执行、测试纪律、Tailwind v4 约束等硬性规则。