拉迷企微客户服务系统 — 项目目录与功能说明

文档版本：2026-06-09
适用范围：本仓库 lami-shequn（PC 社群运营端）

一、项目概览

层级	技术栈	目录	默认地址
PC 前端	Angular 20 + Tailwind v4	`src/`	http://localhost:4200
后端 API	Express + TypeScript + Parse SDK	`backend/`	http://localhost:3101/api
数据库	Parse Server（远程）	配置于 `backend/.env`	`PARSE_SERVER_URL`
产品文档	Markdown	`doc/`	—
后端设计文档	Markdown	`backend/docs/`	—

请求链路：

浏览器 → Angular (4200) → proxy /api → Express (3101) → Parse Server → MongoDB
                                              ↓
                                         QiWe 企微开放平台（群同步、消息同步）

二、目录结构

lami-shequn/
├── README.md                 # 快速启动、演示账号、常见问题
├── package.json              # 前端依赖与脚本
├── angular.json
├── proxy.conf.json           # 开发代理：/api → localhost:3101
├── tsconfig*.json
│
├── src/                      # ★ PC 前端（Angular 20）
│   ├── main.ts
│   ├── environments/         # 环境配置（useBackendApi 等）
│   └── app/
│       ├── app.routes.ts     # 全部路由定义
│       ├── core/             # 认证、布局、模型、API 封装
│       │   ├── auth/         # AuthService、AuthGuard、RoleGuard
│       │   ├── layout/       # MainLayout、侧栏、顶栏、通知中心
│       │   ├── models/       # TypeScript 业务模型
│       │   ├── services/     # MockDataService、api/* 服务
│       │   └── interceptors/ # HTTP 拦截器
│       ├── features/         # ★ 业务页面（按模块分目录）
│       │   ├── auth/         # 登录、注册、忘记密码
│       │   ├── dashboard/    # 总览看板
│       │   ├── workspace/    # 工作台、通知、问题看板
│       │   ├── group-management/  # 客户群、群详情、小区档案
│       │   ├── compliance/   # 合规检查、文档登记
│       │   ├── risk-control/ # 风控总览、关键词、工单、案例
│       │   ├── content-ops/  # 素材库、运营计划、群发、分析
│       │   ├── acquisition/  # 拉群渠道、KOC、意向线索、展厅
│       │   ├── data-entry/   # 客户/订单/直播数据补录
│       │   ├── reports/      # 周报、月报
│       │   └── settings/     # 系统设置、个人资料
│       └── shared/components/  # 可复用 UI（表格、图表、筛选条等）
│
├── backend/                  # ★ 后端 API（Express）
│   ├── package.json
│   ├── .env / .env.example   # 环境变量（Parse、QiWe）
│   ├── docs/                 # 后端设计、数据库、部署文档
│   ├── tests_python/         # Webhook / 群同步自动化测试脚本
│   └── src/
│       ├── index.ts          # 启动入口（先启 HTTP，后台初始化）
│       ├── apps/pc/
│       │   ├── app.ts        # Express 路由装配
│       │   ├── auth/         # 登录 / 注册 / 用户资料
│       │   ├── dashboard/    # 总览看板 API
│       │   ├── health/       # 健康检查、版本信息
│       │   └── qiwe/         # 企微 Webhook、群、消息、组织
│       └── shared/
│           ├── auth/         # 数据范围（总监/督导/店长）
│           ├── config/       # 环境变量读取
│           ├── db/           # Parse 客户端、Schema、迁移
│           ├── errors/       # 统一错误类型
│           └── http/         # 响应封装、错误处理
│
└── doc/                      # ★ 产品与设计文档
    ├── 项目目录与功能说明.md   # ← 本文档
    ├── 企微客户服务-功能清单(2).md
    ├── 社群运营功能模块-实现可行性清单.md
    ├── 产品架构和页面索引.md
    ├── 风控工单-后端开发说明.md
    ├── 项目现状分析与待确认事项.md
    ├── 后续优化需求与流程梳理.md
    ├── UI设计规范白皮书.md
    ├── Angular项目开发规范.md
    └── …（流程图、用户画像、泳道图等）

