tangweijie/fujian_water_biz_doc
1
0
Fork 0
Code Issues Pull Requests 12 Actions Packages Projects Releases 1 Wiki Activity

docs: 标准化技术主文档导航与章节锚点

Browse Source
This commit is contained in:
tangweijie 2026-03-11 16:17:22 +08:00
parent b1463e4e48
commit d95fffc630
6 changed files with 69 additions and 141 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/design/00_Management/01_Project_Progress.md
View File

@ -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` 引用与导出清单。 | 用户提出“详细设计没有分模块”，要求新增模块正文文档 | 正面影响，详细设计形成“主详设总册 + 分模块正文”的双层组织，模块维护颗粒度更清晰；评审、检索、按模块协作改稿效率提升。 |

10
docs/design/00_Management/03_Task_Checklist.md
View File

@ -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)

14
docs/design/00_Management/11_Main_Doc_Chapter_Index.md
View File

@ -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. 使用说明

44
docs/design/03_Technical_Design/01_Database_Design.md
View File

@ -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-安全保密设计)
<a id="sec-preface"></a>
# 前言
本文档详细描述了福建水务营收系统的数据库设计，包括总体架构、E-R图、数据表结构、字段定义和索引策略。旨在为开发和运维人员提供清晰的数据结构参考。
<a id="sec-external-design"></a>
# 外部设计
- **数据库系统**: 主力采用国产数据库 **达梦数据库 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` 字符集。
<a id="sec-database-design-note"></a>
# 数据库设计说明
数据库设计遵循第三范式（3NF），并采用基于`tenant_id`字段隔离的SaaS多租户架构。
<a id="sec-table-design"></a>
# 表结构设计
## 数据表总体概览
@ -1538,6 +1524,7 @@ retrieval_priority: P0
</details>
<a id="sec-mobile-table-optimization"></a>
# 移动端表设计优化说明
## 设计原则
@ -1586,6 +1573,7 @@ retrieval_priority: P0
- **离线缓存**：移动端特有表支持离线操作
- **冲突处理**：通过时间戳和版本控制处理数据冲突
<a id="sec-view-design"></a>
# 视图的设计
## 数据库ER图设计
@ -1791,6 +1779,7 @@ WHERE t.deleted = 0
GROUP BY t.id, t.name;
```
<a id="sec-index-performance"></a>
# 索引设计与性能优化
## 核心索引设计
@ -1929,6 +1918,7 @@ DELETE FROM system_login_log
WHERE create_time < CURRENT_DATE - INTERVAL '3 months';
```
<a id="sec-security-design"></a>
# 安全保密设计
- **用户认证**: 所有数据库连接均需通过应用层的身份认证，禁止数据库密码在配置文件中明文存储。
- **权限控制**: 数据库用户权限遵循最小权限原则。应用层根据用户角色（RBAC）动态构建SQL，并通过行级安全（RLS）策略限制数据访问范围。

25
docs/design/03_Technical_Design/04_Security_Design.md
View File

@ -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)
<a id="sec-overview"></a>
## 安全设计概述
福建水务营收系统安全设计结合水务行业特点和国产化要求，构建全方位、多层次的安全防护体系。
@ -121,6 +123,7 @@ graph TB
PATCH --> API
```
<a id="sec-db-security"></a>
## OpenGauss数据库安全
### 数据库安全架构
@ -199,6 +202,7 @@ graph TB
- 实现手机号、身份证号等敏感信息脱敏
- 支持动态脱敏和静态脱敏
<a id="sec-application-security"></a>
## 应用系统安全
### Spring Security安全配置
@ -244,6 +248,7 @@ graph TB
- 采用滑动窗口算法统计请求频率
- 超过限制时返回429状态码和错误提示
<a id="sec-network-security"></a>
## 网络安全设计
### 网络拓扑安全
@ -351,6 +356,7 @@ graph TB
- 设置基于流量特征的异常检测
- 配置威胁情报实时更新机制
<a id="sec-data-security"></a>
## 数据安全设计
### 数据分类分级
@ -419,6 +425,7 @@ graph TB
- 定期清理历史数据和临时文件
- 确保已删除数据无法被恢复
<a id="sec-ops-security"></a>
## 运维安全设计
### 安全监控体系
@ -546,6 +553,7 @@ graph TB
TRAIN --> DOC
```
<a id="sec-governance"></a>
## 安全管理制度
### 安全组织架构
@ -636,6 +644,7 @@ graph TB
---
<a id="sec-summary"></a>
## 总结
福建水务营收系统安全设计结合OpenGauss数据库的安全特性，建立了全方位、多层次的安全防护体系。通过技术防护、管理制度、人员培训等多重措施，确保系统安全稳定运行，满足水务行业的安全要求。

116
docs/design/03_Technical_Design/05_Deployment_Design.md
View File

@ -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)
<a id="sec-overview"></a>
## 部署概述
福建水务营收系统采用集中化部署模式，基于集团私有云环境进行部署，构建高可用、可扩展的系统架构，满足集团及下属各水务公司的业务需求。
@ -46,6 +48,7 @@ retrieval_priority: P0
- **安全防护**：多层次安全防护体系，确保系统和数据安全
- **弹性扩展**：支持系统横向和纵向扩展，适应业务增长需求
<a id="sec-architecture"></a>
## 部署架构
### 总体部署架构
@ -114,6 +117,7 @@ graph
- **数据同步**：定时同步生产环境数据
- **切换机制**：支持快速切换到灾备环境
<a id="sec-environment"></a>
## 环境配置
### 硬件配置要求
@ -160,6 +164,7 @@ graph
- **工作流引擎**：Flowable 6.8.0
- **文件存储**：MinIO 分布式存储
<a id="sec-solution"></a>
## 部署方案
### 容器化部署方案
@ -231,6 +236,7 @@ graph
3. **环境部署**：自动部署到目标环境
4. **健康检查**：验证服务健康状态
<a id="sec-network-security"></a>
## 网络安全
### 网络架构安全
@ -270,6 +276,7 @@ graph
- **恢复演练**：定期进行数据恢复演练
- **灾难恢复**：制定完整的灾难恢复预案
<a id="sec-operations"></a>
## 监控运维
### 系统监控
@ -324,96 +331,7 @@ graph
- **告警中心**：集中管理和处理系统告警
- **知识库**：建立运维知识库和操作手册
这样，部署设计文档得到了大幅简化，保留了核心的架构设计思路和部署方案，删除了大量详细的配置代码，更符合概要设计的抽象层次，同时仍保持A级交付标准。
<a id="sec-summary"></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"
部署设计以“集中部署、分层防护、可观测运维”为主线，覆盖了环境规划、架构设计、部署实施与运维治理。后续若进入实施细节阶段，建议将脚本、参数模板和操作手册沉淀到附录或运维手册，不在本主文档中重复维护。