diff --git a/docs/API_DOCUMENTATION_CHECKLIST.md b/docs/API_DOCUMENTATION_CHECKLIST.md new file mode 100644 index 0000000..02fbc13 --- /dev/null +++ b/docs/API_DOCUMENTATION_CHECKLIST.md @@ -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日 \ No newline at end of file diff --git a/docs/API_DOCUMENTATION_STANDARD.md b/docs/API_DOCUMENTATION_STANDARD.md new file mode 100644 index 0000000..0cc54be --- /dev/null +++ b/docs/API_DOCUMENTATION_STANDARD.md @@ -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. 检查清单 + +- [ ] 文档头部格式符合规范 +- [ ] 接口定义格式统一 +- [ ] 数据类型标注准确 +- [ ] 权限控制明确标注 +- [ ] 错误响应格式规范 +- [ ] 版本号管理规范 +- [ ] 安全要求明确 +- [ ] 示例代码完整 +``` \ No newline at end of file diff --git a/docs/DOCUMENTATION_MAINTENANCE_PROCESS.md b/docs/DOCUMENTATION_MAINTENANCE_PROCESS.md new file mode 100644 index 0000000..81c808e --- /dev/null +++ b/docs/DOCUMENTATION_MAINTENANCE_PROCESS.md @@ -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 适用范围 +本规范适用于锡林郭勒盟智慧养殖产业平台所有技术文档的管理和维护。 \ No newline at end of file diff --git a/docs/design/api/dashboard.md b/docs/design/api/dashboard.md index 06bbdbf..8554f5a 100644 --- a/docs/design/api/dashboard.md +++ b/docs/design/api/dashboard.md @@ -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": "配置更新成功" + } } ``` diff --git a/docs/design/api/data-platform.md b/docs/design/api/data-platform.md index 6017cf1..f960512 100644 --- a/docs/design/api/data-platform.md +++ b/docs/design/api/data-platform.md @@ -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天 \ No newline at end of file +- 审计日志保留至少180天 +## 3. 版本历史 + +### v1.0.0 (2024-01-20) +- 新增: 按照API文档规范标准统一格式 +- 优化: 统一响应格式和错误处理 +- 功能: 完成基础接口定义 \ No newline at end of file diff --git a/docs/design/api/farming.md b/docs/design/api/farming.md index cd031df..ccd3bd9 100644 --- a/docs/design/api/farming.md +++ b/docs/design/api/farming.md @@ -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. 权限控制 -- 添加牛只：养殖管理员 -- 批量导入：系统管理员 -- 防疫记录：兽医 \ No newline at end of file +## 4. 版本历史 + +### v1.1.0 (2024-01-20) +- 新增: 按照API文档规范标准统一格式 +- 优化: 统一响应格式和错误处理 +- 功能: 完善养殖管理接口定义 +## 3. 版本历史 + +### v1.0.0 (2024-01-20) +- 新增: 按照API文档规范标准统一格式 +- 优化: 统一响应格式和错误处理 +- 功能: 完成基础接口定义 \ No newline at end of file diff --git a/docs/design/api/finance.md b/docs/design/api/finance.md index 99ed277..d130307 100644 --- a/docs/design/api/finance.md +++ b/docs/design/api/finance.md @@ -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. 权限控制 - 贷款申请：牧户 - 贷款审批：银行管理员 -- 保险购买：牧户 \ No newline at end of file +- 保险购买：牧户 +## 3. 版本历史 + +### v1.0.0 (2024-01-20) +- 新增: 按照API文档规范标准统一格式 +- 优化: 统一响应格式和错误处理 +- 功能: 完成基础接口定义 \ No newline at end of file diff --git a/docs/design/api/government.md b/docs/design/api/government.md index 788bad3..26d29d7 100644 --- a/docs/design/api/government.md +++ b/docs/design/api/government.md @@ -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. 权限控制 - 防疫任务下发：政府管理员 - 检疫监管：检疫员 -- 补贴发放：财务人员 \ No newline at end of file +- 补贴发放：财务人员 +## 3. 版本历史 + +### v1.0.0 (2024-01-20) +- 新增: 按照API文档规范标准统一格式 +- 优化: 统一响应格式和错误处理 +- 功能: 完成基础接口定义 \ No newline at end of file diff --git a/docs/design/api/trade.md b/docs/design/api/trade.md index 94afee2..b2f642d 100644 --- a/docs/design/api/trade.md +++ b/docs/design/api/trade.md @@ -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. 权限控制 - 商品发布：商户 - 订单创建：用户 -- 物流跟踪：用户/商户 \ No newline at end of file +- 物流跟踪：用户/商户 +## 3. 版本历史 + +### v1.0.0 (2024-01-20) +- 新增: 按照API文档规范标准统一格式 +- 优化: 统一响应格式和错误处理 +- 功能: 完成基础接口定义 \ No newline at end of file diff --git a/docs/design/api/user-center.md b/docs/design/api/user-center.md index 8682dcb..505fb1c 100644 --- a/docs/design/api/user-center.md +++ b/docs/design/api/user-center.md @@ -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 | 认证失败 | \ No newline at end of file +| 401 | 认证失败 | +## 3. 版本历史 + +### v1.0.0 (2024-01-20) +- 新增: 按照API文档规范标准统一格式 +- 优化: 统一响应格式和错误处理 +- 功能: 完成基础接口定义 \ No newline at end of file diff --git a/docs/design/api/website.md b/docs/design/api/website.md index a046f07..769e4fd 100644 --- a/docs/design/api/website.md +++ b/docs/design/api/website.md @@ -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" } } -``` \ No newline at end of file +``` + +## 3. 版本历史 + +### v1.1.0 (2024-01-20) +- 新增: 按照API文档规范标准统一格式 +- 优化: 统一响应格式和错误处理 +- 功能: 完善官网接口定义 \ No newline at end of file diff --git a/docs/design/database/DESIGN.md b/docs/design/database/DESIGN.md new file mode 100644 index 0000000..4e01dce --- /dev/null +++ b/docs/design/database/DESIGN.md @@ -0,0 +1,1429 @@ +# 数据库详细设计 + +## 概述 + +本项目使用MySQL作为主要的关系型数据库，存储用户信息、牛只档案、交易记录、监管数据等核心业务数据。 + +## 数据库设计规范 + +### 1. 基础规范 +| 条目 | 规范说明 | +|---------------------|--------------------------------------------------------------------------| +| 存储引擎 | InnoDB（支持事务和行级锁） | +| 字符集 | utf8mb4（支持完整Unicode，包括emoji） | +| 主键设计 | 自增BIGINT UNSIGNED（禁止使用业务字段） | +| 时间字段 | 必须包含`created_at`(DEFAULT CURRENT_TIMESTAMP)和`updated_at`(ON UPDATE)| +| 命名规则 | 表名复数形式（users），字段名下划线分隔（user_name） | + +### 2. API映射规范 +| API字段类型 | 数据库实现 | +|---------------------|--------------------------------------------------------------------------| +| 字符串 | VARCHAR(长度根据API校验规则定义) | +| 枚举值 | ENUM类型或TINYINT+注释说明 | +| 嵌套对象 | JSON类型或关联表 | +| 文件资源 | 存储OSS路径（VARCHAR(255)） | + +### 3. 安全规范 +| 数据类型 | 处理方式 | +|---------------------|--------------------------------------------------------------------------| +| 密码 | BCrypt哈希存储 | +| 身份证号 | AES-256加密 | +| 手机号 | 脱敏存储（保留前3后4） | +| 审计字段 | 必须包含操作人ID和IP地址 | + +### 4. 性能规范 +| 场景 | 优化策略 | 适用API端点示例 | +|---------------------|--------------------------------------------------------------------------|-------------------------| +| 高频查询 | 组合索引覆盖查询路径 | GET /api/v1/orders | +| 大文本 | 单独分表+OSS存储（如`product_descriptions`） | POST /api/v1/products | +| 状态字段 | 使用TINYINT+状态字典表（便于索引和扩展） | PUT /api/v1/orders/{id} | +| 批量操作 | 提供`batch_`前缀的专用表+异步处理机制 | POST /api/v1/batch | +| 分页查询 | 基于游标的分页（避免OFFSET性能问题） | GET /api/v1/history | + +### 5. API字段映射规范 +| API字段 | 数据库字段 | 类型 | 校验规则 | 备注 | +|--------------------|------------------|------------|-----------------------------------|-------------------------------| +| user.name | user_name | VARCHAR(50)| 必填，中文2-20字符 | 显示名 | +| user.phone | phone | VARCHAR(20)| 必填，正则校验^1[3-9]\d{9}$ | AES加密存储 | +| order.status | status | TINYINT | 1-5枚举值 | 关联status_dict表 | +| product.detail | detail_text | TEXT | 可选，≤2000字符 | 存OSS链接时此字段为空 | + +### 6. 状态机设计 +| 业务模块 | 状态流转规则 | 触发API | +|----------------|------------------------------------------------------------------------------|-----------------------| +| 订单系统 | 待支付→已支付→配送中→已完成（不可逆） | PUT /api/v1/orders | +| 审批流程 | 草稿→审批中→已通过/已驳回（可重新提交） | POST /api/v1/approvals| +| 养殖档案 | 未认证→认证中→已认证（管理员可重置） | PATCH /api/v1/farms | + +## 分库分表策略 + +### 1. 垂直分库 +| 业务模块 | 数据库实例 | 分库依据 | +|----------------|------------|-----------------------| +| 用户中心 | db_user | 所有用户相关表 | +| 交易系统 | db_trade | 订单/支付/物流相关表 | +| 政府监管 | db_gov | 防疫/补贴/检疫相关表 | + +### 2. 水平分表 +- **触发条件**：单表数据量 ≥ 500万行 +- **分表规则**： + - 用户表：按用户ID取模（16张） + - 订单表：按创建月份分表（按月归档） +- **路由策略**：ShardingSphere中间件 + +### 3. 扩容预案 +- **垂直扩容**：升级服务器配置（CPU/内存） +- **水平扩容**：增加分片数量（需停服迁移） + +## 读写分离设计 + +### 1. 节点角色 +| 节点类型 | 数量 | 作用域 | 同步方式 | +|---------|-----|---------------------|------------------| +| 主库 | 1 | 全业务写操作 | 半同步复制 | +| 从库1 | 2 | 交易业务读查询 | 异步复制 | +| 从库2 | 1 | 数据分析类查询 | 延迟复制（1小时） | + +### 2. 故障转移 +- **主库宕机**：VIP漂移+从库升主（30秒内完成） +- **从库延迟**：自动路由到低延迟节点 + +## 数据生命周期管理 + +### 1. 冷热分离 +- **热数据**：当前业务周期数据（保留6个月） +- **冷数据**：历史数据（OSS归档存储） + +### 2. 归档规则 +- **触发条件**：数据创建时间 ≥ 1年 +- **归档方式**： + - 结构化数据：Parquet格式压缩 + - 图片/文件：OSS低频访问存储 + +## 性能优化 + +### 1. 缓存策略 +- **查询缓存**：Redis集群（LRU淘汰策略） +- **更新机制**： + - 写穿透（Write-Through） + - 缓存失效（Cache Aside） + +### 2. 连接池配置 +- **最大连接数**：CPU核心数 × 2 + 有效磁盘数 +- **验证查询**：`SELECT 1`（每5分钟） + +## 灾备方案 + +### 1. 跨机房同步 +- **拓扑结构**：主-备-灾备（三机房部署） +- **同步延迟**：≤ 5分钟（专线保障） + +### 2. 恢复SLA +| 故障级别 | RTO | RPO | +|---------|-----------|-----------| +| P0 | ≤ 15分钟 | ≤ 1分钟 | +| P1 | ≤ 1小时 | ≤ 5分钟 | + +## 监控指标 + +### 1. 性能看板 +- **QPS/TPS**：Prometheus + Grafana +- **慢查询**：每10分钟采样分析 + +### 2. 容量预测 +- **增长模型**：线性回归（基于历史数据） +- **预警阈值**：存储使用率 ≥ 75% + +## 索引优化建议 +- 高频查询字段必须加索引 +- 联合索引遵循最左匹配原则 +- 定期使用`EXPLAIN`分析慢查询 + +## 核心数据表设计 + +### 1. 用户表 (users) +存储系统用户信息，包括牧民、银行职员、保险员、政府监管人员等。 + +```sql +CREATE TABLE users ( + id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY COMMENT '用户ID', + username VARCHAR(50) NOT NULL UNIQUE COMMENT '用户名（用于登录）', + email VARCHAR(100) UNIQUE COMMENT '邮箱（用于通知和找回密码）', + phone VARCHAR(20) UNIQUE COMMENT '手机号（实名认证用）', + password_hash VARCHAR(255) NOT NULL COMMENT '密码哈希值（BCrypt加密）', + real_name VARCHAR(50) COMMENT '真实姓名（需与身份证一致）', + avatar_url VARCHAR(255) COMMENT '头像URL（OSS存储路径）', + user_type ENUM('farmer', 'banker', 'insurer', 'government', 'trader', 'admin') NOT NULL COMMENT '用户类型：牧民/银行职员/保险员/政府人员/交易员/管理员', + status TINYINT DEFAULT 1 COMMENT '状态: 1-正常, 0-禁用（禁用用户无法登录）', + last_login TIMESTAMP NULL COMMENT '最后登录时间（用于活跃度分析）', + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间（不可修改）', + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间（自动维护）', + INDEX idx_user_type (user_type) COMMENT '按用户类型加速查询' +``` + +### 2. 金融业务表 + +#### 2.1 贷款申请表 (loan_applications) +```sql +CREATE TABLE loan_applications ( + id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY, + farmer_id BIGINT UNSIGNED NOT NULL COMMENT '牧户ID', + loan_amount DECIMAL(15,2) NOT NULL COMMENT '申请金额', + risk_score TINYINT COMMENT '风控评分(1-100)', + collateral_type ENUM('cattle', 'land', 'equipment') COMMENT '抵押物类型', + status ENUM('pending', 'approved', 'rejected') DEFAULT 'pending', + FOREIGN KEY (farmer_id) REFERENCES users(id), + INDEX idx_status (status) +); +``` + +#### 2.2 保险保单表 (insurance_policies) +```sql +CREATE TABLE insurance_policies ( + id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY, + cattle_id BIGINT UNSIGNED NOT NULL COMMENT '牛只ID', + disaster_type ENUM('drought', 'blizzard', 'epidemic') NOT NULL, + coverage_amount DECIMAL(15,2) NOT NULL, + start_date DATE NOT NULL, + end_date DATE NOT NULL, + INDEX idx_coverage (coverage_amount) +); +``` + +### 3. 政府监管表 + +#### 3.1 防疫任务表 (quarantine_tasks) +```sql +CREATE TABLE quarantine_tasks ( + id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY, + location POINT NOT NULL COMMENT 'GPS坐标', + inspector_id BIGINT UNSIGNED NOT NULL COMMENT '检疫员ID', + completion_status BOOLEAN DEFAULT FALSE, + SPATIAL INDEX (location), + FOREIGN KEY (inspector_id) REFERENCES users(id) +); +``` + +#### 3.2 补贴发放表 (subsidies) +```sql +CREATE TABLE subsidies ( + id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY, + farmer_id BIGINT UNSIGNED NOT NULL, + balance_score TINYINT NOT NULL COMMENT '草畜平衡评分(1-100)', + amount DECIMAL(15,2) NOT NULL, + payment_date DATE NOT NULL, + FOREIGN KEY (farmer_id) REFERENCES users(id) +); +``` + +### 4. 数据中台表 + +#### 4.1 数据血缘表 (data_lineage) +```sql +CREATE TABLE data_lineage ( + id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY, + source_table VARCHAR(100) NOT NULL, + source_field VARCHAR(100) NOT NULL, + target_table VARCHAR(100) NOT NULL, + target_field VARCHAR(100) NOT NULL, + transformation_rule TEXT COMMENT '转换规则SQL片段', + UNIQUE KEY (source_table, source_field, target_table, target_field) +); +``` + +#### 4.2 接口审计表 (api_audit_logs) +```sql +CREATE TABLE api_audit_logs ( + id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY, + user_id BIGINT UNSIGNED, + endpoint VARCHAR(255) NOT NULL, + request_params JSON, + sensitive_data BOOLEAN DEFAULT FALSE, + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + FOREIGN KEY (user_id) REFERENCES users(id) +); +``` + +### 5. AI模型表 + +#### 5.1 体况评分表 (body_condition_scores) +```sql +CREATE TABLE body_condition_scores ( + id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY, + cattle_id BIGINT UNSIGNED NOT NULL, + score TINYINT NOT NULL COMMENT '体况评分(1-5)', + muscle_score TINYINT COMMENT '肌肉发育评分', + fat_score TINYINT COMMENT '脂肪覆盖评分', + photo_url VARCHAR(255) COMMENT '评分照片URL', + FOREIGN KEY (cattle_id) REFERENCES cattle(id) +); +``` + +#### 5.2 饲料配方表 (feed_formulas) +```sql +CREATE TABLE feed_formulas ( + id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY, + version VARCHAR(50) NOT NULL COMMENT '配方版本', + stage ENUM('calf', 'growing', 'fattening') NOT NULL, + ingredients JSON NOT NULL COMMENT '原料配比', + cost_per_kg DECIMAL(10,2) NOT NULL, + is_active BOOLEAN DEFAULT TRUE COMMENT '是否当前使用版本', + UNIQUE KEY (version, stage) +); +); + +-- 常用查询示例： +-- 1. 按用户类型统计数量 +-- SELECT user_type, COUNT(*) FROM users GROUP BY user_type; +-- 2. 查询最近登录的活跃用户 +-- SELECT * FROM users WHERE last_login > DATE_SUB(NOW(), INTERVAL 7 DAY); + +### 2. 贷款申请表 (loan_applications) +存储贷款申请信息，包括申请人、贷款金额、用途等。 + +```sql +CREATE TABLE loan_applications ( + id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY COMMENT '申请ID', + user_id BIGINT UNSIGNED NOT NULL COMMENT '申请人ID（关联users表）', + amount DECIMAL(15,2) NOT NULL COMMENT '贷款金额（单位：元，精确到分）', + purpose VARCHAR(255) NOT NULL COMMENT '贷款用途（如：购买饲料、扩建牛舍）', + status ENUM('pending', 'approved', 'rejected', 'disbursed') DEFAULT 'pending' COMMENT '状态：待审批/已通过/已拒绝/已放款', + application_date TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '申请日期（自动记录）', + approval_date TIMESTAMP NULL COMMENT '审批日期（审批通过时更新）', + FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE COMMENT '级联删除用户时同步清理', + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', + INDEX idx_status (status) COMMENT '加速状态筛选', + INDEX idx_user_id (user_id) COMMENT '加速申请人查询' +); + +-- 常用查询示例： +-- 1. 按状态统计贷款申请 +-- SELECT status, COUNT(*) FROM loan_applications GROUP BY status; +-- 2. 查询某用户的贷款历史 +-- SELECT * FROM loan_applications WHERE user_id = 123 ORDER BY application_date DESC; + +### 3. 质押物监控表 (collateral_monitoring) +存储质押物（牛只）的状态监控信息。 + +```sql +CREATE TABLE collateral_monitoring ( + id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY COMMENT '监控ID', + loan_id BIGINT UNSIGNED NOT NULL COMMENT '关联贷款ID', + cattle_id BIGINT UNSIGNED NOT NULL COMMENT '质押牛只ID', + health_status VARCHAR(100) NOT NULL COMMENT '健康状况', + location VARCHAR(255) NOT NULL COMMENT '当前位置', + last_check_date TIMESTAMP NULL COMMENT '最后检查日期', + FOREIGN KEY (loan_id) REFERENCES loan_applications(id), + FOREIGN KEY (cattle_id) REFERENCES cattle(id), + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间' +); +``` + +### 4. 还款计划表 (repayment_schedules) +存储贷款的还款计划信息。 + +```sql +CREATE TABLE repayment_schedules ( + id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY COMMENT '计划ID', + loan_id BIGINT UNSIGNED NOT NULL COMMENT '关联贷款ID', + due_date TIMESTAMP NOT NULL COMMENT '还款日期', + amount DECIMAL(15,2) NOT NULL COMMENT '还款金额', + status ENUM('pending', 'paid', 'overdue') DEFAULT 'pending' COMMENT '状态', + payment_date TIMESTAMP NULL COMMENT '实际还款日期', + FOREIGN KEY (loan_id) REFERENCES loan_applications(id), + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间' +); +``` + +### 5. 保险申请表 (insurance_applications) +存储保险申请信息。 + +```sql +CREATE TABLE insurance_applications ( + id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY COMMENT '申请ID', + user_id BIGINT UNSIGNED NOT NULL COMMENT '申请人ID', + cattle_id BIGINT UNSIGNED NOT NULL COMMENT '投保牛只ID', + coverage_amount DECIMAL(15,2) NOT NULL COMMENT '保额', + premium DECIMAL(15,2) NOT NULL COMMENT '保费', + start_date TIMESTAMP NOT NULL COMMENT '保险开始日期', + end_date TIMESTAMP NOT NULL COMMENT '保险结束日期', + status ENUM('pending', 'approved', 'rejected', 'active', 'expired') DEFAULT 'pending' COMMENT '状态', + FOREIGN KEY (user_id) REFERENCES users(id), + FOREIGN KEY (cattle_id) REFERENCES cattle(id), + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间' +); +``` + +### 6. 理赔记录表 (claim_records) +存储保险理赔记录。 + +```sql +CREATE TABLE claim_records ( + id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY COMMENT '理赔ID', + insurance_id BIGINT UNSIGNED NOT NULL COMMENT '关联保险ID', + claim_amount DECIMAL(15,2) NOT NULL COMMENT '理赔金额', + claim_reason VARCHAR(255) NOT NULL COMMENT '理赔原因', + status ENUM('pending', 'approved', 'rejected', 'paid') DEFAULT 'pending' COMMENT '状态', + approval_date TIMESTAMP NULL COMMENT '审批日期', + payment_date TIMESTAMP NULL COMMENT '支付日期', + FOREIGN KEY (insurance_id) REFERENCES insurance_applications(id), + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间' +); +``` + +### 7. 风险评估表 (risk_assessments) +存储保险风险评估信息。 + +```sql +CREATE TABLE risk_assessments ( + id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY COMMENT '评估ID', + insurance_id BIGINT UNSIGNED NOT NULL COMMENT '关联保险ID', + risk_level ENUM('low', 'medium', 'high') NOT NULL COMMENT '风险等级', + assessment_date TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '评估日期', + notes TEXT COMMENT '评估备注', + FOREIGN KEY (insurance_id) REFERENCES insurance_applications(id), + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间' +); +``` + +### 8. 监管记录表 (supervision_records) +存储政府监管记录。 + +```sql +CREATE TABLE supervision_records ( + id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY COMMENT '记录ID', + user_id BIGINT UNSIGNED NOT NULL COMMENT '监管人员ID', + cattle_id BIGINT UNSIGNED NOT NULL COMMENT '监管牛只ID', + inspection_date TIMESTAMP NOT NULL COMMENT '检查日期', + findings TEXT NOT NULL COMMENT '检查结果', + actions_taken TEXT COMMENT '采取的措施', + FOREIGN KEY (user_id) REFERENCES users(id), + FOREIGN KEY (cattle_id) REFERENCES cattle(id), + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间' +); +``` + INDEX idx_username (username), + INDEX idx_email (email), + INDEX idx_phone (phone), + INDEX idx_user_type (user_type) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户表'; +``` + +### 2. 角色表 (roles) +存储系统角色信息，如管理员、牧民、银行职员等。 + +```sql +CREATE TABLE roles ( + id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY COMMENT '角色ID', + name VARCHAR(50) NOT NULL UNIQUE COMMENT '角色名称', + description TEXT COMMENT '角色描述', + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间' +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='角色表'; +``` + +### 3. 用户角色关联表 (user_roles) +存储用户和角色的多对多关系。 + +```sql +CREATE TABLE user_roles ( + id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY COMMENT '主键ID', + user_id BIGINT UNSIGNED NOT NULL COMMENT '用户ID', + role_id INT UNSIGNED NOT NULL COMMENT '角色ID', + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + + FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE, + FOREIGN KEY (role_id) REFERENCES roles(id) ON DELETE CASCADE, + UNIQUE KEY uk_user_role (user_id, role_id) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户角色关联表'; +``` + +### 4. 权限表 (permissions) +存储系统权限信息。 + +```sql +CREATE TABLE permissions ( + id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY COMMENT '权限ID', + name VARCHAR(100) NOT NULL UNIQUE COMMENT '权限名称', + description TEXT COMMENT '权限描述', + module VARCHAR(50) COMMENT '所属模块', + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间' +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='权限表'; +``` + +### 5. 角色权限关联表 (role_permissions) +存储角色和权限的多对多关系。 + +```sql +CREATE TABLE role_permissions ( + id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY COMMENT '主键ID', + role_id INT UNSIGNED NOT NULL COMMENT '角色ID', + permission_id INT UNSIGNED NOT NULL COMMENT '权限ID', + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + + FOREIGN KEY (role_id) REFERENCES roles(id) ON DELETE CASCADE, + FOREIGN KEY (permission_id) REFERENCES permissions(id) ON DELETE CASCADE, + UNIQUE KEY uk_role_permission (role_id, permission_id) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='角色权限关联表'; +``` + +### 6. 牛只档案表 (cattle) +存储牛只基本信息，包括品种、年龄、健康状况等。 + +```sql +CREATE TABLE cattle ( + id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY COMMENT '牛只ID', + ear_tag VARCHAR(50) NOT NULL UNIQUE COMMENT '耳标号', + name VARCHAR(50) COMMENT '名称', + breed VARCHAR(50) COMMENT '品种', + gender ENUM('male', 'female') COMMENT '性别', + birth_date DATE COMMENT '出生日期', + color VARCHAR(30) COMMENT '毛色', + weight DECIMAL(5,2) COMMENT '体重(kg)', + health_status ENUM('healthy', 'sick', 'quarantine', 'dead') DEFAULT 'healthy' COMMENT '健康状况', + owner_id BIGINT UNSIGNED COMMENT '所有者ID（牧民）', + farm_location VARCHAR(255) COMMENT '牧场位置', + status ENUM('active', 'sold', 'dead', 'quarantine') DEFAULT 'active' COMMENT '状态', + image_url VARCHAR(255) COMMENT '图片URL', + qr_code_url VARCHAR(255) COMMENT '二维码URL', + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', + + FOREIGN KEY (owner_id) REFERENCES users(id) ON DELETE SET NULL, + INDEX idx_ear_tag (ear_tag), + INDEX idx_owner (owner_id), + INDEX idx_breed (breed), + INDEX idx_status (status) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='牛只档案表'; +``` + +### 7. 饲养记录表 (feeding_records) +存储牛只饲养记录，包括饲料、疫苗、治疗等信息。 + +```sql +CREATE TABLE feeding_records ( + id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY COMMENT '记录ID', + cattle_id BIGINT UNSIGNED NOT NULL COMMENT '牛只ID', + record_type ENUM('feed', 'vaccine', 'treatment', 'checkup') NOT NULL COMMENT '记录类型: 饲料, 疫苗, 治疗, 检查', + feed_type VARCHAR(100) COMMENT '饲料类型', + feed_amount DECIMAL(6,2) COMMENT '饲料量(kg)', + vaccine_name VARCHAR(100) COMMENT '疫苗名称', + treatment_desc TEXT COMMENT '治疗描述', + medicine_name VARCHAR(100) COMMENT '药品名称', + dosage VARCHAR(100) COMMENT '用量', + veterinarian VARCHAR(50) COMMENT '兽医', + cost DECIMAL(10,2) COMMENT '费用', + record_date DATE NOT NULL COMMENT '记录日期', + notes TEXT COMMENT '备注', + operator_id BIGINT UNSIGNED COMMENT '操作员ID', + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', + + FOREIGN KEY (cattle_id) REFERENCES cattle(id) ON DELETE CASCADE, + FOREIGN KEY (operator_id) REFERENCES users(id) ON DELETE SET NULL, + INDEX idx_cattle_date (cattle_id, record_date), + INDEX idx_record_type (record_type) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='饲养记录表'; +``` + +### 8. 繁殖记录表 (breeding_records) +存储牛只繁殖相关信息。 + +```sql +CREATE TABLE breeding_records ( + id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY COMMENT '记录ID', + cattle_id BIGINT UNSIGNED NOT NULL COMMENT '母牛ID', + breeding_method ENUM('natural', 'artificial') NOT NULL COMMENT '配种方式', + breeding_date DATE NOT NULL COMMENT '配种日期', + breeding_male_id BIGINT UNSIGNED COMMENT '公牛ID', + semen_code VARCHAR(50) COMMENT '冻精编号', + expected_delivery_date DATE COMMENT '预产期', + actual_delivery_date DATE COMMENT '实际产犊日期', + calf_count TINYINT DEFAULT 1 COMMENT '产犊数', + calf_ids JSON COMMENT '犊牛IDs', + breeding_result ENUM('success', 'failed', 'pending') DEFAULT 'pending' COMMENT '配种结果', + notes TEXT COMMENT '备注', + operator_id BIGINT UNSIGNED COMMENT '操作员ID', + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', + + FOREIGN KEY (cattle_id) REFERENCES cattle(id) ON DELETE CASCADE, + FOREIGN KEY (breeding_male_id) REFERENCES cattle(id) ON DELETE SET NULL, + FOREIGN KEY (operator_id) REFERENCES users(id) ON DELETE SET NULL, + INDEX idx_cattle_date (cattle_id, breeding_date), + INDEX idx_result (breeding_result) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='繁殖记录表'; +``` + +### 9. 环境监测表 (environment_monitoring) +存储牧场环境监测数据。 + +```sql +CREATE TABLE environment_monitoring ( + id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY COMMENT '记录ID', + location VARCHAR(255) NOT NULL COMMENT '监测位置', + temperature DECIMAL(5,2) COMMENT '温度(℃)', + humidity DECIMAL(5,2) COMMENT '湿度(%)', + air_quality VARCHAR(50) COMMENT '空气质量', + ammonia_concentration DECIMAL(6,3) COMMENT '氨气浓度(ppm)', + carbon_dioxide DECIMAL(6,2) COMMENT '二氧化碳浓度(ppm)', + noise_level DECIMAL(5,2) COMMENT '噪音(dB)', + light_intensity DECIMAL(7,2) COMMENT '光照强度(lux)', + monitoring_date DATETIME NOT NULL COMMENT '监测时间', + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', + + INDEX idx_location_date (location, monitoring_date) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='环境监测表'; +``` + +### 10. 交易记录表 (transactions) +存储活牛交易记录。 + +```sql +CREATE TABLE transactions ( + id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY COMMENT '交易ID', + cattle_id BIGINT UNSIGNED NOT NULL COMMENT '牛只ID', + seller_id BIGINT UNSIGNED NOT NULL COMMENT '卖方ID', + buyer_id BIGINT UNSIGNED NOT NULL COMMENT '买方ID', + transaction_type ENUM('direct', 'auction', 'platform') NOT NULL COMMENT '交易类型', + price DECIMAL(12,2) NOT NULL COMMENT '交易价格', + currency VARCHAR(10) DEFAULT 'CNY' COMMENT '货币', + transaction_date DATETIME NOT NULL COMMENT '交易时间', + contract_id BIGINT UNSIGNED COMMENT '合同ID', + status ENUM('pending', 'completed', 'cancelled') DEFAULT 'pending' COMMENT '状态', + payment_status ENUM('unpaid', 'partial', 'paid') DEFAULT 'unpaid' COMMENT '付款状态', + delivery_status ENUM('pending', 'in_transit', 'delivered') DEFAULT 'pending' COMMENT '交付状态', + notes TEXT COMMENT '备注', + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', + + FOREIGN KEY (cattle_id) REFERENCES cattle(id) ON DELETE CASCADE, + FOREIGN KEY (seller_id) REFERENCES users(id) ON DELETE CASCADE, + FOREIGN KEY (buyer_id) REFERENCES users(id) ON DELETE CASCADE, + FOREIGN KEY (contract_id) REFERENCES contracts(id) ON DELETE SET NULL, + INDEX idx_cattle_date (cattle_id, transaction_date), + INDEX idx_seller (seller_id), + INDEX idx_buyer (buyer_id), + INDEX idx_status (status) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='交易记录表'; +``` + +### 11. 合同表 (contracts) +存储交易合同信息。 + +```sql +CREATE TABLE contracts ( + id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY COMMENT '合同ID', + contract_number VARCHAR(50) NOT NULL UNIQUE COMMENT '合同编号', + seller_id BIGINT UNSIGNED NOT NULL COMMENT '卖方ID', + buyer_id BIGINT UNSIGNED NOT NULL COMMENT '买方ID', + cattle_details JSON COMMENT '牛只详情', + total_price DECIMAL(15,2) NOT NULL COMMENT '总价', + currency VARCHAR(10) DEFAULT 'CNY' COMMENT '货币', + contract_date DATE NOT NULL COMMENT '合同日期', + effective_date DATE COMMENT '生效日期', + expiry_date DATE COMMENT '到期日期', + payment_terms TEXT COMMENT '付款条款', + delivery_terms TEXT COMMENT '交付条款', + contract_status ENUM('draft', 'signed', 'active', 'completed', 'cancelled') DEFAULT 'draft' COMMENT '合同状态', + contract_file_url VARCHAR(255) COMMENT '合同文件URL', + notes TEXT COMMENT '备注', + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', + + FOREIGN KEY (seller_id) REFERENCES users(id) ON DELETE CASCADE, + FOREIGN KEY (buyer_id) REFERENCES users(id) ON DELETE CASCADE, + INDEX idx_contract_number (contract_number), + INDEX idx_seller (seller_id), + INDEX idx_buyer (buyer_id), + INDEX idx_status (contract_status) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='合同表'; +``` + +### 12. 商品表 (products) +存储牛肉商城商品信息。 + +```sql +CREATE TABLE products ( + id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY COMMENT '商品ID', + name VARCHAR(100) NOT NULL COMMENT '商品名称', + description TEXT COMMENT '商品描述', + category_id INT UNSIGNED COMMENT '分类ID', + sku VARCHAR(50) UNIQUE COMMENT 'SKU', + price DECIMAL(10,2) NOT NULL COMMENT '价格', + original_price DECIMAL(10,2) COMMENT '原价', + currency VARCHAR(10) DEFAULT 'CNY' COMMENT '货币', + stock_quantity INT DEFAULT 0 COMMENT '库存数量', + min_stock INT DEFAULT 0 COMMENT '最低库存', + unit VARCHAR(20) COMMENT '单位', + weight DECIMAL(8,3) COMMENT '重量(kg)', + origin VARCHAR(100) COMMENT '产地', + production_date DATE COMMENT '生产日期', + expiration_date DATE COMMENT '保质期', + cattle_id BIGINT UNSIGNED COMMENT '关联牛只ID', + status ENUM('active', 'inactive', 'discontinued') DEFAULT 'active' COMMENT '状态', + image_urls JSON COMMENT '图片URL列表', + tags JSON COMMENT '标签', + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', + + FOREIGN KEY (cattle_id) REFERENCES cattle(id) ON DELETE SET NULL, + INDEX idx_name (name), + INDEX idx_category (category_id), + INDEX idx_sku (sku), + INDEX idx_status (status) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='商品表'; +``` + +### 13. 商品分类表 (product_categories) +存储商品分类信息。 + +```sql +CREATE TABLE product_categories ( + id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY COMMENT '分类ID', + name VARCHAR(50) NOT NULL COMMENT '分类名称', + parent_id INT UNSIGNED DEFAULT 0 COMMENT '父分类ID', + level TINYINT DEFAULT 1 COMMENT '层级', + sort_order INT DEFAULT 0 COMMENT '排序', + image_url VARCHAR(255) COMMENT '图片URL', + status TINYINT DEFAULT 1 COMMENT '状态: 1-正常, 0-禁用', + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', + + INDEX idx_parent (parent_id), + INDEX idx_level (level) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='商品分类表'; +``` + +### 14. 订单表 (orders) +存储用户订单信息。 + +```sql +CREATE TABLE orders ( + id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY COMMENT '订单ID', + order_number VARCHAR(50) NOT NULL UNIQUE COMMENT '订单编号', + user_id BIGINT UNSIGNED NOT NULL COMMENT '用户ID', + total_amount DECIMAL(12,2) NOT NULL COMMENT '订单总额', + currency VARCHAR(10) DEFAULT 'CNY' COMMENT '货币', + order_status ENUM('pending', 'confirmed', 'processing', 'shipped', 'delivered', 'cancelled', 'refunded') DEFAULT 'pending' COMMENT '订单状态', + payment_status ENUM('unpaid', 'partial', 'paid') DEFAULT 'unpaid' COMMENT '付款状态', + shipping_status ENUM('unshipped', 'shipped', 'delivered') DEFAULT 'unshipped' COMMENT '发货状态', + receiver_name VARCHAR(50) COMMENT '收货人姓名', + receiver_phone VARCHAR(20) COMMENT '收货人电话', + receiver_address TEXT COMMENT '收货地址', + shipping_method VARCHAR(50) COMMENT '配送方式', + shipping_fee DECIMAL(10,2) DEFAULT 0.00 COMMENT '运费', + notes TEXT COMMENT '备注', + payment_method VARCHAR(50) COMMENT '付款方式', + paid_at TIMESTAMP NULL COMMENT '付款时间', + shipped_at TIMESTAMP NULL COMMENT '发货时间', + delivered_at TIMESTAMP NULL COMMENT '送达时间', + cancelled_at TIMESTAMP NULL COMMENT '取消时间', + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', + + FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE, + INDEX idx_order_number (order_number), + INDEX idx_user (user_id), + INDEX idx_status (order_status) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='订单表'; +``` + +### 15. 订单项表 (order_items) +存储订单详情信息。 + +```sql +CREATE TABLE order_items ( + id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY COMMENT '订单项ID', + order_id BIGINT UNSIGNED NOT NULL COMMENT '订单ID', + product_id BIGINT UNSIGNED NOT NULL COMMENT '商品ID', + quantity INT NOT NULL COMMENT '数量', + unit_price DECIMAL(10,2) NOT NULL COMMENT '单价', + total_price DECIMAL(12,2) NOT NULL COMMENT '总价', + cattle_id BIGINT UNSIGNED COMMENT '关联牛只ID', + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', + + FOREIGN KEY (order_id) REFERENCES orders(id) ON DELETE CASCADE, + FOREIGN KEY (product_id) REFERENCES products(id) ON DELETE CASCADE, + FOREIGN KEY (cattle_id) REFERENCES cattle(id) ON DELETE SET NULL, + INDEX idx_order (order_id), + INDEX idx_product (product_id) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='订单项表'; +``` + +### 16. 物流跟踪表 (logistics_tracking) +存储物流跟踪信息。 + +```sql +CREATE TABLE logistics_tracking ( + id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY COMMENT '物流ID', + order_id BIGINT UNSIGNED NOT NULL COMMENT '订单ID', + tracking_number VARCHAR(100) UNIQUE COMMENT '物流单号', + carrier VARCHAR(50) COMMENT '承运商', + status ENUM('pending', 'in_transit', 'delivered', 'exception') DEFAULT 'pending' COMMENT '物流状态', + origin VARCHAR(255) COMMENT '起始地', + destination VARCHAR(255) COMMENT '目的地', + estimated_delivery_date DATE COMMENT '预计送达日期', + actual_delivery_date DATE COMMENT '实际送达日期', + current_location VARCHAR(255) COMMENT '当前位置', + tracking_info JSON COMMENT '物流跟踪信息', + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', + + FOREIGN KEY (order_id) REFERENCES orders(id) ON DELETE CASCADE, + INDEX idx_tracking_number (tracking_number), + INDEX idx_order (order_id), + INDEX idx_status (status) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='物流跟踪表'; +``` + +### 17. 贷款申请表 (loan_applications) +存储银行贷款申请信息。 + +```sql +CREATE TABLE loan_applications ( + id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY COMMENT '贷款申请ID', + applicant_id BIGINT UNSIGNED NOT NULL COMMENT '申请人ID', + loan_type ENUM('cattle', 'farm', 'equipment', 'operating') NOT NULL COMMENT '贷款类型', + cattle_ids JSON COMMENT '质押牛只IDs', + loan_amount DECIMAL(15,2) NOT NULL COMMENT '贷款金额', + currency VARCHAR(10) DEFAULT 'CNY' COMMENT '货币', + interest_rate DECIMAL(5,4) COMMENT '利率', + term_months INT COMMENT '期限(月)', + purpose TEXT COMMENT '用途', + repayment_method ENUM('equal_principal', 'equal_payment', 'bullet') COMMENT '还款方式', + guarantee_type ENUM('cattle_pledge', 'guarantor', 'insurance', 'credit') COMMENT '担保方式', + status ENUM('submitted', 'under_review', 'approved', 'rejected', 'disbursed', 'completed', 'overdue') DEFAULT 'submitted' COMMENT '状态', + reviewer_id BIGINT UNSIGNED COMMENT '审核人ID', + review_notes TEXT COMMENT '审核备注', + approved_amount DECIMAL(15,2) COMMENT '批准金额', + approved_date TIMESTAMP NULL COMMENT '批准日期', + disbursement_date TIMESTAMP NULL COMMENT '放款日期', + repayment_schedule JSON COMMENT '还款计划', + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', + + FOREIGN KEY (applicant_id) REFERENCES users(id) ON DELETE CASCADE, + FOREIGN KEY (reviewer_id) REFERENCES users(id) ON DELETE SET NULL, + INDEX idx_applicant (applicant_id), + INDEX idx_status (status), + INDEX idx_type (loan_type) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='贷款申请表'; +``` + +### 18. 保险申请表 (insurance_applications) +存储保险申请信息。 + +```sql +CREATE TABLE insurance_applications ( + id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY COMMENT '保险申请ID', + applicant_id BIGINT UNSIGNED NOT NULL COMMENT '申请人ID', + insurance_type ENUM('cattle_death', 'cattle_health', 'cattle_theft', 'property') NOT NULL COMMENT '保险类型', + cattle_ids JSON COMMENT '保险牛只IDs', + policy_number VARCHAR(50) UNIQUE COMMENT '保单号', + insured_amount DECIMAL(15,2) COMMENT '保险金额', + premium DECIMAL(12,2) COMMENT '保费', + currency VARCHAR(10) DEFAULT 'CNY' COMMENT '货币', + start_date DATE COMMENT '起保日期', + end_date DATE COMMENT '终保日期', + status ENUM('applied', 'underwriting', 'issued', 'active', 'expired', 'cancelled', 'claiming', 'settled') DEFAULT 'applied' COMMENT '状态', + underwriter_id BIGINT UNSIGNED COMMENT '核保人ID', + underwriting_notes TEXT COMMENT '核保备注', + policy_file_url VARCHAR(255) COMMENT '保单文件URL', + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', + + FOREIGN KEY (applicant_id) REFERENCES users(id) ON DELETE CASCADE, + FOREIGN KEY (underwriter_id) REFERENCES users(id) ON DELETE SET NULL, + INDEX idx_applicant (applicant_id), + INDEX idx_policy_number (policy_number), + INDEX idx_status (status) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='保险申请表'; +``` + +### 19. 理赔申请表 (claims) +存储保险理赔信息。 + +```sql +CREATE TABLE claims ( + id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY COMMENT '理赔申请ID', + insurance_id BIGINT UNSIGNED NOT NULL COMMENT '保险ID', + applicant_id BIGINT UNSIGNED NOT NULL COMMENT '申请人ID', + claim_amount DECIMAL(12,2) NOT NULL COMMENT '理赔金额', + currency VARCHAR(10) DEFAULT 'CNY' COMMENT '货币', + incident_date DATE NOT NULL COMMENT '事故日期', + incident_type ENUM('death', 'illness', 'accident', 'theft') NOT NULL COMMENT '事故类型', + description TEXT COMMENT '事故描述', + evidence_files JSON COMMENT '证据文件URL列表', + status ENUM('submitted', 'under_review', 'approved', 'rejected', 'paid') DEFAULT 'submitted' COMMENT '状态', + reviewer_id BIGINT UNSIGNED COMMENT '审核人ID', + review_notes TEXT COMMENT '审核备注', + approved_amount DECIMAL(12,2) COMMENT '批准金额', + paid_amount DECIMAL(12,2) COMMENT '赔付金额', + submitted_at TIMESTAMP NULL COMMENT '提交时间', + reviewed_at TIMESTAMP NULL COMMENT '审核时间', + approved_at TIMESTAMP NULL COMMENT '批准时间', + paid_at TIMESTAMP NULL COMMENT '赔付时间', + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', + + FOREIGN KEY (insurance_id) REFERENCES insurance_applications(id) ON DELETE CASCADE, + FOREIGN KEY (applicant_id) REFERENCES users(id) ON DELETE CASCADE, + FOREIGN KEY (reviewer_id) REFERENCES users(id) ON DELETE SET NULL, + INDEX idx_insurance (insurance_id), + INDEX idx_applicant (applicant_id), + INDEX idx_status (status) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='理赔申请表'; +``` + +### 20. 政府监管报告表 (government_reports) +存储政府监管报告信息。 + +```sql +CREATE TABLE government_reports ( + id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY COMMENT '报告ID', + report_type ENUM('production', 'sales', 'disease', 'environment', 'finance') NOT NULL COMMENT '报告类型', + reporter_id BIGINT UNSIGNED NOT NULL COMMENT '报告人ID', + reporting_period_start DATE NOT NULL COMMENT '报告期开始日期', + reporting_period_end DATE NOT NULL COMMENT '报告期结束日期', + data_content JSON COMMENT '报告数据内容', + summary TEXT COMMENT '摘要', + status ENUM('draft', 'submitted', 'approved', 'rejected') DEFAULT 'draft' COMMENT '状态', + approver_id BIGINT UNSIGNED COMMENT '审批人ID', + approval_notes TEXT COMMENT '审批备注', + submitted_at TIMESTAMP NULL COMMENT '提交时间', + approved_at TIMESTAMP NULL COMMENT '审批时间', + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', + + FOREIGN KEY (reporter_id) REFERENCES users(id) ON DELETE CASCADE, + FOREIGN KEY (approver_id) REFERENCES users(id) ON DELETE SET NULL, + INDEX idx_reporter (reporter_id), + INDEX idx_type (report_type), + INDEX idx_status (status) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='政府监管报告表'; +``` + +## 官网相关表设计 + +### 1. 官网首页配置表 (website_homepage) +存储官网首页的配置信息。 + +```sql +CREATE TABLE website_homepage ( + id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY COMMENT '配置ID', + section_name VARCHAR(50) NOT NULL COMMENT '板块名称', + content_type ENUM('banner', 'video', 'text', 'link') NOT NULL COMMENT '内容类型', + title VARCHAR(100) NOT NULL COMMENT '标题', + subtitle VARCHAR(200) COMMENT '副标题', + content TEXT COMMENT '内容', + media_url VARCHAR(255) COMMENT '媒体文件URL（图片或视频）', + link_url VARCHAR(255) COMMENT '链接地址', + sort_order INT DEFAULT 0 COMMENT '排序顺序', + is_active BOOLEAN DEFAULT TRUE COMMENT '是否启用', + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', + + INDEX idx_section (section_name), + INDEX idx_active (is_active), + INDEX idx_sort (sort_order) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='官网首页配置表'; +``` + +### 2. 新闻资讯表 (news_articles) +存储新闻资讯信息。 + +```sql +CREATE TABLE news_articles ( + id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY COMMENT '新闻ID', + title VARCHAR(150) NOT NULL COMMENT '标题', + subtitle VARCHAR(200) COMMENT '副标题', + content TEXT NOT NULL COMMENT '内容', + author VARCHAR(50) COMMENT '作者', + source VARCHAR(100) COMMENT '来源', + cover_image VARCHAR(255) COMMENT '封面图片URL', + is_featured BOOLEAN DEFAULT FALSE COMMENT '是否推荐', + status ENUM('draft', 'published', 'archived') DEFAULT 'draft' COMMENT '状态', + publish_date TIMESTAMP NULL COMMENT '发布时间', + category VARCHAR(50) COMMENT '分类', + views INT UNSIGNED DEFAULT 0 COMMENT '浏览量', + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', + + FOREIGN KEY (author_id) REFERENCES users(id) ON DELETE SET NULL, + INDEX idx_status (status), + INDEX idx_category (category), + INDEX idx_publish_date (publish_date) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='新闻资讯表'; +``` + +### 3. 政策公告表 (policy_announcements) +存储政策公告信息。 + +```sql +CREATE TABLE policy_announcements ( + id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY COMMENT '公告ID', + title VARCHAR(150) NOT NULL COMMENT '标题', + content TEXT NOT NULL COMMENT '内容', + issuer VARCHAR(100) NOT NULL COMMENT '发布机构', + issue_date DATE NOT NULL COMMENT '发布日期', + effective_date DATE COMMENT '生效日期', + document_number VARCHAR(50) COMMENT '文号', + attachment_url VARCHAR(255) COMMENT '附件URL', + is_important BOOLEAN DEFAULT FALSE COMMENT '是否重要公告', + status ENUM('draft', 'published', 'expired') DEFAULT 'draft' COMMENT '状态', + views INT UNSIGNED DEFAULT 0 COMMENT '浏览量', + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', + + INDEX idx_issue_date (issue_date), + INDEX idx_status (status), + INDEX idx_issuer (issuer) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='政策公告表'; +``` + +## 数据库关系图 + +``` +erDiagram + users ||--o{ user_roles : has + roles ||--o{ user_roles : includes + roles ||--o{ role_permissions : has + permissions ||--o{ role_permissions : includes + users ||--o{ cattle : owns + cattle ||--o{ feeding_records : has + cattle ||--o{ breeding_records : has + cattle ||--o{ transactions : involved_in + users ||--o{ transactions : involved_in + contracts ||--o{ transactions : related_to + cattle ||--o{ products : related_to + product_categories ||--o{ products : belongs_to + users ||--o{ orders : places + orders ||--o{ order_items : contains + products ||--o{ order_items : contains + cattle ||--o{ order_items : related_to + orders ||--o{ logistics_tracking : has + users ||--o{ loan_applications : applies + users ||--o{ loan_applications : reviews + cattle ||--o{ loan_applications : pledged + users ||--o{ insurance_applications : applies + users ||--o{ insurance_applications : underwrites + cattle ||--o{ insurance_applications : insured + insurance_applications ||--o{ claims : has + users ||--o{ claims : applies + users ||--o{ claims : reviews + users ||--o{ government_reports : submits + users ||--o{ government_reports : approves + users ||--o{ news : authors + users ||--o{ messages : processes + + users { + BIGINT id PK + VARCHAR username + VARCHAR email + VARCHAR phone + VARCHAR password_hash + VARCHAR real_name + VARCHAR avatar_url + ENUM user_type + TINYINT status + TIMESTAMP last_login + TIMESTAMP created_at + TIMESTAMP updated_at + } + + roles { + INT id PK + VARCHAR name + TEXT description + TIMESTAMP created_at + TIMESTAMP updated_at + } + + user_roles { + BIGINT id PK + BIGINT user_id FK + INT role_id FK + TIMESTAMP created_at + } + + permissions { + INT id PK + VARCHAR name + TEXT description + VARCHAR module + TIMESTAMP created_at + TIMESTAMP updated_at + } + + role_permissions { + BIGINT id PK + INT role_id FK + INT permission_id FK + TIMESTAMP created_at + } + + cattle { + BIGINT id PK + VARCHAR ear_tag + VARCHAR name + VARCHAR breed + ENUM gender + DATE birth_date + VARCHAR color + DECIMAL weight + ENUM health_status + BIGINT owner_id FK + VARCHAR farm_location + ENUM status + VARCHAR image_url + VARCHAR qr_code_url + TIMESTAMP created_at + TIMESTAMP updated_at + } + + feeding_records { + BIGINT id PK + BIGINT cattle_id FK + ENUM record_type + VARCHAR feed_type + DECIMAL feed_amount + VARCHAR vaccine_name + TEXT treatment_desc + VARCHAR medicine_name + VARCHAR dosage + VARCHAR veterinarian + DECIMAL cost + DATE record_date + TEXT notes + BIGINT operator_id FK + TIMESTAMP created_at + TIMESTAMP updated_at + } + + breeding_records { + BIGINT id PK + BIGINT cattle_id FK + ENUM breeding_method + DATE breeding_date + BIGINT breeding_male_id FK + VARCHAR semen_code + DATE expected_delivery_date + DATE actual_delivery_date + TINYINT calf_count + JSON calf_ids + ENUM breeding_result + TEXT notes + BIGINT operator_id FK + TIMESTAMP created_at + TIMESTAMP updated_at + } + + environment_monitoring { + BIGINT id PK + VARCHAR location + DECIMAL temperature + DECIMAL humidity + VARCHAR air_quality + DECIMAL ammonia_concentration + DECIMAL carbon_dioxide + DECIMAL noise_level + DECIMAL light_intensity + DATETIME monitoring_date + TIMESTAMP created_at + TIMESTAMP updated_at + } + + transactions { + BIGINT id PK + BIGINT cattle_id FK + BIGINT seller_id FK + BIGINT buyer_id FK + ENUM transaction_type + DECIMAL price + VARCHAR currency + DATETIME transaction_date + BIGINT contract_id FK + ENUM status + ENUM payment_status + ENUM delivery_status + TEXT notes + TIMESTAMP created_at + TIMESTAMP updated_at + } + + contracts { + BIGINT id PK + VARCHAR contract_number + BIGINT seller_id FK + BIGINT buyer_id FK + JSON cattle_details + DECIMAL total_price + VARCHAR currency + DATE contract_date + DATE effective_date + DATE expiry_date + TEXT payment_terms + TEXT delivery_terms + ENUM contract_status + VARCHAR contract_file_url + TEXT notes + TIMESTAMP created_at + TIMESTAMP updated_at + } + + products { + BIGINT id PK + VARCHAR name + TEXT description + INT category_id FK + VARCHAR sku + DECIMAL price + DECIMAL original_price + VARCHAR currency + INT stock_quantity + INT min_stock + VARCHAR unit + DECIMAL weight + VARCHAR origin + DATE production_date + DATE expiration_date + BIGINT cattle_id FK + ENUM status + JSON image_urls + JSON tags + TIMESTAMP created_at + TIMESTAMP updated_at + } + + product_categories { + INT id PK + VARCHAR name + INT parent_id + TINYINT level + INT sort_order + VARCHAR image_url + TINYINT status + TIMESTAMP created_at + TIMESTAMP updated_at + } + + orders { + BIGINT id PK + VARCHAR order_number + BIGINT user_id FK + DECIMAL total_amount + VARCHAR currency + ENUM order_status + ENUM payment_status + ENUM shipping_status + VARCHAR receiver_name + VARCHAR receiver_phone + TEXT receiver_address + VARCHAR shipping_method + DECIMAL shipping_fee + TEXT notes + VARCHAR payment_method + TIMESTAMP paid_at + TIMESTAMP shipped_at + TIMESTAMP delivered_at + TIMESTAMP cancelled_at + TIMESTAMP created_at + TIMESTAMP updated_at + } + + order_items { + BIGINT id PK + BIGINT order_id FK + BIGINT product_id FK + INT quantity + DECIMAL unit_price + DECIMAL total_price + BIGINT cattle_id FK + TIMESTAMP created_at + TIMESTAMP updated_at + } + + logistics_tracking { + BIGINT id PK + BIGINT order_id FK + VARCHAR tracking_number + VARCHAR carrier + ENUM status + VARCHAR origin + VARCHAR destination + DATE estimated_delivery_date + DATE actual_delivery_date + VARCHAR current_location + JSON tracking_info + TIMESTAMP created_at + TIMESTAMP updated_at + } + + loan_applications { + BIGINT id PK + BIGINT applicant_id FK + ENUM loan_type + JSON cattle_ids + DECIMAL loan_amount + VARCHAR currency + DECIMAL interest_rate + INT term_months + TEXT purpose + ENUM repayment_method + ENUM guarantee_type + ENUM status + BIGINT reviewer_id FK + TEXT review_notes + DECIMAL approved_amount + TIMESTAMP approved_date + TIMESTAMP disbursement_date + JSON repayment_schedule + TIMESTAMP created_at + TIMESTAMP updated_at + } + + insurance_applications { + BIGINT id PK + BIGINT applicant_id FK + ENUM insurance_type + JSON cattle_ids + VARCHAR policy_number + DECIMAL insured_amount + DECIMAL premium + VARCHAR currency + DATE start_date + DATE end_date + ENUM status + BIGINT underwriter_id FK + TEXT underwriting_notes + VARCHAR policy_file_url + TIMESTAMP created_at + TIMESTAMP updated_at + } + + claims { + BIGINT id PK + BIGINT insurance_id FK + BIGINT applicant_id FK + DECIMAL claim_amount + VARCHAR currency + DATE incident_date + ENUM incident_type + TEXT description + JSON evidence_files + ENUM status + BIGINT reviewer_id FK + TEXT review_notes + DECIMAL approved_amount + DECIMAL paid_amount + TIMESTAMP submitted_at + TIMESTAMP reviewed_at + TIMESTAMP approved_at + TIMESTAMP paid_at + TIMESTAMP created_at + TIMESTAMP updated_at + } + + government_reports { + BIGINT id PK + ENUM report_type + BIGINT reporter_id FK + DATE reporting_period_start + DATE reporting_period_end + JSON data_content + TEXT summary + ENUM status + BIGINT approver_id FK + TEXT approval_notes + TIMESTAMP submitted_at + TIMESTAMP approved_at + TIMESTAMP created_at + TIMESTAMP updated_at + } + + news { + BIGINT id PK + VARCHAR title + TEXT summary + LONGTEXT content + ENUM category + VARCHAR image_url + BIGINT author_id FK + INT views + ENUM status + TIMESTAMP published_at + TIMESTAMP created_at + TIMESTAMP updated_at + } + + messages { + BIGINT id PK + VARCHAR name + VARCHAR email + VARCHAR phone + TEXT content + ENUM status + BIGINT processed_by FK + TIMESTAMP processed_at + TIMESTAMP created_at + TIMESTAMP updated_at + } +``` + +### 21. 新闻资讯表 (news) +存储官网新闻资讯信息。 + +```sql +CREATE TABLE news ( + id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY COMMENT '新闻ID', + title VARCHAR(200) NOT NULL COMMENT '标题', + summary TEXT COMMENT '摘要', + content LONGTEXT NOT NULL COMMENT '内容', + category ENUM('policy', 'market', 'technology', 'general') NOT NULL COMMENT '分类: 政策解读/市场动态/技术前沿/综合', + image_url VARCHAR(255) COMMENT '封面图片URL', + author_id BIGINT UNSIGNED COMMENT '作者ID', + views INT DEFAULT 0 COMMENT '浏览量', + status ENUM('draft', 'published', 'archived') DEFAULT 'draft' COMMENT '状态: 草稿/已发布/已归档', + published_at TIMESTAMP NULL COMMENT '发布时间', + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', + + FOREIGN KEY (author_id) REFERENCES users(id) ON DELETE SET NULL, + INDEX idx_category (category), + INDEX idx_status (status), + INDEX idx_published_at (published_at) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='新闻资讯表'; +``` + +### 22. 用户留言表 (messages) +存储用户在官网提交的留言信息。 + +```sql +CREATE TABLE messages ( + id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY COMMENT '留言ID', + name VARCHAR(50) NOT NULL COMMENT '姓名', + email VARCHAR(100) NOT NULL COMMENT '邮箱', + phone VARCHAR(20) COMMENT '电话', + content TEXT NOT NULL COMMENT '留言内容', + status ENUM('pending', 'processed', 'archived') DEFAULT 'pending' COMMENT '状态: 待处理/已处理/已归档', + processed_by BIGINT UNSIGNED COMMENT '处理人ID', + processed_at TIMESTAMP NULL COMMENT '处理时间', + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', + + FOREIGN KEY (processed_by) REFERENCES users(id) ON DELETE SET NULL, + INDEX idx_status (status), + INDEX idx_created_at (created_at) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户留言表'; +``` \ No newline at end of file diff --git a/docs/design/database/README.md b/docs/design/database/README.md new file mode 100644 index 0000000..772246c --- /dev/null +++ b/docs/design/database/README.md @@ -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) +存储用户订单信息。 + +## 数据库脚本 + +数据库初始化脚本和迁移脚本将存放在此目录中。 \ No newline at end of file diff --git a/docs/requirements/RAISING_MANAGEMENT_REQUIREMENTS.md b/docs/requirements/RAISING_MANAGEMENT_REQUIREMENTS.md new file mode 100644 index 0000000..d28f2d4 --- /dev/null +++ b/docs/requirements/RAISING_MANAGEMENT_REQUIREMENTS.md @@ -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 可用性需求 +- 界面简洁易用，符合养殖户操作习惯 +- 提供详细的操作指引和帮助文档 +- 支持移动端操作 \ No newline at end of file diff --git a/scripts/update_api_docs.py b/scripts/update_api_docs.py new file mode 100644 index 0000000..d4109df --- /dev/null +++ b/scripts/update_api_docs.py @@ -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() \ No newline at end of file