fujian_water_biz_doc/文档编写流程指南.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. **文档头部信息**（参考现有文档格式）
   ```markdown
   # 福建水务数智营收管理系统概要设计说明书
   
   ## 目录
   - [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图设计**：实体关系图
   - **表关系说明**：外键关系和业务关联
   - **数据字典**：参考 `ori_doc/营收数据字典.md`

## 五、自动化工具和脚本

### 1. API解析脚本
```bash
# 从OpenAPI JSON中提取接口信息
jq '.paths | keys[]' api/【IF】水务数智营收管理系统.openapi.json
```

### 2. 数据库表解析脚本
```bash
# 从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` 文件和 `ori_doc/营收数据字典.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 里的内容 为准