init

docs/API_REFERENCE.md

@@ -0,0 +1,231 @@
+# 后端 API 文档（当前实现）
+
+## 基础信息
+- Base URL：`http://localhost:5010/api`
+- 认证方式：JWT Bearer Token
+- Header 示例：
+```
+Authorization: Bearer <token>
+Content-Type: application/json
+```
+
+## 通用响应结构
+- 成功：
+```
+{"status":"success","message":"...","data":{...}}
+```
+- 错误：
+```
+{"status":"error","message":"..."}
+```
+
+## 时间与日期格式
+- 日期：`YYYY-MM-DD`
+- 时间：ISO8601（如 `2025-12-20T08:30:00`）
+
+## 认证与用户
+### 发送手机号验证码
+- POST `/auth/phone/code`
+- 请求字段：
+- `phone` string 手机号
+- 成功返回：`data.code`（仅开发模式下返回）
+
+### 手机号验证码登录
+- POST `/auth/phone/login`
+- 请求字段：
+- `phone` string
+- `code` string
+- 成功返回：
+- `data.token` string
+- `data.user` object
+- `data.need_set_password` boolean
+
+### 手机号密码登录
+- POST `/auth/password/login`
+- 请求字段：
+- `phone` string
+- `password` string（8-16 位，需包含字母与数字）
+- 成功返回：
+- `data.token` string
+- `data.user` object
+- `data.need_set_password` boolean
+
+### 设置密码
+- POST `/auth/password/setup`
+- 需要登录
+- 请求字段：
+- `password` string
+- 成功返回：`data.user`
+
+### 更新昵称
+- PUT `/auth/profile`
+- 需要登录
+- 请求字段：
+- `name` string
+- 成功返回：`data.user`
+
+### 微信登录（可选）
+- POST `/auth/wechat`
+- 请求字段：
+- `code` string
+
+## 宝宝管理
+### 列表
+- GET `/babies`
+- 需要登录
+
+### 创建
+- POST `/babies`
+- 需要登录
+- 请求字段：
+- `name` string
+- `gender` string（仅支持“男”“女”）
+- `birthday` string（YYYY-MM-DD）
+- `dueDate` string（可选）
+- `gestationalWeeks` number（可选）
+- `note` string（可选）
+
+### 详情
+- GET `/babies/{id}`
+- 需要登录
+
+### 更新
+- PUT `/babies/{id}`
+- 需要登录
+- 字段与创建一致，均为可选更新
+
+### 删除
+- DELETE `/babies/{id}`
+- 需要登录
+
+## 成长记录
+### 列表
+- GET `/babies/{babyId}/growth`
+- 需要登录
+- Query：
+- `metric` string（可选）
+- `start` string ISO8601（可选）
+- `end` string ISO8601（可选）
+
+### 创建
+- POST `/babies/{babyId}/growth`
+- 需要登录
+- 请求字段：
+- `metric` string
+- `value` number
+- `unit` string
+- `recordedAt` string ISO8601（可选）
+- `note` string（可选）
+
+### 更新
+- PUT `/growth/{id}`
+- 需要登录
+- 字段与创建一致，均为可选更新
+
+### 删除
+- DELETE `/growth/{id}`
+- 需要登录
+
+## 预约管理
+### 列表
+- GET `/appointments`
+- 需要登录
+- Query：
+- `status` string（可选）
+
+### 创建
+- POST `/appointments`
+- 需要登录
+- 请求字段：
+- `clinic` string
+- `department` string
+- `scheduledAt` string ISO8601
+- `remindAt` string ISO8601（可选）
+- `status` string（可选，默认 pending）
+- `note` string（可选）
+- `babyId` number（可选）
+
+### 更新
+- PUT `/appointments/{id}`
+- 需要登录
+- 字段与创建一致，均为可选更新
+
+### 删除
+- DELETE `/appointments/{id}`
+- 需要登录
+
+### 更新状态
+- PATCH `/appointments/{id}/status`
+- 需要登录
+- 请求字段：
+- `status` string
+
+## 内容管理（只读）
+### 视频列表
+- GET `/content/videos`
+- 需要登录
+- Query：
+- `page` number
+- `per_page` number
+- `search` string（标题/简介）
+- `category` string
+
+### 视频详情
+- GET `/content/videos/{id}`
+- 需要登录
+- 说明：会增加 `views` 计数
+
+### 文章列表
+- GET `/content/articles`
+- 需要登录
+- Query：
+- `page` number
+- `per_page` number
+- `search` string（标题/正文）
+- `category` string
+
+### 文章详情
+- GET `/content/articles/{id}`
+- 需要登录
+
+## 聊天与 AI
+### 发送消息
+- POST `/chat/send`
+- 需要登录
+- 请求字段：
+- `content` string
+- `babyId` number（可选）
+- `messageId` string（可选）
+- `history` array（可选）
+- `metadata` object（可选）
+- `params` object（可选）
+
+### 历史记录
+- GET `/chat/history`
+- 需要登录
+- Query：
+- `page` number
+- `per_page` number
+- `babyId` number（可选）
+
+### 清空历史
+- DELETE `/chat/history`
+- 需要登录
+- Query：
+- `babyId` number（可选）
+
+## 健康检查
+- GET `/health`
+- GET `/`
+
+## 常见错误码
+- 400 参数错误
+- 401 认证失败或 token 失效
+- 404 资源不存在
+- 500 服务端异常
+- 502 AI 服务异常（`/chat/send`）
+
+## 管理端缺口说明
+- 当前所有业务接口均以“用户本人”为作用域。
+- 需要管理端能力时，建议新增 `/api/admin/*` 路由与管理员鉴权。
+- 内容模块目前无写接口，后台管理若需编辑视频/文章需补齐写接口。

