ouyangxq
805675f8db
- 拆分应用工厂、业务服务与路由，保留原有 HTTP/SSE 和存储入口 - 分离页面资源，重排客服工作台并完善响应式导航、草稿和附件交互 - 整理维护脚本、请求示例和贡献指南，移除启动脚本中的密钥配置 - 上传文件改为仅本地保留，补充隔离的后端与前端回归验证 验证：46 项 Python 测试通过，含 14 个已有子测试；12 个 Node 前端场景通过。
62 lines
3.5 KiB
Markdown
62 lines
3.5 KiB
Markdown
# 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](docs/architecture.md) 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`, `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.
|
|
|
|
```powershell
|
|
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:
|
|
|
|
```powershell
|
|
py -3 -m venv .venv
|
|
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
|
|
$env:DEEPSEEK_API_KEY = "<your-key>"
|
|
.\.venv\Scripts\python.exe am.py
|
|
.\.venv\Scripts\python.exe -m unittest discover -s tests -v
|
|
```
|
|
|
|
Commands use project `.venv`. 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`. `.env` is not loaded automatically. 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.
|