Files
袁永志 aa12b9f910 初始化政体志子站
收录 zhengquan-site 前后端完整代码:24 朝数据、24 幅权力结构图、
5 条沿革(67 节点 / 269 条细释)、44 个词条,以及部署配置与接口测试。
2026-11-19 11:59:51 +08:00

282 lines
12 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 舆纪历史 · 政体志
`incarnation.cn` 的第四个子站,主题是中国历代**国体、政体、政权组织架构与官制沿革**。从夏商到当代,按朝展示中央与地方的权力结构、各机构的职掌,并用五条专线串起制度在四千年间的因革。
- 站点建议域名:`zhengquan.incarnation.cn`
- 目录:`zhengquan-site/`(前后端同仓,后端直接托管前端)
- 内容:24 个朝代或时期(春秋/战国、三国/两晋/南北朝、五代/十国、北宋/南宋等分卷)、24 幅中央权力结构图(2–4 层、5–9 个分支)、239 处机构、5 条沿革(67 个节点、269 条细释)、44 个词条
## 功能
| 页面 | 说明 |
| --- | --- |
| 总目 `#/` | 竖排书名、朝代尺、八段二十四朝总目(按常规断代分卷:战国、新莽、三国、西晋、东晋、南北朝、十国、南宋等单列),五条沿革入口、凡例(编例说明并入首页第 04 节,不单设页签) |
| 朝代页 `#/dynasty/:slug` | 国体与政体、中央权力结构图(桌面 SVG / 窄屏纵向树)、机构职掌表、地方层级、选官/监察/军事、沿革要点、史料引文 |
| 沿革 `#/threads`、`#/thread/:slug` | 宰相、监察、地方行政、选官、军事五条时间轴,按朝代分节;每节点附分条细释与史料依据 |
| 词典 `#/glossary` | 按类筛选、检索职官与制度术语 |
| 检索 `#/search` | 跨朝代、沿革、词条全文检索,命中高亮 |
设计沿用主站的宣纸、朱印、宋体与细线体系:纸色 `#fdf9f3`、朱红 `#b8261f`、赭金 `#7c5a1f`。字体不加载中文 Web Font:正文走系统无衬线栈(macOS PingFang SC、Windows Microsoft YaHei),标题与机构名走宋体栈(Songti SC / SimSun)。全站响应式,移动端表格自动转为卡片,时间轴与朝代尺可横向滑动。
## 技术栈
- **前端**:原生 ES Modules + 手写 CSS,无构建步骤、无前端框架依赖。哈希路由,直接由后端托管。
- **后端**:Node.js 18+ / Express 4,启动时加载 JSON 数据并做引用校验;提供 REST API、全文检索、静态托管与 SPA 回退。
- **数据**:`backend/src/data/` 下的 JSON 文件,改完重启即可生效;不需要数据库。
## 目录
```
zhengquan-site/
├── package.json # 根级便捷脚本
├── backend/
│ ├── package.json
│ ├── src/
│ │ ├── index.js # 启动入口(PORT 默认 5180)
│ │ ├── app.js # 路由、静态托管、错误处理
│ │ ├── data.js # 数据加载、校验、摘要与统计
│ │ ├── search.js # 轻量全文检索
│ │ └── data/
│ │ ├── meta.json # 站点信息、八个时代
│ │ ├── charts.json # 24 朝组织架构图数据
│ │ ├── threads.json # 五条沿革(含战国、西晋、南北朝、十国、南宋等细化节点)
│ │ ├── glossary.json # 44 个词条
│ │ └── dynasties/*.json # 24 个朝代或时期
│ └── test/smoke.mjs # 接口冒烟测试
├── frontend/
│ ├── index.html
│ ├── favicon.svg
│ ├── og.png
│ └── assets/
│ ├── css/style.css
│ └── js/
│ ├── app.js # 路由与全局事件
│ ├── api.js # API 封装与缓存
│ ├── store.js # 启动数据
│ ├── layout.js # 书眉与页脚
│ ├── orgchart.js # 结构图布局与渲染,窄屏转纵向树
│ ├── util.js
│ └── views/ # 各页面视图
└── deploy/
├── nginx.conf.example
└── zhengquan-site.service
```
## 本地运行
```bash
cd zhengquan-site
npm run install:all # 安装后端依赖
npm start # 启动,默认 http://localhost:5180
```
开发时可用 `npm run dev`(`node --watch`,改后端代码自动重启;前端是静态文件,刷新即可)。
```bash
npm test # 8 项接口冒烟测试
```
环境变量:
| 变量 | 默认 | 说明 |
| --- | --- | --- |
| `PORT` | `5180` | 监听端口 |
| `HOST` | `0.0.0.0` | 监听地址,置于 Nginx 后可改为 `127.0.0.1` |
| `NODE_ENV` | — | 设为 `production` 可关闭请求日志 |
## 数据格式
每个朝代一个文件:`backend/src/data/dynasties/<slug>.json`。
```jsonc
{
"slug": "qin",
"name": "秦",
"fullName": "秦朝",
"subtitle": "皇帝制度、三公九卿与郡县制",
"period": "前221—前207",
"startYear": -221, // 用于排序与朝代尺,公元前为负
"endYear": -207,
"era": "qinhan", // 对应 meta.json 的 eras[].id
"capital": "咸阳",
"founder": "秦始皇嬴政",
"summary": "……",
"tags": ["皇帝制度", "三公九卿", "郡县制"],
"stateForm": { "label": "国体", "value": "……", "note": "……" },
"govForm": { "label": "政体", "value": "……", "note": "……" },
"org": {
"note": "架构说明",
"flow": ["皇帝", "丞相 · 太尉 · 御史大夫", "九卿", "郡", "县"],
"tiers": [
{
"label": "皇帝", "caption": "……",
"nodes": [
{ "name": "皇帝", "duty": "……", "note": "皇权世袭",
"children": [{ "name": "……", "duty": "……" }] }
]
}
]
},
"institutions": [
{ "name": "丞相", "chief": "丞相", "duty": "……", "note": "金印紫绶" }
],
"local": {
"system": "郡县制(郡—县—乡—亭—里)",
"summary": "……",
"levels": [{ "name": "郡", "chief": "郡守", "duty": "……" }],
"note": "……"
},
"selection": { "system": "……", "text": "……" },
"supervision": { "system": "……", "text": "……" },
"military": { "system": "……", "text": "……" },
"changes": [{ "title": "……", "text": "……" }],
"quotes": [{ "text": "……", "source": "《史记·秦始皇本纪》", "paraphrase": false }],
"sources": ["《史记》"],
"prev": "chunqiu", "next": "han-west"
}
```
新增一朝:
1. 复制一个结构相同的 JSON,改 `slug`、`startYear`、`endYear`、`era`。
2. 把相邻朝代的 `next` / `prev` 接上。
3. 若开启新时段,在 `meta.json` 的 `eras` 里加一项;数据按 `era` 字段自动归组。
4. 重启服务。`data.js` 会校验 slug 唯一性与前后引用,坏数据会在启动时报错。
### 组织架构图
`backend/src/data/charts.json` 按 slug 收录各朝架构图,与朝代正文分开维护,便于单独调整图形:
```json
"qin": {
"caption": "皇帝之下三公分权,九卿分理庶务……",
"root": {
"name": "皇帝",
"note": "总揽军政",
"tone": "root",
"children": [
{
"name": "丞相",
"note": "百官之长 · 领九卿",
"tone": "core",
"items": ["奉常", "郎中令", "卫尉", "太仆", "廷尉"]
}
]
}
}
```
- `tone`:`root` 朱红、`core` 金底、`watch` 绿底(监察)、`local` 虚线框(地方)。
- `items`:机构内部的下属职官或部门,渲染为节点内的小标签。
- `children`:下级机构。桌面端生成横向树状图,860px 以下自动切换为纵向缩进树。
- `dashed`:为 true 时连线用虚线,表示监察、派出或地方直隶。
- 每个朝代都必须在 `charts.json` 中有图;缺失会在服务启动时报错。
### 沿革与词条
`threads.json` 的节点结构按朝代分节:`year` 为朝代名(页面主标签),`era` 为大时段(夏商周、秦汉、魏晋南北朝、隋唐、宋元、明清、近现代),`when` 为具体年份或时期,显示在节点头部右侧。`details` 为分条细释,`source` 为主要史料;二者在服务启动时校验,每节点至少 2 条细释:
```json
{
"year": "明", "era": "明清", "when": "1380", "dynasty": "ming",
"title": "废除丞相", "text": "……",
"details": [
{ "label": "胡惟庸案", "text": "……" },
{ "label": "制度代价", "text": "……" }
],
"source": "《明太祖实录》《明史·职官志》"
}
```
`glossary.json` 的词条结构:
```json
{ "term": "军机处", "category": "中央", "definition": "……", "related": ["qing"] }
```
## API
| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/api/bootstrap` | 站点信息、时代、统计、朝代摘要、沿革摘要、随机史料 |
| GET | `/api/dynasties` | 朝代摘要列表 |
| GET | `/api/dynasties/:slug` | 朝代详情(含前后朝与相关词条) |
| GET | `/api/threads` | 五条沿革全文 |
| GET | `/api/threads/:slug` | 单条沿革(节点补朝代名与年代) |
| GET | `/api/glossary?q=&category=` | 词条筛选 |
| GET | `/api/search?q=&limit=` | 跨三类内容检索 |
| GET | `/api/quote` | 随机一条史料 |
| GET | `/api/health` | 健康检查 |
除 `/api/*` 外的路径都会回退到 `frontend/index.html`,可直接支持哈希路由。
## 部署
后端同时托管前端,因此只需要一个 Node 进程,不需要额外的前端服务器。
```bash
# 服务器上
git clone <repo> /opt/zhengquan-site
cd /opt/zhengquan-site
npm --prefix backend ci --omit=dev
PORT=5180 NODE_ENV=production node backend/src/index.js
```
用 systemd 常驻:
```bash
sudo cp deploy/zhengquan-site.service /etc/systemd/system/
sudo chown -R www-data:www-data /opt/zhengquan-site
sudo systemctl daemon-reload
sudo systemctl enable --now zhengquan-site
```
Nginx 反向代理与 HTTPS 见 `deploy/nginx.conf.example`。要点:
- `proxy_pass http://127.0.0.1:5180;`
- `/assets/` 可加长缓存(后端已设 `Cache-Control: max-age=604800`)
- `index.html` 不缓存(后端已设 `no-cache`),保证发版后立即生效
- 证书可用 certbot 申请,把示例中的路径替换为实际证书路径
## 挂到主站
主站首页目前写着「凡三处」,需要改为「凡四处」,并在 `toc-list` 里追加一行。可直接使用主站现有的样式类:
```html
<li class="row">
<a class="row-link" href="https://zhengquan.incarnation.cn" target="_blank" rel="noopener">
<span class="row-no">04</span>
<span class="row-name">
政体志
<span class="row-desc">夏商至当代 · 国体政体 · 官制沿革</span>
<span class="row-detail"><b>16</b> 朝 · <b>162</b> 处机构 · <b>5</b> 条沿革</span>
</span>
<span class="row-lead" aria-hidden="true"></span>
<span class="row-num"><b>40</b> 词条</span>
<span class="row-go">
在线
<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
<path d="M7 17 17 7M8 7h9v9" />
</svg>
</span>
</a>
</li>
```
同时建议更新:
- 主站 `<title>` / `description` / `og:description` 中的「三处」「三处刊行」为「四处」;
- 首屏题记补一句制度卷的读法;
- 「摘录」区可加三条政体志的条目,链到 `#/dynasty/qin`、`#/thread/xiangquan`、`#/glossary?q=三省六部`。
## 口径与资料来源
- **国体**指国家的阶级性质,**政体**指政权的组织形式。古代部分采用中国史学界通行表述(夏商周为奴隶主阶级专政、秦汉至清为地主阶级专政),并对史料局限与学界讨论随文注明。
- 年代取通行说法;先秦年代多依夏商周断代工程。制度名称、官称从正史与政书,异说另注。
- 引文标出处;属于今人概括而非原文的,标「大意」。
- 主要依据:历代正史职官志/百官志、《周礼》《唐六典》《通典》《文献通考》《明会典》《清会典》、《中华民国临时约法》《中华人民共和国宪法》,以及钱穆《中国历代政治得失》、严耕望《中国地方行政制度史》等近人研究。
## 许可
内容与代码用于 `incarnation.cn` 及其子站。转载、引用请注明出处;史料引文请复核原书。