chore: bootstrap repo tooling, dependency and quality gates

uv-managed PEP 621 project with ruff, mypy (strict on packages/domain and
packages/llm), pytest with coverage, and import-linter contracts that
mechanically enforce the dependency rules of 架构文档 §4.2 -- including the
two forbidden edges (compliance and identity must not depend on business
domains). CI, pre-commit and a detect-secrets baseline gate every push;
.env is gitignored before anything is ever staged.

.env.example

@@ -0,0 +1,85 @@
+# =============================================================================
+# 美搭 backend — environment template
+# =============================================================================
+# Copy to `.env` and fill in real values. `.env` is git-ignored and MUST NEVER
+# be committed (架构文档 §11.2: 密钥全部走 SSM/KMS，禁止进代码与镜像).
+# In dev/staging/prod these variables are injected by SSM/KMS, not by a file.
+# Every variable below is documented; NO real values appear in this file.
+# =============================================================================
+
+# --- Application ------------------------------------------------------------
+APP_ENV=local                      # local | dev | staging | prod (架构文档 §14.2)
+APP_NAME=meida-backend
+API_PREFIX=/api/v1                 # 架构文档 §9.1 基础路径；/v1/* 作为别名同样可用
+DEBUG=true
+LOG_LEVEL=INFO                     # DEBUG | INFO | WARNING | ERROR
+LOG_JSON=true                      # false => human-readable console renderer
+
+# --- Database (PostgreSQL 16 + pgvector) ------------------------------------
+# Async driver is required (SQLAlchemy 2.0 asyncio + asyncpg).
+DATABASE_URL=postgresql+asyncpg://meida:meida@localhost:55432/meida
+DB_POOL_SIZE=10
+DB_MAX_OVERFLOW=20
+DB_ECHO=false
+
+# --- Redis 7 (cache / quota counters / celery broker) -----------------------
+REDIS_URL=redis://localhost:56379/0
+CELERY_BROKER_URL=redis://localhost:56379/1
+CELERY_RESULT_BACKEND=redis://localhost:56379/2
+
+# --- Auth (架构文档 §9.1: JWT access 15min + 可撤销 refresh) ----------------
+JWT_SECRET=                        # REQUIRED. >=32 random chars. Generate: openssl rand -hex 32
+JWT_ALGORITHM=HS256
+JWT_ACCESS_TTL_SECONDS=900         # 15 minutes
+JWT_ISSUER=meida
+DEV_AUTH_ENABLED=true              # MUST be false outside local/dev: enables POST /auth/dev-token
+
+# --- LLM gateway: routing (架构文档 §8.1) -----------------------------------
+LLM_PRIMARY_PROVIDER=deepseek      # DeepSeek 为主 (TD-04)
+LLM_BACKUP_PROVIDER=zhipu          # 智谱 GLM 为备（V1 未实现，仅结构占位）
+LLM_STRUCTURED_MAX_RETRIES=2       # 结构化输出校验失败的重试次数
+LLM_CIRCUIT_FAILURE_THRESHOLD=3    # 连续失败达到该值即熔断
+LLM_CIRCUIT_COOLDOWN_SECONDS=30    # 熔断冷却时长，之后半开探测
+# JSON 值一律用单引号包住：scripts/smoke.sh 会 `source .env`，
+# 裸的双引号会被 bash 剥掉，JSON 就此损坏。
+LLM_SCENE_OVERRIDES_JSON='{}'      # 场景路由覆盖，JSON: {"agent_chat":{"max_tokens":900}}
+
+# --- LLM gateway: DeepSeek (OpenAI-compatible) ------------------------------
+DEEPSEEK_API_KEY=                  # REQUIRED. sk-... Never commit.
+DEEPSEEK_BASE_URL=https://api.deepseek.com/v1
+DEEPSEEK_MODEL=deepseek-v4-flash   # 默认模型，可用: deepseek-v4-flash / deepseek-v4-pro
+DEEPSEEK_TIMEOUT_SECONDS=30
+
+# --- LLM gateway: 智谱 GLM (backup, not implemented in V1) ------------------
+ZHIPU_API_KEY=
+ZHIPU_BASE_URL=https://open.bigmodel.cn/api/paas/v4
+ZHIPU_MODEL=glm-4-flash
+ZHIPU_TIMEOUT_SECONDS=30
+
+# --- LLM gateway: prompt caching discipline (架构文档 §7.2 缓存前缀纪律) ----
+# strict => 固定前缀含时间戳/随机ID/昵称时直接拒绝调用
+# warn   => 只记录告警日志；off => 关闭（不建议）
+LLM_CACHE_PREFIX_MODE=strict
+PROMPTS_DIR=prompts
+
+# --- LLM gateway: 成本归因与费率 (架构文档 §13, FR-BILL-08) -----------------
+# 单位：分/百万 token（cents per 1M tokens）。上线前必须以供应商实际价目表校准。
+LLM_COST_RATES_JSON='{"deepseek-v4-flash":{"input_cents_per_mtok":"14","cached_input_cents_per_mtok":"2","output_cents_per_mtok":"28"},"deepseek-v4-pro":{"input_cents_per_mtok":"200","cached_input_cents_per_mtok":"20","output_cents_per_mtok":"800"}}'
+LLM_DEFAULT_COST_RATE_JSON='{"input_cents_per_mtok":"100","cached_input_cents_per_mtok":"20","output_cents_per_mtok":"200"}'
+
+# --- LLM gateway: 全局日成本熔断 (架构文档 §13 三道成本闸门) ----------------
+# 达到阈值后，非关键场景的 AI 调用被直接拒绝/降级，而不仅仅是告警。
+LLM_DAILY_BUDGET_ENABLED=true
+LLM_DAILY_BUDGET_CENTS=100000      # 1000 元/天
+LLM_BUDGET_TIMEZONE_OFFSET_HOURS=8 # 结算日按 UTC+8 (FR-BILL-01)
+
+# --- Observability (架构文档 §15) -------------------------------------------
+OTEL_ENABLED=false
+OTEL_SERVICE_NAME=meida-api
+OTEL_EXPORTER_OTLP_ENDPOINT=       # e.g. http://localhost:4318
+PROMETHEUS_ENABLED=true
+
+# --- Logging redaction (NFR-SEC-03) -----------------------------------------
+# Extra log field names to redact, comma separated. Built-in list already covers
+# phone / token / union_id / open_id / avatar_key / face image keys / diagnosis.
+LOG_EXTRA_REDACT_KEYS=

