# 三处报单系统 · 联动诊断与整改方案

> 出具日期：2026-10-04
> 诊断方式：直接读服务器生产代码与生产库（只读，未做任何写操作）
> 结论：**设计上已经做了联动，但只接了一半；真正阻断"一屋一表归集"的是房号缺失**

---

## 一、三处报单点名（到底是哪三个）

| # | 入口位置 | 后端服务 | 数据库 / 表 | 现有数据量 | 状态机 |
|---|---|---|---|---|---|
| ① | 客服中心 → 报修管理 / 投诉管理 | 主后端 `127.0.0.1:8000`（/root/backend） | SQLite `property.db` → `repairs` / `complaints` | 报修 17 条 | 4 态：pending / processing / completed / closed |
| ② | 项目管理 → 进入工作台 → 报单 | AI 管控 `127.0.0.1:8094`（/root/property-ai） | PostgreSQL 5434 `property_ai` → `ai_work_order` + `ai_work_order_log` | **51 条** | 6 态：pending / acknowledged / processing / rectifying / verifying / closed |
| ③ | /ledger/ 一屋一表台账 | 无后端（本次新增） | 原为演示数据，**本次已改为只读同步 ② 的真实工单** | 51 条（同步） | 只读展示 ② 的 6 态 |

**② 是最详细的那个**：字段含 `before_photos`（施工前照片）、`after_photos`（施工后）、`rectify_photos` / `rectify_note`（整改）、`visit_at` / `visit_note` / `visited_by` / `satisfaction_rating`（回访与满意度）、`sla_response_minutes` / `sla_resolve_minutes`（时效阈值）、`ai_analysis` / `ai_suggestion`（AI 分析）。
你说"完工施工前验收这些都已经非常详细"——就是它。

---

## 二、现有联动链路实测（哪些接了，哪些断了）

| 方向 | 代码位置 | 实测状态 |
|---|---|---|
| ① → ② 创建 | `app/api/repair.py:120` → `push_repair_to_ai()` | ✅ **已接通**（17 条报修中 11 条已写入 `ai_workorder_id`） |
| ① → ② 状态回传 | `app/services/property_ai_client.py:308` `sync_repair_status_to_ai()` | ❌ **函数写了，全仓搜索无任何调用点** —— 客服中心改状态，AI 侧不知道 |
| ② → ① 状态回写 | `app/services/miniapp_callback.py` → `POST /api/v1/ai-webhook/workorder-callback` | ⚠️ **接了但只对"有主"的工单生效**：仅当 `miniapp_repair_id` / `miniapp_complaint_id` 非空才回调，**31/51 条无此字段，永远不同步** |
| ① → ② 满意度 | `repair.py:286` → `push_satisfaction_to_ai()` | ✅ 已接通 |
| ② → ① 兜底查询 | `repair.py` 内 `from_ai: True` 分支（查不到 SQLite 就回查 PG） | ✅ 只读兜底，单向 |
| ③ ↔ ①② | 无 | ❌ 本次之前完全断开，**现已改为只读同步，不回写** |

### 孤儿工单是怎么产生的
`ai_work_order.source` 实测分布：微信群 27、小程序 20、电话客服 2、巡场发现 2。
在 AI 管控侧直接建的（微信群、巡场发现）**不会带 `miniapp_repair_id`** → 回调不触发 → 客服中心和业主小程序都看不到这批单，形成信息孤岛。实测 **31 条（60.8%）**。

---

## 三、哪里不准确（5 个真问题，按严重度排）

### ★★★★★ 1. 报单没有结构化房号 —— 这是根本阻断项
- `repairs` / `complaints` 表：**无** `building` / `unit` / `room` 字段
- `ai_work_order` 表：**无** 房号字段，只有一个自由文本 `location varchar(200)`

`location` 实测值是自由文本，格式完全不统一：

```
"16栋后面护坡树叶堆积，存在安全隐患"   ← 把描述写进位置了
"银桂地库左边入口位置"                 ← 公共区域，无法归户
"12-101后面"                          ← 非标准写法
"4A一楼公区"                           ← 带字母栋号
"3"                                    ← 就一个数字
"1栋北门出口" / "13栋102" / "10-1504"
(空)                                   ← 14 条为空
```

**后果**（都是需求文档里明确要的，但目前做不到）：
- 台账 6.3.1「录单时必须从一屋一表选房号」—— 无从选起
- 「按户归集历史报单」—— 归不了
- 「哪栋楼问题多、哪户反复报单」—— 统计不出来
- KPI 与报表按 `building+unit+room` 汇总 —— 无字段可 GROUP BY

**量化**：51 条工单中，正则解析后
- 完整房号（栋+房）：**13 条（25.5%）**
- 仅栋/单元：**9 条**
- 完全解析不出：**29 条（56.9%）**

### ★★★★ 2. 状态机不一致，映射有损
AI 6 态 → 小程序 4 态，映射表在 `ai_webhook.py`：

