# 复欣物业「一屋一表」数字化台账系统 — 开发接入清单

> 配套文件：`ledger_schema.sql`（数据库脚本）、`ledger_seed.json`（演示数据）、`一屋一表台账系统-后台原型.html`（可交互原型）
> 本清单是对需求文档的**技术落地补充**，与需求文档冲突时以需求文档为准；需求文档未明确的技术细节，以本清单为准。

---

## 0. 一句话结论

台账模块**做在管理后台**，三张业务表（baoxiu / tousu / gongdan）**存在则复用、不存在则按本文档字段建**；
**真正新增的表只有 1 张**：`building`（楼栋基本情况说明书）＋ 2 张规则表；
一屋一表（house）**只补字段不重建**；管理后台对一屋一表**只读**，绝不修改收费数据。

---

## 1. 开发前必须先确认的 5 件事（不定就没法开工）

| # | 确认项 | 结论 / 处理方式 |
|---|---|---|
| 1 | 现有报修表**有没有「房号」字段**？ | 有 → 确认字段名是 `room` 还是门牌地址字符串；没有 → 新增 `building`/`unit`/`room` 三列，历史数据补录一次（清洗脚本见 §4） |
| 2 | **房号格式是否统一**？ | 必须统一成四段式 `project_name + building + unit + room`（例：`中建桂苑 / 1栋 / 1单元 / 501`）。旧数据需跑一次清洗，否则关联必挂 |
| 3 | 管理后台与收费系统**是否同库**？ | 同库（推荐）→ 直接查一屋一表，零成本；异库 → 收费系统出**只读接口**，或每日定时同步房屋数据。无论如何**台账侧只读** |
| 4 | 现有表名与字段结构要提供给台账模块 | 提供 `baoxiu`/`tousu`/`gongdan` 实际表名与字段清单；缺的列用 `ALTER` 补齐，**不新建重复表** |
| 5 | KPI 是否已有独立数据源？ | 已有 → 台账直接读取，不重复计算；没有 → 按 §6 口径从 `gongdan` 表统计，落 `v_kpi_person_month` 视图 |

---

## 2. 新增 vs 复用 vs 改造（严格按此执行）

**新增开发**
- `building` 表 + 后台「每栋一份说明书」页
- 一屋一表每户「历史报单」标签（读 `v_house_ledger` 视图）
- KPI 统计报表模块（读 `v_kpi_person_month` 视图）
- 月度 / 年度报表导出

**复用（不许重做）**
- 一屋一表房屋档案
- 业主报单报修录入与处理闭环（接单/分派/处理/关闭）
- KPI 已有部分，读取即可

**改造（只做关联，不改原有业务逻辑）**
- 已有报修表：确认 / 补齐房号字段
- 一屋一表房屋页：嵌入历史报单查询
- 报表导出：读取已有报修与 KPI 数据

---

## 3. 数据库变更清单

详见 `ledger_schema.sql`，要点：

| 对象 | 类型 | 说明 |
|---|---|---|
| `building` | **新建表** | 楼栋基本情况说明书，唯一键 `(project_name, building_no)` |
| `rule_dept_map` | **新建表** | 类别→部门自动推荐映射，管理员可配，不写死代码 |
| `rule_timeout` | **新建表** | 超时阈值：紧急 4h / 一般 24h / 不紧急 48h |
| `baoxiu` / `tousu` / `gongdan` | 复用（`CREATE TABLE IF NOT EXISTS` 保护） | 已存在则**绝不覆盖** |
| `house` | 补字段 | `payment_status`、`occupancy_status`、`vehicle_info`、`relation` 四列，缺哪个补哪个 |
| `v_house_ledger` | 新建视图 | 按户归集历史报单（Union 三来源） |
| `v_month_summary` | 新建视图 | 月度汇总，报表导出直接读 |
| `v_kpi_person_month` | 新建视图 | KPI 指标口径固化 |

**索引（必建）**：`(project_name, building, unit, room)`、`(month)`、`(status, dept)`、`(dept, handler, status)`。

---

## 4. 房号格式统一（最关键的一环）

统一格式：`project_name + building + unit + room`

```
示例：中建桂苑 | 1栋 | 1单元 | 501
存储：building='1栋'  unit='1单元'  room='501'
展示：1栋1单元501
```

历史数据清洗参考（伪 SQL，字段名按现表调整）：