.github/workflows/ci.yml

@@ -0,0 +1,114 @@
+# 架构文档 §16.2：这些防线是机器可执行的检查，任一失败即阻断合并。
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  UV_CACHE_DIR: /tmp/.uv-cache
+
+jobs:
+  quality-gate:
+    name: lint / typecheck / import-linter / tests / secrets
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    services:
+      postgres:
+        image: pgvector/pgvector:pg16
+        env:
+          POSTGRES_USER: meida
+          POSTGRES_PASSWORD: meida
+          POSTGRES_DB: meida_test
+        ports: ["5432:5432"]
+        options: >-
+          --health-cmd "pg_isready -U meida"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 20
+      redis:
+        image: redis:7-alpine
+        ports: ["6379:6379"]
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 20
+
+    env:
+      APP_ENV: dev
+      JWT_SECRET: ci-only-not-a-real-secret-0123456789abcdef
+      DATABASE_URL: postgresql+asyncpg://meida:meida@localhost:5432/meida_test
+      REDIS_URL: redis://localhost:6379/0
+      CELERY_BROKER_URL: redis://localhost:6379/1
+      CELERY_RESULT_BACKEND: redis://localhost:6379/2
+      DEEPSEEK_API_KEY: ci-placeholder-no-network-calls-in-ci
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python 3.12
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --extra dev --frozen
+
+      # --- 防线 1: 静态检查 (ruff lint + format) ---
+      - name: Ruff lint
+        run: uv run ruff check --output-format=github .
+      - name: Ruff format check
+        run: uv run ruff format --check .
+
+      # --- 防线 2: mypy strict 覆盖 packages/domain 与 packages/llm ---
+      - name: Mypy (strict scope)
+        run: uv run mypy packages/domain packages/llm
+      - name: Mypy (remaining scope)
+        run: uv run mypy apps packages/shared packages/identity packages/billing packages/task packages/agent packages/compliance
+
+      # --- 防线 3: 分层依赖检查 (架构文档 §4.2) ---
+      - name: Import contracts
+        run: uv run lint-imports --verbose
+
+      # --- 防线 4: 单元测试 + 覆盖率 ---
+      - name: Pytest
+        run: uv run pytest --cov-report=xml
+
+      # --- 防线 5: 数据库迁移必须可正向执行并可回滚 (T-P1-06) ---
+      - name: Alembic upgrade/downgrade round-trip
+        run: |
+          uv run alembic upgrade head
+          uv run alembic downgrade base
+          uv run alembic upgrade head
+
+      # --- 防线 6: 敏感信息扫描 ---
+      - name: Secrets scan (detect-secrets)
+        run: |
+          uv run detect-secrets scan --baseline .secrets.baseline
+          git diff --exit-code .secrets.baseline
+
+      - name: Gitleaks
+        uses: gitleaks/gitleaks-action@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Upload coverage
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage
+          path: coverage.xml
+          if-no-files-found: ignore

