# 模块导航与拆分规范

四阶段拆分已落地：`am.py` 保留命令及 WSGI 兼容入口，应用工厂和业务代码位于 `logistics_chat/`，页面样式与脚本位于 `static/`。本文描述当前结构及后续结构调整约定。

## 先定位，再阅读

从 [AGENTS.md](../AGENTS.md) 选择文件，以函数、常量、接口为锚点，搜索后只读取相关实现和调用方。模块移动时更新索引，不保存易失效的行号。默认遵守 Git 忽略规则，排除附件、数据库、日志、备份、虚拟环境和工作草稿。

```powershell
rg --files
rg -n -F 'calc_freight' logistics_chat/pricing.py
rg -n -F '/api/human/' logistics_chat/routes static/js examples
rg -n '^(def |class |    def )' scripts tests -g '*.py'
```

PowerShell 下把目录和 `-g '*.py'` 分开传给 `rg`。报价字典可能整行很长，搜索时加 `--max-columns 200 --max-columns-preview`，避免输出整份数据。

## 当前模块索引

| 业务范围 | 实际文件与搜索锚点 | 联动位置 |
|---|---|---|
| 应用入口与配置 | `am.py`：`main`、延迟访问的 `app`；`logistics_chat/__init__.py`：`create_app`；`config.py`：`default_config`、`get_setting`；`runtime.py`：`serve_app` | `start.bat`、`.env.example` |
| Jenkins 灰度部署 | `Jenkinsfile`、`Dockerfile`；`deploy/gray_config.py`：`GrayConfig`；`publish-gray.sh`、`activate-gray.sh`、`prepare-gray-tls.sh`、`renew-gray-tls.sh` | [部署指南](deployment.md)；独立持久化数据、证书和回环端口；`wsgi.py` 提供容器内路径 |
| 请求钩子 | `logistics_chat/hooks.py`：`rate_limit`、`no_cache_html` | 工厂注册钩子；限流状态在 `app.extensions['rate_hits']` |
| SQLite 与维护 | `logistics_chat/db.py`：`connect`、`close_connections`、`init_db`、`backup_db`、`save_message`、`last_user_question`、`load_context` | 维护 CLI 在 `scripts/`；旧会话自动清理仍未启用 |
| 历史接口 | `logistics_chat/history_service.py`：`new_chat`、`get_history`、`get_messages`、`del_history`、`clear_all`；对应 `routes/history.py` | `static/js/chat.js`：`ensureConv`、`loadHistory`、`openConversation` |
| 知识检索 | `logistics_chat/knowledge.py`：`knowledge_list`、`search_knowledge` | [knowledge.md](knowledge.md) 与代码同步，程序不读取该文档 |
| 运费与附加费 | `logistics_chat/pricing.py`：`RATES`、`parse_shipping_intent`、`dims_to_cm`、`pick_rate`、`calc_freight`、`freight_reply`、`calc_warehouse_card`、`detect_surcharge`、`check_island` | `logistics_chat/rates_extra.py` 为唯一扩展数据源，根目录同名文件仅兼容转发 |
| 运单轨迹 | `logistics_chat/tracking.py`：`extract_tracking_no`、`build_track`、`CARD_PREFIX`、`card_to_text` | `static/js/chat.js`：`fillTrackCard`、`addTrackCard`；模拟节点时间取当前时刻，回归对照需固定时钟 |
| AI 与 SSE | `logistics_chat/chat_service.py`：`create_chat_stream`、`sse`；`ai_client.py`：`post_completion`、`compress_answer`、`gen_followups` | `routes/chat.py`：`stream_chat`；客户端 `doSend`、`renderError`、`renderFollowups` |
| 人工会话 | `logistics_chat/human_service.py`：`human_*`；对应 `routes/human.py` | 输入状态在 `app.extensions['human_typing']`；客户 `startHumanPoll`；客服 `loadQueue`、`poll`、`sendReply` |
| 附件 | `logistics_chat/file_service.py`：`upload_file`、`cleanup_uploads`；`routes/files.py`：`uploaded_file` | 扩展名/大小/目录由配置提供；客户端 `addMsg`，客服端 `appendMsg` |
| 登录、统计、订单、留言、导出 | `logistics_chat/business_service.py`：`admin_login`、`admin_stats`、`my_orders`、`add_ticket`、`list_tickets`、`export_chat` | `routes/admin.py`、`routes/business.py`；登录页 `static/js/admin_login.js` |
| 页面 | `templates/index.html`、`templates/admin.html`、`templates/admin_login.html` | 先加载共享 `static/css/theme.css`，再加载对应 `chat`、`admin`、`admin_login` 的 CSS/JS；保留全局事件入口 |
| 回归 | `tests/test_rules.py`、`test_storage.py`、`test_api.py`、`test_config.py`、`test_deployment.py`、`test_gray_config.py`、`test_gray_activation.py`、`test_startup.py`、`test_maintenance_scripts.py`、`test_frontend.py`；`tests/frontend/admin.test.cjs` | Linux 回退模拟基础设施、实际操作临时文件；模型、数据库及上传隔离；Node 验证异步交互 |

