fujian_water_biz_doc/00_Management/04_Writing_Guide.md

福建水务营收系统文档编写流程指南

一、流程概述

基于当前项目的实际经验，结合 /templates 模板文档、/api 接口规范、/sql 数据库结构以及现有的 water_biz_* 系列文档，建立标准化的文档编写流程。

1.1 现有文档体系分析

当前项目已形成完整的文档体系，包括以下核心文档：

设计文档体系

• water_biz_design_plan.md - 设计计划文档（190行）
• water_biz_system_architecture.md - 系统架构设计（277行）
• water_biz_module_design.md - 模块功能设计（586行）
• water_biz_database_design.md - 数据库设计（313行）
• water_biz_interface_design.md - 接口设计（253行）
• water_biz_deployment_design.md - 部署设计（337行）
• water_biz_summary.md - 总结文档（308行）
• water_biz_integrated_doc.md - 集成目录索引（324行）

模板文档结构

• 301-概要设计说明书（V1.1).md - 系统概要设计模板
• 302-详细设计说明书（V1.1).md - 详细设计模板
• 303-数据库设计说明书（简版).md - 数据库设计模板

输入资源

• /api/【IF】福建水务营收系统.openapi.json - API接口规范
• /sql/sw_biz_table.sql - 业务数据表结构
• /sql/sw_system_publcli.sql - 系统基础表结构
• /parsed_docs_new/ - 原有系统解析文档（包含需求、操作手册等）

1.2 文档质量标准（参考现有文档）

结构化标准

• 清晰的目录结构（参考 water_biz_module_design.md 的8级目录）
• 统一的标题层级和编号方式
• 完整的内部链接系统

内容深度标准

• 系统架构：技术选型 + 架构图 + 部署方案（参考 water_biz_system_architecture.md）
• 模块设计：功能概览 + 详细设计 + 实现方案（参考 water_biz_module_design.md）
• 数据库设计：概述 + 表结构 + 索引优化（参考 water_biz_database_design.md）

二、核心功能模块分析

基于API分析，系统主要包含以下功能模块：

1. 水表管理模块 (MeterManagement)

• 水表厂家管理：增删改查、状态管理、下拉选择
• 水表型号管理：型号信息、规格参数、状态控制
• 水表口径管理：口径规格、适用范围
• 水表量程管理：量程设置、精度控制

2. 部门管理模块

• 组织架构管理：部门层级、权限分配
• 站点管理：营业站点、服务范围
• 人员管理：用户角色、权限控制

3. 地址管理模块 (AddressManagement)

• 小区管理：小区信息、服务区域
• 地址标准化：地址编码、层级管理
• 区域划分：服务范围、管辖区域

4. 水价管理模块

• 水价归属：价格体系、适用范围
• 费用组成：收费项目、计算规则
• 价格调整：调价记录、历史追溯
• 优惠方案：折扣策略、适用条件

5. 账户管理模块

• 水司账户：企业账户、财务管理
• 客户账户：用户信息、账户状态

6. 系统配置模块

• 表格列配置：UI界面定制
• 系统参数：业务规则、基础配置

三、数据库表结构分析

业务表 (sw_biz_table.sql)

1. 社区管理：biz_community - 小区信息管理
2. 企业账户：biz_company_account - 水司账户信息
3. 费用管理：biz_cost_component - 费用组成配置
4. 部门关联：biz_dept_account_rel - 部门账户关联
5. 水表参数：
   • biz_meter_caliber - 水表口径
   • biz_meter_maker - 水表厂家
   • biz_meter_model - 水表型号
   • biz_meter_range - 水表量程
6. 价格体系：
   • biz_price_category - 价格分类
   • biz_price_adjustment_history - 价格调整历史
   • biz_price_cost_adjustment - 费用调整
   • biz_price_discount_* - 优惠方案相关表

系统表 (sw_system_publcli.sql)

1. 基础管理：部门、用户、角色、权限
2. 系统功能：字典、参数、日志、通知
3. 认证授权：OAuth2、JWT、登录日志
4. 租户管理：多租户支持、数据隔离

四、文档编写流程（基于现有文档经验）

第一步：准备工作和资源整理

1. 文档资源盘点

   • 复制 /templates 模板文件到新的工作目录
   • 参考现有 water_biz_* 文档的结构和内容深度
   • 分析 /api 接口规范，提取功能点
   • 分析 /sql 数据库表，梳理数据模型
   • 查阅 /parsed_docs_new 中的原系统文档

2. 确定文档体系架构

   • 参考 water_biz_integrated_doc.md 的文档组织方式
   • 建立文档间的链接关系
   • 确定系统名称和版本信息

第二步：概要设计说明书编写

参考模板：301-概要设计说明书（V1.1).md + water_biz_system_architecture.md