.gitignore

@@ -0,0 +1,41 @@
+# --- SECRETS: never commit. The real DeepSeek key lives in .env only. ---
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+secrets/
+
+# Python
+__pycache__/
+*.py[cod]
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+.venv/
+venv/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+.importlinter_cache/
+
+# Local runtime artefacts
+*.log
+.pgdata/
+.redisdata/
+.scratch/
+.smoke/
+
+# Editors / OS
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db

.pre-commit-config.yaml

@@ -0,0 +1,32 @@
+# 架构文档 §16.2「敏感信息扫描」防线：pre-commit + CI 双卡。
+default_language_version:
+  python: python3.12
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-added-large-files
+        args: ["--maxkb=1024"]
+      - id: check-merge-conflict
+      - id: check-toml
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: mixed-line-ending
+        args: ["--fix=lf"]
+      - id: detect-private-key
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.13.0
+    hooks:
+      - id: ruff
+        args: ["--fix"]
+      - id: ruff-format
+
+  - repo: https://github.com/Yelp/detect-secrets
+    rev: v1.5.0
+    hooks:
+      - id: detect-secrets
+        args: ["--baseline", ".secrets.baseline"]
+        exclude: ^(\.env\.example|uv\.lock)$

.secrets.baseline

@@ -0,0 +1,48 @@
+{
+  "version": "1.5.0",
+  "plugins_used": [
+    {"name": "ArtifactoryDetector"},
+    {"name": "AWSKeyDetector"},
+    {"name": "AzureStorageKeyDetector"},
+    {"name": "Base64HighEntropyString", "limit": 4.5},
+    {"name": "BasicAuthDetector"},
+    {"name": "CloudantDetector"},
+    {"name": "DiscordBotTokenDetector"},
+    {"name": "GitHubTokenDetector"},
+    {"name": "GitLabTokenDetector"},
+    {"name": "HexHighEntropyString", "limit": 3.0},
+    {"name": "IbmCloudIamDetector"},
+    {"name": "IbmCosHmacDetector"},
+    {"name": "IPPublicDetector"},
+    {"name": "JwtTokenDetector"},
+    {"name": "KeywordDetector", "keyword_exclude": ""},
+    {"name": "MailchimpDetector"},
+    {"name": "NpmDetector"},
+    {"name": "OpenAIDetector"},
+    {"name": "PrivateKeyDetector"},
+    {"name": "PypiTokenDetector"},
+    {"name": "SendGridDetector"},
+    {"name": "SlackDetector"},
+    {"name": "SoftlayerDetector"},
+    {"name": "SquareOAuthDetector"},
+    {"name": "StripeDetector"},
+    {"name": "TelegramBotTokenDetector"},
+    {"name": "TwilioKeyDetector"}
+  ],
+  "filters_used": [
+    {"path": "detect_secrets.filters.allowlist.is_line_allowlisted"},
+    {"path": "detect_secrets.filters.common.is_baseline_file"},
+    {"path": "detect_secrets.filters.common.is_ignored_due_to_verification_policies", "min_level": 2},
+    {"path": "detect_secrets.filters.heuristic.is_indirect_reference"},
+    {"path": "detect_secrets.filters.heuristic.is_likely_id_string"},
+    {"path": "detect_secrets.filters.heuristic.is_lock_file"},
+    {"path": "detect_secrets.filters.heuristic.is_not_alphanumeric_string"},
+    {"path": "detect_secrets.filters.heuristic.is_potential_uuid"},
+    {"path": "detect_secrets.filters.heuristic.is_prefixed_with_dollar_sign"},
+    {"path": "detect_secrets.filters.heuristic.is_sequential_string"},
+    {"path": "detect_secrets.filters.heuristic.is_swagger_file"},
+    {"path": "detect_secrets.filters.heuristic.is_templated_secret"}
+  ],
+  "results": {},
+  "generated_at": "2026-08-13T00:00:00Z"
+}

