docs: add ajyy feedback platform design spec

Capture the approved architecture for the hospital纪检扫码反馈 system (backend, web-admin, H5 mobile) before implementation planning.

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/superpowers/specs/2026-09-06-ajyy-feedback-platform-design.md

@@ -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`