lehuo/乐活公益小程序_Codex开发总文档_V1.0.md

<!-- FILE: 00_README_FIRST.md -->

# 乐活公益·暖心服务平台 —— Codex 开发文档包

> 版本：V1.0  
> 文档用途：作为 Codex / AI 编程智能体的长期开发上下文、项目规则和验收依据。  
> 最高原则：任何代码实现不得偏离本目录文档。发生冲突时，按本文档规定的优先级处理。

---

## 1. 项目一句话定义

“乐活公益·暖心服务平台”不是公益宣传页，而是一套以微信小程序为公众入口、Web 管理后台为工作人员入口、以“需求申请 → 受理评估 → 建档 → 派单 → 服务 → 反馈 → 回访 → 持续关爱”为核心闭环的公益服务数字化平台。

主要服务领域：

1. 关爱老年人、为老服务；
2. 困境妇女慈善帮扶；
3. 困境儿童关爱与帮扶；
4. 残疾人爱心救助与帮扶；
5. 其他困难群体服务；
6. 志愿者组织、公益活动、公益资源和社会参与。

---

## 2. Codex 每次开始工作前必须执行

按顺序阅读：

1. `00_README_FIRST.md`
2. `01_PROJECT_CONSTITUTION.md`
3. `02_PRODUCT_PRD_V1.md`
4. `03_ARCHITECTURE.md`
5. `04_DATA_MODEL.md`
6. `05_API_AND_WORKFLOW.md`
7. `06_SECURITY_PRIVACY.md`
8. `07_UI_UX.md`
9. `08_ENGINEERING_RULES.md`
10. `09_TEST_ACCEPTANCE.md`
11. `10_TASK_STATE.md`
12. `11_DECISIONS.md`

如果只是小范围修复，也至少必须阅读：

- `01_PROJECT_CONSTITUTION.md`
- `10_TASK_STATE.md`
- 与修改模块相关的文档
- `11_DECISIONS.md`

不得仅根据聊天中最近一句话修改项目。

---

## 3. 开发结束后必须回写

每完成一个任务，必须：

1. 更新 `10_TASK_STATE.md`；
2. 若产生架构/技术/业务决策，更新 `11_DECISIONS.md`；
3. 若接口变化，更新 API 文档；
4. 若表结构变化，更新数据模型与 migration；
5. 增加或更新自动化测试；
6. 执行 lint、typecheck、unit test、integration test、build；
7. 输出本次变更摘要、影响范围、风险、回滚方式。

禁止“只改代码、不改文档”。

---

## 4. 冲突处理优先级

从高到低：

1. 数据安全、隐私、法律合规；
2. `01_PROJECT_CONSTITUTION.md` 中的硬约束；
3. 已确认的产品业务规则；
4. 数据一致性和可审计性；
5. API 契约；
6. UI/UX 规范；
7. 工程偏好；
8. Codex 自己认为“更先进”的方案。

如果 Codex 认为有更好的方案，但会改变既有边界，必须记录到 `11_DECISIONS.md` 的“待确认建议”，不能擅自实施。

---

## 5. 代码仓库建议结构

```text
lehuo-public-service/
├─ apps/
│  ├─ miniprogram/       # 微信小程序
│  ├─ admin-web/         # Web 管理后台
│  └─ api/               # 后端 API
├─ packages/
│  ├─ contracts/         # DTO / enum / schema / API 契约
│  ├─ shared/            # 无业务副作用的共享代码
│  ├─ eslint-config/
│  └─ tsconfig/
├─ infra/
│  ├─ docker/
│  ├─ nginx/
│  ├─ scripts/
│  └─ backup/
├─ docs/
│  ├─ 本文档包
│  └─ diagrams/
├─ migrations/
├─ .env.example
├─ pnpm-workspace.yaml
├─ package.json
├─ AGENTS.md
└─ README.md
```

---

## 6. AGENTS.md 必须包含

仓库根目录 `AGENTS.md` 应复制以下核心规则：

- 先读 `docs/00_README_FIRST.md` 与 `docs/01_PROJECT_CONSTITUTION.md`。
- 不擅自改变产品定位、技术栈、数据库类型、认证方式。
- 不删除既有功能来“简化实现”。
- 不通过 mock 假装功能完成。
- 不将敏感信息写入日志。
- 每个业务状态变化必须可审计。
- 所有表结构变化必须 migration。
- 所有 API 变更必须同步 contracts。
- 完成任务必须更新 `docs/10_TASK_STATE.md`。
- 任何架构决策必须更新 `docs/11_DECISIONS.md`。
- 不因“AI认为更合理”而推翻已经批准的业务规则。

<!-- FILE: 01_PROJECT_CONSTITUTION.md -->

# 01 项目开发宪法（不可随意修改）

## 1. 产品定位硬约束

本项目必须始终是：

> 公益服务数字化平台，而不是宣传网站、商城、社交平台或复杂互联网平台。

V1.0 第一目标：让真实服务闭环跑通。

主链路：

```text
服务对象/代申请人提交需求
→ 工作人员受理
→ 需求评估
→ 建立/关联服务对象档案
→ 创建服务工单
→ 分配工作人员/志愿者
→ 执行服务
→ 留痕
→ 服务对象确认/反馈
→ 回访
→ 必要时继续跟进
```

任何新功能都必须回答：“是否增强这条主链路？”

---

## 2. 用户体验硬约束

1. 小程序优先服务普通群众、老人和低数字技能用户。
2. 主要操作不得依赖复杂手势。
3. 核心按钮大、清楚、可理解。
4. 服务申请尽量在 3~4 个步骤内完成。
5. 表单遵循“少填、可选、可拍、可说、可代办”。
6. 不在前端暴露技术术语、内部状态码。
7. 不为了视觉炫技牺牲加载速度和可理解性。
8. 所有失败状态必须给普通人能看懂的说明与下一步动作。
9. 适老化不是“放大字体”这么简单，必须包含点击区域、对比度、信息密度、步骤数量、错误恢复能力。
10. 功能完成度优先于动画和装饰。

---

## 3. 技术硬约束

1. 国内网络环境可稳定开发、构建、部署和访问。
2. 微信小程序作为公众端。
3. Web 管理后台作为机构工作人员端。
4. 后端采用模块化单体优先，V1.0 禁止为了“先进”拆微服务。
5. MySQL 为核心关系数据库。
6. Redis 只用于缓存、限流、短期状态等可恢复数据，不作为业务事实唯一存储。
7. 文件不保存到应用容器本地磁盘；生产环境使用对象存储。
8. 必须 Docker 化。
9. 环境分 dev / test / staging / prod。
10. 配置必须环境变量化，禁止把密钥提交 Git。
11. 所有数据库修改必须 migration。
12. 生产部署必须有备份、恢复、日志、监控和健康检查。
13. 对外部供应商能力必须封装 Adapter，不让业务层直接绑定云厂商 SDK。
14. V1.0 不引入 Kubernetes。
15. V1.0 不引入复杂事件总线，必要异步任务先使用可靠 Job/Queue 模式。