Makefile

@@ -0,0 +1,76 @@
+.DEFAULT_GOAL := help
+SHELL := /bin/bash
+
+UV      := $(shell command -v uv 2>/dev/null)
+COMPOSE := docker compose -f deploy/docker-compose.dev.yml
+
+ifdef UV
+  RUN := uv run
+else
+  RUN := .venv/bin/python -m
+endif
+
+.PHONY: help install lint fmt typecheck importlint test test-unit migrate makemigration up down dev worker smoke secrets clean
+
+help: ## Show this help
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-16s\033[0m %s\n", $$1, $$2}'
+
+install: ## Create the venv and install runtime + dev dependencies
+ifdef UV
+	uv sync --extra dev
+	uv run pre-commit install || true
+else
+	python3 -m venv .venv
+	.venv/bin/pip install --upgrade pip
+	.venv/bin/pip install -e ".[dev]"
+	.venv/bin/pre-commit install || true
+endif
+
+lint: ## ruff check + ruff format --check
+	uv run ruff check .
+	uv run ruff format --check .
+
+fmt: ## Auto-fix lint issues and format
+	uv run ruff check --fix .
+	uv run ruff format .
+
+typecheck: ## mypy strict on packages/domain + packages/llm, normal elsewhere (§16.2)
+	uv run mypy packages/domain packages/llm
+	uv run mypy apps packages/shared packages/identity packages/billing packages/task packages/agent packages/compliance
+
+importlint: ## Enforce the dependency rules of 架构文档 §4.2
+	uv run lint-imports
+
+test: lint typecheck importlint test-unit ## Full local quality gate (mirrors CI)
+
+test-unit: ## pytest with coverage
+	uv run pytest
+
+secrets: ## Scan the working tree for committed credentials
+	uv run detect-secrets scan --baseline .secrets.baseline
+
+migrate: ## Apply Alembic migrations to $$DATABASE_URL
+	uv run alembic upgrade head
+
+makemigration: ## Autogenerate a migration: make makemigration m="add xxx"
+	uv run alembic revision --autogenerate -m "$(m)"
+
+up: ## Start PostgreSQL(pgvector) + Redis for local development
+	$(COMPOSE) up -d postgres redis
+	$(COMPOSE) ps
+
+down: ## Stop the local stack (keeps volumes)
+	$(COMPOSE) down
+
+dev: ## Run the API with autoreload
+	uv run uvicorn apps.api.main:app --host 0.0.0.0 --port 8000 --reload
+
+worker: ## Run a Celery worker consuming the cpu/io queues
+	uv run celery -A apps.worker.celery_app.celery_app worker -Q cpu,io -l info
+
+smoke: ## End-to-end proof: compose + migrate + API + real DeepSeek call
+	bash scripts/smoke.sh
+
+clean: ## Remove caches and build artefacts
+	rm -rf .pytest_cache .mypy_cache .ruff_cache .coverage htmlcov dist build
+	find . -type d -name __pycache__ -prune -exec rm -rf {} +

README.md

@@ -0,0 +1,166 @@
+# 美搭 backend — 工程地基 (M1)
+
+「美搭」智能穿搭美学助手的服务端。本仓库当前是 **工程地基**，不是业务实现：
+骨架、横切能力、以及一条打通全链路的最小垂直切片。
+
+> 设计文档是唯一事实来源，在 Windows 侧的 `G:\meida\docs\`：
+> 《技术架构文档》《需求规格说明》《开发任务拆解》。本 README 只讲怎么跑起来。
+
+---
+
+## 现在有什么 / 现在没有什么
+
+| 已实现 | 状态 |
+| --- | --- |
+| 仓库结构与包边界（架构 §16.1） | ✅ |
+| ruff / mypy strict / import-linter / pytest / 密钥扫描 全部进 CI（§16.2） | ✅ |
+| 统一响应与错误码 + 异常处理（§9.2, FR-SYS-02） | ✅ |
+| 结构化日志 + 请求/追踪 ID + 日志脱敏（NFR-SEC-03） | ✅ |
+| 异步 SQLAlchemy + Alembic（含 pgvector）+ 首个迁移 | ✅ |
+| OTel + Prometheus + `/healthz` `/readyz` `/metrics` | ✅ |
+| **LLM 网关**：路由 / 故障转移 / 熔断 / 结构化输出 / Prompt 版本 / 缓存前缀纪律 / 成本归因 / 日预算硬熔断 | ✅ |
+| **配额三段式** reserve → commit → refund（§7.4, FR-BILL-05） | ✅ |
+| **统一任务中心** 状态机 + Celery 四队列 + 一个贯通的 `ping` 任务 | ✅ |
+| 垂直切片 `POST /v1/agent/chat` | ✅ |
+
+| 刻意留白（占位） | 归属任务 |
+| --- | --- |
+| 华为账号登录、手机号验证码、双令牌撤销、游客合并、注销 | T-P1-12 ~ T-P1-16 |
+| 统一合规出口（审核 / 水印 / 元数据 / 内容编号） | T-P1-22、T-P1-23（CR-05/CR-06 不可裁剪） |
+| 知识库、混合检索、规则引擎、记忆系统 | M2 |
+| 报告生成、换装、发型、视觉服务、抠图 | M3 / M4 |
+| 智谱 GLM provider（仅结构占位） | 需先核实备案模型清单 |
+| SSE 流式对话、意图识别、生成后校验 | FR-AGT-01/02/05 |
+
+**开始写业务功能前请先读 `packages/README.md` 与对应域的 README** —— 里面写了
+什么能放进去、什么绝对不能。
+
+---
+
+## 快速开始
+
+前置：Python 3.12、Docker、[uv](https://docs.astral.sh/uv/)。
+
+```bash
+# 1. 依赖（本仓库用 uv 管理；uv.lock 锁定全部版本）
+make install
+
+# 2. 配置。复制模板后至少填 DEEPSEEK_API_KEY 与 JWT_SECRET
+cp .env.example .env
+$EDITOR .env
+
+# 3. 起本地基础设施（PostgreSQL 16 + pgvector，Redis 7）
+make up
+make migrate
+
+# 4. 跑起来
+make dev        # API  → http://localhost:8000/api/v1/docs
+make worker     # Celery worker（另开一个终端）
+
+# 5. 真实链路验证：会真的调用 DeepSeek，花真钱
+make smoke
+```
+
+**包管理器：本仓库使用 `uv`**（`uv sync --extra dev`，锁文件 `uv.lock`）。
+没有 uv 时 `make install` 会退回 `python -m venv` + `pip install -e ".[dev]"`，
+但 CI 与 Docker 镜像都走 uv，因此以 `uv.lock` 为准。
+
+### 常用命令
+
+| 命令 | 作用 |
+| --- | --- |
+| `make lint` | ruff check + format check |
+| `make typecheck` | mypy（`packages/domain`、`packages/llm` 为 strict） |
+| `make importlint` | 校验架构 §4.2 的域间依赖规则 |
+| `make test` | 上面三项 + pytest（本地质量门，与 CI 一致） |
+| `make migrate` / `make makemigration m="..."` | Alembic |
+| `make up` / `make down` | 本地 PG + Redis |
+| `make smoke` | 真实 DeepSeek 端到端验证 |
+
+---
+
+## 垂直切片：`POST /v1/agent/chat`
+
+一次请求依次经过：
+
+```
+JWT 鉴权
+  → billing.reserve()           配额预扣，写 bl_ledger(status=reserved)
+  → LLM 网关                     场景路由 → 缓存前缀校验 → 日预算闸门 → DeepSeek
+  → ob_ai_call                  每次 provider 调用（含失败与重试）写一行
+  → billing.commit() / refund() 成功确认扣除，失败自动退还
+  → 统一响应 {code, message, data, request_id}
+```
+
+接口基础路径是架构 §9.1 规定的 `/api/v1`；`/v1/*` 作为等价别名同样可用
+（内部脚本与部分文档用的是后者，见下方「与设计文档的偏差」）。
+
+```bash
+TOKEN=$(curl -s -XPOST localhost:8000/v1/auth/dev-token \
+  -H 'Content-Type: application/json' -d '{"device_key":"me"}' \
+  | python3 -c 'import json,sys;print(json.load(sys.stdin)["data"]["access_token"])')
+
+curl -s -XPOST localhost:8000/v1/agent/chat \
+  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
+  -d '{"message":"面试穿什么？"}' | python3 -m json.tool
+```
+
+### 地基验收结果（M1 出口）
+
+以下均在本机实跑通过，不是「应该可以」：
+
+| 项 | 结果 |
+| --- | --- |
+| `make lint` / `make typecheck` / `make test` | 全绿；147 unit + 3 integration，`packages/llm` + `packages/domain` 覆盖率 97% |
+| import-linter | 6 条契约全部 KEPT（含 compliance / identity 两条禁止依赖） |
+| `make up` + `make migrate` | 8 张表 + `alembic_version` 建成，`vector` 扩展存在，配额规则已播种 |
+| `alembic downgrade base` → `upgrade head` | 可逆，往返成功 |
+| `make smoke`（真实 DeepSeek） | 通过，模型 **`deepseek-v4-flash`**；第二次调用 `tokens_cached=256`，证明缓存前缀纪律真的生效 |
+| Celery 全链路 | `pending → queued → running → succeeded`，`tk_task.result` 落库 |
+
+`GET https://api.deepseek.com/v1/models` 当前只返回两个模型：
+`deepseek-v4-flash` 与 `deepseek-v4-pro`。默认用前者，通过 `DEEPSEEK_MODEL` 切换，
+调用点不写死。
+
+---
+
+## 密钥
+
+- `.env` 在 `.gitignore` 第一条，**永远不要提交**。
+- `.env.example` 记录每一个变量的含义，**不含任何真实值**。
+- pre-commit 与 CI 都跑密钥扫描（detect-secrets + gitleaks）。
+- 生产环境的密钥来自 SSM/KMS，不来自文件（架构 §11.2）。
+
+---
+
+## 本地 GPU
+
+开发机带一块 **RTX 5090（32GB VRAM）**。这意味着 BiRefNet 抠图（TD-07）与
+RTMPose ONNX 人体关键点（TD-05/TD-06）**可以完全在本地开发和调参，不需要租云
+GPU**。相关占位见 `services/vision/` 与 `services/matting/`。
+本仓库尚未实现它们。
+
+---
+
+## 与设计文档的偏差 / 文档待补
+
+记录在此，以便回灌设计文档：
+
+1. **业务域包的位置**：架构 §16.1 的目录树列出了 `packages/{domain,llm,retrieval,
+   rules,memory,compliance,shared}`，但 §4.1 定义了 11 个业务域。由于
+   `compliance` 同时出现在两处，本仓库按「业务域各自是 `packages/<域>/`，
+   `packages/domain/` 只放纯逻辑」来落地。建议在 §16.1 补全域目录。
+2. **接口前缀**：§9.1 规定 `/api/v1`，但多处任务描述使用 `/v1`。本仓库以
+   `/api/v1` 为准，并在 ASGI 层把 `/v1/*` 重写为等价路径。建议文档统一。
+3. **`bl_ledger` 缺 `status` 列**：§6.2 的列清单没有 `status`，但 §7.4 的三段式
+   明确要求 `reserved → committed / refunded`。本仓库补了该列。
+4. **`ob_ai_call` 缺 Prompt 版本列**：§8.1「可复现」要求记录 prompt 版本，
+   §6.2 的列清单里没有。本仓库补了 `prompt_id` / `prompt_version`。
+5. **日成本熔断是「拒绝」而非「告警」**：§13 写的是「超预算自动降级并告警」。
+   本仓库把它实现为硬闸门（非关键场景直接拒绝），因为重试风暴产生成本的速度
+   远快于人响应告警的速度。关键场景通过 `SceneConfig.critical` 豁免。
+6. **单位成本费率是占位值**：`.env.example` 里的 `LLM_COST_RATES_JSON` 需要用
+   供应商实际价目表校准，否则 `ob_ai_call.cost_cents` 只有相对意义。
+7. **`.env` 里的 JSON 值必须用单引号包住**。`scripts/smoke.sh` 会 `source .env`，
+   裸双引号会被 bash 剥掉，JSON 随即损坏且报错发生在 pydantic-settings 内部，
+   现场很难看出根因。模板里已经这么写了，改的时候别改回去。

pyproject.toml

@@ -0,0 +1,279 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "meida-backend"
+version = "0.1.0"
+description = "美搭 (Meida) backend — AI fashion & styling assistant for HarmonyOS"
+readme = "README.md"
+requires-python = ">=3.12,<3.13"
+license = { text = "Proprietary" }
+
+dependencies = [
+    "fastapi>=0.115",
+    "uvicorn[standard]>=0.30",
+    "gunicorn>=22.0",
+    "sqlalchemy[asyncio]>=2.0",
+    "asyncpg>=0.29",
+    "alembic>=1.13",
+    "pydantic>=2.7",
+    "pydantic-settings>=2.3",
+    "celery[redis]>=5.4",
+    "redis>=5.0",
+    "httpx>=0.27",
+    "structlog>=24.1",
+    "opentelemetry-api>=1.25",
+    "opentelemetry-sdk>=1.25",
+    "opentelemetry-instrumentation-fastapi>=0.46b0",
+    "opentelemetry-exporter-otlp-proto-http>=1.25",
+    "prometheus-client>=0.20",
+    "pgvector>=0.2.5",
+    "tenacity>=8.3",
+    "pyjwt[crypto]>=2.8",
+    "passlib[bcrypt]>=1.7.4",
+]
+
+[project.optional-dependencies]
+dev = [
+    "ruff>=0.6",
+    "mypy>=1.11",
+    "pytest>=8.3",
+    "pytest-asyncio>=0.24",
+    "pytest-cov>=5.0",
+    "import-linter>=2.0",
+    "pre-commit>=3.8",
+    "detect-secrets>=1.5",
+    "testcontainers[postgres,redis]>=4.8",
+    "types-passlib>=1.7",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["apps", "packages", "services"]
+
+# ---------------------------------------------------------------------------
+# ruff — lint + format (架构文档 §16.2 静态检查防线)
+# ---------------------------------------------------------------------------
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+src = ["."]
+extend-exclude = ["migrations/versions"]
+
+[tool.ruff.lint]
+select = [
+    "E", "W",   # pycodestyle
+    "F",        # pyflakes
+    "I",        # isort
+    "N",        # pep8-naming
+    "UP",       # pyupgrade
+    "B",        # bugbear
+    "C4",       # comprehensions
+    "SIM",      # simplify
+    "ASYNC",    # async correctness
+    "S",        # bandit (security)
+    "T20",      # no print
+    "RUF",
+]
+ignore = [
+    "S101",  # assert is fine (pytest)
+    "B008",  # FastAPI Depends() in defaults is idiomatic
+    # 本项目面向中文用户，注释/文案/提示词大量使用全角标点。
+    # RUF001-003 会把每一个中文标点都报成 "ambiguous unicode"，无信号价值。
+    "RUF001",
+    "RUF002",
+    "RUF003",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S105", "S106", "S311"]
+"migrations/**" = ["E501"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["apps", "packages", "services"]
+
+[tool.ruff.format]
+quote-style = "double"
+
+# ---------------------------------------------------------------------------
+# mypy — strict 仅覆盖 packages/domain 与 packages/llm (架构文档 §16.2)
+# ---------------------------------------------------------------------------
+[tool.mypy]
+python_version = "3.12"
+plugins = ["pydantic.mypy"]
+ignore_missing_imports = true
+warn_unused_configs = true
+warn_redundant_casts = true
+show_error_codes = true
+namespace_packages = true
+explicit_package_bases = true
+exclude = ["migrations/versions/"]
+
+[[tool.mypy.overrides]]
+module = ["packages.domain.*", "packages.llm.*"]
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+disallow_untyped_calls = true
+disallow_untyped_decorators = true
+disallow_any_generics = true
+disallow_subclassing_any = true
+check_untyped_defs = true
+no_implicit_reexport = true
+warn_return_any = true
+warn_unused_ignores = true
+strict_equality = true
+extra_checks = true
+
+# ---------------------------------------------------------------------------
+# pytest
+# ---------------------------------------------------------------------------
+[tool.pytest.ini_options]
+minversion = "8.0"
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+addopts = [
+    "-ra",
+    "--strict-markers",
+    "--cov=packages.llm",
+    "--cov=packages.domain",
+    "--cov-report=term-missing",
+    "--cov-fail-under=80",
+]
+markers = [
+    "integration: needs PostgreSQL/Redis (docker compose or testcontainers)",
+    "golden: golden-set regression (retrieval / rules / report)",
+]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+    "\\.\\.\\.",
+]
+
+# ---------------------------------------------------------------------------
+# import-linter — 机器化执行架构文档 §4.2 的依赖规则
+# CI 失败即阻断合并 (§16.2 分层依赖检查)
+# ---------------------------------------------------------------------------
+[tool.importlinter]
+root_packages = ["apps", "packages", "services"]
+include_external_packages = true
+
+# --- §16.1: packages/domain 是纯逻辑层，不依赖 FastAPI / DB / HTTP / 队列 ---
+[[tool.importlinter.contracts]]
+name = "packages.domain is pure (no IO, no framework)"
+type = "forbidden"
+source_modules = ["packages.domain"]
+forbidden_modules = [
+    "fastapi",
+    "starlette",
+    "sqlalchemy",
+    "alembic",
+    "asyncpg",
+    "httpx",
+    "redis",
+    "celery",
+    "packages.shared",
+    "packages.llm",
+    "apps",
+    "services",
+]
+
+# --- §4.2 禁止的依赖 (1): compliance 不得反向依赖任何业务域 ---
+[[tool.importlinter.contracts]]
+name = "compliance must not depend on any business domain"
+type = "forbidden"
+source_modules = ["packages.compliance"]
+forbidden_modules = [
+    "packages.identity",
+    "packages.profile",
+    "packages.report",
+    "packages.agent",
+    "packages.tryon",
+    "packages.kb",
+    "packages.billing",
+    "packages.task",
+    "packages.notify",
+    "packages.wardrobe",
+]
+
+# --- §4.2 禁止的依赖 (2): identity 不得依赖其他业务域 ---
+[[tool.importlinter.contracts]]
+name = "identity must not depend on any other business domain"
+type = "forbidden"
+source_modules = ["packages.identity"]
+forbidden_modules = [
+    "packages.profile",
+    "packages.report",
+    "packages.agent",
+    "packages.tryon",
+    "packages.kb",
+    "packages.billing",
+    "packages.task",
+    "packages.compliance",
+    "packages.notify",
+    "packages.wardrobe",
+]
+
+# --- §3.2 硬性规则 1: 禁止直接查对方的表，只能走对方的 service ---
+[[tool.importlinter.contracts]]
+name = "no cross-domain repository (table) access"
+type = "forbidden"
+source_modules = [
+    "packages.agent",
+    "packages.billing",
+    "packages.task",
+    "packages.identity",
+    "packages.compliance",
+]
+forbidden_modules = [
+    "packages.agent.repo",
+    "packages.billing.repo",
+    "packages.task.repo",
+    "packages.identity.repo",
+]
+unmatched_ignore_imports_alerting = "none"
+ignore_imports = [
+    "packages.agent.* -> packages.agent.repo",
+    "packages.billing.* -> packages.billing.repo",
+    "packages.task.* -> packages.task.repo",
+    "packages.identity.* -> packages.identity.repo",
+]
+
+# --- §3.1 分层视图: L3 API → L4 业务域 → L5 AI 能力 → L6 数据 ---
+[[tool.importlinter.contracts]]
+name = "layered architecture (apps -> domains -> ai/shared -> domain)"
+type = "layers"
+layers = [
+    "apps",
+    "packages.agent | packages.report | packages.tryon | packages.profile | packages.notify | packages.wardrobe",
+    "packages.task | packages.billing | packages.kb",
+    "packages.compliance | packages.identity",
+    "packages.llm | packages.retrieval | packages.rules | packages.memory",
+    "packages.shared",
+    "packages.domain",
+]
+exhaustive = false
+
+# --- AI 能力层不得回头依赖业务域 (§4.3: llm-gateway 必须按远程调用设计) ---
+[[tool.importlinter.contracts]]
+name = "AI capability packages must not depend on business domains"
+type = "forbidden"
+source_modules = [
+    "packages.llm",
+    "packages.retrieval",
+    "packages.rules",
+]
+forbidden_modules = [
+    "packages.identity",
+    "packages.profile",
+    "packages.report",
+    "packages.agent",
+    "packages.tryon",
+    "packages.kb",
+    "packages.billing",
+    "packages.task",
+    "apps",
+]