5.1 KiB
Repository Guidelines
Project Structure & Module Navigation
Use am.py for CLI/WSGI, logistics_chat/ for business code, and static/css//static/js/ for page assets. Architecture defines module 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 |
| Voice input | static/js/voice.js: ChatVoice.create; logistics_chat/speech_service.py: transcribe_recording, baidu_transcribe; logistics_chat/routes/speech.py |
| Guest identity | static/js/visitor.js: bootstrap and cookie recovery; logistics_chat/visitor_service.py: owner checks; routes/visitor.py: customer human support |
| Customer login | logistics_chat/customer_service.py: sessions, default customer bootstrap, order conversation binding; routes/customer.py; static/js/customer.js: login and logout |
| Chat drafts | static/js/drafts.js: ChatDrafts.create; chat.js: flushDraft, restoreDraft, startup recovery |
| 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 |
| Order test data | logistics_chat/order_data.py: lookup_order, answer_query, import_records; scripts/import_order_test_data.py |
| Persistence | logistics_chat/db.py: init_db, save_message; logistics_chat/history_service.py |
| Human support | logistics_chat/human_service.py: lifecycle, transfer, notes, recall; 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; admin_tools.js: notes, transfer, search; support.js: emoji, notifications, rating |
| 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/ |
| Deployment | Jenkinsfile, Dockerfile; deploy/gray_config.py: GrayConfig; publish/activate/TLS scripts; docs/deployment.md |
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
start.bat prefers active VIRTUAL_ENV; verify 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.
Tests run tests/frontend/admin.test.cjs, chat.test.cjs, voice.test.cjs, visitor.test.cjs, and drafts.test.cjs when Node.js is available; no npm dependencies. Baidu ASR uses FFmpeg on PATH or FFMPEG_BIN; provider calls are mocked in tests.
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 root .env; environment variables override it. Restart after changes. create_app initializes storage unless INITIALIZE_RUNTIME=False; order and staff tables start empty. The requested default customer account is separate from staff and stores only a password hash. Default HOST is 0.0.0.0; Linux deployment binds loopback. Staff authentication relies on Nginx: protect staff and unknown routes by default and expose only the owner-checked customer allowlist. Never expose the upstream port publicly. Guest keys authorize public chat history, never customer orders. Order facts and sensitive conversation history require the server-validated customer and tenant; never accept tenant claims from client input. Do not assign unowned legacy records to a new visitor.