好的，这是一份为你规划的详细开发路线图。它遵循你的要求：核心聊天功能优先，一开始就使用SQLite，TUI的优化放在核心功能完成后。这个路线图强调迭代开发和模块化。

**核心原则：**

* **迭代开发**：每个阶段都产出可测试的功能。
* **先后端再前端（逻辑部分）**：确保服务器逻辑稳固后再重点开发客户端交互。
* **SQLite先行**：所有数据持久化从一开始就通过SQLite完成。
* **协议驱动**：`common/protocol.py` 是客户端和服务器沟通的基石，优先定义。
* **TUI逐步完善**：初期TUI只需满足基本交互，后期打磨。

------

**开发路线图**

**Phase 0: 项目搭建与基础定义 **

1. 环境准备
   * 创建项目总目录 `chat_project/`。
   * 初始化Git版本控制 (`git init`)。
   * 创建并激活Python虚拟环境。
   * 创建 `requirements.txt` (初期可能为空或只有 `textual`, `werkzeug` 以后添加)。
2. 目录结构搭建
   * 按照我们之前讨论的模块化结构创建所有子目录 (`client/`, `server/`, `common/` 等) 和空的 `__init__.py` 文件。
3. 核心协议定义 (`common/protocol.py`)
   * 定义初步的消息类型常量 (如 `REQ_LOGIN`, `RESP_LOGIN_SUCCESS`, `REQ_REGISTER`, `RESP_REGISTER_FAIL`, `MSG_TYPE_TEXT_SEND`, `MSG_TYPE_TEXT_BROADCAST` 等)。
   * 定义初步的数据载荷结构（可以使用字典，或开始引入 `common/dto.py` 中的 `dataclasses`）。至少包括登录/注册信息、文本消息结构。
4. 通用工具 (`common/utils.py`)
   * 可以先放一些未来可能用到的辅助函数，如日期时间格式化等。

**Phase 1: 服务器端 - 用户认证与会话管理 **

1. 数据库模块 (`server/data_access/database_manager.py`)
   * 实现SQLite数据库连接的建立与关闭。
   * 实现 `users` 表的创建。
   * 实现用户的CRUD操作 (创建用户、根据用户名查询用户、更新用户状态)。
2. 认证服务 (`server/services/auth_service.py`)
   * 实现用户注册逻辑 (密码哈希使用 `werkzeug.security` 或类似库)。
   * 实现用户登录逻辑 (验证用户名、密码哈希比对)。
3. 用户服务 (`server/services/user_service.py`)
   * 实现用户上线/下线状态更新逻辑 (修改数据库中 `is_online` 字段)。
4. 请求分发器 (`server/core/request_dispatcher.py`) (初步)
   * 能解析认证相关的请求 (基于 `common/protocol.py`)。
   * 将请求分发到 `auth_service.py`。
5. 客户端会话 (`server/core/client_session.py`) (初步)
   * 处理新连接，接收数据。
   * 将接收到的数据传递给 `request_dispatcher`。
   * 管理客户端的基本状态 (如是否已认证、用户ID)。
   * 在用户认证成功后，调用 `user_service` 更新用户为在线状态。
   * 在连接断开时，调用 `user_service` 更新用户为离线状态。
6. 服务器主程序 (`server/main_server.py`) (初步)
   * 启动TCP Socket服务器，监听端口。
   * 接受客户端连接，为每个连接创建一个 `client_session` 实例 (考虑使用线程或异步IO来处理多客户端)。
7. 单元测试/集成测试
   * 对 `database_manager.py` 的用户操作进行单元测试。
   * 对 `auth_service.py` 的注册登录逻辑进行单元测试。
   * 编写一个极简的Python脚本作为临时客户端，测试服务器的注册和登录流程。

**Phase 2: 客户端 - 用户认证与基本交互 **

1. 网络服务 (`client/network/client_service.py`)
   * 实现连接到服务器的功能。
   * 实现发送序列化请求 (基于 `common/protocol.py`) 和接收响应的功能。
   * 启动一个后台线程/任务来持续监听来自服务器的消息。
2. 命令处理器 (`client/services/command_processor.py`) (初步)
   * 解析 `/login {username} {password}` 和 `/signin {username} {password}` 命令。 (注意：实际密码不在命令中输入，而是后续提示输入)