```sql
-- 1) 找出无法拆分的脏数据，人工处理后再继续
SELECT DISTINCT room FROM baoxiu WHERE room NOT LIKE '%栋%' AND room LIKE '%-%';

-- 2) 统一去除空格与全角符号
UPDATE baoxiu SET building = REPLACE(REPLACE(building,' ',''),'＃','#');

-- 3) 关联孤儿房号（无对应一屋一表记录的单子，必须清零才能上线）
SELECT COUNT(*) FROM gongdan g
  LEFT JOIN house h ON g.project_name=h.project_name AND g.building=h.building_no
                   AND g.unit=h.unit AND g.room=h.room
  WHERE h.id IS NULL;
```

---

## 5. 单号生成规则

| 单据 | 规则 | 示例 |
|---|---|---|
| 报修单 | `BX + YYYYMM + 4位序号` | `BX2026100001` |
| 投诉单 | `TS + YYYYMM + 4位序号` | `TS2026100007` |
| 工单 | `GD + YYYYMM + 4位序号` | `GD2026100001` |

序号按**当月流水**，每月重置。并发场景用数据库事务 + `INSERT ... SELECT COUNT(*)+1` 或独立序列表，**不要**用内存自增。

---

## 6. KPI 统计口径（写死在视图里，避免各做各的）

| 指标 | 计算方式 | 字段来源 |
|---|---|---|
| 处理工单总数 | `COUNT(status IN ('已完成','已关闭'))` | `gongdan.status` |
| 平均响应时间 | `AVG(accept_time − work_date)` | `gongdan` |
| 平均处理时效 | `AVG(finish_time − accept_time)` | `gongdan` |
| 超时未处理数 | `COUNT(status='超时未处理' OR overtime=1)` | `gongdan` |
| 超时率 | 超时工单数 ÷ 总工单数 | 派生 |
| 业主满意度 | `满意数 ÷ (满意+一般+不满意)`，并输出分布 | `baoxiu/tousu.satisfaction` |
| 部门处理量对比 | `GROUP BY dept` | `gongdan.dept` |

**考核主体**：`gongdan.handler`（处理人），不是录入人。

---

## 7. 超时判定守护任务

```python
# 每 10 分钟跑一次（crontab 或 APScheduler）
def check_overtime():
    rows = db.query("""
        SELECT g.*, r.hours_limit FROM gongdan g
        JOIN rule_timeout r ON r.urgency = g.urgency
        WHERE g.status IN ('待接单','处理中')
    """)
    for g in rows:
        used = (now() - g.work_date).total_seconds() / 3600
        if used > g.hours_limit:
            update(gongdan).set(status='超时未处理', overtime=1)
            # 同步回写来源单，并向项目经理推送督办提醒
```

超时工单在项目经理看板**自动置顶标红**，督办操作写入 `remark` 留痕。

---

## 8. 权限矩阵

| 角色 | 可见范围 | 可操作 | 报表 / KPI |
|---|---|---|---|
| 系统管理员 | 全部 | 全部，含用户与规则配置 | ✅ |
| 项目经理 | 本项目全部部门 | 督办、分派、导出 | ✅ |
| 客服 | 全部工单 | 代录报单、接单分派、回访关闭（仅处理客服类） | ✅ |
| 保洁 / 保安 / 工程 | **仅本部门工单** | 认领、填结果与照片；**不可分派、不可导出** | 仅个人 KPI |

实现要点：后台接口层做部门过滤，不能只靠前端隐藏。

---

## 9. 报表导出

- **月度**：选 `month` → 报修明细 + 投诉明细 + 工单明细 + 部门汇总 + KPI
- **年度**：选 `year` → 全年汇总 + 按月分布 + 各部门处理量
- **自动归档**：每月 1 号生成上月报表并存档，同时支持手动导任意年月
- 导出格式与飞书《物业一屋一表数字化台账模板》一致：**首页汇总 + 明细页**
- 批量推送若涉及对外发送，须遵循微信订阅消息授权规则（本项目业主端不开小程序，后台操作无此风险）

---

## 10. 验收清单（10 条，逐条勾选上线）

- [ ] 1. 三张业务表与一屋一表通过房号关联正常，孤儿房号为 0
- [ ] 2. 客服可完成代录全流程：选房号自动带出业主 → 填内容 → 提交 → 自动生成工单
- [ ] 3. 报单来源可记录（微信群 / 电话 / 前台），微信群图片可上传
- [ ] 4. 报修 / 投诉 / 工单可完成「代录→接单→分派→处理→关闭」全流程
- [ ] 5. 一屋一表每户档案可查看该户全部历史报单
- [ ] 6. 五部门权限隔离成立，项目经理可见全部
- [ ] 7. 工单看板四 Tab 展示，超时自动标红，可用于早会
- [ ] 8. KPI 可按人 / 部门 / 月自动算出五项指标并可导出
- [ ] 9. 任选年月可导月报、任选年份可导年报，数据与明细一致
- [ ] 10. 现有收费功能不受影响，两模块数据互通但不互相干扰