除标明的根目录文件外，表内缩写的 Python 文件均相对 `logistics_chat/`。

## 当前文件布局

```text
am.py                         # CLI；显式请求 am.app 时创建默认 WSGI 应用
rates_extra.py                # 旧导入路径的兼容转发
logistics_chat/
├── __init__.py               # create_app 与显式运行时初始化
├── config.py                 # 根目录 .env、环境变量、稳定根路径、服务/资源配置
├── db.py                     # 连接、schema、历史持久化、备份
├── knowledge.py              # 知识与关键词检索
├── pricing.py                # 运费规则、解析、换算、附加费说明
├── rates_extra.py            # 扩展报价数据
├── tracking.py               # 单号识别、模拟轨迹、卡片协议
├── ai_client.py              # 模型 HTTP、压缩与追问
├── chat_service.py           # 问答编排与 SSE 帧
├── history_service.py        # 历史会话 CRUD
├── human_service.py          # 人工状态与消息
├── business_service.py       # 反馈、统计、登录、订单、留言、CSV
├── file_service.py           # 附件校验、保存、清理
├── hooks.py                  # 限流及 HTML/SSE 缓存头
├── runtime.py                # Waitress / Flask 启动
└── routes/
    ├── __init__.py           # Blueprint 注册
    ├── chat.py
    ├── history.py
    ├── human.py
    ├── admin.py
    ├── business.py
    ├── files.py
    └── pages.py
templates/                    # HTML/Jinja 及原有事件属性
static/css/                   # theme.css 共享令牌；chat/admin/admin_login 页面样式
static/js/                    # chat.js、admin.js、admin_login.js，经典脚本
scripts/                      # 可独立运行的维护 CLI
tests/                        # 按业务模块组织的回归
```

## 模块边界与依赖方向

- 路由只解析请求并包装响应；服务组织业务；规则模块提供确定性计算。依赖方向为 `routes → services → rules / db / ai_client`，下层不导入路由或根入口。
- `db.py` 统一连接、schema 和历史持久化。人工与管理业务的 SQL 放在所属服务，HTTP 路由不执行 SQL。请求及流式请求结束时关闭连接，未提交事务回滚。
- `init_db` 包括客服账号、订单与留言表，首次启动只建空表；不内置账号。重复初始化保留已有数据，业务测试从真实初始化结果插入夹具，不另建缺失表。
- 所有模型 HTTP 经 `ai_client.post_completion`。保留流式问答 `(5, 90)`、压缩 `(5, 30)`、追问 `(5, 15)` 三组连接/读取超时；不能因共用客户端而合并期限。流结束或取消时释放 HTTP 响应。
- 模块导入不建库、不备份、不清理附件、不访问模型。`create_app` 默认显式初始化运行目录、数据库、备份与旧附件清理；`INITIALIZE_RUNTIME=False` 可禁止这些动作，此时调用方负责提供已有 schema。访问兼容入口 `am.app` 视为显式创建应用。
- `config.ROOT_DIR` 指向仓库根目录，模板/静态目录显式提供给 Flask。数据库、上传、备份、日志使用配置中的绝对路径，避免包文件移动改变数据位置。
- `default_config` 用 `python-dotenv` 读取根目录 `.env`，不修改 `os.environ`；只读取已支持的 `DEEPSEEK_API_KEY`，不展开 `${...}`。显式工厂配置优先于进程环境（含空值），再使用文件值。配置在应用创建时确定，修改后重启；真实 `.env` 不纳入 Git。
- 限流、输入状态由应用实例持有，不能每请求重置或跨测试应用共享。维护 CLI 和纯规则可用标准库加载，包入口延迟导入 Web 依赖。
- 单文件围绕一个职责；超过约 300–400 行时检查职责，而非按行数机械拆分。报价数据保持单一来源；兼容转发不复制字典。页面脚本按页面保留既有执行顺序和全局函数，不擅自改为 ES Modules。
- 配色、字体基线和通用控件放在 `theme.css`，页面布局放在对应 CSS。客户页通过 `body.dark` 覆盖主题令牌；新增可翻译文案加入 `chat.js` 的 `I18N`，静态文案用 `data-i18n`。调整样式后检查桌面、390px 窄屏、侧栏、聊天卡片和客服空/活动状态。
- 客户附件预览由 `clearAttachment` 管理，轨迹展开由 `fillTrackCard` 管理。客服 `drafts` 按 `sid` 保存草稿，发送成功后只清理已确认发送的内容；常用回复仅填入草稿。`renderList` 只在展示数据变化时重绘。
- 客服工作台默认只展示会话列表和全高聊天区；统计使用原生 `details` 收在「数据概览」。`setSessionTab` 切换接待/排队列表，`setChatView` 与 `showSessionList` 控制 720px 及以下的整屏导航，不结束当前会话。`setToolsOpen` 控制默认关闭的服务资料：1200px 以上为侧栏，较窄屏为抽屉；列表入口让未选会话的手机用户也能查看留言。