---

## 4. 安全硬约束

平台会处理老人、困境妇女、儿童、残疾人、困难家庭等敏感服务信息。

必须做到：

- 默认最小权限；
- 后台 RBAC；
- 资源级权限校验；
- 敏感字段脱敏；
- 操作审计；
- 不允许越权查询；
- 不允许通过 ID 枚举他人服务记录；
- 数据导出必须受控；
- 文件下载必须鉴权；
- 上传文件做类型、大小、扩展名、MIME 校验；
- Token、手机号、身份证件、地址、儿童信息不得写入普通日志；
- 删除业务数据优先软删除/归档，禁止随意物理删除；
- 关键状态变更保留历史；
- 不满 14 周岁相关信息按监护人授权与更严格权限原则处理；
- 不把真实生产数据复制到开发环境；
- 测试数据必须脱敏或生成。

---

## 5. 可靠性硬约束

1. 所有写请求应支持幂等或防重复提交。
2. 重要状态迁移必须使用数据库事务。
3. 不允许“接口成功但数据库只写了一半”。
4. 异步任务失败必须可重试、可查询。
5. 外部服务失败不能拖垮主业务。
6. 外部短信、订阅消息、对象存储失败应有降级和补偿。
7. 服务工单状态必须经过状态机校验，不能任意改字符串。
8. 每个关键实体保留 `created_at / updated_at / created_by / updated_by`。
9. 每个关键业务操作有 audit log。
10. 任何“已完成”都必须有可验证结果，不能只靠前端显示。

---

## 6. 易维护硬约束

- 避免自研基础组件；
- 避免魔法数字；
- 枚举集中管理；
- DTO 与数据库 Entity 分离；
- Controller 不写复杂业务；
- Service 不直接散落第三方 SDK；
- Repository 层负责数据访问；
- 公共错误码统一；
- 日志统一；
- 配置集中；
- 每个模块有 README 或模块说明；
- 复杂逻辑写测试；
- 删除代码前检查是否有业务依赖；
- 依赖升级必须经过测试，不追新版本。

---

## 7. V1.0 禁止范围

除非后续明确批准，V1.0 禁止：

- 在线公开募捐核心交易系统；
- 复杂社交/朋友圈；
- 即时 IM 聊天系统自研；
- AI 自动作出救助资格决定；
- 人脸识别；
- 未经必要性论证收集身份证完整信息；
- 微服务/K8s；
- 大数据平台；
- 区块链；
- 自研工作流引擎；
- 复杂积分商城；
- 过度游戏化；
- 对外开放 API 平台；
- 多租户 SaaS 架构。

---

## 8. AI 功能原则

AI 是效率工具，不是 V1.0 主角。

后续 AI 必须：

- 默认建议、不自动做高风险决定；
- AI 结果明确标记；
- 工作人员确认后才写入正式业务记录；
- 不把敏感数据发送到未经批准的外部模型；
- 能关闭；
- 业务流程不依赖 AI 才能运行。

<!-- FILE: 02_PRODUCT_PRD_V1.md -->

# 02 V1.0 产品需求文档（PRD）

## 1. V1.0 目标

交付可真实投入公益服务的第一版：

- 群众能找到服务、提交申请、看进度、给反馈；
- 家属/社区/志愿者能代申请；
- 工作人员能受理、建档、派单、留痕、回访；
- 志愿者能注册、报名活动；
- 管理员能管理项目、内容、人员、权限和统计。

---

## 2. 用户角色

### 2.1 PUBLIC

普通公众。浏览公益项目、活动、组织介绍、参与入口。

### 2.2 APPLICANT

申请人。可以是服务对象本人，也可以是代申请人。

### 2.3 BENEFICIARY

服务对象。老人、困境妇女、困境儿童、残疾人及其他困难群体。

### 2.4 VOLUNTEER

志愿者。

### 2.5 STAFF

公益工作人员。

### 2.6 PROJECT_MANAGER

公益项目负责人。

### 2.7 ADMIN

系统管理员。

### 2.8 SUPER_ADMIN

仅限极少数技术/管理人员，用于系统级配置，日常不使用。

---

## 3. 小程序信息架构

底部 Tab 建议：

1. 首页
2. 服务
3. 公益
4. 我的

### 首页

- Logo/品牌语
- 我需要帮助
- 帮他人申请
- 为老服务
- 妇女帮扶
- 儿童关爱
- 残疾人帮扶
- 最新公益项目
- 最新活动
- 我要做公益

### 服务

- 服务分类
- 服务申请
- 我的申请
- 服务进度
- 我的反馈
- 联系乐活

### 公益

- 公益项目
- 公益动态
- 公益活动
- 志愿者招募
- 企业/资源合作
- 乐活公益介绍

### 我的

根据身份动态显示：

- 微信登录/绑定手机号
- 我的资料
- 我的服务申请
- 我的活动
- 志愿者资料
- 我的志愿服务
- 消息
- 隐私设置
- 联系客服

---

## 4. 服务申请

### 4.1 申请类型

- OLD_AGE：老年关爱/为老服务
- WOMEN：困境妇女
- CHILD：困境儿童
- DISABILITY：残疾人帮扶
- LIFE_DIFFICULTY：生活困难
- OTHER：其他

### 4.2 申请身份

- SELF：本人申请
- FAMILY：家属代申请
- COMMUNITY：社区/机构代申请
- VOLUNTEER：志愿者代申请
- OTHER：其他

### 4.3 最小字段

- 服务类别
- 申请人与服务对象关系
- 服务对象姓名或称呼
- 联系方式
- 所在区域（不默认要求精确门牌）
- 需求描述
- 隐私授权确认

### 4.4 可选字段

- 图片/附件
- 期望联系时间
- 是否行动不便
- 是否需要上门
- 紧急程度（用户只能表达，最终等级由工作人员评估）
- 语音描述（二期可增强）

### 4.5 提交

提交后：

- 生成不可预测的业务编号；
- 显示“已收到”；
- 明确说明后续由工作人员联系；
- 不承诺超出机构能力的即时救援；
- 若用户选择明显紧急风险，应提示联系 110/120 等适当公共紧急服务，但具体文案由运营审核。

---

## 5. 服务申请状态机

```text
SUBMITTED
  ↓
PENDING_CONTACT
  ↓
ASSESSING
  ├─→ REJECTED/OUT_OF_SCOPE
  ├─→ REFERRED
  ↓
ACCEPTED
  ↓
SERVICE_PLANNED
  ↓
IN_SERVICE
  ↓
SERVICE_COMPLETED
  ↓
FOLLOW_UP_PENDING
  ↓
CLOSED
```

可增加：

- CANCELLED
- SUSPENDED

规则：

- 状态变化必须记录历史；
- 不可跳过关键节点，除管理员执行带原因的纠正操作；
- 关闭后再次产生需求，应创建新申请/跟进记录，而不是覆盖旧记录。