---

## 11. 排期建议

| 阶段 | 周期 | 内容 | 交付物 |
|---|---|---|---|
| 第一期 | 第 1-2 周 | 数据库建表与补字段、一屋一表历史报单标签、客服代录报单、报修/投诉/工单页面 | 后台台账核心可试用 |
| 第二期 | 第 3 周 | 五部门权限隔离、工单看板、超时提醒、月度/年度报表导出 | 协同 + 报表上线 |
| 第三期 | 第 4 周 | KPI 统计报表、Excel 台账数据迁移、测试上线 | 全功能正式上线 |
"\n\n---\n\n## 12. 与「收费系统一屋一表」的联动方案（已实测落地）\n\n> 本节基于 2026-10-04 对生产服务器的实勘结果，是**联动部分的唯一事实来源**，开发直接照此实施。\n\n### 12.1 真实数据源位置\n\n| 项 | 值 |\n|---|---|\n| 数据库 | SQLite `/root/backend/property.db`（主后端，**与 8000 端口后端同一文件**） |\n| 核心表 | `house_archive` —— 一屋一表主档，**现有 1844 户 / 45 栋 / 3 个项目** |\n| 项目表 | `projects`（位于同一库，`id` 与 `house_archive.project_id` 一对一） |\n| 后端代码 | `/root/backend/app/house_archive.py` |\n| 只读接口 | `GET /api/v1/house-archive/houses`，支持 `project_id / building / room / owner_name / status` 筛选 + `page/size` 分页 |\n\n### 12.2 house_archive 现有字段\n\n`house_id, project_id, building, unit, room, area, layout, owner_name, owner_id_no, owner_phone, property_remark, fee_code, status, house_photos, house_code, created_at, updated_at`\n\n**缺失字段（对应需求文档 4.4，需 ALTER 补齐，不在本次改动范围）**：\n`payment_status`（缴费状态）、`occupancy_status`（入住状态）、`vehicle_info`（车辆信息）、`relation`（与业主关系）。\n当前导出时这三项标记为「待补」。\n\n### 12.3 为什么\"直接调 API\"这条路走不通（重要）\n\n| 事实 | 说明 |\n|---|---|\n| AI 管控后台 ≠ 主后端 | 后台 API 基址是 `/ai-api/` → `127.0.0.1:8094`（property-ai）；一屋一表接口在 `/api/v1/` → `127.0.0.1:8000`（主后端） |\n| 两套 JWT 不通用 | 8094 签发的 token 调 8000 返回 `401 无效凭据`（实测确认） |\n| 8094 无 house-archive 端点 | 实测 `HTTP 404` |\n| 两侧项目 ID 是两套 | 8094 `/api/v1/projects` 返回 16 个项目的 UUID，与 `house_archive.project_id` 体系不同；后者对应同一 SQLite 库里的 `projects.id` |\n\n**结论**：正式版必须在主后端侧【新增】一个只读、纳入 AI 后台鉴权体系的房屋查询接口，或在 8094 增加一个转发到 8000 的服务间调用（使用 `.env` 中已有的 `AI_SYSTEM_SECRET_KEY`）。**在现有 JWT 打通之前，前端无法直接跨域调通。**\n\n### 12.4 原型期采用的过渡方案（零侵入）\n\n1. 部署**只读同步器** `/opt/fuxin-ledger/sync/export_houses.py`\n   - 以 SQLite 只读模式（`file:...?mode=ro`）打开 `property.db`，绝不写入\n   - JOIN `projects` 取项目名，输出 `/opt/fuxin-ledger/web/data/houses.json`\n   - 默认输出**脱敏版**（业主姓名留姓、电话中段打码）；`--full` 才输出完整版\n2. crontab 每小时第 17 分钟自动同步一次（**追加**在现有任务之后，未改动任何既有定时任务）\n3. 台账页面启动时 `fetch('data/houses.json')` 覆盖内置演示数据；拉取失败自动回退演示数据，页面永远可用\n4. 页面顶部有数据源状态条：绿色「● 已联动 …」/ 橙色「○ 未联动 …」\n\n### 12.5 过渡到正式版的三个必须动作\n\n- [ ] 打通 8094 ↔ 8000 的鉴权（新增内部服务凭证，不要放宽现有 JWT）\n- [ ] `houses.json` 含全量房号，**公网当前可直读** —— 正式版必须改为带鉴权接口下发，不得留静态文件\n- [ ] 按 4.4 补齐 `payment_status / occupancy_status / vehicle_info / relation` 四个字段\n"