aiotagro/xlxumu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(website): 优化新闻轮播功能并更新导航链接

Browse Source
This commit is contained in:
ylweng
2025-09-01 01:24:55 +08:00
parent 451bab4a96
commit 2ba5ae0a72
15 changed files with 2926 additions and 193 deletions
Download Patch File Download Diff File Expand all files Collapse all files

224
docs/API_DOCUMENTATION_CHECKLIST.md Normal file
View File

@@ -0,0 +1,224 @@
# API 文档格式检查清单
## 1. 文档结构检查
### 1.1 文档头部
- [ ] 文档标题包含系统名称和版本号：`# 系统名称 API 文档 (vX.Y.Z)`
- [ ] 版本号采用语义化版本格式：`v主版本.次版本.修订号`
### 1.2 接口概述
- [ ] 包含功能范围说明（1.1）
- [ ] 包含基础路径说明（1.2）：`/api/vX/系统名称`
- [ ] 包含权限控制说明（1.3）
- [ ] 包含全局错误码表格（1.4）
### 1.3 接口明细
- [ ] 接口按功能模块分组（2.x）
- [ ] 每个接口有清晰的序号和名称
- [ ] 接口路径使用相对路径（基于基础路径）
### 1.4 版本历史
- [ ] 包含版本历史章节
- [ ] 每个版本有更新日期和说明
## 2. 接口定义检查
### 2.1 请求参数
- [ ] 使用表格格式定义请求参数
- [ ] 包含参数名、类型、必填、说明四列
- [ ] 参数类型使用标准类型：string、number、boolean、array、object、file
- [ ] 必填字段明确标注：是/否
### 2.2 响应格式
- [ ] 统一使用标准响应格式：
```json
{
"status": "success",
"data": {}
}
```
- [ ] 错误响应格式：
```json
{
"status": "error",
"code": "ERROR_CODE",
"message": "错误描述"
}
```
### 2.3 代码块格式
- [ ] HTTP方法使用大写：GET、POST、PUT、DELETE
- [ ] 接口路径使用反引号包裹
- [ ] JSON示例格式正确，缩进一致
## 3. 内容质量检查
### 3.1 准确性
- [ ] 接口路径与实际实现一致
- [ ] 参数定义准确无误
- [ ] 响应示例真实有效
### 3.2 完整性
- [ ] 包含所有必要的接口
- [ ] 参数说明详细完整
- [ ] 错误处理描述清晰
### 3.3 一致性
- [ ] 术语使用一致
- [ ] 格式风格统一
- [ ] 命名规范一致
## 4. 格式规范检查
### 4.1 Markdown格式
- [ ] 标题层级正确（# ## ###）
- [ ] 表格格式规范
- [ ] 代码块语言标识正确
- [ ] 列表格式一致
### 4.2 文字质量
- [ ] 无拼写错误
- [ ] 无语法错误
- [ ] 描述清晰易懂
- [ ] 专业术语准确
## 5. 安全检查
### 5.1 权限控制
- [ ] 明确标注接口权限要求
- [ ] 敏感接口有安全说明
- [ ] 认证方式描述清晰
### 5.2 数据安全
- [ ] 敏感数据加密要求
- [ ] 数据传输安全说明
- [ ] 访问控制描述
## 6. 版本管理检查
### 6.1 版本兼容性
- [ ] 版本变更说明清晰
- [ ] 向后兼容性考虑
- [ ] 废弃接口标注
### 6.2 更新记录
- [ ] 更新日期准确
- [ ] 变更内容详细
- [ ] 影响范围说明
## 7. 使用说明
### 7.1 检查流程
1. 使用脚本批量检查：`python scripts/update_api_docs.py`
2. 人工复核检查清单
3. 记录不符合项并整改
4. 验证整改结果
### 7.2 检查频率
- 新接口开发：开发完成后立即检查
- 接口变更：变更后立即检查
- 定期检查：每月一次全面检查
### 7.3 检查责任人
- 开发工程师：接口开发时自查
- 技术负责人：代码审查时检查
- 架构师：定期全面检查
## 8. 常见问题
### 8.1 格式问题
- 缺少版本号
- 权限控制不明确
- 响应格式不统一
- 参数定义不完整
### 8.2 内容问题
- 接口描述不清晰
- 示例代码错误
- 错误处理缺失
- 安全要求不明确
### 8.3 维护问题
- 版本更新不及时
- 变更记录缺失
- 兼容性说明不足
## 9. 附录
### 9.1 标准模板
```markdown
# 系统名称 API 文档 (v1.0.0)
## 1. 接口概述
### 1.1 功能范围
- 功能点1
- 功能点2
- 功能点3
### 1.2 基础路径
`/api/v1/system`
### 1.3 权限控制
- 公开接口（无需认证）：数据查询
- 管理接口（需要认证）：数据管理
- 系统接口（高级权限）：配置管理
### 1.4 全局错误码
| 状态码 | 说明 |
|--------|--------------------|
| 400 | 请求参数无效 |
| 401 | 未授权 |
| 403 | 权限不足 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |
## 2. 接口明细
### 2.1 获取数据
```
GET /data
```
**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|-------------|--------|------|--------------------|
| id | string | 是 | 数据ID |
**响应示例**:
```json
{
"status": "success",
"data": {
"id": "123",
"name": "示例数据"
}
}
```
## 3. 版本历史
### v1.0.0 (2024-01-20)
- 新增: 初始版本发布
- 功能: 基础数据接口
```
### 9.2 检查记录表
| 检查日期 | 检查人 | 文档名称 | 问题描述 | 整改状态 | 备注 |
|----------|--------|----------|----------|----------|------|
| 2024-01-20 | 张三 | dashboard.md | 缺少版本号 | 已整改 | |
| 2024-01-20 | 李四 | farming.md | 响应格式不统一 | 已整改 | |
### 9.3 相关文档
- [API文档格式规范标准](../API_DOCUMENTATION_STANDARD.md)
- [文档更新与审核机制](../DOCUMENTATION_MAINTENANCE_PROCESS.md)
- [API文档批量更新脚本](../../scripts/update_api_docs.py)
## 10. 修订记录
| 版本 | 修订日期 | 修订内容 | 修订人 |
|------|----------|----------|--------|
| v1.0 | 2024-01-20 | 初始版本 | 架构师 |
| v1.1 | 2024-01-20 | 增加检查项说明 | 架构师 |
**生效日期**: 2024年1月20日

195
docs/API_DOCUMENTATION_STANDARD.md Normal file
View File

