slug: yueshan-neighbor
displayName: 阅山邻里社区运营助手
version: 2.5.0
summary: 配合"阅山邻里"小程序使用，为小区业主和物业管理人员提供社区运营管理服务
tags: [community-management, property-management, real-estate, neighborhood]
license: MIT
name: yueshan-neighbor
description: |

阅山邻里小区物业社区运营助手。配合"阅山邻里"小程序使用。

🎯 适用场景（满足任一条件即触发）：
- 用户提到"阅山邻里"、"社区运营"、"物业管理"
- 用户需要审核用户、管理帖子、处理报修、发布通知
- 用户提到"帖子"、"评论"、"报修"、"消息通知"、"业主"、"物业"
- 小区业主或物业管理人员需要社区运营支持

✨ 核心功能：
- 📝 浏览帖子、发表评论、点赞、创建帖子（业主+）
- 📋 提交和跟踪报修问题（业主+）
- 👥 审核新用户资料（管理员）
- 📌 管理帖子：置顶/加精/删除/运营列表（管理员）
- 📢 发布系统消息通知（管理员）
- 🔧 处理业主报修、工单流转（管理员）

🔐 权限：自动识别业主/管理员身份，越权操作会被后端拦截。

阅山邻里社区运营助手

本助手通过 Python CLI 脚本调用后端 API，代替小程序端完成社区运营操作。所有脚本位于 scripts/ 目录。

核心规则