2.1 前端 `features/` 模块对照

目录	业务模块	主要路由
`auth/`	认证	`/login`, `/register`, `/forgot-password`
`dashboard/`	总览看板	`/dashboard`
`workspace/`	工作台	`/workspace`, `/workspace/notifications`, `/workspace/issues`
`group-management/`	客户群管理	`/groups`, `/groups/:id`, `/communities`
`compliance/` + 文档	合规与文档	`/documents`, `/compliance/*`
`risk-control/`	风控预警	`/risk-control/*`
`content-ops/`	内容运营	`/content/*`
`acquisition/`	拉群与意向	`/acquisition/*`
`data-entry/`	数据补录	`/data-entry/*`
`reports/`	经营报表	`/reports/weekly`, `/reports/monthly`
`settings/`	设置	`/settings`, `/settings/profile`

2.2 后端 `apps/pc/` 模块对照

目录	路由前缀	职责
`health/`	`/api`	健康检查、版本信息
`auth/`	`/api/auth`	登录、注册、用户资料、改密
`dashboard/`	`/api/dashboard`	总览看板统计
`qiwe/`	`/api/qiwe`	Webhook、群同步、消息、组织、小区

2.3 Parse 数据表（已建 Schema）

表名	用途
`_User`	用户账号（登录、角色、门店）
`GroupChat`	客户群资产
`GroupMember`	群成员
`Message`	群消息
`Store`	门店
`Community`	小区档案
`OrgDepartment` / `OrgMember`	组织架构
`SystemMigration`	一次性迁移记录

三、角色体系

当前代码实现 3 种角色（按数据范围从高到低）：

角色代码	名称	数据范围
`director`	总监	全局
`regional_supervisor`	区域督导	所辖区域
`store_manager`	店长	本门店

侧栏菜单与 RoleGuard 按角色过滤可见页面。

演示账号

默认密码均为 123456，登录使用手机号（非邮箱）：

角色	手机号	邮箱
总监	13800000001	admin@lami.com
区域督导	13800000002	dudao@lami.com
店长	13800000003	lidian@lami.com

四、当前已实现功能

4.1 前后端对接状态总览

状态	说明
✅ 已接后端	页面/功能调用真实 API，数据来自 Parse
🟡 混合	部分走 API，部分仍用 Mock
⬜ Mock	页面 UI 完成，数据来自 `MockDataService`（localStorage）

environment.useBackendApi = true（开发/生产均为 true）。Mock 主要作为 API 失败时的回退 或 后端尚未实现的模块演示。

4.2 已实现（✅ 已接后端）

认证模块

手机号 + 密码登录、注册、忘记密码
个人资料修改、修改密码、退出登录
API：POST /api/auth/login 等

总览看板

群数量、成员数、活跃度、健康评级、生命周期分布
按角色数据范围过滤（总监/督导/店长）
API：GET /api/dashboard/overview
⚠️ 风控相关指标（riskEventCount、pendingWorkOrders）暂写死为 0

客户群管理

群列表（筛选、分页、数据范围）
群详情（基本信息、消息 Tab、成员 Tab）
小区档案列表
API：GET /api/qiwe/groups、/groups/:roomId、/groups/:roomId/members、/messages、/communities

组织与同步（设置页部分功能）

健康检查、版本信息
群同步、消息同步、组织同步
API：GET /api/health、POST /api/qiwe/sync-groups 等

企微 Webhook（后端）

接收企微回调：文本消息入库、群创建/解散/改名、成员进退
先返回 200，再异步处理
⚠️ 图片/视频/文件消息暂不存储；15500 系统消息暂不入库

4.3 前端 UI 已完成、数据仍 Mock（⬜）

