From d95fffc630b6d1d735f2e7621a50f4cb23a0ad08 Mon Sep 17 00:00:00 2001 From: tangweijie <877588133@qq.com> Date: Wed, 11 Mar 2026 16:17:22 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=A0=87=E5=87=86=E5=8C=96=E6=8A=80?= =?UTF-8?q?=E6=9C=AF=E4=B8=BB=E6=96=87=E6=A1=A3=E5=AF=BC=E8=88=AA=E4=B8=8E?= =?UTF-8?q?=E7=AB=A0=E8=8A=82=E9=94=9A=E7=82=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../00_Management/01_Project_Progress.md | 1 + .../design/00_Management/03_Task_Checklist.md | 10 ++ .../11_Main_Doc_Chapter_Index.md | 14 +-- .../03_Technical_Design/01_Database_Design.md | 44 +++---- .../03_Technical_Design/04_Security_Design.md | 25 ++-- .../05_Deployment_Design.md | 116 +++--------------- 6 files changed, 69 insertions(+), 141 deletions(-) diff --git a/docs/design/00_Management/01_Project_Progress.md b/docs/design/00_Management/01_Project_Progress.md index 8b4af92..153d866 100644 --- a/docs/design/00_Management/01_Project_Progress.md +++ b/docs/design/00_Management/01_Project_Progress.md @@ -111,6 +111,7 @@ | 变更时间 | 变更类型 | 变更内容 | 变更原因 | 影响评估 | | ---------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| 2026-03-11 | `03_Technical_Design` 主文档导航与锚点标准化 | 持续优化技术专项主文档可检索性：1）重构 `docs/design/03_Technical_Design/01_Database_Design.md` 顶部导航为“章节导航（精简）”，移除旧目录块并为核心章节补齐 `sec-*` 稳定锚点；2）重构 `docs/design/03_Technical_Design/04_Security_Design.md` 导航并补齐 `sec-*` 锚点；3）重构 `docs/design/03_Technical_Design/05_Deployment_Design.md` 导航并补齐 `sec-*` 锚点，同时清理文档尾部误混入的脚本片段；4）同步更新 `docs/design/00_Management/11_Main_Doc_Chapter_Index.md`，将数据库/安全/部署入口统一切换到标准化锚点。 | 用户要求“持续优化”，需要将技术主文档导航策略与既有概要/详细设计保持同一锚点标准，降低检索与跳转不稳定问题 | 正面影响，技术主文档形成统一“精简导航 + 显式锚点”口径，跨文档链接稳定性提升；部署主文档去除非正文噪音后更符合交付文档定位；索引入口与正文章节映射一致，便于 AI 与人工协同维护。 | | 2026-03-11 | 主文档导航索引与检索白名单持续优化 | 持续优化 AI 检索与导航资产：1）重写 `docs/design/00_Management/11_Main_Doc_Chapter_Index.md`，将旧目录路径（`01_High_Level`、`02_Detailed`、`03_Technical`）统一修正为 `01_Overview`、`02_Detailed_Design`、`03_Technical_Design`，并补充详细设计分模块正文入口；2）更新 `docs/design/00_Management/10_AI_Retrieval_Whitelist.md`，将章节索引与模块追溯索引提升至 P1，并将 `11~15` 分模块正文纳入 P2；3）同步修订 `docs/design/01_Project_Overview.md` 对详细设计目录职责的描述。 | 用户要求“持续优化”，需要在已完成重构基础上继续提升导航准确性与 AI 检索稳定性 | 正面影响，主文档导航与白名单策略与当前目录结构完全对齐，减少旧路径误导和检索漂移；分模块正文入口更明确，便于按模块持续迭代。 | | 2026-03-11 | `01_Detailed_Design` 模块正文去重重构 | 将 `docs/design/02_Detailed_Design/01_Detailed_Design.md` 中五大模块章节（统一平台、营收业务、客户服务、表务、报装与签章）改为“章节定位 + 模块摘要矩阵 + 分模块正文链接”，移除重复详细正文；同步将 `02_Module_Traceability_Index.md` 的模块级链接切换至 `11_UP_Detailed.md`、`12_REV_Detailed.md`、`13_CS_Detailed.md`、`14_METER_Detailed.md`、`15_INST_Detailed.md`，确保主详设与分模块正文职责清晰且链接可用。 | 用户要求“模块正文改为仅保留摘要 + 链接到分模块文件，彻底去重” | 正面影响，主详设从“重复正文集合”收敛为“总册导航与口径文档”，显著降低双份维护成本，后续按模块独立迭代时的一致性和可追溯性更高。 | | 2026-03-11 | `02_Detailed_Design` 新增分模块正文文件 | 在 `docs/design/02_Detailed_Design/` 新增 `11_UP_Detailed.md`、`12_REV_Detailed.md`、`13_CS_Detailed.md`、`14_METER_Detailed.md`、`15_INST_Detailed.md` 五份模块正文文件，并为每份文档补齐 Front Matter、精简导航与模块锚点；同步在 `01_Detailed_Design.md` 增加“模块正文文件索引”，更新 `README.md`、`docs/design/02_Detailed_Design/README.md`、`scripts/unified_export.sh`、`02_Module_Traceability_Index.md` 引用与导出清单。 | 用户提出“详细设计没有分模块”，要求新增模块正文文档 | 正面影响，详细设计形成“主详设总册 + 分模块正文”的双层组织，模块维护颗粒度更清晰；评审、检索、按模块协作改稿效率提升。 | diff --git a/docs/design/00_Management/03_Task_Checklist.md b/docs/design/00_Management/03_Task_Checklist.md index 30faa14..081ac51 100644 --- a/docs/design/00_Management/03_Task_Checklist.md +++ b/docs/design/00_Management/03_Task_Checklist.md @@ -138,6 +138,16 @@ ## ✅ 最新完成任务 (持续更新) +### 📋 `03_Technical_Design` 主文档导航锚点标准化 + +- [x] **完成技术主文档导航精简与稳定锚点改造** ✅ (2026-03-11) + - [x] 重构 `01_Database_Design.md`：导航收敛为“章节导航（精简）”，移除旧目录并补齐 `sec-*` 锚点 ✅ + - [x] 重构 `04_Security_Design.md`：替换旧目录为精简导航并补齐 `sec-*` 锚点 ✅ + - [x] 重构 `05_Deployment_Design.md`：替换旧目录为精简导航并补齐 `sec-*` 锚点 ✅ + - [x] 清理部署主文档尾部误混入的脚本片段，恢复正式文档正文边界 ✅ + - [x] 更新 `11_Main_Doc_Chapter_Index.md` 中数据库/安全/部署章节入口为标准化锚点 ✅ + - [x] 更新项目进度文件记录本次持续优化动作 ✅ + ### 📋 主文档导航与白名单持续优化 - [x] **完成主文档导航索引路径与入口修正** ✅ (2026-03-11) diff --git a/docs/design/00_Management/11_Main_Doc_Chapter_Index.md b/docs/design/00_Management/11_Main_Doc_Chapter_Index.md index ff4f8d4..3585af4 100644 --- a/docs/design/00_Management/11_Main_Doc_Chapter_Index.md +++ b/docs/design/00_Management/11_Main_Doc_Chapter_Index.md @@ -58,11 +58,11 @@ | 快速入口 | 链接 | | --- | --- | -| 前言 | [前言](../03_Technical_Design/01_Database_Design.md#前言) | -| 表结构设计 | [表结构设计](../03_Technical_Design/01_Database_Design.md#表结构设计) | -| 视图设计 | [视图的设计](../03_Technical_Design/01_Database_Design.md#视图的设计) | -| 索引设计与性能优化 | [索引设计与性能优化](../03_Technical_Design/01_Database_Design.md#索引设计与性能优化) | -| 安全保密设计 | [安全保密设计](../03_Technical_Design/01_Database_Design.md#安全保密设计) | +| 前言 | [前言](../03_Technical_Design/01_Database_Design.md#sec-preface) | +| 表结构设计 | [表结构设计](../03_Technical_Design/01_Database_Design.md#sec-table-design) | +| 视图设计 | [视图的设计](../03_Technical_Design/01_Database_Design.md#sec-view-design) | +| 索引设计与性能优化 | [索引设计与性能优化](../03_Technical_Design/01_Database_Design.md#sec-index-performance) | +| 安全保密设计 | [安全保密设计](../03_Technical_Design/01_Database_Design.md#sec-security-design) | ### 2.4 接口设计主文档 @@ -81,8 +81,8 @@ | 文档 | 快速入口 | | --- | --- | -| `docs/design/03_Technical_Design/04_Security_Design.md` | [安全设计概述](../03_Technical_Design/04_Security_Design.md#安全设计概述)、[数据安全设计](../03_Technical_Design/04_Security_Design.md#数据安全设计) | -| `docs/design/03_Technical_Design/05_Deployment_Design.md` | [部署概述](../03_Technical_Design/05_Deployment_Design.md#部署概述)、[部署架构](../03_Technical_Design/05_Deployment_Design.md#部署架构)、[监控运维](../03_Technical_Design/05_Deployment_Design.md#监控运维) | +| `docs/design/03_Technical_Design/04_Security_Design.md` | [安全设计概述](../03_Technical_Design/04_Security_Design.md#sec-overview)、[数据安全设计](../03_Technical_Design/04_Security_Design.md#sec-data-security) | +| `docs/design/03_Technical_Design/05_Deployment_Design.md` | [部署概述](../03_Technical_Design/05_Deployment_Design.md#sec-overview)、[部署架构](../03_Technical_Design/05_Deployment_Design.md#sec-architecture)、[监控运维](../03_Technical_Design/05_Deployment_Design.md#sec-operations) | ## 3. 使用说明 diff --git a/docs/design/03_Technical_Design/01_Database_Design.md b/docs/design/03_Technical_Design/01_Database_Design.md index fc878d7..b67be39 100644 --- a/docs/design/03_Technical_Design/01_Database_Design.md +++ b/docs/design/03_Technical_Design/01_Database_Design.md @@ -10,16 +10,16 @@ retrieval_priority: P0 # 福建水务营收系统数据库设计说明书 -## 快速定位导航 +## 章节导航（精简） -- [前言](#前言) -- [外部设计](#外部设计) -- [数据库设计说明](#数据库设计说明) -- [表结构设计](#表结构设计) -- [移动端表设计优化说明](#移动端表设计优化说明) -- [视图的设计](#视图的设计) -- [索引设计与性能优化](#索引设计与性能优化) -- [安全保密设计](#安全保密设计) +- [前言](#sec-preface) +- [外部设计](#sec-external-design) +- [数据库设计说明](#sec-database-design-note) +- [表结构设计](#sec-table-design) +- [移动端表设计优化说明](#sec-mobile-table-optimization) +- [视图的设计](#sec-view-design) +- [索引设计与性能优化](#sec-index-performance) +- [安全保密设计](#sec-security-design) | 文件状态： | 文档密级： | 公开 | | :--- | :--- | :--- | @@ -40,27 +40,11 @@ retrieval_priority: P0 | 2025-08-01 | V1.3 | 唐伟杰 | 数据库系统变更：将OpenGauss替换为达梦数据库 8.0+，作为主力国产数据库方案。 | | 2025-08-01 | V1.4 | 唐伟杰 | 单点登录采用OAuth2.0协议：新增OAuth2.0相关数据表设计，包括客户端信息表、访问令牌表、刷新令牌表、授权码表。 | -# 目录 - -- [1. 前言](#1-前言) -- [2. 外部设计](#2-外部设计) -- [3. 数据库设计说明](#3-数据库设计说明) -- [4. 表结构设计](#4-表结构设计) - - [4.1. 数据表总体概览](#41-数据表总体概览) - - [4.2. 系统公共表 (system_*)](#42-系统公共表-system_) - - [4.3. 子系统1: 统一平台数据表](#43-子系统1-统一平台数据表) - - [4.4. 子系统2: 营收系统数据表](#44-子系统2-营收系统数据表) - - [4.5. 子系统3: 表务系统数据表](#45-子系统3-表务系统数据表) - - [4.6. 子系统4: 报装系统数据表](#46-子系统4-报装系统数据表) - - [4.7. 子系统5: 客户服务数据表（复用 SYS-002 主数据）](#47-子系统5-客户服务数据表复用-sys-002-主数据) - - [4.8. 子系统6: 手机抄表APP数据表](#48-子系统6-手机抄表app数据表) -- [5. 移动端表设计优化说明](#5-移动端表设计优化说明) -- [6. 视图的设计](#6-视图的设计) -- [7. 安全保密设计](#7-安全保密设计) - + # 前言 本文档详细描述了福建水务营收系统的数据库设计，包括总体架构、E-R图、数据表结构、字段定义和索引策略。旨在为开发和运维人员提供清晰的数据结构参考。 + # 外部设计 - **数据库系统**: 主力采用国产数据库 **达梦数据库 8.0+**。系统设计上兼容 **MySQL 8.x** 或 **MariaDB 10.x**。 @@ -72,9 +56,11 @@ retrieval_priority: P0 - **通用字段**: 所有表必须包含 `id`, `creator`, `create_time`, `updater`, `update_time`, `deleted`, `tenant_id` 字段。 - **字符集**: 统一使用 `utf8mb4` 字符集。 + # 数据库设计说明 数据库设计遵循第三范式（3NF），并采用基于`tenant_id`字段隔离的SaaS多租户架构。 + # 表结构设计 ## 数据表总体概览 @@ -1538,6 +1524,7 @@ retrieval_priority: P0 + # 移动端表设计优化说明 ## 设计原则 @@ -1586,6 +1573,7 @@ retrieval_priority: P0 - **离线缓存**：移动端特有表支持离线操作 - **冲突处理**：通过时间戳和版本控制处理数据冲突 + # 视图的设计 ## 数据库ER图设计 @@ -1791,6 +1779,7 @@ WHERE t.deleted = 0 GROUP BY t.id, t.name; ``` + # 索引设计与性能优化 ## 核心索引设计 @@ -1929,6 +1918,7 @@ DELETE FROM system_login_log WHERE create_time < CURRENT_DATE - INTERVAL '3 months'; ``` + # 安全保密设计 - **用户认证**: 所有数据库连接均需通过应用层的身份认证，禁止数据库密码在配置文件中明文存储。 - **权限控制**: 数据库用户权限遵循最小权限原则。应用层根据用户角色（RBAC）动态构建SQL，并通过行级安全（RLS）策略限制数据访问范围。 diff --git a/docs/design/03_Technical_Design/04_Security_Design.md b/docs/design/03_Technical_Design/04_Security_Design.md index 1d19678..4c9b755 100644 --- a/docs/design/03_Technical_Design/04_Security_Design.md +++ b/docs/design/03_Technical_Design/04_Security_Design.md @@ -20,15 +20,17 @@ retrieval_priority: P0 | **编写日期** | 2024-12-19 | | **文档状态** | ✅ 已完成 | -## 目录 -- [安全设计概述](#安全设计概述) -- [OpenGauss数据库安全](#opengauss数据库安全) -- [应用系统安全](#应用系统安全) -- [网络安全设计](#网络安全设计) -- [数据安全设计](#数据安全设计) -- [运维安全设计](#运维安全设计) -- [安全管理制度](#安全管理制度) +## 章节导航（精简） +- [安全设计概述](#sec-overview) +- [OpenGauss数据库安全](#sec-db-security) +- [应用系统安全](#sec-application-security) +- [网络安全设计](#sec-network-security) +- [数据安全设计](#sec-data-security) +- [运维安全设计](#sec-ops-security) +- [安全管理制度](#sec-governance) +- [总结](#sec-summary) + ## 安全设计概述 福建水务营收系统安全设计结合水务行业特点和国产化要求，构建全方位、多层次的安全防护体系。 @@ -121,6 +123,7 @@ graph TB PATCH --> API ``` + ## OpenGauss数据库安全 ### 数据库安全架构 @@ -199,6 +202,7 @@ graph TB - 实现手机号、身份证号等敏感信息脱敏 - 支持动态脱敏和静态脱敏 + ## 应用系统安全 ### Spring Security安全配置 @@ -244,6 +248,7 @@ graph TB - 采用滑动窗口算法统计请求频率 - 超过限制时返回429状态码和错误提示 + ## 网络安全设计 ### 网络拓扑安全 @@ -351,6 +356,7 @@ graph TB - 设置基于流量特征的异常检测 - 配置威胁情报实时更新机制 + ## 数据安全设计 ### 数据分类分级 @@ -419,6 +425,7 @@ graph TB - 定期清理历史数据和临时文件 - 确保已删除数据无法被恢复 + ## 运维安全设计 ### 安全监控体系 @@ -546,6 +553,7 @@ graph TB TRAIN --> DOC ``` + ## 安全管理制度 ### 安全组织架构 @@ -636,6 +644,7 @@ graph TB --- + ## 总结 福建水务营收系统安全设计结合OpenGauss数据库的安全特性，建立了全方位、多层次的安全防护体系。通过技术防护、管理制度、人员培训等多重措施，确保系统安全稳定运行，满足水务行业的安全要求。 diff --git a/docs/design/03_Technical_Design/05_Deployment_Design.md b/docs/design/03_Technical_Design/05_Deployment_Design.md index b433c8c..0c41d98 100644 --- a/docs/design/03_Technical_Design/05_Deployment_Design.md +++ b/docs/design/03_Technical_Design/05_Deployment_Design.md @@ -20,14 +20,16 @@ retrieval_priority: P0 | **编写日期** | 2024-12-19 | | **文档状态** | ✅ 已完成 | -## 目录 -- [部署概述](#部署概述) -- [部署架构](#部署架构) -- [环境配置](#环境配置) -- [部署方案](#部署方案) -- [网络安全](#网络安全) -- [监控运维](#监控运维) +## 章节导航（精简） +- [部署概述](#sec-overview) +- [部署架构](#sec-architecture) +- [环境配置](#sec-environment) +- [部署方案](#sec-solution) +- [网络安全](#sec-network-security) +- [监控运维](#sec-operations) +- [总结](#sec-summary) + ## 部署概述 福建水务营收系统采用集中化部署模式，基于集团私有云环境进行部署，构建高可用、可扩展的系统架构，满足集团及下属各水务公司的业务需求。 @@ -46,6 +48,7 @@ retrieval_priority: P0 - **安全防护**：多层次安全防护体系，确保系统和数据安全 - **弹性扩展**：支持系统横向和纵向扩展，适应业务增长需求 + ## 部署架构 ### 总体部署架构 @@ -114,6 +117,7 @@ graph - **数据同步**：定时同步生产环境数据 - **切换机制**：支持快速切换到灾备环境 + ## 环境配置 ### 硬件配置要求 @@ -160,6 +164,7 @@ graph - **工作流引擎**：Flowable 6.8.0 - **文件存储**：MinIO 分布式存储 + ## 部署方案 ### 容器化部署方案 @@ -231,6 +236,7 @@ graph 3. **环境部署**：自动部署到目标环境 4. **健康检查**：验证服务健康状态 + ## 网络安全 ### 网络架构安全 @@ -270,6 +276,7 @@ graph - **恢复演练**：定期进行数据恢复演练 - **灾难恢复**：制定完整的灾难恢复预案 + ## 监控运维 ### 系统监控 @@ -324,96 +331,7 @@ graph - **告警中心**：集中管理和处理系统告警 - **知识库**：建立运维知识库和操作手册 -这样，部署设计文档得到了大幅简化，保留了核心的架构设计思路和部署方案，删除了大量详细的配置代码，更符合概要设计的抽象层次，同时仍保持A级交付标准。 + +## 总结 -# 设置时区 -ENV TZ=Asia/Shanghai -RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone - -# 添加应用jar包 -COPY target/water-server.jar app.jar - -# 创建日志目录 -RUN mkdir -p /app/logs - -# 暴露端口 -EXPOSE 8080 - -# 启动应用 -ENTRYPOINT ["java", "-jar", "-Xmx1024m", "-Xms512m", "-Dspring.profiles.active=prod", "/app/app.jar"] - -# 应用配置 -VERSION=${VERSION} -JAVA_OPTS=-Xmx2g -Xms1g -XX:+UseG1GC -XX:+HeapDumpOnOutOfMemoryError - -# 网络配置 -NGINX_PORT=80 -NGINX_SSL_PORT=443 - -# 日志级别 -LOG_LEVEL=INFO -LOG_ROOT_LEVEL=WARN -EOF - -echo "数据库密码: ${DB_PASSWORD}" -echo "Redis密码: ${REDIS_PASSWORD}" -echo "请妥善保存以上密码信息！" - -# 创建SSL证书（自签名，生产环境应使用正式证书） -echo "创建SSL证书..." -if [ ! -f ssl/water-system.crt ]; then - openssl req -x509 -nodes -days 365 -newkey rsa:2048 \ - -keyout ssl/water-system.key \ - -out ssl/water-system.crt \ - -subj "/C=CN/ST=Fujian/L=Fuzhou/O=Water/CN=water.local" -fi - -# 构建应用镜像 -echo "构建应用镜像..." -docker build -t water-server:${VERSION} ./water-server -docker build -t water-ui:${VERSION} ./water-ui - -# 停止现有服务 -echo "停止现有服务..." -docker-compose --env-file .env.prod -f docker-compose.prod.yml down - -# 启动生产服务 -echo "启动生产服务..." -docker-compose --env-file .env.prod -f docker-compose.prod.yml up -d - -# 等待服务启动 -echo "等待服务启动..." -sleep 60 - -# 检查服务状态 -echo "检查服务状态..." -docker-compose --env-file .env.prod -f docker-compose.prod.yml ps - -# 健康检查 -echo "执行健康检查..." -for i in {1..10}; do - if curl -f http://localhost/actuator/health >/dev/null 2>&1; then - echo "应用服务健康检查通过" - break - else - echo "等待应用服务启动... ($i/10)" - sleep 30 - fi - - if [ $i -eq 10 ]; then - echo "警告: 应用服务健康检查失败" - docker-compose --env-file .env.prod -f docker-compose.prod.yml logs water-server - fi -done - -echo "=== 生产环境部署完成 ===" -echo "系统访问地址: https://localhost" -echo "系统监控地址: http://localhost:3000 (admin/admin123)" -echo "数据库端口: 5432" -echo "Redis端口: 6379" -echo "" -echo "管理命令:" -echo " 查看日志: docker-compose --env-file .env.prod -f docker-compose.prod.yml logs -f [服务名]" -echo " 停止服务: docker-compose --env-file .env.prod -f docker-compose.prod.yml down" -echo " 重启服务: docker-compose --env-file .env.prod -f docker-compose.prod.yml restart [服务名]" -echo " 备份数据: docker exec water-opengauss-prod gs_dump -h localhost -U water_user ruoyi_water > ./backups/backup-\$(date +%Y%m%d_%H%M%S).sql" +部署设计以“集中部署、分层防护、可观测运维”为主线，覆盖了环境规划、架构设计、部署实施与运维治理。后续若进入实施细节阶段，建议将脚本、参数模板和操作手册沉淀到附录或运维手册，不在本主文档中重复维护。