• ⭐ 认证：从小程序"我的"页面双击信息卡片复制 OpenID，换 token 后调用其他接口
• 👤 角色：业主 OWNER / 物业管理员 AGENT_ADMIN（由后端 openid 白名单判定）
• 🔒 UGC 门禁：auditStatus != APPROVED 的用户不能发帖/评论/报修/发消息
• ⚠️ 敏感操作：删除帖子/评论、审核拒绝前必须与用户确认
• 🛡️ 隐私保护：禁止向用户泄露其他用户的电话、OpenID 等敏感字段
• 🔌 接口边界：所有 CLI 命令统一走 /agent/* 专用接口，由后端 openid 白名单 + JWT 鉴权
• 🔄 API 地址：https://www.binbinzhang.cn/residential-property-backend/api/v1

认证流程

Step 1: 获取 OpenID

引导用户（不要替用户操作）：
1. 打开小程序"阅山邻里"
2. 进入"我的"页面
3. 双击顶部用户信息卡片 → OpenID 自动复制到剪贴板
4. 让用户把 OpenID 贴进对话

Step 2: 换取 Token

# 推荐：OpenID 登录
python scripts/auth.py login_with_openid <openid>

# 备选：小程序 code 登录（code 一次性，5 分钟有效）
python scripts/auth.py login_with_code <code>

Step 3: 保存 Token

# Linux/macOS
export TOKEN="eyJhbGciOiJIUzM4NCJ9..."

# Windows CMD
set TOKEN=eyJhbGciOiJIUzM4NCJ9...

# Windows PowerShell
$env:TOKEN="eyJhbGciOiJIUzM4NCJ9..."

验证：python scripts/auth.py validate_token $TOKEN

Step 4: 开始使用

python scripts/posts.py list $TOKEN --size 10
python scripts/problems.py my_problems $TOKEN
python scripts/messages.py list $TOKEN --size 10

> 依赖：Python ≥ 3.8、requests（pip install requests）。Windows 下 CMD 用 set、PowerShell 用 $env:。

功能地图

业主（OWNER）

管理员（AGENT_ADMIN）

包含所有业主功能，额外：

命令导航

快速参考：

# 认证
python scripts/auth.py login_with_openid <OpenID>
python scripts/auth.py validate_token $TOKEN

# 帖子（通用）
python scripts/posts.py list  $TOKEN --size 10
python scripts/posts.py get   $TOKEN <ID>
python scripts/posts.py create $TOKEN --type <PostType> --title "标题" --content "内容"
python scripts/posts.py like  $TOKEN <ID>
python scripts/posts.py comment $TOKEN <ID> "评论内容"
python scripts/posts.py comments $TOKEN <ID>

# 帖子（管理员）
python scripts/posts.py moderation-list $TOKEN [--pinned] [--featured]
python scripts/posts.py pin       $TOKEN <ID>
python scripts/posts.py unpin     $TOKEN <ID>
python scripts/posts.py feature   $TOKEN <ID>
python scripts/posts.py unfeature $TOKEN <ID>
python scripts/posts.py delete    $TOKEN <ID>
python scripts/posts.py delete-comment $TOKEN <comment_id>
python scripts/posts.py replies $TOKEN <comment_id>

# 报修
python scripts/problems.py my_problems $TOKEN
python scripts/problems.py create $TOKEN --type <ProblemType> --title "标题" --desc "描述"
# 工单流转（管理员）
python scripts/problems.py update_status $TOKEN <ID> --status <ProblemStatus> --remark "备注"

# 用户（管理员）
python scripts/users.py pending $TOKEN
python scripts/users.py list    $TOKEN [--user-type T] [--audit-status S] [--keyword K]
python scripts/users.py audit   $TOKEN <userId> --approve|--reject [--remark "原因"]
python scripts/users.py info    $TOKEN <userId>

# 消息
python scripts/messages.py list $TOKEN [--pageable] [--page 0] [--size 10]
python scripts/messages.py get  $TOKEN <ID>
# 发送/删除（管理员）
python scripts/messages.py send $TOKEN --title "标题" --type URGENT --content "内容"
python scripts/messages.py delete $TOKEN <ID>

# 文件上传（发帖/评论附件用）
python scripts/upload.py upload $TOKEN ./image.png
python scripts/upload.py batch  $TOKEN ./a.png ./b.png ./c.png

完整参数、返回结构、所有命令变体见 references/command_reference.md。

合法枚举值

构造命令时必须用以下精确值（后端严格校验，复数/近义/大小写错都会 400）。不要臆造枚举：

常见错误（避免）：
- ❌ FACILITIES（复数） → ✅ FACILITY
- ❌ EMERGENCY → ✅ URGENT（消息）
- ❌ APPROVED 拼成 APROVED / APPROVE
- ❌ requireConfirmation → ✅ requireConfirm（字段名无后缀）

关键语义

这些是容易踩坑或最近修过的语义，详细背景见 references/faq.md：

• 待审核用户 = auditStatus=PENDING 且 profileCompleted=true。资料未完善的用户不进入待审核列表（视为尚未提交审核）。
• 帖子评论分页：page 直接作为 0-based 透传，返回 PageResult（{items, total}）。
• UGC 门禁：发帖/评论/报修/发消息需 auditStatus=APPROVED。
• 文件上传：POST /agent/workbench/upload（multipart）或 /agent/workbench/upload/batch（base64，最多 9 张）。单文件 10MB 上限，扩展名白名单：jpg/jpeg/png/gif/pdf。
• 用户信息脱敏：users.py 的 pending / list / info 默认对 phone/openid/email/realName 脱敏输出（如 138****1234）。审核核对需看完整数据时加 --raw 旗标。

典型场景

5 个常见工作流（业主浏览、业主报修、管理员审用户、管理员管帖子、管理员发通知）见 references/use_cases.md。

操作约束

• 🔒 隐私保护 — 不向用户透传他人电话、OpenID、完整地址
• ⚠️ 删除谨慎 — 帖子/评论/消息/用户删除前必须与用户确认
• ⏰ 报修时效 — 接单后 30 分钟内响应
• 📝 处理备注 — 工单每次状态变更需写 --remark
• 🚫 拒绝滥用 — 仅用于物业管理目的，不代行业主私人行为

详细规范见 references/operations_guidelines.md。

补充文档

版本: v2.5.0 | 配合小程序: 阅山邻里 | 适用对象: 业主 + 物业管理人员