3. 应用控制器 (`client/app_controller.py`) (初步)
   * 处理登录/注册的逻辑流程：提示用户输入用户名、密码。
   * 调用 `network.client_service` 发送认证请求。
   * 处理认证响应 (成功/失败)。
4. 消息处理器 (`client/network/message_handler.py`) (初步)
   * 能处理登录/注册的响应消息。
   * 将结果通知给 `app_controller`。
5. 客户端主程序 (`client/main_client.py`) (初步)
   * 初始化 `app_controller` 和 `network_service`。
   * 提供一个极简的 `print/input` 循环，允许用户输入命令，调用 `command_processor`。
   * **此阶段不涉及Textual TUI**，目的是打通认证流程。
6. 集成测试
   * 使用此客户端连接到已完成Phase 1的服务器，测试注册和登录功能。

**Phase 3: 核心聊天功能 - 文本消息**

1. 服务器端
   * `common/protocol.py`: 增加文本消息相关的协议定义 (发送、广播)。
   * `server/data_access/database_manager.py`
     * 实现 `chat_groups` 表的创建 (至少先有公频 `public`)。
     * 实现 `group_members` 表的创建 (所有用户默认加入公频)。
     * 实现 `messages` 表的创建和消息存储/读取功能。
   * `server/services/chat_service.py`
     * 实现发送消息到特定聊天组的逻辑 (先支持公频)。
     * 消息存储到数据库。
   * `server/core/broadcast_service.py`
     * 实现向特定聊天组的所有在线成员广播消息的功能。
     * 维护聊天组和用户会话的映射关系。
   * `server/core/request_dispatcher.py`: 添加处理发送消息请求的路由。
   * `server/core/client_session.py`: 用户登录成功后，将其加入默认聊天组的广播列表。
2. 客户端
   * `client/services/command_processor.py`
     * 允许用户直接输入文本（非 `/` 开头的）作为聊天消息发送。
   * `client/app_controller.py`
     * 处理发送聊天消息的逻辑。
     * 处理从 `message_handler` 收到的广播消息，并将其打印到控制台。
   * `client/network/message_handler.py`: 添加处理服务器广播的聊天消息的逻辑。
3. 集成测试
   * 启动多个客户端实例，登录后互相发送和接收消息。
   * 检查服务器数据库中消息是否正确存储。

**Phase 4: 初步TUI集成 (Textual) **

1. 客户端 (`client/tui/app_tui.py`)
   * 使用Textual搭建基本的三栏界面：聊天区、输入区、状态区（状态区此时可简单显示固定信息或最近的系统消息）。
   * 聊天区能显示消息列表 (从 `app_controller` 获取)。
   * 输入区能捕获用户输入。
2. 客户端 (`client/app_controller.py`)
   * 修改以适配Textual：
     * 当收到新消息时，不再是 `print()`，而是调用 `app_tui` 的方法更新聊天区。
     * 从 `app_tui` 获取用户输入，然后传递给 `command_processor` 或作为消息发送。
3. 测试
   * 确保基本的聊天消息收发能在Textual界面中正常工作。
   * 测试界面布局和基本交互。

**Phase 5: 聊天组与用户列表功能**

1. 服务器端
   * `common/protocol.py`: 增加聊天组管理、用户列表相关的协议。
   * `server/data_access/database_manager.py`: 完善 `chat_groups` 和 `group_members` 的CRUD。
   * `server/services/chat_service.py`: 实现 `/create_chat`, `/enter_chat`, `/join_chat` 的逻辑。
   * `server/services/user_service.py`: 实现获取用户列表、聊天组用户列表的逻辑。
   * `server/core/request_dispatcher.py`: 添加相应路由。
2. 客户端
   * `client/services/command_processor.py`: 实现解析 `/list`, `/create_chat`, `/enter_chat`, `/join_chat` 命令。
   * `client/app_controller.py`: 处理这些命令的逻辑，与服务器交互，并更新TUI。
   * `client/network/message_handler.py`: 处理服务器返回的列表信息、聊天组加入成功/失败等响应。
   * `client/tui/app_tui.py`
     * 在状态区显示 `/list` 命令的结果。
     * 更新以反映当前所在的聊天组。
     * 当进入聊天组时，默认显示当前聊天组用户列表（`/list -s` 的效果）。