## 后续结构调整顺序

| 阶段 | 范围 | 验收要求 |
|---|---|---|
| 1. 纯规则 | 知识、报价、运费、运单识别 | 边界结果与迁移前一致；固定时钟比较模拟轨迹；导入无运行数据副作用 |
| 2. 数据访问 | 配置、SQLite、备份、附件 | 临时目录验证 schema 兼容、事务、保留/清理时机和跨目录 CLI |
| 3. 服务/路由 | 模型、聊天、人工、应用工厂、Blueprint | URL/方法/状态/JSON/SSE 不变；保留限流、HTML/SSE 缓存头及根入口 |
| 4. 前端 | 模板与 CSS/JS | 仅迁移时对照原资源内容；主动改版时验证语法、资源 URL、加载顺序、响应式和客户/客服页交互 |

每阶段完成相关验证再推进依赖阶段。鉴权、缺表和计费的业务修复单独说明，避免在结构调整中顺带改行为。

## 必须保留的接口与数据约定

- SSE 字段为 `t`、`e`、`card`、`replace`、`suggest`、`d`，保留流式输出、停止、异常及中断保存。
- `chat_service.create_chat_stream` 在识别运单号时忽略 `[图片]/uploads/...` 和 `[文件]/uploads/...` 路径，避免附件文件名中的时间戳误触发查询；存储与请求仍保留原始附件标记和 URL。
- 历史卡片以 `__CARD__{json}` 保存；原 SQLite 表、字段、角色值和历史记录继续可读。
- 人工申请使用 `conv_id`，返回 `session_id`，后续用 `sid`。状态为 `waiting/active/closed`，消息方向为 `customer/agent`。
- 计费档位、单位换算和舍入保持原样。`calc_freight.total` 仅含基础运费；附加费尚未统一并入。知识文档与 `knowledge_list` 同步维护。
- 上传 URL 保留 `/uploads/`，默认 10MB，扩展名配置保持不变。原附件保留本地、继续忽略，目录迁移不另建一份数据。
- 后台鉴权和会话隔离仍不完整，轨迹为模拟数据。Linux 公网验收用 Nginx 全站密码隔离访问，不代表已修复面向客户开放所需的应用权限。

## 验证与维护

先按 README 安装项目依赖。Windows 使用 `.\.venv\Scripts\python.exe -m pytest -v` 或同解释器的 `-m unittest discover -s tests -v`；Linux/macOS 使用 `.venv/bin/python`。业务测试依赖 Flask，不能用未安装依赖的全局 Python 运行整套测试。模型请求全部模拟，不代表真实 DeepSeek 联调。

路径、函数或资产移动后同步更新根 `AGENTS.md`、本文、知识资料和 README 目录树。仅改导航时检查路径、符号、命令；改业务时补充相关成功和失败分支，前端改动检查实际页面。