diff --git a/.trae/rules/documentation_sync.md b/.trae/rules/documentation_sync.md new file mode 100644 index 0000000..807ec31 --- /dev/null +++ b/.trae/rules/documentation_sync.md @@ -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) 中记录了本次变更？ diff --git a/README.md b/README.md index 122ae30..278081f 100644 --- a/README.md +++ b/README.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** - 跨平台任务管理，让效率无处不在！ diff --git a/docs/代码规范文档.md b/docs/manual/代码规范文档.md similarity index 100% rename from docs/代码规范文档.md rename to docs/manual/代码规范文档.md diff --git a/docs/manual/其他信息.md b/docs/manual/其他信息.md new file mode 100644 index 0000000..a352a04 --- /dev/null +++ b/docs/manual/其他信息.md @@ -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 交流群) diff --git a/docs/manual/技术栈与模块.md b/docs/manual/技术栈与模块.md new file mode 100644 index 0000000..e6561f2 --- /dev/null +++ b/docs/manual/技术栈与模块.md @@ -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。 diff --git a/docs/技术设计文档.md b/docs/manual/技术设计文档.md similarity index 96% rename from docs/技术设计文档.md rename to docs/manual/技术设计文档.md index 3daa45e..9e1a582 100644 --- a/docs/技术设计文档.md +++ b/docs/manual/技术设计文档.md @@ -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 主项目（跨平台入口） diff --git a/docs/manual/版本记录.md b/docs/manual/版本记录.md new file mode 100644 index 0000000..ffb0614 --- /dev/null +++ b/docs/manual/版本记录.md @@ -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 格式数据备份与迁移。 diff --git a/docs/Android_NotFound_排查计划.md b/docs/project/Android_NotFound_排查计划.md similarity index 100% rename from docs/Android_NotFound_排查计划.md rename to docs/project/Android_NotFound_排查计划.md diff --git a/docs/产品需求文档-1.1.0.md b/docs/project/产品需求文档-1.1.0.md similarity index 100% rename from docs/产品需求文档-1.1.0.md rename to docs/project/产品需求文档-1.1.0.md diff --git a/docs/产品需求文档-1.2.0.md b/docs/project/产品需求文档-1.2.0.md similarity index 100% rename from docs/产品需求文档-1.2.0.md rename to docs/project/产品需求文档-1.2.0.md diff --git a/docs/产品需求文档.md b/docs/project/产品需求文档.md similarity index 100% rename from docs/产品需求文档.md rename to docs/project/产品需求文档.md diff --git a/docs/实现对比文档.md b/docs/project/实现对比文档.md similarity index 100% rename from docs/实现对比文档.md rename to docs/project/实现对比文档.md