doc:整理文档

2026-04-06 23:12:45 +08:00
parent d00a907da0
commit 141b3112a4
12 changed files with 154 additions and 121 deletions
@@ -0,0 +1,32 @@
+---
+alwaysApply: true
+description: 强制文档同步规范：每次变更代码（如新增功能、修改接口、调整架构等）必须同步更新 README.md 和 docs 目录下的相关文档。
+---
+
+# 文档同步规范（必须遵守）
+
+## 通用原则
+
+- **代码即文档，文档随代码**：文档不是静态的，它必须真实反映当前代码的状态。
+- **及时性**：在提交代码变更的同时（或紧随其后），必须完成相关文档的更新。
+- **准确性**：确保文档中的示例代码、接口说明、安装步骤与实际代码完全一致。
+
+## 更新范围
+
+- **README.md**：
+  - 如果变更涉及核心功能点（Features）、安装步骤（Installation）、快速开始（Quick Start）或 API 端点（API Endpoints），必须同步更新。
+  - 变更涉及技术栈调整或项目结构变化时需更新。
+- **docs/ 目录文档**：
+  - **接口变更**：若修改了 API，需同步更新 [技术设计文档](docs/技术设计文档.md) 中的接口部分。
+  - **功能新增/调整**：需在 [产品需求文档](docs/产品需求文档.md) 和 [技术栈与模块](docs/技术栈与模块.md) 中体现。
+  - **架构/模式变更**：需更新 [技术设计文档](docs/技术设计文档.md)。
+  - **代码规范**：若引入了新的编码模式或工具，需更新 [代码规范文档](docs/代码规范文档.md)。
+  - **版本记录**：所有非琐碎的变更必须在 [版本记录.md](docs/版本记录.md) 中添加记录。
+
+## 检查清单
+
+1. [ ] 是否有新增的 API 端点？（更新 README 和技术设计文档）
+2. [ ] 是否修改了现有的业务逻辑或数据结构？（更新技术设计文档）
+3. [ ] 是否有新增的功能模块？（更新产品需求文档和技术栈说明）
+4. [ ] 是否调整了开发环境或依赖？（更新 README）
+5. [ ] 是否在 [版本记录.md](docs/版本记录.md) 中记录了本次变更？
@@ -12,33 +12,6 @@
 - **本地数据持久化**：使用 SQLite 数据库保存数据，支持完全离线使用
 - **HTTP API 通信**：前后端通过 RESTful API 进行数据交互

-### 技术特性
- **现代化架构**：MAUI + WebView + C# 后端 + Vue.js 前端
- **分层设计**：Core（核心层）+ API（后端）+ Web（前端）
- **响应式界面**：Vue.js 3 实现的现代化用户界面
- **统一 API 设计**：RESTful API 风格，支持跨域请求
-
-## 🛠️ 技术栈
-
-### 后端技术栈
- **开发语言**：C# 10
- **框架**：.NET 10
- **UI 框架**：MAUI (Multi-platform App UI)
- **Web 服务器**：Kestrel (ASP.NET Core 内置)
- **API 框架**：ASP.NET Core Web API
- **数据访问**：Entity Framework Core
- **数据库**：SQLite (本地存储)
- **依赖注入**：Microsoft.Extensions.DependencyInjection
-
-### 前端技术栈
- **开发语言**：TypeScript
- **框架**：Vue.js 3
- **构建工具**：Vite
- **HTTP 客户端**：Axios
- **状态管理**：Pinia
- **UI 组件库**：Element Plus / Vant (移动端)
- **CSS 预处理器**：SCSS
-
 ## 📦 安装与使用

 ### 环境要求
@@ -59,9 +32,8 @@ cd Hua.Todo

 #### 2. 启动后端 API
 ```bash
-cd src/Hua.Todo.Api
+cd src/Hua.Todo.Host
 dotnet restore
-dotnet ef database update
 dotnet run
 ```
 API 将在 `http://localhost:5173` 启动
