|
|
@@ -0,0 +1,276 @@
|
|
|
+# 安建医院纪检扫码反馈系统 — 设计规格
|
|
|
+
|
|
|
+**日期：** 2026-09-06
|
|
|
+**状态：** 已评审待实现
|
|
|
+**产品名：** 安徽建工集团医院纪检数字化监督平台 / 安建医院纪检扫码反馈系统
|
|
|
+
|
|
|
+## 1. 背景与目标
|
|
|
+
|
|
|
+安徽建工集团医院纪检室需要一套「扫码反馈」系统：群众微信扫二维码进入移动端 H5 提交投诉/表扬与建言；纪检室通过 Web 管理端查看台账、办理流转并维护热线与二维码配置。
|
|
|
+
|
|
|
+参考工程 `shanxia2.0`（FastAPI + Vue3 Element Plus + uni-app）仅作技术与工程约定参考；业务与视觉以本仓库 `原型图/`、`建设方案/` 为准。
|
|
|
+
|
|
|
+### 1.1 已确认决策
|
|
|
+
|
|
|
+| 项 | 决定 |
|
|
|
+|---|---|
|
|
|
+| 范围 | 按《功能建设清单》核心功能一次可验收（移动端 6 项 + 后台业务 5 项 + 鉴权权限含角色授权 + 附件/台账） |
|
|
|
+| 工程策略 | 同技术栈新建，不拷贝 shanxia 业务模块 |
|
|
|
+| 移动端形态 | uni-app 编译为**微信内 H5**；二维码 → HTTPS 落地页；本期**不上**微信小程序 |
|
|
|
+| 总体架构 | 一后端 + 两端前端；公开 API 与管理 API 分域（方案 A） |
|
|
|
+| 权限 | 角色 ↔ 菜单（`sys_role_menu`）+ 管理端「角色授权」勾选页 |
|
|
|
+| 租户 | 单院部署；无多租户字段 |
|
|
|
+| 基础设施 | 测试 MySQL 库名 `ajyy`（与 shanxia 测试库同实例、不同库）；MinIO 复用测试环境，独立 bucket（如 `ajyy`） |
|
|
|
+
|
|
|
+### 1.2 非目标（本期不做）
|
|
|
+
|
|
|
+- 微信小程序发版与审核
|
|
|
+- 公众端查询反馈进度 / 消息推送
|
|
|
+- 多租户、部门树、复杂数据权限（shanxia data_scope）
|
|
|
+- 公开接口 IP 限流、上传类型白名单、body 限流加固（按普通业务接口实现即可）
|
|
|
+- 列表/详情敏感字段脱敏
|
|
|
+- 管理端导出 Excel（可后置）
|
|
|
+- RSA 登录加密、API 报文加密等 shanxia 全家桶安全中间件
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 2. 仓库与总体架构
|
|
|
+
|
|
|
+```
|
|
|
+ajyy/
|
|
|
+ backend/ # FastAPI（新建）
|
|
|
+ web-admin/ # Vue3 + Vite + Element Plus（新建）
|
|
|
+ mobile-wx/ # uni-app → 微信 H5（已有空壳，在此扩展）
|
|
|
+ 原型图/ # UX/视觉参考，不进运行时
|
|
|
+ 建设方案/ # 需求与报价参考
|
|
|
+ docs/ # 设计、SQL、部署说明
|
|
|
+```
|
|
|
+
|
|
|
+```
|
|
|
+[微信扫码] → HTTPS → mobile-wx (H5)
|
|
|
+ | /api/public/*
|
|
|
+ v
|
|
|
+ backend
|
|
|
+ ^ /api/web/*
|
|
|
+ |
|
|
|
+ web-admin (hash 路由 SPA)
|
|
|
+ |
|
|
|
+ MySQL(ajyy) + MinIO(共用测试环境, bucket ajyy)
|
|
|
+```
|
|
|
+
|
|
|
+约定：
|
|
|
+
|
|
|
+- 统一响应：`{ code, message, data, timestamp }`（对齐 shanxia；成功 `code=200`）
|
|
|
+- 配置：`backend/.env`；前端 `VITE_*` / uni-app `config`
|
|
|
+- 原型仅作字段与交互对照，不嵌入构建产物
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 3. 数据模型与状态机
|
|
|
+
|
|
|
+软删除字段 `del_flag`；主键 `id` 为 UUID 字符串；审计字段：`create_time` / `update_time` / `create_by` / `update_by`（管理端写操作填充；公开提交可空或系统占位）。
|
|
|
+
|
|
|
+### 3.1 表一览
|
|
|
+
|
|
|
+| 表 | 用途 |
|
|
|
+|---|---|
|
|
|
+| `sys_user` | 管理端账号：用户名、密码哈希、显示名、`role_id`、启用状态 |
|
|
|
+| `sys_role` | 角色：`admin` / `handler` / `viewer`（可扩展） |
|
|
|
+| `sys_menu` | 菜单/权限点：`menu_code`、名称、路由 path、类型（目录/菜单/按钮）、排序、显隐 |
|
|
|
+| `sys_role_menu` | 角色拥有的菜单 |
|
|
|
+| `feedback` | 在线反馈 |
|
|
|
+| `suggestion` | 建言献策 |
|
|
|
+| `hotline_config` | 监督热线（单行配置） |
|
|
|
+| `qrcode_config` | 二维码配置（单行配置） |
|
|
|
+| `attachment` | 附件元数据 |
|
|
|
+| `oper_log` | 关键操作审计 |
|
|
|
+
|
|
|
+### 3.2 业务字段（对齐原型）
|
|
|
+
|
|
|
+**feedback**
|
|
|
+
|
|
|
+- 业务编号 `biz_no`（如 `FK20260906001`）
|
|
|
+- 类型：投诉 / 表扬
|
|
|
+- 被反馈人：姓名、部门、职务（选填）
|
|
|
+- 内容（必填）
|
|
|
+- 举报人：姓名、联系方式（选填；全空即匿名）
|
|
|
+- 附件：URL 列表存 JSON 数组（如 `["https://..."]`）
|
|
|
+- 状态、办理备注
|
|
|
+
|
|
|
+**suggestion**
|
|
|
+
|
|
|
+- 业务编号 `biz_no`（如 `JY20260906001`）
|
|
|
+- 建议内容（必填）
|
|
|
+- 联系人、单位/职务、联系方式（选填）
|
|
|
+- 附件、状态、办理备注
|
|
|
+
|
|
|
+**hotline_config：** 电话、邮箱、地址、受理时间说明
|
|
|
+
|
|
|
+**qrcode_config：** 落地 URL、说明文案、自定义图片 URL
|
|
|
+
|
|
|
+**attachment：** 原名、对象键、URL、大小、业务类型、关联业务 ID（可先传后挂）
|
|
|
+
|
|
|
+### 3.3 状态机
|
|
|
+
|
|
|
+**反馈**
|
|
|
+
|
|
|
+```
|
|
|
+待处理 → 处理中 → 已办结
|
|
|
+```
|
|
|
+
|
|
|
+**建言**
|
|
|
+
|
|
|
+```
|
|
|
+待查阅 → 已采纳
|
|
|
+ → 已回复
|
|
|
+```
|
|
|
+
|
|
|
+状态变更写 `oper_log`（操作者、时间、从→到、备注摘要）。
|
|
|
+
|
|
|
+### 3.4 种子数据
|
|
|
+
|
|
|
+- 默认角色三枚 + 菜单树 + `sys_role_menu` 初始授权
|
|
|
+- 默认管理员账号（密码仅存在于本地 `.env` / 初始化文档，不入库明文）
|
|
|
+- 默认热线、二维码各一行（可与原型占位一致，上线前改）
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 4. API 与权限
|
|
|
+
|
|
|
+前缀 `/api`。
|
|
|
+
|
|
|
+### 4.1 公开 `/api/public/*`（无需登录）
|
|
|
+
|
|
|
+| 方法 | 路径 | 说明 |
|
|
|
+|---|---|---|
|
|
|
+| GET | `/hotline` | 读热线 |
|
|
|
+| GET | `/qrcode` | 读二维码配置 |
|
|
|
+| POST | `/attachment/upload` | 上传附件 → MinIO + `attachment` |
|
|
|
+| POST | `/feedback` | 提交反馈 |
|
|
|
+| POST | `/suggestion` | 提交建言 |
|
|
|
+
|
|
|
+不做公众查进度接口。
|
|
|
+
|
|
|
+### 4.2 鉴权 `/api/web/auth/*`
|
|
|
+
|
|
|
+| 方法 | 路径 | 说明 |
|
|
|
+|---|---|---|
|
|
|
+| POST | `/login` | 用户名+密码 → JWT |
|
|
|
+| POST | `/logout` | 登出 |
|
|
|
+| GET | `/current-user` | 当前用户与角色 |
|
|
|
+| GET | `/menus` | 当前用户菜单树（按 `sys_role_menu`） |
|
|
|
+| POST | `/refresh` | 可选；一期可用较长 access token 简化 |
|
|
|
+
|
|
|
+密码：bcrypt。生产环境 HTTPS。不做 RSA 登录加密。
|
|
|
+
|
|
|
+### 4.3 管理 `/api/web/admin/*`（需 JWT）
|
|
|
+
|
|
|
+| 模块 | 能力 |
|
|
|
+|---|---|
|
|
|
+| 工作台 | 统计 + 最近反馈 |
|
|
|
+| 反馈 | 列表筛选、详情、改状态+备注 |
|
|
|
+| 建言 | 列表筛选、详情、改状态+备注 |
|
|
|
+| 热线配置 | 读写 |
|
|
|
+| 二维码配置 | 读写、自定义图上传 |
|
|
|
+| 附件 | 管理端上传/预览（可复用 upload） |
|
|
|
+| 用户 | 列表、启停、重置密码 |
|
|
|
+| 角色授权 | 角色列表；`GET/PUT .../roles/{id}/menus` 勾选保存 |
|
|
|
+| 审计 | `oper_log` 列表（可选，admin） |
|
|
|
+
|
|
|
+**权限模型**
|
|
|
+
|
|
|
+1. 登录后拉取菜单；前端动态渲染侧栏与路由守卫。
|
|
|
+2. 后端对写操作与敏感接口校验角色/菜单权限（不能只靠藏菜单）。
|
|
|
+3. 建议权限点示例：`feedback:handle`、`suggestion:handle`、`hotline:write`、`qrcode:write`、`user:manage`、`role:grant`。
|
|
|
+4. 初始授权：`admin` 全部；`handler` 工作台+反馈+建言（含办理）；`viewer` 工作台+反馈+建言（无办理权限点）。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 5. 三端职责与 UI
|
|
|
+
|
|
|
+### 5.1 mobile-wx（微信 H5）
|
|
|
+
|
|
|
+对齐 `原型图/index.html`，主色 `#a51f23`。
|
|
|
+
|
|
|
+| 页面 | 职责 |
|
|
|
+|---|---|
|
|
|
+| 首页 | 品牌 + 四大入口 |
|
|
|
+| 反馈须知 | 5 秒倒计时 |
|
|
|
+| 在线反馈 | 投诉/表扬、被反馈人选填、内容必填、多附件、匿名可选 |
|
|
|
+| 建言献策 | 内容必填；联系人/附件选填 |
|
|
|
+| 监督热线 | 读配置；一键拨打 |
|
|
|
+| 扫码分享 | 展示配置二维码图或按落地 URL 生成 |
|
|
|
+
|
|
|
+工程结构参考 shanxia `miniprogram`：`api/`、`utils/request`、分页面目录。UI 优先还原原型纪检红，不强制 Vant。
|
|
|
+
|
|
|
+### 5.2 web-admin
|
|
|
+
|
|
|
+对齐 `原型图/admin.html` 信息架构；Vue3 + Element Plus **精简自建壳**（不整套拷贝 Art Design Pro）。
|
|
|
+
|
|
|
+| 模块 | 职责 |
|
|
|
+|---|---|
|
|
|
+| 登录 | 账号密码 |
|
|
|
+| 工作台 | 四指标 + 最近反馈 |
|
|
|
+| 在线反馈 | 筛选、详情抽屉、状态流转 |
|
|
|
+| 建言献策 | 同上 |
|
|
|
+| 热线配置 | 表单保存 |
|
|
|
+| 二维码配置 | URL/文案/自定义图、预览下载 |
|
|
|
+| 用户管理 | 启停、重置密码 |
|
|
|
+| 角色授权 | 勾选菜单保存到 `sys_role_menu` |
|
|
|
+
|
|
|
+列表交互参考 shanxia「筛选项 + 表格 + 抽屉详情」。
|
|
|
+
|
|
|
+### 5.3 backend
|
|
|
+
|
|
|
+薄路由 → `services` → `crud` / `models`；`core`：config、database、auth、storage(MinIO)。
|
|
|
+启动或迁移脚本写入种子数据。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 6. 安全、错误处理与验收
|
|
|
+
|
|
|
+### 6.1 安全（精简）
|
|
|
+
|
|
|
+- 管理端 JWT；密码 bcrypt；生产 HTTPS
|
|
|
+- 登录、配置变更、状态办理写入 `oper_log`
|
|
|
+- 附件 MinIO；按现有测试环境用法配置 endpoint/bucket
|
|
|
+
|
|
|
+不做：公开接口限流/上传白名单加固、字段脱敏、API 加密中间件。
|
|
|
+
|
|
|
+### 6.2 错误与体验
|
|
|
+
|
|
|
+- 校验失败 400；未登录 401；无权限 403；不存在 404
|
|
|
+- 移动端提交成功明确反馈；失败可重试；上传失败单独提示
|
|
|
+- 管理端空态、加载态、办理失败提示
|
|
|
+
|
|
|
+### 6.3 验收对照
|
|
|
+
|
|
|
+| 清单区块 | 覆盖 |
|
|
|
+|---|---|
|
|
|
+| 移动端 1–6 | 首页、须知、反馈、建言、热线、分享 |
|
|
|
+| 后台 7–11 | 工作台、反馈、建言、热线配置、二维码配置 |
|
|
|
+| 后端 12–14 | API、附件、台账留痕 |
|
|
|
+| 安全 15–17 | 登录、角色菜单+授权页、操作审计 |
|
|
|
+| 部署/配套 18–25 | 工程可部署；域名证书、印刷物料、培训按现场另排；建设方案文档已有 |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 7. 实现顺序建议
|
|
|
+
|
|
|
+1. 搭建 `backend` 骨架（config/db/auth/response/storage）+ 建表与种子
|
|
|
+2. 搭建 `web-admin` 骨架（登录、布局、动态菜单）
|
|
|
+3. 公开 API + `mobile-wx` 页面打通提交闭环
|
|
|
+4. 管理端台账与办理、热线/二维码配置
|
|
|
+5. 用户管理 + 角色授权页
|
|
|
+6. 审计日志与联调、测试环境 MySQL/MinIO 接通
|
|
|
+
|
|
|
+详细任务拆解在设计批准后由 implementation plan 给出。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 8. 参考路径
|
|
|
+
|
|
|
+- 移动端原型：`原型图/index.html`
|
|
|
+- 管理端原型：`原型图/admin.html`
|
|
|
+- 功能清单：`建设方案/安徽建工集团医院纪检数字化监督平台-功能建设清单.md`
|
|
|
+- 技术参考：`shanxia2.0/backend`、`shanxia2.0/web-admin`、`shanxia2.0/miniprogram`
|
