# Project: AI内容内参后台

## Tech Stack
- Python 3.11 + FastAPI
- PostgreSQL 16
- Redis for caching
- Deployed on AWS ECS

## Key Conventions
- Use Pydantic v2 for all data models
- Test with pytest, coverage must stay above 85%
- All API endpoints must have OpenAPI docstrings

# Project: AI内容内参后台

## Architecture Decisions (WHY, not just WHAT)
- We chose FastAPI over Django because: async-first, auto-OpenAPI docs,
  and the team has more FastAPI experience.
- PostgreSQL over MongoDB because: we need strict schema enforcement
  for billing data. No exceptions.
- No ORM — we use raw SQL via asyncpg. Reason: complex joins across
  12 tables that ORMs generate terrible query plans for.

## Anti-Patterns (what NOT to do)
- NEVER use `asyncio.create_task` without storing the reference.
  We've had 3 production incidents from orphaned tasks.
- NEVER add a new dependency without discussing in #backend channel.
  Last time someone added `polars` we doubled the Docker image size.
- NEVER bypass the rate limiter in tests. It masks real bugs.

## Current Pain Points
- The `/api/reports/weekly` endpoint takes 8s in prod. Root cause unknown.
  Temporary fix: 30s timeout + caching. Looking for solutions.
- User auth tokens expire at midnight UTC. Users in Asia get logged out
  mid-day. We want to switch to sliding expiration.

## Testing Patterns
- Integration tests use real Postgres (testcontainers), not SQLite.
  SQLite doesn't support our JSONB queries.
- Mock external APIs with `responses` library, not `unittest.mock`.
  We've standardized on `responses` since v2.1.

<!-- CLAUDE: When suggesting database queries, always include
     EXPLAIN ANALYZE estimates for tables > 100k rows. -->

## Database Conventions
...

@CONSTRAINT: All API responses must use this envelope format:
{"status": "ok|error", "data": ..., "meta": {"page": 1, "total": 100}}

@CONSTRAINT: Never expose internal error messages to API responses.
Always return "An unexpected error occurred" for 500s.

{
  "permissions": {
    "allow": [
      "Bash(pytest:*)",
      "Bash(git:diff,status,log,add,commit)",
      "Bash(python:*)",
      "Bash(npm:run,test)",
      "Read(/home/user/projects/ai-neican/**)",
      "Write(/home/user/projects/ai-neican/**)",
      "WebSearch"
    ],
    "deny": [
      "Bash(rm:-rf, -rf *)",
      "Bash(git:push --force, push -f)",
      "Bash(curl:*)",
      "Bash(wget:*)",
      "Write(/etc/**)",
      "Write(~/.ssh/**)",
      "Read(~/.aws/**)",
      "Read(~/.config/**)"
    ]
  },
  "model": "claude-sonnet-4-20250514",
  "maxThinkingTokens": 4000,
  "enablePromptCaching": true,
  "env": {
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "DISABLE_GROWTHBOOK": "1"
  }
}

"allow": [
  "Bash(pytest:*)",              // 只允许 pytest 开头的命令
  "Bash(git:diff,status,log)",   // 只允许 git 的这三个子命令
  "Read(/home/user/projects/**)",// 只读项目目录
  "Write(/home/user/projects/**)" // 只写项目目录
]

"deny": [
  "Bash(rm:-rf)",           // 阻止 rm -rf
  "Bash(git:push --force)", // 阻止 force push
  "Bash(npm:install -g)",   // 阻止全局安装
  "Bash(curl:*)",           // 阻止所有 curl 调用
  "Read(~/.ssh/**)"         // 阻止读取 SSH 密钥
]

"env": {
  "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
  "DISABLE_GROWTHBOOK": "1"
}

.claude/
├── CLAUDE.md
├── settings.json
└── hooks/
    ├── on-start.sh          # 对话开始时
    ├── pre-edit.sh          # Claude 修改文件前
    ├── post-edit.sh         # Claude 修改文件后
    └── on-stop.sh           # 对话结束时