@@ -0,0 +1,195 @@
# API 文档格式规范标准
## 1. 文档结构规范
### 1.1 文档头部
```markdown
# [系统名称] API 文档 (v[版本号])
## 1. 接口概述
### 1.1 功能范围
- [功能点1]
- [功能点2]
- [功能点3]
### 1.2 基础路径
`/api/v[版本号]/[系统名称]`
### 1.3 权限控制
- 公开接口（无需认证）：[接口描述]
- 管理接口（需要认证）：[接口描述]
### 1.4 全局错误码
| 状态码 | 说明 |
|--------|--------------------|
| 400 | 请求参数无效 |
| 401 | 未授权 |
| 403 | 权限不足 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |
```
## 2. 接口定义规范
### 2.1 接口格式
```markdown
### [序号].[序号] [接口名称]
```
[HTTP方法] [接口路径]
**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|-------------|--------|------|--------------------|
| param1 | string | 是 | 参数说明 |
| param2 | number | 否 | 参数说明 |
**响应示例**:
```json
{
"status": "success",
"data": {
"field1": "value1",
"field2": "value2"
}
}
```
### 2.2 错误响应格式
```json
{
"status": "error",
"code": "ERROR_CODE",
"message": "错误描述信息"
}
```
## 3. 数据类型规范
### 3.1 基本数据类型
- `string`: 字符串类型
- `number`: 数字类型
- `boolean`: 布尔类型
- `array`: 数组类型
- `object`: 对象类型
- `file`: 文件类型
### 3.2 日期时间格式
- 日期: YYYY-MM-DD
- 时间: YYYY-MM-DDTHH:mm:ssZ (ISO 8601)
## 4. 权限控制规范
### 4.1 权限级别
- **公开**: 无需认证即可访问
- **用户**: 需要用户登录认证
- **管理员**: 需要管理员权限
- **系统管理员**: 需要系统管理员权限
### 4.2 权限标识
在接口定义中明确标注所需权限级别
## 5. 版本管理规范
### 5.1 版本号格式
采用语义化版本号: `v主版本号.次版本号.修订号`
### 5.2 版本兼容性
- 主版本号变更: 不兼容的API修改
- 次版本号变更: 向下兼容的功能性新增
- 修订号变更: 向下兼容的问题修正
## 6. 安全规范
### 6.1 数据传输
- 敏感数据必须使用HTTPS加密传输
- 密码等敏感信息需要加密存储
### 6.2 身份认证
- 使用JWT Token进行身份认证
- Token有效期设置合理时间
## 7. 文档维护规范
### 7.1 更新记录
每次文档更新需要记录:
- 更新日期
- 更新内容
- 更新人员
### 7.2 审核机制
- 新增接口需要经过技术负责人审核
- 重大变更需要经过架构师审核
## 8. 示例模板
```markdown
# 示例系统 API 文档 (v1.0.0)
## 1. 接口概述
### 1.1 功能范围
- 用户管理
- 数据查询
- 系统配置
### 1.2 基础路径
`/api/v1/example`
### 1.3 权限控制
- 公开接口（无需认证）：数据查询
- 管理接口（需要认证）：用户管理、系统配置
### 1.4 全局错误码
| 状态码 | 说明 |
|--------|--------------------|
| 400 | 请求参数无效 |
| 401 | 未授权 |
| 403 | 权限不足 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |
## 2. 接口明细
### 2.1 获取用户列表
```
GET /users
```
**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|-------------|--------|------|--------------------|
| page | number | 否 | 页码(默认1) |
| limit | number | 否 | 每页数量(默认10) |
**响应示例**:
```json
{
"status": "success",
"data": {
"items": [
{
"id": 1,
"username": "user1",
"email": "user1@example.com"
}
],
"total": 100,
"page": 1,
"limit": 10
}
}
```
```
## 9. 检查清单
- [ ] 文档头部格式符合规范
- [ ] 接口定义格式统一
- [ ] 数据类型标注准确
- [ ] 权限控制明确标注
- [ ] 错误响应格式规范
- [ ] 版本号管理规范
- [ ] 安全要求明确
- [ ] 示例代码完整
```

243
docs/DOCUMENTATION_MAINTENANCE_PROCESS.md Normal file
View File

@@ -0,0 +1,243 @@
# 文档更新与审核机制
## 1. 文档分类与责任人
### 1.1 需求文档类
- **责任部门**: 产品部
- **审核人**: 产品经理
- **维护人**: 产品专员
- **存放位置**: `/docs/requirements/`
### 1.2 设计文档类
- **责任部门**: 技术部
- **审核人**: 技术负责人
- **维护人**: 架构师
- **存放位置**: `/docs/design/`
- 架构设计: `/docs/design/architecture/`
- API设计: `/docs/design/api/`
- 数据库设计: `/docs/design/database/`
### 1.3 开发文档类
- **责任部门**: 开发部
- **审核人**: 开发组长
- **维护人**: 开发工程师
- **存放位置**: `/docs/development/`
## 2. 文档更新流程
### 2.1 更新申请
1. 填写《文档更新申请表》
2. 说明更新原因和内容
3. 提交给相应责任人审批
### 2.2 更新审批
- **次要更新**: 责任人直接审批
- **重要更新**: 需要技术负责人会签
- **重大更新**: 需要产品和技术负责人共同审批
### 2.3 更新执行
1. 基于最新版本进行修改
2. 遵循文档格式规范
3. 更新版本号和修改记录
### 2.4 更新验证
1. 修改人自检
2. 审核人复核
3. 相关方确认
## 3. 版本管理规范
### 3.1 版本号规则
- 主版本号.次版本号.修订号 (v1.0.0)
- 主版本号: 重大架构变更
- 次版本号: 功能新增或修改
- 修订号: 问题修复和优化
### 3.2 版本记录格式
```markdown
## 版本历史
### v1.0.1 (2024-01-15)
- 修复: 修正API文档中的参数类型错误
- 优化: 完善数据库索引说明
### v1.0.0 (2024-01-10)
- 新增: 初始版本发布
- 功能: 完成基础架构设计
```
## 4. 审核标准
### 4.1 内容审核
- ✅ 需求描述准确完整
- ✅ 技术方案合理可行
- ✅ 接口定义清晰规范
- ✅ 数据模型设计合理
- ✅ 权限控制安全可靠
### 4.2 格式审核
- ✅ 文档结构符合规范
- ✅ 标题层级清晰合理
- ✅ 表格格式统一规范
- ✅ 代码示例完整正确
- ✅ 图表清晰易懂
### 4.3 质量审核
- ✅ 无拼写和语法错误
- ✅ 专业术语使用准确
- ✅ 逻辑关系清晰明确
- ✅ 前后内容一致无矛盾
## 5. 定期检查机制
### 5.1 月度检查
- 时间: 每月最后一个工作日
- 内容: 检查文档完整性和准确性
- 责任人: 各文档维护人
### 5.2 季度评审
- 时间: 每季度末
- 内容: 全面评审文档质量
- 参与人: 产品、技术、测试代表
### 5.3 年度总结
- 时间: 每年年底
- 内容: 总结文档维护情况
- 输出: 年度文档维护报告
## 6. 变更控制
### 6.1 变更类型
- **紧急变更**: 生产问题修复
- **计划变更**: 版本迭代更新
- **优化变更**: 文档质量提升
### 6.2 变更流程
```mermaid
graph TD
A[提出变更需求] --> B[填写变更申请]
B --> C{变更类型}
C -->|紧急变更| D[紧急审批流程]
C -->|计划变更| E[正常审批流程]
C -->|优化变更| F[简化审批流程]
D --> G[执行变更]
E --> G
F --> G
G --> H[变更验证]
H --> I[更新记录]
```
## 7. 工具支持
### 7.1 文档管理工具
- Git版本控制
- Markdown格式
- 代码审查工具
### 7.2 自动化检查
- Markdown语法检查
- 链接有效性验证
- 代码示例格式检查
### 7.3 协作平台
- 项目管理系统
- 文档协作平台
- 即时通讯工具
## 8. 培训与推广
### 8.1 新员工培训
- 文档规范培训
- 编写技巧分享
- 审核标准讲解
### 8.2 定期分享
- 优秀文档案例分享
- 常见问题总结
- 最佳实践推广
### 8.3 知识库建设
- 建立文档编写指南
- 收集常见问题解答
- 分享成功经验案例
## 9. 绩效评估
### 9.1 评估指标
- 文档完整性
- 更新及时性
- 质量合格率
- 用户满意度
### 9.2 奖励机制
- 优秀文档奖
- 及时更新奖
- 质量提升奖
### 9.3 改进措施
- 定期收集反馈
- 分析问题原因
- 制定改进计划
- 跟踪改进效果
## 10. 附录
### 10.1 文档更新申请表
```markdown
# 文档更新申请表
## 基本信息
- 申请人:
- 申请日期:
- 文档名称:
- 文档路径:
## 更新内容
- 当前版本:
- 目标版本:
- 更新类型: □紧急 □计划 □优化
- 更新说明:
## 审批意见
- 审核人:
- 审核意见:
- 审核日期:
```
### 10.2 文档质量检查表
```markdown
# 文档质量检查表
## 内容质量
- [ ] 需求描述准确完整
- [ ] 技术方案合理可行
- [ ] 接口定义清晰规范
- [ ] 数据模型设计合理
- [ ] 权限控制安全可靠
## 格式规范
- [ ] 文档结构符合规范
- [ ] 标题层级清晰合理
- [ ] 表格格式统一规范
- [ ] 代码示例完整正确
- [ ] 图表清晰易懂
## 文字质量
- [ ] 无拼写和语法错误
- [ ] 专业术语使用准确
- [ ] 逻辑关系清晰明确
- [ ] 前后内容一致无矛盾
```
## 11. 生效与修订
### 11.1 生效日期
2024年1月20日
### 11.2 修订记录
| 版本 | 修订日期 | 修订内容 | 修订人 |
|------|----------|----------|--------|
| v1.0 | 2024-01-20 | 初始版本 | 架构师 |
### 11.3 适用范围
本规范适用于锡林郭勒盟智慧养殖产业平台所有技术文档的管理和维护。

321
docs/design/api/dashboard.md
View File

@@ -1,69 +1,58 @@
# 大屏可视化系统 API 文档
# 大屏可视化系统 API 文档 (v1.0.0)
## 1. 概述
## 1. 接口概述
大屏可视化系统是锡林郭勒盟智慧养殖产业平台的重要组成部分，主要用于展示产业整体数据、实时监控信息和分析结果。该系统通过直观的图表和数据可视化方式，为管理者提供全面的产业洞察。
### 1.1 功能范围
- 产业数据概览展示
- 实时监控数据推送
- 历史数据查询分析
- 地图区域数据展示
## 2. 技术架构
### 1.2 基础路径
`/api/v1/dashboard`
- **前端框架**: Vue.js 3 + ECharts + 自定义可视化组件
- **可视化库**: Apache ECharts
- **响应式设计**: 支持多种大屏比例(16:9, 4:3等)
- **实时数据**: WebSocket实时数据推送
- **状态管理**: Pinia
### 1.3 权限控制
- 公开接口（无需认证）：数据查询和展示
- 管理接口（需要认证）：数据配置和管理
## 3. 功能模块
### 1.4 全局错误码
| 状态码 | 说明 |
|--------|--------------------|
| 400 | 请求参数无效 |
| 401 | 未授权 |
| 403 | 权限不足 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |
### 3.1 产业概览
展示整体产业规模、产值、增长率等关键指标
## 2. 接口明细
### 3.2 养殖监控
实时展示各牧场的养殖情况、环境数据
### 3.3 金融服务
展示贷款、保险等金融服务数据
### 3.4 交易统计
牛只交易量、价格趋势、区域分布等数据
### 3.5 运输跟踪
牛只运输实时状态和路径展示
### 3.6 风险预警
风险事件展示和预警信息推送
### 3.7 生态指标
环保数据、可持续发展指标展示
### 3.8 政府监管
展示政府监管相关数据和政策执行效果
## 4. API 接口
### 4.1 实时数据接口
#### 获取实时数据
### 2.1 获取实时数据
```
GET /api/v1/dashboard/realtime
GET /realtime
```
**请求参数**:
- 无
| 参数名 | 类型 | 必填 | 说明 |
|-------------|--------|------|--------------------|
| 无参数 | | | |
**响应示例**:
```json
{
"timestamp": "2023-08-19T10:30:00Z",
"total_cattle": 128456,
"total_farms": 1245,
"annual_output_value": 2860000000,
"total_transaction": 1520000000
"status": "success",
"data": {
"timestamp": "2023-08-19T10:30:00Z",
"total_cattle": 128456,
"total_farms": 1245,
"annual_output_value": 2860000000,
"total_transaction": 1520000000
}
}
```
#### WebSocket 实时推送
### 2.2 WebSocket实时数据推送
```
WebSocket /api/v1/dashboard/ws
WebSocket /ws
```
**推送数据格式**:
@@ -80,166 +69,178 @@ WebSocket /api/v1/dashboard/ws
}
```
### 4.2 历史数据接口
#### 获取历史数据
### 2.3 获取历史数据
```
GET /api/v1/dashboard/history
GET /history
```
**请求参数**:
- `start_date` (string, optional): 开始日期，格式 YYYY-MM-DD
- `end_date` (string, optional): 结束日期，格式 YYYY-MM-DD
- `type` (string, required): 数据类型 (breeding, transaction, transport, etc.)
| 参数名 | 类型 | 必填 | 说明 |
|-------------|--------|------|--------------------|
| start_date | string | 否 | 开始日期(YYYY-MM-DD)|
| end_date | string | 否 | 结束日期(YYYY-MM-DD)|
| type | string | 是 | 数据类型 |
**响应示例**:
```json
{
"data": [
{
"date": "2023-01",
"value": 8200
},
{
"date": "2023-02",
"value": 9100
}
]
"status": "success",
"data": {
"items": [
{
"date": "2023-01",
"value": 8200
},
{
"date": "2023-02",
"value": 9100
}
],
"total": 12,
"start_date": "2023-01-01",
"end_date": "2023-12-31"
}
}
```
### 4.3 首页地图数据接口
#### 获取锡林郭勒盟区域地图数据
### 2.4 获取区域地图数据
```
GET /api/v1/dashboard/map/regions
GET /map/regions
```
**请求参数**:
- 无
| 参数名 | 类型 | 必填 | 说明 |
|-------------|--------|------|--------------------|
| 无参数 | | | |
**响应示例**:
```json
{
"regions": [
{
"status": "success",
"data": {
"regions": [
{
"id": "xlg",
"name": "锡林浩特市",
"coordinates": [116.093, 43.946],
"cattle_count": 25600,
"farm_count": 120,
"output_value": 650000000
},
{
"id": "dwq",
"name": "东乌旗",
"coordinates": [116.980, 45.514],
"cattle_count": 18500,
"farm_count": 95,
"output_value": 480000000
}
],
"total": 12
}
}
```
### 2.5 获取指定区域详细数据
```
GET /map/region/{regionId}
```
**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|-------------|--------|------|--------------------|
| regionId | string | 是 | 区域ID |
**响应示例**:
```json
{
"status": "success",
"data": {
"region": {
"id": "xlg",
"name": "锡林浩特市",
"coordinates": [116.093, 43.946],
"cattle_count": 25600,
"farm_count": 120,
"output_value": 650000000
"output_value": 650000000,
"trend": "up"
},
{
"id": "dwq",
"name": "东乌旗",
"coordinates": [116.980, 45.514],
"cattle_count": 18500,
"farm_count": 95,
"output_value": 480000000
},
{
"id": "xwq",
"name": "西乌旗",
"coordinates": [117.615, 44.587],
"cattle_count": 21200,
"farm_count": 108,
"output_value": 520000000
},
{
"id": "abg",
"name": "阿巴嘎旗",
"coordinates": [114.971, 44.022],
"cattle_count": 16800,
"farm_count": 86,
"output_value": 420000000
},
{
"id": "snz",
"name": "苏尼特左旗",
"coordinates": [113.653, 43.859],
"cattle_count": 12400,
"farm_count": 65,
"output_value": 310000000
}
]
"farms": [
{
"id": "FARM001",
"name": "锡林浩特市第一牧场",
"coordinates": [116.120, 43.950],
"cattle_count": 2450,
"output_value": 62000000
}
]
}
}
```
#### 获取指定区域详细数据
## 3. 版本历史
### v1.0.0 (2024-01-20)
- 新增: 按照API文档规范标准统一格式
- 优化: 统一响应格式和错误处理
- 功能: 完成基础接口定义
### 2.6 获取大屏配置
```
GET /api/v1/dashboard/map/region/{regionId}
GET /config
```
**请求参数**:
- `regionId` (string, required): 区域ID
| 参数名 | 类型 | 必填 | 说明 |
|-------------|--------|------|--------------------|
| 无参数 | | | |
**响应示例**:
```json
{
"region": {
"id": "xlg",
"name": "锡林浩特市",
"coordinates": [116.093, 43.946],
"cattle_count": 25600,
"farm_count": 120,
"output_value": 650000000,
"trend": "up"
},
"farms": [
{
"id": "FARM001",
"name": "锡林浩特市第一牧场",
"coordinates": [116.120, 43.950],
"cattle_count": 2450,
"output_value": 62000000
}
]
"status": "success",
"data": {
"layout": "grid",
"theme": "dark",
"refresh_interval": 30,
"charts": [
{
"id": "cattle_count",
"type": "line",
"title": "牛只数量趋势",
"position": "top-left"
},
{
"id": "transaction_volume",
"type": "bar",
"title": "交易量统计",
"position": "top-right"
}
]
}
}
```
### 4.4 配置接口
#### 获取可视化配置
### 2.7 更新大屏配置
```
GET /api/v1/dashboard/config
PUT /config
```
**请求参数**:
- 无
| 参数名 | 类型 | 必填 | 说明 |
|-----------------|--------|------|--------------------|
| layout | string | 是 | 布局方式 |
| theme | string | 是 | 主题 |
| refresh_interval| number | 是 | 刷新间隔(秒) |
| charts | array | 是 | 图表配置 |
**响应示例**:
```json
{
"theme": "dark",
"refresh_interval": 30,
"charts": [
{
"id": "breeding_trend",
"type": "line",
"title": "养殖趋势"
}
]
}
```
#### 更新可视化配置
```
PUT /api/v1/dashboard/config
```
**请求体**:
```json
{
"theme": "dark",
"refresh_interval": 30
}
```
**响应示例**:
```json
{
"message": "配置更新成功"
"status": "success",
"data": {
"message": "配置更新成功"
}
}
```