---

## 6. 服务对象档案

每个 Beneficiary 一人一档。

核心字段：

- 基础身份
- 联系信息
- 联系人/监护人
- 所属服务类别
- 地址分级信息
- 风险/关爱标签
- 备注
- 是否重点关爱
- 档案状态

严禁把所有信息塞入一个 JSON 字段。

儿童、残疾、健康、家庭困难等敏感字段应按实际必要性分表/分域并控制权限。

---

## 7. 工单

服务申请被接受后创建 Service Case / Work Order。

字段：

- 工单编号
- beneficiary_id
- application_id
- project_id（可空）
- 服务类别
- 负责人
- 计划日期
- 服务地点
- 服务说明
- 当前状态
- 优先级
- 完成时间
- 结果摘要
- 后续计划

工单可关联多个执行人/志愿者，但只有一个责任负责人。

---

## 8. 服务记录

一次工单可有多次服务记录。

记录：

- 服务时间
- 服务类型
- 服务人员
- 服务内容
- 服务结果
- 图片附件
- 服务对象确认情况
- 后续建议
- 创建人

服务记录创建后若修改，必须保留修订痕迹或审计日志。

---

## 9. 回访

回访任务来源：

- 服务完成自动创建；
- 重点关爱对象周期任务；
- 工作人员手工创建。

回访结果：

- SATISFIED
- GENERALLY_SATISFIED
- UNSATISFIED
- NEED_MORE_HELP
- UNREACHABLE
- OTHER

若 `NEED_MORE_HELP`：

- 必须支持一键创建后续申请/工单；
- 不能只保存文字然后无人处理。

---

## 10. 志愿者

注册字段遵循最小必要：

- 姓名
- 手机
- 所在区域
- 可服务时间
- 技能标签
- 感兴趣领域
- 紧急联系人（仅确有管理需要时）
- 志愿者状态

状态：

- APPLIED
- APPROVED
- REJECTED
- SUSPENDED
- INACTIVE

志愿者默认不能查看完整服务对象档案。

---

## 11. 公益活动

活动：

- 标题
- 封面
- 项目
- 时间
- 地点
- 招募人数
- 报名截止时间
- 说明
- 状态

状态：

- DRAFT
- PUBLISHED
- REGISTRATION_CLOSED
- IN_PROGRESS
- COMPLETED
- CANCELLED

报名：

- 用户
- 志愿者身份
- 报名时间
- 审核状态
- 签到状态
- 服务时长

---

## 12. 公益项目

项目用于：

- 展示；
- 归集服务工单；
- 统计服务成果；
- 后续政府购买服务项目管理。

V1 字段：

- 项目名称
- 项目类别
- 简介
- 详细介绍
- 封面
- 项目周期
- 状态
- 是否公开
- 负责人
- 目标人数（可空）
- 排序

---

## 13. 内容管理

内容类型：

- 机构介绍
- 公益动态
- 服务故事
- 通知公告
- 常见问题

内容必须支持草稿和发布，不允许编辑即立即对外。

涉及服务对象故事：

- 必须有内容审核流程；
- 展示前脱敏；
- 未授权不得公开身份性信息。

---

## 14. 消息通知

V1：

- 站内消息
- 微信订阅消息（按微信平台能力和用户授权使用）

事件：

- 申请提交
- 申请状态变化
- 服务安排
- 服务完成
- 待评价/回访
- 活动报名结果

通知失败不能回滚主交易。

---

## 15. Web 后台

一级菜单：

- 工作台
- 服务申请
- 服务工单
- 服务对象
- 回访管理
- 公益项目
- 公益活动
- 志愿者
- 内容管理
- 数据统计
- 用户与权限
- 系统设置
- 审计日志（高权限）

工作台至少展示：

- 新申请
- 待联系
- 评估中
- 服务中
- 待回访
- 今日服务
- 超期任务
- 重点关爱提醒

---

## 16. 数据统计 V1

统计以真实业务数据计算：

- 申请数
- 受理数
- 完成服务数
- 服务人次
- 去重服务对象数
- 各服务类别数量
- 志愿者数量
- 活动数量
- 志愿服务时长

不得用手工填写数字覆盖真实统计结果。

<!-- FILE: 03_ARCHITECTURE.md -->

# 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`。

备份成功≠可恢复，必须验证恢复。

<!-- FILE: 04_DATA_MODEL.md -->

# 04 数据模型

## 1. 通用字段规范

核心表统一包含：

- id: bigint/uuid（二选一后固定；建议 bigint 内部主键 + public_id 随机ID）
- public_id: varchar，外部暴露，禁止连续可枚举
- created_at
- updated_at
- created_by（后台业务表适用）
- updated_by
- deleted_at（需要软删除的表）

时间统一数据库 UTC 存储，展示按 Asia/Shanghai。

---

## 2. 核心实体

### users

微信/后台统一用户主体，避免重复身份系统。

- id
- public_id
- status
- user_type
- mobile（加密/脱敏策略）
- nickname
- avatar_url
- last_login_at

### wechat_identities

- user_id
- openid
- unionid nullable
- appid
- created_at
  唯一索引 `(appid, openid)`。

### staff_profiles

- user_id
- employee_no nullable
- display_name
- department
- status

### roles / permissions / user_roles / role_permissions

标准 RBAC。

---

## 3. beneficiary_profiles

服务对象档案：

- id
- public_id
- display_name
- gender nullable
- birth_year nullable
- mobile nullable
- region_code
- address_detail_encrypted nullable
- primary_category
- key_care_flag
- status
- notes_encrypted nullable
- created_by
- timestamps

不要默认收集完整身份证。

---

## 4. beneficiary_contacts

- beneficiary_id
- name
- relation
- mobile
- is_guardian
- is_emergency_contact
- consent_record_id nullable

---

## 5. beneficiary_tags / tags

标签：

- 独居
- 高龄
- 行动不便
- 定期探访
- 困境儿童
  等。

标签只能帮助服务，不应成为歧视性画像。

---

## 6. service_applications

- id
- public_id
- application_no
- applicant_user_id nullable
- beneficiary_id nullable
- apply_mode
- service_category
- description
- region_code
- contact_name
- contact_mobile
- preferred_contact_time nullable
- urgency_self_report nullable
- evaluated_priority nullable
- status
- assigned_staff_id nullable
- source
- submitted_at
- accepted_at nullable
- closed_at nullable
- rejection_reason nullable
- referral_note nullable
- timestamps

索引：

- application_no unique
- status
- assigned_staff_id + status
- created_at
- service_category + created_at

---

## 7. service_application_status_history

- application_id
- from_status
- to_status
- operator_user_id
- reason
- created_at

不可更新，只追加。

---

## 8. service_cases

- id
- public_id
- case_no
- application_id
- beneficiary_id
- project_id nullable
- owner_staff_id
- category
- priority
- status
- planned_start_at nullable
- planned_end_at nullable
- service_location_encrypted nullable
- summary
- result_summary nullable
- follow_up_plan nullable
- completed_at nullable
- timestamps