#!/bin/bash
# .claude/hooks/pre-edit.sh
# Claude 每次修改文件前自动运行此脚本

CHANGED_FILE="$1"

echo "[pre-edit hook] Claude wants to edit: $CHANGED_FILE"

# 1. 阻止修改配置文件
if [[ "$CHANGED_FILE" =~ \.(env|conf|config\.json)$ ]]; then
  echo "❌ BLOCKED: Cannot edit config files. Use manual review."
  exit 1
fi

# 2. 阻止修改数据库迁移文件（必须人工审核）
if [[ "$CHANGED_FILE" =~ /migrations/ ]]; then
  echo "❌ BLOCKED: Migration files require manual review."
  exit 1
fi

# 3. 如果是 Python 文件，先跑 linter
if [[ "$CHANGED_FILE" =~ \.py$ ]]; then
  if command -v ruff &> /dev/null; then
    ruff check "$CHANGED_FILE" --quiet
    if [ $? -ne 0 ]; then
      echo "⚠️  WARNING: ruff found issues in $CHANGED_FILE"
      echo "   Claude will still proceed, but review is recommended."
    fi
  fi
fi

echo "✅ pre-edit check passed for: $CHANGED_FILE"
exit 0

#!/bin/bash
# .claude/hooks/post-edit.sh
# Claude 修改文件后自动运行

EDITED_FILE="$1"

# Python 文件自动格式化
if [[ "$EDITED_FILE" =~ \.py$ ]]; then
  if command -v ruff &> /dev/null; then
    ruff format "$EDITED_FILE" --quiet 2>/dev/null
    echo "[post-edit] Auto-formatted: $EDITED_FILE"
  fi
fi

# 自动 stage 到 git
if git rev-parse --git-dir > /dev/null 2>&1; then
  git add "$EDITED_FILE" 2>/dev/null
  echo "[post-edit] Staged: $EDITED_FILE"
fi

exit 0

{
  "permissions": {
    "allow": [
      "Bash(pytest:*)",
      "Bash(git:diff,status,log,add,commit,branch,checkout)",
      "Bash(python:*)",
      "Bash(npm:run,test,install --save,install --save-dev)",
      "Bash(ruff:*)",
      "Read(**/*.py,**/*.ts,**/*.json,**/*.md,**/*.yaml,**/*.yml)",
      "Write(**/*.py,**/*.ts,**/*.json,**/*.md,**/*.yaml,**/*.yml)"
    ],
    "deny": [
      "Bash(rm:-rf, -rf *, * | sh, * | bash)",
      "Bash(git:push --force, push -f, reset --hard)",
      "Bash(curl:*, wget:*)",
      "Bash(sudo:*)",
      "Read(.env, .env.*, credentials.*, **/secrets/**)",
      "Write(.env, .env.*, credentials.*, **/secrets/**)"
    ]
  },
  "model": "claude-sonnet-4-20250514",
  "maxThinkingTokens": 4000,
  "enablePromptCaching": true,
  "env": {
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "DISABLE_GROWTHBOOK": "1"
  }
}

# Project: {{YOUR_PROJECT_NAME}}

## What This Project Does
<!-- Brief description of the project's purpose -->

## Architecture
<!-- Key architectural decisions and WHY -->

## Code Conventions
<!-- Naming, patterns, and style rules -->

## Anti-Patterns
<!-- Things Claude should NEVER do in this project -->

## Testing
<!-- How to run tests and testing conventions -->

#!/bin/bash
set -euo pipefail
FILE="$1"
# Block edits to sensitive files
case "$FILE" in
  *.env|*.env.*|*credentials*|*secret*) echo "❌ BLOCKED: sensitive file"; exit 1 ;;
  */migrations/*) echo "❌ BLOCKED: migration file - manual review required"; exit 1 ;;
esac
exit 0