docs: update project docs and clean up redundant files

- PROGRESS.md: update to 2026-05-29 with security hardening (T-005),
  4-frontend architecture, AI provider refactoring, discovery features,
  landing page/referral/quota, desktop layout, admin AI management
- AGENTS.md: add AI provider list (Alibaba/NVIDIA, removed Claude/DeepL/Local),
  DB-driven config, CSRF/rate-limit/CORS notes, admin_ai reload quirk
- .env.example: sync with actual config, replace deprecated providers
  with current Sensenova/OpencodeGo/NVIDIA/Spark/Alibaba
- docs/PROJECT_STATUS.md: archive (fully superseded by PROGRESS.md)
- Remove generated JS files (_bing_search.js, _batch_search.js)
- Remove empty directories (data/corpus, data/models)
- Remove backend/.coverage (test artifact)
- Fix services/.gitignore to cover _bing_search.js
- Include pending AI provider DB admin feature (admin_ai, AIProvider model,
  AIProviders.vue, migration) and T-008 test report
This commit is contained in:
TradeMate Dev
2026-05-29 11:15:33 +08:00
parent c04fa2c19f
commit 5d2bced39f
31 changed files with 1933 additions and 816 deletions
+28 -8
View File
@@ -3,19 +3,38 @@
## Architecture
- **Backend**: `backend/` — FastAPI + SQLAlchemy 1.4 async + asyncpg, single `app.main:app`
- **Frontend**: `uni-app/` — Vue 3 + uni-app (H5 first, later WeChat mini-program)
- **Frontends**: `uni-app/` (mobile H5/mini-program), `admin-frontend/` (PC admin), `user-frontend/` (PC workspace)
- **Config**: `backend/app/config.py` reads from `/.env` (project root) via pydantic BaseSettings
- **Auth**: JWT (python-jose). Default dep `get_current_user_id` in `backend/app/api/v1/deps.py`
- **AI Router**: `backend/app/ai/router.py` — singleton `AIRouter`, primary=`opencode_go`, fallbacks=sensenova/openai/anthropic
- **AI Router**: `backend/app/ai/router.py` — singleton `AIRouter`, DB-driven providers. Primary = sensenova, fallbacks = alibaba-mt / opencode_go / nvidia / spark
- **Database**: PostgreSQL via `asyncpg`, pool_size=20
## AI Providers
- **Active**: Sensenova (商汤), OpencodeGo, NVIDIA, 讯飞 Spark, 阿里机器翻译 (alibaba-mt)
- **Removed (dead code)**: Claude (`claude.py`), DeepL (`deepl.py`), Local (`local.py`) — git rm'd, not yet committed
- **DB-driven**: `AIProvider` model + `admin_ai.py` API — manage providers at runtime. `router.seed_from_env()` loads from `.env` on startup
- **Provider type mapping** in `router.py._build_provider()`: sensenova, opencode_go, nvidia, spark, alibaba-mt
## Security
- **CORS**: `middleware.py` — whitelist origins, restricted methods/headers
- **Rate Limit**: endpoint-specific — login 5/min, register 3/h, password 3/5min, payment 20/min, admin 30/min
- **CSRF**: `core/csrf.py` — double-submit cookie pattern. Required on auth/payment/profile. Webhooks skipped.
- **Login**: JSON `LoginRequest` model, not `OAuth2PasswordRequestForm`
## Customer Discovery
- `discovery.py` + `discovery_record.py` — Google Custom Search integration
- Contact extraction from company websites (email/phone/WhatsApp/WeChat)
## Dev Commands
```bash
# Backend (from project root — .env is there)
cd backend && source venv/bin/activate && uvicorn app.main:app --reload --port 8000
# Frontend — uni-app (mobile)
# Mobile H5
cd uni-app && npm run dev:h5
# Admin frontend (PC management)
@@ -41,10 +60,10 @@ alembic revision --autogenerate -m "desc"
## Deployment
- **Landing page** at `trade.yuzhiran.com/` — static marketing HTML
- **SPA** at `trade.yuzhiran.com/app/` — uni-app build (mobile)
- **Admin** at `trade.yuzhiran.com/admin/` — Vue 3 + Element Plus (standalone)
- **Workspace** at `trade.yuzhiran.com/workspace/` — Vue 3 + Element Plus (standalone)
- **Landing page**: `trade.yuzhiran.com/` — static marketing HTML
- **SPA**: `trade.yuzhiran.com/app/` — uni-app build (mobile)
- **Admin**: `trade.yuzhiran.com/admin/` — Vue 3 + Element Plus (standalone)
- **Workspace**: `trade.yuzhiran.com/workspace/` — Vue 3 + Element Plus (standalone)
- **Nginx**: SPA fallbacks for `/app/`, `/admin/`, `/workspace/`
- **vite config**: each project has its own `base` path and dev port
- **API**: proxied via nginx `location /api/` to `127.0.0.1:8002`
@@ -56,8 +75,9 @@ alembic revision --autogenerate -m "desc"
- **Manual auth on some endpoints**: `keywords` and `competitor-analysis` endpoints use `authorization: str = Header(None)` instead of `Depends(get_current_user_id)`.
- **MarketingService fallback**: When no AI providers initialized, returns template content instead of crashing.
- **Onboarding service**: calls `mkt.generate(product_info={"name": ..., ...})`, not keyword args. Check `onboarding.py` for the exact dict shape.
- **Login**: `POST /api/v1/auth/login` uses JSON `LoginRequest` model, not `OAuth2PasswordRequestForm`.
- **CustomerHealthService**: `get_health_overview` endpoint must use `CustomerHealthService(db)` not `CustomerService(db)`.
- **CSRF**: Sensitive endpoints (auth/payment/profile) require `X-CSRF-Token` header. Token available via `csrf_token` cookie / `X-CSRF-Token` response header.
- **AI Router reload**: After modifying AI providers via admin API, call `POST /api/v1/admin/ai/reload` to refresh in-memory providers.
## Project Conventions