# Repository Guidelines

## Project Structure & Module Organization

- `mengyaprofile-frontend/`: React (Create React App) UI (`src/`, `public/`).
- `mengyaprofile-backend/`: Flask API (`app.py`, `db.py`) plus SQLite（默认 `data/site.db`，由 `schema.sql` 定义）与静态资源 `data/logo/`、`data/background/`。首次启动若库为空会写入最小占位行；内容通过管理后台或直连数据库维护。
- Root `*.bat`: Windows helper scripts for starting/building locally.

## Build, Test, and Development Commands

```bash
# Backend (Flask API)
cd mengyaprofile-backend
python -m pip install -r requirements.txt
python app.py  # http://localhost:5000

# Frontend (React)
cd ../mengyaprofile-frontend
npm install
npm start      # http://localhost:3000
npm test       # Jest/RTL in watch mode
npm run build  # production build to ./build
```

- Windows / 根目录脚本: `dev.bat`、`build.bat`（见仓库根目录）。
- Docker (optional): `docker compose -f mengyaprofile-backend/docker-compose.yml up -d --build` (adjust the volume path for your machine).

## Coding Style & Naming Conventions

- Python: PEP 8, 4-space indents; keep API routes under `/api/*` in `mengyaprofile-backend/app.py`.
- React: 2-space indents; components live in `mengyaprofile-frontend/src/components/` with `PascalCase` filenames (e.g., `TechStackSection.js`).
- 站点内容：维护 `data/site.db`（表 `profile`、`project` / `project_tag` / `project_tech_tag`、`contact`、`techstack_section` / `techstack_item`），或通过 `/admin` 与 `X-Admin-Token` 调用 `/api/admin/*`。

## Testing Guidelines

- Frontend tests live in `mengyaprofile-frontend/src/**/*.test.js` (example: `src/App.test.js`); run via `npm test`.
- Backend currently has no test suite; if adding one, use `pytest` and place tests under `mengyaprofile-backend/tests/`.

## Commit & Pull Request Guidelines

- Current Git history uses short subjects (e.g., “Initial commit”, “初始化提交”); keep messages concise and scoped (`frontend: ...`, `backend: ...`).
- PRs: describe behavior changes, link issues, include screenshots for UI changes, and call out any `schema.sql` / API shape changes.

## Security & Configuration Tips

- “Admin mode” is client-side (`/admin?token=...`) and not a security boundary—do not store secrets in this repo.
- Useful env vars: backend `RUN_MODE`, `DATA_DIR`, `DATABASE_PATH`（可选，默认 `DATA_DIR/site.db`）, `BACKGROUND_DIR`, `ADMIN_TOKEN`（管理写接口，默认 `shumengya520`，生产务必修改）, `PORT`; frontend `REACT_APP_API_URL` (use `.env.local`)。主页头像连点 5 次（2 秒内累计重置）弹出 token 验证，通过后进入 `/admin` 管理页；写操作须请求头 `X-Admin-Token`。