# 仪陇表务管理系统 — 总体框架设计 V1.0

> 依据：`../demand/` 下 PRD-01/02/03、产品功能清单、PRD-04 功能需求说明。  
> 后端约束：`PROJECT_SKILL.md`、`java6/java-ylsw-bw.md`（Oracle 11、`com.tofly.wm`、BaseEntity、`Boolean deleted`、Entry 列映射见 java6 §值对象）。

## 1. 建设目标与边界

- **目标**：水表全生命周期数字化（采购→检定→仓储→安装→运行→检定/检查→退库/报废），Web 管控 + 移动外勤 + 内部系统集成。
- **原则**：「**申请走工单、执行可直办**」——带「申请」的能力挂 workflow；任务派单、计划维护、业务登记支持授权直办，工单通过后亦可自动生成下游任务/登记。
- **边界**：不含财务收费、GIS 绘制、硬件运维、客服工单；对接报装/营销/抄表/采购（及检定测量系统）。

## 2. 逻辑架构

```text
┌─────────────────────────────────────────────────────────────┐
│  Web 管理端（配置/审批/台账/统计）  │  移动端（外勤任务执行）   │
└───────────────┬─────────────────────────────┬───────────────┘
                │                             │
        ┌───────▼─────────────────────────────▼───────┐
        │     business/water-meter（表务微服务）         │
        │  com.tofly.wm：manage / ledger / workorder    │
        └───────┬─────────────────────┬───────────────┘
                │                     │
     ┌──────────▼──────────┐   ┌──────▼──────┐
     │ workflow 审批引擎    │   │ 平台公共服务  │
     │（工单中心 UI 复用）   │   │ 组织/用户/附件│
     └──────────┬──────────┘   └─────────────┘
                │
     ┌──────────▼──────────────────────────────────┐
     │ Oracle 11：wssmet_* 业务表（审批走 workflow）  │
     └───────────────────────────────────────────────┘
```

## 3. 后端包结构

根包 **`com.tofly.wm`**（模块 `business/water-meter`）：

| 包 | 职责 | 典型内容 |
|----|------|----------|
| `cons` | 模块常量 | `MeterConstant` 字典目录码、流水号类型 |
| `manage` | 写操作、主数据、流程业务 | 采购、领取、调拨、检定、任务、配置 |
| `ledger` | 只读台账、汇总、导出 | 水表/采购/检定/入出库台账 |
| `workorder` | 工单 UI 聚合（可选） | 委托 workflow API，**不映射本地工单表** |
| `api` | 对外/第三方接口 | 检定记录同步等 |

单域内**平铺** Controller/Service/Entity/Mapper/Query/Vo；枚举放 `{domain}/enums/`；明细子表放 `list` 等子包。

## 4. 数据与持久化约定

> **仅依据 PRD + `database-design.mdc` + `java6/java-ylsw-bw.md`**；不参照存量 `wssmet_*` 表与既有实体。

- **表名**：`wssmet_{x2}_w`（x1=`wssmet`，供水表务）；主键 `id NUMBER(19)`（雪花）。
- **公共列**：每张业务表 `CREATE TABLE` 内含 BaseEntity 扩展列（见 [数据库设计-V1.0.md](./数据库设计-V1.0.md) §2）。
- **逻辑删除**：`deleted NUMBER(1)` ↔ Java **`Boolean deleted`**。
- **字典**：库表 `*_code VARCHAR2` ↔ Java **`DictEntry`** + `@DictDirectory`；COMMENT 标明 **字典类型**与目录码。
- **枚举**：库表 `*_status` / `*_status_code` 等 ↔ Java **业务枚举**；COMMENT 标明 **枚举类型**与枚举类名。
- **组织/用户**：库表 `*_id NUMBER(19)` ↔ Java **`OrganizationEntry`** / **`UserNameEntry`**；关联列 COMMENT 写明目标表（如 `tf_user.id`）。
- **附件**：**无库列**；Java **`FileEntryList`** / **`FileEntry`** + `@TableField(exist = false)`，走平台文件服务。
- **字典/枚举清单**：按表见 [数据库设计-V1.0.md](./数据库设计-V1.0.md) **§2.1**（仅字典、枚举列）。
- **水表主数据**：`wssmet_meter_w`；生命周期 `wssmet_meterlife_w`；入出库 `wssmet_invin_w` / `wssmet_invout_w` 及明细表。