68
docs/design/api/data-platform.md
View File

@@ -1,4 +1,4 @@
# 数据中台系统 API 文档
# 数据中台系统 API 文档 (v1.0.0)
## 1. 接口概述
@@ -8,6 +8,21 @@
- 数据质量监控
### 1.2 基础路径
`/api/v1/[系统名称]`
### 1.3 权限控制
- 公开接口（无需认证）：数据查询
- 管理接口（需要认证）：数据管理
- 系统接口（高级权限）：配置管理
### 1.4 全局错误码
| 状态码 | 说明 |
|--------|--------------------|
| 400 | 请求参数无效 |
| 401 | 未授权 |
| 403 | 权限不足 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |
`/api/v1/data`
## 2. 接口明细
@@ -17,16 +32,65 @@
GET /lineage
```
**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|-------------|--------|------|--------------------|
| source | string | 否 | 源表名 |
| target | string | 否 | 目标表名 |
**响应示例**:
```json
{
"status": "success",
"data": {
"lineage": [
{
"source": "table_a",
"target": "table_b",
"transform_type": "join"
}
]
}
}
```
### 2.2 接口审计
```
GET /audit-logs
```
**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|-------------|--------|------|--------------------|
| start_time | string | 否 | 开始时间 |
| end_time | string | 否 | 结束时间 |
| api_name | string | 否 | 接口名称 |
**响应示例**:
```json
{
"status": "success",
"data": {
"logs": [
{
"id": "log_001",
"api_name": "/lineage",
"request_time": "2024-01-20T10:00:00Z",
"response_time": 150,
"status": "success"
}
],
"total_count": 100
}
}
```
## 3. 性能指标
- 血缘查询响应时间 < 500ms
- 审计日志保留至少180天
- 审计日志保留至少180天
## 3. 版本历史
### v1.0.0 (2024-01-20)
- 新增: 按照API文档规范标准统一格式
- 优化: 统一响应格式和错误处理
- 功能: 完成基础接口定义

90
docs/design/api/farming.md
View File

@@ -4,13 +4,28 @@
### 1.1 功能范围
- 牛只档案管理
- 饲喂记录
- 饲喂记录管理
- 防疫管理
- 繁殖管理
- 环境监测
### 1.2 基础路径
`/api/v1/farming`
### 1.3 权限控制
- 公开接口（无需认证）：数据查询
- 管理接口（需要认证）：数据录入和管理
- 系统接口（高级权限）：批量操作和配置
### 1.4 全局错误码
| 状态码 | 说明 |
|--------|--------------------|
| 400 | 请求参数无效 |
| 401 | 未授权 |
| 403 | 权限不足 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |
## 2. 接口明细
### 2.1 添加牛只
@@ -18,40 +33,97 @@
POST /cattles
```
**请求参数**:
| 字段 | 类型 | 必填 | 说明 |
|--------------|--------|------|--------------------|
| ear_tag | string | 是 | 耳标号(唯一) |
| ear_tag | string | 是 | 耳标号(唯一) |
| breed | string | 是 | 品种 |
| birth_date | string | 是 | 出生日期(YYYY-MM-DD)|
| gender | string | 是 | 性别(公/母) |
| gender | string | 是 | 性别(公/母) |
| weight | number | 否 | 体重(kg) |
**响应示例**:
```json
{
"status": "success",
"data": {
"id": "CATTLE001",
"ear_tag": "NM000001",
"created_at": "2024-01-20T10:00:00Z"
}
}
```
### 2.2 批量导入牛只
```
POST /cattles/batch
```
**请求参数**:
| 字段 | 类型 | 必填 | 说明 |
|--------------|--------|------|--------------------|
| file | file | 是 | Excel文件 |
### 2.3 防疫记录
**响应示例**:
```json
{
"status": "success",
"data": {
"imported_count": 50,
"failed_count": 2,
"failed_items": [
{
"row": 25,
"error": "耳标号格式错误"
}
]
}
}
```
### 2.3 添加防疫记录
```
POST /vaccinations
```
**请求参数**:
| 字段 | 类型 | 必填 | 说明 |
|--------------|--------|------|--------------------|
| cattle_id | string | 是 | 牛只ID |
| cattle_id | string | 是 | 牛只ID |
| vaccine_type | string | 是 | 疫苗类型 |
| date | string | 是 | 接种日期(YYYY-MM-DD)|
| dosage | number | 否 | 剂量(ml) |
| veterinarian | string | 否 | 兽医姓名 |
**响应示例**:
```json
{
"status": "success",
"data": {
"id": "VACC001",
"cattle_id": "CATTLE001",
"vaccine_type": "口蹄疫",
"created_at": "2024-01-20T10:30:00Z"
}
}
```
## 3. 数据规范
- 耳标号格式：省简称+6位数字(如NM000001)
- 疫苗记录保留至少5年
- 敏感数据需RSA加密传输
- 日期格式：YYYY-MM-DD
- 时间格式：YYYY-MM-DDTHH:mm:ssZ
## 4. 权限控制
- 添加牛只：养殖管理员
- 批量导入：系统管理员
- 防疫记录：兽医
## 4. 版本历史
### v1.1.0 (2024-01-20)
- 新增: 按照API文档规范标准统一格式
- 优化: 统一响应格式和错误处理
- 功能: 完善养殖管理接口定义
## 3. 版本历史
### v1.0.0 (2024-01-20)
- 新增: 按照API文档规范标准统一格式
- 优化: 统一响应格式和错误处理
- 功能: 完成基础接口定义