模块	路由	说明
工作台	`/workspace`	千人千面待办概览
通知中心	`/workspace/notifications`	通知列表
问题看板	`/workspace/issues`	工单分类（依赖风控后端）
文档登记	`/documents`	群文档合规登记
文档异常	`/documents/anomalies`	异常文档列表
合规检查	`/compliance/*`	4 个子页（缺文档、格式检查、报告等）
风控预警	`/risk-control/*`	4 个子页（总览、关键词、工单、案例）
内容运营	`/content/*`	素材库、周计划、群发、分析
拉群意向	`/acquisition/*`	渠道、KOC、意向线索、展厅
数据补录	`/data-entry/*`	客户、订单、直播
经营报表	`/reports/*`	周报、月报
系统设置	`/settings`	用户/门店管理部分仍 Mock

五、后端 API 清单（当前）

5.1 健康检查

方法	路径	说明
GET	`/api/health`	服务状态 + Parse 连接状态
GET	`/api/version`	版本信息

5.2 认证 `/api/auth`

方法	路径	说明
POST	`/login`	登录（phone + password）
POST	`/register`	注册
POST	`/forgot-password`	邮箱重置密码
POST	`/logout`	退出
GET	`/me`	当前用户
PUT	`/profile`	更新资料
PUT	`/password`	修改密码

5.3 看板 `/api/dashboard`

方法	路径	说明
GET	`/overview`	总览统计数据

5.4 企微 `/api/qiwe`

方法	路径	说明
POST	`/webhook`	企微消息回调
POST	`/sync-groups`	同步群列表
POST	`/sync-messages`	同步历史消息
POST	`/backfill-groups-from-messages`	从消息补全群
GET	`/groups`	群列表
GET	`/groups/:roomId`	群详情
GET	`/groups/:roomId/members`	群成员
GET	`/messages`	消息列表
GET	`/stores`	门店列表
GET	`/communities`	小区档案
GET/POST	`/org/tree`, `/org/departments`, `/org/members`, `/org/sync`	组织架构

5.5 尚未实现的后端模块

模块	预期路由	状态
风控 / 工单	`/api/risk/*`	❌ 未建
合规 / 文档	`/api/compliance/*`	❌ 未建
内容运营	`/api/content/*`	❌ 未建
拉群 / 意向	`/api/acquisition/*`	❌ 未建
数据补录	`/api/data-entry/*`	❌ 未建
报表	`/api/reports/*`	❌ 未建
通知	`/api/notifications/*`	❌ 未建

六、后续待完成功能

按优先级排列，细节见各专项文档。

P0 — 下一迭代（业务闭环）

1. 风控与工单模块（最高优先级）

详见 doc/风控工单-后端开发说明.md

阶段	内容	预估
阶段 A	Parse 建表（RiskKeyword / RiskEvent / WorkOrder）+ 关键词 CRUD + 只读工单/事件 API + Dashboard 真实计数 + 前端改调 API	1–2 天
阶段 B	工单 resolve/close、Webhook 消息 → 关键词扫描 → 自动建单、预警 PATCH	3–5 天
阶段 C	阈值配置、退群/无互动检测、企微强提醒、案例知识库	后续