完整 DDL 见 [数据库设计-V1.0.md](./数据库设计-V1.0.md)。

## 5. 工单外挂模式（PRD-04-01，无本地工单表）

### 5.1 申请主表审批字段（业务库）

| 列 | 说明 |
|----|------|
| process_instance_id | workflow 流程实例 ID |
| work_order_code | 工单编号（列表/台账展示） |
| approve_status | 审批状态，与流程引擎同步 |
| apply_code 等 | 业务单号、申请人/部门等业务字段（各模块 PRD） |

工单待办/已办/流程配置 **不落表务库**，由 **workflow** 提供（PRD：复用 workflow 组件）。

### 5.2 申请类业务保存模式（设计期）

1. 生成业务单号，写入申请主表 + 明细（`wssmet_*apply*_w`）。
2. 调用 workflow **发起流程**，回写 `process_instance_id`、`work_order_code`、`approve_status=pending`。
3. 用户在工单中心办理；**通过后**更新 `approve_status` 与业务 `process_status_code`，并按 PRD 触发下游（计划、任务、出入库等）。

### 5.3 工单类型与业务表映射

| TYPE（建议） | 业务表 | 模块 |
|--------------|--------|------|
| PURCHASE_APPLY | wssmet_purapply_w | 采购申请 |
| CLAIM_APPLY | wssmet_claimapply_w | 领用申请 |
| TRANSFER_APPLY | wssmet_transferapply_w | 调拨申请 |
| REPLACE_APPLY | wssmet_replaceapply_w | 换表申请 |
| DISPUTE_VERIFY_APPLY | wssmet_disverifyapply_w | 争议检定申请 |
| RELOCATE_APPLY | wssmet_relocateapply_w | 迁表申请 |
| REMOVE_APPLY | wssmet_removeapply_w | 拆表申请 |
| RETURN_STATION_APPLY | wssmet_retstnapply_w | 营业所退库 |
| RETURN_HQ_APPLY | wssmet_rethqapply_w | 退回总仓 |
| SCRAP_APPLY | wssmet_scrapapply_w | 报废申请 |

任务类（安装/换表/检定/轮换/周期检查等）**不挂审批流程表**，使用 `wssmet_*task*_w` + App `wssmet_*rec*_w`。

## 6. 接口与返回约定

- 统一 **`ResultResponse<T>`**（带泛型）。
- Controller：`GET /page`、`GET /list`（同 Query）、`GET /{id}`、`POST /`、`POST /update`、`DELETE /deleteByIds`（**禁止** `DELETE /{id}`）；台账 `GET /export`。接口文档须按 `java6` 模板 **全量列出** 路径。
- 分页：`PageQuery` + `PageHelper.startPage`；单表 `Wrappers.lambdaQuery`；多表台账 `MPJWrappers.lambdaJoin`。
- 详见 [接口文档-V1.0.md](./接口文档-V1.0.md)。

## 7. 组织与数据权限（摘要）

- RBAC：菜单权限 + 数据权限（组织管辖）+ 工单节点岗位权限。
- 上级可查下级；工单待办/已办按本人与岗位匹配。
- 详见 PRD-02。

## 8. 集成接口（摘要）

| 系统 | 方向 | 用途 |
|------|------|------|
| 报装 | 入 | 新装/改址/销户驱动任务 |
| 营销 | 出 | 表号、户档、状态同步（表号变更以营销成功为前提） |
| 抄表 | 出 | 安装信息、设备标识 |
| 检定测量系统 | 入 | `wssmet_verifyrecord_w` 同步，关联落地/到期/争议/其他检定 |
| 采购系统 | 入 | 订单/到货（可选） |

## 9. 文档地图

- 需求文档：`../demand/`（PRD 与功能需求说明）
- 设计文档：本目录 `design/`（框架、库表、接口、功能设计）
- 表结构：[数据库设计-V1.0.md](./数据库设计-V1.0.md)
- 接口：[接口文档-V1.0.md](./接口文档-V1.0.md)
- 分模块：[功能设计/](./功能设计/) 下 01～22