feat: complete V1 phases 0-7
This commit is contained in:
@@ -0,0 +1,279 @@
|
||||
# 03 技术架构
|
||||
|
||||
## 1. 总体选择
|
||||
|
||||
优先采用“TypeScript 全栈 + 模块化单体 + MySQL + Redis + 对象存储 + Docker”。
|
||||
|
||||
推荐：
|
||||
|
||||
### 微信小程序
|
||||
|
||||
- 微信小程序原生框架
|
||||
- TypeScript
|
||||
- TDesign Miniprogram（优先复用成熟组件）
|
||||
- 自建 API Client
|
||||
- 不使用重量级跨端框架作为 V1 默认方案
|
||||
|
||||
### 管理后台
|
||||
|
||||
- Vue 3
|
||||
- TypeScript
|
||||
- Vite
|
||||
- Pinia
|
||||
- Vue Router
|
||||
- TDesign Vue Next 或成熟国内 UI 组件库
|
||||
- ECharts（仅统计图表需要时）
|
||||
|
||||
### API
|
||||
|
||||
- Node.js LTS
|
||||
- NestJS
|
||||
- TypeScript
|
||||
- REST API
|
||||
- Prisma 或 TypeORM 二选一；建议 Prisma，但一旦项目启动后不得混用
|
||||
- OpenAPI/Swagger
|
||||
- Zod/class-validator 统一选一种 DTO 校验体系，NestJS 默认可使用 class-validator
|
||||
|
||||
### 数据
|
||||
|
||||
- MySQL 8.x
|
||||
- Redis 7.x
|
||||
- 对象存储：腾讯云 COS 为生产默认实现
|
||||
- 本地开发：MinIO 兼容 S3 API
|
||||
|
||||
### 部署
|
||||
|
||||
- Docker
|
||||
- Docker Compose
|
||||
- Nginx
|
||||
- 腾讯云 CVM / 轻量云服务器可作为早期部署载体
|
||||
- 数据库生产优先托管 MySQL；预算有限时也可独立数据库容器，但必须有可靠备份
|
||||
- HTTPS
|
||||
- 国内域名和备案按实际上线要求办理
|
||||
|
||||
---
|
||||
|
||||
## 2. 为什么不做微服务
|
||||
|
||||
当前机构规模和 V1 业务复杂度不需要微服务。
|
||||
|
||||
模块化单体优点：
|
||||
|
||||
- 部署简单；
|
||||
- 成本低；
|
||||
- 调试简单；
|
||||
- 事务一致性容易保证；
|
||||
- Codex 更容易保持全局一致；
|
||||
- 后续真有规模需求时可按模块拆分。
|
||||
|
||||
模块边界仍必须清晰。
|
||||
|
||||
---
|
||||
|
||||
## 3. API 模块建议
|
||||
|
||||
```text
|
||||
auth
|
||||
users
|
||||
profiles
|
||||
beneficiaries
|
||||
service-applications
|
||||
service-cases
|
||||
service-records
|
||||
follow-ups
|
||||
projects
|
||||
activities
|
||||
volunteers
|
||||
content
|
||||
files
|
||||
notifications
|
||||
statistics
|
||||
audit
|
||||
permissions
|
||||
system
|
||||
```
|
||||
|
||||
每模块：
|
||||
|
||||
- controller
|
||||
- service
|
||||
- repository
|
||||
- dto
|
||||
- entities/model
|
||||
- policy/permission
|
||||
- tests
|
||||
|
||||
---
|
||||
|
||||
## 4. 分层规则
|
||||
|
||||
```text
|
||||
Controller
|
||||
↓
|
||||
Application Service
|
||||
↓
|
||||
Domain Rules / Policy
|
||||
↓
|
||||
Repository / Adapter
|
||||
↓
|
||||
Database / External Service
|
||||
```
|
||||
|
||||
禁止：
|
||||
|
||||
- Controller 直接访问 ORM；
|
||||
- 页面直接写 SQL；
|
||||
- 业务层直接调用 COS/微信 SDK；
|
||||
- 前端自己判断权限代替后端校验。
|
||||
|
||||
---
|
||||
|
||||
## 5. 外部 Adapter
|
||||
|
||||
必须封装：
|
||||
|
||||
- WeChatAuthAdapter
|
||||
- WeChatSubscribeMessageAdapter
|
||||
- ObjectStorageAdapter
|
||||
- SmsAdapter（若以后使用）
|
||||
- AIAdapter（二期）
|
||||
- GeocodingAdapter（二期）
|
||||
|
||||
这样可更换供应商。
|
||||
|
||||
---
|
||||
|
||||
## 6. API 规范
|
||||
|
||||
统一前缀：
|
||||
|
||||
`/api/v1`
|
||||
|
||||
响应：
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {},
|
||||
"requestId": "..."
|
||||
}
|
||||
```
|
||||
|
||||
错误：
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"error": {
|
||||
"code": "APPLICATION_NOT_FOUND",
|
||||
"message": "未找到该服务申请"
|
||||
},
|
||||
"requestId": "..."
|
||||
}
|
||||
```
|
||||
|
||||
HTTP 状态码必须正确使用，不得永远 200。
|
||||
|
||||
---
|
||||
|
||||
## 7. 认证
|
||||
|
||||
### 小程序端
|
||||
|
||||
- wx.login 获取 code；
|
||||
- 后端换取微信身份；
|
||||
- 服务端创建自己的 session/token；
|
||||
- token 轮换/过期；
|
||||
- 手机号绑定按微信开放能力和实际授权流程实现；
|
||||
- openid/unionid 绝不作为前端授权依据。
|
||||
|
||||
### 后台
|
||||
|
||||
推荐：
|
||||
|
||||
- 用户名/手机号 + 强密码；
|
||||
- 生产可增加 MFA；
|
||||
- HttpOnly Secure Cookie 优先；
|
||||
- 管理后台不把长期 Token 放 localStorage。
|
||||
|
||||
---
|
||||
|
||||
## 8. 权限
|
||||
|
||||
RBAC + 资源级 Policy。
|
||||
|
||||
示例：
|
||||
|
||||
- STAFF 可以看自己负责的工单；
|
||||
- PROJECT_MANAGER 可以看自己项目范围；
|
||||
- ADMIN 可跨项目；
|
||||
- VOLUNTEER 只能查看分配给自己的最小必要任务信息；
|
||||
- 普通小程序用户只能查看自己提交或合法关联的申请。
|
||||
|
||||
---
|
||||
|
||||
## 9. 状态机
|
||||
|
||||
服务申请、工单、活动、志愿者审批必须采用明确状态机。
|
||||
|
||||
所有 transition：
|
||||
|
||||
- 验证当前状态；
|
||||
- 验证目标状态；
|
||||
- 验证权限；
|
||||
- 事务写入；
|
||||
- 写 history；
|
||||
- 写 audit；
|
||||
- 事务提交后再触发通知。
|
||||
|
||||
---
|
||||
|
||||
## 10. 幂等
|
||||
|
||||
以下必须防重复：
|
||||
|
||||
- 服务申请提交
|
||||
- 活动报名
|
||||
- 状态变更
|
||||
- 服务记录提交
|
||||
- 回访提交
|
||||
- 文件关联
|
||||
- 微信回调（若未来有）
|
||||
|
||||
方案：
|
||||
|
||||
- clientRequestId / idempotencyKey
|
||||
- 数据库唯一索引
|
||||
- 事务
|
||||
- 必要时 Redis 短锁
|
||||
|
||||
---
|
||||
|
||||
## 11. 可观测性
|
||||
|
||||
必须：
|
||||
|
||||
- requestId
|
||||
- structured logging
|
||||
- error tracking
|
||||
- health endpoint
|
||||
- readiness/liveness
|
||||
- 慢接口日志
|
||||
- 数据库慢查询
|
||||
- 关键任务状态
|
||||
|
||||
日志中禁止敏感数据。
|
||||
|
||||
---
|
||||
|
||||
## 12. 备份
|
||||
|
||||
至少：
|
||||
|
||||
- MySQL 每日自动备份；
|
||||
- 保留 7/30 天策略可配置；
|
||||
- 对象存储版本/生命周期按预算配置；
|
||||
- 每季度至少做一次恢复演练；
|
||||
- 恢复步骤写入 `infra/backup/README.md`。
|
||||
|
||||
备份成功≠可恢复，必须验证恢复。
|
||||
Reference in New Issue
Block a user