feat: Phase 4 多租户隔离 + 四阶段升级测试 + CSS 统一化

Phase 4: org_id 注入 JWT/API 过滤/组织管理 CRUD/前端组织列测试: tests/test_phase_upgrades.py 97项全覆盖 CSS: theme-modern.css 共享 mobile-card-list/status-dot/search-bar 等模式修复: initial_data.py LLM配置 NOT NULL 约束, TopicResponse 含 org_id
2026-05-17 06:56:53 +08:00
parent 301dc3e438
commit 9c37c9a574
45 changed files with 3707 additions and 1366 deletions
@@ -0,0 +1,72 @@
+# AGENTS.md
+
+## Stack
+- **Backend**: FastAPI 0.104 + SQLAlchemy 2.0 + PostgreSQL 15 (`yzr_nr`)
+- **Frontend**: Vue 3 (CDN, no build step) + Element Plus — static HTML served by FastAPI
+- **Auth**: JWT (`python-jose` + bcrypt), default admin `admin/admin123`
+- **Scheduler**: APScheduler (daily cron: 01:30 collect, 02:30 sync, 03:30 generate, 04:30 optimize, 05:00 optimize_sources)
+- **LLM**: Multi-provider (opencode-go primary, nvidia backup). API keys only in `.env`, not DB.
+
+## Commands
+
+```bash
+# Start server (with detach to survive shell timeout)
+cd /root/openclaw-workspace/projects/yu-zhi-ran
+setsid ./start-platform.sh 8001
+
+# Run full integration test
+cd /root/openclaw-workspace/projects/yu-zhi-ran && python3 tests/test_new_features.py
+
+# Run specific scripts (from project root)
+python3 scripts/collector.py
+python3 scripts/creator.py --topic-id B02
+```
+
+## Project layout
+
+```
+yu-zhi-ran/
+├── platform/
+│   ├── backend/app/main.py       # FastAPI entry, mounts frontend at /
+│   ├── backend/app/api/*.py      # 21 API routers
+│   ├── backend/app/core/         # nvidia_client.py, scheduler.py, etc.
+│   ├── backend/app/models.py     # SQLAlchemy models (593 lines)
+│   ├── backend/app/schemas.py    # Pydantic schemas (504 lines)
+│   ├── backend/app/database.py   # PG env config + ALTER TABLE migrations
+│   ├── backend/app/initial_data.py
+│   └── backend/.env              # API keys, DB creds
+├── scripts/                      # creator.py, writer.py, collector.py, etc.
+├── tests/test_new_features.py    # 33-test integration suite
+└── PROGRESS.md                   # Single source of truth for project status
+```
+
+## Gotchas & conventions
+
+### Server
+- Shell timeout kills background processes — always use `setsid` to start
+- Env in `platform/backend/.env`, loaded via `dotenv` at each module level
+
+### Database
+- `init_db()` in `database.py` runs ALTER TABLE migrations at startup (PostgreSQL)
+- `USE_POSTGRES=false` falls back to SQLite (used in tests)
+- Models have timezone-aware `DateTime(timezone=True)` columns
+
+### LLM
+- `call_llm()` in `core/nvidia_client.py` — reads active provider from DB `LLMConfig.is_active`, API key from env
+- DeepSeek reasoning models return `reasoning_content` (thinking) + `content` (answer). `call_llm` prefers `content`, falls back to tail of `reasoning_content`
+- `max_tokens` must be generous (≥500 for tags/titles, ≥2000 for article content) — reasoning models consume tokens for thinking
+- Schema (`LLMConfigResponse`) must include `provider`, `base_url`, `api_key` fields or they get silently dropped from API responses
+
+### Frontend
+- No npm build step — edit `.html` files directly
+- H5 mobile nav only created when `window.innerWidth <= 768`
+- `navigation-component.js` + `navbar-component.js` injected as Vue components
+- For date filters on topics, use backend `?today=true` (server-side `date.today()`) — client-side `new Date()` gives UTC which differs from Asia/Shanghai by 8h
+
+### Tests
+- `test_new_features.py` starts its own uvicorn on port 18503, runs against SQLite
+- Run from project root: `python3 tests/test_new_features.py`
+
+### Project status
+- PROGRESS.md is the single truth source for progress — update it after any significant task
+- `archive/` dir keeps historical/outdated docs with `YYYY-MM-DD` date suffix