docs/EXECUTION_PLAN_ADMIN.md

@@ -0,0 +1,50 @@
+# 后台管理系统执行计划（独立项目）
+
+## 目标
+- 建立独立的后台管理系统，用于对现有 App 数据进行 CRUD 管理。
+- 仅使用管理员角色，不做多角色权限体系。
+- 当前阶段不考虑软删除与审计日志。
+
+## 范围与边界
+- 后台管理系统前端单独开发，不在本仓库落地。
+- 本仓库后端若需补齐管理能力，只新增接口，不影响现有 App 侧接口。
+- 以“可用、稳定、可维护”为交付标准，优先覆盖核心数据。
+
+## 里程碑与阶段
+### 阶段 0：需求与字段确认
+- 交付物：管理端功能清单、字段字典、角色定义（仅管理员）。
+- 重点确认：哪些数据允许删除、哪些字段允许编辑、是否需要导出。
+
+### 阶段 1：接口盘点与差距分析
+- 交付物：现有 API 清单与管理端需求映射表。
+- 结论预期：当前接口以“用户本人”为作用域，管理端需要跨用户访问能力。
+
+### 阶段 2：管理端 API 设计
+- 交付物：管理端 API 规范。
+- 约定：统一路径前缀建议为 `/api/admin/*`。
+- 约定：统一分页字段 `page`、`per_page`，统一筛选方式（query）。
+
+### 阶段 3：后端能力补齐（如需）
+- 交付物：管理员鉴权、跨用户 CRUD、内容管理写接口、缓存失效策略。
+- 风险控制：只新增接口，不改动现有用户侧行为。
+
+### 阶段 4：管理端前端工程建设（独立仓库）
+- 交付物：登录、用户、宝宝、成长、预约、内容、聊天管理页面。
+- 规范：统一分页、筛选、详情展示、表单校验。
+
+### 阶段 5：联调与验收
+- 交付物：联调清单、验收记录、问题关闭清单。
+- 重点：权限隔离、分页与筛选稳定性、关键字段一致性。
+
+## 风险与对策
+- 风险：管理端操作可能影响 App 侧数据一致性。
+- 对策：操作前确认字段范围，新增接口遵循现有模型与数据约束。
+
+## 回滚方式
+- 仅为文档规划与外部系统开发，不影响现有运行。
+- 若后端新增管理端 API，可通过禁用蓝图注册或环境开关关闭。
+
+## 交付物清单
+- 管理端执行计划文档（本文件）。
+- 管理端 API 文档（见 `docx/API_REFERENCE.md`）。
+- 项目说明（见 `docx/PROJECT_OVERVIEW.md`）。

docs/PROJECT_OVERVIEW.md

@@ -0,0 +1,70 @@
+# 项目说明（当前仓库）
+
+## 项目定位
+- 本仓库提供 App 端后端 API 与 RN 客户端基础工程。
+- 后台管理系统将单独开发，不在本仓库实现前端。
+
+## 仓库结构
+- `backend/`：Flask API 服务
+- `WA/`：React Native Expo 客户端工程
+- `wechat_end/`：已弃用小程序代码，仅存档
+- `app_end/`、`web_end/`：当前为空壳或未启用
+- `docx/`：产品与开发文档
+
+## 后端概览
+### 技术栈
+- Flask 2.3.x
+- Flask-JWT-Extended
+- Flask-SQLAlchemy
+- Flask-CORS
+
+### 入口与路由
+- 入口：`backend/app.py`
+- 路由：`backend/routes/*`
+- 模型：`backend/models/*`
+- 工具：`backend/utils/*`
+
+### 主要模块
+- 认证：手机验证码登录、密码登录、设置密码、更新昵称
+- 宝宝：CRUD
+- 成长记录：CRUD
+- 预约：CRUD
+- 内容：视频/文章列表与详情（只读）
+- 聊天：转发 n8n，历史记录管理
+
+## 前端概览（WA）
+- React Native Expo + TypeScript
+- 已落地通用 UI 组件、主题体系、Axios 封装、导航与状态管理
+- 详细进度参见 `docx/REFACTOR_PLAN.md` 与 `docx/FRAMEWORK_SETUP.md`
+
+## 环境变量
+后端必要配置：
+- `DATABASE_URL`
+- `SECRET_KEY`
+- `JWT_SECRET_KEY`
+可选配置：
+- `N8N_WEBHOOK_URL`
+- `WECHAT_APP_ID`
+- `WECHAT_APP_SECRET`
+- `CONTENT_SEED`（设置为 1 时注入本地示例内容）
+
+## 本地运行
+### 后端
+```
+cd backend
+python app.py
+```
+默认端口：`http://localhost:5010`
+
+### 客户端（WA）
+```
+cd WA
+npm install
+npm start
+```
+
+## 约束与限制
+- 当前无管理员权限与跨用户管理接口。
+- 内容模块仅支持读取，不支持新增/编辑/删除。
+- 未配置软删除与审计日志。
+- 聊天模块依赖 n8n webhook，未配置时会返回错误。