| AI 状态 | 映射为 | 问题 |
|---|---|---|
| `verifying` 待验收 | `completed` 已完成 | ⚠️ **还没验收就告诉业主"已完成"** |
| `rectifying` 整改中 | `processing` 处理中 | 整改中与处理中混为一谈 |
| `acknowledged` 已接单 | `processing` 处理中 | 接单即算处理，响应时效被吃掉 |

### ★★★★ 3. 需求文档里的三张表在生产库根本不存在
文档 4.1/4.2/4.3 要求建 `baoxiu` / `tousu` / `gongdan` 三表。
实测生产库：**三张都不存在**。真实承载的是 `repairs` / `complaints` / `ai_work_order`。
→ **不要新建这三张表**（会变成第四套数据），应直接复用现有表。

### ★★★ 4. 60.8% 工单是孤儿，跨系统互不可见
见上文。客服中心看不到 AI 侧自建的单，AI 侧也看不到只走客服中心的单。

### ★★ 5. 台账此前是演示数据，与实际脱节
本次已修复为只读同步真实工单。

---

## 四、整改方案（分两阶段，严格"只加不减"）

### 阶段一：补齐房号（必须先做，否则后面都无从谈起）

**原则：只 ALTER 加列，不改现有列、不删数据、不改现有业务逻辑。**

```sql
-- ===== PostgreSQL 5434 / property_ai =====
ALTER TABLE ai_work_order ADD COLUMN IF NOT EXISTS building VARCHAR(20);
ALTER TABLE ai_work_order ADD COLUMN IF NOT EXISTS unit     VARCHAR(20);
ALTER TABLE ai_work_order ADD COLUMN IF NOT EXISTS room     VARCHAR(20);
ALTER TABLE ai_work_order ADD COLUMN IF NOT EXISTS house_archive_id INTEGER;  -- 关联一屋一表主键
CREATE INDEX IF NOT EXISTS ix_ai_wo_room ON ai_work_order(project_id, building, unit, room);

-- ===== SQLite /root/backend/property.db =====
ALTER TABLE repairs    ADD COLUMN building VARCHAR(20);
ALTER TABLE repairs    ADD COLUMN unit     VARCHAR(20);
ALTER TABLE repairs    ADD COLUMN room     VARCHAR(20);
ALTER TABLE complaints ADD COLUMN building VARCHAR(20);
ALTER TABLE complaints ADD COLUMN unit     VARCHAR(20);
ALTER TABLE complaints ADD COLUMN room     VARCHAR(20);
CREATE INDEX IF NOT EXISTS ix_repairs_room ON repairs(project_id, building, unit, room);
```

**房号规则（必须全系统统一，否则关联不上）**：四段式
`项目名 + 栋 + 单元 + 房号`，样例 `中建桂苑 / 16栋 / 2单元 / 1504`
栋号统一带"栋"字、单元带"单元"、房号纯数字，与 `house_archive` 现有格式对齐。

**历史数据清洗**：29 条解析不出的工单必须人工补录（公共区域单可标记为"公共区域"，不强制归户）。
上线前置校验（结果必须为 0）：
```sql
SELECT COUNT(*) FROM ai_work_order
WHERE status <> 'closed' AND (room IS NULL OR room = '');
```

### 阶段二：接通断掉的联动

| 动作 | 位置 | 说明 |
|---|---|---|
| 调用 `sync_repair_status_to_ai` | `repair.py` 状态变更处（handle / dispatch / confirm） | 函数已写好，只差调用，改动面极小 |
| 孤儿单回补 | `workorder.py` 建单处 | AI 侧建单若属业主报单，强制要求选房号并写入 `miniapp_repair_id` |
| 状态映射修正 | `ai_webhook.py` 的 `REPAIR_STATUS_MAP` | `verifying` 不应映射为 `completed`，建议新增"待验收"态或映射为 `processing` |
| 台账定位 | /ledger/ | **只做归集层，只读不写**，不新增第四套数据 |

### 台账的正确定位（不要走偏）
台账**不是第四个报单入口**。它是只读归集视图：
- 数据源①：一屋一表 `house_archive`（1844 户 / 45 栋，已联动）
- 数据源②：`ai_work_order` 真实工单（51 条，已联动）
- 关联键补齐房号后，按户串起历史报单 → 这就是需求文档要的"下次业主再报单，管家能立刻看到历史"

---

## 五、本次已实际完成的动作（零侵入）

| 动作 | 内容 | 侵入性 |
|---|---|---|
| 部署台账 | `/opt/fuxin-ledger/`，软链挂载，**nginx 零改动、零 reload** | 无 |
| 接入一屋一表 | `sync/export_houses.py`，SQLite 只读模式，1844 户 | 只读 |
| 接入真实工单 | `sync/export_orders.py`，psycopg2 只读查询，51 条 | 只读 |
| 定时同步 | crontab 追加两行（17 分同步房屋 / 27 分同步工单），**未动现有任何一行** | 追加 |
| 台账页改造 | 顶部状态条显示联动状态 + 房号缺失数；卡片与抽屉标注"⚠ 待补房号" | 仅 /ledger/ 自身 |