@@ -72,7 +44,7 @@ cd src/Hua.Todo.Web
 npm install
 npm run dev
 ```
-前端将在 `http://localhost:5173` 启动
+前端将在 `http://localhost:5174` 启动，并自动代理 `/api` 请求到 `http://localhost:5173`

 ### 使用说明
 - **添加任务**：在前端界面中输入任务内容，设置优先级，点击添加按钮
@@ -86,48 +58,14 @@ npm run dev
 ```
 Hua.Todo/
 ├── docs/                          # 文档目录
-│   ├── 产品需求文档.md
-│   ├── 产品需求文档-1.1.0.md
-│   ├── 技术设计文档.md
-│   └── 代码规范文档.md
+│   ├── manual/                    # 用户/开发者手册
+│   └── project/                   # 项目进度/需求文档
 ├── src/                           # 源代码目录
-│   ├── Hua.Todo.Core/              # 核心业务逻辑层
-│   │   ├── Entities/               # 实体类
-│   │   │   ├── Task.cs
-│   │   │   └── TaskPriority.cs
-│   │   └── Interfaces/             # 接口定义
-│   │       ├── ITaskRepository.cs
-│   │       └── ITaskService.cs
-│   ├── Hua.Todo.Api/               # 后端 API 项目
-│   │   ├── Controllers/            # API 控制器
-│   │   │   └── TasksController.cs
-│   │   ├── Services/               # 业务服务
-│   │   │   └── TaskService.cs
-│   │   ├── Repositories/          # 数据访问层
-│   │   │   └── TaskRepository.cs
-│   │   ├── Data/                 # 数据库上下文
-│   │   │   ├── TodoDbContext.cs
-│   │   │   └── Migrations/        # 数据库迁移
-│   │   ├── Models/                # 数据模型
-│   │   │   └── TaskModels.cs
-│   │   ├── Program.cs             # API 入口
-│   │   └── Hua.Todo.Api.csproj   # API 项目文件
-│   ├── Hua.Todo.Web/               # 前端 Web 项目 (Vue.js)
-│   │   ├── public/                # 静态资源
-│   │   ├── src/
-│   │   │   ├── api/            # API 调用
-│   │   │   │   ├── client.ts
-│   │   │   │   └── tasks.ts
-│   │   │   ├── components/     # Vue 组件
-│   │   │   │   ├── TaskList.vue
-│   │   │   │   └── TaskItem.vue
-│   │   │   ├── types/          # TypeScript 类型定义
-│   │   │   │   └── task.ts
-│   │   │   ├── App.vue         # 根组件
-│   │   │   └── main.ts         # 应用入口
-│   │   ├── package.json           # 依赖配置
-│   │   ├── vite.config.ts         # Vite 配置
-│   │   └── tsconfig.json          # TypeScript 配置
+│   ├── Hua.Todo.Core/              # 领域实体与基础接口
+│   ├── Hua.Todo.Application/       # 业务逻辑与应用层实现
+│   ├── Hua.Todo.Host/              # 后端 API 宿主项目 (Kestrel)
+│   ├── Hua.Todo.Web/               # 前端 Web 项目 (Vue.js 3 + Vite)
+│   ├── Hua.Todo.Maui/              # 跨平台客户端项目 (Windows/Android/iOS/macOS)
 │   └── Hua.Todo.slnx           # 解决方案文件
 ├── .gitignore                     # Git 忽略文件
 └── README.md                      # 项目说明文档
@@ -141,58 +79,29 @@ Hua.Todo/
 - `PATCH /api/tasks/{id}/complete` - 切换完成状态
 - `DELETE /api/tasks/{id}` - 删除任务

-## 🎯 核心模块说明
+## 🤝 交流与贡献

-### Hua.Todo.Core
-核心业务逻辑层，定义领域模型和业务规则，提供核心业务接口。
+- **QQ 交流群**：2167048911 (Hua.Todo 交流群)
+- **项目地址**：[Hua.Todo](https://git.we965.cn/Tools/Hua.Todo)
+- **贡献指南**：欢迎提交 Pull Request，详见 [其他信息](docs/manual/其他信息.md)

-### Hua.Todo.Api
-后端 API 项目，提供 RESTful API 接口，处理业务逻辑，管理数据访问和持久化。
+## 📄 开源协议

-### Hua.Todo.Web
-前端 Web 项目，基于 Vue.js 3 + TypeScript，提供用户界面，通过 HTTP API 与后端通信。
+本项目采用 **AGPL-3.0** 许可证。详细内容请参阅 [LICENSE](LICENSE) 文件。

-## 🔄 版本更新
+## 📚 更多文档

-### 版本策略
- 采用语义化版本号：`MAJOR.MINOR.PATCH`
- v1.0.0：初始 WPF 版本
- v1.1.0：MAUI + WebView 跨平台版本
- v1.2.0 (规划中)：Linux 支持与增强功能
+### 用户与开发者手册
+- [技术栈与模块说明](docs/manual/技术栈与模块.md)
+- [版本更新历史](docs/manual/版本记录.md)
+- [技术设计文档](docs/manual/技术设计文档.md)
+- [代码规范文档](docs/manual/代码规范文档.md)
+- [其他信息 (贡献、许可证、联系方式)](docs/manual/其他信息.md)

-### v1.1.0 更新内容
- 重构为 MAUI + WebView 架构
- 实现跨平台支持 (Windows, macOS, Android, iOS)
- 使用 HTTP API 进行前后端通信
- 采用 Vue.js 3 作为前端框架
- 使用 SQLite 作为本地数据库
- 实现子任务支持
-
-### v1.2.0 规划内容 (即将推出)
- **Linux 官方支持**：正式适配 Linux 平台。
- **搜索与过滤**：支持按标题搜索、按优先级和状态过滤。
- **本地提醒**：支持设置任务提醒时间并发送本地通知。
- **标签系统**：引入多标签支持，提升任务组织效率。
- **暗色模式**：全平台适配暗色/深色主题。
- **数据导出导入**：支持 JSON 格式数据备份与迁移。
-
-## 🤝 贡献指南
-
-1. Fork 项目
-2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
-3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
-4. 推送到分支 (`git push origin feature/AmazingFeature`)
-5. 打开 Pull Request
-
-## 📄 许可证
-
-本项目采用 AGPL-3.0 许可证 - 查看 [LICENSE](LICENSE) (英文) 或 [LICENSE.zh-CN](LICENSE.zh-CN) (中文) 文件了解详情
-
-## 📞 联系方式
-
- 项目作者：ShaoHua
- 项目地址：https://git.we965.cn/Tools/Hua.Todo
+### 项目进度与需求
+- [产品需求文档](docs/project/产品需求文档.md)
+- [Android 离线排查计划](docs/project/Android_NotFound_排查计划.md)
+- [实现对比文档](docs/project/实现对比文档.md)

 ---
-
 **Hua.Todo** - 跨平台任务管理，让效率无处不在！
@@ -0,0 +1,19 @@
+# 其他信息
+
+## 🤝 贡献指南
+
+1. Fork 项目
+2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
+3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
+4. 推送到分支 (`git push origin feature/AmazingFeature`)
+5. 打开 Pull Request
+
+## 📄 许可证
+
+本项目采用 AGPL-3.0 许可证 - 查看 [LICENSE](LICENSE) (英文) 或 [LICENSE.zh-CN](LICENSE.zh-CN) (中文) 文件了解详情
+
+## 📞 联系方式
+
+- 项目作者：ShaoHua
+- 项目地址：https://git.we965.cn/Tools/Hua.Todo
+- QQ 交流群：2167048911 (Hua.Todo 交流群)
@@ -0,0 +1,39 @@
+# 技术栈与模块说明
+
+## 🛠️ 技术栈
+
+### 后端技术栈
+- **开发语言**：C# 10
+- **框架**：.NET 10
+- **UI 框架**：MAUI (Multi-platform App UI)
+- **Web 服务器**：Kestrel (ASP.NET Core 内置)
+- **API 框架**：ASP.NET Core Web API
+- **数据访问**：Entity Framework Core
+- **数据库**：SQLite (本地存储)
+- **依赖注入**：Microsoft.Extensions.DependencyInjection
+
+### 前端技术栈
+- **开发语言**：TypeScript
+- **框架**：Vue.js 3
+- **构建工具**：Vite
+- **HTTP 客户端**：Axios
+- **状态管理**：Pinia
+- **UI 组件库**：Element Plus / Vant (移动端)
+- **CSS 预处理器**：SCSS
+
+## 🎯 核心模块说明
+
+### Hua.Todo.Core
+领域实体层，定义核心实体（TaskEntity）、枚举（TaskPriority）以及仓储接口（ITaskRepository）。
+
+### Hua.Todo.Application
+应用层实现，包含业务逻辑、动态 API 生成逻辑、EF Core 数据库上下文以及具体的服务实现（TaskService）。
+
+### Hua.Todo.Host
+后端 API 宿主，提供运行环境和配置，是后端服务的启动入口。
+
+### Hua.Todo.Web
+前端 Web 项目，基于 Vue.js 3 + TypeScript + Vite，提供用户界面，通过 HTTP API 与后端通信。
+
+### Hua.Todo.Maui
+跨平台客户端项目，将 Web 内容嵌入到原生容器中，支持 Windows、Android、iOS 和 macOS。
@@ -30,10 +30,14 @@
 ```
 Hua.Todo/
 ├── docs/                              # 文档目录
