schoolNews/schoolNewsServ/.doc/快速开始.md

# 校园思政新闻平台 - 快速开始

## 📦 项目结构

```
school-news/
├── admin/          # 管理后台入口
├── api/            # API接口定义
│   ├── api-all/
│   ├── api-auth/
│   └── api-system/
├── auth/           # 认证模块
├── system/         # 系统管理模块（用户、权限、部门等）
├── news/           # 资源/新闻管理模块
├── study/          # 学习管理模块 🆕
├── usercenter/     # 个人中心模块 🆕
├── ai/             # 智能体模块 🆕
└── common/         # 公共模块
    ├── common-all/
    ├── common-annotation/
    ├── common-core/
    ├── common-dto/
    ├── common-exception/
    ├── common-jdbc/
    ├── common-redis/
    └── common-util/
```

## 🚀 快速开始

### 1. 环境要求

- **JDK**: 21+
- **Maven**: 3.8+
- **MySQL**: 8.0+
- **Redis**: 6.0+ (可选)

### 2. 数据库初始化

#### Windows环境
```cmd
cd .bin/mysql
init-database.bat
```

#### Linux/Mac环境
```bash
cd .bin/mysql
chmod +x init-database.sh
./init-database.sh
```

#### 手动执行
```bash
cd .bin/mysql/sql
mysql -u root -p < createDB.sql
mysql -u root -p < createTableUser.sql
mysql -u root -p < createTablePermission.sql
mysql -u root -p < createTablePermissionControl.sql
mysql -u root -p < createTableResource.sql
mysql -u root -p < createTableCourse.sql
mysql -u root -p < createTableLearning.sql
mysql -u root -p < createTableUserCenter.sql
mysql -u root -p < createTableAI.sql
mysql -u root -p < createTableSystem.sql
```

### 3. 配置数据库连接

修改各模块的 `application.yml`：
```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/school_news
    username: root
    password: your_password
```

### 4. 编译项目

```bash
mvn clean install
```

### 5. 启动服务

各模块端口分配：
- **admin**: 8080 (管理后台入口)
- **auth**: 8082 (认证服务)
- **system**: 8081 (系统管理)
- **study**: 8084 (学习管理) 🆕
- **usercenter**: 8085 (个人中心) 🆕
- **ai**: 8086 (智能体) 🆕

启动顺序建议：
1. auth (认证服务)
2. system (系统管理)
3. 其他业务模块

### 6. 访问系统

- **管理后台**: http://localhost:8080
- **默认账号**: admin
- **默认密码**: 查看 `.bin/mysql/sql/createTableUser.sql`

## 📋 模块功能说明

### system (系统管理) - 已有
- 用户管理
- 部门管理
- 角色管理
- 权限管理
- 菜单管理

### news (资源/新闻) - 待扩展
- 资源管理
- 分类管理
- Banner管理
- 推荐管理
- 标签管理
- 数据采集

### study (学习管理) - 新建 🆕
- 学习任务
- 任务分配
- 学习记录
- 学习统计
- 课程管理
- 章节管理
- 课程标签
- 权限控制
### usercenter (个人中心) - 新建 🆕
- 用户收藏
- 成就系统
- 积分系统
- 浏览记录

### ai (智能体) - 新建 🆕
- AI对话
- 知识库
- 文件问答
- 对话历史

## 🔧 开发指南

### 新增接口步骤

1. **定义API接口** (在api模块)
```java
// api-course/src/main/java/org/xyzh/api/course/CourseApi.java
public interface CourseApi {
    @GetMapping("/course/list")
    Object getCourseList(...);
}
```

2. **创建DTO** (在common-dto)
```java
// common/common-dto/src/main/java/org/xyzh/common/dto/course/TbCourse.java
public class TbCourse extends BaseDTO {
    private String courseID;
    private String name;
    // ...
}
```

3. **创建Mapper** (在业务模块)
```java
// course/src/main/java/org/xyzh/course/mapper/CourseMapper.java
@Mapper
public interface CourseMapper extends BaseMapper<TbCourse> {
}
```

4. **创建Service** (在业务模块)
```java
// course/src/main/java/org/xyzh/course/service/CourseService.java
public interface CourseService {
}

// course/src/main/java/org/xyzh/course/service/impl/CourseServiceImpl.java
@Service
public class CourseServiceImpl implements CourseService {
}
```

5. **创建Controller** (在业务模块)
```java
// course/src/main/java/org/xyzh/course/controller/CourseController.java
@RestController
@RequestMapping("/course")
public class CourseController implements CourseApi {
}
```

### 权限控制使用

详见：[权限控制使用说明](.bin/mysql/sql/权限控制使用说明.md)

基本用法：
```java
// 检查用户对资源的权限
SELECT can_read, can_write, can_execute 
FROM tb_resource_permission
WHERE resource_type = 2  -- 课程
  AND resource_id = 'course_001'
  AND (dept_id IS NULL OR dept_id = '用户部门')
  AND (role_id IS NULL OR role_id IN ('用户角色'))
  AND deleted = 0;
```

## 📚 参考文档

### 数据库相关
- [表结构详细说明](.bin/mysql/sql/README.md)
- [表结构汇总](.bin/mysql/sql/表结构汇总.md)
- [ER关系图](.bin/mysql/sql/ER关系图.md)
- [使用说明](.bin/mysql/使用说明.md)

### 开发相关
- [模块创建完整指南](.doc/模块创建完整指南.md)
- [模块创建进度](.doc/模块创建进度.md)
- [需求文档](.doc/需求文档.md)

## ⚠️ 注意事项

1. **数据库编码**: 使用 utf8mb4
2. **主键生成**: 使用 UUID
3. **软删除**: 所有表使用 deleted 字段
4. **日志**: 使用 Log4j2，不要用 Logback
5. **权限**: 所有资源需配置权限控制

## 🐛 常见问题

### Q1: 启动时提示端口被占用
**A**: 修改对应模块的 `application.yml` 中的 `server.port`

### Q2: 数据库连接失败
**A**: 检查 MySQL 服务是否启动，用户名密码是否正确

### Q3: MyBatis找不到Mapper
**A**: 检查 `mybatis-plus.mapper-locations` 配置是否正确

### Q4: 权限检查失败
**A**: 确保在 `tb_resource_permission` 表中配置了相应的权限记录

## 📞 技术支持

遇到问题请参考：
1. 项目根目录下的 `.doc/` 文档
2. 数据库 SQL 脚本中的注释
3. 代码中的 JavaDoc 注释

## 🎯 后续计划

- [ ] 完成所有模块的业务代码
- [ ] 添加单元测试
- [ ] 集成Swagger文档
- [ ] 添加Redis缓存
- [ ] 性能优化
- [ ] 安全加固