diff --git a/README.md b/README.md index d78bb0e..360f3bb 100644 --- a/README.md +++ b/README.md @@ -38,6 +38,11 @@ - [🔧 详细设计说明书](docs/design/02_Detailed_Design/01_Detailed_Design.md) - [🔧 模块追溯索引](docs/design/02_Detailed_Design/02_Module_Traceability_Index.md) - [🔧 报装CA电子签章补充](docs/design/02_Detailed_Design/03_CA_Esignature_Supplement.md) +- [🔧 统一平台模块正文](docs/design/02_Detailed_Design/11_UP_Detailed.md) +- [🔧 营收业务模块正文](docs/design/02_Detailed_Design/12_REV_Detailed.md) +- [🔧 客户服务模块正文](docs/design/02_Detailed_Design/13_CS_Detailed.md) +- [🔧 表务模块正文](docs/design/02_Detailed_Design/14_METER_Detailed.md) +- [🔧 报装与签章模块正文](docs/design/02_Detailed_Design/15_INST_Detailed.md) ### 03\_技术专项 (Technical) diff --git a/docs/design/00_Management/01_Project_Progress.md b/docs/design/00_Management/01_Project_Progress.md index 7e4cd59..81123a3 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 | `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` 引用与导出清单。 | 用户提出“详细设计没有分模块”，要求新增模块正文文档 | 正面影响，详细设计形成“主详设总册 + 分模块正文”的双层组织，模块维护颗粒度更清晰；评审、检索、按模块协作改稿效率提升。 | | 2026-03-11 | `02_Detailed_Design` 结构重组与主稿导航标准化 | 对 `docs/design/02_Detailed_Design/` 执行“单一真源 + 专项补充”重构：1）将并行稿迁入归档（`04_Appendix/Archive/03_Design_Docs/02_Module_Design_legacy_20260311.md`、`03_CA_Installation_Design_legacy_20260311.md`）；2）新增 `02_Module_Traceability_Index.md`（模块-接口-数据域追溯索引）与 `03_CA_Esignature_Supplement.md`（报装电子签章专项补充）；3）重写 `01_Detailed_Design.md` 顶部为“章节导航（精简）”并补齐稳定锚点（`sec-preface`、`sec-overall-design`、`sec-module-detail`、`sec-platform-detail`、`sec-revenue-detail`、`sec-customer-detail`、`sec-meter-detail`、`sec-installation-detail`、`sec-database-detail`、`sec-interface-detail`、`sec-security-detail`、`sec-deployment-detail`、`sec-appendix`）；4）同步更新 README、导出脚本与附录引用。 | 用户确认按重组方案执行，要求解决 `02_Detailed_Design` 混乱问题并形成可长期维护结构 | 正面影响，详细设计目录职责边界明确：主详设聚焦权威正文，索引与CA细节分离；旧并行稿退出正式入口，口径冲突与维护噪音显著降低；章节定位和 AI 检索稳定性提升。 | | 2026-03-11 | `03_Summary_Design` 导航精简与锚点标准化 | 在 `docs/design/01_Overview/03_Summary_Design.md` 中将顶部导航收敛为“章节导航（精简）”，移除冗长目录块，建立稳定锚点体系（`sec-preface`、`sec-overall-design`、`sec-subsystems`、`sec-sys-001~010`、`sec-nfr`）并同步章节跳转链接；执行 `make validate-file FILE=docs/design/01_Overview/03_Summary_Design.md`、`make check-links`、`make validate-mermaid`、`make check-ai-governance`。 | 用户要求“章节导航精简 + 锚点标准化”，并希望直接落地可执行结果 | 正面影响，超长主文档定位成本显著下降，章节跳转稳定性提升，后续标题调整时链接不易失效，便于 AI 检索与评审维护。 | | 2026-03-11 | `01_Overview` 三文档深度重写 | 按“主文档单一真源、支撑文档不重复”原则重写 `docs/design/01_Overview/01_System_Overview.md`、`docs/design/01_Overview/02_System_Architecture.md`、`docs/design/01_Overview/04_System_Diagrams.md`：1）`01` 收敛为背景/目标/范围/术语导览，移除实现细节；2）`02` 收敛为总体架构原则、子系统边界与协同规则，统一数据库口径为达梦数据库 8.0+；3）`04` 重建为图谱目录 + 三张总体图，并修复旧图中重复节点标识问题；同步完成 `validate-file`、`check-links`、`validate-mermaid`、`check-ai-governance` 校验 | 用户要求对 `docs/design/01_Overview` 混乱状态进行重写，形成可维护、可交付、可对齐主稿的总体层结构 | 正面影响，`01_Overview` 目录实现“导览文档 + 架构文档 + 图谱文档”分工清晰，重复内容显著减少，口径冲突（尤其数据库选型）已消除，后续评审和维护成本下降 | diff --git a/docs/design/00_Management/03_Task_Checklist.md b/docs/design/00_Management/03_Task_Checklist.md index c3f8130..e337e78 100644 --- a/docs/design/00_Management/03_Task_Checklist.md +++ b/docs/design/00_Management/03_Task_Checklist.md @@ -138,6 +138,18 @@ ## ✅ 最新完成任务 (持续更新) +### 📋 `02_Detailed_Design` 分模块正文补齐 + +- [x] **完成详细设计分模块正文文件新增** ✅ (2026-03-11) + - [x] 新增 `11_UP_Detailed.md`（统一平台模块正文）✅ + - [x] 新增 `12_REV_Detailed.md`（营收业务模块正文）✅ + - [x] 新增 `13_CS_Detailed.md`（客户服务模块正文）✅ + - [x] 新增 `14_METER_Detailed.md`（表务模块正文）✅ + - [x] 新增 `15_INST_Detailed.md`（报装与签章模块正文）✅ + - [x] 在 `01_Detailed_Design.md` 增加“模块正文文件索引”并纳入参考资料 ✅ + - [x] 更新 `README.md`、`docs/design/02_Detailed_Design/README.md`、`scripts/unified_export.sh`、`02_Module_Traceability_Index.md` 的入口与引用 ✅ + - [x] 更新项目进度文件记录本次分模块补齐动作 ✅ + ### 📋 `02_Detailed_Design` 重组治理（主稿单一真源） - [x] **完成详细设计目录重组与文件治理** ✅ (2026-03-11) diff --git a/docs/design/02_Detailed_Design/01_Detailed_Design.md b/docs/design/02_Detailed_Design/01_Detailed_Design.md index d49ec16..4746700 100644 --- a/docs/design/02_Detailed_Design/01_Detailed_Design.md +++ b/docs/design/02_Detailed_Design/01_Detailed_Design.md @@ -45,6 +45,7 @@ retrieval_priority: P0 - [安全详细设计](#sec-security-detail) - [部署与运维设计](#sec-deployment-detail) - [附录](#sec-appendix) +- [模块正文文件索引](#sec-module-files) @@ -86,12 +87,27 @@ retrieval_priority: P0 1. 《福建水务营收系统概要设计相关文档》 2. `docs/design/02_Detailed_Design/02_Module_Traceability_Index.md` 3. `docs/design/02_Detailed_Design/03_CA_Esignature_Supplement.md` -4. `docs/design/03_Technical_Design/01_Database_Design.md` -5. `docs/design/03_Technical_Design/02_Table_Specs.md` -6. `docs/design/03_Technical_Design/03_Interface_Design.md` -7. `docs/design/03_Technical_Design/04_Security_Design.md` -8. `docs/design/03_Technical_Design/05_Deployment_Design.md` -9. 福建水投相关业务操作手册及需求说明资料 +4. `docs/design/02_Detailed_Design/11_UP_Detailed.md` +5. `docs/design/02_Detailed_Design/12_REV_Detailed.md` +6. `docs/design/02_Detailed_Design/13_CS_Detailed.md` +7. `docs/design/02_Detailed_Design/14_METER_Detailed.md` +8. `docs/design/02_Detailed_Design/15_INST_Detailed.md` +9. `docs/design/03_Technical_Design/01_Database_Design.md` +10. `docs/design/03_Technical_Design/02_Table_Specs.md` +11. `docs/design/03_Technical_Design/03_Interface_Design.md` +12. `docs/design/03_Technical_Design/04_Security_Design.md` +13. `docs/design/03_Technical_Design/05_Deployment_Design.md` +14. 福建水投相关业务操作手册及需求说明资料 + + + +## 模块正文文件索引 + +- 统一平台模块正文：`docs/design/02_Detailed_Design/11_UP_Detailed.md` +- 营收业务模块正文：`docs/design/02_Detailed_Design/12_REV_Detailed.md` +- 客户服务模块正文：`docs/design/02_Detailed_Design/13_CS_Detailed.md` +- 表务模块正文：`docs/design/02_Detailed_Design/14_METER_Detailed.md` +- 报装与签章模块正文：`docs/design/02_Detailed_Design/15_INST_Detailed.md` diff --git a/docs/design/02_Detailed_Design/02_Module_Traceability_Index.md b/docs/design/02_Detailed_Design/02_Module_Traceability_Index.md index df8f490..e49addf 100644 --- a/docs/design/02_Detailed_Design/02_Module_Traceability_Index.md +++ b/docs/design/02_Detailed_Design/02_Module_Traceability_Index.md @@ -32,6 +32,7 @@ retrieval_priority: P1 - 本文档是追溯索引，不替代主详设内容； - 详细设计权威口径以 `01_Detailed_Design.md` 为准； +- 模块正文承载于 `11_UP_Detailed.md`、`12_REV_Detailed.md`、`13_CS_Detailed.md`、`14_METER_Detailed.md`、`15_INST_Detailed.md`； - 数据表字段定义以 `03_Technical_Design/01_Database_Design.md`、`03_Technical_Design/02_Table_Specs.md` 为准； - 接口参数细项以 `03_Technical_Design/03_Interface_Design.md` 为准。 @@ -48,13 +49,13 @@ retrieval_priority: P1 ## 子系统级追溯矩阵 -| 子系统/能力域 | 模块范围 | 主详设章节 | 主要技术专题 | +| 子系统/能力域 | 模块范围 | 模块正文定位 | 主要技术专题 | |---|---|---|---| -| 统一平台 | `UP-001 ~ UP-004` | [统一平台详细设计](./01_Detailed_Design.md#sec-platform-detail) | [接口设计](../03_Technical_Design/03_Interface_Design.md)、[安全设计](../03_Technical_Design/04_Security_Design.md) | -| 营收业务 | `REV-001 ~ REV-009` | [营收业务详细设计](./01_Detailed_Design.md#sec-revenue-detail) | [数据库设计](../03_Technical_Design/01_Database_Design.md)、[接口设计](../03_Technical_Design/03_Interface_Design.md) | -| 客户服务 | `CS-001 ~ CS-007` | [客户服务模块详细设计](./01_Detailed_Design.md#sec-customer-detail) | [接口设计](../03_Technical_Design/03_Interface_Design.md)、[安全设计](../03_Technical_Design/04_Security_Design.md) | -| 表务管理 | `METER-001 ~ METER-004` | [表务详细设计](./01_Detailed_Design.md#sec-meter-detail) | [数据库设计](../03_Technical_Design/01_Database_Design.md)、[接口设计](../03_Technical_Design/03_Interface_Design.md) | -| 报装与签章 | `INST-001 ~ INST-005` | [报装与签章详细设计](./01_Detailed_Design.md#sec-installation-detail) | [CA 补充说明](./03_CA_Esignature_Supplement.md)、[安全设计](../03_Technical_Design/04_Security_Design.md) | +| 统一平台 | `UP-001 ~ UP-004` | [统一平台模块正文](./11_UP_Detailed.md#sec-content) | [接口设计](../03_Technical_Design/03_Interface_Design.md)、[安全设计](../03_Technical_Design/04_Security_Design.md) | +| 营收业务 | `REV-001 ~ REV-009` | [营收业务模块正文](./12_REV_Detailed.md#sec-content) | [数据库设计](../03_Technical_Design/01_Database_Design.md)、[接口设计](../03_Technical_Design/03_Interface_Design.md) | +| 客户服务 | `CS-001 ~ CS-007` | [客户服务模块正文](./13_CS_Detailed.md#sec-content) | [接口设计](../03_Technical_Design/03_Interface_Design.md)、[安全设计](../03_Technical_Design/04_Security_Design.md) | +| 表务管理 | `METER-001 ~ METER-004` | [表务模块正文](./14_METER_Detailed.md#sec-content) | [数据库设计](../03_Technical_Design/01_Database_Design.md)、[接口设计](../03_Technical_Design/03_Interface_Design.md) | +| 报装与签章 | `INST-001 ~ INST-005` | [报装与签章模块正文](./15_INST_Detailed.md#sec-content) | [CA 补充说明](./03_CA_Esignature_Supplement.md)、[安全设计](../03_Technical_Design/04_Security_Design.md) | @@ -105,4 +106,3 @@ retrieval_priority: P1 - `make validate-file FILE=docs/design/02_Detailed_Design/01_Detailed_Design.md` - `make validate-file FILE=docs/design/02_Detailed_Design/02_Module_Traceability_Index.md` - `make check-links` - diff --git a/docs/design/02_Detailed_Design/11_UP_Detailed.md b/docs/design/02_Detailed_Design/11_UP_Detailed.md new file mode 100644 index 0000000..8cef4b7 --- /dev/null +++ b/docs/design/02_Detailed_Design/11_UP_Detailed.md @@ -0,0 +1,125 @@ +--- +doc_id: DT-11-UP +doc_role: module_body +authority: secondary +scope: 详细设计-统一平台 +source_of_truth: false +last_reviewed: 2026-03-11 +retrieval_priority: P1 +--- + +# 福建水务营收系统详细设计-统一平台模块正文 + +## 章节导航（精简） + +- [文档定位](#sec-position) +- [统一平台详细设计正文](#sec-content) + - [UP-001 统一认证与单点登录](#mod-up-001) + - [UP-002 组织用户与权限管理](#mod-up-002) + - [UP-003 参数字典与基础配置](#mod-up-003) + - [UP-004 审计监控与运维支撑](#mod-up-004) + + + +## 文档定位 + +本文档为 `01_Detailed_Design.md` 中“统一平台详细设计”章节的模块正文拆分稿，便于按模块独立维护。正式交付口径以主详设为准。 + + + +# 统一平台详细设计 + + + +## UP-001 统一认证与单点登录 + +### 功能说明 + +UP-001 为全系统提供统一身份认证与单点登录能力，支撑 PC 管理端、移动作业端、客户渠道及外部集成应用的统一接入。 + +### 关键设计 + +1. 支持用户名密码登录、短信验证码登录、第三方授权登录。 +2. 采用 OAuth2.0 + JWT 实现访问令牌签发与会话管理。 +3. 对外部系统开放标准认证接口，支持令牌续期与退出失效。 +4. 对高敏感操作支持 MFA 二次校验。 + +### 业务流程 + +```mermaid +sequenceDiagram + participant 用户 + participant 接入端 + participant 认证中心 + participant 用户中心 + + 用户->>接入端: 提交登录信息 + 接入端->>认证中心: 发起认证请求 + 认证中心->>用户中心: 校验用户/角色/状态 + 用户中心-->>认证中心: 返回校验结果 + 认证中心-->>接入端: 返回Token/权限上下文 + 接入端-->>用户: 登录成功并进入目标系统 +``` + +### 核心数据 + +- `system_users`：用户基本信息。 +- `system_oauth2_client`：客户端信息。 +- `system_oauth2_access_token`：访问令牌。 +- `system_oauth2_refresh_token`：刷新令牌。 +- `system_login_log`：登录审计日志。 + + + +## UP-002 组织用户与权限管理 + +### 功能说明 + +UP-002 管理组织机构、岗位、角色、菜单、数据权限和用户授权关系，是业务系统权限控制与数据隔离的基础。 + +### 关键设计 + +1. 支持集团—区域公司—营业所三级及以上组织结构。 +2. 基于 RBAC 实现菜单权限、按钮权限、数据权限。 +3. 支持多租户/多单位数据隔离与用户归属控制。 +4. 敏感操作如账务调整、退款、作废、签章回退必须经过权限校验。 + +### 主要规则 + +- 角色权限与组织权限叠加生效。 +- 业务数据默认按所属单位、片区、岗位范围过滤。 +- 超权限查询、批量导出、敏感字段查看需单独授权。 + + + +## UP-003 参数字典与基础配置 + +### 功能说明 + +UP-003 用于统一维护业务参数、地址参数、水价规则、短信模板、打印模板、字典数据与定时任务参数。 + +### 关键设计 + +| 配置类别 | 典型内容 | 用途 | +|---|---|---| +| 业务字典 | 客户类型、抄表方式、工单状态 | 统一编码与展示 | +| 地址参数 | 行政区划、片区、册本归属 | 客户与表务归属管理 | +| 价格体系 | 用水性质、阶梯水价、污水费规则 | 开账与账务计算 | +| 渠道参数 | 支付渠道、短信模板、税控配置 | 外部接口集成 | +| 任务参数 | 自动开账、对账、备份周期 | 运维调度 | + + + +## UP-004 审计监控与运维支撑 + +### 功能说明 + +UP-004 提供操作日志、登录日志、接口日志、异常监控、在线用户、任务监控、性能监控等能力。 + +### 关键设计 + +1. 所有核心业务操作写入统一审计日志。 +2. 接口调用成功率、响应时长、异常码进入监控平台。 +3. 定时任务执行结果、失败重试与人工补偿过程可追踪。 +4. 监控与告警支持短信、邮件、站内信等通知方式。 + diff --git a/docs/design/02_Detailed_Design/12_REV_Detailed.md b/docs/design/02_Detailed_Design/12_REV_Detailed.md new file mode 100644 index 0000000..1a96d40 --- /dev/null +++ b/docs/design/02_Detailed_Design/12_REV_Detailed.md @@ -0,0 +1,348 @@ +--- +doc_id: DT-12-REV +doc_role: module_body +authority: secondary +scope: 详细设计-营收业务 +source_of_truth: false +last_reviewed: 2026-03-11 +retrieval_priority: P1 +--- + +# 福建水务营收系统详细设计-营收业务模块正文 + +## 章节导航（精简） + +- [文档定位](#sec-position) +- [营收业务详细设计正文](#sec-content) + - [REV-001 客户资料管理](#mod-rev-001) + - [REV-002 抄表开账](#mod-rev-002) + - [REV-003 营业收费](#mod-rev-003) + - [REV-004 账务处理](#mod-rev-004) + - [REV-005 发票与税务处理](#mod-rev-005) + - [REV-006 催缴与通知](#mod-rev-006) + - [REV-007 统计分析](#mod-rev-007) + - [REV-008 代收与银行业务](#mod-rev-008) + - [REV-009 业务参数配置](#mod-rev-009) + + + +## 文档定位 + +本文档为 `01_Detailed_Design.md` 中“营收业务详细设计”章节的模块正文拆分稿，便于按模块独立维护。正式交付口径以主详设为准。 + + + +# 营收业务详细设计 + + + +## REV-001 客户资料管理 + +### 功能说明 + +负责客户主档、账户主档、联系人、客户分组、客户与水表关系、客户开票信息、客户渠道绑定及托收/代扣关系维护，是抄表、收费、发票、代扣等后续业务的主数据基础。 + +### 关键设计 + +1. 客户建档覆盖立户、变更、更名、过户、销户、报停等全生命周期处理。 +2. 客户资料支持按客户类型、用水性质、片区、集团客户、重点客户等维度管理。 +3. 客户与水表、开票主体、托收/代扣签约关系按关联表维护，避免在主表中堆叠多类属性。 +4. 客户编号、集收标记、计划用水方案等规则类数据由统一配置与客户关系表共同支撑。 + +### 核心数据 + +- `biz_cust`：客户主档。 +- `biz_account`：客户账户与账户状态。 +- `biz_cust_contact`：联系人及联系方式。 +- `biz_cust_group`：客户分组。 +- `biz_cust_meter`：客户与水表绑定关系。 +- `biz_cust_invoice`：客户开票信息。 +- `biz_cust_app_binds`：渠道绑定关系。 +- `biz_cust_collection_rel`：客户托收关系。 +- `biz_cust_withholding_rel`：客户代扣关系。 +- `biz_cust_water_use_scheme`、`biz_cust_water_scheme_rel`：客户计划用水方案关系。 +- `biz_cust_no_rule`：客户编号规则。 +- `biz_cust_hub_marks`：集收号/集收标记关系。 + +### 落地边界 + +- **已落地**：客户主档、账户、联系人、分组、绑定、开票、托收/代扣关系。 +- **部分落地**：客户扩展关系、集收与规则类对象已见明确关系表，但具体业务场景仍需结合流程进一步细化。 +- **文档先行**：主副卡、部分复杂客户关系对象在当前 backend 中未见完全独立表族，文档中仅保留业务对象表述。 + + + +## REV-002 抄表开账 + +### 功能说明 + +负责抄表计划、册本管理、抄表录入、抄表状态跟踪、异常复核、计费计算与账单生成，是营收核心处理链路的起点。 + +### 业务流程 + +```mermaid +flowchart TD + A[制定抄表计划] --> B[生成抄表册本] + B --> C[分配抄表任务] + C --> D[人工/远传/自报抄表] + D --> E[数据校验] + E --> F{是否异常} + F -->|是| G[异常复核处理] + F -->|否| H[生成开账数据] + G --> H + H --> I[按价格模板与费用组成计费] + I --> J[生成营业账与明细] + J --> K[账单审核确认] + K --> L[进入收费/催缴/开票] +``` + +### 关键规则 + +1. 抄表数据同时校验本次读数、上次读数、用量波动和抄表状态。 +2. 异常抄表支持估抄、补抄、重录、人工复核。 +3. 开账按价格归属、价格模板、费用组成、阶梯规则、计划用水方案综合计算。 +4. 审核通过后的营业账方可进入收费、催缴和发票流程。 +5. 远传抄表数据可由 `SYS-006` / IoT 能力提供采集支撑，但账单生成仍归属 SYS-002。 + +### 核心数据 + +- `biz_meter_book`：册本与抄表计划。 +- `biz_meter_read`：抄表任务状态/执行状态。 +- `biz_reading_data`：抄表数据。 +- `biz_last_reading`：上次抄表结果。 +- `biz_reading_logs`：抄表日志与过程留痕。 +- `biz_meter`：计量水表主档引用。 +- `biz_charge`：营业账主表。 +- `biz_charge_detail`：营业账明细。 +- `biz_price_category`：价格归属。 +- `biz_price_template`：价格模板。 +- `biz_price_adjustment_snap`：调价快照。 +- `biz_price_tier_adjustment`：阶梯规则。 +- `biz_cost_component`：费用组成。 +- `biz_water_use_scheme`、`biz_water_use_scheme_tier`：计划用水方案与阶梯。 + +### 落地边界 + +- **已落地**：册本、抄表数据、上次抄表、抄表日志、营业账主明细、价格模板与阶梯规则。 +- **部分落地**：部分异常场景对象可能仍通过状态字段和日志表承载，而非全部拆成独立业务表。 +- **文档先行**：个别精细稽查、轨迹、下载同步对象当前未在本轮映射中确认为独立表。 + + + +## REV-003 营业收费 + +### 功能说明 + +支持柜台收费、预存款/余额抵扣、线上缴费回写、柜面扫码、营业网点收费及收费凭证管理，统一承接营收账单的核销处理。 + +### 业务流程 + +```mermaid +flowchart TD + A[查询客户及待缴账单] --> B[选择账单与核销方式] + B --> C[选择支付渠道] + C --> D{支付方式} + D -->|柜台现金/POS/扫码| E[现场收费] + D -->|微信/支付宝/聚合支付| F[渠道下单] + D -->|预存款/余额抵扣| G[账户余额核销] + E --> H[更新营业账状态] + F --> I[等待异步回调确认] + G --> H + I --> H + H --> J[生成收费记录与凭证] + J --> K[进入发票/对账流程] +``` + +### 关键规则 + +1. 一次缴费可对应多个账单或账单明细的组合核销。 +2. 收费记录必须保留渠道、流水号、网点、操作员、终端信息。 +3. 线上支付必须以回调或查询确认结果为准，不得以发起状态直接记账。 +4. 支付能力由 `SYS-009` 提供，SYS-002 负责账单核销与业务状态回写。 + +### 核心数据 + +- `biz_charge`、`biz_charge_detail`：待缴与已缴账单主明细。 +- `biz_collection`：托收/代收主表。 +- `biz_withholding`：代扣/托收主表。 +- `bk_transaction`：渠道交易流水。 +- `bk_transaction_callback`：支付回调记录。 +- `bk_transaction_exception`：支付异常记录。 + +### 落地边界 + +- **已落地**：营业账主明细、交易流水、回调、异常、托收/代扣主对象。 +- **部分落地**：柜台班结、部分收费汇总类对象可能通过业务流程与报表实现，不一定存在独立表。 +- **文档先行**：部分红冲、实时收费汇总类台账暂不表述为已确认独立实体表。 + + + +## REV-004 账务处理 + +### 功能说明 + +承担水量调整、金额调整、违约金减免、退款、冲正、呆坏账申请等账务修正与审批处理能力，保证收费后账务结果可追溯、可审计。 + +### 关键设计 + +1. 调整类操作以营业账主明细为基础，并通过日志与审批留痕记录前后变化。 +2. 水量调整、金额调整、优惠调整等场景可引用价格模板、阶梯与优惠对象重新计算。 +3. 退款、冲正等交易修正需与原支付流水及渠道状态联动校验。 +4. 对于当前未见明确独立实体表的特账、跨周期水量、退款账等对象，文档以“业务处理场景”表述，不强行落为已实现表。 + +### 核心数据 + +- `biz_charge`、`biz_charge_detail`：账务调整的核心对象。 +- 价格调整/优惠相关表：用于重算账单或差额追溯。 +- `biz_operat_log`、`biz_operat_log_detail`：操作与变更留痕。 + +### 主要场景 + +| 场景 | 说明 | 控制要点 | +|---|---|---| +| 水量调整 | 更正异常水量 | 需复核原因、附件和原抄表依据 | +| 金额调整 | 更正账单金额 | 需记录依据、差异金额和审批链路 | +| 退款处理 | 退回客户支付资金或预存款 | 需校验原交易、退款余额与幂等性 | +| 错误缴费冲正 | 修正误收/误核销记录 | 需关联原交易与账单状态 | +| 呆坏账申请 | 对长期欠费进行分类处理 | 需结合账龄、客户状态与审批结果 | + +### 落地边界 + +- **已落地**：营业账主明细、操作日志、价格/方案相关重算支撑。 +- **部分落地**：精细化账务对象更多表现为流程与场景，并未在 backend 中全部体现为独立表族。 +- **文档先行**：特账、退款账、跨周期水量等对象保留业务语义，不宣称为已实现独立表。 + + + +## REV-005 发票与税务处理 + +### 功能说明 + +负责发票申请、开票校验、开票结果回写、发票查询、作废与红冲处理，作为营收业务对发票服务的业务接入层。 + +### 关键设计 + +1. 发票申请以客户信息、缴费记录、账单信息、税率配置为基础。 +2. 个人与企业开票均通过客户开票信息与税率表完成合法性校验。 +3. 发票开具、作废、红冲由 `SYS-008` 统一承接，SYS-002 负责业务上下文传递与结果落账。 +4. 电子发票可通过客户服务渠道推送或下载。 + +### 核心数据 + +- `biz_invoice`：发票主记录。 +- `biz_invoice_taxrate`：税率配置。 +- `biz_cust_invoice`：客户开票信息。 + +### 落地边界 + +- **已落地**：发票主记录、税率配置、客户开票信息。 +- **部分落地**：发票修改、开票过程留痕在后端中已有相关对象，但整套发票明细/批次类对象尚未全部确认。 +- **文档先行**：发票明细、营业账开票关系等对象仍按设计能力描述，不表述为本轮已确认独立表。 + + + +## REV-006 催缴与通知 + +### 功能说明 + +针对欠费账单按账龄、金额、客户类别等规则生成催缴任务，通过短信、微信、站内通知等方式触达客户，并回写催缴结果。 + +### 关键设计 + +1. 催缴策略以营业账状态、欠费金额、账龄分布和客户类别为基础。 +2. 自动催缴与人工催缴可并行，支持停复水等后续处置联动。 +3. 触达能力由 `SYS-010` 提供，SYS-002 负责生成待发送业务事件、催缴名单与结果回写。 +4. 当前后端中部分催缴汇总、停水明细对象未确认独立落表，文档中保持保守描述。 + +### 核心数据 + +- `biz_charge`、`biz_charge_detail`：催缴对象来源。 +- 催缴结果与通知日志：通过业务状态与消息结果联动留痕。 + +### 落地边界 + +- **已落地**：以营业账为基础的欠费识别与消息协同前提数据。 +- **部分落地**：催缴登记汇总、停水汇总等对象暂未在 backend 中确认独立表。 +- **文档先行**：复杂催缴台账与停复水统计仅作为业务场景保留。 + + + +## REV-007 统计分析 + +### 功能说明 + +提供营收、抄表、收费、欠费、渠道、客户、工单等多维度统计分析能力，为经营分析和业务监管提供数据支撑。 + +### 关键设计 + +1. 报表统计基于客户、账单、收费、渠道、时间、片区等维度聚合。 +2. 常用统计口径包括售水量、收费金额、欠费规模、渠道占比、客户类型分布、抄表完成率等。 +3. 导出与查询结果受数据权限控制，重点报表可采用预聚合或物化结果提升查询性能。 + +### 核心数据 + +- 客户维度：`biz_cust`、`biz_account`。 +- 抄表维度：`biz_meter_book`、`biz_reading_data`、`biz_last_reading`。 +- 账务与收费维度：`biz_charge`、`biz_charge_detail`。 +- 渠道维度：`bk_transaction`、`bk_payment_channel`。 + +### 落地边界 + +- **已落地**：主要统计源数据在客户、抄表、收费、渠道等领域均已具备。 +- **部分落地**：部分分析结果更多依赖报表层实现，而非单独分析表。 +- **文档先行**：预测类、专题分析类深度模型暂不写成后端已实现能力。 + + + +## REV-008 代收与银行业务 + +### 功能说明 + +支持银行代收、银行代扣、实时收费、夜间批量扣款、对账与结算处理，是 SYS-002 面向 `SYS-009` 支付与银行结算能力的业务承接模块。 + +### 关键设计 + +1. 渠道、路由、接口配置、签约、交易、回调、异常、对账、结算形成完整银行业务链条。 +2. 实时收费场景由渠道交易流水驱动账单核销，批量代扣场景由签约关系与批次处理驱动。 +3. 对账结果区分一致、长款、短款、失败待处理等状态，支持差异追踪与人工补偿。 +4. 国密报文、批量文件、标准 API 等技术细节由 `SYS-009` 承载，SYS-002 保留业务规则与状态协同。 + +### 核心数据 + +- `bk_payment_channel`：支付渠道。 +- `bk_channel_api_config`：渠道接口配置。 +- `bk_channel_route_rule`：渠道路由规则。 +- `bk_withholding_agreement`：代扣签约。 +- `bk_withholding_batch`、`bk_withholding_item`：代扣批次与明细。 +- `bk_reconcile_batch`、`bk_reconcile_diff`：对账批次与差异。 +- `bk_settlement_batch`：结算批次。 +- `bk_transaction`、`bk_transaction_callback`、`bk_transaction_exception`：交易、回调、异常。 +- `biz_collection`、`biz_withholding`：代收/代扣业务主对象。 + +### 落地边界 + +- **已落地**：渠道、路由、交易、回调、异常、签约、批次、对账、结算等主链路对象。 +- **部分落地**：部分统计类、汇总类对象可能在渠道报表或外部结算文件层体现。 +- **文档先行**：不将未明确扫描到的扩展银行台账写成已实现独立表。 + + + +## REV-009 业务参数配置 + +### 功能说明 + +负责营收域的价格参数、客户编号规则、页面配置、打印与渠道相关业务参数配置，为客户、开账、收费、发票、催缴等模块提供统一配置支撑。 + +### 关键设计 + +1. 业务参数按租户、单位、片区、业务类别分层管理。 +2. 价格体系、客户编号规则、页面字段配置、打印与通知参数统一归口维护。 +3. 配置变更应具备版本化、操作留痕与生效范围控制。 + +### 核心数据 + +- `biz_parameter_settings`：业务参数配置。 +- `biz_page_settings`、`biz_page_settings_detail`：页面配置。 +- `biz_price_category`、`biz_price_template`、`biz_template_dept_rel`：价格归属与模板站点关系。 +- `biz_cust_no_rule`：客户编号规则。 + diff --git a/docs/design/02_Detailed_Design/13_CS_Detailed.md b/docs/design/02_Detailed_Design/13_CS_Detailed.md new file mode 100644 index 0000000..d573086 --- /dev/null +++ b/docs/design/02_Detailed_Design/13_CS_Detailed.md @@ -0,0 +1,165 @@ +--- +doc_id: DT-13-CS +doc_role: module_body +authority: secondary +scope: 详细设计-客户服务 +source_of_truth: false +last_reviewed: 2026-03-11 +retrieval_priority: P1 +--- + +# 福建水务营收系统详细设计-客户服务模块正文 + +## 章节导航（精简） + +- [文档定位](#sec-position) +- [客户服务详细设计正文](#sec-content) + - [CS-001 账户绑定管理](#mod-cs-001) + - [CS-002 信息查询服务](#mod-cs-002) + - [CS-003 在线缴费服务](#mod-cs-003) + - [CS-004 电子发票服务](#mod-cs-004) + - [CS-005 营业网点服务](#mod-cs-005) + - [CS-006 业务办理服务](#mod-cs-006) + - [CS-007 柜面扫码支付](#mod-cs-007) + + + +## 文档定位 + +本文档为 `01_Detailed_Design.md` 中“客户服务模块详细设计”章节的模块正文拆分稿，便于按模块独立维护。正式交付口径以主详设为准。 + + + +# 客户服务模块详细设计 + + + +## CS-001 账户绑定管理 + +### 功能说明 + +面向微信、支付宝、微网厅等渠道实现客户账户绑定、解绑、默认账户设置、多账户切换与身份校验。 + +### 关键规则 + +1. 一个渠道账户可绑定多个用水账户。 +2. 绑定、解绑、默认账户变更等敏感操作需进行身份校验。 +3. 已销户、冻结或限制服务的账户不得新增绑定。 + +### 核心数据 + +- `biz_cust_app_binds` +- `biz_cust` +- `biz_account` + + + +## CS-002 信息查询服务 + +### 功能说明 + +提供账单查询、缴费记录查询、用水分析、欠费查询、账户流水、历史账单等服务。 + +### 关键设计 + +1. 查询范围严格限制在已绑定客户与账户范围内。 +2. 账单、缴费、发票、办理进度等数据通过 SYS-002 标准接口聚合展示。 +3. 常用历史数据支持按最近周期快速查询。 + +### 核心数据 + +- `biz_cust` +- `biz_account` +- `biz_charge` +- `biz_charge_detail` +- `biz_invoice` + + + +## CS-003 在线缴费服务 + +### 功能说明 + +提供微信支付、支付宝支付、银行卡支付、预存款支付等在线缴费能力。 + +### 关键规则 + +1. 下单前再次校验账单未缴状态和应缴金额。 +2. 支付结果以 `SYS-009` 回调/查询确认为准。 +3. 对失败订单支持补单、查询与结果回写。 + +### 核心数据 + +- `biz_charge` +- `biz_charge_detail` +- `bk_transaction` +- `bk_transaction_callback` + + + +## CS-004 电子发票服务 + +### 功能说明 + +在客户渠道中提供电子发票申请、查询、下载以及缴费后发票推送能力。 + +### 关键设计 + +1. 电子发票开具能力经 `SYS-008` 统一提供。 +2. 发票申请与客户开票信息、缴费记录和账单状态联动校验。 +3. 发票结果支持下载、查看和渠道推送。 + +### 核心数据 + +- `biz_invoice` +- `biz_cust_invoice` +- `biz_invoice_taxrate` + + + +## CS-005 营业网点服务 + +### 功能说明 + +提供营业网点查询、服务范围查看、办事指引与营业时间展示能力。 + +### 关键设计 + +1. 网点信息展示地址、联系电话、营业时间与可办理业务范围。 +2. 网点服务以查询与引导为主，不在本模块中虚构额外业务实体表。 +3. 与 CS-006 业务办理服务协同，支持从网点查询跳转到线上办理。 + + + +## CS-006 业务办理服务 + +### 功能说明 + +提供更名、过户、联系方式变更、开票方式变更、一户多人口、自主抄表、换表申请等线上业务办理入口。 + +### 关键设计 + +1. 业务办理统一调用工单/流程能力，不与后台流程表重复建模。 +2. 办理结果与客户资料、工单状态、报装或表务流程联动更新。 +3. 触达通知通过 `SYS-010` 完成结果通知。 + + + +## CS-007 柜面扫码支付 + +### 功能说明 + +支持营业厅柜台二维码收款、票据关联、结果回传，是柜台收费场景对线上支付能力的补充入口。 + +### 关键设计 + +1. 柜面扫码支付与 REV-003 营业收费统一核销口径。 +2. 支付结果与交易流水经 `SYS-009` 回传后更新收费状态。 +3. 支持支付凭证、发票申请与收费记录联动。 + +### 核心数据 + +- `biz_charge` +- `bk_transaction` +- `bk_transaction_callback` + diff --git a/docs/design/02_Detailed_Design/14_METER_Detailed.md b/docs/design/02_Detailed_Design/14_METER_Detailed.md new file mode 100644 index 0000000..c9275c8 --- /dev/null +++ b/docs/design/02_Detailed_Design/14_METER_Detailed.md @@ -0,0 +1,95 @@ +--- +doc_id: DT-14-METER +doc_role: module_body +authority: secondary +scope: 详细设计-表务管理 +source_of_truth: false +last_reviewed: 2026-03-11 +retrieval_priority: P1 +--- + +# 福建水务营收系统详细设计-表务模块正文 + +## 章节导航（精简） + +- [文档定位](#sec-position) +- [表务详细设计正文](#sec-content) + - [METER-001 表务基础管理](#mod-meter-001) + - [METER-002 表务工单管理](#mod-meter-002) + - [METER-003 仓储与生命周期管理](#mod-meter-003) + - [METER-004 物联网接入与数据同步](#mod-meter-004) + + + +## 文档定位 + +本文档为 `01_Detailed_Design.md` 中“表务详细设计”章节的模块正文拆分稿，便于按模块独立维护。正式交付口径以主详设为准。 + + + +# 表务详细设计 + + + +## METER-001 表务基础管理 + +### 功能说明 + +管理水表档案、厂家、型号、口径、量程、检定证书、安装位置、当前状态等基础信息。 + +### 关键设计 + +- 一块水表对应唯一档案主记录。 +- 设备状态覆盖在库、在用、待检、故障、报废等。 +- 与客户、水表工单、抄表记录形成关联闭环。 + + + +## METER-002 表务工单管理 + +### 功能说明 + +处理换表、移表、拆表、复装、校表、稽查、维修等表务工单。 + +### 关键设计 + +1. 工单类型决定必填字段、处理流程和附件要求。 +2. 换表工单需同时记录旧表拆除信息与新表安装信息。 +3. 表务工单完成后同步更新水表档案与客户绑定关系。 + + + +## METER-003 仓储与生命周期管理 + +### 功能说明 + +管理新表入库、领用、出库、退库、报废及全生命周期追踪。 + +### 核心数据 + +- `water_meter_stock` +- `water_meter_inventory` +- `water_meter_archive` + + + +## METER-004 物联网接入与数据同步 + +### 功能说明 + +接入集抄系统、智能表平台及厂家物联网平台，实现远程抄表、状态查询、设备参数同步与异常告警。 + +### 业务流程 + +```mermaid +flowchart TD + A[定时采集任务] --> B[发送采集请求] + B --> C[物联网平台返回数据] + C --> D[数据校验] + D --> E{是否有效} + E -->|有效| F[写入抄表记录] + E -->|无效| G[异常标记并告警] + F --> H[参与开账] + G --> I[人工复核处理] +``` + diff --git a/docs/design/02_Detailed_Design/15_INST_Detailed.md b/docs/design/02_Detailed_Design/15_INST_Detailed.md new file mode 100644 index 0000000..ed27a2f --- /dev/null +++ b/docs/design/02_Detailed_Design/15_INST_Detailed.md @@ -0,0 +1,159 @@ +--- +doc_id: DT-15-INST +doc_role: module_body +authority: secondary +scope: 详细设计-报装与签章 +source_of_truth: false +last_reviewed: 2026-03-11 +retrieval_priority: P1 +--- + +# 福建水务营收系统详细设计-报装与签章模块正文 + +## 章节导航（精简） + +- [文档定位](#sec-position) +- [报装与签章详细设计正文](#sec-content) + - [INST-001 报装申请与受理](#mod-inst-001) + - [INST-002 现场踏勘与方案设计](#mod-inst-002) + - [INST-003 施工验收与立户通水](#mod-inst-003) + - [INST-004 合同签署与电子签章](#mod-inst-004) + - [INST-005 档案归档与过程留痕](#mod-inst-005) + + + +## 文档定位 + +本文档为 `01_Detailed_Design.md` 中“报装与签章详细设计”章节的模块正文拆分稿，便于按模块独立维护。正式交付口径以主详设为准。 + + + +# 报装与签章详细设计 + + + +## INST-001 报装申请与受理 + +### 功能说明 + +支持新装、改造、一户一表等业务的申请受理、资料提交、受理审核与流程发起。 + +### 关键设计 + +- 统一采集申请人、地址、产权、用水性质、附件材料等信息。 +- 支持政务平台、柜台、微网厅等多入口申请。 +- 受理后自动生成报装编号并进入踏勘流程。 + + + +## INST-002 现场踏勘与方案设计 + +### 功能说明 + +组织现场勘查、工程条件确认、材料测算、施工方案与费用方案编制。 + +### 关键设计 + +1. 踏勘记录包括现场照片、供水接入条件、施工难点、估算费用。 +2. 方案版本化管理，支持设计审核与退回修改。 +3. 勘查结果直接驱动合同金额与施工计划。 + + + +## INST-003 施工验收与立户通水 + +### 功能说明 + +完成施工派工、安装实施、竣工验收、立户建档和通水确认。 + +### 关键设计 + +- 施工节点按派工、实施、验收、归档逐步留痕。 +- 验收通过后自动触发客户建档、水表绑定和账户初始化。 +- 与表务系统共享水表安装与换表数据。 + + + +## INST-004 合同签署与电子签章 + +### 功能说明 + +通过集成泛微 CA 电子签章系统，实现报装合同、用水协议等文件的电子签署、时间戳和电子存证。 + +### 集成架构 + +```mermaid +graph TD + subgraph INST[报装业务系统] + A[申请受理] + B[合同管理] + C[电子签章模块] + D[档案归档] + end + + subgraph CA[泛微CA电子签章系统] + E[身份认证服务] + F[电子签章服务] + G[时间戳服务] + H[电子存证服务] + end + + A --> B + B --> C + C --> E + C --> F + C --> G + C --> H + C --> D +``` + +### 合同签署流程 + +```mermaid +sequenceDiagram + participant 客户 + participant 报装系统 + participant 电子签章模块 + participant 泛微CA系统 + + 客户->>报装系统: 提交签署申请 + 报装系统->>电子签章模块: 生成签署任务 + 电子签章模块->>泛微CA系统: 发起身份认证 + 泛微CA系统-->>电子签章模块: 返回认证结果 + 电子签章模块->>泛微CA系统: 发起电子签章 + 泛微CA系统-->>电子签章模块: 返回签章结果 + 电子签章模块->>泛微CA系统: 申请时间戳与存证 + 泛微CA系统-->>电子签章模块: 返回凭证 + 电子签章模块-->>报装系统: 返回签署结果 + 报装系统-->>客户: 通知合同签署完成 +``` + +### 核心数据 + +| 数据对象 | 说明 | +|---|---| +| `installation_contract` | 报装合同主表 | +| `installation_signature` | 电子签章记录表 | +| `installation_evidence` | 电子存证记录表 | + +### 关键规则 + +1. 合同签署前必须完成身份认证。 +2. 合同正文、签署位置、签署人、签署时间必须完整留痕。 +3. 签署完成文件必须归档并生成可验证凭证。 +4. 外部 CA 接口异常时应支持重试与人工补偿处理。 + + + +## INST-005 档案归档与过程留痕 + +### 功能说明 + +归集申请材料、设计方案、合同文件、验收资料、签章回执和过程日志，形成完整报装档案。 + +### 关键设计 + +- 档案按申请单维度统一归档。 +- 电子签章合同、验收附件、影像资料统一存储。 +- 档案查询支持按申请编号、客户、地址、时间、状态检索。 + diff --git a/docs/design/02_Detailed_Design/README.md b/docs/design/02_Detailed_Design/README.md index 4f2dbfa..846dc82 100644 --- a/docs/design/02_Detailed_Design/README.md +++ b/docs/design/02_Detailed_Design/README.md @@ -12,6 +12,11 @@ - `02_Module_Traceability_Index.md`：模块追溯索引（模块-接口-数据域快速定位） - `03_CA_Esignature_Supplement.md`：报装 CA 电子签章专项补充 +- `11_UP_Detailed.md`：统一平台模块正文 +- `12_REV_Detailed.md`：营收业务模块正文 +- `13_CS_Detailed.md`：客户服务模块正文 +- `14_METER_Detailed.md`：表务模块正文 +- `15_INST_Detailed.md`：报装与签章模块正文 ## 维护原则 diff --git a/scripts/unified_export.sh b/scripts/unified_export.sh index 6dbb55f..74bffb4 100755 --- a/scripts/unified_export.sh +++ b/scripts/unified_export.sh @@ -620,6 +620,21 @@ process_single_document() { "03_CA_Esignature_Supplement") doc_title="福建水务营收系统-报装CA电子签章补充" ;; + "11_UP_Detailed") + doc_title="福建水务营收系统-统一平台模块正文" + ;; + "12_REV_Detailed") + doc_title="福建水务营收系统-营收业务模块正文" + ;; + "13_CS_Detailed") + doc_title="福建水务营收系统-客户服务模块正文" + ;; + "14_METER_Detailed") + doc_title="福建水务营收系统-表务模块正文" + ;; + "15_INST_Detailed") + doc_title="福建水务营收系统-报装与签章模块正文" + ;; *) doc_title="福建水务营收系统-$doc_name" ;; @@ -674,6 +689,11 @@ main() { "docs/design/02_Detailed_Design/01_Detailed_Design.md" "docs/design/02_Detailed_Design/02_Module_Traceability_Index.md" "docs/design/02_Detailed_Design/03_CA_Esignature_Supplement.md" + "docs/design/02_Detailed_Design/11_UP_Detailed.md" + "docs/design/02_Detailed_Design/12_REV_Detailed.md" + "docs/design/02_Detailed_Design/13_CS_Detailed.md" + "docs/design/02_Detailed_Design/14_METER_Detailed.md" + "docs/design/02_Detailed_Design/15_INST_Detailed.md" "docs/design/03_Technical_Design/01_Database_Design.md" "docs/design/03_Technical_Design/02_Table_Specs.md" "docs/design/03_Technical_Design/03_Interface_Design.md"