-│   ├── PRD.md                         # 产品需求文档
-│   ├── PRD-1.1.0.md                   # v1.1.0 产品需求文档
-│   ├── TechnicalDesign.md             # 技术设计文档（本文件）
-│   └── CodeStandards.md               # 代码规范文档
+│   ├── manual/                        # 用户/开发者手册
+│   │   ├── 技术栈与模块.md
+│   │   ├── 版本记录.md
+│   │   ├── 技术设计文档.md（本文件）
+│   │   └── 代码规范文档.md
+│   └── project/                       # 项目进度/需求文档
+│       ├── 产品需求文档.md
+│       └── ...
 │
 ├── src/                               # 源代码目录
 │   ├── Hua.Todo.Maui/                 # MAUI 主项目（跨平台入口）
@@ -0,0 +1,30 @@
+# 版本更新历史
+
+## 🔄 版本更新
+
+### 版本策略
+- 采用语义化版本号：`MAJOR.MINOR.PATCH`
+- v1.0.0：初始 WPF 版本
+- v1.1.0：MAUI + WebView 跨平台版本
+- v1.2.0 (规划中)：Linux 支持与增强功能
+
+### v1.1.1 (2026-04-06)
+- **文档规范增强**：新增文档同步规则，强制代码变更与文档更新保持同步。
+- **项目结构说明校准**：修正 README.md 和技术文档中对 `Hua.Todo.Host`、`Hua.Todo.Application` 等模块的路径与职责描述。
+- **端口配置校准**：修正文档中关于前端与后端 API 的端口说明（5173/5174）。
+
+### v1.1.0 更新内容
+- 重构为 MAUI + WebView 架构
+- 实现跨平台支持 (Windows, macOS, Android, iOS)
+- 使用 HTTP API 进行前后端通信
+- 采用 Vue.js 3 作为前端框架
+- 使用 SQLite 作为本地数据库
+- 实现子任务支持
+
+### v1.2.0 规划内容 (即将推出)
+- **Linux 官方支持**：正式适配 Linux 平台。
+- **搜索与过滤**：支持按标题搜索、按优先级和状态过滤。
+- **本地提醒**：支持设置任务提醒时间并发送本地通知。
+- **标签系统**：引入多标签支持，提升任务组织效率。
+- **暗色模式**：全平台适配暗色/深色主题。
+- **数据导出导入**：支持 JSON 格式数据备份与迁移。