81
docs/design/api/finance.md
View File

@@ -9,6 +9,21 @@
- 贷款审批
### 1.2 基础路径
`/api/v1/[系统名称]`
### 1.3 权限控制
- 公开接口（无需认证）：数据查询
- 管理接口（需要认证）：数据管理
- 系统接口（高级权限）：配置管理
### 1.4 全局错误码
| 状态码 | 说明 |
|--------|--------------------|
| 400 | 请求参数无效 |
| 401 | 未授权 |
| 403 | 权限不足 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |
`/api/v1/finance`
## 2. 接口明细
@@ -18,6 +33,7 @@
POST /loans
```
**请求参数**:
| 字段 | 类型 | 必填 | 说明 |
|-----------------|---------|------|--------------------|
| farmer_id | number | 是 | 牧户ID |
@@ -26,16 +42,55 @@ POST /loans
| term | number | 是 | 贷款期限(月) |
| interest_rate | number | 是 | 年利率(%) |
**响应示例**:
```json
{
"status": "success",
"data": {
"loan_id": "loan_001",
"farmer_id": 1001,
"amount": 50000,
"collateral_type": "牛只",
"term": 12,
"interest_rate": 4.35,
"monthly_payment": 4260.25,
"application_date": "2024-01-20T10:00:00Z",
"status": "审批中"
}
}
```
### 2.2 贷款审批状态查询
```
GET /loans/:id/status
```
**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|-------------|--------|------|--------------------|
| id | string | 是 | 贷款ID |
**响应示例**:
```json
{
"status": "success",
"data": {
"loan_id": "loan_001",
"status": "已批准",
"approval_date": "2024-01-21T10:00:00Z",
"approved_amount": 50000,
"approver": "审批员001",
"next_payment_date": "2024-02-20T10:00:00Z"
}
}
```
### 2.3 保险购买
```
POST /insurances
```
**请求参数**:
| 字段 | 类型 | 必填 | 说明 |
|-----------------|---------|------|--------------------|
| farmer_id | number | 是 | 牧户ID |
@@ -43,6 +98,24 @@ POST /insurances
| insurance_type | string | 是 | 保险类型 |
| premium | number | 是 | 保费(元) |
**响应示例**:
```json
{
"status": "success",
"data": {
"insurance_id": "ins_001",
"farmer_id": 1001,
"cattle_id": "cattle_123",
"insurance_type": "疾病保险",
"premium": 500,
"coverage_amount": 10000,
"effective_date": "2024-01-20T10:00:00Z",
"expiry_date": "2025-01-20T10:00:00Z",
"policy_number": "POL-20240120-001"
}
}
```
## 3. 风控规则
- 单笔贷款金额 ≤ 牧户资产总额的50%
- 理赔申请需在灾害发生后30天内提交
@@ -51,4 +124,10 @@ POST /insurances
## 4. 权限控制
- 贷款申请：牧户
- 贷款审批：银行管理员
- 保险购买：牧户
- 保险购买：牧户
## 3. 版本历史
### v1.0.0 (2024-01-20)
- 新增: 按照API文档规范标准统一格式
- 优化: 统一响应格式和错误处理
- 功能: 完成基础接口定义

76
docs/design/api/government.md
View File

@@ -9,6 +9,21 @@
- 任务状态跟踪
### 1.2 基础路径
`/api/v1/[系统名称]`
### 1.3 权限控制
- 公开接口（无需认证）：数据查询
- 管理接口（需要认证）：数据管理
- 系统接口（高级权限）：配置管理
### 1.4 全局错误码
| 状态码 | 说明 |
|--------|--------------------|
| 400 | 请求参数无效 |
| 401 | 未授权 |
| 403 | 权限不足 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |
`/api/v1/gov`
## 2. 接口明细
@@ -18,6 +33,7 @@
POST /quarantines
```
**请求参数**:
| 字段 | 类型 | 必填 | 说明 |
|---------------|--------|------|--------------------|
| location | string | 是 | GPS坐标(纬度,经度)|
@@ -26,22 +42,74 @@ POST /quarantines
| task_type | string | 是 | 任务类型(常规/紧急)|
| priority | number | 否 | 优先级(1-5) |
**响应示例**:
```json
{
"status": "success",
"data": {
"task_id": "task_001",
"location": "39.9042,116.4074",
"inspector_id": 1001,
"deadline": "2024-01-25",
"task_type": "紧急",
"priority": 1,
"created_at": "2024-01-20T10:00:00Z"
}
}
```
### 2.2 防疫任务状态查询
```
GET /quarantines/:id/status
```
**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|-------------|--------|------|--------------------|
| id | string | 是 | 任务ID |
**响应示例**:
```json
{
"status": "success",
"data": {
"task_id": "task_001",
"status": "进行中",
"progress": 50,
"inspector": "张三",
"start_time": "2024-01-20T10:00:00Z",
"estimated_completion": "2024-01-22T10:00:00Z"
}
}
```
### 2.3 检疫监管
```
POST /inspections
```
**请求参数**:
| 字段 | 类型 | 必填 | 说明 |
|---------------|--------|------|--------------------|
| cattle_id | string | 是 | 牛只ID |
| inspector_id | number | 是 | 检疫员ID |
| result | string | 是 | 检疫结果(合格/不合格)|
**响应示例**:
```json
{
"status": "success",
"data": {
"inspection_id": "insp_001",
"cattle_id": "cattle_123",
"inspector_id": 1001,
"result": "合格",
"inspection_time": "2024-01-20T10:00:00Z",
"certificate_number": "CERT-20240120-001"
}
}
```
## 3. 审计要求
- 所有操作记录操作人IP和时间
- 敏感数据需RSA加密传输
@@ -49,4 +117,10 @@ POST /inspections
## 4. 权限控制
- 防疫任务下发：政府管理员
- 检疫监管：检疫员
- 补贴发放：财务人员
- 补贴发放：财务人员
## 3. 版本历史
### v1.0.0 (2024-01-20)
- 新增: 按照API文档规范标准统一格式
- 优化: 统一响应格式和错误处理
- 功能: 完成基础接口定义

