# AiPlan 项目说明

---

## 一、项目初衷与目标

### 1.1 设计初衷

在现代社会，个人与团队的计划管理需求日益增长，传统的计划工具难以满足智能化、个性化和高效协作的需求。AiPlan 致力于通过 AI 技术与现代前端技术结合，打造一个智能、灵活、可扩展的计划管理平台。

### 1.2 解决的核心问题
- **计划碎片化**：用户计划分散，难以统一管理。
- **协作低效**：团队成员协作不畅，信息同步滞后。
- **智能化不足**：缺乏智能推荐、自动优化等功能。
- **扩展性差**：传统工具难以根据业务变化快速扩展。

---

## 二、设计思路

### 2.1 系统架构
- **前端**：基于 React + TypeScript，采用组件化、模块化开发，支持响应式布局。
- **后端**（预期）：RESTful API，支持微服务架构，便于横向扩展。
- **AI 服务**（预期）：独立服务，提供智能推荐、自动计划等能力。
- **数据库**（预期）：关系型数据库（如 PostgreSQL）+ 缓存（如 Redis）。

### 2.2 前端架构
- 采用分层结构：页面（pages）- 组件（components）- 服务（services）- 工具（utils）。
- 状态管理：Context/Redux，便于全局状态同步。
- 路由管理：React Router。
- 样式方案：Tailwind CSS，支持主题切换与响应式。
- 接口统一管理，便于维护和扩展。

### 2.3 可扩展性与可维护性
- 组件高度解耦，便于复用和单元测试。
- 业务逻辑与视图分离，降低维护成本。
- 统一接口与数据结构，便于前后端协作。

### 2.4 安全性设计
- 前端防止 XSS、CSRF 攻击。
- 接口鉴权采用 JWT，敏感操作需二次确认。
- 数据传输全程 HTTPS。

---

## 三、技术栈与选择理由

| 技术         | 作用/理由                                                                 |
|--------------|--------------------------------------------------------------------------|
| React        | 现代主流前端框架，组件化开发，生态丰富，社区活跃                         |
| TypeScript   | 静态类型检查，提升代码健壮性与可维护性                                   |
| Tailwind CSS | 原子化 CSS，开发效率高，易于定制主题，支持响应式                         |
| ESLint       | 代码质量保障，统一团队编码风格                                           |
| Prettier     | 代码格式化，提升代码可读性                                               |
| Jest         | 单元测试框架，保障核心逻辑稳定                                           |
| React Testing Library | 组件测试，贴近用户行为，提升测试覆盖率                         |
| Vite/CRA     | 快速开发与构建工具，提升开发体验                                         |
| GitHub Actions/CI     | 自动化测试与部署，保障交付质量                                   |

---

## 四、功能规划与未来展望

### 4.1 当前功能
- 任务/计划的增删改查
- 任务分类与标签管理
- 任务优先级与进度追踪
- 响应式界面，适配多端

### 4.2 未来展望
- AI 智能推荐与自动计划生成
- 团队协作与权限管理
- 日历视图与甘特图支持
- 多语言与国际化
- 插件/扩展机制，支持自定义功能
- 移动端 App 支持

---

## 五、业务流程与系统架构（文字描述）

1. 用户注册/登录，获取身份令牌（JWT）。
2. 进入主界面，加载用户计划数据。
3. 用户可创建、编辑、删除、分类、标记任务。
4. 前端通过统一的 API 服务与后端通信，所有请求均带上鉴权 Token。
5. 任务数据支持实时同步（后续可接入 WebSocket）。
6. AI 服务可根据用户历史行为，推荐计划或自动生成任务。
7. 用户可邀请他人协作，分配任务，设置权限。
8. 所有操作均有日志记录，便于审计与回溯。

---

## 六、前后端通信机制

### 6.1 通信协议与安全
- 全部接口采用 HTTPS，防止中间人攻击。
- 鉴权采用 JWT，Token 失效自动跳转登录。
- 敏感操作需二次确认（如删除、批量操作）。

### 6.2 接口设计与幂等性
- RESTful 风格，资源路径清晰。
- POST/PUT 操作需保证幂等性，防止重复提交。
- 支持批量操作接口，提升效率。

### 6.3 错误码体系
| code | 含义           | 说明                     |
|------|----------------|--------------------------|
| 0    | 成功           | 操作成功                 |
| 1001 | 参数错误       | 请求参数校验失败         |
| 1002 | 鉴权失败       | Token 无效或过期         |
| 1003 | 权限不足       | 无操作权限               |
| 1004 | 资源不存在     | 查询对象不存在           |
| 1005 | 服务器异常     | 后端服务处理异常         |

### 6.4 数据校验
- 前端表单校验 + 后端二次校验，防止非法数据入库。
- 统一返回错误提示，便于用户理解。

### 6.5 示例接口调用
```typescript
// src/services/task.ts
export async function createTask(task) {
  const res = await fetch('/api/tasks', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer ' + localStorage.getItem('token'),
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(task),
  });
  const data = await res.json();
  if (data.code !== 0) throw new Error(data.msg);
  return data.data;
}
```

---

## 七、开发、测试、部署流程

### 7.1 开发流程
1. Fork & Clone 仓库
2. 新建 feature/bugfix 分支
3. 本地开发，编写/完善单元测试
4. 提交 PR，自动触发 CI 检查
5. 通过代码评审后合并主分支

### 7.2 测试流程
- 单元测试：Jest + React Testing Library
- 集成测试：可用 Cypress 等工具
- 覆盖率要求：核心模块 > 80%

### 7.3 部署流程
- 本地构建：`npm run build`，产物位于 `build/` 或 `dist/`


---


## 八、典型场景举例

### 8.1 个人计划管理
- 用户可新建、编辑、删除个人任务，设置优先级、截止时间、标签等
- 可视化日历查看任务分布

### 8.2 团队协作
- 创建团队项目，邀请成员，分配任务
- 任务进度实时同步，支持评论与附件上传

### 8.3 智能推荐
- AI 根据历史行为、时间安排，自动推荐每日/每周计划
- 智能检测任务冲突，给出优化建议

---