影响页面：/risk-control/*、/workspace/issues、Dashboard 风控指标。

2. 通知机制统一

通知中心（顶栏）与通知页（/workspace/notifications）数据源不一致
需定义通知产生规则（Webhook 事件、工单创建、合规异常等）
后端 /api/notifications/* + 前端统一对接

3. 合规与文档模块

群文档登记（hasDocument、documentPinned 等字段已有 Schema，缺写入逻辑）
缺文档检测、格式检查、合规报告
后端 API + 前端从 Mock 切换

P1 — 中期

模块	待做	参考文档
内容运营	素材库 CRUD、周计划、群发对接 QiWe	`doc/社群运营功能模块-实现可行性清单.md`
数据补录	客户/订单/直播字段确认 + API	`doc/项目现状分析与待确认事项.md`
拉群意向	KOC 管理、意向线索跟进	同上
经营报表	周报/月报数据聚合	同上
非文本消息	图片/视频/文件消息存储	`backend/docs/database-design.md`
系统消息	15500 类型消息按需入库	`backend/docs/backend-design.md`

P2 — 长期 / 需外部配合

能力	说明
销售添加链接率跟踪	企微 API 无法直接获取，需替代方案
私域跟进完整链路	需 CRM 对接
完整直播模块	需直播平台数据
完整周月报（转化/添加）	部分指标需手工录入或 ERP
移动端企微侧边栏	未开工
CRM / ERP 打通	见 `doc/后续优化需求与流程梳理.md`

产品规划 vs 当前实现

doc/产品架构和页面索引.md 规划约 60+ 页面，当前已实现 33 条路由。未开工示例：

/access/*（权限管理细分页）
/workspace/recheck（复核工作台）
多层级 Dashboard 下钻页
更多报表与配置页

七、本地开发

7.1 启动

# 1. 后端
cd backend
npm install
npm run dev          # → http://localhost:3101

# 2. 前端（另开终端，仓库根目录）
npm install
npm start            # → http://localhost:4200

7.2 环境变量（`backend/.env`）

变量	说明
`PC_PORT`	后端端口，默认 3101
`PARSE_SERVER_URL`	Parse 数据库地址
`PARSE_APP_ID`	Parse 应用 ID
`PARSE_MASTER_KEY`	Parse 管理员密钥
`QIWE_API_BASE`	QiWe 平台 API 地址
`QIWE_TOKEN` / `QIWE_GUID` / `QIWE_USER_ID`	企微平台凭证（群同步需要）

7.3 常见问题

现象	原因	处理
登录 500 + Parse 502 HTML	远程 Parse 服务不可用	检查 `PARSE_SERVER_URL` 对应服务；或临时设 `useBackendApi: false` 用 Mock
`EADDRINUSE :::3101`	端口被占用	`netstat -ano \\| findstr ":3101"` 后 `taskkill`
前端「网络错误」	后端未启动	确认 `backend/` 在跑，访问 `/api/health`

八、相关文档索引

文档	内容
`README.md`	快速启动
`doc/风控工单-后端开发说明.md`	风控后端详细设计 + 分阶段计划
`doc/社群运营功能模块-实现可行性清单.md`	P0/P1 可实现性评估
`doc/产品架构和页面索引.md`	完整页面规划
`doc/项目现状分析与待确认事项.md`	业务待确认问题
`backend/docs/backend-design.md`	Webhook 架构设计
`backend/docs/database-design.md`	Parse 表结构
`doc/UI设计规范白皮书.md`	Fiori 风格 UI 规范
`doc/Angular项目开发规范.md`	前端开发规范

九、架构现状总结

┌─────────────────────────────────────────────────────────┐
│  前端 Angular（UI 骨架完整，33+ 路由）                    │
│  ├─ ✅ 已接 API：认证、看板、群管理、小区、部分设置         │
│  └─ ⬜ 仍 Mock：风控、合规、内容、拉群、补录、报表、工作台   │
├─────────────────────────────────────────────────────────┤
│  后端 Express（企微接入层较成熟）                           │
│  ├─ ✅ auth / dashboard / qiwe（Webhook+群+消息+组织）      │
│  └─ ❌ 未建：risk / compliance / content / reports …     │
├─────────────────────────────────────────────────────────┤
│  Parse Server（远程数据库，登录与业务数据均依赖）            │
└─────────────────────────────────────────────────────────┘

下一优先级：风控工单后端（阶段 A）→ 通知统一 → 合规文档 → 其余 Mock 模块逐个接 API。

项目目录与功能说明.md 17 KB Постійне посилання Історія Запис