3.5 KiB
Repository Guidelines
Project Structure & Module Navigation
am.py is a compatible CLI/WSGI entry. Business code lives in logistics_chat/; templates load page assets from static/css/ and static/js/. See architecture for ownership, contracts, and extraction rules.
| Area | Files and search anchors |
|---|---|
| AI | logistics_chat/chat_service.py: create_chat_stream; logistics_chat/ai_client.py: post_completion |
| Knowledge | logistics_chat/knowledge.py: knowledge_list, search_knowledge; docs/knowledge.md |
| Pricing | logistics_chat/pricing.py: RATES, calc_freight; logistics_chat/rates_extra.py |
| Tracking | logistics_chat/tracking.py: extract_tracking_no, build_track, CARD_PREFIX |
| Persistence | logistics_chat/db.py: init_db, save_message; logistics_chat/history_service.py |
| Human support | logistics_chat/human_service.py; logistics_chat/routes/human.py |
| Business / files | logistics_chat/business_service.py, logistics_chat/file_service.py; logistics_chat/routes/ |
| UI | templates/; static/css/theme.css: tokens; page CSS; static/js/chat.js: doSend, I18N; static/js/admin.js: poll, sendReply, setChatView |
| Startup / hooks | logistics_chat/__init__.py: create_app; config.py: default_config; hooks.py, runtime.py in that package |
| CLI / tests | start.bat: probe_python; scripts/, tests/, examples/requests/ |
Efficient Search & File Boundaries
Start with mapped files, then follow callers. Prefer symbols over saved line numbers. rg --files includes untracked source; respect ignored runtime data.
rg --files
rg -n -F -e 'calc_freight' -e '/api/human/' logistics_chat static/js
Routes adapt HTTP; services compose rules, persistence, and model calls. Keep pure rules independent of Flask. Preserve URL/SSE/storage contracts and update navigation after moves.
Build, Test, and Development Commands
Run from the repository root:
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
Copy-Item .env.example .env # First run only; set DEEPSEEK_API_KEY inside .env.
.\.venv\Scripts\python.exe am.py
.\.venv\Scripts\python.exe -m unittest discover -s tests -v
Optional start.bat prefers active VIRTUAL_ENV; verify selection with start.bat --check-python. No frontend build is required.
Coding Style & Naming Conventions
Use four-space Python indentation, snake_case, UPPER_SNAKE_CASE constants, and JavaScript camelCase. Preserve Chinese terminology. No formatter/linter is configured.
Testing Guidelines
Use tests/test_<feature>.py and test_<behavior>. Mock DeepSeek; configure temporary database/upload/backup/log paths before create_app. Pytest: .\.venv\Scripts\python.exe -m pytest -v; Linux/macOS: .venv/bin/python -m pytest -v.
With Node.js installed, tests also run tests/frontend/admin.test.cjs; no npm dependencies are required.
Commit & Pull Request Guidelines
History uses concise Chinese summaries. Keep commits focused. PRs explain behavior, validation, linked issues, and UI screenshots.
Security & Configuration Tips
Never commit credentials or runtime/customer data. Revoke exposed keys. Keep uploads/.gitkeep. Startup reads the root .env; environment variables override it. Restart after changes. Imports are inert; create_app initializes runtime storage unless INITIALIZE_RUNTIME=False. Default HOST remains 0.0.0.0. Missing agents/orders/tickets initialization and complete admin authentication remain unresolved.