---

## 9. case_assignees

支持多人协作：

- case_id
- user_id
- assignee_type STAFF/VOLUNTEER
- role
- assigned_at
- removed_at nullable

---

## 10. service_records

- id
- public_id
- case_id
- beneficiary_id
- service_start_at
- service_end_at nullable
- service_type
- content
- result
- follow_up_suggestion nullable
- beneficiary_confirm_status nullable
- created_by
- timestamps

---

## 11. follow_up_tasks

- id
- public_id
- beneficiary_id
- case_id nullable
- owner_staff_id
- due_at
- follow_up_type
- status
- result_code nullable
- result_note nullable
- completed_at nullable
- source
- timestamps

索引：

- owner_staff_id + status + due_at
- beneficiary_id + due_at

---

## 12. volunteers / volunteer_skills

volunteers：

- user_id
- real_name
- mobile
- region_code
- availability_note
- status
- approved_by nullable
- approved_at nullable

skills：

- volunteer_id
- skill_code

---

## 13. projects

- id
- public_id
- name
- category
- summary
- content
- cover_file_id
- manager_user_id
- start_date
- end_date
- target_people nullable
- status
- is_public
- sort_order
- timestamps

---

## 14. activities

- id
- public_id
- project_id nullable
- title
- summary
- content
- cover_file_id
- start_at
- end_at
- registration_deadline
- location_text
- capacity nullable
- status
- published_at nullable
- timestamps

---

## 15. activity_registrations

- activity_id
- user_id
- status
- registered_at
- checked_in_at nullable
- service_minutes nullable

唯一 `(activity_id,user_id)` 防重复报名。

---

## 16. content_posts

- id
- public_id
- type
- title
- summary
- content
- cover_file_id nullable
- status DRAFT/REVIEW/PUBLISHED/ARCHIVED
- author_user_id
- reviewer_user_id nullable
- published_at nullable
- timestamps

---

## 17. files

只保存元数据：

- id
- public_id
- storage_provider
- bucket
- object_key
- original_filename
- mime_type
- size
- sha256
- business_type
- uploader_user_id
- status
- created_at

前端不得直接拼接永久公网 URL。

---

## 18. consents

- id
- public_id
- user_id nullable
- beneficiary_id nullable
- consent_type
- version
- granted_by
- granted_at
- revoked_at nullable
- evidence_json（仅保存必要证明）
- ip_hash nullable
- created_at

---

## 19. audit_logs

只追加：

- id
- request_id
- actor_user_id
- actor_role
- action
- resource_type
- resource_public_id
- result
- metadata_json（不得含敏感明文）
- ip_hash
- user_agent_summary
- created_at

---

## 20. notifications / notification_deliveries

通知实体与发送记录分开，支持重试和追踪。

---

## 21. 数据库规则

1. 必须使用 FK 或由 ORM/服务保证等价完整性；禁止无约束“凭感觉关联”。
2. 唯一业务编号必须 unique。
3. 常查字段建组合索引。
4. 禁止对大文本字段滥建索引。
5. 金额如未来出现用 decimal，禁止 float。
6. 所有枚举在 contracts 中有单一事实来源。
7. migration 不允许 destructive change 直接上线。
8. 删除列采用“停用 → 迁移 → 验证 → 后续版本删除”。

<!-- FILE: 05_API_AND_WORKFLOW.md -->

# 05 API 与业务流程规范

## 1. API 命名

REST 为主。

示例：

- POST `/api/v1/auth/wechat/login`
- GET `/api/v1/me`
- POST `/api/v1/service-applications`
- GET `/api/v1/service-applications/:publicId`
- POST `/api/v1/admin/service-applications/:publicId/transition`
- POST `/api/v1/admin/service-cases`
- POST `/api/v1/admin/service-cases/:publicId/records`
- POST `/api/v1/admin/follow-ups/:publicId/complete`

不使用：

- `/getAllXXX`
- `/doSomething2`
- `/updateStatusDirectly`

---

## 2. 服务申请提交事务

伪代码：

```text
validate input
check idempotency key
resolve applicant user
create or leave beneficiary unlinked
create service_application
create initial status history
create audit log
commit
enqueue notification
return public_id + application_no
```

禁止在事务中等待第三方消息服务。

---

## 3. 受理

工作人员：

1. 打开申请；
2. 权限检查；
3. 联系服务对象；
4. 评估；
5. 可关联已有档案或建立档案；
6. ACCEPTED；
7. 创建 service_case；
8. 指定负责人；
9. 创建后续任务；
10. 通知用户。

“关联已有档案”必须防止同名误合并，至少依据手机号+人工确认等多个条件。

---

## 4. 服务执行

- 工单 `SERVICE_PLANNED → IN_SERVICE`
- 新增 service_record
- 上传附件
- 可多次服务
- 完成时填写 result_summary
- `IN_SERVICE → SERVICE_COMPLETED`
- 自动生成 follow_up_task

---

## 5. 回访

完成回访时：

- 写结果；
- 标记任务完成；
- 如果需要继续帮助，创建 linked application/case；
- 记录来源关系；
- 写 audit。

---

## 6. 文件上传

推荐流程：

1. 客户端申请上传凭证；
2. 后端检查业务权限和文件约束；
3. 生成短期上传签名或后端代理上传；
4. 上传完成后回调/确认；
5. 后端校验 object metadata；
6. files 表记录；
7. 业务表关联 file_id。

安全约束：

- 文件大小限制；
- MIME 白名单；
- 扩展名白名单；
- object key 随机；
- 禁止使用原始文件名作路径；
- 图片需要时进行安全转码；
- 下载使用短时签名 URL；
- 私有 Bucket 默认。

---

## 7. 分页

统一 cursor 或 page/pageSize。V1 可使用：

- page >= 1
- pageSize 默认 20，最大 100

返回：

```json
{
  "items": [],
  "page": 1,
  "pageSize": 20,
  "total": 120
}
```

---

## 8. 搜索

后台允许按：

- 业务编号
- 姓名/称呼
- 脱敏手机号后四位（视实现）
- 服务类别
- 状态
- 时间
- 项目
- 负责人

敏感全文搜索能力应谨慎开放。

---

## 9. 导出

任何导出：

- 必须权限校验；
- 记录审计；
- 限制数据范围；
- 大数据量异步生成；
- 文件有过期时间；
- 默认脱敏；
- 导出儿童等敏感信息需要更高权限。

---

## 10. 错误码

至少：

- AUTH_REQUIRED
- FORBIDDEN
- RESOURCE_NOT_FOUND
- VALIDATION_ERROR
- DUPLICATE_REQUEST
- INVALID_STATE_TRANSITION
- APPLICATION_NOT_FOUND
- CASE_NOT_FOUND
- VOLUNTEER_NOT_APPROVED
- ACTIVITY_FULL
- REGISTRATION_CLOSED
- FILE_TYPE_NOT_ALLOWED
- FILE_TOO_LARGE
- RATE_LIMITED
- INTERNAL_ERROR

