chengshishouce/REQUIREMENTS_IMPLEMENTATION.md

城市手册项目需求实施计划

📋 需求实施状态

基于《城市手册需求文档 v1.0》的实施进度追踪。

✅ 已完成

模块	功能	状态
项目框架	Django + React 基础框架	✅
用户系统	用户模型扩展（角色、状态）	✅
版块管理	Region 模型（省市县乡村层级）	✅
版主管理	版主申请、权限、支持模型	✅
文章管理	Article 模型 + 审核流程	✅
特色服务	FeaturedService 模型 + 审核流程	✅
交互功能	评论、评分、点赞、收藏模型	✅

🚧 进行中

模块	功能	状态
API 接口	REST API 端点	🚧
前端组件	MobX Stores	🚧
前端页面	页面组件	⏸️

⏸️ 待开发

模块	功能	优先级
AI 审核	AI 审核逻辑	高
搜索功能	城市和服务搜索	中
后台管理	Django Admin 自定义	中
分享功能	分享卡片生成	低

---

🗄️ 数据库模型结构

核心模型

User (用户)
├── role: user/moderator/ai_auditor/admin
├── status: active/disabled
└── 扩展字段

Region (版块)
├── level: province/city/county/town/village
├── parent: self-referential
└── children: hierarchical

ModeratorApplication (版主申请)
├── applicant: User
├── region: Region
├── support_count: int
└── status: pending/approved/rejected/cancelled

ModeratorPermission (版主权限)
├── moderator: User
├── region: Region
├── rank: general/colonel/captain/soldier
└── status: active/restricted/revoked

ModeratorSupport (版主支持)
├── supporter: User
└── application: ModeratorApplication

PermissionRestriction (权限限制)
├── operator: User
├── target_moderator: User
└── restriction_type: partial/full

Article (文章)
├── title, content
├── region: Region
├── article_type: basic/history/culture/practical/life
├── author: User
├── moderator_status: pending/approved/rejected
├── ai_status: pending/approved/rejected
└── publish_status: draft/pending_moderator/pending_ai/published/rejected

FeaturedService (特色服务)
├── name, description
├── region: Region
├── category: clothing/food/accommodation/transport/entertainment/tourism/culture
├── submitter: User
├── moderator_status: pending/approved/rejected
├── ai_status: pending/approved/rejected
└── publish_status: draft/pending_moderator/pending_ai/published/rejected

Comment (评论)
├── content
├── target_type: article/service
├── target_id
├── author: User
└── ai_status: pending/approved/rejected

Rating (评分)
├── user: User
├── target_type: region/service
├── target_id
└── score: 1-5

Like (点赞)
├── user: User
├── target_type: article/service
└── target_id

Favorite (收藏)
├── user: User
├── target_type: region/service
└── target_id

---

🔧 API 端点设计

认证端点

POST /api/auth/login/          # 登录获取 token
POST /api/auth/token/refresh/  # 刷新 token
POST /api/auth/logout/         # 登出

用户端点

GET    /api/users/me/          # 获取当前用户
PUT    /api/users/me/          # 更新个人信息
GET    /api/users/favorites/   # 获取收藏列表
GET    /api/users/ratings/     # 获取评分列表

版块端点

GET    /api/regions/           # 获取版块列表
GET    /api/regions/{id}/      # 获取版块详情
GET    /api/regions/{id}/children/  # 获取子版块
GET    /api/regions/{id}/path/     # 获取完整路径

文章端点

GET    /api/articles/          # 获取文章列表
POST   /api/articles/          # 创建文章
GET    /api/articles/{id}/     # 获取文章详情
PUT    /api/articles/{id}/     # 更新文章
DELETE /api/articles/{id}/     # 删除文章
POST   /api/articles/{id}/submit/    # 提交审核
POST   /api/articles/{id}/approve/   # 版主通过
POST   /api/articles/{id}/reject/    # 版主拒绝

特色服务端点

GET    /api/services/          # 获取服务列表
POST   /api/services/          # 创建服务
GET    /api/services/{id}/     # 获取服务详情
PUT    /api/services/{id}/     # 更新服务
DELETE /api/services/{id}/     # 删除服务
POST   /api/services/{id}/submit/    # 提交审核
POST   /api/services/{id}/approve/   # 版主通过
POST   /api/services/{id}/reject/    # 版主拒绝