3. 测试
   * 全面测试聊天组的创建、加入、进入功能。
   * 测试各种 `/list` 命令的输出是否正确显示在TUI状态区。

**Phase 6: 文件传输功能**

1. 服务器端
   * `common/protocol.py`: 定义文件传输相关的协议 (请求上传、开始上传、数据块、上传完毕、请求下载、文件信息、下载数据块等)。
   * `server/data_access/database_manager.py`: 实现 `files_metadata` 表的创建和CRUD。
   * `server/services/file_service.py`
     * 处理客户端上传请求，分配文件ID/路径。
     * 接收文件数据块并存储到 `storage/uploaded_files/`。
     * 处理客户端下载请求，读取文件并分块发送。
   * `server/services/chat_service.py`: 在聊天消息中嵌入文件通知 (文件名、大小、由谁发送)。
   * `server/core/request_dispatcher.py`: 添加文件传输相关路由。
2. 客户端
   * `client/services/command_processor.py`: 实现 `/send_files`, `/recv_files` 命令解析。
   * `client/services/file_transfer_client.py`
     * 实现文件分块读取并发送给服务器的逻辑。
     * 实现接收服务器文件数据块并写入本地文件的逻辑。
   * `client/app_controller.py`: 协调文件上传/下载流程，更新TUI。
   * `client/network/message_handler.py`: 处理文件相关的通知和数据。
   * `client/tui/app_tui.py`: 在聊天区显示文件通知，可能显示传输进度（可选）。
3. 测试
   * 客户端之间互相发送和接收不同大小、类型的文件。
   * 检查服务器 `storage/` 目录和 `files_metadata` 表。

**Phase 7: AI集成 (glm-4-flash) **

1. 服务器端

   * `server/services/ai_service.py`

     * 封装与智谱AI API的交互逻辑。
     * 处理错误和超时。

   * `server/services/chat_service.py`

      或 `ai_service.py`

     * 判断消息是否需要AI处理（私聊AI用户或群聊中 `@AI`）。
     * 构建prompt，调用 `ai_service` 获取回复。
     * 将AI回复作为一条消息通过 `broadcast_service` 发送。

   * (可选) 在 `users` 表中创建一个特殊的AI用户。

2. 客户端

   * AI的回复会被当作普通消息处理，客户端改动较小。
   * 可能需要在 `command_processor` 中对 `@AI` 的输入做一些特殊识别或提示。

3. 测试

   :

   * 在私聊和群聊中与AI进行交互。

**Phase 8: TUI打磨与细节完善**

1. 客户端 (`client/tui/app_tui.py`)
   * 优化消息显示格式（颜色、对齐、时间戳）。
   * 改进状态区列表的显示美观度。
   * 实现 `/info` 命令的界面显示。
   * 密码输入框的掩码处理。
   * 确保三个区域按需刷新。
2. 客户端/服务器端
   * 完善错误处理和用户提示 (如命令错误、网络异常、文件不存在等)。
   * 实现 `/help {command}`。
   * 实现 `/?`。
3. 代码审查与重构
   * 检查模块耦合度，进行必要的调整。
   * 补充注释。

**Phase 9: 测试、文档与收尾**

1. 全面测试
   * 多用户场景测试。
   * 边界条件测试 (空消息、大文件、错误命令等)。
   * 压力测试 (可选)。
2. 文档编写
   * 完善 `README.md`：项目介绍、如何运行、命令列表、已知问题等。
   * 必要的代码注释。
3. 代码清理
   * 移除不必要的调试代码。
   * 格式化代码。

------

**一些通用建议：**

* **小步快跑**：每个小功能点完成后都进行测试。
* **版本控制**：频繁使用Git提交，每次提交都应对应一个小的、完整的功能点或修复。
* **日志**：在服务器端和客户端添加适当的日志记录，方便调试。
* **配置文件**：将服务器端口、数据库文件名、AI密钥等配置项放入 `config_server.py` 和 `config_client.py`。

这份路线图比较详尽，你可以根据实际进度和遇到的困难进行调整。祝你项目顺利！