23
docs/design/api/trade.md
View File

@@ -9,6 +9,21 @@
- 订单状态查询
### 1.2 基础路径
`/api/v1/[系统名称]`
### 1.3 权限控制
- 公开接口（无需认证）：数据查询
- 管理接口（需要认证）：数据管理
- 系统接口（高级权限）：配置管理
### 1.4 全局错误码
| 状态码 | 说明 |
|--------|--------------------|
| 400 | 请求参数无效 |
| 401 | 未授权 |
| 403 | 权限不足 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |
`/api/v1/trades`
## 2. 接口明细
@@ -59,4 +74,10 @@ stateDiagram
## 5. 权限控制
- 商品发布：商户
- 订单创建：用户
- 物流跟踪：用户/商户
- 物流跟踪：用户/商户
## 3. 版本历史
### v1.0.0 (2024-01-20)
- 新增: 按照API文档规范标准统一格式
- 优化: 统一响应格式和错误处理
- 功能: 完成基础接口定义

61
docs/design/api/user-center.md
View File

@@ -1,4 +1,4 @@
# 用户中心系统 API 文档
# 用户中心系统 API 文档 (v1.0.0)
## 1. 接口概述
@@ -8,6 +8,21 @@
- 权限控制
### 1.2 基础路径
`/api/v1/[系统名称]`
### 1.3 权限控制
- 公开接口（无需认证）：数据查询
- 管理接口（需要认证）：数据管理
- 系统接口（高级权限）：配置管理
### 1.4 全局错误码
| 状态码 | 说明 |
|--------|--------------------|
| 400 | 请求参数无效 |
| 401 | 未授权 |
| 403 | 权限不足 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |
`/api/v1/users`
## 2. 接口明细
@@ -17,20 +32,62 @@
POST /register
```
**请求参数**:
| 字段 | 类型 | 必填 | 说明 |
|------------|--------|------|----------------|
| username | string | 是 | 4-20位字母数字 |
| password | string | 是 | 6-20位含大小写 |
| phone | string | 是 | 11位手机号 |
**响应示例**:
```json
{
"status": "success",
"data": {
"user_id": "user_001",
"username": "testuser",
"phone": "13800138000",
"created_at": "2024-01-20T10:00:00Z"
}
}
```
### 2.2 用户登录
```
POST /login
```
**请求参数**:
| 字段 | 类型 | 必填 | 说明 |
|------------|--------|------|----------------|
| username | string | 是 | 用户名 |
| password | string | 是 | 密码 |
**响应示例**:
```json
{
"status": "success",
"data": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
"user_info": {
"user_id": "user_001",
"username": "testuser",
"roles": ["user"]
},
"expires_in": 86400
}
}
```
## 3. 状态码规范
| 代码 | 说明 |
|------|----------------|
| 200 | 成功 |
| 400 | 参数校验失败 |
| 401 | 认证失败 |
| 401 | 认证失败 |
## 3. 版本历史
### v1.0.0 (2024-01-20)
- 新增: 按照API文档规范标准统一格式
- 优化: 统一响应格式和错误处理
- 功能: 完成基础接口定义

61
docs/design/api/website.md
View File

@@ -7,13 +7,15 @@
- 平台数据展示
- 用户留言处理
- 平台信息配置
- 管理员认证
### 1.2 基础路径
`/api/v1/website`
### 1.3 权限控制
- 公开接口（无需认证）：新闻列表、数据展示等
- 管理接口（需要认证）：新闻管理、留言处理等
- 公开接口（无需认证）：新闻列表、数据展示、留言提交
- 管理接口（需要认证）：新闻管理、留言处理、配置管理
- 认证接口：管理员登录
### 1.4 全局错误码
| 状态码 | 说明 |
@@ -31,13 +33,14 @@
GET /news
```
| 参数 | 类型 | 必填 | 说明 |
**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|-------------|--------|------|--------------------|
| page | number | 否 | 页码(默认1) |
| limit | number | 否 | 每页数量(默认10) |
| category | string | 否 | 分类筛选 |
#### 响应示例
**响应示例**:
```json
{
"status": "success",
@@ -64,11 +67,12 @@ GET /news
GET /news/{id}
```
| 参数 | 类型 | 必填 | 说明 |
**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|-------------|--------|------|--------------------|
| id | number | 是 | 新闻ID |
#### 响应示例
**响应示例**:
```json
{
"status": "success",
@@ -89,7 +93,12 @@ GET /news/{id}
GET /statistics
```
#### 响应示例
**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|-------------|--------|------|--------------------|
| 无参数 | | | |
**响应示例**:
```json
{
"status": "success",
@@ -113,19 +122,21 @@ GET /statistics
POST /messages
```
| 字段 | 类型 | 必填 | 说明 |
**请求参数**:
| 字段名 | 类型 | 必填 | 说明 |
|-------------|--------|------|--------------------|
| name | string | 是 | 姓名 |
| email | string | 是 | 邮箱 |
| phone | string | 否 | 电话 |
| content | string | 是 | 留言内容 |
#### 响应示例
**响应示例**:
```json
{
"status": "success",
"data": {
"message": "留言提交成功，我们会尽快回复您"
"message": "留言提交成功，我们会尽快回复您",
"message_id": "MSG001"
}
}
```
@@ -135,18 +146,23 @@ POST /messages
POST /auth/login
```
| 字段 | 类型 | 必填 | 说明 |
**请求参数**:
| 字段名 | 类型 | 必填 | 说明 |
|-------------|--------|------|--------------------|
| username | string | 是 | 用户名 |
| password | string | 是 | 密码 |
#### 响应示例
**响应示例**:
```json
{
"status": "success",
"data": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expires_in": 3600
"expires_in": 3600,
"user_info": {
"username": "admin",
"role": "administrator"
}
}
}
```
@@ -156,21 +172,32 @@ POST /auth/login
POST /news
```
| 字段 | 类型 | 必填 | 说明 |
**请求参数**:
| 字段名 | 类型 | 必填 | 说明 |
|-------------|--------|------|--------------------|
| title | string | 是 | 标题 |
| content | string | 是 | 内容 |
| summary | string | 否 | 摘要 |
| category | string | 是 | 分类 |
| author | string | 否 | 作者 |
| image_url | string | 否 | 图片URL |
#### 响应示例
**响应示例**:
```json
{
"status": "success",
"data": {
"id": 101,
"title": "新发布的新闻",
"created_at": "2025-08-19T10:00:00Z"
"created_at": "2025-08-19T10:00:00Z",
"publish_time": "2025-08-19T10:00:00Z"
}
}
```
```
## 3. 版本历史
### v1.1.0 (2024-01-20)
- 新增: 按照API文档规范标准统一格式
- 优化: 统一响应格式和错误处理
- 功能: 完善官网接口定义

1429
docs/design/database/DESIGN.md Normal file
View File

File diff suppressed because it is too large Load Diff

58
docs/design/database/README.md Normal file
View File

@@ -0,0 +1,58 @@
# 数据库设计
## 概述
本项目使用MySQL作为主要的关系型数据库，存储用户信息、牛只档案、交易记录、监管数据等核心业务数据。
## 数据库设计规范
1. 使用InnoDB存储引擎
2. 字符集使用utf8mb4
3. 所有表都有创建时间和更新时间字段
4. 主键使用自增ID
5. 外键约束用于保证数据一致性
## 备份与恢复策略
- **每日全量备份**: 通过`mysqldump`导出数据
- **Binlog增量备份**: 实时同步到备份服务器
- **恢复测试**: 每月验证备份文件可用性
## 数据迁移工具
- 使用Flyway管理数据库版本变更
- 迁移脚本存放在`/migrations`目录
## 核心数据表
### 1. 用户表 (users)
存储系统用户信息，包括牧民、银行职员、保险员、政府监管人员等。
### 2. 角色表 (roles)
存储系统角色信息，如管理员、牧民、银行职员等。
### 3. 权限表 (permissions)
存储系统权限信息。
### 4. 牛只档案表 (cattle)
存储牛只基本信息，包括品种、年龄、健康状况等。
### 5. 饲养记录表 (feeding_records)
存储牛只饲养记录，包括饲料、疫苗、治疗等信息。
### 6. 繁殖记录表 (breeding_records)
存储牛只繁殖相关信息。
### 7. 交易记录表 (transactions)
存储活牛交易记录。
### 8. 合同表 (contracts)
存储交易合同信息。
### 9. 商品表 (products)
存储牛肉商城商品信息。
### 10. 订单表 (orders)
存储用户订单信息。
## 数据库脚本
数据库初始化脚本和迁移脚本将存放在此目录中。

74
docs/requirements/RAISING_MANAGEMENT_REQUIREMENTS.md Normal file
View File

@@ -0,0 +1,74 @@
# 养殖管理系统详细需求文档
## 1. 系统概述
养殖管理系统是锡林郭勒盟地区养殖产业平台的重要组成部分，主要用于管理牛只档案、饲喂记录、环境监测和繁殖管理等核心养殖业务。通过该系统，养殖户和监管人员可以全面掌握牛只的生长状况和养殖环境情况。
## 2. 功能需求
### 2.1 牛只档案管理
- **耳标二维码生成与打印**：为每只牛生成唯一标识二维码，支持打印功能
- **疫苗接种计划自动提醒**：根据预设计划自动提醒接种时间
- **牛只生命周期记录管理**：记录牛只的出生、转栏、淘汰、死亡等全生命周期事件
- **牛只照片和视频资料管理**：支持上传和管理牛只的照片和视频资料
### 2.2 饲喂管理
- **饲料库存多维度分析**：按仓库、品种等维度分析饲料库存情况
- **投喂量异常波动预警**：当投喂量出现异常波动时自动发出预警
- **饲料消耗统计和成本分析**：统计饲料消耗情况并进行成本分析
- **饲喂计划制定和执行跟踪**：制定饲喂计划并跟踪执行情况
### 2.3 环境监测
- **物联网设备状态监控**：实时监控各类环境监测设备的运行状态
- **历史环境数据趋势分析**：分析历史环境数据的变化趋势
- **环境异常自动告警**：当环境数据异常时通过短信/邮件自动告警
- **环境数据报表生成**：自动生成环境数据统计报表
### 2.4 繁殖管理
- **繁殖计划制定和跟踪**：制定繁殖计划并跟踪执行情况
- **配种记录管理**：记录配种相关信息
- **妊娠检查记录**：记录妊娠检查结果
- **分娩记录管理**：记录分娩相关信息
- **犊牛档案自动生成**：分娩后自动生成犊牛档案
### 2.5 健康监测
- **疾病记录管理**：记录牛只疾病相关信息
- **免疫记录管理**：记录牛只免疫相关信息
- **药物使用记录**：记录药物使用情况
- **健康状况统计分析**：对牛只健康状况进行统计分析
## 3. 用户角色与权限
### 3.1 养殖户
- 可以查看和管理自己名下的牛只档案
- 可以录入饲喂记录和环境数据
- 可以查看繁殖计划和记录
- 可以录入健康相关信息
### 3.2 养殖场管理员
- 拥有养殖户的所有权限
- 可以查看和管理整个养殖场的牛只信息
- 可以配置饲喂计划和繁殖计划
- 可以查看和分析统计数据
### 3.3 政府监管员
- 可以查看辖区内所有养殖场的养殖数据
- 可以查看和审核养殖场提交的各类记录
- 可以查看统计数据和分析报告
## 4. 非功能需求
### 4.1 性能需求
- 页面响应时间不超过2秒
- 数据查询响应时间不超过500ms
- 支持同时管理10000+头牛只的数据
### 4.2 安全需求
- 牛只信息访问权限控制
- 操作日志记录和审计
- 数据传输加密
### 4.3 可用性需求
- 界面简洁易用，符合养殖户操作习惯
- 提供详细的操作指引和帮助文档
- 支持移动端操作

115
scripts/update_api_docs.py Normal file
View File

@@ -0,0 +1,115 @@
#!/usr/bin/env python3
"""
API文档格式统一脚本
用于批量更新API文档格式，使其符合统一的规范标准
"""
import os
import re
from pathlib import Path
def update_api_documentation(file_path):
"""更新单个API文档文件的格式"""
try:
with open(file_path, 'r', encoding='utf-8') as f:
content = f.read()
# 1. 添加版本号和统一头部格式
if not re.search(r'# .*API 文档 \(v\d+\.\d+\.\d+\)', content):
content = re.sub(r'# (.+?) API 文档', r'# \1 API 文档 (v1.0.0)', content)
# 2. 统一接口概述部分
overview_pattern = r'## 1\. 接口概述\n\n### 1\.1 功能范围\n([\s\S]*?)\n### 1\.2 基础路径'
if not re.search(overview_pattern, content):
# 添加标准的接口概述结构
content = re.sub(r'## 1\. 接口概述\n\n',
'## 1. 接口概述\n\n### 1.1 功能范围\n- 功能点1\n- 功能点2\n- 功能点3\n\n### 1.2 基础路径\n',
content)
# 3. 添加权限控制和全局错误码
if '### 1.3 权限控制' not in content:
content = content.replace('### 1.2 基础路径',
'### 1.2 基础路径\n`/api/v1/[系统名称]`\n\n### 1.3 权限控制\n- 公开接口（无需认证）：数据查询\n- 管理接口（需要认证）：数据管理\n- 系统接口（高级权限）：配置管理\n\n### 1.4 全局错误码\n| 状态码 | 说明 |\n|--------|--------------------|\n| 400 | 请求参数无效 |\n| 401 | 未授权 |\n| 403 | 权限不足 |\n| 404 | 资源不存在 |\n| 500 | 服务器内部错误 |')
# 4. 统一接口定义格式
# 将旧的接口定义格式转换为新的表格格式
content = re.sub(r'### (\d+\.\d+) (.+?)\n```\n(\w+) (.+?)\n```\n\n\*\*请求参数\*\*:\n- (.+?)\n\n\*\*响应示例\*\*:',
r'### \1 \2\n```\n\3 \4\n```\n\n**请求参数**:\n| 参数名 | 类型 | 必填 | 说明 |\n|-------------|--------|------|--------------------|\n| \5 | string | 是 | 参数说明 |\n\n**响应示例**:',
content)
# 5. 添加版本历史
if '## 版本历史' not in content and '## 3. 版本历史' not in content:
content += '\n## 3. 版本历史\n\n### v1.0.0 (2024-01-20)\n- 新增: 按照API文档规范标准统一格式\n- 优化: 统一响应格式和错误处理\n- 功能: 完成基础接口定义'
# 写入更新后的内容
with open(file_path, 'w', encoding='utf-8') as f:
f.write(content)
print(f"✓ 已更新: {file_path}")
return True
except Exception as e:
print(f"✗ 更新失败 {file_path}: {e}")
return False
def main():
"""主函数"""
api_docs_dir = Path("/Users/ainongkeji/code/vue/xlxumu/docs/design/api")
if not api_docs_dir.exists():
print(f"API文档目录不存在: {api_docs_dir}")
return
print("开始统一API文档格式...")
print("=" * 50)
# 获取所有API文档文件
api_files = []
for ext in ['*.md', '*.markdown']:
api_files.extend(api_docs_dir.glob(ext))
updated_count = 0
total_count = len(api_files)
for file_path in api_files:
if update_api_documentation(file_path):
updated_count += 1
print("=" * 50)
print(f"完成! 已更新 {updated_count}/{total_count} 个API文档")
# 生成检查报告
generate_check_report(api_docs_dir)
def generate_check_report(api_docs_dir):
"""生成格式检查报告"""
print("\n格式检查报告:")
print("-" * 30)
check_items = [
("版本号标识", r'# .*API 文档 \(v\d+\.\d+\.\d+\)'),
("权限控制", r'### 1\.3 权限控制'),
("全局错误码", r'### 1\.4 全局错误码'),
("统一响应格式", r'"status": "success"'),
("版本历史", r'## .*版本历史')
]
api_files = []
for ext in ['*.md', '*.markdown']:
api_files.extend(api_docs_dir.glob(ext))
for file_path in api_files:
with open(file_path, 'r', encoding='utf-8') as f:
content = f.read()
print(f"\n检查文件: {file_path.name}")
for check_name, pattern in check_items:
if re.search(pattern, content):
print(f" ✓ {check_name}")
else:
print(f" ✗ {check_name} (缺失)")
if __name__ == "__main__":
main()