交互端点

# 评论
GET    /api/comments/          # 获取评论列表
POST   /api/comments/          # 创建评论

# 评分
POST   /api/ratings/           # 创建/更新评分
DELETE /api/ratings/{id}/      # 删除评分

# 点赞
POST   /api/likes/             # 创建/取消点赞

# 收藏
POST   /api/favorites/         # 创建/取消收藏
GET    /api/favorites/         # 获取收藏列表

版主管理端点

# 版主申请
POST   /api/moderator/applications/     # 申请版主
GET    /api/moderator/applications/     # 获取申请列表
POST   /api/moderator/applications/{id}/support/  # 支持申请
POST   /api/moderator/applications/{id}/approve/ # 审核通过
POST   /api/moderator/applications/{id}/reject/  # 审核拒绝

# 版主权限
GET    /api/moderator/permissions/     # 获取权限列表
POST   /api/moderator/permissions/{id}/restrict/  # 限制权限

---

📱 前端页面结构

主要页面

/                          # 首页
├── 城市导航
├── 推荐城市
└── 最新文章

/cities/{id}/              # 城市详情页
├── 基础信息卡片
├── 历史
├── 文化
├── 实用信息
└── 生活推荐

/cities/{id}/services      # 城市特色服务页
├── 分类筛选
└── 服务列表

/articles/{id}/            # 文章详情页
├── 文章内容
├── 评论
├── 评分
└── 点赞

/services/{id}/            # 服务详情页
├── 服务信息
├── 评论
├── 评分
└── 点赞

/user/profile/             # 个人中心
├── 个人信息
├── 收藏列表
├── 我的评分
└── 申请管理

/admin/                    # 后台管理（管理员）
├── 用户管理
├── 版主管理
├── 内容审核
└── 数据统计

/login/                    # 登录页
/register/                 # 注册页

---

🔄 审核流程实现

文章/服务审核流程

用户提交 → 版主初审 → AI审核 → 发布
   ↓          ↓         ↓
  拒绝       拒绝      拒绝

代码实现：

1. 用户创建内容（状态：draft）
2. 提交审核（状态：pending_moderator）
3. 版主审核：
   • 通过（moderator_status: approved）→ pending_ai
   • 拒绝（moderator_status: rejected）→ rejected
4. AI审核：
   • 通过（ai_status: approved）→ published
   • 拒绝（ai_status: rejected）→ rejected

评论审核流程

用户评论 → AI审核 → 显示/隐藏
   ↓          ↓
  通过       拒绝

代码实现：

1. 用户创建评论（状态：pending）
2. AI审核：
   • 通过（ai_status: approved）→ 显示
   • 拒绝（ai_status: rejected）→ 隐藏

---

🎯 待确认事项

需要用户确认

1. 评分机制

   • 几星制？（1-5星？）
   • 是否需要写评价？

2. 版主申请规则

   • 征集期多长时间？
   • 需要多少支持人数？

3. AI审核

   • AI审核规则和阈值？
   • 拒绝原因是否对用户可见？

4. 分享功能

   • 分享卡片样式和内容格式？

5. 版主权限限制

   • 部分限制具体限制哪些权限？
   • 限制的最长时限？

---

📊 MVP 范围

MVP 包含功能

✅ 用户注册登录 ✅ 城市信息展示 ✅ 文章发布和浏览 ✅ 特色服务展示 ✅ 评论、评分、点赞、收藏 ✅ 版主申请和审核 ✅ 内容审核流程（版主+AI） ✅ 基础搜索功能

MVP 不包含

❌ 数据抓取工具 ❌ 商家入驻功能 ❌ 高级统计和分析 ❌ 移动 App ❌ 多语言支持

---

📝 下一步开发计划

阶段 1：API 开发

1. 创建所有 Serializer
2. 创建所有 ViewSet
3. 配置 URL 路由
4. 测试 API 端点

阶段 2：前端开发

1. 创建 MobX Stores
2. 创建页面组件
3. 集成 API 调用
4. 路由配置

阶段 3：AI 集成

1. 实现 AI 审核逻辑
2. 配置审核规则
3. 测试审核流程

阶段 4：测试和优化

1. 功能测试
2. 性能优化
3. 用户体验优化

---

📚 参考资料

• 需求文档
• README
• 技术文档
• API 测试