**红线遵守**：现有服务未停未重启、nginx 配置未改一字、现有表未 ALTER、现有数据未增删改。

**回滚**：
```bash
rm -f /usr/share/nginx/html/ledger && rm -rf /opt/fuxin-ledger
crontab -l | grep -v 'export_houses.py\|export_orders.py' | crontab -
```


---

# 七、补充：工区（公共区域）主数据表 —— 2026-10-04 新增

> 起因：物业报单绝大多数发生在**公共区域**（楼道、电梯、地库、门岗、护坡、配电房），
> 不是业主户内。前文把 29 条解析不出房号的全算作"缺失"是错的 ——
> 它们多数本就不属于任何一户，需要一个独立的**工区**坐标来承接。

## 7.1 位置归属改为两套坐标（互斥）

| location_type | 使用字段 | 场景 |
|---|---|---|
| `户内` | `building` + `unit` + `room`（一屋一表四段式） | 业主家里的问题 |
| `公共区域` | `area_id`（工区）+ `building`（工区所属栋） | 某栋的楼道/电梯/大堂 |
| `跨栋公共` | `area_id`（building 留空） | 园区主路、门岗、地库、配电房 |
| `未分类` | — | 历史数据兜底，需人工归档 |

**两套坐标互斥**：`户内` 时 `area_id` 必须为空，反之亦然。已加校验（当前违规 0 条）。

## 7.2 work_area 表核心字段

| 字段 | 说明 |
|---|---|
| `project_name` / `building` | 归属项目 + 标准化栋号（跨栋工区 building 留空） |
| `area_code` | 工区编码，全局唯一，规则 `项目码-栋号-类型码-序号`（如 `ZJGY-16-LT-01`） |
| `area_name` / `area_type` / `area_subtype` | 名称 / 大类 / 细分 |
| `floor` | 楼层：B1/1F/全楼层/屋面 |
| `owner_dept` / `owner_name` | 默认责任部门与责任人 —— **报单自动分派的依据** |
| `patrol_enabled` / `patrol_freq` / `patrol_std` | 是否纳巡检、频次、巡检标准 |

六大类：楼内公区 / 园区公区 / 地下车库 / 设备机房 / 商业配套 / 其他

## 7.3 主数据已生成（254 条）

由 `build_workarea.py` 从真实房档 + 历史报单自动生成：

| 来源 | 条数 |
|---|---|
| 楼内公区（31 栋 × 6：大堂/电梯/楼道/楼梯间/屋面/管道井） | 187 |
| 园区级工区（3 项目 × 16：道路/绿化/门岗/护坡/配电房…） | 45 |
| 历史报单提取（银桂地库左边入口、5号仓、4A一楼公区…） | 20 |
| **合计** | **254** |

栋号同时做了标准化：`第001栋 → 1栋`、`"2" → 2栋`、`杂屋/杂屋栋 → 杂屋栋`
（华欣公寓原本"1栋"与"第001栋"并存、天峰名苑"2"与"2栋"并存，属同栋异名）

## 7.4 实测归类效果（51 条真实工单）

| 归属 | 条数 | 占比 |
|---|---|---|
| 户内 | 10 | 19.6% |
| **公共区域 / 跨栋公共** | **23** | **45.1%** |
| 未分类 | 18 | 35.3% |

对比整改前「房号缺失 29 条（56.9%）」，**工区表让 23 条有了归属**。
剩余 18 条未分类中约 14 条 `location` 原本就是空的，只能人工补。

## 7.5 交付文件

| 文件 | 说明 |
|---|---|
| `work_area_schema.sql` | 建表（PG + SQLite）+ 报单侧 ALTER + 楼栋说明书 + 上线校验 SQL |
| `/ledger/files/work_area_init.sql.txt` | 254 条工区初始化数据（`ON CONFLICT DO NOTHING`，可重复导入） |
| `deploy/build_workarea.py` | 工区主数据生成器（只读，可重跑） |
| `deploy/export_orders.py` | 工单同步器，含 `match_area()` 工区归类 |

## 7.6 台账页面已上线工区维度

- 新增导航「**工区（公共区域）**」：工区台账表（编码/名称/类型/责任部门/巡检频次/**报单量/未完结**）+ 分类统计卡 + 导出
- 代录报单新增「**公共区域 / 户内**」切换，**默认工区**（物业主力场景）
  - 选工区 → 自动带出责任部门与巡检标准
  - 选房号 → 自动带出业主姓名电话（一屋一表）
- 工单卡片与详情按归属显示：户内显示房号、公共区域显示工区名、未归档高亮提示

## 7.7 踩坑记录

- `RE_R1` 原写法会把**单元号误判成房号**（`7栋2单元` → 房号 2）。已加负向预查 `(?!\s*单元)`。
- 两套坐标必须互斥：户内工单不得带 `area_id`，否则台账展示会出现"既是房号又是工区"的歧义。
- 栋号不统一（`第001栋` vs `1栋`）会让工区按栋生成时重复，必须先标准化。