用户端错误文案必须友好，日志保留 requestId 便于排障。

<!-- FILE: 06_SECURITY_PRIVACY.md -->

# 06 安全、隐私与合规基线

> 本文是工程基线，不替代正式法律意见。上线前应由运营主体根据实际收集信息、服务范围和微信平台规则完成隐私政策、用户协议和必要合规审核。

## 1. 数据分类

### L1 公开

公益项目公开介绍、公开活动、组织联系方式。

### L2 内部

普通内部运营信息、非敏感统计。

### L3 敏感业务

服务申请详情、家庭困难、住址、联系方式、服务记录。

### L4 高敏感

儿童个人信息、监护信息、健康/残疾相关详细信息、证件、特殊风险记录。

默认 L3/L4 不得公开。

---

## 2. 最小收集

每个字段进入系统前必须回答：

- 为什么需要？
- 不收集是否仍能提供服务？
- 保存多久？
- 谁能看？
- 是否可脱敏？
- 是否真的需要精确地址/证件？

没有明确目的不得新增收集项。

---

## 3. 未成年人

不满 14 周岁相关个人信息必须采用更严格保护：

- 明确监护人角色；
- 记录同意；
- 限制访问人员；
- 默认不公开案例身份；
- 不允许志愿者看到与任务无关的信息；
- 定期审计访问；
- 允许合法更正、删除/撤回等请求按规则处理。

---

## 4. 加密

传输：

- 全站 HTTPS/TLS。

存储：

- 云盘/数据库基础加密按环境开启；
- 极敏感字段应用层加密；
- 密钥不与数据库同库；
- 密钥通过云 KMS/Secret Manager 或安全环境变量管理。

密码：

- Argon2id 或 bcrypt 强哈希；
- 禁止 MD5/SHA1 直接存密码。

---

## 5. 手机号和地址

显示：

- 普通列表默认脱敏，例如 138****1234；
- 详细查看必须权限。

查询：

- 如需精确匹配可存 HMAC/hash 辅助索引；
- 明文/密文设计需避免为搜索而降低保护。

---

## 6. 日志

禁止记录：

- 身份证完整号码
- 完整手机号
- openid
- access token
- session token
- 详细住址
- 儿童档案内容
- 服务描述全文
- 上传文件原文

允许：

- public_id
- requestId
- action code
- status
- 耗时
- 脱敏 actor 信息

---

## 7. OWASP 基线

必须防：

- SQL injection
- XSS
- CSRF（后台 Cookie 认证时）
- SSRF
- IDOR/BOLA
- path traversal
- unrestricted upload
- mass assignment
- brute force
- credential stuffing
- rate abuse
- insecure direct object reference

每个资源 API 后端都做授权，不相信前端按钮是否隐藏。

---

## 8. 限流

按场景设置：

- 登录
- 验证码
- 服务申请
- 文件上传
- 搜索
- 导出
- 微信登录 exchange

不能只按 IP，必要时组合 user/device/IP。

---

## 9. 审计事件

至少审计：

- 登录成功/失败
- 角色权限修改
- 查看高敏感档案
- 新增/修改服务对象
- 服务申请状态变化
- 工单分配
- 服务记录修改
- 导出
- 删除/归档
- 隐私同意变化
- 系统配置变化

---

## 10. 数据保留

不要永久保留所有数据。

必须由运营方定义：

- 服务档案保存期限；
- 未成年人数据期限；
- 日志期限；
- 导出文件期限；
- 已取消授权后的处理；
- 项目验收要求。

程序上把保留策略做成可配置任务，而不是散落代码。

---

## 11. 权限矩阵核心原则

### Volunteer

只能：

- 看自己被分配任务；
- 看完成服务所需的最小信息；
- 提交服务记录；
  不能：
- 搜索全体服务对象；
- 导出名单；
- 看完整历史档案。

### Staff

按负责范围访问。

### Project Manager

按项目访问。

### Admin

跨项目业务管理，但高敏感导出仍可要求额外权限。

### Super Admin

系统维护，不等于默认业务数据无限查看；高敏感读取同样审计。

---

## 12. 安全发布门禁

上线前必须：

- npm/pnpm dependency audit
- secret scan
- SAST 基础扫描
- API 权限测试
- 越权测试
- 文件上传测试
- SQL 注入/XSS 测试
- 弱密码/暴力登录测试
- 备份恢复测试
- staging 冒烟测试

发现 Critical/High 安全问题不得上线。

<!-- FILE: 07_UI_UX.md -->

# 07 UI/UX 与适老化规范

## 1. 视觉原则

关键词：

- 温暖
- 可信
- 简洁
- 清楚
- 不商业化
- 不花哨

不得做：

- 密集 Banner
- 过多卡片
- 首页十几个同级入口
- 小字号说明堆叠
- 复杂渐变和强动画
- 倒计时/诱导点击式设计

---

## 2. 小程序首页优先级

P0：

1. 我需要帮助
2. 帮他人申请

P1：3. 四大服务类别 4. 我的服务进度

P2：5. 公益项目 6. 公益活动 7. 我要做公益

宣传内容不能挤压服务入口。

---

## 3. 适老规范

建议基线：

- 正文字号尽量 >= 16px 等效视觉；
- 主要按钮文字 >= 17px 等效视觉；
- 主要点击区域高度约 48px 以上；
- 按钮间距足够；
- 一屏只做一个主要决定；
- 错误提示紧贴字段；
- 表单支持保存草稿（较长时）；
- 不用颜色作为唯一状态表达；
- 图标同时配文字；
- 返回动作清晰；
- 网络失败可重试；
- 提交后明确“已成功”。

具体像素可在设计系统中统一，不以本建议替代微信设备适配。

---

## 4. 表单原则

一页最多 5~7 个核心输入。
复杂申请拆步骤：

1. 需要什么帮助
2. 帮谁申请
3. 联系方式与地区
4. 需求描述
5. 确认提交

可选信息放“补充信息”。

---

## 5. 文案

使用：

- “我需要帮助”
- “帮家人申请”
- “工作人员正在联系您”
- “还需要继续帮助”
- “重新提交”

避免：

- “创建工单”
- “状态流转”
- “Beneficiary”
- “Record Not Found”
- “非法参数”

---

## 6. 空状态

例如没有服务申请：
“您还没有提交过服务申请。如果您或家人需要帮助，可以从这里开始。”

提供明确按钮。

---

## 7. 错误恢复

提交失败不能清空已填表单。
上传失败允许单文件重试。
网络失败保持本地草稿。
重复点击提交不应生成多个申请。

---

## 8. 管理后台

后台目标：让工作人员每天打开工作台就知道做什么。

表格：

- 默认显示业务必要列；
- 手机、地址默认脱敏；
- 常用筛选固定；
- 详情采用清晰分区；
- 状态颜色+文字；
- 危险操作二次确认并说明影响。