1. 文档头部信息（参考现有文档格式）

   # 福建水务营收系统概要设计说明书
   
   ## 目录
   - [1. 系统架构概述](#1-系统架构概述)
   - [2. 技术架构](#2-技术架构)
   - [3. 应用架构](#3-应用架构)
   

2. 系统总体设计（参考 water_biz_system_architecture.md）

   • 技术架构图：包含系统架构图和技术栈说明
   • 多租户架构：基于字段隔离的SaaS设计
   • 服务端技术栈：Spring Boot 3.x + MyBatis Plus + Redis
   • 客户端技术栈：Vue 3.x + TypeScript + Element Plus

3. 各子系统设计（参考 water_biz_module_design.md 的模块划分）

   • 统一平台（单点登录、系统管理）
   • 营收系统（抄表开账、收费管理、账务处理等）
   • 表务系统（表务工单、表务仓库、水表参数等）
   • 报装系统、客户服务、系统配置等

第三步：详细设计说明书编写

参考模板：302-详细设计说明书（V1.1).md + water_biz_module_design.md + water_biz_interface_design.md

1. 模块详细设计（参考 water_biz_module_design.md 的586行详细内容）

   • 功能模块层次结构：8级目录的详细分解
   • 业务流程设计：每个模块的业务处理流程
   • 数据流设计：模块间的数据交互关系

2. 接口设计（参考 water_biz_interface_design.md）

   • RESTful API规范：资源命名、HTTP方法、状态码
   • 外部接口：银行、支付宝/微信、短信、集抄系统等
   • 内部接口：模块间API接口定义
   • 接口安全：认证授权、参数校验机制

3. 技术实现设计

   • 缓存策略：Redis缓存设计和数据一致性
   • 工作流引擎：基于Flowable的业务流程设计
   • 定时任务：基于Quartz的任务调度设计

第四步：数据库设计说明书编写

参考模板：303-数据库设计说明书（简版).md + water_biz_database_design.md

1. 数据库概览（参考 water_biz_database_design.md 的架构设计）

   • 技术选型：MySQL/MariaDB（支持国产OpenGauss）
   • 多租户设计：基于字段隔离的租户架构
   • 缓存架构：Redis缓存系统设计
   • 数据安全：权限控制和数据加密方案

2. 表结构设计（基于 /sql 文件分析）

   • 业务表设计：基于 sw_biz_table.sql 的表结构详细说明
   • 系统表设计：基于 sw_system_publcli.sql 的基础功能表
   • 索引设计：性能优化的索引策略
   • 约束设计：数据完整性约束

3. 数据模型

   • ER图设计：实体关系图
   • 表关系说明：外键关系和业务关联
   • 数据字典：参考 04_Appendix/Archive/05_Data_Dictionary/营收数据字典.md

五、自动化工具和脚本

1. API解析脚本

# 从OpenAPI JSON中提取接口信息
jq '.paths | keys[]' api/【IF】福建水务营收系统.openapi.json

2. 数据库表解析脚本

# 从SQL文件中提取表结构
grep -E "CREATE TABLE|COMMENT ON" sql/*.sql

3. 文档转换脚本

已有的转换脚本：

• export_to_docx.sh - 转换为Word文档
• export_to_pdf.sh - 转换为PDF文档

六、AI辅助编写建议（基于实践经验）

1. 分阶段编写策略

第一阶段：结构搭建（参考 water_biz_integrated_doc.md）

• 建立完整的目录结构，参考现有文档的8级目录层次
• 设置文档间的链接关系，形成文档网络
• 确定每个文档的预期长度（参考现有文档：190-586行）

第二阶段：内容填充（参考 water_biz_module_design.md）

• 每次编写一个模块，保持单一焦点
• 按照"概述→详细设计→实现方案"的三层结构
• 保持技术深度的一致性

第三阶段：质量提升

• 参考现有文档的写作风格和术语使用
• 统一技术栈描述（如：Spring Boot 3.x + MyBatis Plus）
• 完善图表和代码示例

2. 充分利用现有资源

参考文档优先级

1. 核心参考：water_biz_* 系列文档（已验证的高质量内容）
2. 补充参考：/parsed_docs_new/ 中的原系统文档
3. 结构参考：/templates 模板文档
4. 技术参考：/api 接口规范 + /sql 数据库结构

内容复用策略

• 架构描述：直接复用 water_biz_system_architecture.md 中的技术架构部分
• 模块设计：参考 water_biz_module_design.md 的功能分解方式
• 接口规范：复用 water_biz_interface_design.md 的RESTful设计原则
• 数据库设计：基于 water_biz_database_design.md 的多租户架构思路

术语标准化（参考现有文档）

• 系统名称：福建水务营收系统
• 技术栈：RuoYi-Vue-Pro + yudao-ui-admin-vue3
• 数据库：MySQL/MariaDB（支持国产 OpenGauss）
• 架构模式：多租户SaaS架构

3. 质量控制标准

内容深度检查（参考现有文档标准）

• 系统架构：需达到 water_biz_system_architecture.md 的277行深度
• 模块设计：需达到 water_biz_module_design.md 的586行详细程度
• 数据库设计：需达到 water_biz_database_design.md 的313行完整性

格式规范检查

• 目录结构：参考现有文档的markdown目录链接格式
• 代码块：使用统一的代码语言标识（json、sql、markdown等）
• 表格格式：保持与现有文档一致的表格样式
• 链接检查：确保内部文档链接的正确性

技术方案验证

• 架构一致性：与 water_biz_system_architecture.md 的技术选型保持一致
• 接口规范：遵循 water_biz_interface_design.md 的RESTful设计原则
• 数据库设计：符合 water_biz_database_design.md 的多租户架构要求

七、协作流程

1. 版本控制

• 使用Git管理文档版本
• 建立分支管理策略
• 定期合并和发布

2. 评审流程

• 技术评审：架构师、开发负责人
• 业务评审：产品经理、业务专家
• 格式评审：技术文档管理员

3. 更新维护

• 定期更新API变更
• 同步数据库结构变化
• 维护文档的时效性

八、输出成果和迭代优化

8.1 标准文档产出（基于模板）

核心设计文档

1. 新-概要设计说明书.md（目标：300行左右，参考 water_biz_system_architecture.md）
2. 新-详细设计说明书.md（目标：500行左右，参考 water_biz_module_design.md）
3. 新-数据库设计说明书.md（目标：300行左右，参考 water_biz_database_design.md）

配套文档 4. 新-接口设计说明书.md（参考 water_biz_interface_design.md） 5. 新-部署运维说明书.md（参考 water_biz_deployment_design.md） 6. 新-项目总结报告.md（参考 water_biz_summary.md） 7. 新-集成文档索引.md（参考 water_biz_integrated_doc.md）

8.2 文档体系架构（参考现有经验）

文档关系网络

新-集成文档索引.md (主入口)
├── 新-概要设计说明书.md
├── 新-详细设计说明书.md  
├── 新-数据库设计说明书.md
├── 新-接口设计说明书.md
├── 新-部署运维说明书.md
└── 新-项目总结报告.md

内部链接系统（参考 water_biz_integrated_doc.md）

• 建立完整的内部文档链接
• 设置章节跳转链接
• 创建相关文档引用关系

8.3 格式转换和发布

多格式支持

• Markdown原始文档：便于AI迭代和版本控制
• Word文档：使用 export_to_docx.sh 转换为正式交付格式
• PDF文档：使用 export_to_pdf.sh 转换为存档备份格式

质量检查清单

• 文档内部链接完整性
• 技术术语统一性（参考现有文档标准）
• 代码示例格式规范
• 表格和图表质量
• 目录结构层次合理性

8.4 配套资源体系

技术资源

• API文档：基于 /api/【IF】福建水务营收系统.openapi.json
• 数据库字典：基于 /sql 文件和 04_Appendix/Archive/05_Data_Dictionary/营收数据字典.md
• 架构图表：参考 architecture_diagram.html 和 images/architecture_diagram.png

参考资源库

• 原系统文档：/parsed_docs_new/ 目录下的完整解析文档
• 经验文档：water_biz_* 系列作为最佳实践参考
• 开发规范：cursor_rules.md 作为编码和文档规范

8.5 迭代优化机制

持续改进流程

1. 定期回顾：每两周回顾一次文档质量和完整性
2. 版本管理：使用Git管理文档版本，建立里程碑标记
3. 质量对标：以现有 water_biz_* 文档为质量基准
4. 用户反馈：收集开发团队和业务团队的使用反馈

优化重点领域

• 技术一致性：确保与 water_biz_system_architecture.md 的技术选型一致
• 业务完整性：覆盖 water_biz_module_design.md 中的所有功能模块
• 实施可行性：参考 water_biz_deployment_design.md 的部署经验

成功评价标准

• 文档内容深度达到现有文档标准（300-600行）
• 技术方案与现有架构设计保持一致
• 能够指导实际的系统开发和部署工作
• 便于AI工具进行迭代优化和维护更新

这个完善的流程体系融合了项目的实际经验，确保新文档既符合标准模板要求，又能达到现有高质量文档的水准。

最后交付的文档

概要设计说明书.md 详细设计说明书.md 数据库设计说明书.md

需要内容完整，格式正确，结构清晰，易于阅读。包含我现有./api ./sql 里的内容 设计内容覆盖./parsed_docs_new 里的内容 但是数据库设计还是 我现有./sql 里的内容 为准