禁止为了“企业感”做过密 Dashboard。

---

## 9. 无障碍

- 合理对比度；
- 图片提供语义说明（可用场景）；
- 表单 label 明确；
- 键盘操作兼容后台；
- focus 可见；
- 不用仅 hover 才出现核心操作。

<!-- FILE: 08_ENGINEERING_RULES.md -->

# 08 工程开发规则

## 1. Monorepo

推荐 pnpm workspace。

根命令：

```bash
pnpm install
pnpm lint
pnpm typecheck
pnpm test
pnpm build
```

必须保证 CI 与本地命令一致。

---

## 2. 包管理

- 锁定 package manager 版本；
- 提交 lockfile；
- 不混 npm/yarn/pnpm；
- 国内开发可配置可靠 npm 镜像，但源码不得依赖私有个人镜像；
- CI 应支持官方源回退。

---

## 3. TypeScript

- strict: true
- 禁止大面积 any
- 禁止 `@ts-ignore` 掩盖错误；特殊情况写原因
- API contracts 明确类型
- 日期统一 ISO 8601

---

## 4. Git

分支：

- main
- develop（可选）
- feature/*
- fix/*
- chore/*

Commit 建议 Conventional Commits。

每个 PR：

- 变更摘要
- 测试结果
- 截图（UI）
- migration 说明
- 风险
- 回滚方案

---

## 5. 环境变量

`.env.example` 只能放占位符。

示例：

```env
APP_ENV=development
DATABASE_URL=
REDIS_URL=
WECHAT_APP_ID=
WECHAT_APP_SECRET=
COS_BUCKET=
COS_REGION=
COS_SECRET_ID=
COS_SECRET_KEY=
SESSION_SECRET=
FIELD_ENCRYPTION_KEY=
```

真实密钥不得入 Git。

---

## 6. 数据库 Migration

规则：

- 每次 schema 修改一份 migration；
- migration 可审查；
- 生产不允许 ORM 自动 `synchronize=true`；
- 大表变更考虑锁；
- destructive migration 分阶段。

---

## 7. 代码质量

函数：

- 单一职责；
- 复杂度高就拆；
- 业务规则命名表达含义；
- 不写 1000 行 service；
- 不复制粘贴权限逻辑。

必须有：

- lint
- format
- typecheck
- unit test
- integration test

---

## 8. 错误处理

后端：

- 业务错误使用统一 Domain/Application Error；
- 未预期错误不把 stack 返回用户；
- requestId 贯穿。

前端：

- 业务错误直接友好提示；
- 网络错误可重试；
- 401 统一重新登录；
- 403 明确无权限；
- 5xx 提供 requestId。

---

## 9. 第三方依赖

新增依赖前：

1. 是否真有必要？
2. 是否长期维护？
3. License 是否可用？
4. 是否显著增大 bundle？
5. 是否国内网络可获取？
6. 能否用现有依赖实现？

避免“为了 10 行代码引入一个包”。

---

## 10. Codex 禁止行为

- 不读文档直接重构；
- 看到旧代码就全量重写；
- 为通过测试删除测试；
- 用 mock 替代真实功能后宣称完成；
- 注释掉权限；
- 关闭类型检查；
- `catch {}` 吞错误；
- 生产环境 hardcode；
- 把敏感值写 fixtures；
- 删除 migration 历史；
- 改 API 不更新前端和 contracts；
- 自己决定产品删减。

---

## 11. Definition of Done

一个任务只有同时满足以下条件才算完成：

- 功能实现；
- 正常路径测试；
- 异常路径测试；
- 权限测试；
- 数据 migration 完成；
- 文档更新；
- lint 通过；
- typecheck 通过；
- test 通过；
- build 通过；
- 无新 High/Critical 漏洞；
- `10_TASK_STATE.md` 已回写。

<!-- FILE: 09_TEST_ACCEPTANCE.md -->

# 09 测试与验收

## 1. 测试金字塔

### Unit

业务规则、状态机、权限策略、计算。

### Integration

API + DB，重点测试事务、唯一约束、权限和状态流转。

### E2E

关键业务闭环。

---

## 2. P0 E2E 场景

### E2E-001 本人申请

用户登录 → 选择老年服务 → 填写需求 → 提交 → 获得编号 → 我的申请可见。

### E2E-002 防重复

用户连续点击提交两次 → 只能产生一个业务申请。

### E2E-003 代申请

家属为老人申请 → 正确保存申请人与服务对象关系。

### E2E-004 工作人员受理

工作人员登录 → 查看待处理 → 联系/评估 → 建档 → 受理 → 创建工单。

### E2E-005 服务执行

负责人 → 开始服务 → 添加两条服务记录 → 完成 → 自动生成回访任务。

### E2E-006 回访继续帮扶

回访选择“需要继续帮助” → 生成关联后续任务/申请，原历史不丢失。

### E2E-007 越权

志愿者 A 访问志愿者 B 的工单 → 403。

### E2E-008 用户越权

用户 A 猜测用户 B 的 public_id → 404/403，不泄露存在性。

### E2E-009 活动报名

报名 → 重复报名被唯一约束阻止 → 人数达到上限后不可继续报名。

### E2E-010 文件

允许图片上传；exe/php/html 等危险类型拒绝；超限拒绝；私有文件无授权无法下载。

---

## 3. 安全验收

必须测试：

- IDOR
- broken access control
- mass assignment
- SQLi
- stored/reflected XSS
- CSRF（后台）
- upload bypass
- rate limit
- brute force
- token expiry
- session fixation
- sensitive log leakage

---

## 4. 可靠性验收

模拟：

- Redis 不可用；
- COS 暂时失败；
- 微信消息发送失败；
- 数据库瞬时错误；
- 客户端重复请求；
- 网络超时。

要求：

- 主业务不产生半状态；
- 可重试；
- 失败可追踪；
- UI 不假成功。

---

## 5. 性能目标（V1 建议基线）

不是大型互联网项目，不盲目追极限。

建议：

- 常规 API P95 < 500ms（不含第三方和大文件）
- 后台列表首屏合理数据量 < 2s
- 小程序首页优先内容快速可见
- 100 并发常规请求下无明显错误率上升
- 数据库常用列表避免 N+1

具体目标可根据云资源实测调整。

---

## 6. UAT 验收人员

至少模拟：

- 65+ 老年服务对象
- 家属代申请
- 普通工作人员
- 项目负责人
- 志愿者
- 管理员

UAT 不只让开发人员自测。

---

## 7. V1 上线门槛

必须全部满足：

- P0 E2E 全通过；
- 无 Critical/High 已知安全漏洞；
- 备份成功；
- 恢复演练通过；
- staging 走完整闭环；
- 隐私政策/授权页面就绪；
- 微信小程序审核所需材料就绪；
- 监控和告警正常；
- 可回滚上一版本。

<!-- FILE: 10_TASK_STATE.md -->

# 10 任务状态（Codex 每次必须维护）

> 这是项目“长记忆”的核心文件之一。禁止删除历史，仅更新状态并添加记录。

## 当前阶段

`PHASE_0 - 仓库初始化与技术基线`

## 当前版本目标

`V1.0 MVP：跑通公益服务主闭环`

---

## 阶段任务

### Phase 0：工程初始化

- [ ] 建立 monorepo
- [ ] 建立 miniprogram
- [ ] 建立 admin-web
- [ ] 建立 api
- [ ] 建立 shared contracts
- [ ] Docker Compose 本地环境
- [ ] MySQL / Redis / MinIO
- [ ] ESLint / Prettier / TSConfig
- [ ] CI
- [ ] health check
- [ ] 环境变量模板
- [ ] AGENTS.md

### Phase 1：认证与权限

- [ ] 微信登录
- [ ] 后台登录
- [ ] user
- [ ] RBAC
- [ ] resource policy
- [ ] audit baseline

### Phase 2：服务申请

- [ ] 服务分类
- [ ] 本人申请
- [ ] 代申请
- [ ] 我的申请
- [ ] 状态历史
- [ ] 防重复提交
- [ ] 后台申请列表/详情

### Phase 3：服务对象与工单

- [ ] beneficiary 档案
- [ ] 联系人/监护人
- [ ] 标签
- [ ] 工单
- [ ] 分配工作人员
- [ ] 志愿者协作
- [ ] 服务记录
- [ ] 附件

### Phase 4：回访闭环

- [ ] 回访任务
- [ ] 自动创建
- [ ] 完成回访
- [ ] 继续帮扶
- [ ] 工作台待办

### Phase 5：公益项目/活动/志愿者

- [ ] 项目 CRUD/发布
- [ ] 活动
- [ ] 活动报名
- [ ] 志愿者申请/审核
- [ ] 服务时长

### Phase 6：内容与通知

- [ ] 公益动态
- [ ] 机构介绍
- [ ] 内容审核状态
- [ ] 站内消息
- [ ] 微信订阅通知 Adapter

### Phase 7：统计、安全与上线

- [ ] 基础统计
- [ ] 导出
- [ ] 权限扫描
- [ ] 安全测试
- [ ] 备份恢复
- [ ] staging
- [ ] UAT
- [ ] production deployment

---

## 当前正在处理

暂无。Codex 第一次执行时填写。

---

## 最近完成记录

格式：

```text
YYYY-MM-DD
任务：
完成：
测试：
涉及 migration：
文档变化：
遗留问题：
```

---

## 已知问题

首次开发为空。任何未解决问题必须写这里，禁止只留在聊天上下文。

---

## 下一步

从 Phase 0 依次执行。禁止跳到 AI、地图、复杂报表等后续功能。

<!-- FILE: 11_DECISIONS.md -->

# 11 架构与产品决策日志（ADR 简化版）

> Codex 不得删除已批准决策。新决策追加。

## D-001 产品架构

状态：ACCEPTED

决定：
V1 使用“微信小程序 + Web 管理后台 + 单体 API + MySQL + Redis + 对象存储”。

原因：
低复杂度、易部署、易维护、适合当前组织规模。

---

## D-002 后端架构

状态：ACCEPTED

决定：
模块化单体，不采用微服务。

触发重新评估条件：

- 单体部署已形成明确性能瓶颈；
- 团队规模显著扩大；
- 某模块有独立扩容/安全隔离的客观需求。

---

## D-003 主技术语言

状态：ACCEPTED

决定：
优先 TypeScript 全栈。

原因：
前后端共享类型、Codex 开发一致性高、维护人员切换成本较低。

---

## D-004 数据库

状态：ACCEPTED

决定：
MySQL 作为业务事实数据库。
Redis 不保存不可恢复的唯一业务事实。

---

## D-005 文件

状态：ACCEPTED

决定：
生产文件进入私有对象存储，通过授权临时访问；不持久化在应用容器本地盘。

---

## D-006 V1 范围

状态：ACCEPTED

决定：
V1 首先实现服务闭环、志愿者、项目活动、内容和基础统计，不做复杂 AI、地图、公开募捐、自研 IM。

---

## D-007 隐私

状态：ACCEPTED

决定：
个人敏感信息采取最小收集、最小权限、默认脱敏、操作审计；儿童相关信息更严格。

---

## D-008 UI

状态：ACCEPTED

决定：
优先普通群众与适老使用，不追求炫技。

---

## 待确认建议

Codex 若有会改变已批准架构的建议，只能写在这里，不得直接实施：

```text
[PENDING]
日期：
建议：
原因：
收益：
风险：
迁移成本：
需要用户确认：
```

<!-- FILE: 12_CODEX_MASTER_PROMPT.md -->

# 12 可直接交给 Codex 的总指令

你现在是“乐活公益·暖心服务平台”的主开发工程师、架构维护者和测试负责人。

你的目标不是一次生成大量代码，而是在整个项目周期中持续、准确、可验证地完成系统。

## 一、第一原则

在写任何代码之前，必须完整阅读 `docs/` 中的项目文档，特别是：

- 00_README_FIRST.md
- 01_PROJECT_CONSTITUTION.md
- 10_TASK_STATE.md
- 11_DECISIONS.md

项目文档是当前事实来源。聊天上下文只能补充，不能覆盖已批准规则，除非用户明确要求修改。

## 二、记忆协议

每次任务开始：

1. 读取项目开发宪法；
2. 读取当前任务状态；
3. 读取决策日志；
4. 检查 Git diff；
5. 确定任务属于哪个 Phase；
6. 输出本次实现范围，不扩大范围。

每次任务结束：

1. 运行 lint；
2. 运行 typecheck；
3. 运行 unit tests；
4. 运行 integration tests；
5. 运行 build；
6. 需要时运行 E2E；
7. 更新 `10_TASK_STATE.md`；
8. 更新 `11_DECISIONS.md`（如有）；
9. 更新 API/DB 文档；
10. 汇报“完成内容 / 未完成内容 / 测试结果 / 风险 / 下一步”。

如果上下文不足：
优先从仓库文档和代码中恢复，而不是凭空假设。

## 三、禁止行为

你绝对不能：

- 擅自改产品方向；
- 删除业务需求来降低开发难度；
- 重写整个项目只因为你更喜欢另一套技术；
- 擅自换数据库；
- 擅自改认证方案；
- 跳过权限；
- 跳过 migration；
- 跳过测试；
- 用 mock 冒充生产功能；
- 写死生产密钥；
- 把敏感信息写日志；
- 把所有业务逻辑堆在 Controller；
- 让前端权限判断代替后端鉴权；
- 使用连续 ID 作为面向用户的资源标识；
- 对服务对象数据做无授权公开；
- 开发未批准的 AI 自动决策能力。

## 四、编码优先级

顺序永远是：

1. 正确性
2. 安全
3. 数据一致性
4. 用户可理解
5. 可维护
6. 可测试
7. 性能
8. 开发速度
9. 技术“先进程度”

## 五、实现策略

不要一次开发所有功能。

严格按 `10_TASK_STATE.md` Phase 执行。

一个 Phase 的 P0 测试不通过，不进入下一个 Phase。

## 六、发生冲突时

如果新需求与项目宪法冲突：

- 不静默修改；
- 说明冲突点；
- 在 `11_DECISIONS.md` 建 PENDING 项；
- 等用户明确批准后再改变。

如果是不会改变边界的小实现细节，可自行采用最简单可靠方案，并记录重要决定。

## 七、安全要求

本项目处理弱势群体和未成年人相关信息。

任何时候都按：

- 最小收集
- 最小权限
- 默认脱敏
- 完整审计
- 私有文件
- 后端鉴权
- 不信任客户端
- 不信任用户输入
- 不信任第三方回调
- 不信任 AI 输出

执行。

## 八、完成标准

“页面能打开”不是完成。
“接口返回 200”不是完成。
“我写了代码但没运行测试”不是完成。

完成必须符合 `08_ENGINEERING_RULES.md` 的 Definition of Done 和 `09_TEST_ACCEPTANCE.md`。

## 九、第一次任务

请从 Phase 0 开始：

1. 初始化 monorepo；
2. 创建 `apps/miniprogram`；
3. 创建 `apps/admin-web`；
4. 创建 `apps/api`；
5. 创建 `packages/contracts`；
6. 建立本地 Docker Compose：MySQL、Redis、MinIO；
7. 建立统一 lint/typecheck/test/build；
8. 创建 `/health`；
9. 创建 `.env.example`；
10. 创建根目录 `AGENTS.md`；
11. 创建 CI；
12. 运行全部命令并修复问题；
13. 更新 `docs/10_TASK_STATE.md`；
14. 不开发业务功能，等待 Phase 1。

完成后只汇报：

- 新增/修改文件
- 本地启动方式
- 测试命令和结果
- 已知问题
- 下一步 Phase 1 计划

不要自行开始 Phase 1。

<!-- FILE: 13_DEPLOYMENT_CHINA.md -->

# 13 国内环境部署与运维

## 1. 目标

- 中国大陆访问稳定；
- 微信小程序合法域名可配置；
- TLS；
- 低维护成本；
- 可迁移；
- 可备份；
- 可回滚。

---

## 2. 推荐生产拓扑（初期）

```text
微信小程序
   │ HTTPS
   ▼
Nginx / API Domain
   │
   ▼
NestJS API (Docker)
   ├── MySQL
   ├── Redis
   └── Tencent COS

管理后台
   │ HTTPS
   └────────► Nginx / API
```

管理后台静态资源可由 Nginx 或对象存储/CDN 托管。

---

## 3. 云厂商

优先腾讯云并非代码强绑定要求，而是微信生态和国内运维便利性考虑。

代码必须通过 Adapter 保持：

- COS 可替换 S3 兼容存储；
- Redis 可替换其他标准 Redis；
- MySQL 可迁移标准 MySQL；
- Nginx/Docker 不绑定专有 PaaS。

---

## 4. 国内依赖获取

开发机可根据实际环境配置：

- npm 国内镜像；
- Docker 镜像加速；
- 操作系统软件源镜像。

但：

- lockfile 必须提交；
- CI 至少验证标准 registry 可构建；
- 不依赖个人私服；
- 不在代码写死镜像地址。

---

## 5. 环境

### dev

开发者本机 Docker Compose。

### test

CI 自动化测试。

### staging

与生产拓扑尽量一致，使用测试小程序/测试账号。

### prod

真实用户。

严禁 dev 直连 prod 数据库。

---

## 6. 发布

建议：

1. CI build；
2. 生成 immutable image tag；
3. staging deploy；
4. migration precheck；
5. smoke test；
6. production backup；
7. production deploy；
8. health check；
9. E2E smoke；
10. 观察；
11. 出现严重问题回滚应用版本。

数据库 migration 必须设计可前后兼容，避免应用回滚后数据库不兼容。

---

## 7. 监控

至少：

- API availability
- 5xx rate
- P95 latency
- CPU/memory
- disk
- MySQL connection
- Redis connectivity
- job failures
- backup failures

告警进入实际有人查看的渠道。

---

## 8. 容灾

初期无需昂贵双活，但必须：

- 自动数据库备份；
- 异地/云端备份；
- IaC/部署脚本；
- Docker 镜像可重建；
- 文档化恢复；
- 定期演练。

---

## 9. 微信小程序上线准备

实际申请和上线阶段需要根据微信公众平台最新规则核对：

- 小程序主体
- 服务类目
- 隐私保护指引
- 用户信息/手机号等接口使用说明
- request/download/upload 合法域名
- HTTPS 证书
- 备案/域名要求
- 订阅消息模板
- 审核材料

微信平台规则可能变化，因此上线前必须重新查官方文档，不得只依赖本文件。

<!-- FILE: 14_RELEASE_CHECKLIST.md -->

# 14 发布检查清单

## 代码

- [ ] main branch clean
- [ ] lockfile committed
- [ ] lint pass
- [ ] typecheck pass
- [ ] unit pass
- [ ] integration pass
- [ ] E2E P0 pass
- [ ] build pass

## 数据库

- [ ] migration reviewed
- [ ] backup done
- [ ] rollback compatibility checked
- [ ] indexes reviewed

## 安全

- [ ] secrets scan
- [ ] dependency scan
- [ ] auth test
- [ ] IDOR test
- [ ] export permission test
- [ ] file upload test
- [ ] logs checked for PII

## 隐私

- [ ] privacy policy version correct
- [ ] consent flow correct
- [ ] children/guardian flow checked
- [ ] sensitive list fields masked
- [ ] retention configuration checked

## 微信

- [ ] legal domains
- [ ] HTTPS
- [ ] privacy declarations
- [ ] API permissions
- [ ] subscribe message handling
- [ ] real device test

## 运维

- [ ] health
- [ ] monitor
- [ ] alert
- [ ] backup
- [ ] restore procedure
- [ ] rollback image available

## UAT

- [ ] 本人申请
- [ ] 代申请
- [ ] 受理
- [ ] 建档
- [ ] 派单
- [ ] 服务
- [ ] 回访
- [ ] 继续帮扶
- [ ] 志愿者
- [ ] 活动报名

<!-- FILE: AGENTS_TEMPLATE.md -->

# AGENTS.md

Before coding, read:

1. docs/00_README_FIRST.md
2. docs/01_PROJECT_CONSTITUTION.md
3. docs/10_TASK_STATE.md
4. docs/11_DECISIONS.md
5. task-related docs

Rules:

- Do not change approved product scope or architecture without explicit approval.
- Do not bypass authorization, migrations, tests, or audit requirements.
- Do not log sensitive beneficiary data.
- Do not expose sequential internal IDs.
- Update docs/10_TASK_STATE.md after every task.
- Update docs/11_DECISIONS.md for architecture/product decisions.
- Run lint, typecheck, tests and build before marking work complete.